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

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { C as ToolResultPart, S as ToolMessage, T as WithAgentInputSchema, _ as NormalizedEventSchemas, a as AgentToolChoice, b as TextPart, c as AgentTools, d as ChosenEvent, f as EventUnion, g as InferOutput, h as InferInput, i as AgentTool, l as AllowedEvents, m as ImagePart, n as AgentMessage, o as AgentToolDescriptor, p as FilePart, r as AgentSnapshotStore, s as AgentToolExecute, t as AgentEventSchemaInputMap, u as AssistantMessage, v as StandardSchemaV1, w as UserMessage, x as ToolCallPart, y as SystemMessage } from "./types-DYpK3QF4.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { A as AgentDecisionExecutor, B as AgentEventToolNameResolver, C as buildEnvelopeSchema, D as parseModelRef, E as getCallUsage, F as DecisionLogicConfig, G as parseAgentEvent, H as AgentRequestSource, I as ResolveDecisionOptions, L as renderDecisionAttempts, M as AgentDecisionInput, N as AgentDecisionRequest, O as parseOutput, P as DecisionAttempt, R as resolveDecision, S as bindRequestExecutor, T as getAgentOutputMode, U as AgentSchemas, V as AgentRequestOptions, W as getAcceptedEvents, _ as StructuredOutputEnvelope, a as AgentOutputMode, b as TextLogicExecuteArgs, c as AgentRequestExecutorResult, d as AgentTextRequest, f as AgentUsage, g as BuiltinAgentActors, h as AiSdkShapedTextResult, i as AgentModelRef, j as AgentDecisionExhaustedError, k as parseStructuredEnvelope, l as AgentRequestExecutors, m as AiSdkShapedStreamResult, n as AgentExecutorTextRequest, o as AgentRequestExecutor, p as AgentUserInput, r as AgentModelMap, s as AgentRequestExecutorInfo, t as AgentCallUsage, u as AgentRequestMode, v as TextLogic, w as createTextLogic, x as TextLogicExecutor, y as TextLogicConfig, z as AgentEventDescriptor } from "./text-logic-RvnlD-An.mjs";
-import { a as AgentLogVerification, c as assertAgentLogEntry, d as assertEventLogStoreConformance, i as AgentLogEntry, l as assertJsonSerializable, n as AgentEventLogConflictError, o as JsonValue, r as AgentEventLogStore, s as NonSerializableAgentEventError, t as AGENT_EVENT_SCHEMA_VERSION, u as createInMemoryEventLogStore } from "./event-log-store-BrC9Q1xW.mjs";
-import { A as AgentEffect, B as ReplayResult, C as traceTransitions, D as executeAgentRequest, E as AgentStepRequest, F as AgentReplayMachineMismatchError, G as replay, H as diffEventLogs, I as AgentUsageEvent, K as verifyReplay, L as CreateReplayEntryOptions, M as AgentEventLogDiff, N as AgentLogPatchOperation, O as AGENT_INIT_EVENT_TYPE, P as AgentReplayDivergenceError, R as GetAgentEffectsOptions, S as serializeTraceEvent, T as AgentRequest, U as getAgentEffects, V as createReplayEntry, W as initEntry, _ as RunAgentResult, a as AgentInputFrom, b as inspectTransitions, c as AgentSnapshotVersionMismatchError, d as GenerateResult, f as InspectedActorRef, g as RunAgentOptions, h as RunAgentErrorCause, i as AgentIllegalResumeEventError, j as AgentEffectDiff, k as AGENT_USAGE_EVENT_TYPE, l as AgentTraceEvent, m as PendingUserInput, n as AgentActorSession, o as AgentMessageInfo, p as JsonSerializableTraceEvent, r as AgentIdleError, s as AgentRunMeta, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentUserInputExecutor, v as createAgentActor, w as AgentStateRequest, x as runAgent, y as generateResult, z as ReplayOptions } from "./run-agent-DQIDikfd.mjs";
-import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, InputFrom, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema, SnapshotFrom, StateValue } from "xstate";
+import { A as AgentDecisionExecutor, B as AgentEventToolNameResolver, C as buildEnvelopeSchema, D as parseModelRef, E as getCallUsage, F as DecisionLogicConfig, G as parseAgentEvent, H as AgentRequestSource, I as ResolveDecisionOptions, L as renderDecisionAttempts, M as AgentDecisionInput, N as AgentDecisionRequest, O as parseOutput, P as DecisionAttempt, R as resolveDecision, S as bindRequestExecutor, T as getAgentOutputMode, U as AgentSchemas, V as AgentRequestOptions, W as getAcceptedEvents, _ as StructuredOutputEnvelope, a as AgentOutputMode, b as TextLogicExecuteArgs, c as AgentRequestExecutorResult, d as AgentTextRequest, f as AgentUsage, g as BuiltinAgentActors, h as AiSdkShapedTextResult, i as AgentModelRef, j as AgentDecisionExhaustedError, k as parseStructuredEnvelope, l as AgentRequestExecutors, m as AiSdkShapedStreamResult, n as AgentExecutorTextRequest, o as AgentRequestExecutor, p as AgentUserInput, r as AgentModelMap, s as AgentRequestExecutorInfo, t as AgentCallUsage, u as AgentRequestMode, v as TextLogic, w as createTextLogic, x as TextLogicExecutor, y as TextLogicConfig, z as AgentEventDescriptor } from "./text-logic-Er5KkTX6.mjs";
+import { a as AgentLogVerification, c as assertAgentLogEntry, d as assertEventLogStoreConformance, i as AgentLogEntry, l as assertJsonSerializable, n as AgentEventLogConflictError, o as JsonValue, r as AgentEventLogStore, s as NonSerializableAgentEventError, t as AGENT_EVENT_SCHEMA_VERSION, u as createInMemoryEventLogStore } from "./event-log-store-hrA1vqtN.mjs";
+import { A as AgentRequest, B as AgentReplayMachineMismatchError, C as getSnapshotNodes, D as serializeTraceEvent, E as runAgent, F as AgentEffect, G as ReplayResult, H as CreateReplayEntryOptions, I as AgentEffectDiff, J as getAgentEffects, K as createReplayEntry, L as AgentEventLogDiff, M as executeAgentRequest, N as AGENT_INIT_EVENT_TYPE, O as traceTransitions, P as AGENT_USAGE_EVENT_TYPE, R as AgentLogPatchOperation, S as generateResult, T as inspectTransitions, U as GetAgentEffectsOptions, V as AgentUsageEvent, W as ReplayOptions, X as replay, Y as initEntry, _ as PendingUserInput, a as AgentInputFrom, b as RunAgentResult, c as AgentRunMeta, d as AgentTraceEvent, f as AgentUserInputExecutor, g as JsonSerializableTraceEvent, h as InspectedActorRef, i as AgentIllegalResumeEventError, j as AgentStepRequest, k as AgentStateRequest, l as AgentSnapshotNode, m as GetSnapshotRequestsOptions, n as AgentActorSession, o as AgentMaxModelCallsExceededError, p as GenerateResult, q as diffEventLogs, r as AgentIdleError, s as AgentMessageInfo, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentSnapshotVersionMismatchError, v as RunAgentErrorCause, w as getSnapshotRequests, x as createAgentActor, y as RunAgentOptions, z as AgentReplayDivergenceError } from "./run-agent-CwmzAZwj.mjs";
+import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, InputFrom, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/messages.d.ts
 /**
@@ -99,14 +99,14 @@ interface AgentWorkflowConfig {
   /**
    * State tags that mark an INTENTIONAL wait for an external event (a human
    * approval, an inbound webhook, …) — the declarative form of `setupAgent({
-   * isSuspended })`, since a config cannot carry a function. Lowered to a
+   * isIdle })`, since a config cannot carry a function. Lowered to a
    * `snapshot.hasTag(...)`-any-of predicate so `runAgent` settles those
    * snapshots idle deterministically instead of using its timing heuristic.
    * Every listed tag must appear in some state's `tags` — an unused tag is a
-   * build-time error. A `fromConfig(config, { isSuspended })` option takes
-   * precedence; a `runAgent({ isSuspended })` host override beats both.
+   * build-time error. A `fromConfig(config, { isIdle })` option takes
+   * precedence; a `runAgent({ isIdle })` host override beats both.
    */
