Skip to main content

ActiveSession

Struct ActiveSession 

Source
pub struct ActiveSession<Link>
where Link: HasPeer<Agent>,
{ /* private fields */ }
Available on crate feature unstable_protocol_v2 only.
Expand description

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§

Source§

impl<Link> ActiveSession<Link>
where Link: HasPeer<Agent>,

Source

pub fn session_id(&self) -> &SessionId

Access the session ID.

Source

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

Access the underlying connection.

Source

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.

The agent owns the inserted user message. Match it to this submission by the response’s message_id, never by content or arrival order: the content the agent reports for it can differ from prompt.

Source

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.

Self::cancel_active_work and Self::close drop the prompts the agent has received and not inserted, and the agent answers each with -32800. Cancelling the returned SentRequest sends $/cancel_request, which is best effort: an agent that honors it answers -32800 and does not insert the message, and otherwise the prompt is inserted as usual and the response carries its messageId. An inserted prompt cannot be withdrawn. Stop the work it started with Self::cancel_active_work.

A prompt sent this way has no idempotency key, so sending it again after a lost response can insert a second user message. Use Self::send_prompt_blocks_with_key for a prompt you may need to retry.

Source

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

Submit prompt content with an idempotency key and return its acceptance request.

The key identifies one submission. While the agent recognizes the key, it inserts at most one user message for it in a session and answers a retry with the messageId of the message it already inserted, without starting the work again. To retry, call this again with the same key and the same prompt. Each attempt is its own request.

A retry is not always safe. On a new connection, resume the session before you retry. A successful session/resume does not tell you whether the prompt was inserted or whether the agent kept the key, and a retry with a forgotten key is a new submission. If a duplicate would matter and you cannot rule one out, do not resend the prompt automatically. Tell the user that it might already have run and let them decide.

Create the key when the user submits the input, with v2::schema::IdempotencyKey::generate or another random value, and store it with the pending input. Use a new key for a new submission, including when the user sends the same text again on purpose. Do not derive the key from the content, and do not send the same key with a different prompt.

An error response means the message was not inserted and leaves the key unused, so the same prompt can be sent again with the same key. The agent recognizes a key for as long as it retains the message. For a message it does not retain, it recognizes the key while the session stays active on a connection.

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

Source

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 idle update is required when nothing was running. The agent sends that update before it starts new foreground work in the session, and it does not reject a prompt because cancellation is in progress. cancelled is only reported for work the client cancelled, through this notification or by closing the session, and for a child session whose parent cancelled its work. The client should immediately mark unfinished tool calls for the active work as cancelled.

Keep accepting updates after sending this notification. Updates for listed background work can arrive after the idle update. To stop a listed tool call or terminal, send tool_call/cancel or terminal/cancel while the item advertises capabilities.cancel.

The agent stops waiting for pending v2::schema::RequestPermissionRequests of the cancelled work and must cancel each of them with $/cancel_request. The agent decides which requests belong to that work, so do not answer every pending permission request when you send this notification. When $/cancel_request arrives for a permission request you have not answered, dismiss the prompt and answer 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.

§Errors

Returns an error if the cancellation notification cannot be encoded or queued. Success does not mean the agent has finished cancelling.

Source

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 options of a child session are read-only, so do not call this for one.

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.

Source

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). After the close response the agent sends no notifications or requests for the session. It still answers session/prompt requests that were pending.

A child session cannot be closed on its own. Close its root session instead.

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§

Source§

impl<Link> Clone for ActiveSession<Link>
where Link: HasPeer<Agent> + Clone,

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<Link> Debug for ActiveSession<Link>
where Link: HasPeer<Agent> + Debug,

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<Link> !RefUnwindSafe for ActiveSession<Link>

§

impl<Link> !UnwindSafe for ActiveSession<Link>

§

impl<Link> Forget for ActiveSession<Link>

§

impl<Link> Freeze for ActiveSession<Link>
where ConnectionTo<Link>: Freeze,

§

impl<Link> Move for ActiveSession<Link>

§

impl<Link> Send for ActiveSession<Link>
where ConnectionTo<Link>: Send,

§

impl<Link> Sync for ActiveSession<Link>
where ConnectionTo<Link>: Sync,

§

impl<Link> Unpin for ActiveSession<Link>
where ConnectionTo<Link>: Unpin,

§

impl<Link> UnsafeUnpin for ActiveSession<Link>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DynClone for T
where T: Clone,

Source§

fn __clone_box(&self, _: Private) -> *mut ()

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoMaybeUndefined<T> for T

Source§

fn into_maybe_undefined(self) -> MaybeUndefined<T>

Converts this value into a three-state builder argument.
Source§

impl<T> IntoOption<T> for T

Source§

fn into_option(self) -> Option<T>

Converts this value into an optional builder argument.
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more