agent_client_protocol/
v1.rs

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

agent_client_protocol/
v1.rs
