Repository navigation
feat: update to schema v1.34.0 and v2.0.0-beta.1 - #355
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
plan_updatewithitemsormarkdownplans,plan_removed, theplanclient capability) and subagent sessions (subagent_update,session_message,session_message_chunk,sessiontool call content, thesubagentsclient capability, and theStateUpdateandIdleStateUpdateguards). Agents send them only to a client that advertises the capability.plan_removed. They need no client capability.MIGRATION_STABLE_UNSTABLE.mdno longer lists either as unstable.Changed on receive
propertyNames: { not }. The generator restores that with a newforbidKeyshelper, soelicitation/createfails with-32602before the handler runs when:sessionIdortoolCallId, also with anullvaluerequestIditemshave atypebut no validenum. They parsed as the titled form before.systemPrompt.content: [](v2) failssession/newandsession/resumewith-32602. The schema hasminItems: 1now.compaction_update(v2) parses withoutstatus, which is a patch field now: omitted leaves the status unchanged, andnullresets it toin_progress.initializebelow v2. A v2 agent negotiates it like a first one and answers-32022withsupported: [2]. It answered-32600before, which no longer fits: a client may now repeatinitializewith 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,IdleStateUpdateandStateUpdatemoved from the v1 unstable union list to the v1 stable one, and a newannotateForbiddenKeysstage with a call-site count guard (3 per v2 lane, 0 per v1 lane). Any otherpropertyNamesshape fails generation.src/examples/dual-version-agent.ts:session/closemarks 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.src/v2/bindings.ts,src/v2/acp.tsandsrc/v1/bindings.ts:session/resumedoes 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.session/resumedoes not mark the start of the replay. A live update the agent sent before it received the request can arrive beforereplay_complete. A replay does not include past usage, session info, config option, or command list updates.idlewithcancelledbefore it starts new foreground work, and does not reject a prompt because a cancellation is in progress. A child also reportscancelledwhen its parent cancels its work.selectedoutcome is not approval by itself. A reject option, an unofferedoptionId, an unknown kind or outcome, an error response, and a lost connection all mean not approved.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.planandsubagentscapability gates, metadata patches onusage_update, and a form the client cannot render (-32602).README.md, thesrc/v2/acp.tsmodule doc, the v2 typedoc titles and the example's header say Preview.forbidKeys, a message without params written without aparamskey, and the example's permission outcomes, a prompt aftersession/cancel, and a prompt while the session is closing.Checked, no change needed
"params": null. The SDK never writes it:paramsis passed through andJSON.stringifydropsundefined.optionsand terminal size. The validators already hadmin(1)andgte(1).-32601fortool_call/cancelandterminal/cancelwithout a handler, and a new session's state after the response were already covered by earlier PRs.-32602, approves a tool call only for the offered allow option, ends a replay withreplay_complete, and starts a later prompt's work after the cancelled turn's idle update. Its v1 side sends no plan updates.allOf,x-methods,x-stateandx-scope, and theErrorif/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, andprocessIncomingMessageawaits each handler in turn, so a message whose handler is registered earlier can overtake one received before it. Two probes showed it:session/cancelfollowed bysession/promptin 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 aftersession/cancel.session/updatenotifications 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 asreplay_completebefore thesession/resumeresponse.Both predate this release. The fix belongs in
src/core/jsonrpc.tsand 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
@experimentaltags and theexperimental/v2entrypoint names. Whether the SDK's own labels change with Preview is a separate question.assertSupportedMcpServersrejecting a relative stdiocommand. It changes what a published helper rejects, and "absolute" depends on the agent's platform. It is only documented for now.toolCallId?: neveron a request-scoped elicitation, so a builder gets a compile error.x-methods, envelope rules, andx-state/x-scopehints. They could check the method tables or generate client-side state helpers. None is used yet.session/request_permissionorelicitation/createwith thecancelledoutcome or thecancelaction when the handler throws after itssignalaborts (today-32800), and client-side state helpers.For review
forbidKeysreturns a plainZodType, not aZodObject, forzElicitationSessionScope,zElicitationRequestScopeandzTitledMultiSelectItems. Code that called.shapeor.extendon those exported validators would break. Nothing in the repo does.-32022answer for a repeatedinitializebelow v2 matches what the Rust SDK does.npm run checkpasses (720 tests).