a3s_code_core/agent_api/
session_options.rs

1//! Session option builder interface.
2//!
3//! `SessionOptions` is the host-facing capability configuration for a session.
4//! Keeping the builder implementation here lets `agent_api.rs` keep the type
5//! shape visible while moving option construction behavior behind this module.
6
7use super::SessionOptions;
8use crate::prompts::{PlanningMode, SystemPromptSlots};
9use crate::queue::SessionQueueConfig;
10use crate::subagent::WorkerAgentSpec;
11use a3s_memory::MemoryStore;
12use std::path::PathBuf;
13use std::sync::Arc;
14
15impl std::fmt::Debug for SessionOptions {
16    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
17        f.debug_struct("SessionOptions")
18            .field("model", &self.model)
19            .field("agent_dirs", &self.agent_dirs)
20            .field("worker_agents", &self.worker_agents.len())
21            .field("skill_dirs", &self.skill_dirs)
22            .field("queue_config", &self.queue_config)
23            .field("security_provider", &self.security_provider.is_some())
24            .field("llm_client", &self.llm_client.is_some())
25            .field("context_providers", &self.context_providers.len())
26            .field("confirmation_manager", &self.confirmation_manager.is_some())
27            .field("permission_checker", &self.permission_checker.is_some())
28            .field("permission_policy", &self.permission_policy.is_some())
29            .field("planning_mode", &self.planning_mode)
30            .field("goal_tracking", &self.goal_tracking)
31            .field(
32                "skill_registry",
33                &self
34                    .skill_registry
35                    .as_ref()
36                    .map(|r| format!("{} skills", r.len())),
37            )
38            .field(
39                "enforce_active_skill_tool_restrictions",
40                &self.enforce_active_skill_tool_restrictions,
41            )
42            .field("memory_store", &self.memory_store.is_some())
43            .field("file_memory_dir", &self.file_memory_dir)
44            .field("session_store", &self.session_store.is_some())
45            .field("file_session_store_dir", &self.file_session_store_dir)
46            .field("session_id", &self.session_id)
47            .field("rl_trajectory", &self.rl_trajectory)
48            .field("llm_logprobs", &self.llm_logprobs)
49            .field("llm_top_logprobs", &self.llm_top_logprobs)
50            .field("auto_save", &self.auto_save)
51            .field("artifact_store_limits", &self.artifact_store_limits)
52            .field("max_parse_retries", &self.max_parse_retries)
53            .field("tool_timeout_ms", &self.tool_timeout_ms)
54            .field("llm_api_timeout_ms", &self.llm_api_timeout_ms)
55            .field("circuit_breaker_threshold", &self.circuit_breaker_threshold)
56            .field(
57                "duplicate_tool_call_threshold",
58                &self.duplicate_tool_call_threshold,
59            )
60            .field("sandbox_handle", &self.sandbox_handle.is_some())
61            .field("workspace_services", &self.workspace_services.is_some())
62            .field("auto_compact", &self.auto_compact)
63            .field("auto_compact_threshold", &self.auto_compact_threshold)
64            .field("max_context_tokens", &self.max_context_tokens)
65            .field("continuation_enabled", &self.continuation_enabled)
66            .field("max_continuation_turns", &self.max_continuation_turns)
67            .field("mcp_manager", &self.mcp_manager.is_some())
68            .field("temperature", &self.temperature)
69            .field("thinking_budget", &self.thinking_budget)
70            .field("max_tool_rounds", &self.max_tool_rounds)
71            .field("max_parallel_tasks", &self.max_parallel_tasks)
72            .field("auto_delegation", &self.auto_delegation)
73            .field("manual_delegation_enabled", &self.manual_delegation_enabled)
74            .field("auto_parallel_delegation", &self.auto_parallel_delegation)
75            .field("prompt_slots", &self.prompt_slots.is_some())
76            .finish()
77    }
78}
79
80impl SessionOptions {
81    pub fn new() -> Self {
82        Self::default()
83    }
84
85    pub fn with_model(mut self, model: impl Into<String>) -> Self {
86        self.model = Some(model.into());
87        self
88    }
89
90    pub fn with_agent_dir(mut self, dir: impl Into<PathBuf>) -> Self {
91        self.agent_dirs.push(dir.into());
92        self
93    }
94
95    /// Register a cattle-style worker with this session's task delegation registry.
96    pub fn with_worker_agent(mut self, spec: WorkerAgentSpec) -> Self {
97        self.worker_agents.push(spec);
98        self
99    }
100
101    /// Register multiple cattle-style workers with this session.
102    pub fn with_worker_agents<I>(mut self, specs: I) -> Self
103    where
104        I: IntoIterator<Item = WorkerAgentSpec>,
105    {
106        self.worker_agents.extend(specs);
107        self
108    }
109
110    pub fn with_queue_config(mut self, config: SessionQueueConfig) -> Self {
111        self.queue_config = Some(config);
112        self
113    }
114
115    /// Enable default security provider with taint tracking and output sanitization
116    pub fn with_default_security(mut self) -> Self {
117        self.security_provider = Some(Arc::new(crate::security::DefaultSecurityProvider::new()));
118        self
119    }
120
121    /// Set a custom security provider
122    pub fn with_security_provider(
123        mut self,
124        provider: Arc<dyn crate::security::SecurityProvider>,
125    ) -> Self {
126        self.security_provider = Some(provider);
127        self
128    }
129
130    /// Provide a custom LLM client for this session.
131    ///
132    /// When set, this client is used directly, overriding the `provider/model`
133    /// factory resolution. Use it to plug in a provider the built-in factory
134    /// does not cover, a deterministic record/replay client for tests, or an
135    /// HTTP-layer proxy/audit wrapper. Mirrors [`Self::with_workspace_backend`];
136    /// the `provider/model` config path remains the default when unset.
137    pub fn with_llm_client(mut self, client: Arc<dyn crate::llm::LlmClient>) -> Self {
138        self.llm_client = Some(client);
139        self
140    }
141
142    /// Add a file system context provider for simple RAG
143    pub fn with_fs_context(mut self, root_path: impl Into<PathBuf>) -> Self {
144        let config = crate::context::FileSystemContextConfig::new(root_path);
145        self.context_providers
146            .push(Arc::new(crate::context::FileSystemContextProvider::new(
147                config,
148            )));
149        self
150    }
151
152    /// Add a custom context provider
153    pub fn with_context_provider(
154        mut self,
155        provider: Arc<dyn crate::context::ContextProvider>,
156    ) -> Self {
157        self.context_providers.push(provider);
158        self
159    }
160
161    /// Set a confirmation manager for HITL
162    pub fn with_confirmation_manager(
163        mut self,
164        manager: Arc<dyn crate::hitl::ConfirmationProvider>,
165    ) -> Self {
166        self.confirmation_manager = Some(manager);
167        self
168    }
169
170    /// Set a confirmation policy for HITL
171    ///
172    /// The policy will be used to create a ConfirmationManager when the session is built.
173    /// This is the preferred way to configure HITL from the Node SDK.
174    pub fn with_confirmation_policy(mut self, policy: crate::hitl::ConfirmationPolicy) -> Self {
175        self.confirmation_policy = Some(policy);
176        self
177    }
178
179    /// Set a serializable permission policy for tool execution.
180    pub fn with_permission_policy(mut self, policy: crate::permissions::PermissionPolicy) -> Self {
181        self.permission_checker = Some(Arc::new(policy.clone()));
182        self.permission_policy = Some(policy);
183        self
184    }
185
186    /// Set a permission checker
187    pub fn with_permission_checker(
188        mut self,
189        checker: Arc<dyn crate::permissions::PermissionChecker>,
190    ) -> Self {
191        self.permission_checker = Some(checker);
192        self
193    }
194
195    /// Set planning mode
196    pub fn with_planning_mode(mut self, mode: PlanningMode) -> Self {
197        self.planning_mode = mode;
198        self
199    }
200
201    /// Enable planning (shortcut for `with_planning_mode(PlanningMode::Enabled)`)
202    pub fn with_planning(mut self, enabled: bool) -> Self {
203        self.planning_mode = if enabled {
204            PlanningMode::Enabled
205        } else {
206            PlanningMode::Disabled
207        };
208        self
209    }
210
211    /// Enable goal tracking
212    pub fn with_goal_tracking(mut self, enabled: bool) -> Self {
213        self.goal_tracking = enabled;
214        self
215    }
216
217    /// Add the compatibility built-in skill registry.
218    ///
219    /// A3S Code no longer ships embedded built-in skills, so this currently
220    /// installs an empty registry. Use skill directories, inline skills, or a
221    /// custom skill registry for reusable behavior.
222    pub fn with_builtin_skills(mut self) -> Self {
223        self.skill_registry = Some(Arc::new(crate::skills::SkillRegistry::with_builtins()));
224        self
225    }
226
227    /// Add a custom skill registry
228    pub fn with_skill_registry(mut self, registry: Arc<crate::skills::SkillRegistry>) -> Self {
229        self.skill_registry = Some(registry);
230        self
231    }
232
233    /// Enable or disable legacy global active-skill `allowed-tools` restrictions.
234    ///
235    /// The default is disabled: active skills do not block ordinary session
236    /// tools before the host permission/HITL approval chain runs.
237    pub fn with_active_skill_tool_restrictions(mut self, enabled: bool) -> Self {
238        self.enforce_active_skill_tool_restrictions = Some(enabled);
239        self
240    }
241
242    /// Add skill directories to scan for skill files (*.md).
243    /// Merged with any global `skill_dirs` from [`CodeConfig`] at session build time.
244    pub fn with_skill_dirs(mut self, dirs: impl IntoIterator<Item = impl Into<PathBuf>>) -> Self {
245        self.skill_dirs.extend(dirs.into_iter().map(Into::into));
246        self
247    }
248
249    /// Load skills from a directory (eager — scans immediately into a registry).
250    pub fn with_skills_from_dir(mut self, dir: impl AsRef<std::path::Path>) -> Self {
251        let registry = self
252            .skill_registry
253            .unwrap_or_else(|| Arc::new(crate::skills::SkillRegistry::new()));
254        if let Err(e) = registry.load_from_dir(&dir) {
255            tracing::warn!(
256                dir = %dir.as_ref().display(),
257                error = %e,
258                "Failed to load skills from directory — continuing without them"
259            );
260        }
261        self.skill_registry = Some(registry);
262        self
263    }
264
265    /// Set a custom memory store override.
266    ///
267    /// Sessions resolve a default memory store when no override is provided.
268    pub fn with_memory(mut self, store: Arc<dyn MemoryStore>) -> Self {
269        self.memory_store = Some(store);
270        self.file_memory_dir = None;
271        self
272    }
273
274    /// Use a file-based memory store at the given directory instead of the default.
275    ///
276    /// The store is created lazily when the session is built (requires async).
277    /// This stores the directory path; `FileMemoryStore::new()` is called during
278    /// session construction.
279    pub fn with_file_memory(mut self, dir: impl Into<PathBuf>) -> Self {
280        self.memory_store = None;
281        self.file_memory_dir = Some(dir.into());
282        self
283    }
284
285    /// Set a session store for persistence
286    pub fn with_session_store(mut self, store: Arc<dyn crate::store::SessionStore>) -> Self {
287        self.session_store = Some(store);
288        self.file_session_store_dir = None;
289        self
290    }
291
292    /// Use a file-based session store at the given directory.
293    ///
294    /// The path is a typed construction specification. No I/O occurs until
295    /// [`SessionBuilder::build`](super::SessionBuilder::build) is awaited.
296    pub fn with_file_session_store(mut self, dir: impl Into<PathBuf>) -> Self {
297        self.session_store = None;
298        self.file_session_store_dir = Some(dir.into());
299        self
300    }
301
302    /// Set an explicit session ID (auto-generated UUID if not set)
303    pub fn with_session_id(mut self, id: impl Into<String>) -> Self {
304        self.session_id = Some(id.into());
305        self
306    }
307
308    /// Tag the session with a host-defined tenant id. Opaque to the
309    /// framework — propagated to `SessionData`, hooks, and traces.
310    pub fn with_tenant_id(mut self, tenant: impl Into<String>) -> Self {
311        self.tenant_id = Some(tenant.into());
312        self
313    }
314
315    /// Tag the session with the id of the principal (user / service
316    /// account / etc.) that triggered it.
317    pub fn with_principal(mut self, principal: impl Into<String>) -> Self {
318        self.principal = Some(principal.into());
319        self
320    }
321
322    /// Tag the session with the id of the agent template / definition it
323    /// was instantiated from.
324    pub fn with_agent_template_id(mut self, template_id: impl Into<String>) -> Self {
325        self.agent_template_id = Some(template_id.into());
326        self
327    }
328
329    /// Attach a distributed-trace correlation id so this session's events
330    /// can be joined with upstream/downstream work.
331    pub fn with_correlation_id(mut self, corr: impl Into<String>) -> Self {
332        self.correlation_id = Some(corr.into());
333        self
334    }
335
336    /// Install a host-supplied [`BudgetGuard`](crate::budget::BudgetGuard).
337    ///
338    /// The guard is consulted before every LLM call (and after, for
339    /// usage accounting). When unset, no budget enforcement happens.
340    pub fn with_budget_guard(mut self, guard: Arc<dyn crate::budget::BudgetGuard>) -> Self {
341        self.budget_guard = Some(guard);
342        self
343    }
344
345    /// Install a host-provided [`HostEnv`](crate::host_env::HostEnv) for
346    /// deterministic ID generation and time. Replaces the framework
347    /// default of `uuid::Uuid::new_v4()` + wall clock — used by
348    /// host replay infrastructure to recreate a run bit-identical on
349    /// another node.
350    pub fn with_host_env(mut self, env: Arc<crate::host_env::HostEnv>) -> Self {
351        self.host_env = Some(env);
352        self
353    }
354
355    /// Install FIFO retention caps for the session's in-memory stores.
356    ///
357    /// Without these caps the in-memory run store, trace sink, and
358    /// subagent task tracker grow unboundedly across long-running
359    /// sessions. Hosts running thousands of long-lived sessions per
360    /// node should set sensible caps (e.g. retain the last 100 runs,
361    /// 5000 events per run, 10000 trace events, 1000 terminal subagent
362    /// tasks). When unset, the framework keeps every record — the
363    /// pre-existing behaviour.
364    pub fn with_retention_limits(
365        mut self,
366        limits: crate::retention::SessionRetentionLimits,
367    ) -> Self {
368        self.retention_limits = Some(limits);
369        self
370    }
371
372    /// Enable structured JSONL trajectory capture for this session.
373    ///
374    /// This is the preferred programmatic path for RL training and deployed
375    /// service data collection. Environment-only deployments can instead set
376    /// `A3S_CODE_TRAJECTORY_PATH`.
377    pub fn with_rl_trajectory(mut self, config: crate::rl_trajectory::RlTrajectoryConfig) -> Self {
378        self.rl_trajectory = Some(config);
379        self
380    }
381
382    /// Request token-level log probabilities from compatible LLM providers.
383    pub fn with_llm_logprobs(mut self, enabled: bool) -> Self {
384        self.llm_logprobs = Some(enabled);
385        self
386    }
387
388    /// Request up to `top_logprobs` alternative logprobs per generated token.
389    pub fn with_llm_top_logprobs(mut self, top_logprobs: usize) -> Self {
390        self.llm_logprobs = Some(true);
391        self.llm_top_logprobs = Some(top_logprobs);
392        self
393    }
394
395    /// Enable auto-save after each `send()` call
396    pub fn with_auto_save(mut self, enabled: bool) -> Self {
397        self.auto_save = enabled;
398        self
399    }
400
401    /// Set artifact retention limits for this session.
402    pub fn with_artifact_store_limits(mut self, limits: crate::tools::ArtifactStoreLimits) -> Self {
403        self.artifact_store_limits = Some(limits);
404        self
405    }
406
407    /// Set the maximum number of consecutive malformed-tool-args errors before
408    /// the agent loop bails.
409    ///
410    /// Default: 2 (the LLM gets two chances to self-correct before the session
411    /// is aborted).
412    pub fn with_parse_retries(mut self, max: u32) -> Self {
413        self.max_parse_retries = Some(max);
414        self
415    }
416
417    /// Set a per-tool execution timeout.
418    ///
419    /// When set, each tool execution is wrapped in `tokio::time::timeout`.
420    /// A timeout produces an error message that is fed back to the LLM
421    /// (the session continues).
422    pub fn with_tool_timeout(mut self, timeout_ms: u64) -> Self {
423        self.tool_timeout_ms = Some(timeout_ms);
424        self
425    }
426
427    /// Set a per-model API HTTP timeout.
428    ///
429    /// This is separate from [`with_tool_timeout`](Self::with_tool_timeout):
430    /// tool calls may need long-running process limits while model API calls
431    /// should use provider/network-specific deadlines.
432    pub fn with_llm_api_timeout(mut self, timeout_ms: u64) -> Self {
433        self.llm_api_timeout_ms = Some(timeout_ms);
434        self
435    }
436
437    /// Set the circuit-breaker threshold.
438    ///
439    /// In non-streaming mode, the agent retries transient LLM API failures up
440    /// to this many times (with exponential backoff) before aborting.
441    /// Default: 3 attempts.
442    pub fn with_circuit_breaker(mut self, threshold: u32) -> Self {
443        self.circuit_breaker_threshold = Some(threshold);
444        self
445    }
446
447    /// Set the duplicate-tool-call threshold.
448    ///
449    /// When the same tool is called with identical arguments more than this
450    /// budget allows, the call is returned to the model as a failed tool result
451    /// instead of executing again. Default: 3.
452    pub fn with_duplicate_tool_call_threshold(mut self, threshold: u32) -> Self {
453        self.duplicate_tool_call_threshold = Some(threshold.max(1));
454        self
455    }
456
457    /// Enable all resilience defaults with sensible values:
458    ///
459    /// - `max_parse_retries = 2`
460    /// - `tool_timeout_ms = 120_000` (2 minutes)
461    /// - `circuit_breaker_threshold = 3`
462    pub fn with_resilience_defaults(self) -> Self {
463        self.with_parse_retries(2)
464            .with_tool_timeout(120_000)
465            .with_circuit_breaker(3)
466    }
467
468    /// Provide a concrete [`BashSandbox`] implementation for this session.
469    ///
470    /// When set, `bash` tool commands are routed through the given sandbox
471    /// instead of `std::process::Command`. The host application is responsible
472    /// for constructing and lifecycle-managing the sandbox.
473    ///
474    /// [`BashSandbox`]: crate::sandbox::BashSandbox
475    pub fn with_sandbox_handle(mut self, handle: Arc<dyn crate::sandbox::BashSandbox>) -> Self {
476        self.sandbox_handle = Some(handle);
477        self
478    }
479
480    /// Provide a workspace backend for this session.
481    ///
482    /// Built-in tools keep their stable names and schemas, while their backing
483    /// implementation can target a DFS, browser workspace, remote runner, or
484    /// any other host-provided backend.
485    pub fn with_workspace_backend(
486        mut self,
487        services: Arc<crate::workspace::WorkspaceServices>,
488    ) -> Self {
489        self.workspace_services = Some(services);
490        self
491    }
492
493    /// Enable auto-compaction when context usage exceeds threshold.
494    ///
495    /// When enabled, the agent loop automatically prunes large tool outputs
496    /// and summarizes old messages when context usage exceeds the threshold.
497    pub fn with_auto_compact(mut self, enabled: bool) -> Self {
498        self.auto_compact = enabled;
499        self
500    }
501
502    /// Set the auto-compact threshold (0.0 - 1.0). Default: 0.80 (80%).
503    pub fn with_auto_compact_threshold(mut self, threshold: f32) -> Self {
504        self.auto_compact_threshold = Some(threshold.clamp(0.0, 1.0));
505        self
506    }
507
508    /// Set the active model's context window for compaction accounting.
509    pub fn with_max_context_tokens(mut self, tokens: usize) -> Self {
510        self.max_context_tokens = Some(tokens);
511        self
512    }
513
514    /// Enable or disable continuation injection (default: enabled).
515    ///
516    /// When enabled, the loop injects a continuation message when the LLM stops
517    /// calling tools before the task appears complete, nudging it to keep working.
518    pub fn with_continuation(mut self, enabled: bool) -> Self {
519        self.continuation_enabled = Some(enabled);
520        self
521    }
522
523    /// Set the maximum number of continuation injections per execution (default: 3).
524    pub fn with_max_continuation_turns(mut self, turns: u32) -> Self {
525        self.max_continuation_turns = Some(turns);
526        self
527    }
528
529    /// Inherit tools from an existing MCP manager.
530    ///
531    /// The session reads the manager as a capability source but never mutates
532    /// or disconnects it. Live [`AgentSession::add_mcp_server`](super::AgentSession::add_mcp_server)
533    /// calls use a separate session-owned manager. Delegated child agents
534    /// inherit both sources, with session-owned tools taking precedence.
535    pub fn with_mcp(mut self, manager: Arc<crate::mcp::manager::McpManager>) -> Self {
536        self.mcp_manager = Some(manager);
537        self
538    }
539
540    pub fn with_temperature(mut self, temperature: f32) -> Self {
541        self.temperature = Some(temperature);
542        self
543    }
544
545    pub fn with_thinking_budget(mut self, budget: usize) -> Self {
546        self.thinking_budget = Some(budget);
547        self
548    }
549
550    /// Override the maximum number of tool execution rounds for this session.
551    ///
552    /// Useful when binding a markdown-defined subagent to a session —
553    /// pass the agent definition's `max_steps` value here to enforce its step budget.
554    pub fn with_max_tool_rounds(mut self, rounds: usize) -> Self {
555        self.max_tool_rounds = Some(rounds);
556        self
557    }
558
559    /// Override the maximum number of sibling parallel branches for this session.
560    pub fn with_max_parallel_tasks(mut self, tasks: usize) -> Self {
561        self.max_parallel_tasks = Some(tasks.max(1));
562        self
563    }
564
565    /// Override automatic subagent delegation for this session.
566    pub fn with_auto_delegation(mut self, config: crate::config::AutoDelegationConfig) -> Self {
567        self.auto_delegation = Some(config);
568        self
569    }
570
571    /// Enable or disable automatic subagent delegation for this session.
572    pub fn with_auto_delegation_enabled(mut self, enabled: bool) -> Self {
573        let mut config = self.auto_delegation.take().unwrap_or_default();
574        config.enabled = enabled;
575        self.auto_delegation = Some(config);
576        self
577    }
578
579    /// Enable or disable model-visible manual child-agent tools for this session.
580    ///
581    /// When false, `task` and `parallel_task` are not registered in the session
582    /// tool surface. Worker agents remain registered for introspection and hosts
583    /// that manage them directly. This is for cost control or debugging; it is
584    /// not a security sandbox for the parent agent.
585    pub fn with_manual_delegation_enabled(mut self, enabled: bool) -> Self {
586        if let Some(config) = &mut self.auto_delegation {
587            config.allow_manual_delegation = enabled;
588        }
589        self.manual_delegation_enabled = Some(enabled);
590        self
591    }
592
593    /// Globally enable or disable automatic parallel child-agent fan-out.
594    ///
595    /// Manual `parallel_task` calls remain available when this is false.
596    pub fn with_auto_parallel_delegation(mut self, enabled: bool) -> Self {
597        if let Some(config) = &mut self.auto_delegation {
598            config.auto_parallel = enabled;
599        }
600        self.auto_parallel_delegation = Some(enabled);
601        self
602    }
603
604    /// Set slot-based system prompt customization for this session.
605    ///
606    /// Allows customizing role, guidelines, response style, and extra instructions
607    /// without overriding the core agentic capabilities.
608    pub fn with_prompt_slots(mut self, slots: SystemPromptSlots) -> Self {
609        self.prompt_slots = Some(slots);
610        self
611    }
612
613    /// Replace the built-in hook engine with an external hook executor.
614    ///
615    /// All lifecycle events are forwarded to the executor instead of the
616    /// in-process `HookEngine`.
617    pub fn with_hook_executor(mut self, executor: Arc<dyn crate::hooks::HookExecutor>) -> Self {
618        self.hook_executor = Some(executor);
619        self
620    }
621}
a3s_code_core/agent_api/session_options.rs

a3s_code_core/agent_api/
session_options.rs
