Struct SessionOptions 

pub struct SessionOptions {

    pub model: Option<String>,
    pub agent_dirs: Vec<PathBuf>,
    pub queue_config: Option<SessionQueueConfig>,
    pub security_provider: Option<Arc<dyn SecurityProvider>>,
    pub context_providers: Vec<Arc<dyn ContextProvider>>,
    pub confirmation_manager: Option<Arc<dyn ConfirmationProvider>>,
    pub permission_checker: Option<Arc<dyn PermissionChecker>>,
    pub planning_enabled: bool,
    pub goal_tracking: bool,
    pub skill_registry: Option<Arc<SkillRegistry>>,
    pub memory_store: Option<Arc<dyn MemoryStore>>,
    pub session_store: Option<Arc<dyn SessionStore>>,
    pub session_id: Option<String>,
    pub auto_save: bool,
    pub max_parse_retries: Option<u32>,
    pub tool_timeout_ms: Option<u64>,
    pub circuit_breaker_threshold: Option<u32>,
    pub sandbox_config: Option<SandboxConfig>,
    pub auto_compact: bool,
    pub auto_compact_threshold: Option<f32>,
    pub continuation_enabled: Option<bool>,
    pub max_continuation_turns: Option<u32>,
    pub mcp_manager: Option<Arc<McpManager>>,
    pub temperature: Option<f32>,
    pub thinking_budget: Option<usize>,
    pub prompt_slots: Option<SystemPromptSlots>,
    /* private fields */
}

Optional per-session overrides.

Fields

model: Option<String>

Override the default model. Format: "provider/model" (e.g., "openai/gpt-4o").

agent_dirs: Vec<PathBuf>

Extra directories to scan for agent files. Merged with any global agent_dirs from CodeConfig.

queue_config: Option<SessionQueueConfig>

Optional queue configuration for lane-based tool execution.

When set, enables priority-based tool scheduling with parallel execution of read-only (Query-lane) tools, DLQ, metrics, and external task handling.

security_provider: Option<Arc<dyn SecurityProvider>>

Optional security provider for taint tracking and output sanitization

context_providers: Vec<Arc<dyn ContextProvider>>

Optional context providers for RAG

confirmation_manager: Option<Arc<dyn ConfirmationProvider>>

Optional confirmation manager for HITL

permission_checker: Option<Arc<dyn PermissionChecker>>

Optional permission checker

planning_enabled: bool

Enable planning

goal_tracking: bool

Enable goal tracking

skill_registry: Option<Arc<SkillRegistry>>

Optional skill registry for instruction injection

memory_store: Option<Arc<dyn MemoryStore>>

Optional memory store for long-term memory persistence

session_store: Option<Arc<dyn SessionStore>>

Optional session store for persistence

session_id: Option<String>

Explicit session ID (auto-generated if not set)

auto_save: bool

Auto-save after each send() call

max_parse_retries: Option<u32>

Max consecutive parse errors before aborting (overrides default of 2). None uses the AgentConfig default.

tool_timeout_ms: Option<u64>

Per-tool execution timeout in milliseconds. None = no timeout (default).

circuit_breaker_threshold: Option<u32>

Circuit-breaker threshold: max consecutive LLM API failures before aborting in non-streaming mode (overrides default of 3). None uses the AgentConfig default.

sandbox_config: Option<SandboxConfig>

Optional sandbox configuration.

When set, bash tool commands are routed through an A3S Box MicroVM sandbox instead of std::process::Command. Requires the sandbox Cargo feature to be enabled.

auto_compact: bool

Enable auto-compaction when context usage exceeds threshold.

auto_compact_threshold: Option<f32>

Context usage percentage threshold for auto-compaction (0.0 - 1.0). Default: 0.80 (80%).

continuation_enabled: Option<bool>

Inject a continuation message when the LLM stops without completing the task. None uses the AgentConfig default (true).

max_continuation_turns: Option<u32>

Maximum continuation injections per execution. None uses the AgentConfig default (3).

mcp_manager: Option<Arc<McpManager>>

Optional MCP manager for connecting to external MCP servers.

When set, all tools from connected MCP servers are registered and available during agent execution with names like mcp__server__tool.

temperature: Option<f32>

Sampling temperature (0.0–1.0). Overrides the provider default.

thinking_budget: Option<usize>

Extended thinking budget in tokens (Anthropic only).

prompt_slots: Option<SystemPromptSlots>

Slot-based system prompt customization.

When set, overrides the agent-level prompt slots for this session. Users can customize role, guidelines, response style, and extra instructions without losing the core agentic capabilities.

Implementations

impl SessionOptions

pub fn new() -> Self

pub fn with_model(self, model: impl Into<String>) -> Self

pub fn with_agent_dir(self, dir: impl Into<PathBuf>) -> Self

pub fn with_queue_config(self, config: SessionQueueConfig) -> Self

pub fn with_default_security(self) -> Self

Enable default security provider with taint tracking and output sanitization

pub fn with_security_provider(self, provider: Arc<dyn SecurityProvider>) -> Self

Set a custom security provider

