feat: add agent-device acp, a deterministic stdio ACP agent

[XeonBloomfield]

Summary

Adds agent-device acp: an Agent Client Protocol v1 agent over stdio, so ACP clients such as Zed can drive devices from their agent panel. Before: ACP editors could only reach agent-device indirectly, through whatever LLM agent they run and its MCP config. After: agent-device acp is a first-class agent surface — each prompt line is one agent-device command in CLI syntax, executed through the same AgentDeviceClient path as MCP tools, streamed back as ACP tool calls with daemon progress updates and inline screenshot images.

Design choices:

• Deterministic agent, no LLM: natural-language prompts are refused with guidance; the reasoning stays in the ACP client's own model. Keeps the zero-runtime-dependency policy — the protocol layer is hand-rolled in src/acp/, reusing the MCP server's newline-delimited JSON-RPC transport, payload queue, and error formatting (the shared pieces are now exported from src/mcp/ instead of duplicated).
• Prompt lines are tokenized with the replay-script tokenizer and parsed by the real CLI parser, so ACP prompts, replay scripts, and the CLI share one dialect. Target flags (--platform, --device, --udid, --session, --state-dir) are sticky within an ACP session.
• session/cancel is intercepted ahead of the serialized inbound queue so it takes effect between command lines of a running prompt. The command already in flight runs to completion — there is no abort seam in the daemon client; documented as a v1 limitation.
• session/new advertises all MCP-exposed commands via available_commands_update (response-before-notification ordering is pinned by test).

Docs: new ACP section in agent-setup.md with the Zed agent_servers config, README pointer, CHANGELOG entry, CONTEXT.md command-surface vocabulary update.

23 files touched (13 new: src/acp/ + tests). Scope stayed within the planned command-surface addition; the only changes outside it are exports of previously-private MCP transport/formatting helpers and the replay tokenizer.

Validation

Full unit bundle green (3296 tests / 366 files, including 27 new ACP tests covering the router contract, prompt parsing, sticky flags, cancellation, refusal, screenshot image attachment, and out-of-band cancel interception). check:quick, check:layering, fallow audit (0 dead code / 0 duplication after deduplicating against src/mcp/), and test:smoke all pass — including a new smoke-acp.test.ts that spawns the real stdio process and drives initialize → session/new → prompt refusal → clean shutdown. Live device evidence: through the packaged build (dist/src/internal/bin.js acp), an ACP session ran devices against a real daemon with an isolated state dir and streamed back actual inventory (iPhone 17 Pro simulator + host macOS target) as a completed tool_call_update; the daemon and state dir were cleaned up afterwards. Zed itself was not exercised — the wire contract was verified against the official ACP v1 JSON schema; a follow-up interactive Zed session is the remaining real-client check.

🤖 Generated with Claude Code

[thymikee]

Review finding: available_commands_update advertises agent-device commands as ACP available commands, but the prompt parser only accepts bare CLI lines. ACP slash-command usage sends the command as prompt text with a leading slash (for example /devices or /snapshot -i); on this branch those resolve as unknown commands because parsePromptCommandLine only strips optional agent-device before calling the CLI parser. Please either accept a leading / command prefix and add tests for /devices / /snapshot -i, or stop advertising available_commands_update until slash-form invocation is supported.

[XeonBloomfield]

I think this line within the guide can be reverted as the previous behavior still works!

[thymikee]

Ready for human review.

I rechecked #1132 at head 5b802f60 after the ACP follow-up commits. The prior blocker is addressed: advertised ACP commands now accept slash-form prompt lines (/devices, /snapshot -i) and tests cover that path in src/acp/__tests__/prompt-lines.test.ts. session/new now rejects relative cwd and malformed/missing mcpServers, with router coverage for invalid params. The docs were updated to explain ACP as a first-class deterministic interface while keeping examples CLI-shaped.

Checks: 15 successful; only expected skipped Bundle Size and deploy-preview jobs. Remaining residual risk is real-client Zed validation, but the stdio/protocol behavior now matches the ACP usage shape reviewed earlier.

[thymikee]

Rechecked the later fix: tighten acp tool updates delta after the prior ready-for-human review. The parse-error tool-call shape now follows the normal in-progress -> failed update flow, snapshot/find avoid duplicating bulky structured raw output while keeping CLI text content, and the docs clarify the CLI-reader/command-contract path plus ACP ref semantics. Checks are green for the code gates; deploy-preview and Bundle Size remain skipped/non-code. No new actionable blockers found; the existing ready-for-human label still looks valid.

