@statelyai/agent 2.0.0-alpha.14 → 2.0.0-alpha.16

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, a as AgentToolChoice, b as ToolCallPart, c as AgentTools, d as ChosenEvent, f as EventUnion, g as NormalizedEventSchemas, h as InferOutput, 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 SystemMessage, x as ToolMessage, y as TextPart } from "./types-rMe7x6NR.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-pJ5Hn8fv.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
-import { A as AgentDecisionExhaustedError, B as AgentRequestOptions, C as buildEnvelopeSchema, D as parseOutput, E as parseModelRef, F as ResolveDecisionOptions, H as getAcceptedEvents, I as renderDecisionAttempts, L as resolveDecision, M as AgentDecisionRequest, N as DecisionAttempt, O as parseStructuredEnvelope, P as DecisionLogicConfig, R as AgentEventDescriptor, S as bindRequestExecutor, T as getAgentOutputMode, U as parseAgentEvent, V 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 AgentDecisionInput, k as AgentDecisionExecutor, 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 AgentEventToolNameResolver } from "./text-logic-Jkilp1Ie.cjs";
-import { a as AgentLogVerification, c as assertAgentLogEntry, d as createInMemoryEventLogStore, i as AgentLogEntry, l as assertEventLogStoreConformance, n as AgentEventLogConflictError, o as JsonValue, r as AgentEventLogStore, s as NonSerializableAgentEventError, t as AGENT_EVENT_SCHEMA_VERSION, u as assertJsonSerializable } from "./event-log-store-CVd2eyRy.cjs";
-import { A as AgentEffectDiff, B as createReplayEntry, C as AgentStateRequest, D as AGENT_INIT_EVENT_TYPE, E as executeAgentRequest, F as AgentUsageEvent, G as replay, H as getAgentEffects, I as CreateReplayEntryOptions, K as verifyReplay, L as GetAgentEffectsOptions, M as AgentLogPatchOperation, N as AgentReplayDivergenceError, O as AGENT_USAGE_EVENT_TYPE, P as AgentReplayMachineMismatchError, R as ReplayOptions, S as traceTransitions, T as AgentStepRequest, U as getCallUsage, V as diffEventLogs, W as initEntry, _ as createAgentActor, a as AgentMessageInfo, b as runAgent, c as AgentTraceEvent, d as InspectedActorRef, f as JsonSerializableTraceEvent, g as RunAgentResult, h as RunAgentOptions, i as AgentIllegalResumeEventError, j as AgentEventLogDiff, k as AgentEffect, l as AgentUserInputExecutor, m as RunAgentErrorCause, n as AgentActorSession, o as AgentRunMeta, p as PendingUserInput, r as AgentIdleError, s as AgentSnapshotVersionMismatchError, t as AGENT_TRACE_SCHEMA_VERSION, u as GenerateResult, v as generateResult, w as AgentRequest, x as serializeTraceEvent, y as inspectTransitions, z as ReplayResult } from "./run-agent-BlqKwHIF.cjs";
+import { A as AgentDecisionExecutor, B as AgentEventToolNameResolver, C as buildEnvelopeSchema, D as parseModelRef, E as getCallUsage, F as DecisionLogicConfig, 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 getAcceptedEvents, V as AgentRequestOptions, W as parseAgentEvent, _ 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-BFX5q7fM.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-CQJq8_v4.cjs";
+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-BxjGaVpL.cjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, InputFrom, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/messages.d.ts
@@ -309,10 +309,27 @@ type AgentSetupEventsSchema<TEventSchemas extends AgentEventSchemaInputMap> = {
 type AgentSetupEmittedSchema<TEmittedSchemas extends Record<string, StandardSchemaV1>> = [keyof TEmittedSchemas] extends [never] ? {} : {
   emitted: TEmittedSchemas;
 };
+/**
+ * The input schema as handed to xstate's `setup(...)`, with the machine's input
+ * type branded by the schema it came from.
+ *
+ * XState resolves `schemas.input` to a single type used both by
+ * `createActor`'s `input` option and by the `context: ({ input })` factory —
+ * and it never validates, so a schema default reads as a required field at the
+ * call site while being absent at runtime. `runAgent` validates the input
+ * (filling defaults) and reads this brand back through `AgentInputFrom` to
+ * accept the schema's looser *input* side, while the factory keeps seeing the
+ * validated *output* side.
+ *
+ * Only object-shaped input is branded: with no declared input schema the
+ * resolved type is xstate's `NonReducibleUnknown` (a union including `null`),
+ * and intersecting a brand into that collapses members to `never`.
+ */
+type BrandedInputSchema<TInputSchema extends StandardSchemaV1> = InferOutput<TInputSchema> extends Record<string, unknown> ? StandardSchemaV1<InferInput<TInputSchema>, InferOutput<TInputSchema> & WithAgentInputSchema<TInputSchema>> : TInputSchema;
 type AgentSetupXStateConfig<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, SetupStateSchema> = Record<string, SetupStateSchema>> = {
   schemas: {
     context: TContextSchema;
-    input: TInputSchema;
+    input: BrandedInputSchema<TInputSchema>;
     output: TOutputSchema;
     meta: TMetaSchema;
   } & AgentSetupEventsSchema<TEventSchemas> & AgentSetupEmittedSchema<TEmittedSchemas>;
@@ -606,7 +623,7 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
  * Throws at bind time if a source needs an executor kind that `executors` does
  * not provide.
  *
- * v1 does NOT descend into invoked child state machines: a string-keyed child
+ * `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).
  */
@@ -860,7 +877,10 @@ interface TrajectoryMatch {
   matchedCount: number;
   /** `expected.length`, so a scorer can compute its own ratio. */
   expectedCount: number;
-  /** Partial credit, 0..1. `1` for an empty expectation. */
+  /**
+   * Partial credit, 0..1. `1` for an empty expectation. Denominator is
+   * `max(expectedCount, actual.length)` in `exact` mode, `expectedCount` otherwise.
+   */
   score: number;
   /** Absent when `matched`. */
   firstMiss?: TrajectoryMiss;
@@ -910,7 +930,6 @@ type ScriptedDecisionValue = ChosenEvent | {
   event: ChosenEvent;
   reason?: string;
   usage?: AgentCallUsage;
-  [key: string]: unknown;
 };
 /**
  * One entry in the `decisions` queue: a scripted answer, or a function of the
@@ -970,6 +989,101 @@ interface ScriptedExecutorsScript {
  */
 declare function createScriptedExecutors(script?: ScriptedExecutorsScript): Required<AgentRequestExecutors>;
 //#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
+ * event types and targets, invoke `src`s, `initial`, and any other serializable
+ * config fields. Function values (context/output builders, prompts, inline
+ * guards/actions) are excluded entirely, so two machines that differ only in
+ * their prompts or executors hash identically; adding/removing/retargeting a
+ * state or transition changes the hash.
+ *
+ * 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.
+ */
+declare function getMachineStructuralHash(machine: AnyStateMachine): string;
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+declare function userMessage(content: string | Array<TextPart | ImagePart | FilePart>): UserMessage;
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+declare function assistantMessage(content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>): AssistantMessage;
+/** Builds a {@link SystemMessage}. */
+declare function systemMessage(content: string): SystemMessage;
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+declare function toolMessage(content: Array<ToolResultPart>): ToolMessage;
+type MetaOfSnapshot<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+}> = NonNullable<ReturnType<TSnapshot["getMeta"]>[keyof ReturnType<TSnapshot["getMeta"]>]>;
+/**
+ * Returns the merged `meta` of a snapshot's active state(s) — the typed
+ * replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+ *
+ * `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.
+ *
+ * The return type is recovered from the snapshot's own `getMeta()` type, so a
+ * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+ * output type. Pass an explicit `TMeta` to override when the snapshot is
+ * untyped (e.g. `AnyMachineSnapshot`).
+ *
+ * @example HITL: read the current state's interaction protocol off an idle
+ * snapshot to render for a human.
+ * ```ts
+ * const { interaction } = getStateMeta(result.snapshot);
+ * ```
+ */
+declare function getStateMeta<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+} = AnyMachineSnapshot, TMeta = MetaOfSnapshot<TSnapshot>>(snapshot: TSnapshot): Partial<TMeta>;
+/**
+ * Reads the run-owned message log off a snapshot settled by a `runAgent` call
+ * that used `getRequests` (or `options.messages`) — the typed replacement for
+ * the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
+ * stamps the log as a plain enumerable `messages` property (like `agentMeta`),
+ * so it survives a JSON persist/resume round-trip; this accessor works on the
+ * live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
+ * when no log was stamped (e.g. a default invoke-driven run).
+ *
+ * The write path is `runAgent(..., { messages })`: an explicit seed that
+ * overrides the resume snapshot's stamped log (fold in a user reply on
+ * resume, or start a run with prior history).
+ */
+declare function getAgentMessages(snapshot: unknown): AgentMessage[];
+/**
+ * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+ * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+ * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+ * can't read directly — see the `ai-sdk` tool pass-through.
+ */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/**
+ * Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+ * `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+ * `z.toJSONSchema`), awaiting it when the producer is async. Returns
+ * `undefined` when the schema doesn't expose the extension. Use this to build
+ * a provider request's `response_format`/tool `parameters` from a schema.
+ */
+declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string, unknown> | undefined>;
+/**
+ * Synchronous variant of {@link getJsonSchema}, for call sites that can't
+ * await (building tool/event descriptors inline). An async JSON Schema
+ * producer is treated as absent (returns `undefined`) — in practice Zod's
+ * `z.toJSONSchema` resolves synchronously.
+ */
+declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
+//#endregion
 //#region src/seam.d.ts
 /**
  * Which model call is under test: the Nth call addressed either by request
@@ -997,8 +1111,11 @@ interface SeamTurn<TMachine extends AnyStateMachine> {
   snapshot: SnapshotFrom<TMachine>;
   /** Its state value, for a `switch` on flat machines. */
   state: StateValue;
-  /** The merged `meta` of the active state(s) — e.g. a declared `interaction`. */
-  meta: Record<string, unknown>;
+  /**
+   * The merged `meta` of the active state(s), e.g. a declared `interaction`.
+   * Typed from the machine's own meta schema (`setupAgent({ meta })`).
+   */
+  meta: Partial<MetaOfSnapshot<SnapshotFrom<TMachine>>>;
   /** 0-based index of this pause within the run. */
   turn: number;
   /** The `idle` result that produced the pause. */
@@ -1103,99 +1220,4 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  */
 declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
 //#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
- * event types and targets, invoke `src`s, `initial`, and any other serializable
- * config fields. Function values (context/output builders, prompts, inline
- * guards/actions) are excluded entirely, so two machines that differ only in
- * their prompts or executors hash identically; adding/removing/retargeting a
- * state or transition changes the hash.
- *
- * 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.
- */
-declare function getMachineStructuralHash(machine: AnyStateMachine): string;
-/** Builds a {@link UserMessage} from a string or multimodal content parts. */
-declare function userMessage(content: string | Array<TextPart | ImagePart | FilePart>): UserMessage;
-/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
-declare function assistantMessage(content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>): AssistantMessage;
-/** Builds a {@link SystemMessage}. */
-declare function systemMessage(content: string): SystemMessage;
-/** Builds a {@link ToolMessage} from one or more tool-result parts. */
-declare function toolMessage(content: Array<ToolResultPart>): ToolMessage;
-type MetaOfSnapshot<TSnapshot extends {
-  getMeta(): Record<string, unknown>;
-}> = NonNullable<ReturnType<TSnapshot["getMeta"]>[keyof ReturnType<TSnapshot["getMeta"]>]>;
-/**
- * Returns the merged `meta` of a snapshot's active state(s) — the typed
- * replacement for the `Object.values(snapshot.getMeta())[0]` dance.
- *
- * `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.
- *
- * The return type is recovered from the snapshot's own `getMeta()` type, so a
- * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
- * output type. Pass an explicit `TMeta` to override when the snapshot is
- * untyped (e.g. `AnyMachineSnapshot`).
- *
- * @example HITL: read the current state's interaction protocol off an idle
- * snapshot to render for a human.
- * ```ts
- * const { interaction } = getStateMeta(result.snapshot);
- * ```
- */
-declare function getStateMeta<TSnapshot extends {
-  getMeta(): Record<string, unknown>;
-} = AnyMachineSnapshot, TMeta = MetaOfSnapshot<TSnapshot>>(snapshot: TSnapshot): Partial<TMeta>;
-/**
- * Reads the run-owned message log off a snapshot settled by a `runAgent` call
- * that used `getRequests` (or `options.messages`) — the typed replacement for
- * the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
- * stamps the log as a plain enumerable `messages` property (like `agentMeta`),
- * so it survives a JSON persist/resume round-trip; this accessor works on the
- * live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
- * when no log was stamped (e.g. a default invoke-driven run).
- *
- * The write path is `runAgent(..., { messages })`: an explicit seed that
- * overrides the resume snapshot's stamped log (fold in a user reply on
- * resume, or start a run with prior history).
- */
-declare function getAgentMessages(snapshot: unknown): AgentMessage[];
-/**
- * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
- * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
- * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
- * can't read directly — see the `ai-sdk` tool pass-through.
- */
-declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
-/**
- * Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
- * `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
- * `z.toJSONSchema`), awaiting it when the producer is async. Returns
- * `undefined` when the schema doesn't expose the extension. Use this to build
- * a provider request's `response_format`/tool `parameters` from a schema.
- */
-declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string, unknown> | undefined>;
-/**
- * Synchronous variant of {@link getJsonSchema}, for call sites that can't
- * await (building tool/event descriptors inline). An async JSON Schema
- * producer is treated as absent (returns `undefined`) — in practice Zod's
- * `z.toJSONSchema` resolves synchronously.
- */
-declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
-//#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 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 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 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, 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 };
+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 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, 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 };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, a as AgentToolChoice, b as ToolCallPart, c as AgentTools, d as ChosenEvent, f as EventUnion, g as NormalizedEventSchemas, h as InferOutput, 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 SystemMessage, x as ToolMessage, y as TextPart } from "./types-9Bqg5rZB.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-DYpK3QF4.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { A as AgentDecisionExhaustedError, B as AgentRequestOptions, C as buildEnvelopeSchema, D as parseOutput, E as parseModelRef, F as ResolveDecisionOptions, H as getAcceptedEvents, I as renderDecisionAttempts, L as resolveDecision, M as AgentDecisionRequest, N as DecisionAttempt, O as parseStructuredEnvelope, P as DecisionLogicConfig, R as AgentEventDescriptor, S as bindRequestExecutor, T as getAgentOutputMode, U as parseAgentEvent, V 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 AgentDecisionInput, k as AgentDecisionExecutor, 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 AgentEventToolNameResolver } from "./text-logic-C5kbjaDz.mjs";
-import { a as AgentLogVerification, c as assertAgentLogEntry, d as createInMemoryEventLogStore, i as AgentLogEntry, l as assertEventLogStoreConformance, n as AgentEventLogConflictError, o as JsonValue, r as AgentEventLogStore, s as NonSerializableAgentEventError, t as AGENT_EVENT_SCHEMA_VERSION, u as assertJsonSerializable } from "./event-log-store-BkUNtyOF.mjs";
-import { A as AgentEffectDiff, B as createReplayEntry, C as AgentStateRequest, D as AGENT_INIT_EVENT_TYPE, E as executeAgentRequest, F as AgentUsageEvent, G as replay, H as getAgentEffects, I as CreateReplayEntryOptions, K as verifyReplay, L as GetAgentEffectsOptions, M as AgentLogPatchOperation, N as AgentReplayDivergenceError, O as AGENT_USAGE_EVENT_TYPE, P as AgentReplayMachineMismatchError, R as ReplayOptions, S as traceTransitions, T as AgentStepRequest, U as getCallUsage, V as diffEventLogs, W as initEntry, _ as createAgentActor, a as AgentMessageInfo, b as runAgent, c as AgentTraceEvent, d as InspectedActorRef, f as JsonSerializableTraceEvent, g as RunAgentResult, h as RunAgentOptions, i as AgentIllegalResumeEventError, j as AgentEventLogDiff, k as AgentEffect, l as AgentUserInputExecutor, m as RunAgentErrorCause, n as AgentActorSession, o as AgentRunMeta, p as PendingUserInput, r as AgentIdleError, s as AgentSnapshotVersionMismatchError, t as AGENT_TRACE_SCHEMA_VERSION, u as GenerateResult, v as generateResult, w as AgentRequest, x as serializeTraceEvent, y as inspectTransitions, z as ReplayResult } from "./run-agent-2MnlQTkB.mjs";
+import { A as AgentDecisionExecutor, B as AgentEventToolNameResolver, C as buildEnvelopeSchema, D as parseModelRef, E as getCallUsage, F as DecisionLogicConfig, 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 getAcceptedEvents, V as AgentRequestOptions, W as parseAgentEvent, _ 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-DQW8_DWW.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-COHoCgQd.mjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, InputFrom, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/messages.d.ts
@@ -309,10 +309,27 @@ type AgentSetupEventsSchema<TEventSchemas extends AgentEventSchemaInputMap> = {
 type AgentSetupEmittedSchema<TEmittedSchemas extends Record<string, StandardSchemaV1>> = [keyof TEmittedSchemas] extends [never] ? {} : {
   emitted: TEmittedSchemas;
 };
+/**
+ * The input schema as handed to xstate's `setup(...)`, with the machine's input
+ * type branded by the schema it came from.
+ *
+ * XState resolves `schemas.input` to a single type used both by
+ * `createActor`'s `input` option and by the `context: ({ input })` factory —
+ * and it never validates, so a schema default reads as a required field at the
+ * call site while being absent at runtime. `runAgent` validates the input
+ * (filling defaults) and reads this brand back through `AgentInputFrom` to
+ * accept the schema's looser *input* side, while the factory keeps seeing the
+ * validated *output* side.
+ *
+ * Only object-shaped input is branded: with no declared input schema the
+ * resolved type is xstate's `NonReducibleUnknown` (a union including `null`),
+ * and intersecting a brand into that collapses members to `never`.
+ */
+type BrandedInputSchema<TInputSchema extends StandardSchemaV1> = InferOutput<TInputSchema> extends Record<string, unknown> ? StandardSchemaV1<InferInput<TInputSchema>, InferOutput<TInputSchema> & WithAgentInputSchema<TInputSchema>> : TInputSchema;
 type AgentSetupXStateConfig<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, SetupStateSchema> = Record<string, SetupStateSchema>> = {
   schemas: {
     context: TContextSchema;
-    input: TInputSchema;
+    input: BrandedInputSchema<TInputSchema>;
     output: TOutputSchema;
     meta: TMetaSchema;
   } & AgentSetupEventsSchema<TEventSchemas> & AgentSetupEmittedSchema<TEmittedSchemas>;
@@ -606,7 +623,7 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
  * Throws at bind time if a source needs an executor kind that `executors` does
  * not provide.
  *
- * v1 does NOT descend into invoked child state machines: a string-keyed child
+ * `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).
  */
@@ -860,7 +877,10 @@ interface TrajectoryMatch {
   matchedCount: number;
   /** `expected.length`, so a scorer can compute its own ratio. */
   expectedCount: number;
-  /** Partial credit, 0..1. `1` for an empty expectation. */
+  /**
+   * Partial credit, 0..1. `1` for an empty expectation. Denominator is
+   * `max(expectedCount, actual.length)` in `exact` mode, `expectedCount` otherwise.
+   */
   score: number;
   /** Absent when `matched`. */
   firstMiss?: TrajectoryMiss;
@@ -910,7 +930,6 @@ type ScriptedDecisionValue = ChosenEvent | {
   event: ChosenEvent;
   reason?: string;
   usage?: AgentCallUsage;
-  [key: string]: unknown;
 };
 /**
  * One entry in the `decisions` queue: a scripted answer, or a function of the
@@ -970,6 +989,101 @@ interface ScriptedExecutorsScript {
  */
 declare function createScriptedExecutors(script?: ScriptedExecutorsScript): Required<AgentRequestExecutors>;
 //#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
+ * event types and targets, invoke `src`s, `initial`, and any other serializable
+ * config fields. Function values (context/output builders, prompts, inline
+ * guards/actions) are excluded entirely, so two machines that differ only in
+ * their prompts or executors hash identically; adding/removing/retargeting a
+ * state or transition changes the hash.
+ *
+ * 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.
+ */
+declare function getMachineStructuralHash(machine: AnyStateMachine): string;
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+declare function userMessage(content: string | Array<TextPart | ImagePart | FilePart>): UserMessage;
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+declare function assistantMessage(content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>): AssistantMessage;
+/** Builds a {@link SystemMessage}. */
+declare function systemMessage(content: string): SystemMessage;
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+declare function toolMessage(content: Array<ToolResultPart>): ToolMessage;
+type MetaOfSnapshot<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+}> = NonNullable<ReturnType<TSnapshot["getMeta"]>[keyof ReturnType<TSnapshot["getMeta"]>]>;
+/**
+ * Returns the merged `meta` of a snapshot's active state(s) — the typed
+ * replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+ *
+ * `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.
+ *
+ * The return type is recovered from the snapshot's own `getMeta()` type, so a
+ * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+ * output type. Pass an explicit `TMeta` to override when the snapshot is
+ * untyped (e.g. `AnyMachineSnapshot`).
+ *
+ * @example HITL: read the current state's interaction protocol off an idle
+ * snapshot to render for a human.
+ * ```ts
+ * const { interaction } = getStateMeta(result.snapshot);
+ * ```
+ */
+declare function getStateMeta<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+} = AnyMachineSnapshot, TMeta = MetaOfSnapshot<TSnapshot>>(snapshot: TSnapshot): Partial<TMeta>;
+/**
+ * Reads the run-owned message log off a snapshot settled by a `runAgent` call
+ * that used `getRequests` (or `options.messages`) — the typed replacement for
+ * the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
+ * stamps the log as a plain enumerable `messages` property (like `agentMeta`),
+ * so it survives a JSON persist/resume round-trip; this accessor works on the
+ * live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
+ * when no log was stamped (e.g. a default invoke-driven run).
+ *
+ * The write path is `runAgent(..., { messages })`: an explicit seed that
+ * overrides the resume snapshot's stamped log (fold in a user reply on
+ * resume, or start a run with prior history).
+ */
+declare function getAgentMessages(snapshot: unknown): AgentMessage[];
+/**
+ * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+ * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+ * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+ * can't read directly — see the `ai-sdk` tool pass-through.
+ */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/**
+ * Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+ * `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+ * `z.toJSONSchema`), awaiting it when the producer is async. Returns
+ * `undefined` when the schema doesn't expose the extension. Use this to build
+ * a provider request's `response_format`/tool `parameters` from a schema.
+ */
+declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string, unknown> | undefined>;
+/**
+ * Synchronous variant of {@link getJsonSchema}, for call sites that can't
+ * await (building tool/event descriptors inline). An async JSON Schema
+ * producer is treated as absent (returns `undefined`) — in practice Zod's
+ * `z.toJSONSchema` resolves synchronously.
+ */
+declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
+//#endregion
 //#region src/seam.d.ts
 /**
  * Which model call is under test: the Nth call addressed either by request
@@ -997,8 +1111,11 @@ interface SeamTurn<TMachine extends AnyStateMachine> {
   snapshot: SnapshotFrom<TMachine>;
   /** Its state value, for a `switch` on flat machines. */
   state: StateValue;
-  /** The merged `meta` of the active state(s) — e.g. a declared `interaction`. */
-  meta: Record<string, unknown>;
+  /**
+   * The merged `meta` of the active state(s), e.g. a declared `interaction`.
+   * Typed from the machine's own meta schema (`setupAgent({ meta })`).
+   */
+  meta: Partial<MetaOfSnapshot<SnapshotFrom<TMachine>>>;
   /** 0-based index of this pause within the run. */
   turn: number;
   /** The `idle` result that produced the pause. */
@@ -1103,99 +1220,4 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  */
 declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
 //#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
- * event types and targets, invoke `src`s, `initial`, and any other serializable
- * config fields. Function values (context/output builders, prompts, inline
- * guards/actions) are excluded entirely, so two machines that differ only in
- * their prompts or executors hash identically; adding/removing/retargeting a
- * state or transition changes the hash.
- *
- * 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.
- */
-declare function getMachineStructuralHash(machine: AnyStateMachine): string;
-/** Builds a {@link UserMessage} from a string or multimodal content parts. */
-declare function userMessage(content: string | Array<TextPart | ImagePart | FilePart>): UserMessage;
-/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
-declare function assistantMessage(content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>): AssistantMessage;
-/** Builds a {@link SystemMessage}. */
-declare function systemMessage(content: string): SystemMessage;
-/** Builds a {@link ToolMessage} from one or more tool-result parts. */
-declare function toolMessage(content: Array<ToolResultPart>): ToolMessage;
-type MetaOfSnapshot<TSnapshot extends {
-  getMeta(): Record<string, unknown>;
-}> = NonNullable<ReturnType<TSnapshot["getMeta"]>[keyof ReturnType<TSnapshot["getMeta"]>]>;
-/**
- * Returns the merged `meta` of a snapshot's active state(s) — the typed
- * replacement for the `Object.values(snapshot.getMeta())[0]` dance.
- *
- * `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.
- *
- * The return type is recovered from the snapshot's own `getMeta()` type, so a
- * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
- * output type. Pass an explicit `TMeta` to override when the snapshot is
- * untyped (e.g. `AnyMachineSnapshot`).
- *
- * @example HITL: read the current state's interaction protocol off an idle
- * snapshot to render for a human.
- * ```ts
- * const { interaction } = getStateMeta(result.snapshot);
- * ```
- */
-declare function getStateMeta<TSnapshot extends {
-  getMeta(): Record<string, unknown>;
-} = AnyMachineSnapshot, TMeta = MetaOfSnapshot<TSnapshot>>(snapshot: TSnapshot): Partial<TMeta>;
-/**
- * Reads the run-owned message log off a snapshot settled by a `runAgent` call
- * that used `getRequests` (or `options.messages`) — the typed replacement for
- * the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
- * stamps the log as a plain enumerable `messages` property (like `agentMeta`),
- * so it survives a JSON persist/resume round-trip; this accessor works on the
- * live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
- * when no log was stamped (e.g. a default invoke-driven run).
- *
- * The write path is `runAgent(..., { messages })`: an explicit seed that
- * overrides the resume snapshot's stamped log (fold in a user reply on
- * resume, or start a run with prior history).
- */
-declare function getAgentMessages(snapshot: unknown): AgentMessage[];
-/**
- * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
- * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
- * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
- * can't read directly — see the `ai-sdk` tool pass-through.
- */
-declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
-/**
- * Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
- * `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
- * `z.toJSONSchema`), awaiting it when the producer is async. Returns
- * `undefined` when the schema doesn't expose the extension. Use this to build
- * a provider request's `response_format`/tool `parameters` from a schema.
- */
-declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string, unknown> | undefined>;
-/**
- * Synchronous variant of {@link getJsonSchema}, for call sites that can't
- * await (building tool/event descriptors inline). An async JSON Schema
- * producer is treated as absent (returns `undefined`) — in practice Zod's
- * `z.toJSONSchema` resolves synchronously.
- */
-declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
-//#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 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 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 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, 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 };
+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 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, 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 };