1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
//! [](https://agentclientprotocol.com/)
//!
//! # Agent Client Protocol Schema
//!
//! Strongly-typed Rust definitions of the Agent Client Protocol (ACP) wire
//! format. ACP is a JSON-RPC based protocol that standardizes communication
//! between code editors (IDEs, text-editors, etc.) and coding agents
//! (programs that use generative AI to autonomously modify code).
//!
//! This crate is **only** the schema: the request, response, and
//! notification types, plus serde plumbing and optional JSON Schema generation.
//! For the runtime pieces (transport, connection setup, the `Agent` / `Client`
//! traits, etc.) use the higher-level [`agent-client-protocol`] crate, which
//! builds on top of these types.
//!
//! [`agent-client-protocol`]: https://crates.io/crates/agent-client-protocol
//!
//! ## What's in this crate
//!
//! - Versioned wire-format types for every ACP method: request, response, and
//! notification structs grouped by which side handles them, currently under
//! the [`v1`] module.
//! - JSON-RPC envelope and routing types: [`v1::JsonRpcMessage`],
//! [`rpc::JsonRpcBatch`], [`v1::Request`], [`v1::Response`],
//! [`v1::Notification`], [`v1::RequestId`], [`v1::Error`].
//! - Aggregated routing enums: [`v1::AgentRequest`], [`v1::AgentResponse`],
//! [`v1::AgentNotification`], and the matching client-side trio used by SDK
//! crates to dispatch incoming JSON-RPC messages.
//!
//! ## Parsing aggregate enums
//!
//! Do not deserialize an aggregate routing enum directly from a wire payload.
//! Its untagged `Deserialize` implementation selects by payload shape, not the
//! JSON-RPC method, and can silently select an unrelated variant.
//! Use the enum's `from_method_and_params` or `from_method_and_result` method
//! instead. Individual payload structs can be deserialized directly once the
//! method is known.
//!
//! These helpers only select and deserialize payloads. Use the SDK for
//! connections, request tracking, and JSON-RPC error handling.
//!
//! ```
//! use agent_client_protocol_schema::v1::ClientRequest;
//! use serde_json::json;
//!
//! let params = json!({"cwd": "/work", "mcpServers": []});
//! let request = ClientRequest::from_method_and_params("session/new", ¶ms)?;
//! assert!(matches!(request, ClientRequest::NewSessionRequest(_)));
//! # Ok::<(), agent_client_protocol_schema::MethodDispatchError>(())
//! ```
//!
//! ## Maps
//!
//! Maps keep the order of their keys, so the types hold them in an
//! [`IndexMap`]. The crate re-exports it, so building one needs no direct
//! `indexmap` dependency.
//!
//! ```
//! use agent_client_protocol_schema::IndexMap;
//! use agent_client_protocol_schema::v1::{OtherStateUpdate, StateUpdate};
//! use serde_json::json;
//!
//! let fields = IndexMap::from([
//! ("reason".to_string(), json!("rate_limited")),
//! ("attempt".to_string(), json!(2)),
//! ]);
//! let state = StateUpdate::Other(OtherStateUpdate::new("_paused", fields));
//! assert_eq!(
//! serde_json::to_string(&state)?,
//! r#"{"state":"_paused","reason":"rate_limited","attempt":2}"#
//! );
//! # Ok::<(), serde_json::Error>(())
//! ```
//!
//! ## Cargo features
//!
//! The `schemars` feature implements `schemars::JsonSchema` for the protocol
//! types. It is enabled by default to preserve the existing default API.
//! Consumers that only need serialization can disable default features to omit
//! the dependency and those trait implementations.
//!
//! The `uuid` feature adds `IdempotencyKey::generate` to the `v2` module, which
//! creates a key from a random UUID. It is off by default.
//!
//! ## Versioning
//!
//! Stable protocol types are exposed through explicit version modules. For
//! example, use `agent_client_protocol_schema::v1::SessionId` for ACP protocol
//! version 1 types.
//!
//! For the complete protocol specification and documentation, visit
//! <https://agentclientprotocol.com>.
// The `uuid` feature only adds API to the `v2` module. With `uuid` on and
// `unstable_protocol_v2` off, the dependency is enabled and nothing uses it.
// That combination is valid, so reference the crate to say so. Remove this
// once the `v2` module is no longer behind `unstable_protocol_v2`.
use uuid as _;
pub use MethodDispatchError;
pub use IndexMap;
pub use ;
pub use *;