Struct Runtime 

pub struct Runtime {
    pub watcher_exit_path: Option<PathBuf>,
    /* private fields */
}

Fields

watcher_exit_path: Option<PathBuf>

Path for watcher_exit tool to write handoff state (agent mode only)

Implementations

impl Runtime

pub fn reset_context_continuation( &self, session_id: &str, messages: &[Arc<Value>], )

Bind continuation bookkeeping to a newly loaded/cleared conversation. Authority and opt-in configuration remain runtime-owned. Never carry a previous conversation’s model-authored note or phase into the next one.

pub fn context_management_enabled(&self) -> bool

pub fn context_management_status(&self) -> String

pub fn context_management_command(&self, arg: &str) -> Result<String, String>

impl Runtime

pub fn cache_keepwarm_ineligibility(&self) -> Option<String>

Why this runtime cannot keep its cache warm, or None when it can. Only the native Anthropic transport carries cache_control; every TTL (5m, 1h, hybrid) and every thinking mode is supported.

pub fn cache_anchor(&self) -> Option<CacheAnchor>

The last accepted Anthropic request of this runtime’s request chain.

pub fn cache_ttl_downgraded(&self) -> bool

The session’s silent 1h→5m downgrade latch has fired: the server honours only 5m whatever the configured TTL says.

pub fn cache_1h_honoured(&self) -> bool

A request of this session has written a 1h cache entry.

pub async fn cache_keepwarm_probe( &self, history: &[Arc<Value>], ) -> Result<KeepWarmProbe, RuntimeError>

Probe the ping the next real turn would justify for history (see the module docs): its prefix fingerprint, its worst-case output, and whether the next turn would roll the context over first. Builds the request through the real builder and returns before anything is sent; no network I/O.

pub async fn cache_keepwarm_ping( &self, history: &[Arc<Value>], expect: u64, cancel: &CancellationToken, tap: &PingTap, ) -> PingReport

Send ONE keep-warm ping for history (the session’s durable history, unchanged) if its freshly built prefix still hashes to expect. Never mutates history, the runtime’s session state, or any persisted state; fires no extension hooks; emits nothing to any frontend. tap sees the request leave and its usage arrive while it runs.

impl Runtime

pub async fn new() -> Result<Runtime, RuntimeError>

pub fn set_system_prompt(&mut self, prompt: String)

pub fn system_prompt(&self) -> Option<&str>

pub async fn effective_system_prompt(&self) -> Option<String>

The system prompt that actually goes on the wire for the next request: the configured base plus any builtin orchestration adapter (see agent_core::prompt::builtin_orchestration_adapters) selected by the current model identity, so the doctrine follows mid-session model switches. Composition is skipped when:

• a typed prompt manifest is active — the manifest author owns the full stack;
• the runtime exposes no subagent tools (worker runtimes) — the doctrine would be unactionable noise;
• the model identity cannot be canonicalized — fail closed to the unmodified base.

pub async fn frozen_tool_catalog(&self) -> Option<String>

The progressive-disclosure catalog of activatable tools for the system prompt, frozen per session (see tool_catalog_prompt). None when progressive disclosure is off, model-initiated activation is denied, the runtime cannot activate tools (workers), or nothing outside the session core is activatable.

pub fn effective_prompt(&self) -> Option<&PromptStack>

pub fn prompt_generation(&self) -> u64

pub fn retain_prompt_reload_source( &mut self, manifest: PathBuf, context: SelectionContext, user_module: Option<PromptModule>, delegation_policy_digest: Option<String>, )

pub fn reload_prompt(&mut self) -> Result<u64, PromptError>

Recompile retained manifest inputs, validate, then atomically install the candidate.

pub fn apply_prompt_stack( &mut self, candidate: PromptStack, ) -> Result<u64, PromptError>

Atomically validate and install a compiled stack. Failed validation leaves all state intact.

pub fn prompt_inspection_json(&self) -> Option<String>

pub fn install_mcp_runtime(&mut self, manager: Arc<McpRuntimeManager>)

Install the shared exact MCP lease manager (Task 19, engine boot). Also mints ONE durable session-scope guard for the runtime’s tool session, shared by every clone and stream; only the LAST owner’s drop terminates leases.

pub fn set_turn_budget(&mut self, budget: TurnBudget)

Set this runtime’s per-turn budget (Task 23). The engine resolves role + typed config at boot; subagent/watcher constructions pass their role’s budget explicitly.