[thymikee]

Branch blocker at head 6dbd05e82494ae124cf5eb0a296046f0b00e5cd8: this PR is now CONFLICTING / DIRTY against current main. Main is 245 commits beyond merge base 0dcc1aa55357dcdf4b1449acaeb1816aba7b638a, while the PR carries five commits; every reported green check is from July 7 and is not evidence for the eventual resolved tree.

Please rebase or merge current main, resolve the conflicts, push a new head, then rerun current CI and revalidate the ACP stdio/device flow on that exact head. Substantive re-review should wait for that change.

Residual risk: no separately authorized cross-vendor review was performed.

[thymikee]

Sentinel review of exact head 6dbd05e82494ae124cf5eb0a296046f0b00e5cd8: recommend closing this PR rather than attempting a rebase. It is 588 commits behind current main, conflicts across the CLI/MCP/catalog/docs surfaces, imports paths that no longer exist, and its July CI plus one devices inventory run do not validate the current product; Zed itself was never tested.

The architecture is also obsolete: current ADR 0008 derives command surfaces from the descriptor registry, while this branch adds a second parser/executor/client-progress/error/output stack around old CLI and MCP seams. That duplicates the current supported CLI, MCP, Node, and AI SDK surfaces. The 1,841-line addition is not justified without a confirmed ACP client need.

If real client demand appears, start a fresh discovery issue and rebuild against current descriptor-backed metadata/client seams with a typed ACP protocol boundary and real Zed plus mutated-device validation.

[thymikee]

Not ready; this needs a fresh architecture pass rather than conflict resolution. The branch is 624 current-main commits stale and DIRTY, with only July 7 CI. ACP files import interfaces removed from main (cli/parser/cli-flags.ts, daemon/request-progress.ts, replay/script.ts, utils/cli-options.ts), so a naive rebase cannot typecheck. More importantly, prompt-runner.ts hand-builds a daemon client from a small flags subset and explicitly omits remote materialization/lock binding, while the current CLI resolves binding/defaults/active connection/auth/materialization through resolveRemoteContext. A surface advertised as CLI syntax therefore silently diverges for remote, lease, and runtime connection paths.

At +1,841/-52 across 30 files with no current size evidence, the materially smaller/deeper direction is a fresh implementation: derive exposure from current command descriptors/CLI grammar and reuse one structured client-context/command-dispatch seam. The ACP adapter should own only ACP wire/session semantics, not a parallel flags/client/progress/error stack. Old inventory evidence did not exercise Zed and is not current evidence for a resolved tree. Do not modify the branch.

[thymikee]

This branch is no longer reviewable against current main. Exact head 6dbd05e is conflicting and roughly 646 commits stale, and it depends on CLI, daemon progress, replay, and option seams that have since been removed. Resolving Git conflicts would not restore the current descriptor-derived CLI/MCP ownership or client-context/remote-lock behavior required by ADR-0003/0008; the July checks and device evidence cannot validate the resulting tree. Given the parallel ~1.8k-line flags/client/progress stack, I recommend closing this PR rather than rebasing it. If ACP demand remains, start a fresh, smaller adapter on the current command descriptors and client-context seams.

[thymikee]

This head is no longer reviewable against current main and should be closed rather than routinely rebased. It is CONFLICTING/DIRTY and 653 commits behind, depends on removed CLI/progress/client/replay ownership seams, and adds a parallel ~1.8k-line flags/protocol/client stack with only stale July CI and narrow inventory evidence. If ACP demand remains, start a fresh smaller adapter over current command descriptors and client-context/structured-dispatch seams, with current checks and practical ACP-client/device evidence.

[thymikee]

This exact head is closable rather than rebaseable. It is 668 main commits behind its merge base, CONFLICTING, and imports removed CLI/replay/request-progress seams; July 7 checks validate the obsolete tree and Zed was never exercised. There is no linked issue, replacement PR, or current ACP demand signal, and repeated prior closure reviews produced no new author head. A rebase would be a rewrite across current descriptor/client-context/remote ownership. Close this PR; if concrete ACP-client demand returns, start fresh as a small adapter over current command descriptors/structured dispatch with real ACP-client plus device evidence.