Struct ActiveSession 

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

Available on crate feature unstable_protocol_v2 only.

Cloneable command handle for a draft protocol v2 session.

Inbound protocol traffic is intentionally not owned by this value. Receive authoritative v2::schema::UpdateSessionNotification values and interactive requests such as v2::schema::RequestPermissionRequest through typed handlers installed on v2::Builder.

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.

pub fn send_prompt( &self, prompt: impl ToString, ) -> SentRequest<PromptResponse, V2>

Submit a text prompt and return its independent acceptance request.

A successful response only acknowledges that the agent accepted the prompt. The accepted user message, output, state changes, and completion arrive independently through v2::schema::UpdateSessionNotification.

pub fn send_prompt_blocks( &self, prompt: Vec<ContentBlock>, ) -> SentRequest<PromptResponse, V2>

Submit arbitrary prompt content and return its acceptance request.

prompt must not be empty; an agent may reject [] with -32602.

The SDK does not track foreground state or gate prompt submission locally. A prompt may be sent in any state, including while foreground work is active: the agent either inserts it right away or holds it and inserts held prompts in received order, and it must not reject a prompt only because work is active. A held prompt’s response stays pending until it is inserted. Cancel the returned SentRequest to withdraw a held prompt; Self::cancel_active_work and Self::close also answer prompts that were not yet inserted with -32800.

pub fn cancel_active_work(&self) -> Result<(), Error>

Ask the agent to cancel the session’s current foreground work.

This is independent from cancelling a prompt’s SentRequest. session/cancel covers the session’s foreground work and prompts received before it that the agent has not yet inserted; those prompt requests fail with -32800 (request cancelled). A prompt sent after this notification is not cancelled by it. A prompt whose user message was already inserted still succeeds with its messageId. Work in the latest background list is not covered and keeps running.

If foreground work was active, cancellation completes when the agent reports an idle state update with v2::schema::StopReason::Cancelled; no completion update is required when nothing was running. cancelled is only reported for work the client cancelled, through this notification or by closing the session. The client should immediately mark unfinished tool calls for the active work as cancelled.

The agent stops waiting for pending v2::schema::RequestPermissionRequests of the cancelled work and should cancel each of them with $/cancel_request. Answer a cancelled permission request with the cancelled outcome. A client may also answer a request it knows belongs to the cancelled work that way without waiting for $/cancel_request.

See https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#cancellation.

pub fn set_config_option( &self, config_id: impl Into<SessionConfigId>, value: impl Into<SessionConfigOptionValue>, ) -> SentRequest<SetSessionConfigOptionResponse, V2>

Set a session configuration option.

Only send a config_id the agent advertised for this session, with a value from that option. The agent rejects an unknown config_id or an invalid value with -32602 and leaves the configuration unchanged.

The response contains the complete option set as of the response and may report a different currentValue than requested; currentValue is always the value the agent is using. Apply responses and config_option_update notifications in the order received, each replacing the whole list. A duplicate config_option_update notification for the same change may arrive before the response. The response is not cached on this command handle.

See https://agentclientprotocol.com/protocol/v2/session-config-options.

pub fn close(&self) -> SentRequest<CloseSessionResponse, V2>

Close the remote session and release its resources.

The agent cancels the session’s ongoing work as if session/cancel had been sent. When that cancels active foreground work, the agent sends the work’s final updates and an idle state update with stop reason cancelled before it responds to session/close. A pending prompt whose user message closing kept from being inserted fails with -32800 (request cancelled); one already inserted still succeeds with its message ID. Prompt responses need not precede the close response. Before it responds, the agent cancels every pending permission request and elicitation in the session with $/cancel_request.

Existing clones of this local command handle are not invalidated, but the session is no longer active: the agent rejects later commands for it with -32002 (resource not found).

Closing is idempotent. An agent should answer a close of an unknown or already-closed session with success, and an older agent may answer -32002 instead, so this helper resolves a -32002 response as a successful, empty v2::schema::CloseSessionResponse. Other errors are returned unchanged.

See https://agentclientprotocol.com/protocol/v2/session-setup#closing-active-sessions.

Trait Implementations

impl<Link> Clone for ActiveSession<Link>

where Link: HasPeer<Agent> + Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Link> Debug for ActiveSession<Link>

where Link: HasPeer<Agent> + Debug,

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

Formats the value using the given formatter.