pub fn turn_budget(&self) -> &TurnBudget

The currently configured per-turn budget.

pub fn install_extension_runtime( &mut self, manager: Arc<ExtensionRuntimeManager>, )

Install the shared exact EXTENSION lease manager (Task 20, engine boot). Also mints ONE durable session-scope guard for the runtime’s tool session, shared by every clone and stream; only the LAST owner’s drop terminates leases.

pub fn install_orchestration(&mut self, runtime: Arc<OrchestrationRuntime>)

pub fn install_worker_orchestration( &mut self, runtime: Arc<OrchestrationRuntime>, )

A runtime spawned for a worker shares only this session’s bounded dispatch/tree authority. It must not replay process-global favorite models: doing so would turn a child construction into a fresh grant source. The child can dispatch only identities already authorized by this installed session policy.

pub fn subagent_limits(&self) -> SubagentLimits

The subagent.* limits this runtime sizes delegation policies with.

pub fn set_delegation_parent(&mut self, parent: Option<String>)

pub fn orchestration(&self) -> Option<&Arc<OrchestrationRuntime>>

pub fn grant_worker_model(&self, model: &str) -> Result<(), String>

Extends the live session delegation policy with one explicitly user-trusted worker model (e.g. favorited mid-session in the models picker). Mid-session trust grants were always meant to be honored; the policy snapshot is not pinned against user decisions.

pub fn set_model(&mut self, model: String) -> Option<ReasoningClamp>

Infallible model change. Returns the reasoning clamp applied (if any) when the current level is not supported by the new model; errors from try_set_model are swallowed (model left unchanged).

pub fn try_set_model( &mut self, model: String, ) -> Result<Option<ReasoningClamp>, String>

Apply a model change while preserving orchestration lifecycle invariants. Returns an error instead of mutating either model or policy when active workers still require collection/reconciliation or when the replacement foreground cannot produce a trusted manifestless policy snapshot. On success, returns Some(ReasoningClamp) when an explicit reasoning level had to be substituted because the new model does not support it.

pub fn set_tools(&mut self, tools: ToolRegistry)

pub fn subagent_registry(&self) -> &Arc<Mutex<SubagentRegistry>>

pub fn event_queue(&self) -> &Arc<EventQueue>

pub fn set_event_queue(&mut self, queue: Arc<EventQueue>)

Install a session-lifetime queue (B3 unpark: the queue outlives the Runtime so synaps send keeps resolving while parked). Must be called before the first turn — in-flight streams hold a clone.

pub fn hook_bus(&self) -> &Arc<HookBus>

Get a shared reference to the extension hook bus.

pub fn session_manager(&self) -> &Arc<SessionManager>

Background shell/PTY sessions owned by this runtime (Checkpoint and Parked close them via shutdown_all).

pub fn host_tool_session_id(&self) -> &SessionId

Runtime-scoped tool-session identity used by the stream execution gate (Task 16). Shared by clones (which share the tool registry); fresh per independently constructed Runtime.

pub fn set_session_id(&mut self, id: Option<String>)

Conversation/session identity this runtime serves (keys hook injection). None = unkeyed (workers).

pub fn session_id(&self) -> Option<&str>

pub fn set_cwd(&mut self, cwd: Option<PathBuf>)

Per-session working directory handed to tools via ToolCapabilities.cwd. None = process cwd.

pub fn cwd(&self) -> Option<&Path>

pub fn set_env(&mut self, env: Option<Vec<(String, String)>>)

Per-session environment snapshot handed to tools via ToolCapabilities.env. None = inherit process env.

pub fn set_env_stripped(&mut self, stripped: Vec<String>)

pub fn env(&self) -> Option<&Vec<(String, String)>>

pub fn env_stripped(&self) -> &[String]

pub fn tools_shared(&self) -> Arc<RwLock<ToolRegistry>>

Get a shared reference to the tool registry (for MCP lazy loading).

pub fn model(&self) -> &str

pub fn http_client(&self) -> &Client

pub fn progressive_tool_disclosure(&self) -> bool

Whether this runtime projects a progressive (core-only) tool schema.

pub fn activation_confirm(&self) -> ActivationConfirm

tools.activation_confirm policy in force for this runtime.

pub fn set_activation_confirm(&mut self, mode: ActivationConfirm)

Override the tools.activation_confirm policy (hosts/tests that do not go through apply_config).

pub fn set_thinking_budget(&mut self, budget: u32)

pub fn set_reasoning_level(&mut self, level: ReasoningLevel)