-  suspendedTags?: string[];
+  idleTags?: string[];
   meta?: Record<string, unknown>;
 }
 /** A `requests` entry in {@link AgentWorkflowConfig} — the JSON equivalent of a `setupAgent({ requests })` `TextLogicConfig`. Fields beyond `input`/`output`/`tools`/`mode`/`description` are `unknown` because they accept template-expression strings (see {@link AgentWorkflowConfig}). */
@@ -241,14 +241,14 @@ interface FromConfigOptions {
   actions?: Record<string, (params: any) => unknown>;
   /**
    * Detects a snapshot that is an INTENTIONAL wait for an external event —
-   * the same machine-carried predicate `setupAgent({ isSuspended })` declares
+   * the same machine-carried predicate `setupAgent({ isIdle })` declares
    * for TS-authored machines, registered here because a function cannot live
    * in the workflow config itself. Takes precedence over the config's
-   * declarative {@link AgentWorkflowConfig.suspendedTags}; a
-   * `runAgent({ isSuspended })` host override beats both. Travels with the
+   * declarative {@link AgentWorkflowConfig.idleTags}; a
+   * `runAgent({ isIdle })` host override beats both. Travels with the
    * machine through `machine.provide(...)`.
    */
-  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
+  isIdle?: (snapshot: AnyMachineSnapshot) => boolean;
 }
 //#endregion
 //#region src/setup-agent.d.ts
@@ -412,14 +412,14 @@ type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string,
   /**
    * Detects a snapshot that is an INTENTIONAL wait for an external event (a
    * human approval, an inbound webhook, …) — the machine's own declaration of
-   * what "suspended" means for it, so `runAgent` settles those snapshots idle
+   * what "idle" means for it, so `runAgent` settles those snapshots idle
    * deterministically instead of using its timing heuristic. Travels with the
-   * machine through `machine.provide(...)`. A `runAgent({ isSuspended })` host
+   * machine through `machine.provide(...)`. A `runAgent({ isIdle })` host
    * override takes precedence; with neither, `runAgent` falls back to the timing
    * heuristic. Declare your own signal — e.g. `(s) => s.hasTag('awaiting-review')`
    * or `(s) => getStateMeta(s).interaction !== undefined`.
    */
-  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
+  isIdle?: (snapshot: AnyMachineSnapshot) => boolean;
 };
 type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, ResolveAgentStateSchemas<TContextSchema, TStateSchemas>>>;
 /**
@@ -656,9 +656,12 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
  * Throws at bind time if a source needs an executor kind that `executors` does
  * not provide.
  *
- * `provideExecutors` does not descend into invoked child state machines: a string-keyed child
- * machine source is left untouched, so a child with its own agent invokes needs
- * its own `provideExecutors(...)` (or `runAgent`, which does rebind children).
+ * Executor inheritance is RECURSIVE, exactly as in `runAgent`: a string-keyed
+ * invoked child machine is rebound too, so its own text/decision requests — at
+ * any depth — reach the same host executors. A direct-object invoke `src`
+ * cannot be swapped via `.provide`, so nothing under one inherits; bind those
+ * with `.withExecutor(...)` or register the child as a string-keyed source. A
+ * source that already carries its own executor is never overwritten.
  */
 declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
 //#endregion
@@ -677,10 +680,18 @@ interface AgentLintDiagnostic {
   path: string;
   message: string;
 }
-/** Options for {@link lintAgentMachine}. Reserved for future check selection. */
+/** Options for {@link lintAgentMachine}. */
 interface LintAgentMachineOptions {
   /** Skip these check codes entirely. */
   disable?: AgentLintDiagnostic["code"][];
+  /**
+   * Throw {@link AgentLintError} on failing diagnostics instead of returning
+   * them. Fails on error-severity findings; add `warnings: true` to fail on
+   * warnings too.
+   */
+  throw?: boolean;
+  /** With `throw: true`, also fail on warning-severity findings. Default: errors only. */
+  warnings?: boolean;
 }
 /**
  * Runs static structural checks over a built agent machine and returns the
@@ -693,20 +704,28 @@ interface LintAgentMachineOptions {
  * call this to catch dead states, undeliverable decisions, un-rebindable
  * invoke srcs, and output-contract gaps before ever running it.
  *
+ * Pass `{ throw: true }` for the one-liner form used in tests and generation
+ * loops: it returns silently when the machine is clean and throws
+ * {@link AgentLintError} (findings on `.diagnostics`) on error-severity
+ * findings, or on warnings too with `{ throw: true, warnings: true }`.
+ *
  * @example
  * ```ts
  * const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
  * if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
  * ```
+ *
+ * @example Throwing form
+ * ```ts
+ * test('agent machine is structurally sound', () => {
+ *   lintAgentMachine(machine, { throw: true });
+ * });
+ * ```
  */
 declare function lintAgentMachine(machine: AnyStateMachine, options?: LintAgentMachineOptions): AgentLintDiagnostic[];
-/** Options for {@link assertAgentMachine}. */
-interface AssertAgentMachineOptions extends LintAgentMachineOptions {
-  /** Also fail on warning-severity findings. Default: errors only. */
-  warnings?: boolean;
-}
 /**
- * Thrown by {@link assertAgentMachine} when lint finds failing diagnostics.
+ * Thrown by `lintAgentMachine(machine, { throw: true })` when lint finds
+ * failing diagnostics.
  * `diagnostics` holds the findings; the message lists them one per finding,
  * so a test runner's failure output reads like the CLI's lint report.
  */
@@ -714,20 +733,6 @@ declare class AgentLintError extends AgentError {
   readonly diagnostics: AgentLintDiagnostic[];
   constructor(machineId: string, diagnostics: AgentLintDiagnostic[]);
 }
-/**
- * Asserts a machine passes {@link lintAgentMachine}: returns silently when
- * clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
- * otherwise. Fails on error-severity findings; set `warnings: true` to fail on
- * warnings too. The one-liner for tests and generation loops:
- *
- * @example
- * ```ts
- * test('agent machine is structurally sound', () => {
- *   assertAgentMachine(machine);
- * });
- * ```
- */
-declare function assertAgentMachine(machine: AnyStateMachine, options?: AssertAgentMachineOptions): void;
 /**
  * Scripted responses for a {@link simulateAgent} playthrough. Each channel is a
  * by-`src` map of FIFO queues, consumed in the order the machine reaches the
@@ -736,13 +741,17 @@ declare function assertAgentMachine(machine: AnyStateMachine, options?: AssertAg
  *   `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`).
  * - `decisions` — the {@link ChosenEvent} to apply for a decision request,
  *   keyed by decision src (usually `agent.decide`).
- * - `invokes` — output values for scripted invokes (notably `agent.userInput`,
- *   and any other actor whose output must be canned), keyed by src.
+ * - `invokes` — output values for scripted invokes (any actor whose output must
+ *   be canned), keyed by src.
+ * - `userInput` — a flat FIFO queue of answers for `agent.userInput`, the
+ *   shorthand for `invokes: { 'agent.userInput': [...] }`. Entries here are
+ *   consumed before that src's `invokes` queue.
  */
 interface SimulationScript {
   text?: Record<string, unknown[]>;
   decisions?: Record<string, ChosenEvent[]>;
   invokes?: Record<string, unknown[]>;
+  userInput?: unknown[];
 }
 /** One entry in a {@link SimulateAgentResult.trail}: the state after this step, plus what drove the step. */
 interface SimulationTrailEntry {
@@ -798,8 +807,17 @@ interface ExplorePathsOptions {
   maxDepth?: number;
   /** Total path cap before exploration stops (reported via `hitPathCap`). Default 200. */
   maxPaths?: number;
-  /** Canned outputs for text/userInput invokes, keyed by src. A missing src halts that branch with a `needs-output` note. */
-  textOutputs?: Record<string, unknown>;
+  /**
+   * Canned output for each text request, keyed by src (the
+   * `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`).
+   * One value per src, reused every time that src is reached. A missing src
+   * halts that branch with a `needs-output` terminal.
+   */
+  text?: Record<string, unknown>;
+  /** Canned output for scripted invokes, keyed by src. Same one-value-per-src rule as `text`. */
+  invokes?: Record<string, unknown>;
+  /** Canned output for `agent.userInput`, the shorthand for `invokes['agent.userInput']`. */
+  userInput?: unknown;
 }
 /** A single explored path's terminal outcome. */
 interface AgentPathTerminal {
@@ -831,9 +849,10 @@ interface AgentPathReport {
  * depth, model-free, and reports which states are reached and how each path
  * terminates. At each decision request it forks one branch per candidate event
  * (guard-rejected candidates are counted in `prunedByGuard`, not explored); at
- * an idle wait it forks per externally-accepted event. Text/`userInput` invokes
- * are resolved from `textOutputs` (a by-src canned-output map) — a missing src
- * halts that branch with a `needs-output` terminal rather than throwing.
+ * an idle wait it forks per externally-accepted event. Text requests resolve
+ * from `text`, other invokes from `invokes` (or `userInput` for
+ * `agent.userInput`) — all by-src canned-output maps, and a missing src halts
+ * that branch with a `needs-output` terminal rather than throwing.
  *
  * Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
  * 200, reported via `hitPathCap`).
@@ -847,19 +866,21 @@ interface AgentPathReport {
 declare function explorePaths(machine: AnyStateMachine, options?: ExplorePathsOptions): Promise<AgentPathReport>;
 /** The result of a {@link canReach} query. */
 interface CanReachResult {
-  canReach: boolean;
+  /** True when the target state was reached within the exploration bounds. */
+  reachable: boolean;
   /** When reachable, the sequence of chosen/applied events that gets there. */
   witness?: ChosenEvent[];
 }
 /**
  * Answers "can the machine reach `statePath`?" by exploring its branches (a
- * thin wrapper over {@link explorePaths}). Returns `{ canReach: true, witness }`
- * with the event sequence that reaches it, or `{ canReach: false }`.
+ * thin wrapper over {@link explorePaths}). Returns
+ * `{ reachable: true, witness }` with the event sequence that reaches it, or
+ * `{ reachable: false }`.
  *
  * @example
  * ```ts
- * const { canReach, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
- * // canReach → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+ * const { reachable, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+ * // reachable → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
  * ```
  */
 declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
@@ -984,13 +1005,40 @@ type ScriptedDecisionEntry = ScriptedDecisionValue | ((request: AgentDecisionReq
  * `{ output, usage }`), wrap it once more: `{ output: { output: '…' } }`.
  */
 type ScriptedTextEntry = ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => unknown) | string | number | boolean | null | object;
-/** The script {@link createScriptedExecutors} plays back. */
+/**
+ * One entry in the `userInput` queue: the string the simulated human typed, or
+ * a function of the {@link AgentUserInput} request (its `prompt`/`metadata`)
+ * returning one.
+ */
+type ScriptedUserInputEntry = string | ((input: AgentUserInput) => string | PromiseLike<string>);
+/**
+ * The script {@link createScriptedExecutors} plays back.
+ *
+ * The key names match `simulateAgent`'s script (`decisions`, `text`,
+ * `invokes`, `userInput`), but the shapes differ by design: `simulateAgent`
+ * drives the pure step path and keys each channel BY SRC
+ * (`text: { summarize: [...] }`), while these executors sit behind the real
+ * executor contract, where one flat FIFO queue per channel is the ergonomic
+ * form — route per request inside a function entry (`request.name`) when one
+ * script must serve several requests. There is no `invokes` queue here:
+ * non-`userInput` invokes are plain actors, supplied via `actors`.
+ */
 interface ScriptedExecutorsScript {
   /** Answers for `decide` requests, consumed in order. */
   decisions?: ScriptedDecisionEntry[];
   /** Answers for text requests, consumed in order. `generateText` and `streamText` share this one queue. */
   text?: ScriptedTextEntry[];
+  /** Answers for `agent.userInput` requests, consumed in order. */
+  userInput?: ScriptedUserInputEntry[];
 }
+/**
+ * What {@link createScriptedExecutors} returns: the full executor set, plus a
+ * `userInput` handler for `runAgent`'s own `userInput` option (the builtin
+ * `agent.userInput` actor is not an executor slot).
+ */
+type ScriptedExecutors = Required<AgentRequestExecutors> & {
+  userInput: (input: AgentUserInput) => Promise<string>;
+};
 /**
  * Keyless executors that replay a script instead of calling a model. Every
  * slot is provided, so any machine binds; a request with no entry left throws a
@@ -1019,18 +1067,16 @@ interface ScriptedExecutorsScript {
  *   decisions: [(request) => ({ type: request.events[0]!.type })],
  * });
  * ```
+ *
+ * @example Scripted human input
+ * ```ts
+ * const scripted = createScriptedExecutors({ userInput: ['ship it'] });
+ * await runAgent(machine, { executors: scripted, userInput: scripted.userInput });
+ * ```
  */
-declare function createScriptedExecutors(script?: ScriptedExecutorsScript): Required<AgentRequestExecutors>;
+declare function createScriptedExecutors(script?: ScriptedExecutorsScript): ScriptedExecutors;
 //#endregion
 //#region src/utils.d.ts
-/**
- * Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
- * shape you persist and later feed back to `runAgent({ snapshot })`. Asserts
- * JSON-serializability: functions, `undefined`, and other non-JSON values are
- * dropped or throw exactly as `JSON.stringify`/`JSON.parse` would. Returns a
- * plain-JSON deep clone, not a live snapshot.
- */
-declare function persistSnapshot<TSnapshot>(snapshot: TSnapshot): TSnapshot;
 /**
  * A stable, dependency-free structural fingerprint of a machine — a short hex
  * `djb2` hash over its **structural** config only: state ids/nesting, transition
@@ -1043,7 +1089,7 @@ declare function persistSnapshot<TSnapshot>(snapshot: TSnapshot): TSnapshot;
  * Used by {@link runAgent} to stamp settled snapshots with a `version` and to
  * detect a structurally-edited machine on resume. It is a change detector, not
  * a cryptographic digest — collisions are possible but unlikely for real
- * configs. Pass an explicit `machineVersion` to `runAgent` to override it.
+ * configs. Declare `createMachine({ version })` to pin an explicit version instead.
  */
 declare function getMachineStructuralHash(machine: AnyStateMachine): string;
 /** Builds a {@link UserMessage} from a string or multimodal content parts. */
@@ -1063,8 +1109,15 @@ type MetaOfSnapshot<TSnapshot extends {
  *
  * `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
  * state, but parallel/nested machines can have several. This shallow-merges
- * every active state's meta into one object (later/deeper entries win) and
- * returns `{}` when no active state declares meta.
+ * every active state's meta into one object and returns `{}` when no active
+ * state declares meta.
+ *
+ * Merge order is fixed and does not depend on XState's internal node order:
+ * entries are sorted by structural depth (the state node's distance from the
+ * root, regardless of custom `id` strings), then by state id lexicographically,
+ * and merged in that order. So a deeper state's key wins over an ancestor's,
+ * and between equal-depth parallel siblings the later state id alphabetically
+ * wins.
  *
  * The return type is recovered from the snapshot's own `getMeta()` type, so a
  * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
@@ -1119,20 +1172,17 @@ declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, un
 //#endregion
 //#region src/seam.d.ts
 /**
- * Which model call is under test: the Nth call addressed either by request
- * `name` (the `setupAgent({ requests })` key or `createTextLogic({ name })`,
- * the better developer handle) or by `model` key (the `defineModels` key) for
- * requests that carry no name.
+ * Which model call is under test: the Nth call with this request `name` (the
+ * `setupAgent({ requests })` key, or `createTextLogic({ name })`). Name the
+ * requests you want to score — a seam is a developer-facing handle, not a
+ * model binding, so there is no addressing by model key.
  */
-type SeamRef = {
-  /** The request's registered `name`. */request: string;
-  model?: undefined; /** 0-based occurrence among the calls matching this key. Default `0`. */
-  occurrence?: number;
-} | {
-  /** The `defineModels` key the request names. */model: string;
-  request?: undefined; /** 0-based occurrence among the calls matching this key. Default `0`. */
+interface SeamRef {
+  /** The request's registered `name`. */
+  request: string;
+  /** 0-based occurrence among the calls with this name. Default `0`. */
   occurrence?: number;
-};
+}
 /**
  * One idle pause, handed to {@link RunSeamOptions.respond} so the simulated
  * user answers off the machine's own state rather than a fixed transcript — a
@@ -1172,11 +1222,17 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
    * by model.
    *
    * Entries follow {@link ScriptedTextEntry} conventions (a value, an
-   * `{ output, usage? }` envelope, or a function of the request). The LAST
-   * entry of a queue repeats, so a live seam that sends the run down a longer
-   * branch still finds an answer instead of running dry.
+   * `{ output, usage? }` envelope, or a function of the request). A queue that
+   * runs dry throws; set {@link RunSeamOptions.repeatLast} to replay its last
+   * entry instead.
    */
   scripts?: Record<string, ScriptedTextEntry[]>;
+  /**
+   * Replay the LAST entry of a queue once it is exhausted, so a live seam that
+   * sends the run down a longer branch still finds an answer. Off by default:
+   * a dry queue throws, the same as every other scripted surface.
+   */
+  repeatLast?: boolean;
   /** The call under test. */
   seam: SeamRef;
   /**
@@ -1200,7 +1256,7 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
    */
   executors?: Partial<AgentRequestExecutors>;
   /** Passed through to `runAgent`: the deterministic idle-state predicate. */
-  isSuspended?: RunAgentOptions<TMachine>["isSuspended"];
+  isIdle?: RunAgentOptions<TMachine>["isIdle"];
   /** Passed through to `runAgent`: actor implementations merged onto the machine. */
   actors?: RunAgentOptions<TMachine>["actors"];
 }
@@ -1253,4 +1309,76 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  */
 declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
 //#endregion
-export { AGENT_EVENT_SCHEMA_VERSION, AGENT_INIT_EVENT_TYPE, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentActorSession, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionRequest, type AgentEffect, type AgentEffectDiff, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogDiff, type AgentEventLogStore, type AgentEventToolNameResolver, type AgentExecutorTextRequest, AgentIdleError, AgentIllegalResumeEventError, type AgentInputFrom, type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentLogEntry, type AgentLogPatchOperation, type AgentLogVerification, type AgentMessage, type AgentMessageInfo, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, AgentReplayDivergenceError, AgentReplayMachineMismatchError, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRun, type AgentRunMeta, type AgentSchemaPack, type AgentSchemas, type AgentSnapshotStore, AgentSnapshotVersionMismatchError, type AgentStateRequest, type AgentStepRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEvents, type AssertAgentMachineOptions, type AssistantMessage, type CanReachResult, type ChosenEvent, type CreateReplayEntryOptions, type DecisionAttempt, type DecisionLogicConfig, type ExplorePathsOptions, type FilePart, type FromConfigOptions, type FromConfigResult, type GenerateResult, type GetAgentEffectsOptions, type ImagePart, type InferInput, type InferOutput, type InspectedActorRef, type JsonSerializableTraceEvent, type JsonValue, type LintAgentMachineOptions, type MatchTrajectoryOptions, NonSerializableAgentEventError, type PendingUserInput, type ProvideExecutorsOptions, type ReplayOptions, type ReplayResult, type ResolveDecisionOptions, type RunAgentErrorCause, type RunAgentOptions, type RunAgentResult, type RunSeamOptions, type RunSeamResult, type SchemaCompiler, type ScriptedDecisionEntry, type ScriptedDecisionValue, type ScriptedExecutorsScript, type ScriptedTextEntry, type SeamRef, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StandardSchemaV1, type StructuredOutputEnvelope, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, type UserMessage, type WithAgentUsageEvent, appendMessages, assertAgentLogEntry, assertAgentMachine, assertEventLogStoreConformance, assertJsonSerializable, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentActor, createAgentRun, createAgentSchemas, createInMemoryEventLogStore, createReplayEntry, createScriptedExecutors, createTextLogic, diffEventLogs, executeAgentRequest, explorePaths, generateResult, getAcceptedEvents, getAgentEffects, getAgentMessages, getAgentOutputMode, getAgentSchemas, getCallUsage, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initEntry, inspectTransitions, isStandardSchema, lintAgentMachine, matchesTrajectory, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, provideExecutors, renderDecisionAttempts, replay, resolveDecision, runAgent, runSeam, serializeTraceEvent, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage, verifyReplay };
+//#region src/durable.d.ts
+/** Options for {@link runDurableAgent}. */
+interface RunDurableAgentOptions<TMachine extends AnyStateMachine> extends Pick<ProvideExecutorsOptions<TMachine>, "actors" | "onChunk" | "onTrace"> {
+  /** Machine input for a FRESH run (ignored when `entries` has an init entry). */
+  input?: InputFrom<TMachine>;
+  /**
+   * The journal to resume from — the `entries` a previous
+   * {@link runDurableAgent} result returned (or any replay-compatible
+   * {@link AgentLogEntry} log with a reserved `@agent.init` first entry).
+   */
+  entries?: readonly AgentLogEntry[];
+  /** One external event to feed after the journal is folded (a user reply, a timer). */
+  event?: EventFromLogic<TMachine>;
+  /** Host executors, bound with {@link provideExecutors} semantics. */
+  executors?: AgentRequestExecutors;
+  /** Called with each entry as it is appended, for incremental persistence. */
+  onEntry?: (entry: AgentLogEntry) => void;
+  /**
+   * Settle `idle` when this returns true for the current snapshot even though
+   * children are still pending — for machines whose wait states keep a
+   * never-resolving invoke in flight (e.g. an unbound `agent.userInput`).
+   */
+  isIdle?: (snapshot: SnapshotFrom<TMachine>) => boolean;
+  /** Explicit machine version for entry stamping; defaults to the structural hash. */
+  machineVersion?: string;
+  /**
+   * Record replay-verification hashes on appended entries. Off by default:
+   * hashing replays the whole prefix per entry, which is quadratic in log
+   * length.
+   */
+  verification?: boolean;
+}
+/** The settled result of a {@link runDurableAgent} call. */
+type DurableAgentResult<TMachine extends AnyStateMachine> = {
+  /** The machine reached a final state. */status: "done";
+  output: OutputFrom<TMachine>;
+  snapshot: SnapshotFrom<TMachine>; /** The complete journal; replaying it reproduces this run. */
+  entries: AgentLogEntry[];
+} | {
+  /** The machine is waiting for an external event. Persist `entries`; resume with them plus `event`. */status: "idle";
+  snapshot: SnapshotFrom<TMachine>;
+  entries: AgentLogEntry[];
+};
+/**
+ * Runs an agent machine as a durable execution: journal in, journal out.
+ *
+ * A fresh call starts from `input` and appends a reserved init entry; a
+ * resume call folds `entries` through pure transitions first — invokes whose
+ * completions are journaled are suppressed (their recorded results replay
+ * instead of re-executing), while work that was in flight at the crash
+ * re-executes live. After the journal, an optional `options.event` is
+ * delivered. The call settles:
+ *
+ * - `done` when the machine reaches a final state, with `output`;
+ * - `idle` when the frontier needs an external event the host has not
+ *   supplied (no live work pending, or `isIdle` says the pending work is a
+ *   human wait). Persist `entries` and call again with them later.
+ *
+ * ```ts
+ * const first = await runDurableAgent(machine, { input, executors });
+ * // ... persist first.entries; later, in a new process:
+ * const next = await runDurableAgent(machine, {
+ *   entries: first.entries,
+ *   event: { type: "APPROVE" },
+ *   executors,
+ * });
+ * ```
+ *
+ * @experimental Built on xstate's experimental `xstate/durable` entrypoint.
+ */
+declare function runDurableAgent<TMachine extends AnyStateMachine>(machine: TMachine, options?: RunDurableAgentOptions<TMachine>): Promise<DurableAgentResult<TMachine>>;
+//#endregion
+export { AGENT_EVENT_SCHEMA_VERSION, AGENT_INIT_EVENT_TYPE, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentActorSession, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionRequest, type AgentEffect, type AgentEffectDiff, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogDiff, type AgentEventLogStore, type AgentEventToolNameResolver, type AgentExecutorTextRequest, AgentIdleError, AgentIllegalResumeEventError, type AgentInputFrom, type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentLogEntry, type AgentLogPatchOperation, type AgentLogVerification, AgentMaxModelCallsExceededError, type AgentMessage, type AgentMessageInfo, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, AgentReplayDivergenceError, AgentReplayMachineMismatchError, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRun, type AgentRunMeta, type AgentSchemaPack, type AgentSchemas, type AgentSnapshotNode, type AgentSnapshotStore, AgentSnapshotVersionMismatchError, type AgentStateRequest, type AgentStepRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEvents, type AssistantMessage, type CanReachResult, type ChosenEvent, type CreateReplayEntryOptions, type DecisionAttempt, type DecisionLogicConfig, type DurableAgentResult, type ExplorePathsOptions, type FilePart, type FromConfigOptions, type FromConfigResult, type GenerateResult, type GetAgentEffectsOptions, type GetSnapshotRequestsOptions, type ImagePart, type InferInput, type InferOutput, type InspectedActorRef, type JsonSerializableTraceEvent, type JsonValue, type LintAgentMachineOptions, type MatchTrajectoryOptions, NonSerializableAgentEventError, type PendingUserInput, type ProvideExecutorsOptions, type ReplayOptions, type ReplayResult, type ResolveDecisionOptions, type RunAgentErrorCause, type RunAgentOptions, type RunAgentResult, type RunDurableAgentOptions, type RunSeamOptions, type RunSeamResult, type SchemaCompiler, type ScriptedDecisionEntry, type ScriptedDecisionValue, type ScriptedExecutors, type ScriptedExecutorsScript, type ScriptedTextEntry, type ScriptedUserInputEntry, type SeamRef, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StandardSchemaV1, type StructuredOutputEnvelope, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, type UserMessage, type WithAgentUsageEvent, appendMessages, assertAgentLogEntry, assertEventLogStoreConformance, assertJsonSerializable, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentActor, createAgentRun, createAgentSchemas, createInMemoryEventLogStore, createReplayEntry, createScriptedExecutors, createTextLogic, diffEventLogs, executeAgentRequest, explorePaths, generateResult, getAcceptedEvents, getAgentEffects, getAgentMessages, getAgentOutputMode, getAgentSchemas, getCallUsage, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getSnapshotNodes, getSnapshotRequests, getStateMeta, initEntry, inspectTransitions, isStandardSchema, lintAgentMachine, matchesTrajectory, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, provideExecutors, renderDecisionAttempts, replay, resolveDecision, runAgent, runDurableAgent, runSeam, serializeTraceEvent, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage };