Skip to content

fix(acp): Allow v2 initialize with future params #304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benbrandt wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(acp): Allow v2 initialize with future params #304

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 34 additions & 42 deletions md/migration_v2.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,16 @@ version-aligned as part of the coordinated release but do not impose that public
constraint. The rmcp integration moves to 3.x because both `agent-client-protocol` and `rmcp` are
public dependencies in its API:

| Crate | Coordinated release |
| --- | --- |
| `agent-client-protocol` | 2.x |
| `agent-client-protocol-derive` | 2.x |
| `agent-client-protocol-conductor` | 2.x |
| `agent-client-protocol-cookbook` | 2.x |
| `agent-client-protocol-http` | 2.x |
| `agent-client-protocol-polyfill` | 2.x |
| `agent-client-protocol-trace-viewer` | 2.x |
| `agent-client-protocol-rmcp` | 3.x |
| Crate | Coordinated release |
| ------------------------------------ | ------------------- |
| `agent-client-protocol` | 2.x |
| `agent-client-protocol-derive` | 2.x |
| `agent-client-protocol-conductor` | 2.x |
| `agent-client-protocol-cookbook` | 2.x |
| `agent-client-protocol-http` | 2.x |
| `agent-client-protocol-polyfill` | 2.x |
| `agent-client-protocol-trace-viewer` | 2.x |
| `agent-client-protocol-rmcp` | 3.x |

## Notifications cannot receive error responses

Expand Down Expand Up @@ -118,11 +118,11 @@ channel adapter may still override `into_channel_and_future` to avoid an interme
`ResponseRouter` completes a local pending request; it does not send a new JSON-RPC response.
Its methods have therefore been renamed:

| 1.x | 2.0 |
| --- | --- |
| `respond_with_result` | `route_with_result` |
| `respond` | `route` |
| `respond_with_error` | `route_with_error` |
| 1.x | 2.0 |
| ----------------------------- | --------------------------- |
| `respond_with_result` | `route_with_result` |
| `respond` | `route` |
| `respond_with_error` | `route_with_error` |
| `respond_with_internal_error` | `route_with_internal_error` |

`Responder` still uses `respond*`, because it sends the response to an incoming request.
Expand Down Expand Up @@ -185,14 +185,14 @@ the connection, replace `run_indefinitely()` with `detach()`. Detaching no longe
Builder extensions implementing `RunWithConnectionTo` run alongside the connection; they do not
respond to an individual JSON-RPC request. The builder method now reflects that distinction:

| 1.x | 2.0 |
| --- | --- |
| 1.x | 2.0 |
| ------------------------- | ---------------------- |
| `Builder::with_responder` | `Builder::with_runner` |

The conductor crate applies the same terminology to its public background task:

| 1.x | 2.0 |
| --- | --- |
| 1.x | 2.0 |
| ----------------------------------------------------- | -------------------------------------------------- |
| `agent_client_protocol_conductor::ConductorResponder` | `agent_client_protocol_conductor::ConductorRunner` |

This is a type rename only; custom code that names the conductor task should update its imports
Expand All @@ -203,9 +203,9 @@ and type references.
The combined matchers operate on `Dispatch` values, which can represent requests, notifications,
or responses. Their method names now reflect that input:

| 1.x | 2.0 |
| --- | --- |
| `MatchDispatch::if_message` | `MatchDispatch::if_dispatch` |
| 1.x | 2.0 |
| ------------------------------------ | ------------------------------------- |
| `MatchDispatch::if_message` | `MatchDispatch::if_dispatch` |
| `MatchDispatchFrom::if_message_from` | `MatchDispatchFrom::if_dispatch_from` |

## Connection and session accessors borrow
Expand Down Expand Up @@ -253,22 +253,22 @@ use:
The low-level SDK-local `McpConnectRequest`, `McpConnectResponse`, `McpOverAcpMessage`, and
`McpDisconnectNotification` types were removed. Use the feature-gated schema types instead:

