@statelyai/agent 2.0.0-alpha.26 → 2.0.0-alpha.28

package/dist/{run-agent-CG343kFs.d.mts → run-agent-ByO-Bxyd.d.cts}

@@ -1,7 +1,8 @@
-import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-tA3SdczG.mjs";
-import { G as AgentRequestOptions, K as AgentRequestSource, M as AgentDecisionRequest, U as AgentEventDescriptor, Z as AgentError, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, p as AgentTextResult, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-hZSiRUo1.mjs";
-import { c as AgentLogEntry, n as AgentEventLogStore } from "./event-log-store-DxyVgnas.mjs";
+import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-hR5f5YXa.cjs";
+import { K as AgentRequestSource, M as AgentDecisionRequest, U as AgentEventDescriptor, Z as AgentError, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-IjfYy9DP.cjs";
+import { c as AgentLogEntry, n as AgentEventLogStore } from "./event-log-store-2xzFmgr2.cjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom } from "xstate";
+import { DurableExecution } from "xstate/durable";
 
 //#region src/usage.d.ts
 /** Reserved event delivered after a model call reports token usage. */
@@ -17,11 +18,6 @@ interface AgentUsageEvent extends EventObject {
   name?: string;
 }
 //#endregion
-//#region src/internal/registry.d.ts
-type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actors"> & {
-  models?: object;
-};
-//#endregion
 //#region src/steps.d.ts
 /**
  * A pending text request surfaced by step discovery ({@link getAgentRequests}
@@ -41,88 +37,13 @@ interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
 }
 /** `AgentStep.requests` element: a text or decision request. */
 type AgentStepRequest = AgentRequest | AgentDecisionRequest;
-/**
- * One checkpoint on the step path: the machine's current snapshot, the
- * executable actions that produced it, the pending
- * {@link AgentStepRequest}s (text/decision work still to resolve), and
- * whether the machine has reached a final state. Produced by
- * {@link initialAgentStep}, {@link transitionAgentStep},
- * {@link resolveAgentStep}, and {@link rejectAgentStep}.
- */
-interface AgentStep<TSnapshot extends AnyMachineSnapshot = AnyMachineSnapshot> {
-  snapshot: TSnapshot;
-  actions: readonly {
-    type?: string;
-    params?: unknown;
-  }[];
-  requests: AgentStepRequest[];
-  done: boolean;
-}
-/**
- * Starts a machine and returns its first {@link AgentStep} — the step-path
- * equivalent of `initialTransition` plus request discovery. Begins the
- * durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
- * (via {@link executeAgentRequest} for `kind: 'text'`, or
- * {@link resolveDecision} for `kind: 'decision'`), then advance with
- * {@link resolveAgentStep} or {@link transitionAgentStep}.
- */
-declare function initialAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, input?: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
-/**
- * Applies an externally-sent event (e.g. a decision's chosen event, or a
- * human's reply) and returns the next {@link AgentStep}. Accepts **either**
- * a raw snapshot **or** a prior `AgentStep` as the second argument —
- * `.snapshot` is unwrapped automatically, so callers can thread the whole
- * step object through without manually plucking the snapshot out.
- */
-declare function transitionAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, snapshotOrStep: SnapshotFrom<TMachine> | AgentStep<SnapshotFrom<TMachine>>, event: EventFromLogic<TMachine>, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
-/**
- * Applies a resolved text request's output (a `kind: 'text'`
- * {@link AgentRequest} — not a decision) as a done event and returns the
- * next {@link AgentStep}. For decisions, resolve with `resolveDecision`
- * (which returns a {@link ChosenEvent}) and apply it with
- * {@link transitionAgentStep} instead — a decision has no output value of
- * its own to feed here.
- */
-declare function resolveAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, request: Pick<AgentRequest, "id"> | string, output: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
-/**
- * Rejects a pending invoke — the failure counterpart of
- * {@link resolveAgentStep}. Delivers `error` as the invoke's
- * `xstate.error.actor` event, so the machine takes that invoke's `onError`
- * transition and returns the next {@link AgentStep}. With no `onError` in
- * scope the returned step's snapshot has `status: 'error'`, exactly as a live
- * run's failed invoke does.
- *
- * A durable host replays a failed call with this: the log says the call
- * failed, so the replay rejects the invoke instead of resolving it. Scripted
- * playthroughs use it too — see `simulateAgent`'s `script.errors`.
- *
- * `error` can be any value. An `Error` instance is the usual one, but a plain
- * object (`{ code: 'truncated' }`) reaches the `onError` transition as
- * `event.error` untouched, so a machine that branches on a failure code is
- * testable without constructing a provider's error class.
- */
-declare function rejectAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, request: Pick<AgentRequest, "id"> | string, error: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
-/**
- * Resolves one **text** request ({@link AgentRequest}, from
- * {@link AgentStep.requests}) against a host's {@link AgentRequestExecutors}
- * — merges the request's tools, dispatches to `generateText`/`streamText`
- * per `mode`, and validates the result against the request's
- * `outputSchema` if present. **Text-only**: passing a `kind: 'decision'`
- * request throws, directing the caller to `resolveDecision(request,
- * executors, ...)` instead. Returns the invoke's output — `{ result,
- * messages }`, ready for {@link resolveAgentStep} — plus the `raw` executor
- * result (tool calls, usage, finish reason).
- */
-declare function executeAgentRequest(request: AgentStepRequest, executors: Partial<AgentRequestExecutors>): Promise<AgentTextResult & {
-  raw: unknown;
-}>;
 //#endregion
 //#region src/run-agent.d.ts
 type JsonValue = string | number | boolean | null | JsonValue[] | {
   [key: string]: JsonValue;
 };
 /**
- * Thrown by {@link runAgent} when a resume is given BOTH an `events` log and a
+ * Thrown by {@link AgentRuntime.start} when a resume is given BOTH an `events` log and a
  * `snapshot` that claims a position in that log (`agentMeta.logIndex`), and the
  * two disagree about the state at that position. The log is the source of
  * truth, so this is a host bug (a snapshot cached from a different lineage, or
@@ -136,10 +57,10 @@ declare class AgentSnapshotDivergedError extends AgentError {
   constructor(expected: string, actual: string, logIndex: number);
 }
 /**
- * The stamp {@link RunAgentResult.persist} writes onto the persisted snapshot:
+ * The stamp {@link AgentRunResult.persist} writes onto the persisted snapshot:
  * the machine identity that produced it plus the position in the event log it
  * caches. Read back by the next resume to decide whether the snapshot can be
- * trusted without replaying the log (see {@link RunAgentOptions.events}).
+ * trusted without replaying the log (see {@link AgentRunStart.events}).
  */
 interface AgentRunMeta {
   machineId: string;
@@ -149,13 +70,13 @@ interface AgentRunMeta {
   /** The log's length at the moment this snapshot was taken. */
   logIndex: number;
 }
-/** Typed root-machine transition observer accepted by {@link runAgent}. */
+/** Typed root-machine transition observer accepted by {@link createAgentRuntime}. */
 type AgentTransitionHandler<TMachine extends AnyStateMachine> = (snapshot: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine>) => void;
 /**
  * The version of the {@link AgentTraceEvent} envelope every trace event carries
  * as `schemaVersion`. Bumped only on a breaking change to the envelope or any
  * payload shape, so a consumer can gate on it. Emitted identically by
- * {@link runAgent}, {@link provideExecutors}' `onTrace`, and
+ * {@link createAgentRuntime}, {@link provideExecutors}' `onTrace`, and
  * {@link traceTransitions}.
  */
 declare const AGENT_TRACE_SCHEMA_VERSION = 1;
@@ -185,7 +106,7 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   reasoning?: string;
   /** This call's token usage, lifted off the raw executor result's `usage`.
    * Present only when the executor reported it. The run-level total is
-   * {@link RunAgentResult.usage}. */
+   * {@link AgentRunResult.usage}. */
   usage?: AgentCallUsage;
   /** Why the call stopped, lifted off the raw executor result's
    * `finishReason` and normalized. Present only when the executor reported
@@ -208,7 +129,7 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   event: EmittedFrom<TMachine>;
 } | {
   /** A reserved `@agent.usage` event the run declined to deliver. The
-   * tokens still fold into {@link RunAgentResult.usage}; only the machine
+   * tokens still fold into {@link AgentRunResult.usage}; only the machine
    * event is dropped. */
   type: "usage.dropped";
   event: AgentUsageEvent; /** `'settled'`: the call settled after the run's cycle had resolved. */
@@ -225,7 +146,7 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
 } | {
   type: "run.end";
   status: "error";
-  cause: RunAgentErrorCause;
+  cause: AgentRunErrorCause;
   error: unknown;
   snapshot: SnapshotFrom<TMachine>;
 }));
