refactor(acp)!: reach each protocol version's schema only through v1::schema / v2::schema (#481)

Each protocol version's message types were reachable twice: as
`agent_client_protocol::schema::v1::X` and as `agent_client_protocol::v1::schema::X`
(and the same for v2). Make the version modules the only path.

- `v1::schema` and `v2::schema` now re-export `agent_client_protocol_schema::v1`
  and `::v2` directly.
- `schema::v1` and `schema::v2` are removed. The root `schema` module keeps
  only the version-neutral items: `ProtocolVersion`, `MaybeUndefined`,
  `IntoOption`, `IntoMaybeUndefined` and `SuccessorMessage`.
- All internal code, tests, examples, the cookbook, doctests and the book use
  the new paths. Public doc examples import `vN::schema` and write
  `schema::X`; internal code uses a local `vN::schema as vN` alias where
  that keeps the diff readable.
- The migration guide gains a rename row and drops the text that presented
  both paths. The stability guidance in lib.rs, the README and the book, and
  the "Adding a protocol version" checklist, point at `vN::schema`.

BREAKING CHANGE: `agent_client_protocol::schema::v1` and
`agent_client_protocol::schema::v2` are removed. Use
`agent_client_protocol::v1::schema` and `agent_client_protocol::v2::schema`
instead. `schema::ProtocolVersion`, `schema::MaybeUndefined`,
`schema::IntoOption`, `schema::IntoMaybeUndefined` and
`schema::SuccessorMessage` are unchanged.

Co-authored-by: Claude <noreply@anthropic.com>

Author: benbrandt

md/design.md

@@ -14,7 +14,7 @@ The core SDK. Provides:
 - **Versioned connection builders** (`Client.v1()`, `Agent.v2()`, ..., `connect_to()`, `connect_with()`)
 - **Per-version modules** (`agent_client_protocol::v1`, and `agent_client_protocol::v2` with `unstable_protocol_v2`) - the same names (`ConnectionTo`, `Builder`, `Responder`, `SessionBuilder`, ...) for each protocol version
 - **Message handling** (`on_receive_request`, `on_receive_notification`, `on_receive_dispatch`)
-- **Protocol types** (`agent_client_protocol::schema::*`) - all ACP message types
+- **Protocol types** (`agent_client_protocol::v1::schema`, and `agent_client_protocol::v2::schema` with `unstable_protocol_v2`) - each protocol version's ACP message types, with the version-neutral items such as `ProtocolVersion` in `agent_client_protocol::schema`
 - **Transports and process launching** (`Channel`, `Lines`, `ByteStreams`, `Stdio`, `AcpAgent`)
 - **MCP server attachment** - runtime-agnostic interfaces for wiring MCP servers into ACP sessions through the opt-in `unstable_mcp_over_acp` transport
 

md/migration-v5.md

@@ -83,8 +83,7 @@ Agent
 ```
 
 When v2 mode is enabled, application code should use SDK types from
-`agent_client_protocol::v2` and message types from `v2::schema`, the same
-module as `agent_client_protocol::schema::v2`. Importing
+`agent_client_protocol::v2` and message types from `v2::schema`. Importing
 `agent_client_protocol::v2::{self, schema}` brings both into scope without a
 name clash. The preceding agent fragment demonstrates version negotiation only.
 An agent that advertises session support must also implement the complete
@@ -107,7 +106,7 @@ handle and complete operation-specific response.
 Low-level custom `with_handler` and `with_runner` implementations continue to
 receive the protocol-neutral `ConnectionTo<_>`, and generic `send_request`
 remains schema-agnostic. These generic APIs do not infer a protocol version from
-the Rust payload type: callers on a v2 connection must use `schema::v2` types,
+the Rust payload type: callers on a v2 connection must use `v2::schema` types,
 or deliberately send extension or untyped messages. The connection guard
 enforces negotiation and initialization lifecycle, not Rust-type provenance.
 Dynamic handlers registered through `v2::ConnectionTo::add_dynamic_handler` use
@@ -251,15 +250,14 @@ the agent must reject. It does not rename or drop either server.
 non-blocking setup helpers for a v2 proxy:
 
 ```rust,ignore