| 1.x SDK-local type | 2.0 schema type |
| --- | --- |
| `McpConnectRequest` | `schema::v1::ConnectMcpRequest` |
| `McpConnectResponse` | `schema::v1::ConnectMcpResponse` |
| `McpOverAcpMessage` request | `schema::v1::MessageMcpRequest` |
| `McpOverAcpMessage` notification | `schema::v1::MessageMcpNotification` |
| `McpDisconnectNotification` | `schema::v1::DisconnectMcpRequest` and `DisconnectMcpResponse` |
| 1.x SDK-local type | 2.0 schema type |
| -------------------------------- | -------------------------------------------------------------- |
| `McpConnectRequest` | `schema::v1::ConnectMcpRequest` |
| `McpConnectResponse` | `schema::v1::ConnectMcpResponse` |
| `McpOverAcpMessage` request | `schema::v1::MessageMcpRequest` |
| `McpOverAcpMessage` notification | `schema::v1::MessageMcpNotification` |
| `McpDisconnectNotification` | `schema::v1::DisconnectMcpRequest` and `DisconnectMcpResponse` |

The public method-name constants moved to the schema's generated method-name
tables:

| 1.x SDK-local constant | 2.0 schema constant |
| --- | --- |
| `METHOD_MCP_CONNECT_REQUEST` | `schema::v1::CLIENT_METHOD_NAMES.mcp_connect` |
| `METHOD_MCP_MESSAGE` | `schema::v1::CLIENT_METHOD_NAMES.mcp_message` or `AGENT_METHOD_NAMES.mcp_message`, depending on direction |
| `METHOD_MCP_DISCONNECT_NOTIFICATION` | `schema::v1::CLIENT_METHOD_NAMES.mcp_disconnect` |
| 1.x SDK-local constant | 2.0 schema constant |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `METHOD_MCP_CONNECT_REQUEST` | `schema::v1::CLIENT_METHOD_NAMES.mcp_connect` |
| `METHOD_MCP_MESSAGE` | `schema::v1::CLIENT_METHOD_NAMES.mcp_message` or `AGENT_METHOD_NAMES.mcp_message`, depending on direction |
| `METHOD_MCP_DISCONNECT_NOTIFICATION` | `schema::v1::CLIENT_METHOD_NAMES.mcp_disconnect` |

Code using `Builder::with_mcp_server` or `SessionBuilder::with_mcp_server` continues to attach the
high-level server in the same place; the emitted declaration and wire methods change. Global
Expand Down Expand Up @@ -350,14 +350,6 @@ are included in the SDK 2.0 migration rather than treated as stable-v1 wire chan
- Terminal state is represented by `Terminal`, `TerminalUpdate`, `TerminalOutput`,
`TerminalOutputChunk`, and `TerminalExitStatus`. `SessionUpdate` also has terminal update and
output-chunk variants, so exhaustive matches must handle the new variants.
- Conversion helpers are now generic and fallible. Replace `v2_to_v1(value)` and
`v1_to_v2(value)` with `try_v2_to_v1::<_, Target>(value)` and
`try_v1_to_v2::<_, Target>(value)`. Use `try_v2_to_v1_many::<_, Target>(value)` when one v2
update may become several v1 updates.
- The bespoke `IntoV1`, `IntoV1Many`, and `IntoV2` conversion traits have been removed. Use the
standard `TryFrom`/`TryInto` traits for fallible conversions, `From`/`Into` for infallible
conversions, or the helper functions above.
- `v2::SessionCapabilities::into_v1()` is now `try_into_v1_parts()`.

## `SentRequest::map` accepts arbitrary output

Expand Down
11 changes: 8 additions & 3 deletions md/protocol-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -319,9 +319,10 @@ The protocol router reads the initial `initialize` request, selects the
highest configured protocol version that is compatible with the requested
version, and then hands the connection to that implementation. If only v2 is
configured, v1 clients are rejected without changing the fluent API. The router
does not convert messages between v1 and v2 after routing. For compatibility,
the initial frame may be a batch whose first call-shaped entry is `initialize`;
the router preserves the complete frame when handing it to the selected
normalizes a v2 initialize request when selecting a v1 implementation, but does
not convert messages between v1 and v2 after routing. For compatibility, the
initial frame may be a batch whose first call-shaped entry is `initialize`; the
router preserves the complete frame when handing it to the selected
implementation. Response-only frames before initialization are ignored.

Clients use a connector because fallback may require opening a new transport.
Expand Down Expand Up @@ -353,6 +354,10 @@ agent:
- If the agent rejects the v2 initialize request, the error is surfaced. A
rejected initialize is not treated as permission to retry with v1.

The reuse probe is conservative: if parsing and serializing the raw v2 request
would change any parameter, reuse is disabled and fallback opens a fresh
connection. That does not turn an otherwise valid v2 request into an error.

## Draft schema changes in schema 1.5 and 1.6

The `unstable_protocol_v2` API follows the moving draft schema. Schema 1.5 added
Expand Down
Loading
Loading