Struct SessionOptions 

pub struct SessionOptions {

    pub model: Option<String>,
    pub agent_dirs: Vec<PathBuf>,
    pub worker_agents: Vec<WorkerAgentSpec>,
    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 confirmation_policy: Option<ConfirmationPolicy>,
    pub permission_checker: Option<Arc<dyn PermissionChecker>>,
    pub permission_policy: Option<PermissionPolicy>,
    pub planning_mode: PlanningMode,
    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 tenant_id: Option<String>,
    pub principal: Option<String>,
    pub agent_template_id: Option<String>,
    pub correlation_id: Option<String>,
    pub budget_guard: Option<Arc<dyn BudgetGuard>>,
    pub host_env: Option<Arc<HostEnv>>,
    pub retention_limits: Option<SessionRetentionLimits>,
    pub auto_save: bool,
    pub artifact_store_limits: Option<ArtifactStoreLimits>,
    pub max_parse_retries: Option<u32>,
    pub tool_timeout_ms: Option<u64>,
    pub circuit_breaker_threshold: Option<u32>,
    pub sandbox_handle: Option<Arc<dyn BashSandbox>>,
    pub workspace_services: Option<Arc<WorkspaceServices>>,
    pub auto_compact: bool,
    pub auto_compact_threshold: Option<f32>,
    pub continuation_enabled: Option<bool>,
    pub max_continuation_turns: Option<u32>,
    pub max_execution_time_ms: Option<u64>,
    pub mcp_manager: Option<Arc<McpManager>>,
    pub temperature: Option<f32>,
    pub thinking_budget: Option<usize>,
    pub max_tool_rounds: Option<usize>,
    pub max_parallel_tasks: Option<usize>,
    pub auto_delegation: Option<AutoDelegationConfig>,
    pub auto_parallel_delegation: Option<bool>,
    pub prompt_slots: Option<SystemPromptSlots>,
    pub hook_executor: Option<Arc<dyn HookExecutor>>,
    /* 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.

worker_agents: Vec<WorkerAgentSpec>

Reproducible disposable workers registered for task delegation. Explicit session workers override agents loaded from directories by name.

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

confirmation_policy: Option<ConfirmationPolicy>

Optional confirmation policy (will be used to create ConfirmationManager if confirmation_manager is not set)

permission_checker: Option<Arc<dyn PermissionChecker>>

Optional permission checker

permission_policy: Option<PermissionPolicy>

Serializable permission policy used to build the checker, when available.

planning_mode: PlanningMode

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)

tenant_id: Option<String>

Multi-tenant identifier. Framework only transports this string; the host (e.g. 书安OS) decides what “tenant” means and how to aggregate/bill on it. Emitted to hooks/traces, persisted in SessionData, never interpreted by core.

principal: Option<String>

Identity of the principal that triggered this session (user id, service account, etc). Treated as opaque.

agent_template_id: Option<String>

Logical identifier of the agent template / definition the session was instantiated from. Lets the host aggregate sessions by “which agent recipe” independent of the concrete session id.

correlation_id: Option<String>

Distributed-trace correlation id. Propagated through hooks/traces so a session’s events join with upstream/downstream work in the host’s observability pipeline.

budget_guard: Option<Arc<dyn BudgetGuard>>

Optional host-supplied budget / quota guard. The framework calls into it before each LLM call (and reports actuals after) so the host can refuse or rate-limit at the cluster level. Default is None (no enforcement — equivalent to NoopBudgetGuard).

host_env: Option<Arc<HostEnv>>

Optional host-provided ID/Clock pair. Replaces the default random-UUID + wall-clock pair, enabling deterministic replay on another node. None keeps pre-P2 behaviour.

retention_limits: Option<SessionRetentionLimits>

Optional FIFO retention caps on the session’s in-memory stores (run records, run events, trace events, terminal subagent tasks). None (default) keeps everything — fine for short sessions, a memory leak for hours-long cluster workloads.

auto_save: bool

Auto-save after each completed send() or default-history stream() call.

artifact_store_limits: Option<ArtifactStoreLimits>

Optional artifact retention limits for large tool/program outputs.

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

workspace_services: Option<Arc<WorkspaceServices>>

Optional host-provided workspace backend.

When set, built-in tools such as read, write, ls, and bash execute against these workspace capabilities instead of assuming the server-local filesystem. This is the primary extension point for DFS, browser, container, and remote workspace deployments.

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

max_execution_time_ms: Option<u64>

Maximum execution time in milliseconds. None = no timeout (default). When set, the execution loop will abort if it exceeds this duration.

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.

max_parallel_tasks: Option<usize>

Per-session parallel fan-out limit override.

Applies to delegated parallel_task, plan wave execution, and safe parallel write batches.

auto_delegation: Option<AutoDelegationConfig>

Per-session automatic subagent delegation override.

auto_parallel_delegation: Option<bool>

Per-session kill switch for automatic parallel child-agent fan-out.

This overlays the effective automatic delegation config instead of replacing it, so callers can disable auto fan-out without disabling automatic delegation itself.

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.

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_worker_agent(self, spec: WorkerAgentSpec) -> Self

Register a cattle-style worker with this session’s task delegation registry.

pub fn with_worker_agents<I>(self, specs: I) -> Self

where I: IntoIterator<Item = WorkerAgentSpec>,

Register multiple cattle-style workers with this session.

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_confirmation_policy(self, policy: ConfirmationPolicy) -> Self

Set a confirmation policy for HITL

The policy will be used to create a ConfirmationManager when the session is built. This is the preferred way to configure HITL from the Node SDK.

pub fn with_permission_policy(self, policy: PermissionPolicy) -> Self

Set a serializable permission policy for tool execution.

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

Set a permission checker

pub fn with_planning_mode(self, mode: PlanningMode) -> Self

Set planning mode

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

Enable planning (shortcut for with_planning_mode(PlanningMode::Enabled))

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_tenant_id(self, tenant: impl Into<String>) -> Self

Tag the session with a host-defined tenant id. Opaque to the framework — propagated to SessionData, hooks, and traces.

pub fn with_principal(self, principal: impl Into<String>) -> Self

Tag the session with the id of the principal (user / service account / etc.) that triggered it.

pub fn with_agent_template_id(self, template_id: impl Into<String>) -> Self

Tag the session with the id of the agent template / definition it was instantiated from.

pub fn with_correlation_id(self, corr: impl Into<String>) -> Self

Attach a distributed-trace correlation id so this session’s events can be joined with upstream/downstream work.

pub fn with_budget_guard(self, guard: Arc<dyn BudgetGuard>) -> Self

Install a host-supplied BudgetGuard.

The guard is consulted before every LLM call (and after, for usage accounting). When unset, no budget enforcement happens.

pub fn with_host_env(self, env: Arc<HostEnv>) -> Self

Install a host-provided HostEnv for deterministic ID generation and time. Replaces the framework default of uuid::Uuid::new_v4() + wall clock — used by 书安OS replay infrastructure to recreate a run bit-identical on another node.

pub fn with_retention_limits(self, limits: SessionRetentionLimits) -> Self

Install FIFO retention caps for the session’s in-memory stores.

Without these caps the in-memory run store, trace sink, and subagent task tracker grow unboundedly across long-running sessions. Hosts running thousands of long-lived sessions per node should set sensible caps (e.g. retain the last 100 runs, 5000 events per run, 10000 trace events, 1000 terminal subagent tasks). When unset, the framework keeps every record — the pre-existing behaviour.

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

Enable auto-save after each send() call

pub fn with_artifact_store_limits(self, limits: ArtifactStoreLimits) -> Self

Set artifact retention limits for this session.

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_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_workspace_backend(self, services: Arc<WorkspaceServices>) -> Self

Provide a workspace backend for this session.

Built-in tools keep their stable names and schemas, while their backing implementation can target a DFS, browser workspace, remote runner, or any other host-provided backend.

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 subagent to a session — pass the agent definition’s max_steps value here to enforce its step budget.

pub fn with_max_parallel_tasks(self, tasks: usize) -> Self

Override the maximum number of sibling parallel branches for this session.

pub fn with_auto_delegation(self, config: AutoDelegationConfig) -> Self

Override automatic subagent delegation for this session.

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

Enable or disable automatic subagent delegation for this session.

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

Globally enable or disable automatic parallel child-agent fan-out.

Manual parallel_task calls remain available when this is false.

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.