agent_client_protocol/
v2.rs

1//! The SDK API for draft ACP protocol v2.
2//!
3//! Start a v2 connection with [`Client.v2()`](crate::Client::v2),
4//! [`Agent.v2()`](crate::Agent::v2) or [`Proxy.v2()`](crate::Proxy::v2). The
5//! protocol v2 message types are in [`v2::schema`](schema).
6//!
7//! This module uses the same names as [`crate::v1`] for protocol v2's
8//! connection, builder, request handles and `schema`. The session APIs differ:
9//! [`ActiveSession`] here only sends commands, and the session's updates and
10//! the agent's requests arrive through typed handlers on the connection,
11//! while `v1::ActiveSession` reads them from its own stream. [`InitializeOutcome`]
12//! and, with `unstable_session_fork`, `ForkSessionBuilder` exist only here.
13//! v1's `LoadSessionBuilder`, `SessionMessage` and blocking states have no v2
14//! counterpart.
15//!
16//! Message types are not tied to a protocol version in the type system: a v2
17//! connection accepts any [`JsonRpcRequest`](crate::JsonRpcRequest), so
18//! sending a protocol v1 message through it compiles. Send the types from
19//! [`schema`].
20//!
21//! The request handles here are the crate-root handles with the [`V2`]
22//! protocol marker: `id()` returns a [`v2::schema::RequestId`].
23//!
24//! Requires the `unstable_protocol_v2` crate feature.
25//!
26//! ```no_run
27//! use agent_client_protocol::schema::ProtocolVersion;
28//! use agent_client_protocol::v2::schema::{Implementation, InitializeRequest};
29//! use agent_client_protocol::v2::{ConnectionTo, InitializeOutcome};
30//! use agent_client_protocol::{Agent, Client, ConnectTo};
31//!
32//! # async fn run(transport: impl ConnectTo<Client>) -> agent_client_protocol::Result<()> {
33//! Client
34//!     .v2()
35//!     .connect_with(transport, async |cx: ConnectionTo<Agent>| {
36//!         let request = InitializeRequest::new(
37//!             ProtocolVersion::V2,
38//!             Implementation::new("my-client", "0.1.0"),
39//!         );
40//!         let InitializeOutcome::Initialized(_response) =
41//!             cx.send_initialize(request).block_task().await?
42//!         else {
43//!             return Err(agent_client_protocol::Error::internal_error());
44//!         };
45//!         Ok(())
46//!     })
47//!     .await
48//! # }
49//! ```
50//!
51//! # Stability
52//!
53//! Everything in this module is unstable and may change in a minor release.
54//! Stabilizing protocol v2 only removes the `unstable_protocol_v2` gate. See
55//! [Stability](crate#stability) in the crate docs.
56//!
57//! [`v2::schema::RequestId`]: crate::v2::schema::RequestId
58
59use crate::{NullClose, NullHandler, UntypedMessage, V2, jsonrpc::run::NullRun};
60
61/// The protocol v2 message types: requests, responses, notifications and
62/// their supporting types, re-exported from the `agent-client-protocol-schema`
63/// crate's `v2` module.
64///
65/// This is the only path to them.
66/// `use agent_client_protocol::v2::{self, schema};` brings both the SDK
67/// types and the messages into scope under names that do not clash with the
68/// SDK's `v2` module. The version-neutral items, such as
69/// [`ProtocolVersion`](crate::schema::ProtocolVersion), are in
70/// [`crate::schema`].
71pub use agent_client_protocol_schema::v2 as schema;
72
73pub use crate::jsonrpc::InitializeOutcome;
74pub use crate::jsonrpc::v2_connection::ConnectionTo;
75#[cfg(feature = "unstable_session_fork")]
76pub use crate::session::v2::ForkSessionBuilder;
77pub use crate::session::v2::{ActiveSession, ResumeSessionBuilder, SessionBuilder, SessionSetup};
78
79/// A protocol v2 connection builder, returned by
80/// [`Client.v2()`](crate::Client::v2), [`Agent.v2()`](crate::Agent::v2) and
81/// [`Proxy.v2()`](crate::Proxy::v2).
82///
83/// Typed handlers receive v2 request handles and callbacks receive a
84/// [`ConnectionTo`].
85pub type Builder<Host, Handler = NullHandler, Runner = NullRun, Close = NullClose> =
86    crate::Builder<Host, Handler, Runner, Close, V2>;
87
88/// A v2 request's [`Responder`](crate::Responder): `id()` returns a
89/// [`v2::schema::RequestId`](crate::v2::schema::RequestId).
90pub type Responder<T = serde_json::Value> = crate::Responder<T, V2>;
91
92/// A v2 [`ResponseRouter`](crate::ResponseRouter): `id()` returns a
93/// [`v2::schema::RequestId`](crate::v2::schema::RequestId).
94pub type ResponseRouter<T = serde_json::Value> = crate::ResponseRouter<T, V2>;
95
96/// A request sent through a v2 [`ConnectionTo`]: the
97/// [`SentRequest`](crate::SentRequest) with a v2 request ID.
98pub type SentRequest<T> = crate::SentRequest<T, V2>;
99
100/// A request prepared through a v2 [`ConnectionTo`]: the
101/// [`PreparedRequest`](crate::PreparedRequest) with a v2 request ID.
102pub type PreparedRequest<T> = crate::PreparedRequest<T, V2>;
103
104/// A message received by a typed handler on a v2 [`Builder`]: the
105/// [`Dispatch`](crate::Dispatch) with v2 request handles.
106pub type Dispatch<Req = UntypedMessage, Notif = UntypedMessage> = crate::Dispatch<Req, Notif, V2>;
agent_client_protocol/v2.rs

agent_client_protocol/
v2.rs
