Skip to content

fix: follow the remaining ACP schema 1.13 rules in Testy, examples, and docs - #452

Merged
benbrandt merged 6 commits into
mainfrom
schema-1.13-followups
Oct 28, 2026
Merged

benbrandt merged 6 commits into
mainfrom
schema-1.13-followups

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Follow-ups to the schema 1.13 update (#443, #444) that bring Testy, the examples, and the docs in line with the remaining v2 spec changes. #450 already covered the prompt-content rejection, simple_agent_v2's resume session info, and most of the Schema 1.13 section, so this branch adds only what that left out.

Each commit can be reviewed on its own:

  • Testy and simple_agent_v2 reject session/list cursors. Neither issues a nextCursor, so any cursor a client sends is invalid and gets -32602, as v1 Testy already does.
  • Testy v2 sends session info before its resume response. The session-setup page says agents SHOULD send current session info after any replay and before responding. md/testy.md documents this, the prompt-content and cursor rules, and that the prompt response carries messageId.
  • Docs for the acp MCP declaration and remaining 1.13 notes. The v2 with_mcp_server builders declare an McpServer::Acp server, which a conforming agent rejects with -32602 unless it advertises session.mcp.acp. The rustdoc and the protocol v2 chapter now say so and point to McpOverAcpPolyfill. No runtime capability check is added. The Schema 1.13 section also lists the new _meta fields, and the v1 downgrade notes that terminal auth is kept.
  • Close ordering and cancelled responses. V2Session::close rustdoc now describes the close ordering from the spec. The cancellation docs no longer suggest answering a cancelled request with partial data: a successful response is allowed only where the method defines one, and -32800 otherwise. The error-handling docs note the reserved code ranges.
  • Example clients.
    • v2_one_shot_client and the cookbook's v2 recipe decline permission requests with the agent's reject_once option. They fall back to session/cancel plus the cancelled outcome only when there is no such option.
    • Both treat any non-idle state, including an unknown one, as active work.
    • yopo and v2_one_shot_client strip control characters from agent text before printing it, per the security considerations.
  • Dead downgrade keys. The v1 initialize downgrade no longer lists nes and positionEncodings, which schema 1.12 removed.

Testing:

  • cargo fmt --all --check
  • cargo clippy --workspace --all-targets --all-features --locked
  • cargo test --workspace --all-features --locked --exclude agent-client-protocol-derive: 951 passed

The derive crate's tests were excluded because their test binary fails to load locally (a dyld rpath issue in the local runner); none of these commits touch that crate.

benbrandt and others added 6 commits October 28, 2026 16:41
Testy v2 and the simple_agent_v2 example return every session in one page
and never issue nextCursor, so any cursor a client sends is invalid and
must fail with -32602, matching v1 Testy.

Co-Authored-By: Claude <noreply@anthropic.com>
The v2 session-setup page says agents SHOULD send current session info via
session_info_update after any requested replay and before the resume
response, even without replayFrom. Testy v2 now does so alongside the
idle-state snapshot, as simple_agent_v2 already does.

md/testy.md now documents this, the baseline prompt content and
session/list cursor rules, and that the v2 prompt response carries the
accepted user message's messageId rather than being empty.

Co-Authored-By: Claude <noreply@anthropic.com>
The v2 with_mcp_server builders declare an acp MCP server, which a
conforming agent rejects with -32602 unless it advertises session.mcp.acp.
Say so in their rustdoc and the protocol v2 chapter, and point to a
compatibility proxy such as McpOverAcpPolyfill for agents without it.

The Schema 1.13 section also lists the new _meta fields on DiffPatch,
ToolCallPermissionSubject, and Icon, and the v1 downgrade notes that terminal
authentication is kept.

Co-Authored-By: Claude <noreply@anthropic.com>
V2Session::close now documents the session/close ordering: it cancels like
session/cancel, sends final updates and idle(cancelled) before the close
response, fails uninserted prompts with -32800, and leaves later commands
to fail with -32002.

The Responder::cancellation and cancellation chapter no longer suggest
answering a cancelled request with partial data: a successful response is
only allowed where the method defines one for cancellation, and -32800
otherwise. The error handling chapter notes the reserved JSON-RPC and ACP
error code ranges.

Co-Authored-By: Claude <noreply@anthropic.com>
…put in clients

The v2_one_shot_client example answered every permission request with the
cancelled outcome without sending session/cancel. It and the cookbook's v2
recipe now select the agent's reject_once option by kind and fall back to
session/cancel plus the cancelled outcome only when none is offered.

Both now treat any non-idle state, including StateUpdate::Other, as active
foreground work, since clients must show unrecognized states as busy and
never as idle.

yopo and v2_one_shot_client strip control characters other than newline
and tab from agent text before printing it, so untrusted escape sequences
cannot manipulate the terminal.

Co-Authored-By: Claude <noreply@anthropic.com>
…rade

Schema 1.12 removed Next Edit Suggestions and their position-encoding
capabilities, so v1 ClientCapabilities no longer has nes or
positionEncodings fields. Copying those keys during the v1 downgrade was
dead code: typed v1 decoding discarded them anyway.

Co-Authored-By: Claude <noreply@anthropic.com>
@benbrandt
benbrandt enabled auto-merge (squash) October 28, 2026 15:48
@benbrandt
benbrandt merged commit 1d2b358 into main Oct 28, 2026
13 checks passed
@benbrandt
benbrandt deleted the schema-1.13-followups branch October 28, 2026 15:54
@acp-release-bot acp-release-bot Bot mentioned this pull request Oct 28, 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.

1 participant