Set the named reasoning level (config/restore path). Updates thinking_budget from the level’s canonical budget when one exists; for Max/Ultra (no numeric budget), leaves thinking_budget unchanged. Marks explicit_reasoning = false — use set_reasoning_level_explicit for user commands and settings.

pub fn set_reasoning_level_explicit(&mut self, level: ReasoningLevel)

Set the named reasoning level as an explicit user choice (slash commands, settings panel). Identical to set_reasoning_level but sets explicit_reasoning = true so that a subsequent set_model call does not overwrite the level with the new model’s default.

pub fn restore_session_reasoning( &mut self, thinking_level: &str, ) -> Option<ReasoningClamp>

Restore a saved session’s thinking_level string as an explicit user choice, then clamp it against the current model. Call after set_model(session.model): re-applying the saved level would otherwise undo the clamp set_model performed (old grok+xhigh session files). Returns the clamp applied, if any, so callers can surface it.

pub fn set_thinking_budget_explicit(&mut self, budget: u32)

Set a custom numeric thinking budget as an explicit user choice (e.g. /thinking 8192). Retains the exact budget in thinking_budget while syncing named_level to the nearest named level for display. Sets explicit_reasoning = true.

pub fn is_reasoning_explicit(&self) -> bool

Expose the explicit_reasoning provenance flag (test/introspection).

pub fn thinking_budget_raw(&self) -> u32

Raw thinking budget value (for testing and legacy request building).

pub fn set_reasoning_level_checked( &mut self, level: ReasoningLevel, ) -> Result<(), String>

Validate level against the current model’s capability metadata via the shared per-provider validator (cache then exact static tables), then apply it. Returns Err(user-facing message) and leaves runtime state unchanged if the level is unsupported.

pub fn set_thinking_budget_checked(&mut self, budget: u32) -> Result<(), String>

Validate then apply a custom numeric thinking budget (/thinking <N>). The budget’s derived ReasoningLevel runs through the same exact-model mutation validator as named levels (Anthropic fixed-budget models pass: derived levels never exceed XHigh and thinking-capable descriptors accept them). On Ok the exact budget is retained — never downgraded to a named-level canonical budget. On Err state is unchanged.

pub fn reasoning_level(&self) -> ReasoningLevel

pub fn set_compaction_model(&mut self, model: Option<String>)

pub fn set_compaction_mode(&mut self, mode: CompactionMode)

Set where compaction summarization runs (spec §9.4).

pub fn set_compaction_exclusions(&mut self, exclude: Vec<ContentClass>)

Set the content classes withheld from remote compaction disclosure.

pub fn remote_summarization_attempts(&self) -> u64

Number of times the remote-summarization transport seam was entered (CP-12 M3). Local-only compaction must leave this at zero.

pub fn compaction_policy(&self) -> DisclosurePolicy

The session’s compaction disclosure policy (spec §9.4) — consumed by runtime::compaction for both the preview and the dispatch path.

pub fn set_context_window(&mut self, window: Option<u64>)

pub fn compaction_model(&self) -> &str

Effective context window for the current model — user override if set, otherwise the model’s native window from models::context_window_for_model.

pub fn context_window(&self) -> u64

pub async fn assess_context(&self, messages: &[Arc<Value>]) -> ContextAssessment

Task 29 (spec §9.1): the ONE request-aware context assessment every frontend consumes on its compaction trigger path. Reads the segments the next request will actually carry — the effective system prompt, the exposed tool-schema set, the supplied history — and the runtime’s configured reserves (thinking budget, tool-result cap, model output reserve, provider window with the documented safety margin).

Skill bodies that reach the request do so through the system prompt or history today, so they are already accounted there; the skill lane is fed once loaders hand the engine distinct segments. The memory lane is live as of task A7: a validated recall segment held for the current turn is charged to ContextBreakdown::memory_tokens (spec §10.3 — memory competes for budget headroom only, never reserves).

pub fn memory_recall_why(&self) -> Option<RecallTurnMetadata>

Task B4 (spec §10.4): explainability metadata retained for the current turn’s accepted recall, if any. Metadata only — selected IDs, source classes, rank reasons, byte/token accounting, latency, and withheld/skipped counts; never memory content. Rendered for /memory why by memory_context::render_recall_why (task B5).

pub fn apply_memory_backend_config(&mut self, config: &MemoryBackendConfig)

Bind standalone host entry points without applying unrelated settings.