pub fn with_fs_context(self, root_path: impl Into<PathBuf>) -> Self

Add a file system context provider for simple RAG

pub fn with_context_provider(self, provider: Arc<dyn ContextProvider>) -> Self

Add a custom context provider

pub fn with_confirmation_manager( self, manager: Arc<dyn ConfirmationProvider>, ) -> Self

Set a confirmation manager for HITL

pub fn with_permission_checker( self, checker: Arc<dyn PermissionChecker>, ) -> Self

Set a permission checker

pub fn with_permissive_policy(self) -> Self

Allow all tool execution without confirmation (permissive mode).

Use this for automated scripts, demos, and CI environments where human-in-the-loop confirmation is not needed. Without this (or a custom permission checker), the default is Ask, which requires a HITL confirmation manager to be configured.

pub fn with_planning(self, enabled: bool) -> Self

Enable planning

pub fn with_goal_tracking(self, enabled: bool) -> Self

Enable goal tracking

pub fn with_builtin_skills(self) -> Self

Add a skill registry with built-in skills

pub fn with_skill_registry(self, registry: Arc<SkillRegistry>) -> Self

Add a custom skill registry

pub fn with_skills_from_dir(self, dir: impl AsRef<Path>) -> Self

Load skills from a directory

pub fn with_memory(self, store: Arc<dyn MemoryStore>) -> Self

Set a custom memory store

pub fn with_file_memory(self, dir: impl Into<PathBuf>) -> Self

Use a file-based memory store at the given directory.

The store is created lazily when the session is built (requires async). This stores the directory path; FileMemoryStore::new() is called during session construction.

pub fn with_session_store(self, store: Arc<dyn SessionStore>) -> Self

Set a session store for persistence

pub fn with_file_session_store(self, dir: impl Into<PathBuf>) -> Self

Use a file-based session store at the given directory

pub fn with_session_id(self, id: impl Into<String>) -> Self

Set an explicit session ID (auto-generated UUID if not set)

pub fn with_auto_save(self, enabled: bool) -> Self

Enable auto-save after each send() call

pub fn with_parse_retries(self, max: u32) -> Self

Set the maximum number of consecutive malformed-tool-args errors before the agent loop bails.

Default: 2 (the LLM gets two chances to self-correct before the session is aborted).

pub fn with_tool_timeout(self, timeout_ms: u64) -> Self

Set a per-tool execution timeout.

When set, each tool execution is wrapped in tokio::time::timeout. A timeout produces an error message that is fed back to the LLM (the session continues).

pub fn with_circuit_breaker(self, threshold: u32) -> Self

Set the circuit-breaker threshold.

In non-streaming mode, the agent retries transient LLM API failures up to this many times (with exponential backoff) before aborting. Default: 3 attempts.

pub fn with_resilience_defaults(self) -> Self

Enable all resilience defaults with sensible values:

• max_parse_retries = 2
• tool_timeout_ms = 120_000 (2 minutes)
• circuit_breaker_threshold = 3

pub fn with_sandbox(self, config: SandboxConfig) -> Self

Route bash tool execution through an A3S Box MicroVM sandbox.

The workspace directory is mounted read-write at /workspace inside the sandbox. Requires the sandbox Cargo feature; without it a warning is logged and bash commands continue to run locally.

Example

use a3s_code_core::{SessionOptions, SandboxConfig};

SessionOptions::new().with_sandbox(SandboxConfig {
    image: "ubuntu:22.04".into(),
    memory_mb: 512,
    network: false,
    ..SandboxConfig::default()
});

pub fn with_auto_compact(self, enabled: bool) -> Self

Enable auto-compaction when context usage exceeds threshold.

When enabled, the agent loop automatically prunes large tool outputs and summarizes old messages when context usage exceeds the threshold.

pub fn with_auto_compact_threshold(self, threshold: f32) -> Self

Set the auto-compact threshold (0.0 - 1.0). Default: 0.80 (80%).

pub fn with_continuation(self, enabled: bool) -> Self

Enable or disable continuation injection (default: enabled).

When enabled, the loop injects a continuation message when the LLM stops calling tools before the task appears complete, nudging it to keep working.

pub fn with_max_continuation_turns(self, turns: u32) -> Self

Set the maximum number of continuation injections per execution (default: 3).

pub fn with_mcp(self, manager: Arc<McpManager>) -> Self

Set an MCP manager to connect to external MCP servers.

All tools from connected servers will be available during execution with names like mcp__<server>__<tool>.

pub fn with_temperature(self, temperature: f32) -> Self

pub fn with_thinking_budget(self, budget: usize) -> Self

pub fn with_prompt_slots(self, slots: SystemPromptSlots) -> Self

Set slot-based system prompt customization for this session.

Allows customizing role, guidelines, response style, and extra instructions without overriding the core agentic capabilities.

Trait Implementations

impl Clone for SessionOptions

fn clone(&self) -> SessionOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SessionOptions

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

Formats the value using the given formatter.

impl Default for SessionOptions

fn default() -> SessionOptions

Returns the “default value” for a type.