@statelyai/agent 2.0.0-alpha.15 → 2.0.0-alpha.17

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-DFD28AWe.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-DZW7XWy9.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 AgentEffect, B as ReplayResult, C as traceTransitions, D as executeAgentRequest, E as AgentStepRequest, F as AgentReplayMachineMismatchError, G as initEntry, H as diffEventLogs, I as AgentUsageEvent, K as replay, 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 getCallUsage, _ 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, q as verifyReplay, 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-B_n4Qxye.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
@@ -96,6 +96,17 @@ interface AgentWorkflowConfig {
   actors?: Record<string, AgentWorkflowActorConfig>;
   initial: string;
   states: Record<string, AgentWorkflowStateConfig>;
+  /**
+   * State tags that mark an INTENTIONAL wait for an external event (a human
+   * approval, an inbound webhook, …) — the declarative form of `setupAgent({
+   * isSuspended })`, since a config cannot carry a function. Lowered to a
+   * `snapshot.hasTag(...)`-any-of predicate so `runAgent` settles those
+   * snapshots idle deterministically instead of using its timing heuristic.
+   * Every listed tag must appear in some state's `tags` — an unused tag is a
+   * build-time error. A `fromConfig(config, { isSuspended })` option takes
+   * precedence; a `runAgent({ isSuspended })` host override beats both.
+   */
+  suspendedTags?: string[];
   meta?: Record<string, unknown>;
 }
 /** A `requests` entry in {@link AgentWorkflowConfig} — the JSON equivalent of a `setupAgent({ requests })` `TextLogicConfig`. Fields beyond `input`/`output`/`tools`/`mode`/`description` are `unknown` because they accept template-expression strings (see {@link AgentWorkflowConfig}). */
@@ -228,6 +239,16 @@ interface FromConfigOptions {
    * implementation here is a build-time error.
    */
   actions?: Record<string, (params: any) => unknown>;
+  /**
+   * Detects a snapshot that is an INTENTIONAL wait for an external event —
+   * the same machine-carried predicate `setupAgent({ isSuspended })` declares
+   * for TS-authored machines, registered here because a function cannot live
+   * in the workflow config itself. Takes precedence over the config's
+   * declarative {@link AgentWorkflowConfig.suspendedTags}; a
+   * `runAgent({ isSuspended })` host override beats both. Travels with the
+   * machine through `machine.provide(...)`.
+   */
+  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
 }
 //#endregion
 //#region src/setup-agent.d.ts
@@ -623,7 +644,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).
  */
@@ -877,7 +898,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;
@@ -927,7 +951,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
@@ -987,6 +1010,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
@@ -1014,8 +1132,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. */
@@ -1120,99 +1241,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 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 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-CTBhMnFu.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-C7anC7qX.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 AgentEffect, B as ReplayResult, C as traceTransitions, D as executeAgentRequest, E as AgentStepRequest, F as AgentReplayMachineMismatchError, G as initEntry, H as diffEventLogs, I as AgentUsageEvent, K as replay, 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 getCallUsage, _ 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, q as verifyReplay, 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-BWzo4FLv.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
@@ -96,6 +96,17 @@ interface AgentWorkflowConfig {
   actors?: Record<string, AgentWorkflowActorConfig>;
   initial: string;
   states: Record<string, AgentWorkflowStateConfig>;
+  /**
+   * State tags that mark an INTENTIONAL wait for an external event (a human
+   * approval, an inbound webhook, …) — the declarative form of `setupAgent({
+   * isSuspended })`, since a config cannot carry a function. Lowered to a
+   * `snapshot.hasTag(...)`-any-of predicate so `runAgent` settles those
+   * snapshots idle deterministically instead of using its timing heuristic.
+   * Every listed tag must appear in some state's `tags` — an unused tag is a
+   * build-time error. A `fromConfig(config, { isSuspended })` option takes
+   * precedence; a `runAgent({ isSuspended })` host override beats both.
+   */
+  suspendedTags?: string[];
   meta?: Record<string, unknown>;
 }
 /** A `requests` entry in {@link AgentWorkflowConfig} — the JSON equivalent of a `setupAgent({ requests })` `TextLogicConfig`. Fields beyond `input`/`output`/`tools`/`mode`/`description` are `unknown` because they accept template-expression strings (see {@link AgentWorkflowConfig}). */
@@ -228,6 +239,16 @@ interface FromConfigOptions {
    * implementation here is a build-time error.
    */
   actions?: Record<string, (params: any) => unknown>;
+  /**
+   * Detects a snapshot that is an INTENTIONAL wait for an external event —
+   * the same machine-carried predicate `setupAgent({ isSuspended })` declares
+   * for TS-authored machines, registered here because a function cannot live
+   * in the workflow config itself. Takes precedence over the config's
+   * declarative {@link AgentWorkflowConfig.suspendedTags}; a
+   * `runAgent({ isSuspended })` host override beats both. Travels with the
+   * machine through `machine.provide(...)`.
+   */
+  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
 }
 //#endregion
 //#region src/setup-agent.d.ts
@@ -623,7 +644,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).
  */
@@ -877,7 +898,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;
@@ -927,7 +951,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
@@ -987,6 +1010,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
@@ -1014,8 +1132,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. */
@@ -1120,99 +1241,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 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 };