Struct Runtime 

pub struct Runtime { /* private fields */ }

The batteries-included runtime. See the module docs for the three verbs.

Implementations

impl Runtime

pub fn new(store: Arc<dyn EventStore>) -> Self

A runtime over store with the default clock and OS randomness.

pub fn with_hooks( store: Arc<dyn EventStore>, clock: ClockFn, random: RandomFn, ) -> Self

A runtime with an injected clock and random source, handed to every RunCtx it builds. Deterministic tests inject fixed functions so full event logs compare equal across runs.

pub fn with_record_prompts(self, record_prompts: bool) -> Self

Turns on recording of the full model request body for every run this runtime drives, passed through to each RunCtx it builds. Off by default. Chained builder style so new/with_hooks keep their signatures and every existing caller stays at off.

This is PII-sensitive (the body may hold user data or secrets), which is why it is off unless an operator opts in. See RunCtx::with_record_prompts for what recording means and the guarantee that it does not affect replay.

pub fn with_labels(self, labels: BTreeMap<String, String>) -> Self

Sets the correlation tags every run this runtime drives stamps on its RunStarted, passed through to each RunCtx it builds. Unset by default. Chained builder style, mirroring with_record_prompts; see RunCtx::with_labels for the bounds that apply and when they are checked.

pub async fn start( &self, agent: &Agent, input: Value, ) -> Result<RunOutcome, RuntimeError>

Starts a fresh run of agent with input, under a newly minted run id.

Errors

Everything start_with_id returns.

pub async fn start_with_id( &self, agent: &Agent, run_id: RunId, input: Value, ) -> Result<RunOutcome, RuntimeError>

Starts a fresh run under a caller-chosen run id (tests use this to make logs comparable across control and killed runs).

Errors

RuntimeError::RunAlreadyStarted when the id already has history; otherwise whatever the loop surfaces (RuntimeError::Store, RuntimeError::Model, RuntimeError::Replay, …).

pub async fn recover( &self, agent: &Agent, run_id: RunId, ) -> Result<RunOutcome, RuntimeError>

Re-drives an interrupted run: replays the recorded log, then continues live from the first unrecorded step. This is the post-crash verb; it supplies no new input.

Errors

RuntimeError::UnknownRun when the id has no history; RuntimeError::Replay(ReplayError::NeedsReconciliation) when the log ends in a write intent with no completion (a human must resolve it); RuntimeError::Replay on any divergence.

pub async fn resume( &self, agent: &Agent, run_id: RunId, input: Value, ) -> Result<RunOutcome, RuntimeError>

Resumes a parked run with input.

The run must be parked: its derived status must be Suspended or BudgetExceeded. The input is validated before anything is recorded: a suspension validates against its recorded input_schema, a budget crossing against the extension shape. On success, the loop re-drives the run; the input is recorded as Resumed at the parked position and becomes the pending tool’s result (or the budget extension).

Errors

RuntimeError::UnknownRun, RuntimeError::NotParked, or RuntimeError::ResumeInputRejected; then whatever the loop surfaces.

pub async fn resolve( &self, run_id: RunId, output: Value, ) -> Result<RunId, RuntimeError>

Records, by hand, the completion of a dangling Write intent, after a human has verified externally what the write did.

This is the concrete form of human resolution. A crash between a write’s recorded intent and its completion derives to RunStatus::NeedsReconciliation, which every automatic verb refuses: the write may or may not have reached its target, and the runtime will not guess. Once a human has checked, resolve appends the completion they observed (or the completion of the write they performed by hand), so replay treats the call as done and never re-executes it. The run is then recoverable through recover like any other.

It takes the same care as resume: the state is validated before anything is written, and exactly one event is appended. output is recorded verbatim as the tool’s output; nothing executes and nothing else is driven.

Errors

RuntimeError::UnknownRun when the id has no history; RuntimeError::NotReconcilable when the run’s log does not end at a dangling write intent (so there is no completion to record); RuntimeError::Store when the append fails.

pub async fn abandon( &self, run_id: RunId, reason: Option<String>, ) -> Result<RunId, RuntimeError>

Abandons a run: appends a terminal Event::RunAbandoned by hand, retiring a run deliberately without finishing or failing it.

An operator action, not a driver action. It executes nothing, drives nothing, and needs no lease: abandonment is the sanctioned “we do not care about this run anymore” path, appended straight to the log the way resolve appends its one completion. It is allowed for any non-terminal run, whatever state it parked or crashed in.

When the run is parked at a dangling write (status RunStatus::NeedsReconciliation), the outstanding intent’s position and tool ride on the event as unresolved_write. The abandonment never claims the write question was answered: it records exactly which write was left unsettled, so the honesty the reconciliation refusal carried is preserved in the terminal record rather than erased.

Errors

RuntimeError::UnknownRun when the id has no history; RuntimeError::AlreadyTerminal when the run already reached a terminal event (completed, failed, or previously abandoned), so there is nothing left to retire; RuntimeError::Store when the append fails.