mirror of
https://github.com/agentclientprotocol/claude-agent-acp.git
synced 2026-10-27 04:30:59 +00:00
d24272c6b0
Second part of step 3 of opt-in ACP v2 support (#1217, #1219, #1222). The v2 surface now serves `session/prompt` and `session/cancel`. It still doesn't advertise `capabilities.session`; that waits for tool calls and replay (step 4). ## What `src/v2/prompt.ts` serves a v2 prompt through the agent's turn events (#1222), instead of translating it into a v1 prompt: | Turn event | v2 | |---|---| | `inserted(messageId)` | `user_message` (the prompt as received, under the uuid Claude Code echoed), `state_update: running`, then the answer `{ messageId }` | | `awaitingUser()` / `resumed()` | `requires_action` / `running` | | `ended(outcome)` | `idle` with the stop reason, `usage`, and `_meta` | | `ended` before insertion | `-32800`: a queued prompt that a cancel ended | | `failed` before insertion | the error as the JSON-RPC answer | | `failed` after insertion | an error `notice` that shows it, then `idle` with the custom stop reason `_error` and v1's JSON-RPC error in `_meta.claudeCode.error` | The last row is a gap in the draft: the idle `state_update` has no error, its stop reasons are all non-error ones, and a notice "must not carry … fatal-error reporting". So the failure travels on `idle` as a `_`-prefixed custom stop reason, which the draft allows, with the error in `_meta`; `auth_required`'s code survives there. The notice shows the agent's own failure title ("API Error: 529 Overloaded"); `TurnEvents.failed` gains an optional `title` for it. That's going back to the v2 draft as feedback. - `session/cancel` maps to the v1 cancel. - **Ordering:** the turn's state updates and the agent's own updates go through one `ctx.notify` path in call order, so `idle` comes after the turn's last output. The tests check the order. - **Message chunks** (`agent_message_chunk`, `agent_thought_chunk`, `user_message_chunk`) are translated with the `messageId` v2 requires, and fail loudly without one. - **Prompt content:** blocks that v1 can't express (a custom or future type) are rejected with `-32602`. Audience roles that v1 doesn't know are dropped from annotations, which the agent doesn't read. - Tool call and plan updates still fail loudly until their step. ## The one change on v1 The agent built three message chunks without a `messageId`: local command output, a result forwarded as the answer (a local-only command, or the issue #453 fallback), and a refusal explanation. Each now carries the uuid of the SDK message it came from, the id `messageIdForGrouping` already uses for non-assistant messages. It's an additive field on v1. None of the recorded v1 scenario baselines contain these chunks, so they don't change. ## Testing `src/tests/acp-v2.test.ts` drives the router with the SDK's v2 client, which validates every message against the v2 schema. Its mocked Claude Code now answers prompts: each turn echoes its prompt, then runs a script. New tests: - a prompt is answered with the echoed uuid while its turn still runs, then `agent_message_chunk` and `idle end_turn` with usage; - a queued prompt stays unanswered until the turn before it ends, then is answered with its own echoed uuid; - an MCP elicitation during the turn gives `requires_action`, then `running`; - `session/cancel` follows a real interrupt: output Claude Code sends after it arrives before `idle cancelled`, and a queued prompt is answered `-32800`; - a turn whose result is an API error gives an error `notice` with the agent's title, then `idle _error` with the error code; a missing login keeps `auth_required`'s code; - a queued prompt whose stream ends before insertion is answered with the error; - a refusal explanation carries the refusing result's uuid; - local command output and a forwarded result each arrive with their SDK message's uuid as `messageId`; - a prompt with a `_acme/widget` block is rejected and never reaches Claude Code; - a chunk without a `messageId` fails translation, and audience roles v1 doesn't know are dropped. Mutation check: answering at the end or at queueing instead of at insertion, dropping `user_message`, answering a cancelled queued prompt, dropping the failure notice or its title, ending a failure with `end_turn` or without the error, dropping `requires_action`, removing any of the three new `messageId`s, accepting any content block, or swallowing a failure before insertion each fails at least one test. `npm run build`, `npm run check`, `npm run test:run` (2240 passed). ## Not in this PR A review of this PR found these in the agent's turn reporting and cancellation, outside the mapping. They're tracked for their own PRs before the v2 surface is advertised; the first three also affect v1: - insertion is reported at the echo, which can lag the turn's first output; - a cancelled queued prompt's streamed output still reaches the client; - cancelling a held turn settles it before the interrupt's remaining output; - `session/close` answers before the active turn's `idle cancelled`; - whether a held turn should delay `idle` in v2 at all.
ACP adapter for the Claude Agent SDK
Use Claude Agent SDK from ACP-compatible clients!
This tool implements an ACP agent by using the official Claude Agent SDK, supporting:
- Context @-mentions
- Images
- Tool calls (with permission requests)
- Compact file changes through the negotiated AIR diff patch extension
- Following
- Edit review
- TODO lists
- Nested subagent transcripts
- Interactive (and background) terminals
- Custom Slash commands
- Client MCP servers
/mcpin the chat: the MCP server status as a list. The adapter runs/mcp reconnect,/mcp enable, and/mcp disablethrough the SDK control API, because Claude Code refuses them in SDK mode. A reconnect of an ACP server that needs authentication starts MCP OAuth through URL elicitation- Session-scoped long-running goals for AIR through the goal extension under
_meta.jetbrains.air.goal - Structured errors, recovery, and warnings through the opt-in session failure extension
- Concrete model and effort defaults through the opt-in recommended config value extension
- Tool permission presentation, editable choices, and durable effects through the permission extension
- One fact per field in every tool call report, as the ACP tool call contract defines
- All AIR extensions, capabilities, and
_metakeys: AIR extensions
Learn more about the Agent Client Protocol.
To try changes that have landed on main but are not released yet, install from the
preview channel — every push to main publishes one. See
docs/RELEASES.md.
npm install @agentclientprotocol/claude-agent-acp@preview
Subagent sessions
Subagents are exposed only after bilateral capability negotiation. Until the released ACP SDKs
preserve the draft clientCapabilities.subagents field, a supporting client may advertise
nativeSubagentSessions in _meta.jetbrains.air.capabilities; the adapter mirrors the capability
in its initialize response. The canonical field remains supported and takes precedence once it is
available. Without either client signal, Agent/Task lifecycle keeps its legacy ordinary ACP
tool-call representation and child interactions stay on the root session. Clients that use the
historical _meta["subagent-transcript"] capability or forwardSubagentText session option retain
the flattened child transcript behavior. See AIR extensions.
Contribution Policy
This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms:
By contributing to this project, you agree that your contributions will be licensed under the Apache License, Version 2.0. You affirm that you have the legal right to submit your work, that you are not including code you do not have rights to, and that you understand contributions are made without requiring a Contributor License Agreement (CLA).