Skip to content

feat: update to schema v1.34.0 and v2.0.0-beta.1 - #355

Merged
benbrandt merged 1 commit into
mainfrom
feat/schema-v1.34.0
Nov 21, 2026
Merged

benbrandt merged 1 commit into
mainfrom
feat/schema-v1.34.0

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Regenerates the v1 and v2 bindings from schema v1.34.0 and v2.0.0-beta.1. ACP v2 moved to Preview with this release. The v2 entrypoints stay experimental.

I went through the whole ACP diff from v1.19.0 to v1.20.0 (88 commits, spec pages included) and checked each change against the SDK. The sections below list what changed here, what needed no change, and what I left for a follow-up.

Moved to the stable entrypoints

  • v1: plan operations (plan_update with items or markdown plans, plan_removed, the plan client capability) and subagent sessions (subagent_update, session_message, session_message_chunk, session tool call content, the subagents client capability, and the StateUpdate and IdleStateUpdate guards). Agents send them only to a client that advertises the capability.
  • v2: Markdown plans and plan_removed. They need no client capability.

MIGRATION_STABLE_UNSTABLE.md no longer lists either as unstable.

Changed on receive

  • Elicitation scope and multi-select items (v2). The schema now forbids some keys with propertyNames: { not }. The generator restores that with a new forbidKeys helper, so elicitation/create fails with -32602 before the handler runs when:
    • a request-scoped elicitation carries sessionId or toolCallId, also with a null value
    • a session-scoped one carries requestId
    • multi-select items have a type but no valid enum. They parsed as the titled form before.
  • systemPrompt.content: [] (v2) fails session/new and session/resume with -32602. The schema has minItems: 1 now.
  • compaction_update (v2) parses without status, which is a patch field now: omitted leaves the status unchanged, and null resets it to in_progress.
  • Repeated initialize below v2. A v2 agent negotiates it like a first one and answers -32022 with supported: [2]. It answered -32600 before, which no longer fits: a client may now repeat initialize with a lower version it supports. The earlier initialization stays in effect. With a v1 and v2 router the error still lists only v2, because the router does not re-route a connection.

Beyond the regenerated files

  • scripts/generate.js: the two release tags, IdleStateUpdate and StateUpdate moved from the v1 unstable union list to the v1 stable one, and a new annotateForbiddenKeys stage with a call-site count guard (3 per v2 lane, 0 per v1 lane). Any other propertyNames shape fails generation.
  • src/examples/dual-version-agent.ts: session/close marks the session inactive before it cancels the work. Before, a prompt that arrived while the session was closing could be held, inserted, and run after the close response.
  • Handler and module docs in src/v2/bindings.ts, src/v2/acp.ts and src/v1/bindings.ts:
    • Prompt retries. This reverses advice from feat: update to schema v1.33.0 and v2.0.0-alpha.17 #350. A successful session/resume does not show which keys the agent kept. A client does not resend an unanswered prompt automatically when a duplicate would matter, and lets the user decide.
    • Replay. Sending session/resume does not mark the start of the replay. A live update the agent sent before it received the request can arrive before replay_complete. A replay does not include past usage, session info, config option, or command list updates.
    • Cancellation. The agent reports idle with cancelled before it starts new foreground work, and does not reject a prompt because a cancellation is in progress. A child also reports cancelled when its parent cancels its work.
    • Permissions. A selected outcome is not approval by itself. A reject option, an unoffered optionId, an unknown kind or outcome, an error response, and a lost connection all mean not approved.
    • Session setup, close and delete. An absolute stdio command, continuing without an MCP server that fails to start, what the agent still answers after the close response, and that a child session cannot be closed or deleted on its own.
    • Plans, the v1 plan and subagents capability gates, metadata patches on usage_update, and a form the client cannot render (-32602).
  • README.md, the src/v2/acp.ts module doc, the v2 typedoc titles and the example's header say Preview.
  • 32 new tests: the new wire shapes through both entrypoints of each version, forbidKeys, a message without params written without a params key, and the example's permission outcomes, a prompt after session/cancel, and a prompt while the session is closing.

