Struct SessionBuilder 

pub struct SessionBuilder<Counterpart, Run = NullRun>
where
    Counterpart: HasPeer<Agent>,
    Run: RunWithConnectionTo<Counterpart>,
{ /* private fields */ }

Available on crate feature unstable_protocol_v2 only.

Builder for a draft protocol v2 session/new request.

Protocol v2 acknowledges session/prompt independently from inbound session updates. Register typed v2::schema::UpdateSessionNotification and session request handlers on v2::Builder before connecting, then use Self::start_session to create the command-only ActiveSession handle or on_proxy_session_start to forward setup through a proxy.

With both the unstable_protocol_v2 and unstable_mcp_over_acp features, with_mcp_server attaches an MCP server to the new session.

Implementations

impl<Counterpart, Run> SessionBuilder<Counterpart, Run>

where Counterpart: HasPeer<Agent>, Run: RunWithConnectionTo<Counterpart>,

pub fn with_mcp_server<McpRun>( self, mcp_server: McpServer<Counterpart, McpRun>, ) -> Result<SessionBuilder<Counterpart, ChainRun<Run, McpRun>>, Error>

where McpRun: RunWithConnectionTo<Counterpart>,

Available on crate feature unstable_mcp_over_acp only.

Attach an MCP server to this new protocol v2 session.

This method is available when both unstable_protocol_v2 and unstable_mcp_over_acp are enabled. MCP routes are installed and their runner tasks receive an initial poll before session/new is published, allowing the agent to connect while handling session setup. A successful attachment remains active for the lifetime of the connection.

The declaration is an acp transport (McpServer::Acp). The agent must advertise session.mcp.acp, or a compatibility proxy such as McpOverAcpPolyfill must sit in front of it; otherwise a conforming agent rejects the setup request with -32602. This method does not check the agent’s capabilities.

pub fn start_session( self, ) -> SentRequest<SessionSetup<Counterpart, NewSessionResponse>, V2>

where Run: 'static,

Send session/new and return its independently consumable request.

The successful result contains both a cloneable command handle and the complete v2::schema::NewSessionResponse. Consume the returned request with SentRequest::block_task, SentRequest::on_receiving_result, or another explicit SentRequest completion mode.

Attached MCP routes are installed and their runner tasks begin executing before the request is published. A valid success response promotes them to the connection lifetime, independently from how this request handle is consumed. Setup errors clean up the pending attachment.

pub fn on_proxy_session_start<F, Fut>( self, responder: Responder<NewSessionResponse, V2>, op: F, ) -> Result<(), Error>

where Counterpart: HasPeer<Client>, Run: 'static, F: FnOnce(SessionSetup<Counterpart, NewSessionResponse>) -> Fut + Send + 'static, Fut: Future<Output = Result<(), Error>> + Send,

Start a protocol v2 session through a proxy and forward its response.

The downstream request is ordered and inherits cancellation from the upstream request. On success, this helper installs session routing before later inbound traffic is processed, forwards the complete response, and spawns op with an SessionSetup containing the command-only session handle plus the complete setup response. Inbound updates and interactive requests remain independent connection traffic.

The callback runs outside the ordered response barrier, so it may wait for later connection traffic without deadlocking the dispatch loop.

Trait Implementations

impl<Counterpart, Run> Debug for SessionBuilder<Counterpart, Run>

where Counterpart: HasPeer<Agent> + Debug, Run: RunWithConnectionTo<Counterpart> + Debug,

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

Formats the value using the given formatter.