pub fn memory_backend_is_axel(&self) -> bool

True when legacy note/history/provider access is forbidden by the host selection, including invalid or unavailable backend configuration. Whether the project forum is live for this runtime (Axel backend). Workers use it to decide whether forum guidance belongs in the prompt.

pub fn memory_backend_exclusive(&self) -> bool

pub fn memory_tool_capability(&self) -> Option<MemoryContextCapability>

pub fn apply_config(&mut self, config: &SynapsConfig)

Apply a parsed config file to this runtime (model, thinking budget, etc.) Includes the disabled_tools pass on this runtime’s registry — the fresh-Runtime::new() path, where the registry holds builtins only.

pub fn apply_auth_config(&mut self, config: &SynapsConfig)

Apply only the credential-source portion of config. Used by subagent spawns that build a fresh Runtime::new() (which defaults to Local) and must inherit the user’s Remote/broker setup. (#158 A3)

A6: invalidates the token cache if the source/endpoint changed. A2: scrubs AuthState when Remote so no local auth.json credential is used or held (invariant 1).

pub fn thinking_budget(&self) -> u32

pub fn max_tool_output(&self) -> usize

pub fn bash_timeout(&self) -> u64

pub fn bash_max_timeout(&self) -> u64

pub fn subagent_timeout(&self) -> u64

pub fn api_retries(&self) -> u32

pub fn set_max_tool_output(&mut self, v: usize)

pub fn set_bash_timeout(&mut self, v: u64)

pub fn set_bash_max_timeout(&mut self, v: u64)

pub fn set_subagent_timeout(&mut self, v: u64)

pub fn set_api_retries(&mut self, v: u32)

pub fn telemetry_level(&self) -> TelemetryLevel

pub fn set_telemetry_level(&mut self, level: TelemetryLevel)

pub fn trace_context(&self) -> TraceContext

The session trace context handed to every request (cheap clone).

pub fn trace_arm_next(&self, with_content: bool)

Arm tracing for exactly the next outgoing provider request (/trace next; with_content adds the one-request redacted content capture for /trace next content).

pub fn trace_status(&self) -> TraceStatusReport

Metadata-only /trace status report: mode, persistence path, counters. Never secrets or content. Also performs the opportunistic expired-capture sweep (B2): status is a trace interaction, so stale content-capture bundles are physically removed here too.

pub fn memory_context_status(&self) -> MemoryContextStatus

Typed /memory status snapshot — metadata-only, never spawns a provider process (spec §7.2 “status does not spawn”).

pub fn memory_context_disable(&self) -> MemoryContextStatus

Revoke this session’s memory context (/memory off). Always locally allowed (spec §7.2); idempotent — disabling an already-off session reports Off.

Task A6 revocation wiring: after the session state transition, the extension runtime lease backing each bound provider is defensively revoked through the SAME ExtensionRuntimeManager mechanism the deferred tool/handler lifecycle uses (Self::install_extension_runtime / ExtensionSessionEndGuard). While Phase A never spawns, this is an idempotent no-op; once Phase B routes real recall/capture calls under this runtime’s tool session, disable reaps the provider child exactly.

pub fn memory_history_preview( &self, ) -> Result<HistoryImportPreview, HistoryImportError>

Return the history-import disclosure preview. This is D1’s production entry point: metadata is scanned, but session bodies and Axel are never opened. All frontends share this runtime implementation.

pub fn context_report(&self, history: Option<&[Arc<Value>]>) -> ContextReport

Structured /context report (Task 12): counts, byte lengths, cache change/reuse estimates, and writer counters — never content.

history is the conversation owned by the calling surface (TUI / headless); when it is not provided the history lines honestly read unavailable rather than fabricating zeros. Loaded skills/memories are session-surface state the runtime cannot enumerate, so they are reported unavailable with that provenance.

pub fn telemetry_writer(&self) -> Option<TelemetryWriter>

The shared observability writer, when telemetry is enabled.

pub fn shutdown_observability( &self, timeout: Duration, ) -> Option<ShutdownOutcome>

Bounded shutdown flush of the observability writer: stop intake, drain until timeout, return typed stats (None when telemetry is off). Sync and bounded — safe from shutdown paths that cannot await; async callers should use Self::shutdown_observability_async.

Semantics (Task 11):

• telemetry off → no writer exists → None, a true no-op;
• “flushed” means every queued record was appended into OS file buffers (write(2) returned) — deliberately no fsync, these are best-effort diagnostic logs;
• on timeout the worker stays detached and keeps draining in the background; the caller logs metadata-only stats and continues — trace loss must never fail or abort a clean exit.

pub async fn shutdown_observability_async( &self, timeout: Duration, ) -> Option<ShutdownOutcome>

Async epilogue helper for every clean process/runtime exit path that owns a Runtime (headless chat, TUI teardown, autonomous agent, RPC/server graceful shutdown): clones the writer handle and runs the bounded Self::shutdown_observability on the blocking pool, so an executor thread is never parked. Same None/no-fsync/timeout semantics as the sync variant. Idempotent — a second call finds the intake already closed and returns immediately.

Note: the writer is shared across Runtime clones (subagents). Call this only from the session owner’s exit epilogue, after in-flight work has drained — cloned runtimes still serving requests would see their subsequent records counted as drops.

pub fn cache_diagnostics(&self) -> bool

pub fn set_cache_diagnostics(&mut self, v: bool)

pub fn cache_ttl(&self) -> CacheTtl

pub fn share_ttl_latches(&mut self, parent: &Runtime)

Thread a parent runtime’s TTL atomics onto this (cloned) runtime so that a driver-owned turn shares the session’s single downgrade latch instead of firing a redundant 1h→5m notice.

pub fn set_cache_ttl(&mut self, ttl: CacheTtl)

Change the cache TTL strategy mid-session. The next request re-marks with the new TTL; the old prefix expires naturally (single-last strategy never prunes old markers, so no invalidation logic needed).

pub fn thinking_level(&self) -> &str

pub async fn refresh_if_needed(&self) -> Result<(), RuntimeError>

Check if the OAuth token is expired and refresh it if needed.

pub async fn compact_call( &self, messages: Vec<Arc<Value>>, ) -> Result<String, RuntimeError>

Make a simple non-streaming API call for compaction (no tools).

Uses a dedicated summarization system prompt (not the user’s), omits all tools, and returns the raw text response. Caller supplies the full message array including the serialized conversation.

pub async fn run_single(&self, prompt: &str) -> Result<String, RuntimeError>

Run a single prompt synchronously (non-streaming). Handles tool execution internally, looping until the model produces a final text response.

pub async fn run_stream( &self, prompt: String, cancel: CancellationToken, ) -> Pin<Box<dyn Stream<Item = StreamEvent> + Send>>

Run a prompt as a cancellable stream of StreamEvents. Convenience wrapper around [run_stream_with_messages] for single-turn usage.

pub async fn run_stream_with_messages( &self, messages: Vec<Arc<Value>>, cancel: CancellationToken, steering_rx: Option<UnboundedReceiver<String>>, secret_prompt: Option<SecretPromptHandle>, auto_approve_confirms: bool, ) -> Pin<Box<dyn Stream<Item = StreamEvent> + Send>>

Run a multi-turn conversation as a cancellable stream of StreamEvents. This is the main entry point for chat UIs and agents. Handles tool execution, API retries, and dynamic tool registration (MCP) internally.

pub async fn run_stream_tracked( &self, messages: Vec<Arc<Value>>, cancel: CancellationToken, steering_rx: Option<UnboundedReceiver<String>>, secret_prompt: Option<SecretPromptHandle>, auto_approve_confirms: bool, completion: TurnCompletion, ) -> Pin<Box<dyn Stream<Item = StreamEvent> + Send>>

Runtime::run_stream_with_messages that also reports, through completion, whether the turn reached its normal end (see TurnCompletion).

Trait Implementations

impl Clone for Runtime

fn clone(&self) -> Runtime

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Drop for Runtime

The owning runtime stops its shell-session reaper when it goes away (clones carry None). Without this every dropped Runtime — a parked session, a finished worker — left a 30 s ticker holding the manager.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl RuntimeRead for Runtime

fn model(&self) -> &str

fn thinking_level(&self) -> &str

fn reasoning_level(&self) -> ReasoningLevel

fn is_reasoning_explicit(&self) -> bool

fn thinking_budget(&self) -> u32

fn context_window(&self) -> u64

fn system_prompt(&self) -> Option<&str>

fn compaction_model(&self) -> &str

fn api_retries(&self) -> u32

fn subagent_timeout(&self) -> u64

fn max_tool_output(&self) -> usize

fn bash_timeout(&self) -> u64

fn bash_max_timeout(&self) -> u64

fn prompt_inspection_json(&self) -> Option<String>

RuntimeView: cached at snapshot time.