Struct V2ConnectionTo 

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

Available on crate feature unstable_protocol_v2 only.

A protocol-v2 connection context.

Values of this type are supplied to callbacks registered on a V2Builder. It exposes the general connection operations that are valid for protocol v2 while keeping version-specific high-level helpers for other protocol versions out of the typed context. The generic JSON-RPC send methods remain intentionally schema-agnostic.

This is a thin, cheaply cloneable handle to the underlying JSON-RPC connection. It intentionally does not implement Deref to ConnectionTo.

Implementations

impl V2ConnectionTo<Agent>

pub fn send_initialize( &self, request: InitializeRequest, ) -> SentRequest<InitializeOutcome>

Send the client’s initialize request and report how the agent negotiated.

Unlike send_request, a v1-only agent’s valid v1 response resolves successfully as InitializeOutcome::LowerVersion with the agent’s typed response, so the caller can decide whether to fall back to a v1 client implementation. The connection stays uninitialized in that case; the SDK never converts it to v1.

The request still resolves with an error for errors returned by the agent (including the -32022 version mismatch), malformed responses, and transport failures.

let outcome = Client
    .v2()
    .connect_with(agent, async |cx| {
        let request = v2::InitializeRequest::new(
            ProtocolVersion::V2,
            v2::Implementation::new("example", "0.1.0"),
        );
        match cx.send_initialize(request).block_task().await? {
            InitializeOutcome::Initialized(_response) => {
                // Continue with v2 traffic.
                Ok(None)
            }
            InitializeOutcome::LowerVersion(mismatch) => Ok(Some(mismatch)),
            _ => Err(agent_client_protocol::util::internal_error("unexpected outcome")),
        }
    })
    .await?;
if let Some(mismatch) = outcome
    && let SelectedInitializeResponse::V1(_v1_response) = mismatch.response
{
    // Reconnect with a v1 client implementation.
}

impl<Counterpart: Role> V2ConnectionTo<Counterpart>

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, Context: ConnectionContext>( &self, builder: Builder<R, impl HandleDispatchFrom<R::Counterpart> + 'static, impl RunWithConnectionTo<R::Counterpart> + 'static, impl HandleConnectionClose<R::Counterpart> + 'static, Context>, transport: impl ConnectTo<R> + 'static, ) -> Result<Context::Connection<R::Counterpart>, Error>

Spawn a JSON-RPC connection in the background.

The returned connection context is selected by builder; spawning a V2Builder therefore returns another V2ConnectionTo.

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

pub fn send_proxied_message<Req: JsonRpcRequest<Response: Send>, Notif: JsonRpcNotification>( &self, message: Dispatch<Req, Notif>, ) -> 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>( &self, peer: Peer, message: Dispatch<Req, Notif>, ) -> 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>

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>

where Counterpart: HasPeer<Peer>,

Send an outgoing request to a specific peer.

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

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>

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.

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.

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 ConnectionTo. Prefer typed handlers on V2Builder when registration can happen before the connection starts.

Client.v2().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> V2ConnectionTo<Counterpart>

where Counterpart: HasPeer<Agent>,

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

Build a draft protocol v2 session/new request.

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

Build a draft protocol v2 session using the current working directory.

Returns an error if the current directory cannot be determined.

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

Build a draft protocol v2 session from an existing session/new request.

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

Available on crate feature unstable_session_fork only.

Build an unstable draft protocol v2 session/fork request.

This helper is available with the unstable_session_fork feature. Call V2ForkSessionBuilder::start_session to publish the request and obtain a command handle for the newly created fork.

pub fn fork_session_from( &self, request: ForkSessionRequest, ) -> V2ForkSessionBuilder<Counterpart>

Available on crate feature unstable_session_fork only.

Build an unstable draft protocol v2 session/fork request from an existing request.

This helper is available with the unstable_session_fork feature. Call V2ForkSessionBuilder::start_session to publish the request.

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

Build a draft protocol v2 session/resume request.

Use Self::resume_session_from to request history replay or set other optional resume parameters. Call V2ResumeSessionBuilder::start_session to publish the request.

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

Build a draft protocol v2 session/resume request from an existing request.

Register typed session update handlers before connecting. When the request asks for replay, the agent sends those updates before the v2::ResumeSessionResponse. Call V2ResumeSessionBuilder::start_session to publish the request.

Trait Implementations

impl<Counterpart: Clone + Role> Clone for V2ConnectionTo<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 V2ConnectionTo<Counterpart>

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

Formats the value using the given formatter.