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

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-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-pJ5Hn8fv.cjs";
+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-DSdj2tGs.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
-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-Cavva1W6.cjs";
+import { A as AgentDecisionExecutor, B as resolveDecision, C as buildEnvelopeSchema, D as parseModelRef, E as getCallUsage, F as DecisionLogic, G as AgentSchemas, H as AgentEventToolNameResolver, I as DecisionLogicConfig, K as getAcceptedEvents, L as ResolveDecisionOptions, M as AgentDecisionInput, N as AgentDecisionRequest, O as parseOutput, P as DecisionAttempt, R as createDecisionLogic, S as bindRequestExecutor, T as getAgentOutputMode, U as AgentRequestOptions, V as AgentEventDescriptor, W as AgentRequestSource, _ 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, q as parseAgentEvent, 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 renderDecisionAttempts } from "./text-logic-BaxPrcLk.cjs";
 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-Bz7HDBkE.cjs";
-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--4bbms-D.cjs";
+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-Zbkx7XP8.cjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, InputFrom, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/messages.d.ts
@@ -40,8 +40,9 @@ declare function appendMessages<TContext extends {
  * A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
  * checks that every message has a known `role` (`system`/`user`/`assistant`/
  * `tool`) and that `content` is either a string (where the role allows it) or
- * an array of parts with a known `type`. Use it directly as a context
- * schema's `messages` field when authoring with `createAgentSchemas`.
+ * an array of role-appropriate parts whose required fields and media payloads
+ * have the right runtime types (extra fields are allowed). Use it directly as
+ * a context schema's `messages` field when authoring with `createAgentSchemas`.
  */
 declare const messagesSchema: StandardSchemaV1<AgentMessage[]>;
 //#endregion
@@ -121,8 +122,8 @@ interface AgentWorkflowRequestConfig {
   output: JsonSchemaObject;
   tools?: AgentTools;
   toolChoice?: AgentToolChoice | unknown;
-  /** Opt into the structured-output envelope's `reasoning` field (see `AgentTextRequest.reasoning`). */
-  reasoning?: boolean;
+  /** Opt into the structured-output envelope's `reasoning` field (see `AgentTextRequest.includeReasoning`). */
+  includeReasoning?: boolean;
   temperature?: unknown;
   maxOutputTokens?: unknown;
   topP?: unknown;
@@ -255,6 +256,22 @@ interface FromConfigOptions {
 type Constrain<T, TConstraint> = T extends TConstraint ? T : TConstraint;
 type ContextOf<TContextSchema extends StandardSchemaV1> = Constrain<InferOutput<TContextSchema>, MachineContext>;
 type EventsOf<TEventSchemas extends AgentEventSchemaInputMap> = Constrain<EventUnion<TEventSchemas>, EventObject>;
+/**
+ * The first argument a guard or delay source receives. `context` and `event`
+ * come from the agent's own schemas, so an inline source is contextually typed
+ * and an annotated one stays assignable. XState's remaining fields (`self`,
+ * `parent`, `value`, `children`, `stateNode`) are deliberately not modeled:
+ * `setupAgent` only forwards these sources to `setup()`, which types them for
+ * real where the machine is built.
+ */
+type AgentSourceArgs<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = {
+  context: ContextOf<TContextSchema>;
+  event: EventsOf<TEventSchemas>;
+};
+/** Guard sources for `setupAgent({ guards })`, typed against the agent's own context and events. */
+type AgentGuardSources<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = Record<string, (args: AgentSourceArgs<TContextSchema, TEventSchemas>, ...params: any[]) => boolean>;
+/** Delay sources for `setupAgent({ delays })`, typed the same way as {@link AgentGuardSources}. */
+type AgentDelaySources<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = Record<string, number | ((args: AgentSourceArgs<TContextSchema, TEventSchemas>) => number)>;
 type SetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic }> = { [K in keyof TActors]: TActors[K] extends AsyncActorLogic<infer TOutput, infer TInput> ? AsyncActorLogic<TOutput, TInput> : TActors[K] };
 type AgentSetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic }, TEvent extends string = string, TModel extends string = string> = TActors & BuiltinAgentActors<TEvent, TModel>;
 /**
@@ -407,8 +424,8 @@ type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string,
   states?: TStateSchemas;
   requests?: AgentRequestInput<TRequestSchemas, AgentModelRef<TModels>>;
   actions?: NonNullable<AnySetupConfig["actions"]>;
-  guards?: NonNullable<AnySetupConfig["guards"]>;
-  delays?: NonNullable<AnySetupConfig["delays"]>;
+  guards?: AgentGuardSources<TContextSchema, TEventSchemas>;
+  delays?: AgentDelaySources<TContextSchema, TEventSchemas>;
   /**
    * Detects a snapshot that is an INTENTIONAL wait for an external event (a
    * human approval, an inbound webhook, …) — the machine's own declaration of
@@ -724,8 +741,8 @@ interface LintAgentMachineOptions {
  */
 declare function lintAgentMachine(machine: AnyStateMachine, options?: LintAgentMachineOptions): AgentLintDiagnostic[];
 /**
- * Thrown by `lintAgentMachine(machine, { throw: true })` when lint finds
- * failing diagnostics.
+ * Thrown by `lintAgentMachine(machine, { throw: true })` (and its
+ * {@link assertAgentMachine} alias) 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.
  */
@@ -733,6 +750,26 @@ declare class AgentLintError extends AgentError {
   readonly diagnostics: AgentLintDiagnostic[];
   constructor(machineId: string, diagnostics: AgentLintDiagnostic[]);
 }
+/** Options for {@link assertAgentMachine}. */
+interface AssertAgentMachineOptions extends LintAgentMachineOptions {
+  /** Also fail on warning-severity findings. Default: errors only. */
+  warnings?: boolean;
+}
+/**
+ * Asserts a machine passes {@link lintAgentMachine}: returns silently when
+ * clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+ * otherwise — sugar for `lintAgentMachine(machine, { ...options, throw: true })`.
+ * 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
@@ -740,25 +777,49 @@ declare class AgentLintError extends AgentError {
  * - `text` — output values for text requests, keyed by request src (the
  *   `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`).
+ *   keyed by decision src (usually `agent.decide`). An invoke whose src is an
+ *   inline logic object has only an auto-generated src, so its queue may be
+ *   keyed by the invoke's `id` instead.
  * - `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.
+ * - `events` — a flat FIFO queue of external (human/host-sent) events. When the
+ *   machine settles idle with no pending request or invoke — a human gate — the
+ *   next queued event is applied, so a simulation can cross states that a live
+ *   run crosses via `actor.send(...)`. An event the current state cannot take
+ *   (no handler, or guard-rejected) throws rather than silently vanishing.
  */
 interface SimulationScript {
   text?: Record<string, unknown[]>;
   decisions?: Record<string, ChosenEvent[]>;
   invokes?: Record<string, unknown[]>;
   userInput?: unknown[];
+  events?: ChosenEvent[];
 }
-/** One entry in a {@link SimulateAgentResult.trail}: the state after this step, plus what drove the step. */
+/**
+ * One entry in a {@link SimulateAgentResult.trail}: the state after this step,
+ * plus what drove the step. The first entry is always the machine's initial
+ * state, with no `appliedEvent`/`resolvedRequest` — so `trail.map((e) =>
+ * e.state)` is the complete state path, directly comparable with
+ * `matchesTrajectory` without prepending the initial state by hand.
+ */
 interface SimulationTrailEntry {
   /** The machine state value after applying this step. */
   state: unknown;
-  /** The chosen event applied (for a decision request). */
+  /** The chosen event applied (for a decision request), or the external event applied (when `external`). */
   appliedEvent?: ChosenEvent;
+  /** True when `appliedEvent` came from the script's `events` queue (an external/user event), not a decision. */
+  external?: boolean;
+  /**
+   * Scripted decisions that failed validation (unknown event, invalid payload,
+   * or guard-rejected — live-run retry parity, see {@link simulateAgent})
+   * before this step settled. Present with an `appliedEvent` when a later
+   * scripted attempt succeeded, or alone when every attempt failed and the
+   * exhaustion error was routed through the decision invoke's `onError`.
+   */
+  rejectedEvents?: ChosenEvent[];
   /** The resolved request (for a text/userInput invoke): its kind and src. */
   resolvedRequest?: {
     kind: "text" | "userInput";
@@ -787,6 +848,21 @@ interface SimulateAgentResult {
  * the real transition logic. Returns the terminal `status`, final `snapshot`,
  * and a `trail` of every step taken.
  *
+ * Decisions run through the live run's own validation/retry core,
+ * {@link resolveDecision}, with the script standing in for the model: each
+ * attempt consumes the next queued {@link ChosenEvent} for that src, so an
+ * unknown, payload-invalid, or guard-rejected event is NOT silently swallowed
+ * — the next queued decision is tried, exactly as a live run re-asks the
+ * model. The decision logic's `maxRetries` caps attempts as it would live;
+ * when retries continue past the end of the queue, the last queued decision
+ * repeats (a scripted model that insists). The repeat applies only within one
+ * decision request's retries — each new decision request must have its own
+ * queued entry, or the dry-script error throws as usual. Exhausting all
+ * attempts delivers
+ * the resulting {@link AgentDecisionExhaustedError} to the machine as the
+ * decision invoke's error (so an `onError` transition observes it, as it
+ * would live); with no `onError` to catch it, it is thrown.
+ *
  * Throws a descriptive error when the script runs dry mid-request, naming the
  * pending request's kind, src, and id so the missing scripted response is
  * obvious.
@@ -795,7 +871,10 @@ interface SimulateAgentResult {
  * ```ts
  * const { status, snapshot } = simulateAgent(machine, {
  *   input: { topic: 'state machines' },
- *   script: { decisions: { 'agent.decide': [{ type: 'END' }] } },
+ *   script: {
+ *     decisions: { 'agent.decide': [{ type: 'ESCALATE' }] },
+ *     events: [{ type: 'APPROVE' }], // crosses the human gate
+ *   },
  * });
  * ```
  */
@@ -872,8 +951,11 @@ interface CanReachResult {
   witness?: ChosenEvent[];
 }
 /**
- * Answers "can the machine reach `statePath`?" by exploring its branches (a
- * thin wrapper over {@link explorePaths}). Returns
+ * Answers "can the machine reach this?" by exploring its branches (a thin
+ * wrapper over {@link explorePaths}). The target is either a state path string
+ * (`snapshot.matches(...)` semantics) or a snapshot predicate — the predicate
+ * form checks any property (a context invariant, a tag, a state+context
+ * combination) without reifying a sentinel state for it. Returns
  * `{ reachable: true, witness }` with the event sequence that reaches it, or
  * `{ reachable: false }`.
  *
@@ -882,8 +964,18 @@ interface CanReachResult {
  * const { reachable, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
  * // reachable → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
  * ```
+ *
+ * @example Predicate target — a violation property, no sentinel state needed
+ * ```ts
+ * const violation = await canReach(
+ *   refundMachine,
+ *   (snapshot) => snapshot.matches('issued') && !snapshot.context.approved,
+ *   { input: { amount: 5000 } },
+ * );
+ * // violation.reachable → false is the safety proof
+ * ```
  */
-declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
+declare function canReach(machine: AnyStateMachine, target: string | ((snapshot: AnyMachineSnapshot) => boolean), options?: ExplorePathsOptions): Promise<CanReachResult>;
 //#endregion
 //#region src/trajectory.d.ts
 /** An event-shaped trajectory item: anything with a string `type`. */
@@ -1204,6 +1296,26 @@ interface SeamTurn<TMachine extends AnyStateMachine> {
   /** The `idle` result that produced the pause. */
   result: RunAgentResult<TMachine>;
 }
+/**
+ * One text call in a {@link runSeam} run's ledger, in call order — the receipt
+ * that says which answers came from the script and which one came from the
+ * candidate, so "everything else stayed scripted" is a plain assertion on
+ * {@link RunSeamResult.calls} rather than a recording function wrapped around
+ * every script entry. Text calls only: `decide` and other base executors are
+ * not routed by the seam and do not appear.
+ */
+interface SeamCall {
+  /** The request's `name`, when it has one. */
+  name?: string;
+  /** The request's model key. */
+  model: string;
+  /** The `scripts` queue key that routed this call. */
+  key: string;
+  /** Where the answer came from: the script, or the seam's `candidate`. */
+  source: "script" | "candidate";
+  /** True for the seam call itself — scripted or candidate. */
+  seam: boolean;
+}
 /** One side of the seam: a trajectory pair ready for `matchesTrajectory`. */
 interface SeamSlice {
   /** State values entered on this side of the seam, in order. */
@@ -1240,7 +1352,7 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
    * request-shaped. Omit to run the seam scripted too: the whole seam run is
    * then keyless and deterministic.
    */
-  candidate?: AgentRequestExecutors["generateText"];
+  candidate?: AgentRequestExecutor;
   /**
    * The simulated user. Called at every idle pause; return the event to send,
    * or `null`/`undefined` to stop the run there. Omitted, the run stops at the
@@ -1269,8 +1381,17 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
   result: RunAgentResult<TMachine>;
   /** What the seam call returned, or `undefined` when the run never reached it. */
   seamOutput: unknown;
+  /**
+   * The seam call's own reported token usage — the cost of the one live call
+   * when a `candidate` is a real model. `undefined` when the run never reached
+   * the seam or its answer reported no usage (scripted entries report usage
+   * only via the `{ output, usage }` envelope).
+   */
+  seamUsage?: AgentCallUsage;
   /** Model calls made before the seam, or `-1` when the run never reached it. */
   callsBeforeSeam: number;
+  /** The run's text calls in order: what was served, and by whom. */
+  calls: SeamCall[];
   /** Everything up to the seam's own effect completion. */
   before: SeamSlice;
   /**
@@ -1381,4 +1502,4 @@ type DurableAgentResult<TMachine extends AnyStateMachine> = {
  */
 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 };
+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 AssertAgentMachineOptions, type AssistantMessage, type CanReachResult, type ChosenEvent, type CreateReplayEntryOptions, type DecisionAttempt, type DecisionLogic, 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 SeamCall, 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, createDecisionLogic, 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 };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-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 { 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-CvWRGFxP.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-Er5KkTX6.mjs";
+import { A as AgentDecisionExecutor, B as resolveDecision, C as buildEnvelopeSchema, D as parseModelRef, E as getCallUsage, F as DecisionLogic, G as AgentSchemas, H as AgentEventToolNameResolver, I as DecisionLogicConfig, K as getAcceptedEvents, L as ResolveDecisionOptions, M as AgentDecisionInput, N as AgentDecisionRequest, O as parseOutput, P as DecisionAttempt, R as createDecisionLogic, S as bindRequestExecutor, T as getAgentOutputMode, U as AgentRequestOptions, V as AgentEventDescriptor, W as AgentRequestSource, _ 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, q as parseAgentEvent, 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 renderDecisionAttempts } from "./text-logic-DhfFWzu9.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 { 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-0fpEZ1wJ.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
@@ -40,8 +40,9 @@ declare function appendMessages<TContext extends {
  * A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
  * checks that every message has a known `role` (`system`/`user`/`assistant`/
  * `tool`) and that `content` is either a string (where the role allows it) or
- * an array of parts with a known `type`. Use it directly as a context
- * schema's `messages` field when authoring with `createAgentSchemas`.
+ * an array of role-appropriate parts whose required fields and media payloads
+ * have the right runtime types (extra fields are allowed). Use it directly as
+ * a context schema's `messages` field when authoring with `createAgentSchemas`.
  */
 declare const messagesSchema: StandardSchemaV1<AgentMessage[]>;
 //#endregion
@@ -121,8 +122,8 @@ interface AgentWorkflowRequestConfig {
   output: JsonSchemaObject;
   tools?: AgentTools;
   toolChoice?: AgentToolChoice | unknown;
-  /** Opt into the structured-output envelope's `reasoning` field (see `AgentTextRequest.reasoning`). */
-  reasoning?: boolean;
+  /** Opt into the structured-output envelope's `reasoning` field (see `AgentTextRequest.includeReasoning`). */
+  includeReasoning?: boolean;
   temperature?: unknown;
   maxOutputTokens?: unknown;
   topP?: unknown;
@@ -255,6 +256,22 @@ interface FromConfigOptions {
 type Constrain<T, TConstraint> = T extends TConstraint ? T : TConstraint;
 type ContextOf<TContextSchema extends StandardSchemaV1> = Constrain<InferOutput<TContextSchema>, MachineContext>;
 type EventsOf<TEventSchemas extends AgentEventSchemaInputMap> = Constrain<EventUnion<TEventSchemas>, EventObject>;
+/**
+ * The first argument a guard or delay source receives. `context` and `event`
+ * come from the agent's own schemas, so an inline source is contextually typed
+ * and an annotated one stays assignable. XState's remaining fields (`self`,
+ * `parent`, `value`, `children`, `stateNode`) are deliberately not modeled:
+ * `setupAgent` only forwards these sources to `setup()`, which types them for
+ * real where the machine is built.
+ */
+type AgentSourceArgs<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = {
+  context: ContextOf<TContextSchema>;
+  event: EventsOf<TEventSchemas>;
+};
+/** Guard sources for `setupAgent({ guards })`, typed against the agent's own context and events. */
+type AgentGuardSources<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = Record<string, (args: AgentSourceArgs<TContextSchema, TEventSchemas>, ...params: any[]) => boolean>;
+/** Delay sources for `setupAgent({ delays })`, typed the same way as {@link AgentGuardSources}. */
+type AgentDelaySources<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = Record<string, number | ((args: AgentSourceArgs<TContextSchema, TEventSchemas>) => number)>;
 type SetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic }> = { [K in keyof TActors]: TActors[K] extends AsyncActorLogic<infer TOutput, infer TInput> ? AsyncActorLogic<TOutput, TInput> : TActors[K] };
 type AgentSetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic }, TEvent extends string = string, TModel extends string = string> = TActors & BuiltinAgentActors<TEvent, TModel>;
 /**
@@ -407,8 +424,8 @@ type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string,
   states?: TStateSchemas;
   requests?: AgentRequestInput<TRequestSchemas, AgentModelRef<TModels>>;
   actions?: NonNullable<AnySetupConfig["actions"]>;
-  guards?: NonNullable<AnySetupConfig["guards"]>;
-  delays?: NonNullable<AnySetupConfig["delays"]>;
+  guards?: AgentGuardSources<TContextSchema, TEventSchemas>;
+  delays?: AgentDelaySources<TContextSchema, TEventSchemas>;
   /**
    * Detects a snapshot that is an INTENTIONAL wait for an external event (a
    * human approval, an inbound webhook, …) — the machine's own declaration of
@@ -724,8 +741,8 @@ interface LintAgentMachineOptions {
  */
 declare function lintAgentMachine(machine: AnyStateMachine, options?: LintAgentMachineOptions): AgentLintDiagnostic[];
 /**
- * Thrown by `lintAgentMachine(machine, { throw: true })` when lint finds
- * failing diagnostics.
+ * Thrown by `lintAgentMachine(machine, { throw: true })` (and its
+ * {@link assertAgentMachine} alias) 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.
  */
@@ -733,6 +750,26 @@ declare class AgentLintError extends AgentError {
   readonly diagnostics: AgentLintDiagnostic[];
   constructor(machineId: string, diagnostics: AgentLintDiagnostic[]);
 }
+/** Options for {@link assertAgentMachine}. */
+interface AssertAgentMachineOptions extends LintAgentMachineOptions {
+  /** Also fail on warning-severity findings. Default: errors only. */
+  warnings?: boolean;
+}
+/**
+ * Asserts a machine passes {@link lintAgentMachine}: returns silently when
+ * clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+ * otherwise — sugar for `lintAgentMachine(machine, { ...options, throw: true })`.
+ * 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
@@ -740,25 +777,49 @@ declare class AgentLintError extends AgentError {
  * - `text` — output values for text requests, keyed by request src (the
  *   `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`).
+ *   keyed by decision src (usually `agent.decide`). An invoke whose src is an
+ *   inline logic object has only an auto-generated src, so its queue may be
+ *   keyed by the invoke's `id` instead.
  * - `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.
+ * - `events` — a flat FIFO queue of external (human/host-sent) events. When the
+ *   machine settles idle with no pending request or invoke — a human gate — the
+ *   next queued event is applied, so a simulation can cross states that a live
+ *   run crosses via `actor.send(...)`. An event the current state cannot take
+ *   (no handler, or guard-rejected) throws rather than silently vanishing.
  */
 interface SimulationScript {
   text?: Record<string, unknown[]>;
   decisions?: Record<string, ChosenEvent[]>;
   invokes?: Record<string, unknown[]>;
   userInput?: unknown[];
+  events?: ChosenEvent[];
 }
-/** One entry in a {@link SimulateAgentResult.trail}: the state after this step, plus what drove the step. */
+/**
+ * One entry in a {@link SimulateAgentResult.trail}: the state after this step,
+ * plus what drove the step. The first entry is always the machine's initial
+ * state, with no `appliedEvent`/`resolvedRequest` — so `trail.map((e) =>
+ * e.state)` is the complete state path, directly comparable with
+ * `matchesTrajectory` without prepending the initial state by hand.
+ */
 interface SimulationTrailEntry {
   /** The machine state value after applying this step. */
   state: unknown;
-  /** The chosen event applied (for a decision request). */
+  /** The chosen event applied (for a decision request), or the external event applied (when `external`). */
   appliedEvent?: ChosenEvent;
+  /** True when `appliedEvent` came from the script's `events` queue (an external/user event), not a decision. */
+  external?: boolean;
+  /**
+   * Scripted decisions that failed validation (unknown event, invalid payload,
+   * or guard-rejected — live-run retry parity, see {@link simulateAgent})
+   * before this step settled. Present with an `appliedEvent` when a later
+   * scripted attempt succeeded, or alone when every attempt failed and the
+   * exhaustion error was routed through the decision invoke's `onError`.
+   */
+  rejectedEvents?: ChosenEvent[];
   /** The resolved request (for a text/userInput invoke): its kind and src. */
   resolvedRequest?: {
     kind: "text" | "userInput";
@@ -787,6 +848,21 @@ interface SimulateAgentResult {
  * the real transition logic. Returns the terminal `status`, final `snapshot`,
  * and a `trail` of every step taken.
  *
+ * Decisions run through the live run's own validation/retry core,
+ * {@link resolveDecision}, with the script standing in for the model: each
+ * attempt consumes the next queued {@link ChosenEvent} for that src, so an
+ * unknown, payload-invalid, or guard-rejected event is NOT silently swallowed
+ * — the next queued decision is tried, exactly as a live run re-asks the
+ * model. The decision logic's `maxRetries` caps attempts as it would live;
+ * when retries continue past the end of the queue, the last queued decision
+ * repeats (a scripted model that insists). The repeat applies only within one
+ * decision request's retries — each new decision request must have its own
+ * queued entry, or the dry-script error throws as usual. Exhausting all
+ * attempts delivers
+ * the resulting {@link AgentDecisionExhaustedError} to the machine as the
+ * decision invoke's error (so an `onError` transition observes it, as it
+ * would live); with no `onError` to catch it, it is thrown.
+ *
  * Throws a descriptive error when the script runs dry mid-request, naming the
  * pending request's kind, src, and id so the missing scripted response is
  * obvious.
@@ -795,7 +871,10 @@ interface SimulateAgentResult {
  * ```ts
  * const { status, snapshot } = simulateAgent(machine, {
  *   input: { topic: 'state machines' },
- *   script: { decisions: { 'agent.decide': [{ type: 'END' }] } },
+ *   script: {
+ *     decisions: { 'agent.decide': [{ type: 'ESCALATE' }] },
+ *     events: [{ type: 'APPROVE' }], // crosses the human gate
+ *   },
  * });
  * ```
  */
@@ -872,8 +951,11 @@ interface CanReachResult {
   witness?: ChosenEvent[];
 }
 /**
- * Answers "can the machine reach `statePath`?" by exploring its branches (a
- * thin wrapper over {@link explorePaths}). Returns
+ * Answers "can the machine reach this?" by exploring its branches (a thin
+ * wrapper over {@link explorePaths}). The target is either a state path string
+ * (`snapshot.matches(...)` semantics) or a snapshot predicate — the predicate
+ * form checks any property (a context invariant, a tag, a state+context
+ * combination) without reifying a sentinel state for it. Returns
  * `{ reachable: true, witness }` with the event sequence that reaches it, or
  * `{ reachable: false }`.
  *
@@ -882,8 +964,18 @@ interface CanReachResult {
  * const { reachable, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
  * // reachable → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
  * ```
+ *
+ * @example Predicate target — a violation property, no sentinel state needed
+ * ```ts
+ * const violation = await canReach(
+ *   refundMachine,
+ *   (snapshot) => snapshot.matches('issued') && !snapshot.context.approved,
+ *   { input: { amount: 5000 } },
+ * );
+ * // violation.reachable → false is the safety proof
+ * ```
  */
-declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
+declare function canReach(machine: AnyStateMachine, target: string | ((snapshot: AnyMachineSnapshot) => boolean), options?: ExplorePathsOptions): Promise<CanReachResult>;
 //#endregion
 //#region src/trajectory.d.ts
 /** An event-shaped trajectory item: anything with a string `type`. */
@@ -1204,6 +1296,26 @@ interface SeamTurn<TMachine extends AnyStateMachine> {
   /** The `idle` result that produced the pause. */
   result: RunAgentResult<TMachine>;
 }
+/**
+ * One text call in a {@link runSeam} run's ledger, in call order — the receipt
+ * that says which answers came from the script and which one came from the
+ * candidate, so "everything else stayed scripted" is a plain assertion on
+ * {@link RunSeamResult.calls} rather than a recording function wrapped around
+ * every script entry. Text calls only: `decide` and other base executors are
+ * not routed by the seam and do not appear.
+ */
+interface SeamCall {
+  /** The request's `name`, when it has one. */
+  name?: string;
+  /** The request's model key. */
+  model: string;
+  /** The `scripts` queue key that routed this call. */
+  key: string;
+  /** Where the answer came from: the script, or the seam's `candidate`. */
+  source: "script" | "candidate";
+  /** True for the seam call itself — scripted or candidate. */
+  seam: boolean;
+}
 /** One side of the seam: a trajectory pair ready for `matchesTrajectory`. */
 interface SeamSlice {
   /** State values entered on this side of the seam, in order. */
@@ -1240,7 +1352,7 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
    * request-shaped. Omit to run the seam scripted too: the whole seam run is
    * then keyless and deterministic.
    */
-  candidate?: AgentRequestExecutors["generateText"];
+  candidate?: AgentRequestExecutor;
   /**
    * The simulated user. Called at every idle pause; return the event to send,
    * or `null`/`undefined` to stop the run there. Omitted, the run stops at the
@@ -1269,8 +1381,17 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
   result: RunAgentResult<TMachine>;
   /** What the seam call returned, or `undefined` when the run never reached it. */
   seamOutput: unknown;
+  /**
+   * The seam call's own reported token usage — the cost of the one live call
+   * when a `candidate` is a real model. `undefined` when the run never reached
+   * the seam or its answer reported no usage (scripted entries report usage
+   * only via the `{ output, usage }` envelope).
+   */
+  seamUsage?: AgentCallUsage;
   /** Model calls made before the seam, or `-1` when the run never reached it. */
   callsBeforeSeam: number;
+  /** The run's text calls in order: what was served, and by whom. */
+  calls: SeamCall[];
   /** Everything up to the seam's own effect completion. */
   before: SeamSlice;
   /**
@@ -1381,4 +1502,4 @@ type DurableAgentResult<TMachine extends AnyStateMachine> = {
  */
 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 };
+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 AssertAgentMachineOptions, type AssistantMessage, type CanReachResult, type ChosenEvent, type CreateReplayEntryOptions, type DecisionAttempt, type DecisionLogic, 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 SeamCall, 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, createDecisionLogic, 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 };