Struct ActiveSession 

pub struct ActiveSession<'runner, Link>
where
    Link: HasPeer<Agent>,
{ /* private fields */ }

Stable protocol v1 active session that lets you send prompts and receive updates.

The session owns a stream of SessionMessages: the requests and notifications the agent sends for this session, and the responses to prompts sent with send_prompt or send_prompt_blocks.

This handle covers prompting and reading the stream only. It has no helpers for session/cancel, session/set_mode, session/set_config_option, session/close or session/fork. Send those messages through connection with session_id, for example session.connection().send_notification_to(Agent, CancelNotification::new(session.session_id().clone())).

The 'runner lifetime represents the span during which session support runners (such as MCP servers) are active. When created via SessionBuilder::start_session, this is 'static because the runners are spawned into background tasks. When created via SessionBuilder::run_until, this is tied to the closure scope, preventing Self::proxy_remaining_messages from being called (since the runners would stop when the closure returns).

Implementations

impl<Link> ActiveSession<'_, Link>

where Link: HasPeer<Agent>,

pub fn session_id(&self) -> &SessionId

Access the session ID.

pub fn connection(&self) -> &ConnectionTo<Link>

Access the underlying connection context used to communicate with the agent.

pub fn send_prompt(&mut self, prompt: impl ToString) -> Result<(), Error>

Send a text prompt to the agent.

Read the agent’s output with read_update or read_to_string. The session/prompt response, or the error the agent answered with, arrives on the same stream as SessionMessage::PromptResponse.

pub fn send_prompt_blocks( &mut self, prompt: Vec<ContentBlock>, ) -> Result<(), Error>

Send a prompt made of arbitrary content blocks to the agent.

Content other than text and resource links needs the matching promptCapabilities entry from the agent’s initialize response. Like send_prompt, the response arrives on the update stream as SessionMessage::PromptResponse.

pub async fn read_update(&mut self) -> Result<SessionMessage, Error>

Read the next item on the session’s update stream: a message the agent sent for this session, or the response to a prompt.

pub async fn read_to_string(&mut self) -> Result<String, Error>

Read updates until the next prompt response and return the text of the agent’s message chunks.

Ignores non-text updates. Requests from the agent that reach the session, such as session/request_permission, are answered with a method not found error (-32601). Use read_update instead to answer them yourself. If the agent answers the prompt with an error, this returns that error.

impl<Link> ActiveSession<'static, Link>

where Link: HasPeer<Agent>,

pub fn proxy_remaining_messages(self) -> Result<(), Error>

where Link: HasPeer<Client>,

Proxy all remaining messages for this session between client and agent.

Use this when you want to inject MCP servers into a session but don’t need to actively interact with it after setup. The session messages will be proxied between client and agent automatically.

This consumes the ActiveSession since you’re giving up active control.

This method is only available on ActiveSession<'static, _> (from SessionBuilder::start_session) because it requires the session’s runners to outlive the method call.

Message Ordering Guarantees

This method ensures proper handoff from active session mode to proxy mode without losing or reordering messages:

1. Stop the session handler - Deactivate the handler that routes messages to update_rx. After this, no new messages will be queued.
2. Close the channel - Drop update_tx so we can detect when the channel is fully drained.
3. Drain queued messages - Forward any messages that were already queued in update_rx to the client, preserving order.
4. Install proxy handler - Now that all queued messages are forwarded, install the proxy handler to handle future messages.
5. Remove the session handler - Drop its registration.

This sequence prevents the race condition where messages could be delivered out of order or lost during the transition. Messages that arrive between steps 1 and 4 wait for the proxy handler. The deactivated handler stays registered until the proxy handler is installed, so a request in that window waits too instead of being rejected.

Trait Implementations

impl<'runner, Link> Debug for ActiveSession<'runner, Link>

where Link: HasPeer<Agent> + Debug,

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

Formats the value using the given formatter.