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_dirs: Vec<PathBuf>,
    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 sandbox_handle: Option<Arc<dyn BashSandbox>>,
    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 max_tool_rounds: Option<usize>,
    pub prompt_slots: Option<SystemPromptSlots>,
    pub hook_executor: Option<Arc<dyn HookExecutor>>,
    pub document_parser_registry: Option<Arc<DocumentParserRegistry>>,
    pub plugins: Vec<Arc<dyn Plugin>>,
    /* 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_dirs: Vec<PathBuf>

Extra directories to scan for skill files (*.md). Merged with any global skill_dirs from CodeConfig.

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 (kept for backward compatibility).

Setting this alone has no effect; the host application must also supply a concrete BashSandbox implementation via with_sandbox_handle.

sandbox_handle: Option<Arc<dyn BashSandbox>>

Optional concrete sandbox implementation.

When set, bash tool commands are routed through this sandbox instead of std::process::Command. The host application constructs and owns the implementation (e.g., an A3S Box–backed handle).

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).

max_tool_rounds: Option<usize>

Per-session tool round limit override.

When set, overrides the agent-level max_tool_rounds for this session only. Maps directly from [AgentDefinition::max_steps] when creating sessions via Agent::session_for_agent.

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.

hook_executor: Option<Arc<dyn HookExecutor>>

Optional external hook executor (e.g. an AHP harness server).

When set, replaces the built-in HookEngine for this session. All 11 lifecycle events are forwarded to the executor instead of being dispatched locally. The executor is also propagated to sub-agents via the sentinel hook mechanism.

document_parser_registry: Option<Arc<DocumentParserRegistry>>

Optional document parser registry for document-aware tools.

When set, enables custom format support (PDF, Excel, Word, etc.) for tools such as agentic_search and agentic_parse. If not set, only plain text files are accessible to those tools.

plugins: Vec<Arc<dyn Plugin>>

Plugins to mount onto this session.

Each plugin is loaded in order after the core tools are registered. Use [PluginManager] or add plugins directly via SessionOptions::with_plugin.

Example

use a3s_code_core::{SessionOptions, AgenticSearchPlugin, AgenticParsePlugin};

let opts = SessionOptions::new()
    .with_plugin(AgenticSearchPlugin::new())
    .with_plugin(AgenticParsePlugin::new());

Implementations

impl SessionOptions

pub fn new() -> Self

pub fn with_plugin(self, plugin: impl Plugin + 'static) -> Self

Mount a plugin onto this session.

The plugin’s tools are registered after the core tools, in the order plugins are added.

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_skill_dirs( self, dirs: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Add skill directories to scan for skill files (*.md). Merged with any global skill_dirs from CodeConfig at session build time.

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

Load skills from a directory (eager — scans immediately into a registry).

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_sandbox_handle(self, handle: Arc<dyn BashSandbox>) -> Self

Provide a concrete BashSandbox implementation for this session.

When set, bash tool commands are routed through the given sandbox instead of std::process::Command. The host application is responsible for constructing and lifecycle-managing the sandbox.

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_max_tool_rounds(self, rounds: usize) -> Self

Override the maximum number of tool execution rounds for this session.

Useful when binding a markdown-defined agent to a [TeamRunner] member — pass the agent’s max_steps value here to enforce its step budget.

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.

pub fn with_hook_executor(self, executor: Arc<dyn HookExecutor>) -> Self

Replace the built-in hook engine with an external hook executor.

Use this to attach an AHP harness server (or any custom HookExecutor) to the session. All lifecycle events will be forwarded to the executor instead of the in-process HookEngine.

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.