Skip to content

feat(acp): add acq acp subcommand for Agent Client Protocol - #696

Closed
JJediny wants to merge 1 commit into
mainfrom
feat/acp-standard-agent-interface
Closed

JJediny wants to merge 1 commit into
mainfrom
feat/acp-standard-agent-interface

Conversation

@JJediny

@JJediny JJediny commented Nov 13, 2026

Copy link
Copy Markdown
Member

Context

Desktop IDEs and multi-agent orchestrators (such as Zed via agent_servers) communicate with coding agents over the Agent Client Protocol (ACP) (https://agentclientprotocol.com/): newline-delimited JSON-RPC 2.0 over stdio. While opencode (opencode acp) and goose (goose acp) implement ACP natively, connecting a host IDE directly to a sandboxed agent previously had three obstacles:

  1. acq run allocates a PTY (msb exec -t / sbx run), which translates \n to \r\n and emits terminal control sequences that corrupt JSON-RPC framing.
  2. Provisioning, kit-healing, and backend-resolution steps must never emit bytes to stdout (fd 1) or read from the IDE's stdin (fd 0) pipe, and interactive terminal pickers must not block on a headless JSON-RPC pipe.
  3. On msb (microsandbox), a plain msb exec buffers or waits for stdin EOF before completing non-interactive I/O; msb exec --stream (and sbx exec -i without -t) is required for real-time bidirectional JSON-RPC line streaming while the IDE holds stdin open.

Plan & Changes (ADR-0040)

  • docs/adr/0040-acp-standard-agent-interface.md: Record the architectural decision to expose acq acp as acq's standard programmatic agent interface alongside interactive acq run (PTY) and one-shot acq exec.
  • acq.backends/agents.sh & acq.backends/common.sh:
    • Add acq_agent_kit_acp_entrypoint (resolving known coding agents and rejecting shell).
    • Add acq_build_acp_argv (mapping opencode to opencode acp with working directory set by acq_backend_run's -w "$ws", honoring post--- flags and custom ACP server overrides).
    • Include acp in acq_session_is_user.
  • acq.backends/msb.sh & acq.backends/sbx.sh:
    • Pass --stream to msb exec and -i to sbx exec when ACQ_SESSION_KIND=acp for byte-faithful bidirectional streaming without a PTY.
  • acq:
    • Add acq acp [AGENT] [PATH ...] [-- ACP_ARGS...] and acq acp SANDBOX_NAME [-- ACP_ARGS...].
    • Run the entire prologue with </dev/null >&2, ACQ_NO_PROMPT=1, and ACQ_UPDATE_CHECK=0.
    • Fast-path already-running sandboxes whose kit bundle provenance is current so IDE reconnects skip redundant remote kit fetches.
  • Documentation & Tests:

Verification Transcript

1. Offline Bash 3.2 Syntax & Bats Unit Suite

$ ./scripts/test-acq-bash32 --syntax
test-acq-bash32: 36 files parse under bash 3.2.57

$ ./scripts/test-acq-bats test/bats/36-agent-catalog.bats test/bats/60-help.bats
1..29
ok 10 agents: acq_agent_kit_acp_entrypoint resolves coding agents and rejects shell
ok 11 agents: acq_build_acp_argv builds opencode acp and honors -- flags and command escape
ok 19 help: every acq-owned verb prints its own per-verb usage (not the banner)
... (29/29 passed)

$ ./scripts/test-acq-bats --filter '^acp:' test/bats/30-dispatch-routing.bats
1..4
ok 1 acp: acq acp opencode creates sandbox if missing, keeps stdout pure, and runs opencode acp over exec -i (no PTY)
ok 2 acp: acq acp on existing msb sandbox heals and runs msb exec --stream without -t
ok 3 acp: acq acp fast-paths an already-running current sandbox without re-applying kits
ok 4 acp: acq acp rejects shell and unknown targets with exit 2

$ ./scripts/fix-exec-bits --check
fix-exec-bits: OK - every tracked file matches its index mode

2. Live End-to-End Verification (Zed + msb v0.7.7 + OpenCode v2.0.30)

Verified both via open-pipe bidirectional JSON-RPC (initialize -> session/new in 1.62s / 3.02s) and live inside Zed (agent_servers.opencode-acq), confirming the agent runs inside the msb microVM (uid=1000(agent), /var/lib/acq/host :ro, /var/lib/acq/provider-input/generation.* :ro, workspace mounted rw).

Rollback

Revert the squash-merge commit on main. acq acp is an additive subcommand; existing acq run, acq create, and acq exec flows are unchanged.

Security Impact

  • Boundary Protection (SC-7, AC-6): The host IDE communicates over stdio pipes via msb exec --stream / sbx exec -i; no TCP ports are opened on the host, and provider/GitHub credentials remain bound to the sandbox wire injector.
  • Host-Authoritative Config (SI-7, ADR-0035): Preserves read-only /var/lib/acq/host and /var/lib/acq/provider-input mounts.
  • Disclosure: AI-assisted contribution via OpenCode (gemini-4-argon), reviewed and verified live.

Add a first-class 'acq acp' subcommand (ADR-0040) that launches a
sandboxed coding agent's Agent Client Protocol (ACP) server over
bidirectional stdio without allocating a PTY:

- Route all prologue output (backend resolution, prepare, create-or-heal,
  and credential validation) to stderr with stdin bound to /dev/null and
  ACQ_NO_PROMPT=1 / ACQ_UPDATE_CHECK=0 enforced so stdout stays reserved
  for JSON-RPC 2.0 frames.
- Pass '--stream' to 'msb exec' and '-i' to 'sbx exec' when
  ACQ_SESSION_KIND=acp so bidirectional JSON-RPC lines stream without
  waiting for stdin EOF or allocating a PTY.
- Fast-path already-running sandboxes on the current kit bundle so IDE
  reconnects skip redundant remote kit fetches.
- Add ADR-0040, how-to documentation for Zed agent_servers, KFM #53, and
  offline Bats unit coverage.

Co-authored-by: OpenCode [gemini-4-argon] <John.Jediny@gsa.gov>
@JJediny
JJediny requested a review from a team as a code owner November 13, 2026 16:53
@mogul

mogul commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

@JJediny this is an interesting idea! I wish you'd talked to us about it first though... We're about to land a major Python rewrite of acq, and we don't want to integrate this before we do that. Are you game to make another run at this once the Python version is in place?

@JJediny

JJediny commented Nov 13, 2026

Copy link
Copy Markdown
Member Author

@mogul sure just point me at the branch to work off a porting to python

@JJediny

JJediny commented Nov 13, 2026

Copy link
Copy Markdown
Member Author

Closing without merging. Per the maintainers, this waits for the Python implementation. The Python port is #700, and both are tracked in #701.

AI-assisted.

@JJediny JJediny closed this Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants