Struct AgentSession 

pub struct AgentSession {
    pub manager: Mutex<SessionManager>,
    pub registry: Arc<Registry>,
    /* private fields */
}

Fields

manager: Mutex<SessionManager>

Lock order: take manager before phase, never the other way; take context_file before manager.

registry: Arc<Registry>

Implementations

impl AgentSession

pub fn new( manager: SessionManager, tools: Vec<DynTool>, registry: impl Into<Arc<Registry>>, settings: Settings, system_prompt: String, model: Model, thinking: ThinkingLevel, api_key_override: Option<(String, String)>, sink: SessionEventSink, ) -> Arc<Self>

pub fn new_with_subagents_allowed( manager: SessionManager, tools: Vec<DynTool>, registry: impl Into<Arc<Registry>>, settings: Settings, system_prompt: String, model: Model, thinking: ThinkingLevel, api_key_override: Option<(String, String)>, sink: SessionEventSink, subagents_allowed: bool, ) -> Arc<Self>

pub fn set_stream_fn(&self, stream_fn: Option<StreamFn>)

Replace the provider streaming function used by every later request.

Pass None to restore the real provider. Child sessions created after this call inherit the override so a scripted fake model also serves subagents and compaction.

pub fn model(&self) -> Model

pub fn advisor(&self) -> Option<(Model, ThinkingLevel)>

The model and thinking level the advisor tool asks, if one is set.

pub fn set_advisor(&self, advisor: Option<(Model, ThinkingLevel)>)

Set or clear the advisor for the next request. A child session or a session without tools has no advisor, so this does nothing there. Saving the choice is the caller’s job (Settings::advisor_model).

pub fn resolve_advisor( registry: &Registry, pattern: &str, ) -> Option<(Model, ThinkingLevel)>

The advisor for a pattern such as anthropic/claude-opus-5-5 or openai/gpt-5.2:xhigh. Without a thinking suffix the advisor thinks at high, or the nearest level the model supports.

pub fn advisor_max_uses(&self) -> u32

Advisor calls allowed for each user prompt.

pub fn thinking_level(&self) -> ThinkingLevel

pub fn fast_mode(&self) -> bool

pub fn set_fast_mode(&self, enabled: bool)

pub fn totals(&self) -> Usage

pub fn run_phase(&self) -> RunPhase

pub fn is_running(&self) -> bool

pub async fn wait_idle(&self)

Resolve once no run or manual compaction is active.

pub fn settings(&self) -> Settings

pub fn update_settings(&self, settings: Settings)

pub fn reload_runtime( &self, settings: Settings, system_prompt: String, tools: Vec<DynTool>, )

Replace resources used by the next model request.

pub fn install_session_tool(&self, tool: DynTool)

Add or replace one tool for this process without changing saved tool configuration.

pub fn remove_session_tool(&self, name: &str) -> bool

Remove one process-only tool. Return true when a tool was removed.

pub fn workflows_enabled(&self) -> bool

Dynamic workflows are built on child agents, so they need subagents on as well as their own setting.

pub fn prompt_mode_for(&self, text: &str) -> PromptMode

Select workflow mode from one submitted user prompt.

pub fn workflows(&self) -> Option<Arc<WorkflowRuntime>>

pub fn iterative_jobs(&self) -> Option<Arc<IterativeRuntime>>

pub fn set_workflow_approver(&self, approver: WorkflowApprover)

Install the callback that asks the user to approve a run.

pub fn system_context(&self) -> (String, Vec<(String, String)>)

The system prompt and each active tool’s name and description.

pub fn available_tool_names(&self) -> Vec<String>

pub fn new_session(&self) -> Result<()>

Switch the active session without appending synthetic history. Refuse replacement while a prompt or compaction is active. Start a sibling session after admission, preserving the storage mode.

pub fn replace_manager( &self, create: impl FnOnce(&SessionManager) -> Result<SessionManager>, ) -> Result<()>

Replace the session with the one create builds from the current one. create runs only once the session is idle, so a refused replacement writes no new session file.

pub fn record_user_shell(&self, session_id: &str, message: AgentMessage)

Save the result of a shell command the user ran in session session_id. It is dropped when that session was replaced meanwhile. While a run is active it waits and is saved when the run ends, so it never lands between a tool call and its result.

pub fn set_model(&self, model: Model)

Switch the model. A thinking level the new model does not support moves to the nearest one it does, and that change is recorded too.

pub fn set_thinking_level(&self, level: ThinkingLevel)

Set the thinking level, moved to the nearest level the current model supports.

pub async fn navigate_tree( self: &Arc<Self>, target_id: &str, summarize: bool, custom_instructions: Option<String>, cancel: CancellationToken, ) -> Result<TreeNavigationOutcome>

Move the active leaf in the current session tree, with an optional summary of the branch that is no longer active.

pub fn queue_steering(&self, message: AgentMessage)

pub fn queue_follow_up(&self, message: AgentMessage)

pub fn add_for_next_turn(&self, message: AgentMessage)

Give the next model request a message without starting one. A busy session delivers it as a follow-up. An idle session adds it to history, so that a later prompt sees it without an extra model turn.

pub fn reclaim_queued(&self) -> Vec<AgentMessage>

Drain both queues back to the caller (Escape restores to editor).

pub fn abort(&self)

pub async fn answer_btw( self: &Arc<Self>, question: &str, cancel: CancellationToken, ) -> Result<EphemeralResponse>

Answer a short side question without changing the active session.

pub async fn generate_session_title( self: &Arc<Self>, prompt: &str, cancel: CancellationToken, ) -> Result<String>

Generate a short session title without changing conversation history.

pub async fn generate_recap( self: &Arc<Self>, previous_recap: Option<&str>, cancel: CancellationToken, ) -> Result<EphemeralResponse>

Create a one-line recap without changing the active session.

pub fn prompt( self: &Arc<Self>, prompts: Vec<AgentMessage>, ) -> impl Future<Output = ()> + Send + 'static + use<>

Run one prompt to completion, including retry and auto-compaction.

The session decides during this call whether the prompt starts or joins the steering queue, before the returned future is first polled.

pub fn prompt_with_mode( self: &Arc<Self>, prompts: Vec<AgentMessage>, prompt_mode: PromptMode, ) -> impl Future<Output = ()> + Send + 'static + use<>

Run one prompt with tools and instructions selected for this turn.

pub fn try_start_prompt( self: &Arc<Self>, message: AgentMessage, prompt_mode: PromptMode, ) -> Option<BoxFuture<'static, ()>>

Start a run, or return None when the session is busy.

pub fn submit( self: &Arc<Self>, prompts: Vec<AgentMessage>, prompt_mode: PromptMode, kind: QueueKind, ) -> Option<BoxFuture<'static, ()>>

Start a run, or queue the prompts when the session is busy. The caller must drive a returned future to run them.

pub fn compact( self: &Arc<Self>, custom_instructions: Option<String>, ) -> impl Future<Output = Result<(), String>> + Send + 'static + use<>

Compact on request. The session refuses during this call when a prompt or another compaction is active. Prompts that arrive during compaction run when it ends.

pub fn context_usage(&self) -> (u64, u64)

Current estimated context tokens and window fraction.