Skip to content

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

Merged
benbrandt merged 1 commit into
mainfrom
single-schema-path
Nov 2, 2026
Merged

benbrandt merged 1 commit into
mainfrom
single-schema-path

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Each protocol version's message types were reachable at two paths: agent_client_protocol::schema::v1::X and agent_client_protocol::v1::schema::X (same for v2). This PR keeps only the version modules. It was written as a stacked PR on #480; #480 has merged, so it targets main.

Changes

  • v1::schema is now pub use agent_client_protocol_schema::v1 as schema;, and v2::schema is the same behind unstable_protocol_v2.
  • schema::v1 and schema::v2 are removed. The root schema module now holds only the version-neutral items: ProtocolVersion, MaybeUndefined, IntoOption, IntoMaybeUndefined and SuccessorMessage. It keeps its name. The items in it are schema items, and renaming it would break every schema::ProtocolVersion import for no gain.
  • Every crate, test, example, cookbook page, doctest and book page now uses 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 small.
    • Rustdoc links that showed paths that don't exist (such as v2::NewSessionResponse in session/v2.rs) now show v2::schema::....
  • The impl_proxy_jsonrpc! macro now reaches the proxy types through $crate::$ns::schema. The derive crate emits no schema paths.
  • Docs:
    • md/migration-v5.md gets a rename table (schema::v1::X -> v1::schema::X, same for v2). The text that presented both paths is gone, and the "After" examples use the new paths.
    • The stability guidance in lib.rs and the README, plus md/design.md, md/protocol.md, md/protocol-v2.md and the "Adding a protocol version" checklist in md/versioning.md are updated.
  • No compatibility aliases.

Left at the old path on purpose

  • "Before" (3.6) code and text in md/migration-v5.md.
  • The historical guides md/migration_v2.0.md and md/migration_v0.11.x.md, which describe the APIs of those releases.

Checks

These pass:

  • cargo fmt --check
  • both clippy runs
  • cargo build --workspace --bins --examples --all-features --locked
  • cargo hack check --feature-powerset --depth 2
  • cargo test --workspace --all-features
  • cargo test --no-default-features
  • the rmcp_3 tests
  • the nightly docs.rs build with -D warnings
  • mdbook build
  • typos

agent-client-protocol-derive --lib aborts under the local kache runner, which also happens on main.

…:schema / v2::schema

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>
@benbrandt
benbrandt merged commit 75e00be into main Nov 2, 2026
13 checks passed
@benbrandt
benbrandt deleted the single-schema-path branch November 2, 2026 08:15
@acp-release-bot acp-release-bot Bot mentioned this pull request Nov 1, 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