Add warpctrl product and tech specs

[zachlloyd]

Description

Product and tech specs for warpctrl, a standalone local-control CLI for scripting Warp UI actions against running app instances.

PRODUCT.md defines:

• Allowlisted action catalog organized by namespace (discovery, window, tab, pane, session, input, appearance, settings, panels)
• Hierarchical target selector model (instance → window → tab → pane → session)
• 4-tier action classification: read-only/metadata, read-only/terminal data, mutating/non-destructive, mutating/destructive
• Differentiated permission policies for human vs agent callers (agents are expected to be major consumers)
• Protocol-first settings (reads/writes go through the authenticated control endpoint, not direct file manipulation)
• Future entity extensibility for files and Warp Drive objects
• Future remote URL transport extensibility (out of scope for first slice)

TECH.md covers:

• Protocol crate design with stable envelopes, opaque IDs, and versioning
• Per-process discovery via ephemeral-port loopback listeners and filesystem discovery records
• Local authentication boundary (bearer token, file permissions, no CORS)
• App-side request bridge using ModelSpawner to safely dispatch from Tokio HTTP threads to the main UI thread
• Target resolution model
• CLI library constraints (clap/serde/clap_complete matching the Oz CLI)
• Packaging and release shape following the Oz CLI artifact model

README.md documents:

• Build/install/invocation for macOS, Linux, Windows
• End-to-end test flow
• Security model with authenticated request flow diagram

This is a specs-only PR for review. Implementation is on zach/warp-cli stacked on top of this branch.

Warp conversation

Linked Issue

• Related: Add a warpctrl local-control CLI for scripting Warp #11545

Testing

• Specs only, no code changes to test.

Agent Mode

• Warp Agent Mode - This PR was created via Warp's AI Agent Mode

CHANGELOG-NONE

Co-Authored-By: Oz oz-agent@warp.dev

[oz-for-oss]

@zachlloyd

I'm starting a first review of this spec-only pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds product, technical, and operator specs for warpctrl, a standalone local-control CLI for addressing running Warp instances through an allowlisted protocol. The specs cover the catalog shape, target hierarchy, first-slice implementation, packaging direction, and local authentication model.

Concerns

• The operator test flow documents warpctrl tab list even though the first slice only commits to discovery and tab create, which makes the implementation target ambiguous.
• The per-caller permission model does not define how the server distinguishes human CLI use from agent use when both can read the same local discovery credential.
• The discovery-token storage model uses POSIX-style 0600 permissions but the spec also claims Windows support without equivalent ACL requirements.
• The tab.create bridge flow falls back from active window to the first ordered window, contradicting the deterministic targeting/error semantics in the product spec.

Security

• Define separate scoped credentials or capability issuance for agent callers before destructive/input actions are implemented; otherwise an agent that can read the discovery record can present the same full-access token as a human CLI.
• Specify Windows discovery-record ACL/storage requirements, or explicitly mark Windows local-control auth as follow-up, so bearer tokens are not protected only on POSIX platforms.

Verdict

Found: 0 critical, 4 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz