@statelyai/agent 2.0.0-alpha.18 → 2.0.0-alpha.20

package/dist/{run-agent-r9OD4z8F.d.cts → run-agent--4bbms-D.d.cts}

@@ -1,7 +1,7 @@
 import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-pJ5Hn8fv.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
-import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-VcWqO-Cl.cjs";
-import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-CQJq8_v4.cjs";
+import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-Cavva1W6.cjs";
+import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-Bz7HDBkE.cjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, ExecutableActionObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, createActor } from "xstate";
 
 //#region src/internal/registry.d.ts
@@ -240,8 +240,6 @@ interface AgentEventLogDiff<TMachine extends AnyStateMachine> {
   effectChanges: AgentEffectDiff;
 }
 declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
-/** Requires and checks every entry's recorded state/effect hashes. */
-declare function verifyReplay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: Omit<ReplayOptions, "verify">): ReplayResult<TMachine>;
 /** Structural event-tail, logical-state, and owed-effect comparison. */
 declare function diffEventLogs<TMachine extends AnyStateMachine>(machine: TMachine, parentEntries: readonly AgentLogEntry[], forkEntries: readonly AgentLogEntry[], options?: ReplayOptions): AgentEventLogDiff<TMachine>;
 //#endregion
@@ -271,7 +269,7 @@ type AgentStepRequest = AgentRequest | AgentDecisionRequest;
  * present. Accepts either a `kind: 'text'` `AgentEffect` (the step-path shape
  * from `getAgentEffects`) or an {@link AgentRequest} envelope.
  * **Text-only**: passing a `kind: 'decision'` request throws, directing the
- * caller to `resolveDecision(request, executors.decide, ...)` instead. Always
+ * caller to `resolveDecision(request, executors, ...)` instead. Always
  * returns both the normalized `output` and the `raw` executor result (tool
  * calls, usage, finish reason — needed for observability and event-sourced
  * replay).
@@ -341,8 +339,7 @@ interface AgentStateRequest {
  * {@link getAcceptedEvents}). A programmer/integration error, in the same
  * class as runAgent's bind-time throws — it throws rather than settling an
  * `error` result. A type-legal event a guard rejects is NOT this error (the
- * machine simply takes no transition). Opt out with
- * {@link RunAgentOptions.onIllegalResumeEvent} `'ignore'`.
+ * machine simply takes no transition). Always enforced; there is no opt-out.
  */
 declare class AgentIllegalResumeEventError extends AgentError {
   readonly eventType: string;
@@ -382,8 +379,8 @@ interface AgentUserInputExecutor {
 }
 /**
  * The run's machine identity, stamped onto every settled snapshot's `agentMeta`.
- * `machineId` is the machine's `id`; `version` is
- * {@link RunAgentOptions.machineVersion} or the
+ * `machineId` is the machine's `id`; `version` is the machine's own
+ * `version` (XState's `createMachine({ version })`) or, when unversioned, the
  * {@link getMachineStructuralHash} of the machine. Trace events and the
  * `onMessage` info arg carry the same identity flattened, as
  * `machineId`/`machineVersion`.
@@ -400,7 +397,7 @@ interface AgentRunMeta {
 interface AgentMessageInfo {
   runId: string;
   machineId: string;
-  /** {@link RunAgentOptions.machineVersion}, else the machine's own `version`, else its structural hash. */
+  /** The machine's own `version`, else its structural hash. */
   machineVersion: string;
 }
 /**
@@ -416,7 +413,7 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   runId: string;
   seq: number;
   timestamp: string;
-  machineId: string; /** {@link RunAgentOptions.machineVersion}, else the machine's own `version`, else its structural hash. */
+  machineId: string; /** The machine's own `version`, else its structural hash. */
   machineVersion: string;
 } & ({
   type: "run.start";
@@ -516,7 +513,7 @@ declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "t
  * in a JSONL file). Live values are sanitized rather than trusted:
  *
  * - Snapshots (`run.start`, `machine.transition`, `run.end`) go through the
- *   same JSON round-trip as {@link persistSnapshot}, so what lands on disk is
+ *   same JSON round-trip as `machine.getPersistedSnapshot(...)`, so what lands on disk is
  *   what a resume would see.
  * - `request.end`'s `raw` (a provider SDK object, frequently cyclic) is DROPPED
  *   unless `includeRaw` is set, in which case it is sanitized like everything
@@ -582,27 +579,11 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * (or an event-log store) and resume from the log alone.
    */
   events?: readonly AgentLogEntry[];
-  /**
-   * How to handle a resume `event` the restored state cannot accept (a
-   * type-level check via {@link getAcceptedEvents}, only applied when resuming
-   * from a `snapshot`). `'throw'` (default) throws {@link AgentIllegalResumeEventError}
-   * before delivering the event; `'ignore'` restores the older silent behavior
-   * (the event is sent and the machine drops it). A type-legal event a guard
-   * rejects is never an illegal resume event.
-   */
-  onIllegalResumeEvent?: "throw" | "ignore";
-  /**
-   * The version stamped onto every settled snapshot's `agentMeta` and compared
-   * against an incoming snapshot's stamp on resume. Defaults to the machine's
-   * own `version` (XState's `createMachine({ version })` prop) when set, else
-   * {@link getMachineStructuralHash} of the machine (a structural fingerprint
-   * that changes on any edit). Set `version` on the machine — or this option —
-   * to control migration boundaries yourself.
-   */
-  machineVersion?: string;
   /**
    * How to handle a resume `snapshot` whose stamped `agentMeta.version` differs
-   * from the current machine's version. `'throw'` (default) throws
+   * from the current machine's `version` (XState's `createMachine({ version })`
+   * prop — the single source of truth; an unversioned machine falls back to its
+   * {@link getMachineStructuralHash}). `'throw'` (default) throws
    * {@link AgentSnapshotVersionMismatchError} with `from`/`to`; `'warn'`
    * `console.warn`s once and proceeds; `'ignore'` proceeds silently. Ignored
    * when {@link migrateSnapshot} is provided (that runs instead), and never
@@ -614,6 +595,12 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * version mismatches the current machine's: receives the incoming snapshot
    * and `{ from, to }`, and its return value is used as the snapshot to resume
    * from. A throw propagates.
+   *
+   * Prefer XState's own `createMachine({ version, migrate })` hook when the
+   * migration belongs to the machine: a machine that declares `migrate` is left
+   * to xstate, and runAgent neither throws nor rewrites the snapshot's version
+   * before restore. This option stays for host-owned migrations (a machine you
+   * do not control, or a migration that needs run-scoped context).
    */
   migrateSnapshot?: (snapshot: Snapshot<unknown>, info: {
     from: string;
@@ -635,7 +622,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * Host override for detecting a snapshot that is an INTENTIONAL wait for an
    * external event — the deterministic replacement for the timing heuristic
    * runAgent uses to settle idle. Resolution order: this option (host override)
-   * → the machine-carried predicate declared via `setupAgent({ isSuspended })`
+   * → the machine-carried predicate declared via `setupAgent({ isIdle })`
    * → the timing heuristic (when neither is present). When the resolved
    * predicate returns true and nothing is in flight (no live requests/
    * invokes; the `agent.userInput` placeholder exemption still applies), runAgent
@@ -645,7 +632,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * exactly as before (with a one-time dev warning suggesting a predicate).
    * Declare your own signal, e.g. `(s) => s.hasTag('awaiting-review')`.
    */
-  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
+  isIdle?: (snapshot: AnyMachineSnapshot) => boolean;
   /**
    * The override to runAgent's DEFAULT contract. By default agent work is
    * whatever the machine *invokes* (`agent.generateText`, TextLogic,
@@ -655,23 +642,16 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * tags, a lookup table keyed by state value, wherever you keep them. Return
    * nothing to settle idle (human-wait states).
    *
-   * There is no blessed source for the prompts — this is a recipe seam.
-   * Prompts-in-descriptions, copy-paste and adapt:
+   * There is no blessed source for the prompts — this is a recipe seam. The
+   * shipped prompts-in-descriptions recipe is {@link getSnapshotRequests}:
    *
    * ```ts
-   * getRequests: (snapshot) =>
-   *   snapshot._nodes
-   *     .filter((node) => node.description && !node.tags.includes('waiting'))
-   *     .map((node) => ({
-   *       model: 'writer',
-   *       prompt: node.description!,
-   *       kind: node.tags.includes('decision') ? 'decision' : 'text',
-   *       // single-outcome states advance deterministically; else `decide`
-   *       onDone: node.ownEvents.length === 1 ? { type: node.ownEvents[0] } : undefined,
-   *       allowedEvents: node.ownEvents,
-   *     })),
+   * getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
    * ```
    *
+   * Reach for {@link getSnapshotNodes} when you want to build requests some
+   * other way — between them, host code never touches `snapshot._nodes`.
+   *
    * Each request runs per {@link AgentStateRequest.kind}, appends to the
    * run's message log (see {@link RunAgentOptions.messages}), and advances
    * the machine per {@link AgentStateRequest.onDone} — explicitly named/
@@ -768,11 +748,84 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
   inspect?: ((inspectionEvent: InspectionEvent) => void) | {
     next?: (inspectionEvent: InspectionEvent) => void;
   };
-  /** Caps the number of model/decision calls this run may make (each retry of a decision counts separately); exceeding it settles `{ status: 'error', cause: 'max-model-calls' }`. Default 100. */
+  /**
+   * Caps the number of model/decision calls this run may make (each retry of a
+   * decision counts separately). Default 100. The overrun is thrown into the
+   * invoke that would have made the call, as an
+   * {@link AgentMaxModelCallsExceededError} with `code: 'max-model-calls'` — so
+   * an `onError` can branch on it and route to a degraded state. Unhandled, it
+   * settles `{ status: 'error', cause: 'max-model-calls' }`.
+   */
   maxModelCalls?: number;
   /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
   signal?: AbortSignal;
 }
+/**
+ * One active state node of a snapshot, as {@link getSnapshotRequests} and
+ * {@link getSnapshotNodes} surface it: the prompt-bearing `description`, the
+ * `tags` a recipe branches on, the state `meta`, and `ownEvents` (the event
+ * types this node itself declares transitions for). The shape hosts used to
+ * reach for through the private `snapshot._nodes` array.
+ */
+interface AgentSnapshotNode {
+  /** The node's full id (e.g. `writer.drafting`). */
+  id: string;
+  /** The node's own key (e.g. `drafting`). */
+  key: string;
+  /** The node's `description` — the prompt, in the prompts-in-descriptions recipe. */
+  description?: string;
+  tags: string[];
+  meta?: unknown;
+  /** Event types this node declares transitions for (xstate's `ownEvents`). */
+  ownEvents: string[];
+  /** True when the node has no child states. */
+  leaf: boolean;
+}
+/**
+ * The active state nodes of a snapshot, as plain {@link AgentSnapshotNode}
+ * descriptors. The escape hatch under {@link getSnapshotRequests}: use it when
+ * your `getRequests` hook needs to build requests some other way, so host code
+ * never touches xstate's private `snapshot._nodes`.
+ */
+declare function getSnapshotNodes(snapshot: AnyMachineSnapshot): AgentSnapshotNode[];
+/** Options for {@link getSnapshotRequests}. */
+interface GetSnapshotRequestsOptions {
+  /** Executor model name every produced request carries. */
+  model: string;
+  /**
+   * Which active nodes produce a request. Default: every node with a
+   * `description` that is NOT tagged `'waiting'` (a human-wait state settles
+   * idle instead).
+   */
+  filter?: (node: AgentSnapshotNode) => boolean;
+  /**
+   * Shapes (or drops, by returning `undefined`) each node's request before it
+   * is returned — set `system`, `allowedEvents`, a custom `onDone`, …
+   */
+  map?: (request: AgentStateRequest, node: AgentSnapshotNode) => AgentStateRequest | undefined;
+}
+/**
+ * Builds the {@link AgentStateRequest}s for a snapshot straight from its active
+ * state nodes — the prompts-in-descriptions recipe as a function, so a
+ * {@link RunAgentOptions.getRequests} hook is one line and never reaches into
+ * xstate's private `snapshot._nodes`:
+ *
+ * ```ts
+ * runAgent(machine, {
+ *   executors,
+ *   getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
+ * });
+ * ```
+ *
+ * Each described active node becomes one request: `prompt` from the node's
+ * `description`, `kind: 'decision'` when it is tagged `'decision'`, `system`
+ * from `meta.role` when present, `allowedEvents` scoped to the node's own
+ * events, and an explicit `onDone` when the node has exactly one own event
+ * (single-outcome states advance deterministically; anything else falls
+ * through to a `decide` call). Nodes tagged `'waiting'` produce nothing, so the
+ * run settles idle for a human. Override any of it with `filter`/`map`.
+ */
+declare function getSnapshotRequests(snapshot: AnyMachineSnapshot, options: GetSnapshotRequestsOptions): AgentStateRequest[];
 /**
  * The outcome of a {@link runAgent} call — always exactly one of three
  * variants, never a throw for a waiting or failed machine (programmer
@@ -848,6 +901,26 @@ type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine
  * - `'stopped'` — the actor was stopped externally (`status === 'stopped'`).
  */
 type RunAgentErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped";
+/**
+ * Thrown into the invoke that would have made the call once
+ * {@link RunAgentOptions.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
+ * run. Unhandled, it settles `{ status: 'error', cause: 'max-model-calls' }`.
+ *
+ * ```ts
+ * onError: [
+ *   { guard: ({ event }) => event.error?.code === 'max-model-calls', target: 'budgetSpent' },
+ *   { target: 'failed' },
+ * ]
+ * ```
+ */
+declare class AgentMaxModelCallsExceededError extends AgentError {
+  /** The budget that was exceeded (`options.maxModelCalls`). */
+  readonly maxModelCalls: number;
+  constructor(maxModelCalls: number);
+}
 /**
  * The machine input a run accepts, which is the schema's *pre*-validation side.
  *
@@ -1022,4 +1095,4 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  */
 declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
 //#endregion
-export { AgentEffect as A, ReplayResult as B, traceTransitions as C, executeAgentRequest as D, AgentStepRequest as E, AgentReplayMachineMismatchError as F, replay as G, diffEventLogs as H, AgentUsageEvent as I, verifyReplay as K, CreateReplayEntryOptions as L, AgentEventLogDiff as M, AgentLogPatchOperation as N, AGENT_INIT_EVENT_TYPE as O, AgentReplayDivergenceError as P, GetAgentEffectsOptions as R, serializeTraceEvent as S, AgentRequest as T, getAgentEffects as U, createReplayEntry as V, initEntry as W, RunAgentResult as _, AgentInputFrom as a, inspectTransitions as b, AgentSnapshotVersionMismatchError as c, GenerateResult as d, InspectedActorRef as f, RunAgentOptions as g, RunAgentErrorCause as h, AgentIllegalResumeEventError as i, AgentEffectDiff as j, AGENT_USAGE_EVENT_TYPE as k, AgentTraceEvent as l, PendingUserInput as m, AgentActorSession as n, AgentMessageInfo as o, JsonSerializableTraceEvent as p, AgentIdleError as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentUserInputExecutor as u, createAgentActor as v, AgentStateRequest as w, runAgent as x, generateResult as y, ReplayOptions as z };
+export { AgentRequest as A, AgentReplayMachineMismatchError as B, getSnapshotNodes as C, serializeTraceEvent as D, runAgent as E, AgentEffect as F, ReplayResult as G, CreateReplayEntryOptions as H, AgentEffectDiff as I, getAgentEffects as J, createReplayEntry as K, AgentEventLogDiff as L, executeAgentRequest as M, AGENT_INIT_EVENT_TYPE as N, traceTransitions as O, AGENT_USAGE_EVENT_TYPE as P, AgentLogPatchOperation as R, generateResult as S, inspectTransitions as T, GetAgentEffectsOptions as U, AgentUsageEvent as V, ReplayOptions as W, replay as X, initEntry as Y, PendingUserInput as _, AgentInputFrom as a, RunAgentResult as b, AgentRunMeta as c, AgentTraceEvent as d, AgentUserInputExecutor as f, JsonSerializableTraceEvent as g, InspectedActorRef as h, AgentIllegalResumeEventError as i, AgentStepRequest as j, AgentStateRequest as k, AgentSnapshotNode as l, GetSnapshotRequestsOptions as m, AgentActorSession as n, AgentMaxModelCallsExceededError as o, GenerateResult as p, diffEventLogs as q, AgentIdleError as r, AgentMessageInfo as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentSnapshotVersionMismatchError as u, RunAgentErrorCause as v, getSnapshotRequests as w, createAgentActor as x, RunAgentOptions as y, AgentReplayDivergenceError as z };

package/dist/{run-agent-DQIDikfd.d.mts → run-agent-CwmzAZwj.d.mts}

@@ -1,7 +1,7 @@
 import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-DYpK3QF4.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-RvnlD-An.mjs";
-import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-BrC9Q1xW.mjs";
+import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-Er5KkTX6.mjs";
+import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-hrA1vqtN.mjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, ExecutableActionObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, createActor } from "xstate";
 
 //#region src/internal/registry.d.ts
@@ -240,8 +240,6 @@ interface AgentEventLogDiff<TMachine extends AnyStateMachine> {
   effectChanges: AgentEffectDiff;
 }
 declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
-/** Requires and checks every entry's recorded state/effect hashes. */
-declare function verifyReplay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: Omit<ReplayOptions, "verify">): ReplayResult<TMachine>;
 /** Structural event-tail, logical-state, and owed-effect comparison. */
 declare function diffEventLogs<TMachine extends AnyStateMachine>(machine: TMachine, parentEntries: readonly AgentLogEntry[], forkEntries: readonly AgentLogEntry[], options?: ReplayOptions): AgentEventLogDiff<TMachine>;
 //#endregion
@@ -271,7 +269,7 @@ type AgentStepRequest = AgentRequest | AgentDecisionRequest;
  * present. Accepts either a `kind: 'text'` `AgentEffect` (the step-path shape
  * from `getAgentEffects`) or an {@link AgentRequest} envelope.
  * **Text-only**: passing a `kind: 'decision'` request throws, directing the
- * caller to `resolveDecision(request, executors.decide, ...)` instead. Always
+ * caller to `resolveDecision(request, executors, ...)` instead. Always
  * returns both the normalized `output` and the `raw` executor result (tool
  * calls, usage, finish reason — needed for observability and event-sourced
  * replay).
@@ -341,8 +339,7 @@ interface AgentStateRequest {
  * {@link getAcceptedEvents}). A programmer/integration error, in the same
  * class as runAgent's bind-time throws — it throws rather than settling an
  * `error` result. A type-legal event a guard rejects is NOT this error (the
- * machine simply takes no transition). Opt out with
- * {@link RunAgentOptions.onIllegalResumeEvent} `'ignore'`.
+ * machine simply takes no transition). Always enforced; there is no opt-out.
  */
 declare class AgentIllegalResumeEventError extends AgentError {
   readonly eventType: string;
@@ -382,8 +379,8 @@ interface AgentUserInputExecutor {
 }
 /**
  * The run's machine identity, stamped onto every settled snapshot's `agentMeta`.
- * `machineId` is the machine's `id`; `version` is
- * {@link RunAgentOptions.machineVersion} or the
+ * `machineId` is the machine's `id`; `version` is the machine's own
+ * `version` (XState's `createMachine({ version })`) or, when unversioned, the
  * {@link getMachineStructuralHash} of the machine. Trace events and the
  * `onMessage` info arg carry the same identity flattened, as
  * `machineId`/`machineVersion`.
@@ -400,7 +397,7 @@ interface AgentRunMeta {
 interface AgentMessageInfo {
   runId: string;
   machineId: string;
-  /** {@link RunAgentOptions.machineVersion}, else the machine's own `version`, else its structural hash. */
+  /** The machine's own `version`, else its structural hash. */
   machineVersion: string;
 }
 /**
@@ -416,7 +413,7 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   runId: string;
   seq: number;
   timestamp: string;
-  machineId: string; /** {@link RunAgentOptions.machineVersion}, else the machine's own `version`, else its structural hash. */
+  machineId: string; /** The machine's own `version`, else its structural hash. */
   machineVersion: string;
 } & ({
   type: "run.start";
@@ -516,7 +513,7 @@ declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "t
  * in a JSONL file). Live values are sanitized rather than trusted:
  *
  * - Snapshots (`run.start`, `machine.transition`, `run.end`) go through the
- *   same JSON round-trip as {@link persistSnapshot}, so what lands on disk is
+ *   same JSON round-trip as `machine.getPersistedSnapshot(...)`, so what lands on disk is
  *   what a resume would see.
  * - `request.end`'s `raw` (a provider SDK object, frequently cyclic) is DROPPED
  *   unless `includeRaw` is set, in which case it is sanitized like everything
@@ -582,27 +579,11 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * (or an event-log store) and resume from the log alone.
    */
   events?: readonly AgentLogEntry[];
-  /**
-   * How to handle a resume `event` the restored state cannot accept (a
-   * type-level check via {@link getAcceptedEvents}, only applied when resuming
-   * from a `snapshot`). `'throw'` (default) throws {@link AgentIllegalResumeEventError}
-   * before delivering the event; `'ignore'` restores the older silent behavior
-   * (the event is sent and the machine drops it). A type-legal event a guard
-   * rejects is never an illegal resume event.
-   */
-  onIllegalResumeEvent?: "throw" | "ignore";
-  /**
-   * The version stamped onto every settled snapshot's `agentMeta` and compared
-   * against an incoming snapshot's stamp on resume. Defaults to the machine's
-   * own `version` (XState's `createMachine({ version })` prop) when set, else
-   * {@link getMachineStructuralHash} of the machine (a structural fingerprint
-   * that changes on any edit). Set `version` on the machine — or this option —
-   * to control migration boundaries yourself.
-   */
-  machineVersion?: string;
   /**
    * How to handle a resume `snapshot` whose stamped `agentMeta.version` differs
-   * from the current machine's version. `'throw'` (default) throws
+   * from the current machine's `version` (XState's `createMachine({ version })`
+   * prop — the single source of truth; an unversioned machine falls back to its
+   * {@link getMachineStructuralHash}). `'throw'` (default) throws
    * {@link AgentSnapshotVersionMismatchError} with `from`/`to`; `'warn'`
    * `console.warn`s once and proceeds; `'ignore'` proceeds silently. Ignored
    * when {@link migrateSnapshot} is provided (that runs instead), and never
@@ -614,6 +595,12 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * version mismatches the current machine's: receives the incoming snapshot
    * and `{ from, to }`, and its return value is used as the snapshot to resume
    * from. A throw propagates.
+   *
+   * Prefer XState's own `createMachine({ version, migrate })` hook when the
+   * migration belongs to the machine: a machine that declares `migrate` is left
+   * to xstate, and runAgent neither throws nor rewrites the snapshot's version
+   * before restore. This option stays for host-owned migrations (a machine you
+   * do not control, or a migration that needs run-scoped context).
    */
   migrateSnapshot?: (snapshot: Snapshot<unknown>, info: {
     from: string;
@@ -635,7 +622,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * Host override for detecting a snapshot that is an INTENTIONAL wait for an
    * external event — the deterministic replacement for the timing heuristic
    * runAgent uses to settle idle. Resolution order: this option (host override)
-   * → the machine-carried predicate declared via `setupAgent({ isSuspended })`
+   * → the machine-carried predicate declared via `setupAgent({ isIdle })`
    * → the timing heuristic (when neither is present). When the resolved
    * predicate returns true and nothing is in flight (no live requests/
    * invokes; the `agent.userInput` placeholder exemption still applies), runAgent
@@ -645,7 +632,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * exactly as before (with a one-time dev warning suggesting a predicate).
    * Declare your own signal, e.g. `(s) => s.hasTag('awaiting-review')`.
    */
-  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
+  isIdle?: (snapshot: AnyMachineSnapshot) => boolean;
   /**
    * The override to runAgent's DEFAULT contract. By default agent work is
    * whatever the machine *invokes* (`agent.generateText`, TextLogic,
@@ -655,23 +642,16 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * tags, a lookup table keyed by state value, wherever you keep them. Return
    * nothing to settle idle (human-wait states).
    *
-   * There is no blessed source for the prompts — this is a recipe seam.
-   * Prompts-in-descriptions, copy-paste and adapt:
+   * There is no blessed source for the prompts — this is a recipe seam. The
+   * shipped prompts-in-descriptions recipe is {@link getSnapshotRequests}:
    *
    * ```ts
-   * getRequests: (snapshot) =>
-   *   snapshot._nodes
-   *     .filter((node) => node.description && !node.tags.includes('waiting'))
-   *     .map((node) => ({
-   *       model: 'writer',
-   *       prompt: node.description!,
-   *       kind: node.tags.includes('decision') ? 'decision' : 'text',
-   *       // single-outcome states advance deterministically; else `decide`
-   *       onDone: node.ownEvents.length === 1 ? { type: node.ownEvents[0] } : undefined,
-   *       allowedEvents: node.ownEvents,
-   *     })),
+   * getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
    * ```
    *
+   * Reach for {@link getSnapshotNodes} when you want to build requests some
+   * other way — between them, host code never touches `snapshot._nodes`.
+   *
    * Each request runs per {@link AgentStateRequest.kind}, appends to the
    * run's message log (see {@link RunAgentOptions.messages}), and advances
    * the machine per {@link AgentStateRequest.onDone} — explicitly named/
@@ -768,11 +748,84 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
   inspect?: ((inspectionEvent: InspectionEvent) => void) | {
     next?: (inspectionEvent: InspectionEvent) => void;
   };
-  /** Caps the number of model/decision calls this run may make (each retry of a decision counts separately); exceeding it settles `{ status: 'error', cause: 'max-model-calls' }`. Default 100. */
+  /**
+   * Caps the number of model/decision calls this run may make (each retry of a
+   * decision counts separately). Default 100. The overrun is thrown into the
+   * invoke that would have made the call, as an
+   * {@link AgentMaxModelCallsExceededError} with `code: 'max-model-calls'` — so
+   * an `onError` can branch on it and route to a degraded state. Unhandled, it
+   * settles `{ status: 'error', cause: 'max-model-calls' }`.
+   */
   maxModelCalls?: number;
   /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
   signal?: AbortSignal;
 }
+/**
+ * One active state node of a snapshot, as {@link getSnapshotRequests} and
+ * {@link getSnapshotNodes} surface it: the prompt-bearing `description`, the
+ * `tags` a recipe branches on, the state `meta`, and `ownEvents` (the event
+ * types this node itself declares transitions for). The shape hosts used to
+ * reach for through the private `snapshot._nodes` array.
+ */
+interface AgentSnapshotNode {
+  /** The node's full id (e.g. `writer.drafting`). */
+  id: string;
+  /** The node's own key (e.g. `drafting`). */
+  key: string;
+  /** The node's `description` — the prompt, in the prompts-in-descriptions recipe. */
+  description?: string;
+  tags: string[];
+  meta?: unknown;
+  /** Event types this node declares transitions for (xstate's `ownEvents`). */
+  ownEvents: string[];
+  /** True when the node has no child states. */
+  leaf: boolean;
+}
+/**
+ * The active state nodes of a snapshot, as plain {@link AgentSnapshotNode}
+ * descriptors. The escape hatch under {@link getSnapshotRequests}: use it when
+ * your `getRequests` hook needs to build requests some other way, so host code
+ * never touches xstate's private `snapshot._nodes`.
+ */
+declare function getSnapshotNodes(snapshot: AnyMachineSnapshot): AgentSnapshotNode[];
+/** Options for {@link getSnapshotRequests}. */
+interface GetSnapshotRequestsOptions {
+  /** Executor model name every produced request carries. */
+  model: string;
+  /**
+   * Which active nodes produce a request. Default: every node with a
+   * `description` that is NOT tagged `'waiting'` (a human-wait state settles
+   * idle instead).
+   */
+  filter?: (node: AgentSnapshotNode) => boolean;
+  /**
+   * Shapes (or drops, by returning `undefined`) each node's request before it
+   * is returned — set `system`, `allowedEvents`, a custom `onDone`, …
+   */
+  map?: (request: AgentStateRequest, node: AgentSnapshotNode) => AgentStateRequest | undefined;
+}
+/**
+ * Builds the {@link AgentStateRequest}s for a snapshot straight from its active
+ * state nodes — the prompts-in-descriptions recipe as a function, so a
+ * {@link RunAgentOptions.getRequests} hook is one line and never reaches into
+ * xstate's private `snapshot._nodes`:
+ *
+ * ```ts
+ * runAgent(machine, {
+ *   executors,
+ *   getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
+ * });
+ * ```
+ *
+ * Each described active node becomes one request: `prompt` from the node's
+ * `description`, `kind: 'decision'` when it is tagged `'decision'`, `system`
+ * from `meta.role` when present, `allowedEvents` scoped to the node's own
+ * events, and an explicit `onDone` when the node has exactly one own event
+ * (single-outcome states advance deterministically; anything else falls
+ * through to a `decide` call). Nodes tagged `'waiting'` produce nothing, so the
+ * run settles idle for a human. Override any of it with `filter`/`map`.
+ */
+declare function getSnapshotRequests(snapshot: AnyMachineSnapshot, options: GetSnapshotRequestsOptions): AgentStateRequest[];
 /**
  * The outcome of a {@link runAgent} call — always exactly one of three
  * variants, never a throw for a waiting or failed machine (programmer
@@ -848,6 +901,26 @@ type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine
  * - `'stopped'` — the actor was stopped externally (`status === 'stopped'`).
  */
 type RunAgentErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped";
+/**
+ * Thrown into the invoke that would have made the call once
+ * {@link RunAgentOptions.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
+ * run. Unhandled, it settles `{ status: 'error', cause: 'max-model-calls' }`.
+ *
+ * ```ts
+ * onError: [
+ *   { guard: ({ event }) => event.error?.code === 'max-model-calls', target: 'budgetSpent' },
+ *   { target: 'failed' },
+ * ]
+ * ```
+ */
+declare class AgentMaxModelCallsExceededError extends AgentError {
+  /** The budget that was exceeded (`options.maxModelCalls`). */
+  readonly maxModelCalls: number;
+  constructor(maxModelCalls: number);
+}
 /**
  * The machine input a run accepts, which is the schema's *pre*-validation side.
  *
@@ -1022,4 +1095,4 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  */
 declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
 //#endregion
-export { AgentEffect as A, ReplayResult as B, traceTransitions as C, executeAgentRequest as D, AgentStepRequest as E, AgentReplayMachineMismatchError as F, replay as G, diffEventLogs as H, AgentUsageEvent as I, verifyReplay as K, CreateReplayEntryOptions as L, AgentEventLogDiff as M, AgentLogPatchOperation as N, AGENT_INIT_EVENT_TYPE as O, AgentReplayDivergenceError as P, GetAgentEffectsOptions as R, serializeTraceEvent as S, AgentRequest as T, getAgentEffects as U, createReplayEntry as V, initEntry as W, RunAgentResult as _, AgentInputFrom as a, inspectTransitions as b, AgentSnapshotVersionMismatchError as c, GenerateResult as d, InspectedActorRef as f, RunAgentOptions as g, RunAgentErrorCause as h, AgentIllegalResumeEventError as i, AgentEffectDiff as j, AGENT_USAGE_EVENT_TYPE as k, AgentTraceEvent as l, PendingUserInput as m, AgentActorSession as n, AgentMessageInfo as o, JsonSerializableTraceEvent as p, AgentIdleError as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentUserInputExecutor as u, createAgentActor as v, AgentStateRequest as w, runAgent as x, generateResult as y, ReplayOptions as z };
+export { AgentRequest as A, AgentReplayMachineMismatchError as B, getSnapshotNodes as C, serializeTraceEvent as D, runAgent as E, AgentEffect as F, ReplayResult as G, CreateReplayEntryOptions as H, AgentEffectDiff as I, getAgentEffects as J, createReplayEntry as K, AgentEventLogDiff as L, executeAgentRequest as M, AGENT_INIT_EVENT_TYPE as N, traceTransitions as O, AGENT_USAGE_EVENT_TYPE as P, AgentLogPatchOperation as R, generateResult as S, inspectTransitions as T, GetAgentEffectsOptions as U, AgentUsageEvent as V, ReplayOptions as W, replay as X, initEntry as Y, PendingUserInput as _, AgentInputFrom as a, RunAgentResult as b, AgentRunMeta as c, AgentTraceEvent as d, AgentUserInputExecutor as f, JsonSerializableTraceEvent as g, InspectedActorRef as h, AgentIllegalResumeEventError as i, AgentStepRequest as j, AgentStateRequest as k, AgentSnapshotNode as l, GetSnapshotRequestsOptions as m, AgentActorSession as n, AgentMaxModelCallsExceededError as o, GenerateResult as p, diffEventLogs as q, AgentIdleError as r, AgentMessageInfo as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentSnapshotVersionMismatchError as u, RunAgentErrorCause as v, getSnapshotRequests as w, createAgentActor as x, RunAgentOptions as y, AgentReplayDivergenceError as z };