Struct ConnectionTo 

pub struct ConnectionTo<Counterpart: Role> { /* private fields */ }

A protocol-v1 connection context.

Values of this type are supplied to callbacks registered on a v1::Builder. It exposes the general connection operations, typed for protocol v1, and the v1 session helpers such as build_session. Requests sent through it return v1::SentRequest and v1::PreparedRequest, whose id() is a v1::schema::RequestId. The generic JSON-RPC send methods remain schema-agnostic.

This is a thin, cheaply cloneable handle to the underlying JSON-RPC connection. It intentionally does not implement Deref to the version-neutral ConnectionTo; convert explicitly with into_raw and ConnectionTo::into_protocol.

Implementations

impl<Counterpart: Role> ConnectionTo<Counterpart>

pub fn into_raw(self) -> RawConnectionTo<Counterpart>

The underlying version-neutral connection.

Requests sent through it return Raw handles. Convert back with ConnectionTo::into_protocol.

pub fn counterpart(&self) -> Counterpart

Return the counterpart role this connection is talking to.

pub async fn incoming_closed(&self)

Wait until the incoming transport reaches clean EOF.

pub fn is_incoming_closed(&self) -> bool

Return whether clean incoming-EOF processing has completed.

pub async fn terminated(&self) -> ConnectionTermination

Wait until the connection driver has terminated, for any reason.

See ConnectionTo::terminated.

pub fn termination(&self) -> Option<ConnectionTermination>

Return the termination reason if the connection driver has terminated.

pub fn spawn( &self, task: impl IntoFuture<Output = Result<(), Error>, IntoFuture: Send + 'static>, ) -> Result<(), Error>

Spawn a task that runs for as long as the JSON-RPC connection is served.

pub fn spawn_connection<R: Role, P: Protocol>( &self, builder: Builder<R, impl HandleDispatchFrom<R::Counterpart> + 'static, impl RunWithConnectionTo<R::Counterpart> + 'static, impl HandleConnectionClose<R::Counterpart> + 'static, P>, transport: impl ConnectTo<R> + 'static, ) -> Result<P::Connection<R::Counterpart>, Error>

Spawn a JSON-RPC connection in the background.

The returned connection context is selected by builder; spawning a v1::Builder therefore returns another v1::ConnectionTo.

let child: ConnectionTo<Agent> =
    connection.spawn_connection(Client.v1(), transport)?;

pub fn send_proxied_message<Req: JsonRpcRequest<Response: Send>, Notif: JsonRpcNotification, Q: Protocol>( &self, message: Dispatch<Req, Notif, Q>, ) -> Result<(), Error>

where Counterpart: HasPeer<Counterpart>,

Send a request or notification and forward its response appropriately.

pub fn send_proxied_message_to<Peer: Role, Req: JsonRpcRequest<Response: Send>, Notif: JsonRpcNotification, Q: Protocol>( &self, peer: Peer, message: Dispatch<Req, Notif, Q>, ) -> Result<(), Error>

where Counterpart: HasPeer<Peer>,

Send a request or notification to a specific peer and forward its response appropriately.

pub fn send_request<Req: JsonRpcRequest>( &self, request: Req, ) -> SentRequest<Req::Response, V1>

where Counterpart: HasPeer<Counterpart>,

Send an outgoing request to the default counterpart peer.

pub fn send_request_to<Peer: Role, Req: JsonRpcRequest>( &self, peer: Peer, request: Req, ) -> SentRequest<Req::Response, V1>

where Counterpart: HasPeer<Peer>,

Send an outgoing request to a specific peer.

pub fn prepare_request<Req: JsonRpcRequest>( &self, request: Req, ) -> PreparedRequest<Req::Response, V1>

where Counterpart: HasPeer<Counterpart>,

Prepare a request without sending it until response handling is selected.

See ConnectionTo::prepare_request for publication and ordering semantics.

pub fn prepare_request_to<Peer: Role, Req: JsonRpcRequest>( &self, peer: Peer, request: Req, ) -> PreparedRequest<Req::Response, V1>

where Counterpart: HasPeer<Peer>,

Prepare a request to a specific peer without sending it.

See ConnectionTo::prepare_request_to for publication and ordering semantics.

pub fn send_notification<N: JsonRpcNotification>( &self, notification: N, ) -> Result<(), Error>

where Counterpart: HasPeer<Counterpart>,

Send an outgoing notification to the default counterpart peer.

pub fn send_notification_to<Peer: Role, N: JsonRpcNotification>( &self, peer: Peer, notification: N, ) -> Result<(), Error>

where Counterpart: HasPeer<Peer>,

Send an outgoing notification to a specific peer.

pub fn send_cancel_request( &self, request_id: impl Into<RequestId>, ) -> Result<(), Error>

where Counterpart: HasPeer<Counterpart>,

Send a $/cancel_request notification to the default counterpart peer.

Prefer SentRequest::cancel when you have the request handle. request_id is a v1 request ID, such as the id of a request sent through this connection. The raw ConnectionTo::send_cancel_request takes any RawJsonRpcId.

pub fn send_cancel_request_to<Peer: Role>( &self, peer: Peer, request_id: impl Into<RequestId>, ) -> Result<(), Error>

where Counterpart: HasPeer<Peer>,

Send a $/cancel_request notification to a specific peer.

The notification is always sent plain, never wrapped in proxy/successor, as the raw ConnectionTo::send_cancel_request_to describes. See send_cancel_request.

pub fn add_dynamic_handler( &self, handler: impl HandleDispatchFrom<Counterpart> + 'static, ) -> Result<DynamicHandlerGuard<Counterpart>, Error>

Register a low-level dynamic message handler.

Dynamic handlers use the version-neutral HandleDispatchFrom trait, so their callback receives the underlying version-neutral ConnectionTo. Prefer typed handlers on v1::Builder when registration can happen before the connection starts.

Client.v1().connect_with(transport, async |connection| {
    let guard: DynamicHandlerGuard<Agent> =
        connection.add_dynamic_handler(NullHandler)?;

    // Keep `guard` alive for as long as the modal handler is needed.
    drop(guard);
    Ok(())
}).await

impl<Counterpart> ConnectionTo<Counterpart>

where Counterpart: HasPeer<Agent> + Role,

pub fn build_session( &self, cwd: impl AsRef<Path>, ) -> SessionBuilder<Counterpart, NullRun>

Stable protocol v1 session builder for a new session request.

With unstable_protocol_v2, a Client.v2() callback receives a v2::ConnectionTo with its own v2 build_session helper.

cwd must be an absolute path: ACP requires one, and the SDK sends it without checking.

pub fn build_session_cwd( &self, ) -> Result<SessionBuilder<Counterpart, NullRun>, Error>

Stable protocol v1 session builder using the current working directory.

This is a convenience wrapper around build_session that uses std::env::current_dir to get the working directory.

Returns an error if the current directory cannot be determined.

pub fn build_session_from( &self, request: NewSessionRequest, ) -> SessionBuilder<Counterpart, NullRun>

Stable protocol v1 session builder starting from an existing request.

Use this when you’ve intercepted a session.new request and want to modify it (e.g., inject MCP servers) before forwarding.

pub fn load_session( &self, session_id: impl Into<SessionId>, cwd: impl AsRef<Path>, ) -> LoadSessionBuilder<Counterpart>

Stable protocol v1 session builder that loads an existing session.

The returned builder installs session routing before publishing session/load, so replay notifications sent before the response are available through the restored ActiveSession.

Call this only when the initialization response advertises agentCapabilities.loadSession.

cwd must be an absolute path: ACP requires one, and the SDK sends it without checking.

pub fn load_session_from( &self, request: LoadSessionRequest, ) -> LoadSessionBuilder<Counterpart>

Stable protocol v1 session builder from an existing session/load request.

Use this to send a typed request assembled or intercepted elsewhere without rebuilding it.

pub fn resume_session( &self, session_id: impl Into<SessionId>, cwd: impl AsRef<Path>, ) -> ResumeSessionBuilder<Counterpart>

Stable protocol v1 session builder that resumes an existing session.

This is the session/resume counterpart of load_session, but continues without replaying conversation history. Call this only when the initialization response advertises agentCapabilities.sessionCapabilities.resume.

cwd must be an absolute path: ACP requires one, and the SDK sends it without checking.

pub fn resume_session_from( &self, request: ResumeSessionRequest, ) -> ResumeSessionBuilder<Counterpart>

Stable protocol v1 session builder from an existing session/resume request.

Use this to send a typed request assembled or intercepted elsewhere without rebuilding it.

Trait Implementations

impl<Counterpart: Clone + Role> Clone for ConnectionTo<Counterpart>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Counterpart: Debug + Role> Debug for ConnectionTo<Counterpart>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Counterpart: Role> From<ConnectionTo<Counterpart>> for ConnectionTo<Counterpart>

fn from(connection: ConnectionTo<Counterpart>) -> Self

The same as ConnectionTo::into_raw. Generic code over Protocol uses it to turn a P::Connection<Counterpart> back into the version-neutral connection.