Struct AgentSessionHandle 

pub struct AgentSessionHandle { /* private fields */ }

Lightweight handle for programmatic embedding.

This wraps AgentSession and exposes high-level request methods while still allowing access to the underlying session when needed.

Session-level event listeners can be registered via Self::subscribe or by providing callbacks on SessionOptions. These fire for every prompt, in addition to the per-prompt on_event callback.

Implementations

impl AgentSessionHandle

pub const fn from_session_with_listeners( session: AgentSession, listeners: EventListeners, ) -> Self

Create a handle from a pre-built AgentSession with custom listeners.

This is useful for tests and advanced embedding scenarios where the full create_agent_session() flow is not needed.

pub async fn prompt( &mut self, input: impl Into<String>, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<AssistantMessage>

Send one user prompt through the agent loop.

The on_event callback receives events for this prompt only. Session-level listeners registered via Self::subscribe or SessionOptions callbacks also fire for every event.

pub async fn prompt_with_abort( &mut self, input: impl Into<String>, abort_signal: AbortSignal, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<AssistantMessage>

Send one user prompt through the agent loop with an explicit abort signal.

pub async fn continue_turn( &mut self, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<AssistantMessage>

Continue the current agent loop without adding a new user prompt.

This is useful for retry/continuation flows where session history or injected messages should drive the next turn without synthesizing a new user message through Self::prompt.

pub async fn continue_turn_with_abort( &mut self, abort_signal: AbortSignal, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<AssistantMessage>

Continue the current agent loop with an explicit abort signal.

pub fn new_abort_handle() -> (AbortHandle, AbortSignal)

Create a new abort handle/signal pair for prompt cancellation.

pub fn subscribe( &self, listener: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> SubscriptionId

Register a session-level event listener.

The listener fires for every AgentEvent across all future prompts until removed via Self::unsubscribe.

Returns a SubscriptionId that can be used to remove the listener.

pub fn unsubscribe(&self, id: SubscriptionId) -> bool

Remove a previously registered event listener.

Returns true if the listener was found and removed.

pub const fn listeners(&self) -> &EventListeners

Access the session-level event listeners.

pub const fn listeners_mut(&mut self) -> &mut EventListeners

Mutable access to session-level event listeners.

Allows updating typed hooks (on_tool_start, on_tool_end, on_stream_event) after session creation.

pub const fn has_extensions(&self) -> bool

Whether this session has extensions loaded.

pub fn extension_manager(&self) -> Option<&ExtensionManager>

Return a reference to the extension manager (if extensions are loaded).

pub const fn extension_region(&self) -> Option<&ExtensionRegion>

Return a reference to the extension region (if extensions are loaded).

The region wraps the extension manager with lifecycle management.

pub fn model(&self) -> (String, String)

Return the active provider/model pair.

pub async fn set_model(&mut self, provider: &str, model_id: &str) -> Result<()>

Update the active provider/model pair and persist it to session metadata.

pub const fn thinking_level(&self) -> Option<ThinkingLevel>

Return the currently configured thinking level.

pub const fn thinking(&self) -> Option<ThinkingLevel>

Alias for thinking level access, matching the SDK naming style.

pub async fn set_thinking_level(&mut self, level: ThinkingLevel) -> Result<()>

Update thinking level and persist it to session metadata.

Delegates to AgentSession::set_thinking_level so the runtime reconfiguration logic (clamping, history dedupe, persistence) lives in one place and stays consistent across the SDK handle and the ACP transport, which both need it.

pub async fn set_session_name(&mut self, name: impl Into<String>) -> Result<()>

Update the persisted session display name.

Records a SessionInfo entry with the new name on the leaf path and flushes session metadata to disk, mirroring how the in-process rename path works for runtime CLIs that need to retitle a live session.

pub const fn max_tokens(&self) -> Option<u32>

Read the per-prompt max_tokens cap currently configured on the session’s stream options.

None means the provider’s default applies (e.g. 4096 for the openai-compat provider), which can truncate generations that emit large tool-call arguments. Embedders carrying tool-heavy traffic should raise this via Self::set_max_tokens.

pub const fn set_max_tokens(&mut self, max_tokens: Option<u32>)

Override the per-prompt max_tokens cap.

Persists for the lifetime of the in-process handle only; not written to session metadata. Pass None to fall back to the provider’s default cap.

pub async fn messages(&self) -> Result<Vec<Message>>

Return all model messages for the current session path.

pub async fn state(&self) -> Result<AgentSessionState>

Return a lightweight state snapshot.

pub async fn compact( &mut self, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<()>

Trigger an immediate compaction pass (if compaction is enabled).

pub const fn session(&self) -> &AgentSession

Access the underlying AgentSession.

pub const fn session_mut(&mut self) -> &mut AgentSession

Mutable access to the underlying AgentSession.

pub fn into_inner(self) -> AgentSession

Consume the handle and return the inner AgentSession.