Checked, no change needed

  • JSON-RPC envelope. The v2 schema now rejects "params": null. The SDK never writes it: params is passed through and JSON.stringify drops undefined.
  • Permission options and terminal size. The validators already had min(1) and gte(1).
  • Null request IDs, -32601 for tool_call/cancel and terminal/cancel without a handler, and a new session's state after the response were already covered by earlier PRs.
  • The example's v2 side already rejects unadvertised prompt content, system prompts and MCP transports with -32602, approves a tool call only for the offered allow option, ends a replay with replay_complete, and starts a later prompt's work after the cancelled turn's idle update. Its v1 side sends no plan updates.
  • The generator ignores the schema's new root allOf, x-methods, x-state and x-scope, and the Error if/then.

Found while testing, not fixed here

The connection can invoke handlers out of receive order. receive() does not wait for one message's dispatch before it starts the next, and processIncomingMessage awaits each handler in turn, so a message whose handler is registered earlier can overtake one received before it. Two probes showed it:

  • Agent side. session/cancel followed by session/prompt in one chunk invoked the prompt handler first. The example then holds the prompt and the cancel drops it with -32800, which the spec does not allow for a prompt received after session/cancel.
  • Client side. Two session/update notifications followed by a response in one chunk: the code awaiting the response continued before either notification handler ran. That affects anything that relies on updates before a response, such as replay_complete before the session/resume response.

Both predate this release. The fix belongs in src/core/jsonrpc.ts and should be its own PR. Because of it, the new cancellation test waits for the cancelled tool call before it sends the next prompt.

Not in this PR

  • The dispatch order fix above.
  • Calling v2 "draft" or "experimental". 37 "draft" mentions remain in hand-written files, plus 24 @experimental tags and the experimental/v2 entrypoint names. Whether the SDK's own labels change with Preview is a separate question.
  • assertSupportedMcpServers rejecting a relative stdio command. It changes what a published helper rejects, and "absolute" depends on the agent's platform. It is only documented for now.
  • Types for the forbidden keys, such as toolCallId?: never on a request-scoped elicitation, so a builder gets a compile error.
  • The schema's new x-methods, envelope rules, and x-state / x-scope hints. They could check the method tables or generate client-side state helpers. None is used yet.
  • Send-side checks. The SDK validates no outgoing params today.
  • Carried over from feat: update to schema v1.33.0 and v2.0.0-alpha.17 #350: answering a cancelled session/request_permission or elicitation/create with the cancelled outcome or the cancel action when the handler throws after its signal aborts (today -32800), and client-side state helpers.

For review

  • forbidKeys returns a plain ZodType, not a ZodObject, for zElicitationSessionScope, zElicitationRequestScope and zTitledMultiSelectItems. Code that called .shape or .extend on those exported validators would break. Nothing in the repo does.
  • The -32022 answer for a repeated initialize below v2 matches what the Rust SDK does.

npm run check passes (720 tests).

Regenerate the v1 and v2 bindings from schema v1.34.0 and v2.0.0-beta.1.
ACP v2 is in Preview from this release. The v2 entrypoints stay
experimental.

Plan operations and v1 subagent sessions are stable, so they move from the
unstable entrypoints to the stable ones. In v2, Markdown plans and
`plan_removed` are part of the stable-feature entrypoint.

The generator now restores `propertyNames: { not }` clauses with a new
`forbidKeys` helper, so the v2 validators reject a `toolCallId` or
`sessionId` on a request-scoped elicitation, a `requestId` on a
session-scoped one, and a `type` on titled multi-select items.

A repeated `initialize` that requests a version below v2 is negotiated
like a first one and gets `-32022` instead of `-32600`, since a Client may
now repeat `initialize` with a lower version.

The handler and module docs follow the spec changes of this release, and
the dual-version example no longer inserts a prompt that arrives while its
session is closing.
@benbrandt
benbrandt merged commit 2657e5b into main Nov 21, 2026
6 checks passed
@benbrandt
benbrandt deleted the feat/schema-v1.34.0 branch November 21, 2026 10:31
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