Struct AgentSession 

pub struct AgentSession { /* private fields */ }

Workspace-bound session. All LLM and tool operations happen here.

History is automatically accumulated after each send() call. Use history() to retrieve the current conversation log.

Implementations

impl AgentSession

pub fn command_registry(&self) -> &CommandRegistry

Get a reference to the slash command registry.

pub fn register_command(&mut self, cmd: Arc<dyn SlashCommand>)

Register a custom slash command.

pub async fn send( &self, prompt: &str, history: Option<&[Message]>, ) -> Result<AgentResult>

Send a prompt and wait for the complete response.

When history is None, uses (and auto-updates) the session’s internal conversation history. When Some, uses the provided history instead (the internal history is not modified).

If the prompt starts with /, it is dispatched as a slash command and the result is returned without calling the LLM.

pub async fn send_with_attachments( &self, prompt: &str, attachments: &[Attachment], history: Option<&[Message]>, ) -> Result<AgentResult>

Send a prompt with image attachments and wait for the complete response.

Images are included as multi-modal content blocks in the user message. Requires a vision-capable model (e.g., Claude Sonnet, GPT-4o).

pub async fn stream_with_attachments( &self, prompt: &str, attachments: &[Attachment], history: Option<&[Message]>, ) -> Result<(Receiver<AgentEvent>, JoinHandle<()>)>

Stream a prompt with image attachments.

Images are included as multi-modal content blocks in the user message. Requires a vision-capable model (e.g., Claude Sonnet, GPT-4o).

pub async fn stream( &self, prompt: &str, history: Option<&[Message]>, ) -> Result<(Receiver<AgentEvent>, JoinHandle<()>)>

Send a prompt and stream events back.

When history is None, uses the session’s internal history (note: streaming does not auto-update internal history since the result is consumed asynchronously via the channel). When Some, uses the provided history instead.

If the prompt starts with /, it is dispatched as a slash command and the result is emitted as a single TextDelta + End event.

pub fn history(&self) -> Vec<Message>

Return a snapshot of the session’s conversation history.

pub fn memory(&self) -> Option<&Arc<AgentMemory>>

Return a reference to the session’s memory, if configured.

pub fn id(&self) -> &str

Return the session ID.

pub fn workspace(&self) -> &Path

Return the session workspace path.

pub fn init_warning(&self) -> Option<&str>

Return any deferred init warning (e.g. memory store failed to initialize).

pub fn session_id(&self) -> &str

Return the session ID.

pub fn register_hook(&self, hook: Hook)

Register a hook for lifecycle event interception.

pub fn unregister_hook(&self, hook_id: &str) -> Option<Hook>

Unregister a hook by ID.

pub fn register_hook_handler( &self, hook_id: &str, handler: Arc<dyn HookHandler>, )

Register a handler for a specific hook.

pub fn unregister_hook_handler(&self, hook_id: &str)

Unregister a hook handler by hook ID.

pub fn hook_count(&self) -> usize

Get the number of registered hooks.

pub async fn save(&self) -> Result<()>

Save the session to the configured store.

Returns Ok(()) if saved successfully, or if no store is configured (no-op).

pub async fn read_file(&self, path: &str) -> Result<String>

Read a file from the workspace.

pub async fn bash(&self, command: &str) -> Result<String>

Execute a bash command in the workspace.

When a sandbox is configured via SessionOptions::with_sandbox(), the command is routed through the A3S Box sandbox.

pub async fn glob(&self, pattern: &str) -> Result<Vec<String>>

Search for files matching a glob pattern.

pub async fn grep(&self, pattern: &str) -> Result<String>

Search file contents with a regex pattern.

pub async fn tool(&self, name: &str, args: Value) -> Result<ToolCallResult>

Execute a tool by name, bypassing the LLM.

pub fn has_queue(&self) -> bool

Returns whether this session has a lane queue configured.

pub async fn set_lane_handler( &self, lane: SessionLane, config: LaneHandlerConfig, )

Configure a lane’s handler mode (Internal/External/Hybrid).

Only effective when a queue is configured via SessionOptions::with_queue_config.

pub async fn complete_external_task( &self, task_id: &str, result: ExternalTaskResult, ) -> bool

Complete an external task by ID.

Returns true if the task was found and completed, false if not found.

pub async fn pending_external_tasks(&self) -> Vec<ExternalTask>

Get pending external tasks awaiting completion by an external handler.

pub async fn queue_stats(&self) -> SessionQueueStats

Get queue statistics (pending, active, external counts per lane).

pub async fn queue_metrics(&self) -> Option<MetricsSnapshot>

Get a metrics snapshot from the queue (if metrics are enabled).

pub async fn dead_letters(&self) -> Vec<DeadLetter>

Get dead letters from the queue’s DLQ (if DLQ is enabled).

Trait Implementations

impl Debug for AgentSession

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

Formats the value using the given formatter.