agent-client-protocol 5.0.0

Core protocol types and traits for the Agent Client Protocol
Documentation 
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

//! The SDK API for ACP protocol v1.
//!
//! Start a v1 connection with [`Client.v1()`](crate::Client::v1),
//! [`Agent.v1()`](crate::Agent::v1) or [`Proxy.v1()`](crate::Proxy::v1). The
//! protocol v1 message types are in [`v1::schema`](schema).
//!
//! With the `unstable_protocol_v2` feature, `agent_client_protocol::v2` uses
//! the same names for protocol v2's connection, builder, request handles and
//! `schema`. The session APIs differ: [`ActiveSession`] here reads the
//! session's updates from its own stream ([`read_update`] and
//! [`read_to_string`]), while `v2::ActiveSession` only sends commands and the
//! updates arrive through typed handlers on the connection. [`LoadSessionBuilder`],
//! [`SessionMessage`] and the [`Blocking`] / [`NonBlocking`] states exist only
//! here.
//!
//! Message types are not tied to a protocol version in the type system: a v1
//! connection accepts any [`JsonRpcRequest`](crate::JsonRpcRequest), so
//! sending a protocol v2 message through it compiles. Send the types from
//! [`schema`].
//!
//! The request handles here are the crate-root handles with the [`V1`]
//! protocol marker: `id()` returns a [`v1::schema::RequestId`].
//!
//! ```no_run
//! use agent_client_protocol::schema::ProtocolVersion;
//! use agent_client_protocol::v1::{ConnectionTo, schema::InitializeRequest};
//! use agent_client_protocol::{Agent, Client, ConnectTo};
//!
//! # async fn run(transport: impl ConnectTo<Client>) -> agent_client_protocol::Result<()> {
//! Client
//!     .v1()
//!     .connect_with(transport, async |cx: ConnectionTo<Agent>| {
//!         cx.send_request(InitializeRequest::new(ProtocolVersion::V1))
//!             .block_task()
//!             .await?;
//!         Ok(())
//!     })
//!     .await
//! # }
//! ```
//!
//! [`v1::schema::RequestId`]: crate::v1::schema::RequestId
//! [`read_update`]: ActiveSession::read_update
//! [`read_to_string`]: ActiveSession::read_to_string

use crate::{NullClose, NullHandler, UntypedMessage, V1, jsonrpc::run::NullRun};

/// The protocol v1 message types: requests, responses, notifications and
/// their supporting types, re-exported from the `agent-client-protocol-schema`
/// crate's `v1` module.
///
/// This is the only path to them.
/// `use agent_client_protocol::v1::{self, schema};` brings both the SDK
/// types and the messages into scope under names that do not clash with the
/// SDK's `v1` module. The version-neutral items, such as
/// [`ProtocolVersion`](crate::schema::ProtocolVersion), are in
/// [`crate::schema`].
pub use agent_client_protocol_schema::v1 as schema;

pub use crate::jsonrpc::v1_connection::ConnectionTo;

pub use crate::session::{
    ActiveSession, Blocking, LoadSessionBuilder, NonBlocking, ResumeSessionBuilder,
    SessionBlockState, SessionBuilder, SessionMessage, SessionSetup,
};

/// A protocol v1 connection builder, returned by
/// [`Client.v1()`](crate::Client::v1), [`Agent.v1()`](crate::Agent::v1) and
/// [`Proxy.v1()`](crate::Proxy::v1).
///
/// Typed handlers receive v1 request handles and callbacks receive a
/// [`ConnectionTo`].
pub type Builder<Host, Handler = NullHandler, Runner = NullRun, Close = NullClose> =
    crate::Builder<Host, Handler, Runner, Close, V1>;

/// A v1 request's [`Responder`](crate::Responder): `id()` returns a
/// [`v1::schema::RequestId`](crate::v1::schema::RequestId).
pub type Responder<T = serde_json::Value> = crate::Responder<T, V1>;

/// A v1 [`ResponseRouter`](crate::ResponseRouter): `id()` returns a
/// [`v1::schema::RequestId`](crate::v1::schema::RequestId).
pub type ResponseRouter<T = serde_json::Value> = crate::ResponseRouter<T, V1>;

/// A request sent through a v1 [`ConnectionTo`]: the
/// [`SentRequest`](crate::SentRequest) with a v1 request ID.
pub type SentRequest<T> = crate::SentRequest<T, V1>;

/// A request prepared through a v1 [`ConnectionTo`]: the
/// [`PreparedRequest`](crate::PreparedRequest) with a v1 request ID.
pub type PreparedRequest<T> = crate::PreparedRequest<T, V1>;

/// A message received by a typed handler on a v1 [`Builder`]: the
/// [`Dispatch`](crate::Dispatch) with v1 request handles.
pub type Dispatch<Req = UntypedMessage, Notif = UntypedMessage> = crate::Dispatch<Req, Notif, V1>;