Struct ActiveSession 

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

Active session struct that lets you send prompts and receive updates.

The 'responder lifetime represents the span during which responders (e.g., MCP server handlers) are active. When created via SessionBuilder::start_session, this is 'static because responders 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 responders would die 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 modes(&self) -> &Option<SessionModeState>

Access modes available in this session.

pub fn meta(&self) -> &Option<Map<String, Value>>

Access meta data from session response.

pub fn response(&self) -> NewSessionResponse

Build a NewSessionResponse from the session information.

Useful when you need to forward the session response to a client after doing some processing.

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 prompt to the agent. You can then read messages sent in response.

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

Read an update from the agent in response to the prompt.

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

Read all updates until the end of the turn and create a string. Ignores non-text updates.

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 responders 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 - Drop the registration 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.

This sequence prevents the race condition where messages could be delivered out of order or lost during the transition.

Trait Implementations

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

where Link: HasPeer<Agent> + Debug,

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

Formats the value using the given formatter.