Struct RuntimeBuilder 

pub struct RuntimeBuilder { /* private fields */ }

Builder for an embeddable Talos runtime.

The safe default is conservative: registered tools are wrapped in a permission-aware adapter, and unresolved Ask decisions are denied instead of being executed.

Implementations

impl RuntimeBuilder

pub fn new() -> Self

Creates a builder with no provider and the current directory as the workspace root.

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

Sets the language model provider used by the runtime.

pub fn workspace_root(self, root: impl Into<PathBuf>) -> Self

Sets the workspace root used for path-sensitive runtime behavior.

pub fn tool(self, tool: Arc<dyn AgentTool>) -> Self

Registers a tool with runtime-level permission gating.

pub fn permission_rule(self, rule: PermissionRule) -> Self

Adds an extra permission rule to the runtime permission engine.

Runtime rules are evaluated before the engine’s default fallback, so embedders can add narrow allow-list or deny-list rules without changing the safe default for unmatched write, execute, and network tools. Richer policy import remains a later RUNTIME-001 follow-up.

pub fn sandbox(self, sandbox: Box<dyn SandboxProvider>) -> Self

Sets an optional sandbox provider for sandbox-capable tools.

pub fn sandbox_fallback_policy(self, policy: SandboxFallbackPolicy) -> Self

Sets the sandbox fallback policy. The default is Deny.

pub fn sandbox_fallback(self, policy: SandboxFallbackPolicy) -> Self

Sets the sandbox fallback policy using the SDK contract name.

pub fn preset(self, preset: RuntimePreset) -> Self

Selects an explicit runtime capability preset.

pub fn coding_preset(self) -> Self

Selects the shared coding capability composition.

pub fn initial_history(self, history: Vec<Message>) -> Self

Seeds the runtime with existing conversation history.

pub fn model_context_limit(self, limit: u32) -> Self

Sets the model context limit used by the session compactor.

pub fn approval_handler(self, handler: Arc<dyn ApprovalHandler>) -> Self

Sets the approval handler for tools whose permission policy returns Ask.

Without a handler, Ask decisions are denied. AlwaysApprove choices install first-class in-memory Session grants for this runtime build only; they are not persisted to user configuration or durable sessions.

pub fn custom_prompt(self, prompt: impl Into<String>) -> Self

Replaces the default Talos identity/system prompt.

This is intended for embedders that reuse the runtime in a product with its own identity. Use RuntimeBuilder::append_prompt when the default identity should remain and only extra instructions are needed.

pub fn append_prompt(self, prompt: impl Into<String>) -> Self

Appends extra instructions to the system prompt.

pub fn durable_session(self, session: DurableSession) -> Self

Binds this runtime to a host-selected durable Talos session.

The session’s model history is restored during Self::build. Every successful turn is atomically persisted by Talos before its success completion event is emitted; failed, cancelled, and denied turns are not persisted. Calling this is optional and does not alter the existing in-memory runtime behavior when omitted.

pub fn durable_session_with_policy( self, session: DurableSession, policy: PersistencePolicy, ) -> Self

Sets the filtering policy for a durable session binding.

pub fn hook_registry(self, registry: Arc<HookRegistry>) -> Self

Injects a pre-populated HookRegistry into the runtime.

This allows embedders to register reviewed hooks (e.g., from a curated hook catalog) before the runtime starts, following the same builder pattern as RuntimeBuilder::approval_handler.

If not called, the runtime uses an empty HookRegistry.

pub fn skill_index(self, skills: Vec<SkillIndex>) -> Self

Sets the skill index for the runtime’s system prompt.

Embedders that discover skills via talos_skill::SkillLoader (e.g., from a local or remote skill store) can inject the Level 0 index here, following the same pattern as the CLI’s skill_runtime.rs.

If not called, the runtime has no skills in its system prompt.

pub fn build(self) -> RuntimeResult<RuntimeHandle>

Builds and starts the runtime actor.

The returned primary handle owns submission and event access. Dropping it initiates the non-blocking default shutdown plan; use RuntimeHandle::shutdown or RuntimeHandle::shutdown_with when the host must observe terminal cleanup.

Trait Implementations

impl Default for RuntimeBuilder

fn default() -> Self

Returns the “default value” for a type.