@@ -283,63 +204,27 @@ declare function serializeTraceEvent(event: AgentTraceEvent, options?: {
   includeRaw?: boolean;
 }): JsonSerializableTraceEvent;
 /**
- * Options for {@link runAgent}.
+ * Options for {@link createAgentRuntime}: what the runtime binds and observes.
+ * The run's `input`/`snapshot`/`events` go to {@link AgentRuntime.start} (or
+ * {@link runToQuiescence}) instead.
  *
  * Host executors are passed as a single {@link AgentRequestExecutors}-shaped
- * set under `executors` (the same shape the step path takes). Each executor
+ * set under `executors`. Each executor
  * kind is required only if the machine actually reaches a request of that kind
  * — checked at bind time, before any actor runs. The whole `executors` field is
  * optional: a machine whose agent sources all carry their own executor
  * (`.withExecutor(...)`) needs none.
  */
-interface RunAgentOptions<TMachine extends AnyStateMachine> {
+interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
   /**
    * The host executor set backing the machine's agent actors — build it with
    * `createAiSdkExecutors({ models })` from '@statelyai/agent/ai-sdk', or supply
    * `{ generateText?, streamText?, decide? }` by hand. Every slot is optional
-   * here (unlike the step path's {@link AgentRequestExecutors}): each kind is
+   * here: each kind is
    * bind-time-checked only when the machine actually reaches a request of that
    * kind, so e.g. a stream-only machine may pass `{ streamText }` alone.
    */
   executors?: Partial<AgentRequestExecutors>;
-  /**
-   * Machine input. Validated against the machine's declared input schema —
-   * defaults filled, transforms applied — before it reaches
-   * `createActor(machine, { input })`; invalid
-   * input throws an {@link AgentError} with code `invalid-machine-input`.
-   * Typed as {@link AgentInputFrom}, so fields the schema defaults are optional
-   * here. Omit when resuming via `snapshot`.
-   */
-  input?: AgentInputFrom<TMachine>;
-  /** A previously-settled run's `result.persist()`, to resume from instead of starting fresh. Pair with `event` to deliver the event that unblocks the resumed idle state. */
-  snapshot?: Snapshot<unknown>;
-  /**
-   * An event to send immediately after starting/resuming the actor (e.g. the
-   * human's answer to an idle-state prompt), typed as the machine's event
-   * union. If the resumed state has no transition for it, the machine ignores
-   * it — the run settles normally and the result carries
-   * {@link RunAgentResult.ignored}. For a payload off the wire, parse it first
-   * with `parseAgentEvent(machine, payload)`.
-   */
-  event?: EventFromLogic<TMachine>;
-  /**
-   * A prior run's `result.events` — the replayable log to resume from and keep
-   * appending to. THE LOG IS THE SOURCE OF TRUTH: journaled model/tool results
-   * are folded back in rather than re-executed, so a crashed run resumes from
-   * its log alone.
-   *
-   * A `snapshot` passed alongside is a CACHE of that log: it is trusted only
-   * when it is stamped (see {@link AgentRunMeta}) at the log's current tail and
-   * hashes to what the tail entry recorded; otherwise the log is replayed and
-   * the cache is verified against the position it claims (a genuine
-   * disagreement throws {@link AgentSnapshotDivergedError}).
-   *
-   * When the log was written by a DIFFERENT machine version, a `snapshot` is
-   * required (XState's own `migrate` applies on restore) and the run starts a
-   * NEW log segment whose init entry records where it bridged from; without one
-   * it throws `AgentMachineVersionMismatchError`.
-   */
-  events?: readonly AgentLogEntry[];
   /**
    * Durable log storage, write-ahead. With a `store` the run reads the thread's
    * log to resume from (unless `events` is given, which wins) and writes every
@@ -349,15 +234,15 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * write (an {@link AgentEventLogConflictError} from a concurrent writer, or
    * any other failure) stops the run: `{ status: 'error', cause: 'journal' }`.
    *
-   * Requires {@link RunAgentOptions.threadId}.
+   * Requires {@link AgentRuntimeOptions.threadId}.
    */
   store?: AgentEventLogStore;
-  /** The {@link RunAgentOptions.store} thread this run reads and appends to. Required whenever `store` is given. */
+  /** The {@link AgentRuntimeOptions.store} thread this run reads and appends to. Required whenever `store` is given. */
   threadId?: string;
   /**
    * Called synchronously as each log entry is appended, init entry first. An
    * observer, never awaited: persisting here is at-least-once and the run does
-   * not wait for it. Use {@link RunAgentOptions.store} for write-ahead
+   * not wait for it. Use {@link AgentRuntimeOptions.store} for write-ahead
    * durability.
    */
   onEvent?: (entry: AgentLogEntry) => void;
@@ -437,23 +322,26 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
   maxModelCalls?: number;
   /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
   signal?: AbortSignal;
+  /** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
+  timers?: AgentTimerScheduler;
 }
 /**
- * The outcome of a {@link runAgent} call — always exactly one of three
- * variants, never a throw for a waiting or failed machine (programmer
- * errors like a missing executor still throw, at bind time before any actor
- * runs). `done`: a final state was reached (`output` is the machine's
- * `OutputFrom`). `idle`: the run settled with no in-flight work — resume by
- * calling `runAgent` again with `{ snapshot, event }`. `error`: a run-level
+ * The outcome of a run ({@link AgentRuntime.finish} / {@link runToQuiescence})
+ * — always exactly one of three variants, never a throw for a waiting or
+ * failed machine (programmer errors like a missing executor still throw,
+ * synchronously from {@link createAgentRuntime} before any actor runs).
+ * `done`: a final state was reached (`output` is the machine's `OutputFrom`).
+ * `idle`: the run went quiescent (no child, request or in-process timer in
+ * flight) — resume with a new runtime and `{ snapshot, event }`. `error`: a run-level
  * failure, discriminated by `cause` (`'aborted'`, `'max-model-calls'`,
  * `'decision-exhausted'`, `'machine'` for any other machine error state, or
- * `'stopped'` for an external stop — see {@link RunAgentErrorCause}). Every
+ * `'stopped'` for an external stop — see {@link AgentRunErrorCause}). Every
  * variant carries the final `snapshot` and a native XState persistence
  * function. The
  * underlying actor is stopped on every settle path — there is no live actor to
  * resume; resume is always by snapshot.
  */
-type RunAgentOutcome<TMachine extends AnyStateMachine> = {
+type AgentRunOutcome<TMachine extends AnyStateMachine> = {
   status: "done";
   output: OutputFrom<TMachine>;
   snapshot: SnapshotFrom<TMachine>;
@@ -462,16 +350,16 @@ type RunAgentOutcome<TMachine extends AnyStateMachine> = {
   snapshot: SnapshotFrom<TMachine>;
 } | {
   status: "error";
-  cause: RunAgentErrorCause;
+  cause: AgentRunErrorCause;
   error: unknown;
   snapshot: SnapshotFrom<TMachine>;
 };
-type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine> & {
+type AgentRunResult<TMachine extends AnyStateMachine> = AgentRunOutcome<TMachine> & {
   /**
    * The complete, self-contained replayable log for this run — the resumed
    * prefix (if any) plus every entry this run appended, starting with the
    * reserved `@agent.init` entry. Pass it back as
-   * {@link RunAgentOptions.events} to resume; fold it with
+   * {@link AgentRunStart.events} to resume; fold it with
    * `getUsageFromEvents` for cumulative spend; hand it to `replay` for
    * crash recovery or time travel.
    */
@@ -489,7 +377,7 @@ type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine
    */
   persist(): Snapshot<unknown>;
   /**
-   * Resolves once every {@link RunAgentOptions.store} write issued so far has
+   * Resolves once every {@link AgentRuntimeOptions.store} write issued so far has
    * landed — including a straggler `@agent.usage` entry appended by a call
    * that settled after the run returned, which the result itself does not wait
    * for. Await it before terminating the process if those entries matter.
@@ -508,7 +396,7 @@ type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine
    */
   usage: AgentUsage;
   /**
-   * The {@link RunAgentOptions.event} the machine did not handle: present only
+   * The {@link AgentRunInit.event} the machine did not handle: present only
    * when the resumed state had no transition for it, so sending it was a
    * no-op (no state change, no actions). The run settles normally — usually
    * back to `idle` at the same state — and the event is still journaled, so a
@@ -526,20 +414,20 @@ type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine
   ignored?: EventObject;
 };
 /**
- * Discriminates a {@link RunAgentResult} `error`:
+ * Discriminates a {@link AgentRunResult} `error`:
  * - `'aborted'` — the run's `signal` fired.
  * - `'max-model-calls'` — the `maxModelCalls` budget was exceeded.
  * - `'decision-exhausted'` — the machine reached an error state whose error is
  *   (or wraps) a {@link AgentDecisionExhaustedError} that no `onError` handled.
  * - `'machine'` — any other machine error state.
  * - `'stopped'` — the actor was stopped externally (`status === 'stopped'`).
- * - `'journal'` — a {@link RunAgentOptions.store} write rejected (a concurrent
+ * - `'journal'` — a {@link AgentRuntimeOptions.store} write rejected (a concurrent
  *   writer's {@link AgentEventLogConflictError}, or any other storage failure).
  */
-type RunAgentErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped" | "journal";
+type AgentRunErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped" | "journal";
 /**
  * Thrown into the invoke that would have made the call once
- * {@link RunAgentOptions.maxModelCalls} is spent. It reaches the machine
+ * {@link AgentRuntimeOptions.maxModelCalls} is spent. It reaches the machine
  * through the normal error channel, so an invoke's `onError` can branch on it
  * (`error.code === 'max-model-calls'`, the same string the settled result's
  * `cause` uses) and route to a degraded/finish state instead of failing the
@@ -572,31 +460,150 @@ declare class AgentMaxModelCallsExceededError extends AgentError {
  */
 type AgentInputFrom<TMachine extends AnyStateMachine> = [NonNullable<InputFrom<TMachine>>] extends [WithAgentInputSchema<infer TInputSchema>] ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
 /**
- * Runs an agent machine to completion or idle: a `createActor` host that
- * binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/
- * `DecisionLogic` actor sources, starts (or resumes) the actor, and drives
- * it until it settles — {@link RunAgentResult} `done | idle | error`. Unlike
- * the step helpers ({@link initialAgentStep} etc — a pure
- * transition-at-a-time path for durable hosts), `runAgent` owns a live actor
- * internally; there is no continuation callback, so **idle always settles**
- * and the caller resumes explicitly by passing the settled `{ snapshot,
- * event }` back in. The actor is stopped on every settle path (`done`,
- * `idle`, and `error` alike) — resume is always by snapshot, never by
- * holding a reference to a live actor.
+ * The durable effects one transition produced. Hand them to
+ * {@link AgentRuntime.execute}; nothing in them has run yet.
+ */
+type AgentEffects = Parameters<DurableExecution<AnyStateMachine>["executeEffects"]>[0];
+/**
+ * Where a run's `after` timers live. The default (`"in-process"`) arms them
+ * with `setTimeout` and counts a pending timer as work in flight, so a loop
+ * keeps reading its mailbox until the timer fires. A host with its own
+ * durable timers (a Temporal timer, a Durable Object alarm, an Inngest sleep)
+ * passes `schedule`/`cancel`: the loop then treats a pending timer as the
+ * outside world's business, and the host delivers `{ type: "xstate.timer", id }`
+ * through {@link AgentRuntime.transition} when it fires.
+ */
+type AgentTimerScheduler = "in-process" | {
+  schedule(timer: {
+    id: string;
+    delay: number;
+  }): void;
+  cancel(id: string): void;
+};
+/**
+ * A host-owned timer firing: what a host with its own durable timers (see
+ * {@link AgentTimerScheduler}) delivers when the `id` it was asked to
+ * schedule comes due.
+ */
+interface AgentTimerEvent {
+  type: "xstate.timer";
+  id: string;
+}
+/** How {@link AgentRuntime.start} opens a run. */
+interface AgentRunStart<TMachine extends AnyStateMachine> {
+  /**
+   * Machine input. Validated against the machine's declared input schema —
+   * defaults filled, transforms applied — before it reaches
+   * `createActor(machine, { input })`; invalid
+   * input throws an {@link AgentError} with code `invalid-machine-input`.
+   * Typed as {@link AgentInputFrom}, so fields the schema defaults are optional
+   * here. Omit when resuming via `snapshot`.
+   */
+  input?: AgentInputFrom<TMachine>;
+  /** A previously-settled run's `result.persist()`, to resume from instead of starting fresh. Pair with `event` to deliver the event that unblocks the resumed idle state. */
+  snapshot?: Snapshot<unknown>;
+  /**
+   * A prior run's `result.events` — the replayable log to resume from and keep
+   * appending to. THE LOG IS THE SOURCE OF TRUTH: journaled model/tool results
+   * are folded back in rather than re-executed, so a crashed run resumes from
+   * its log alone.
+   *
+   * A `snapshot` passed alongside is a CACHE of that log: it is trusted only
+   * when it is stamped (see {@link AgentRunMeta}) at the log's current tail and
+   * hashes to what the tail entry recorded; otherwise the log is replayed and
+   * the cache is verified against the position it claims (a genuine
+   * disagreement throws {@link AgentSnapshotDivergedError}).
+   *
+   * When the log was written by a DIFFERENT machine version, a `snapshot` is
+   * required (XState's own `migrate` applies on restore) and the run starts a
+   * NEW log segment whose init entry records where it bridged from; without one
+   * it throws `AgentMachineVersionMismatchError`.
+   */
+  events?: readonly AgentLogEntry[];
+}
+/**
+ * The agent loop's helpers for one run. The host owns the loop:
+ *
+ * ```ts
+ * let [state, effects] = await runtime.start({ input });
+ * await runtime.execute(effects);
+ * for (let event; (event = await runtime.nextEvent()); ) {
+ *   [state, effects] = runtime.transition(state, event);
+ *   await runtime.execute(effects);
+ * }
+ * const result = await runtime.finish();
+ * ```
+ *
+ * `execute` only starts work. Every completion, failure, child message and
+ * timer lands in one mailbox, and `nextEvent` hands out whichever arrived
+ * first. It resolves `undefined` once nothing but the outside world can move
+ * the machine: no effect, child or timer is in flight and the mailbox is
+ * empty (or the run finished, was cancelled, or lost its journal).
+ *
+ * "In flight" means any running child that is not a machine at rest: a model
+ * request, an async actor, a child machine whose own children are running.
+ * A callback or subscription child never finishes on its own, so while one
+ * is running the loop keeps reading until it stops; a host that invokes one
+ * for the life of a state should expect `nextEvent` to keep waiting there.
+ */
+interface AgentRuntime<TMachine extends AnyStateMachine> {
+  /** Opens the run: a fresh start from `input`, a resume from `snapshot`, or recovery from a log. */
+  start(init?: AgentRunStart<TMachine>): Promise<[SnapshotFrom<TMachine>, AgentEffects]>;
+  /** Applies one event: journals it, traces it, and returns the next state plus its effects. */
+  transition(state: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine> | AgentTimerEvent): [SnapshotFrom<TMachine>, AgentEffects];
+  /** Starts the effects' work and returns once it is accepted, not once it finishes. */
+  execute(effects: AgentEffects): Promise<void>;
+  /** The next event that arrived, or `undefined` once the run is quiescent. */
+  nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
+  /** Settles the run: stops what is still running and returns the outcome. */
+  finish(): Promise<AgentRunResult<TMachine>>;
+}
+/** How {@link runToQuiescence} opens a run: {@link AgentRunStart} plus one event to deliver. */
+interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<TMachine> {
+  /**
+   * An event to send immediately after starting/resuming the actor (e.g. the
+   * human's answer to an idle-state prompt), typed as the machine's event
+   * union. If the resumed state has no transition for it, the machine ignores
+   * it — the run settles normally and the result carries
+   * {@link AgentRunResult.ignored}. For a payload off the wire, parse it first
+   * with `parseAgentEvent(machine, payload)`. A host-owned timer that came
+   * due is delivered the same way, as an {@link AgentTimerEvent}.
+   */
+  event?: EventFromLogic<TMachine> | AgentTimerEvent;
+}
+/**
+ * The blocking host: opens the run, delivers `event` if given, then applies
+ * every event that arrives until the run is quiescent, and returns the
+ * outcome. A request handler or durable engine writes the same loop with its
+ * own stop policy; this one is for scripts and tests.
+ */
+declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: AgentRuntime<TMachine>, init?: AgentRunInit<TMachine>): Promise<AgentRunResult<TMachine>>;
+/**
+ * Creates the helpers for one run of `machine`: executors bound to its
+ * requests, the write-ahead log, traces, the budget, and a mailbox over
+ * XState's durable transition loop (`xstate/durable`). See
+ * {@link AgentRuntime} for the loop a host writes around it, and
+ * {@link runToQuiescence} for the blocking host. {@link AgentRuntime.finish}
+ * stops whatever is still running on every settle path (`done`, `idle`, and
+ * `error` alike) — resume is always by snapshot (or log), never by holding a
+ * reference to a live actor.
  *
- * Binding happens **before** the actor starts: every invoke the machine
+ * Binding happens **before** any actor starts: every invoke the machine
  * could reach is walked and checked against the effective actor sources
  * (`options.actors` merged onto the machine), so a missing
  * `streamText`/`decide` executor or any other unbound actor source throws
- * immediately — a bind-time error, not a mid-run failure.
+ * synchronously from this call — a bind-time error, not a mid-run failure.
  *
  * @example
  * ```ts
  * const executors = createAiSdkExecutors({ models });
- * let r = await runAgent(machine, { input, executors });
+ * let r = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
  * while (r.status === 'idle') {
  *   const event = await promptUser(getAcceptedEvents(r.snapshot));
- *   r = await runAgent(machine, { snapshot: r.snapshot, event, executors });
+ *   r = await runToQuiescence(createAgentRuntime(machine, { executors }), {
+ *     snapshot: r.snapshot,
+ *     event,
+ *   });
  * }
  * if (r.status !== 'done') throw new Error(`Run did not complete: ${r.status}`);
  * console.log(r.output);
@@ -606,7 +613,7 @@ type AgentInputFrom<TMachine extends AnyStateMachine> = [NonNullable<InputFrom<T
  * an adapter's set: `createAiSdkExecutors` from '@statelyai/agent/ai-sdk' or
  * `createOpenAiExecutors` from '@statelyai/agent/openai' supply all three.
  */
-declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, options: RunAgentOptions<TMachine>): Promise<RunAgentResult<TMachine>>;
+declare function createAgentRuntime<TMachine extends AnyStateMachine>(machine: TMachine, options?: AgentRuntimeOptions<TMachine>): AgentRuntime<TMachine>;
 /**
  * The actor handed to an {@link inspectTransitions} handler: an
  * {@link AnyActorRef} widened with the runtime `id`/`src` used to attribute a
@@ -619,7 +626,7 @@ type InspectedActorRef = AnyActorRef & {
 };
 /**
  * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
- * {@link RunAgentOptions.inspect}: it filters the raw inspection stream to
+ * {@link AgentRuntimeOptions.inspect}: it filters the raw inspection stream to
  * `@xstate.transition` events and hands the handler the typed
  * {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
  * transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
@@ -639,12 +646,12 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  * const actor = createActor(bound, { inspect: traceTransitions(onTrace) });
  * ```
  *
- * Only ROOT-actor transitions are traced (matching `runAgent`'s
+ * Only ROOT-actor transitions are traced (matching the runtime's
  * `machine.transition`); child-actor transitions are ignored. Attribute the
  * event via its envelope `runId`.
  *
  * By design this path has NO `run.start`/`run.end` events: `createActor` has no
- * run boundary the way `runAgent` does, so the stream starts at the actor's
+ * run boundary the way `createAgentRuntime` does, so the stream starts at the actor's
  * first transition. It also does NOT emit `emit` trace events: in this xstate
  * build emitted events are delivered through `actor.on(...)`, not the inspection
  * protocol, so they are not observable from an `inspect` handler — subscribe
@@ -652,16 +659,14 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  */
 declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
 /**
- * Default machine-owned idle signal used by {@link runAgent}: an active
+ * Whether a snapshot is asking the outside world for something: an active
  * snapshot that accepts an external event anywhere in its active hierarchy,
  * or declares interaction metadata on an active state.
  *
- * Compose this in `setupAgent({ isIdle })` when the application has additional
- * wait states: `isIdle: (snapshot) => isAgentIdle(snapshot) || snapshot.hasTag('waiting')`.
- * Pending work and active invoked children are checked separately by the
- * runner, so this function only answers whether the state is an intentional
- * external wait.
+ * The runtime does not use this to stop; a run settles when nothing is in
+ * flight. Use it once the run is quiescent, to tell a human wait (render
+ * `getInteraction(snapshot)`) from a machine that is simply stuck.
  */
 declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
 //#endregion
-export { rejectAgentStep as C, AgentUsageEvent as D, AGENT_USAGE_EVENT_TYPE as E, initialAgentStep as S, transitionAgentStep as T, traceTransitions as _, AgentSnapshotDivergedError as a, AgentStepRequest as b, InspectedActorRef as c, RunAgentOptions as d, RunAgentResult as f, serializeTraceEvent as g, runAgent as h, AgentRunMeta as i, JsonSerializableTraceEvent as l, isAgentIdle as m, AgentInputFrom as n, AgentTraceEvent as o, inspectTransitions as p, AgentMaxModelCallsExceededError as r, AgentTransitionHandler as s, AGENT_TRACE_SCHEMA_VERSION as t, RunAgentErrorCause as u, AgentRequest as v, resolveAgentStep as w, executeAgentRequest as x, AgentStep as y };
+export { serializeTraceEvent as C, AGENT_USAGE_EVENT_TYPE as D, AgentStepRequest as E, AgentUsageEvent as O, runToQuiescence as S, AgentRequest as T, InspectedActorRef as _, AgentRunErrorCause as a, inspectTransitions as b, AgentRunResult as c, AgentRuntimeOptions as d, AgentSnapshotDivergedError as f, AgentTransitionHandler as g, AgentTraceEvent as h, AgentMaxModelCallsExceededError as i, AgentRunStart as l, AgentTimerScheduler as m, AgentEffects as n, AgentRunInit as o, AgentTimerEvent as p, AgentInputFrom as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRuntime as u, JsonSerializableTraceEvent as v, traceTransitions as w, isAgentIdle as x, createAgentRuntime as y };