-use agent_client_protocol::schema::v2;
-use agent_client_protocol::v2::SessionSetup;
+use agent_client_protocol::v2::{SessionSetup, schema};
 use agent_client_protocol::{Client, Proxy};
 
 Proxy
     .v2()
     .on_receive_request_from(
         Client,
-        async |request: v2::NewSessionRequest, responder, cx| {
+        async |request: schema::NewSessionRequest, responder, cx| {
             cx.build_session_from(request)
                 .with_mcp_server(session_server)?
                 .on_proxy_session_start(responder, async |setup| {
@@ -356,9 +354,9 @@ it, such as a v2-only agent behind a v1-only proxy, rejects the
 initialization, and the client sees the error.
 
 Proxy implementations use the schema crate's
-`agent_client_protocol::schema::v2::InitializeProxyRequest`. Its response is
-`schema::v2::InitializeProxyResponse`, a transparent wrapper around the v2
-`InitializeResponse`. `schema::v1::InitializeProxyRequest` is the v1
+`agent_client_protocol::v2::schema::InitializeProxyRequest`. Its response is
+`v2::schema::InitializeProxyResponse`, a transparent wrapper around the v2
+`InitializeResponse`. `v1::schema::InitializeProxyRequest` is the v1
 type. Static conductor component providers can carry either selected
 schema, but each supplied component must support that version. Use
 `Agent.protocol_router()` or `Proxy.protocol_router()` when a static component
@@ -416,15 +414,15 @@ The SDK handles the `initialize` negotiation at the JSON-RPC boundary:
 - V2 request ids must be strings or integers. A v2 connection answers a request
   with a `null` id with `-32600` and `id: null`. V1 connections still accept
   `null` ids.
-- Since schema 1.13, v2 has its own `schema::v2::RequestId` without a `Null`
+- Since schema 1.13, v2 has its own `v2::schema::RequestId` without a `Null`
   variant. Request handles carry a protocol marker as their last type
   parameter: `Responder<T, V2>`, `ResponseRouter<T, V2>`,
   `SentRequest<T, V2>`, `PreparedRequest<T, V2>` and
   `Dispatch<Req, Notif, V2>`, named `v2::Responder<T>`,
   `v2::ResponseRouter<T>`, `v2::SentRequest<T>`, `v2::PreparedRequest<T>` and
   `v2::Dispatch<Req, Notif>`. Handles from `Client.v2()`, `Agent.v2()`,
   `Proxy.v2()` and `v2::ConnectionTo` use `V2`, so their `id()` returns a
-  `schema::v2::RequestId`, for example to match an elicitation's `requestId`.
+  `v2::schema::RequestId`, for example to match an elicitation's `requestId`.
   It never fails, because the SDK rejects `null` IDs on v2 connections and
   never assigns `null` itself. v1 builders use `V1`. Low-level
   `HandleDispatchFrom` and `MatchDispatch` handlers are not tied to a version:
@@ -502,17 +500,17 @@ applications built with v2 support to control v2 rollout with a runtime feature
 flag:
 
 ```rust
-use agent_client_protocol::schema::{v1, v2};
+use agent_client_protocol::{v1, v2};
 use agent_client_protocol::{Agent, ConnectTo};
 
-# fn implementation() -> v2::Implementation {
-#     v2::Implementation::new("example", "0.1.0")
+# fn implementation() -> v2::schema::Implementation {
+#     v2::schema::Implementation::new("example", "0.1.0")
 # }
 # async fn serve(client_transport: impl agent_client_protocol::ConnectTo<Agent>) -> agent_client_protocol::Result<()> {
 # let enable_protocol_v2 = true;
 let v1_agent = Agent.v1().on_receive_request(
-    async |initialize: v1::InitializeRequest, responder, _cx| {
-        responder.respond(v1::InitializeResponse::new(initialize.protocol_version))
+    async |initialize: v1::schema::InitializeRequest, responder, _cx| {
+        responder.respond(v1::schema::InitializeResponse::new(initialize.protocol_version))
     },
     agent_client_protocol::on_receive_request!(),
 );
@@ -521,8 +519,8 @@ let agent = Agent.protocol_router().with_v1(v1_agent);
 
 let agent = if enable_protocol_v2 {
     let v2_agent = Agent.v2().on_receive_request(
-        async |initialize: v2::InitializeRequest, responder, _cx| {
-            responder.respond(v2::InitializeResponse::new(
+        async |initialize: v2::schema::InitializeRequest, responder, _cx| {
+            responder.respond(v2::schema::InitializeResponse::new(
                 initialize.protocol_version,
                 implementation(),
             ))
@@ -576,7 +574,7 @@ arrive before initialization are ignored. The proxy protocol router, whose
 with `-32022` but closes after a rejection.
 
 Custom endpoints can construct the same wire error with
-`schema::v2::Error::unsupported_protocol_version(requested, supported).into()`.
+`v2::schema::Error::unsupported_protocol_version(requested, supported).into()`.
 The code is defined by v2 negotiation, not by a change to the v1 protocol.
 The SDK's version-neutral `Error` carries any numeric code, so a v1 client
 receives the initialization error as an unknown code without new v1 schema
@@ -739,7 +737,7 @@ removes keys whose values are `null`, and replaces each other value whole.
 Nested objects are not merged; nested nulls are ordinary data. An empty object
 does not clear metadata. Replay uses the same rules and never implicitly resets
 metadata. `ToolCallUpdate::apply_update` and `TerminalUpdate::apply_update`
-apply this rule; use `schema::v2::apply_meta_update` for application-owned
+apply this rule; use `v2::schema::apply_meta_update` for application-owned
 message, session, compaction, or subagent projections. Metadata on chunks,
 content, snapshots, and `plan_update` is not an entity patch.
 
@@ -836,7 +834,7 @@ Client projections should also follow these rules:
 
 Draft v2 type changes:
 
-- JSON-RPC batching is removed from v2, and `schema::v2::JsonRpcBatch` no
+- JSON-RPC batching is removed from v2, and `v2::schema::JsonRpcBatch` no
   longer exists. The SDK dropped batch support in both protocol versions:
   every connection answers a JSON array with a single `-32600` error with
   `id: null` (see [JSON-RPC batches](#json-rpc-batches)).

md/protocol-v2.md

@@ -22,20 +22,20 @@ Use the version's `SystemPrompt::new` builder and pass the complete request
 through the SDK's `_from` session helpers:
 
 ```rust
-use agent_client_protocol::schema::v1;
+use agent_client_protocol::v1::schema;
 
-let instructions = v1::SystemPrompt::new(vec![
+let instructions = schema::SystemPrompt::new(vec![
     "Review changes without modifying files.".into(),
 ]);
-let request = v1::NewSessionRequest::new("/workspace/project")
+let request = schema::NewSessionRequest::new("/workspace/project")
     .system_prompt(instructions);
 // After checking the agent's advertised capability:
 // connection.build_session_from(request).block_task().start_session().await?;
 # let _ = request;
 ```
 
 This snippet requires `unstable_session_system_prompt`; v2 additionally
-requires `unstable_protocol_v2` and uses the equivalent `v2` types.
+requires `unstable_protocol_v2` and uses the equivalent `v2::schema` types.
 `SystemPrompt::new` defaults to `append` in Rust, but both `mode` and `content`
 are required on the wire. Omitted or `null` `systemPrompt` supplies no client
 instructions. Malformed values fail typed request decoding with `-32602`;
@@ -87,8 +87,8 @@ component that it is running as a proxy and may forward messages with
 
 The response is the matching version's normal `InitializeResponse` result. The
 SDK uses the schema crate's types, one per version:
-`schema::v1::InitializeProxyRequest` and, with `unstable_protocol_v2`,
-`schema::v2::InitializeProxyRequest`. Each is answered with that version's
+`v1::schema::InitializeProxyRequest` and, with `unstable_protocol_v2`,
+`v2::schema::InitializeProxyRequest`. Each is answered with that version's
 `InitializeProxyResponse`, a transparent wrapper around its
 `InitializeResponse`. Convert a forwarded `initialize` response with `.into()`.
 The final agent receives the ordinary `initialize` method and does not need to
@@ -123,8 +123,8 @@ next to `method` and `params`; the inner message keeps its own `_meta` inside
 its `params`.
 
 The schema types for the envelope are `ProxySuccessorRequest`,
-`ProxySuccessorNotification` and `ProxySuccessorResponse` in `schema::v1` and
-`schema::v2`, with the `ProxyRequest`, `ProxyResponse` and `ProxyNotification`
+`ProxySuccessorNotification` and `ProxySuccessorResponse` in `v1::schema` and
+`v2::schema`, with the `ProxyRequest`, `ProxyResponse` and `ProxyNotification`
 unions and the method names in `PROXY_METHOD_NAMES`. They hold the inner
 message as raw JSON. `schema::SuccessorMessage<M>` is the SDK's typed view of
 the same envelope: it holds the inner message as an SDK message type, works for

md/protocol.md

@@ -58,10 +58,11 @@ are private. Work through this list, using v2 as the template. Search for
 `ProtocolVersion::V2` and `unstable_protocol_v2` to find each place.
 
 1. **Schema.** Bump the `agent-client-protocol-schema` pin to a release with
-   the new version's types. Add `schema::v3` in
-   `src/agent-client-protocol/src/schema/mod.rs`, with the JSON-RPC trait
-   implementations for its messages (see `v2_impls.rs`) and its
-   `InitializeProxyRequest`.
+   the new version's types. Implement the JSON-RPC traits for its messages
+   in `src/agent-client-protocol/src/schema/` (see `v2_impls.rs`), including
+   its proxy-chain types (`impl_proxy_jsonrpc!` in `proxy_protocol.rs`). The
+   messages are re-exported as `v3::schema` in step 4, the only public path
+   to them.
 2. **Feature gate.** Add `unstable_protocol_v3` to
    `src/agent-client-protocol/Cargo.toml`, forwarding to the schema crate's
    feature, and to the crates that need a passthrough (the polyfill and the
@@ -72,7 +73,8 @@ are private. Work through this list, using v2 as the template. Search for
    conversions.
 4. **Connection and module.** Add `jsonrpc/v3_connection.rs` and
    `src/agent-client-protocol/src/v3.rs`, re-exporting the shared names
-   (`ConnectionTo`, `Builder`, the request handle aliases, `schema`) and the
+   (`ConnectionTo`, `Builder`, the request handle aliases, and
+   `pub use agent_client_protocol_schema::v3 as schema;`) and the
    version's session API. Add `Client.v3()`, `Agent.v3()` and `Proxy.v3()`.
 5. **Negotiation.** Teach the wire guard in `jsonrpc/protocol_compat.rs` the
    new version: selecting it from `initialize` and `proxy/initialize`,

md/versioning.md

@@ -137,8 +137,7 @@
 use std::sync::Arc;
 
 #[cfg(feature = "unstable_protocol_v2")]
-use agent_client_protocol::schema::v2;
-use agent_client_protocol::schema::{ProtocolVersion, v1};
+use agent_client_protocol::v2::schema as v2;
 use agent_client_protocol::{
     Agent, BoxFuture, Client, Conductor, ConnectTo, Dispatch, DynConnectTo, Error, JsonRpcMessage,
     Proxy, Responder, Role, RunWithConnectionTo, UntypedMessage, role::HasPeer,
@@ -149,6 +148,7 @@ use agent_client_protocol::{
 };
 use agent_client_protocol::{HandleDispatchFrom, util::MatchDispatchFrom};
 use agent_client_protocol::{Handled, schema::SuccessorMessage};
+use agent_client_protocol::{schema::ProtocolVersion, v1::schema as v1};
 use futures::{
     SinkExt, StreamExt,
     channel::mpsc::{self},

src/agent-client-protocol-conductor/src/conductor.rs

@@ -10,7 +10,7 @@ use std::path::Path;
 use std::time::Instant;
 
 use agent_client_protocol::schema::SuccessorMessage;
-use agent_client_protocol::schema::v1::{
+use agent_client_protocol::v1::schema::{
     MessageMcpNotification, MessageMcpRequest, MessageMcpResponse,
 };
 use agent_client_protocol::{

src/agent-client-protocol-conductor/src/trace.rs

@@ -5,9 +5,9 @@
 //! 2. Multi-component chains: proxies receive `v1::InitializeProxyRequest`
 //! 3. Last component (agent) receives `InitializeRequest`
 
-use agent_client_protocol::schema::v1::{AgentCapabilities, InitializeRequest, InitializeResponse};
-use agent_client_protocol::schema::{ProtocolVersion, v1};
+use agent_client_protocol::v1::schema::{AgentCapabilities, InitializeRequest, InitializeResponse};
 use agent_client_protocol::{Agent, Client, Conductor, ConnectTo, DynConnectTo, Proxy};
+use agent_client_protocol::{schema::ProtocolVersion, v1::schema as v1};
 use agent_client_protocol_conductor::{ConductorImpl, ProxiesAndAgent};
 use agent_client_protocol_test::testy::v1::Testy;
 use std::sync::Arc;

src/agent-client-protocol-conductor/tests/initialization_sequence.rs

@@ -5,11 +5,11 @@ use std::sync::{
     atomic::{AtomicUsize, Ordering},
 };
 
-use agent_client_protocol::schema::{ProtocolVersion, v1, v2};
 use agent_client_protocol::{
     Agent, Builder, ByteStreams, Client, Conductor, ConnectTo, ConnectionTo, DynConnectTo, Error,
     JsonRpcRequest, JsonRpcResponse, Proxy, UntypedMessage,
 };
+use agent_client_protocol::{schema::ProtocolVersion, v1::schema as v1, v2::schema as v2};
 use agent_client_protocol_conductor::{
     ConductorImpl, InstantiateProxies, InstantiateProxiesAndAgent, InstantiatedChain,
     InstantiatedProxies, ProxiesAndAgent, SelectedInitializeRequest,

src/agent-client-protocol-conductor/tests/initialization_v2.rs

@@ -9,7 +9,7 @@ mod mcp_integration;
 
 use agent_client_protocol::Agent;
 use agent_client_protocol::schema::ProtocolVersion;
-use agent_client_protocol::schema::v1::{
+use agent_client_protocol::v1::schema::{
     ContentBlock, InitializeRequest, NewSessionRequest, PromptRequest, SessionNotification,
     TextContent,
 };