@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.13

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, O as ToolResultOutput, S as ProviderOptions, T as TextPart, _ as EventUnion, a as AgentTool, b as InferOutput, c as AgentToolExecute, d as AllowedEventPattern, f as AllowedEvents, g as EventPayload, h as DataContent, i as AgentSnapshotStore, k as ToolResultPart, l as AgentToolSchema, m as ChosenEvent, n as AgentEventSchemaInputMap, o as AgentToolChoice, p as AssistantMessage, r as AgentMessage, s as AgentToolDescriptor, t as AgentEventSchemaInput, u as AgentTools, v as FilePart, w as SystemMessage, x as NormalizedEventSchemas, y as ImagePart } from "./types-qm00QF91.mjs";
-import { A as AgentDecisionInput, C as createTextLogic, F as DecisionExhaustedError, G as AgentRequestOptions, I as DecisionLogic, K as AgentRequestSource, M as AgentPlanInput, N as AgentPlanOutput, P as DecisionAttempt, U as AgentEventDescriptor, W as AgentEventToolNameResolver, Y as parseAgentEvent, _ as TextLogicExecuteArgs, a as AgentRequestExecutorInfo, b as TextLogicOutput, c as AgentRequestMode, d as AiSdkShapedStreamResult, f as AiSdkShapedTextResult, g as TextLogicConfig, h as TextLogic, i as AgentRequestExecutor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, n as AgentModelRef, o as AgentRequestExecutorResult, p as BuiltinAgentActors, q as getAcceptedEvents, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, y as TextLogicInput, z as PlanLogic } from "./text-logic-CaKqgX4Y.mjs";
-import { c as persistSnapshot, d as userMessage, l as systemMessage, n as getAgentMessages, o as getStateMeta, t as assistantMessage, u as toolMessage } from "./utils-Do5wIJrh.mjs";
-import { i as AgentStepRequest, n as AgentRequest } from "./steps-BALp1eZo.mjs";
-import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, Snapshot, SnapshotFrom } from "xstate";
+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-_FXoFBGO.mjs";
+import { t as AgentError } from "./errors-C9rxnWbX.mjs";
+import { A as AgentDecisionExhaustedError, B as renderDecisionAttempts, C as buildEnvelopeSchema, D as parseOutput, E as parseModelRef, F as DecisionAttempt, G as AgentRequestSource, H as AgentEventDescriptor, I as DecisionLogicConfig, K as getAcceptedEvents, L as PLAN_DONE_EVENT_TYPE, M as AgentDecisionRequest, N as AgentPlanInput, O as parseStructuredEnvelope, P as AgentPlanOutput, R as PlanLogic, S as bindRequestExecutor, T as getAgentOutputMode, U as AgentEventToolNameResolver, V as resolveDecision, W as AgentRequestOptions, _ 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, q as parseAgentEvent, r as AgentModelMap, s as AgentRequestExecutorInfo, t as AgentCallUsage, u as AgentRequestMode, v as TextLogic, w as createTextLogic, x as TextLogicExecutor, y as TextLogicConfig, z as ResolveDecisionOptions } from "./text-logic-TkKPw8Aq.mjs";
+import { A as AgentReplayDivergenceError, B as getCallUsage, C as AgentStateRequest, D as AgentEffectDiff, E as AgentEffect, F as ReplayOptions, G as AgentRequest, H as replay, I as ReplayResult, K as AgentStepRequest, L as createReplayEntry, M as AgentUsageEvent, N as CreateReplayEntryOptions, O as AgentEventLogDiff, P as GetAgentEffectsOptions, R as diffEventLogs, S as traceTransitions, T as AGENT_USAGE_EVENT_TYPE, U as verifyReplay, V as initEntry, W as AgentPlanRequest, _ 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 AgentReplayMachineMismatchError, k as AgentLogPatchOperation, l as AgentUserInputExecutor, m as RunAgentErrorCause, n as AgentActorSession, o as AgentRunMeta, p as PendingUserInput, q as executeAgentRequest, r as AgentIdleError, s as AgentSnapshotVersionMismatchError, t as AGENT_TRACE_SCHEMA_VERSION, u as GenerateResult, v as generateResult, w as AGENT_INIT_EVENT_TYPE, x as serializeTraceEvent, y as inspectTransitions, z as getAgentEffects } from "./run-agent-C3mFDGTf.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-CriMgX1D.mjs";
+import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, InputFrom, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/messages.d.ts
 /**
@@ -119,7 +120,7 @@ interface AgentWorkflowRequestConfig {
   stopSequences?: unknown;
   metadata?: unknown;
 }
-/** An `actors` entry in {@link AgentWorkflowConfig} — declares a placeholder actor source (by key) with no host execution wired from JSON; provide it via `machine.provide({ actorSources })` after `setupAgent.fromConfig(...)`. */
+/** An `actors` entry in {@link AgentWorkflowConfig} — declares a placeholder actor source (by key) with no host execution wired from JSON; provide it via `machine.provide({ actors })` after `setupAgent.fromConfig(...)`. */
 interface AgentWorkflowActorConfig {
   input?: JsonSchemaObject;
   output?: JsonSchemaObject;
@@ -158,7 +159,15 @@ interface AgentWorkflowInvokeConfig {
   onError?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
   meta?: Record<string, unknown>;
 }
-/** A transition target in {@link AgentWorkflowConfig} (`on`/`always`/`onDone`/`after`/invoke `onDone`/`onError`) — the JSON equivalent of an XState transition config. `guard`, when a string, is a template expression evaluated as truthy/falsy. */
+/**
+ * A transition target in {@link AgentWorkflowConfig}
+ * (`on`/`always`/`onDone`/`after`/invoke `onDone`/`onError`) — the JSON
+ * equivalent of an XState transition config. A string `guard` containing
+ * `{{ ... }}` is a template expression evaluated as truthy/falsy; any other
+ * string is a named guard reference resolved against the `guards` passed to
+ * `setupAgent.fromConfig(config, { guards })` (unresolvable references throw
+ * at build time).
+ */
 interface AgentWorkflowTransitionConfig {
   target?: string | string[];
   guard?: unknown;
@@ -168,7 +177,7 @@ interface AgentWorkflowTransitionConfig {
   reenter?: boolean;
   meta?: Record<string, unknown>;
 }
-/** An `entry`/`exit`/transition `actions` entry in {@link AgentWorkflowConfig} — either a named action `type` (with template-expression `params`) or a bare context `assign`. */
+/** An `entry`/`exit`/transition `actions` entry in {@link AgentWorkflowConfig} — a bare context `assign`, an `emit`, or a named action `type` (with template-expression `params`) resolved against the `actions` passed to `setupAgent.fromConfig(config, { actions })`. */
 interface AgentWorkflowActionConfig {
   type?: string;
   params?: unknown;
@@ -176,6 +185,23 @@ interface AgentWorkflowActionConfig {
   emit?: unknown;
   [key: string]: unknown;
 }
+/**
+ * What `setupAgent.fromConfig(...)` returns: the built machine plus the
+ * schema pack compiled from the config's `schemas` (with `compileSchema`).
+ * The pack is what hosts need for the runtime work the machine's types can't
+ * do for a JSON-authored agent — e.g. validating an inbound raw event:
+ *
+ * @example
+ * ```ts
+ * const { machine, schemas } = setupAgent.fromConfig(config, { compileSchema });
+ * const event = parseAgentEvent(snapshot, raw, { events: schemas.events });
+ * ```
+ */
+interface FromConfigResult {
+  machine: AnyStateMachine;
+  /** Compiled `context`/`events`/`input`/`output`/`meta`/`emitted` schemas — the same pack `runAgent` executes this machine with. */
+  schemas: AgentSchemaPack<StandardSchemaV1<Record<string, unknown>>, Record<string, StandardSchemaV1>, StandardSchemaV1, StandardSchemaV1, StandardSchemaV1<MetaObject>>;
+}
 /** Options for `setupAgent.fromConfig(...)`. */
 interface FromConfigOptions {
   /**
@@ -184,6 +210,24 @@ interface FromConfigOptions {
    * pipeline, ...). Core intentionally ships no JSON Schema engine.
    */
   compileSchema: SchemaCompiler;
+  /**
+   * Host guard implementations for named guard references in the config
+   * (`guard: "isFromHuman"`). Each is called with `{ context, event }` and
+   * returns a boolean. A named guard reference with no implementation here is
+   * a build-time error — a guard is never silently dropped.
+   */
+  guards?: Record<string, (args: {
+    context: any;
+    event: any;
+  }) => boolean>;
+  /**
+   * Host action implementations for named action types in the config
+   * (`{ type: "notify", params: ... }`). Each is called with the
+   * template-resolved `params` as its only argument — pull context/event data
+   * into `params` via `{{ ... }}` templates. A named action type with no
+   * implementation here is a build-time error.
+   */
+  actions?: Record<string, (params: any) => unknown>;
 }
 //#endregion
 //#region src/setup-agent.d.ts
@@ -219,6 +263,21 @@ type AgentSchemaConfig<TContextSchema extends StandardSchemaV1<Record<string, un
   meta?: TMetaSchema;
   emitted?: TEmittedSchemas;
 };
+/**
+ * The payload of the reserved `'@agent.usage'` event — {@link AgentUsageEvent}
+ * without its `type`. It is what a machine's `'@agent.usage'` handler receives
+ * alongside `type`, since event schemas describe payloads only.
+ */
+type AgentUsageEventPayload = Omit<AgentUsageEvent, "type">;
+/**
+ * An authored event schema map with the reserved `'@agent.usage'` entry added —
+ * every agent machine's event union includes it, so `on: { '@agent.usage': … }`
+ * is typed (and autocompletes) without the machine declaring anything.
+ * Idempotent: re-applying it to an already-registered map is a no-op.
+ */
+type WithAgentUsageEvent<T extends AgentEventSchemaInputMap> = Omit<T, typeof AGENT_USAGE_EVENT_TYPE> & {
+  [AGENT_USAGE_EVENT_TYPE]: StandardSchemaV1<AgentUsageEventPayload>;
+};
 /**
  * Builds a machine's {@link AgentSchemaPack} from a partial schema
  * declaration — only `context` is required; `events`/`input`/`output`/`meta`
@@ -227,21 +286,25 @@ type AgentSchemaConfig<TContextSchema extends StandardSchemaV1<Record<string, un
  * directly into `setupAgent({ context, events, ... })` — both forms are
  * accepted).
  */
-declare function createAgentSchemas<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}>(schemas: AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>): AgentSchemaPack<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
-type AgentRequestConfig<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata = Record<string, unknown>, TModel extends string = string> = TextLogicConfig<TInputSchema, TOutputSchema, TMetadata, TModel> & {
-  mode?: AgentRequestMode;
-};
+declare function createAgentSchemas<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}>(schemas: AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>): AgentSchemaPack<TContextSchema, WithAgentUsageEvent<TEventSchemas>, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
 type AgentRequestSchemaMap = Record<string, {
-  input: StandardSchemaV1;
-  output: StandardSchemaV1;
+  input?: StandardSchemaV1;
+  output?: StandardSchemaV1;
 }>;
-type AgentRequestInput<TRequestSchemas extends AgentRequestSchemaMap, TModel extends string = string> = { [K in keyof TRequestSchemas]: AgentRequestConfig<TRequestSchemas[K]["input"], TRequestSchemas[K]["output"], Record<string, unknown>, TModel> & {
+type ResolvedRequestSchema<TSchema, TFallback> = [NonNullable<TSchema>] extends [never] ? TFallback : [NonNullable<TSchema>] extends [StandardSchemaV1] ? NonNullable<TSchema> : TFallback;
+type RequestInputSchema<TSchemas extends {
+  input?: StandardSchemaV1;
+}> = ResolvedRequestSchema<TSchemas["input"], StandardSchemaV1<undefined>>;
+type RequestOutputSchema<TSchemas extends {
+  output?: StandardSchemaV1;
+}> = ResolvedRequestSchema<TSchemas["output"], StandardSchemaV1<string>>;
+type AgentRequestInput<TRequestSchemas extends AgentRequestSchemaMap, TModel extends string = string> = { [K in keyof TRequestSchemas]: Omit<TextLogicConfig<RequestInputSchema<TRequestSchemas[K]>, RequestOutputSchema<TRequestSchemas[K]>, Record<string, unknown>, TModel>, "schemas"> & {
   schemas: TRequestSchemas[K];
 } };
-type RequestActors<TRequestSchemas extends AgentRequestSchemaMap> = { [K in keyof TRequestSchemas]: TextLogic<TRequestSchemas[K]["input"], TRequestSchemas[K]["output"]> };
+type RequestActors<TRequestSchemas extends AgentRequestSchemaMap> = { [K in keyof TRequestSchemas]: TextLogic<RequestInputSchema<TRequestSchemas[K]>, RequestOutputSchema<TRequestSchemas[K]>> };
 type AgentAllActors<TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap> = TActors & RequestActors<TRequestSchemas>;
-type AgentSetupEventsSchema<TEventSchemas extends AgentEventSchemaInputMap> = [keyof TEventSchemas] extends [never] ? {} : {
-  events: NormalizedEventSchemas<TEventSchemas>;
+type AgentSetupEventsSchema<TEventSchemas extends AgentEventSchemaInputMap> = {
+  events: NormalizedEventSchemas<WithAgentUsageEvent<TEventSchemas>>;
 };
 type AgentSetupEmittedSchema<TEmittedSchemas extends Record<string, StandardSchemaV1>> = [keyof TEmittedSchemas] extends [never] ? {} : {
   emitted: TEmittedSchemas;
@@ -254,7 +317,7 @@ type AgentSetupXStateConfig<TContextSchema extends StandardSchemaV1<Record<strin
     meta: TMetaSchema;
   } & AgentSetupEventsSchema<TEventSchemas> & AgentSetupEmittedSchema<TEmittedSchemas>;
   states?: TStateSchemas;
-  actorSources: SetupActors<AgentSetupActors<AgentAllActors<TActors, TRequestSchemas>, keyof TEventSchemas & string, AgentModelRef<TModels>>>;
+  actors: SetupActors<AgentSetupActors<AgentAllActors<TActors, TRequestSchemas>, Exclude<keyof TEventSchemas & string, typeof AGENT_USAGE_EVENT_TYPE>, AgentModelRef<TModels>>>;
   actions?: NonNullable<AnySetupConfig["actions"]>;
   guards?: NonNullable<AnySetupConfig["guards"]>;
   delays?: NonNullable<AnySetupConfig["delays"]>;
@@ -294,7 +357,7 @@ type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string,
   schemas: AgentSchemaPack<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
 } | AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>) & {
   models?: TModels;
-  actorSources?: TActors;
+  actors?: TActors;
   /**
    * Per-state schemas, mirroring xstate's `setup({ states })`: narrow
    * `context` inside a state (invoke `input`, transition fns, final `output`)
@@ -336,8 +399,8 @@ type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unk
    * its schemas/actors without re-passing them, and a single final state's
    * `output` is copied to the machine root when the root declares none.
    */
-  createMachine: SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>["createMachine"]; /** The retained schema pack ({@link AgentSchemaPack}) for host-side validation and tooling. */
-  schemas: AgentSchemaPack<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>; /** The `models` registry passed to `setupAgent(...)`, if any (used to type-narrow `AgentModelRef`). */
+  createMachine: SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>["createMachine"]; /** The retained schema pack ({@link AgentSchemaPack}) for host-side validation and tooling. Its `events` include the reserved `'@agent.usage'` entry setupAgent registers by default. */
+  schemas: AgentSchemaPack<TContextSchema, WithAgentUsageEvent<TEventSchemas>, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>; /** The `models` registry passed to `setupAgent(...)`, if any (used to type-narrow `AgentModelRef`). */
   readonly models: TModels; /** The {@link TextLogic} actors built from `setupAgent({ requests })`, keyed the same way. */
   readonly requests: RequestActors<TRequestSchemas>; /** {@link appendMessages}, typed against this agent's context/event schemas. */
   appendMessages(resolve: AgentMessage | AgentMessage[] | ((args: {
@@ -347,12 +410,8 @@ type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unk
     event: any;
   }) => AgentMessage | AgentMessage[])): ReturnType<typeof appendMessages<ContextOf<TContextSchema> & {
     messages: AgentMessage[];
-  }, EventsOf<TEventSchemas>>>;
+  }, EventsOf<WithAgentUsageEvent<TEventSchemas>>>>;
 };
-/** Typed machine config used by convenience authoring layers built on `setupAgent`. */
-type AgentMachineConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TInputSchema extends StandardSchemaV1, TEventSchemas extends AgentEventSchemaInputMap = {}, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TModels extends AgentModelMap = {}> = Parameters<SetupAgentResult<TContextSchema, TEventSchemas, {}, {}, TInputSchema, TOutputSchema, StandardSchemaV1<MetaObject>, TModels>["createMachine"]>[0];
-/** Machine produced from {@link AgentMachineConfig}. */
-type AgentMachine<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TInputSchema extends StandardSchemaV1, TEventSchemas extends AgentEventSchemaInputMap = {}, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TModels extends AgentModelMap = {}> = ReturnType<SetupAgentResult<TContextSchema, TEventSchemas, {}, {}, TInputSchema, TOutputSchema, StandardSchemaV1<MetaObject>, TModels>["createMachine"]>;
 /**
  * Schema-first `setup(...)` for agent machines — the standard entry point
  * for authoring a machine (the blueprint) that this library then runs (via
@@ -361,7 +420,7 @@ type AgentMachine<TContextSchema extends StandardSchemaV1<Record<string, unknown
  * state/transition meta are all standard schemas — no `{} as Type` casts —
  * and are retained on `result.schemas` for runtime validation. Also
  * registers the `agent.generateText`/`agent.streamText`/`agent.userInput`/
- * `agent.decide`/`agent.plan` builtin actors and lowers `requests`/`actorSources` into the
+ * `agent.decide`/`agent.plan` builtin actors and lowers `requests`/`actors` into the
  * machine's actor sources. The result is the xstate `setup(...)` object with
  * a wrapped `result.createMachine(...)` plus `result.schemas`/`models`/
  * `requests`/`appendMessages` attached. Also has a
@@ -378,7 +437,7 @@ type AgentMachine<TContextSchema extends StandardSchemaV1<Record<string, unknown
  *
  * const agent = setupAgent({
  *   schemas,
- *   actorSources: { tellJoke },
+ *   actors: { tellJoke },
  * });
  *
  * const jokeMachine = agent.createMachine({
@@ -408,567 +467,97 @@ declare namespace setupAgent {
    * the library bundles no JSON Schema engine itself; bring Ajv,
    * @cfworker/json-schema, or another compiler that returns Standard Schema.
    *
+   * Returns the built `machine` plus the compiled `schemas` pack (context,
+   * events, input, output, meta, emitted) — a JSON-authored agent has no
+   * TypeScript types, so hosts need the runtime schemas for things like
+   * validating an inbound raw event with `parseAgentEvent`.
+   *
    * @example
    * ```ts
-   * const machine = setupAgent.fromConfig(workflowConfig, {
+   * const { machine, schemas } = setupAgent.fromConfig(workflowConfig, {
    *   compileSchema,
    * });
    * const result = await runAgent(machine, { input: { ticket }, executors: { generateText, decide } });
+   * const event = parseAgentEvent(result.snapshot, raw, { events: schemas.events });
    * ```
    */
-  function fromConfig(config: AgentWorkflowConfig, options: FromConfigOptions): AnyStateMachine;
+  function fromConfig(config: AgentWorkflowConfig, options: FromConfigOptions): FromConfigResult;
 }
 //#endregion
-//#region src/internal/state-request-pass.d.ts
+//#region src/agent-run.d.ts
 /**
- * One model request read off the machine's CURRENT snapshot by a
- * `RunAgentOptions.getRequests` hook. `model` is an executor model NAME — the
- * same string every {@link AgentTextRequest.model} carries, resolved by the
- * run's executors (e.g. a `defineModels` key when using
- * `createAiSdkExecutors`) — never a model instance.
- */
-interface AgentStateRequest {
-  /** Instruction for this request's model call, appended to the run's message log as a user message. */
-  prompt: string;
-  /** System prompt for this request's model call(s). */
-  system?: string;
-  /** Executor model name (resolved by the run's executors). */
-  model: string;
-  /**
-   * `'text'` (default): a `generateText` call with the message log +
-   * `prompt`; the reply is appended to the log, then the machine is advanced
-   * per {@link AgentStateRequest.onDone}. `'decision'`: no text call — a
-   * single `decide` call (log + `prompt`) chooses the event. Use for pure
-   * routing states.
-   */
-  kind?: "text" | "decision";
-  /**
-   * What to send when this request's text call resolves — the EXPLICIT
-   * advancement contract, always an event OBJECT (the same shape
-   * `actor.send` takes; no string shorthand). A literal event sends exactly
-   * that; a function receives the text output (plus the live snapshot and
-   * message log) and returns the event to send — payload included — or
-   * `undefined` to send nothing. Omitted: a `decide` call chooses among the
-   * candidate events (requires a `decide` executor) — there is no implicit
-   * auto-send. A resolved event whose type the state does not accept throws
-   * (programmer error); one a guard rejects is simply not sent. Ignored for
-   * `kind: 'decision'` (the decide call IS the advancement).
-   */
-  onDone?: ChosenEvent | ((args: {
-    output: unknown;
-    snapshot: AnyMachineSnapshot;
-    messages: readonly AgentMessage[];
-  }) => ChosenEvent | undefined);
-  /** Restricts this request's candidate outcome events for the `decide` fallback (default: every currently-accepted event). */
-  allowedEvents?: readonly string[];
-  /** Trace/request id; defaults to `interpret_<n>`. */
-  id?: string;
-}
-//#endregion
-//#region src/run-agent.d.ts
-/**
- * Thrown by {@link runAgent} when resuming with a `snapshot` + `event` whose
- * `type` the restored state cannot accept (a type-level check via
- * {@link getAcceptedEvents}). A programmer/integration error, in the same
- * class as runAgent's bind-time throws — it throws rather than settling an
- * `error` result. A type-legal event a guard rejects is NOT this error (the
- * machine simply takes no transition). Opt out with
- * {@link RunAgentOptions.onIllegalResumeEvent} `'ignore'`.
- */
-declare class IllegalResumeEventError extends Error {
-  readonly eventType: string;
-  readonly acceptedTypes: string[];
-  constructor(eventType: string, acceptedTypes: string[]);
-}
-/**
- * Thrown by {@link runAgent} when resuming from a `snapshot` whose stamped
- * `agentMeta.version` differs from the current machine's version, under the
- * default `onVersionMismatch: 'throw'` and with no `migrateSnapshot` hook. The
- * structural fingerprint of the machine changed since the snapshot was
- * persisted (a state/transition/invoke was added, removed, or retargeted), so
- * the snapshot may no longer resume cleanly. `from` is the snapshot's version,
- * `to` the current machine's.
- */
-declare class SnapshotVersionMismatchError extends Error {
-  readonly from: string;
-  readonly to: string;
-  readonly machineId: string;
-  constructor(from: string, to: string, machineId: string);
-}
-/**
- * Thrown by {@link runAgentToCompletion} when the run settles `idle` instead of
- * `done`: the machine paused for external input. Carries the idle `snapshot`
- * and `acceptedTypes` (the event types that could resume it, via
- * {@link getAcceptedEvents}). Use {@link runAgent} directly when idle is an
- * expected outcome you handle.
- */
-declare class AgentIdleError extends Error {
-  readonly snapshot: AnyMachineSnapshot;
-  readonly acceptedTypes: string[];
-  constructor(snapshot: AnyMachineSnapshot, acceptedTypes: string[]);
-}
-/** Handler for `agent.userInput` invokes passed as {@link RunAgentOptions.userInput}. Resolves to what the human typed. */
-interface AgentUserInputExecutor {
-  (input: AgentUserInput): PromiseLike<string>;
-}
-/**
- * The run's machine identity, stamped onto every settled snapshot's `agentMeta`.
- * `machineId` is the machine's `id`; `version` is
- * {@link RunAgentOptions.machineVersion} or the
- * {@link getMachineStructuralHash} of the machine. Trace events and the
- * `onMessage` info arg carry the same identity flattened, as
- * `machineId`/`machineVersion`.
- */
-interface AgentRunMeta {
-  machineId: string;
-  version: string;
-}
-/**
- * Second argument passed to {@link RunAgentOptions.onMessage}: the run's
- * identity, carried alongside each live message. Not stamped onto the message
- * itself (messages stay clean model input).
- */
-interface AgentMessageInfo {
-  runId: string;
-  machineId: string;
-  /** {@link RunAgentOptions.machineVersion} or the machine's structural hash. */
-  machineVersion: string;
-}
-/**
- * The version of the {@link AgentTraceEvent} envelope every trace event carries
- * as `schemaVersion`. Bumped only on a breaking change to the envelope or any
- * payload shape, so a consumer can gate on it. Emitted identically by
- * {@link runAgent}, {@link provideExecutors}' `onTrace`, and
- * {@link traceTransitions}.
- */
-declare const AGENT_TRACE_SCHEMA_VERSION = 1;
-type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
-  /** The {@link AGENT_TRACE_SCHEMA_VERSION} the event was produced with. */schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
-  runId: string;
-  seq: number;
-  timestamp: string;
-  machineId: string; /** {@link RunAgentOptions.machineVersion} or the machine's structural hash. */
-  machineVersion: string;
-} & ({
-  type: "run.start";
-  input?: InputFrom<TMachine>;
-  snapshot?: Snapshot<unknown>;
-  event?: EventFromLogic<TMachine>;
-} | {
-  type: "request.start";
-  request: AgentStepRequest;
-} | {
-  type: "request.end";
-  request: AgentStepRequest;
-  output: unknown;
-  raw: unknown;
-  /** The model's reasoning, lifted off the raw executor result when the
-   * request opted into the structured-output envelope's `reasoning` field.
-   * Present only when the executor surfaced a string `reasoning`. */
-  reasoning?: string;
-} | {
-  type: "request.error";
-  request: AgentStepRequest;
-  error: unknown;
-} | {
-  type: "stream.chunk";
-  request: AgentRequest;
-  chunk: string;
-} | {
-  type: "machine.transition";
-  snapshot: SnapshotFrom<TMachine>;
-  event: EventFromLogic<TMachine>;
-} | {
-  type: "emit";
-  event: EmittedFrom<TMachine>;
-} | ({
-  type: "run.end";
-  status: "done";
-  output: OutputFrom<TMachine>;
-  snapshot: SnapshotFrom<TMachine>;
-} | {
-  type: "run.end";
-  status: "idle";
-  snapshot: SnapshotFrom<TMachine>;
-  pendingUserInputs?: PendingUserInput[];
-  persistedSnapshot?: Snapshot<unknown>;
-} | {
-  type: "run.end";
-  status: "error";
-  cause: RunAgentErrorCause;
-  error: unknown;
-  snapshot: SnapshotFrom<TMachine>;
-}));
-/**
- * Options for {@link runAgent}.
+ * A live handle over a single {@link runAgent} call: its trace events as an
+ * async stream, plus the same result promise `runAgent` returns.
  *
- * Host executors are passed as a single {@link AgentRequestExecutors}-shaped
- * set under `executors` (the same shape the step path takes). Each executor
- * kind is required only if the machine actually reaches a request of that kind
- * — checked at bind time, before any actor runs. The whole `executors` field is
- * optional: a machine whose agent sources all carry their own executor
- * (`.withExecutor(...)`) needs none.
+ * Build it with {@link createAgentRun}. Use `events` for a pull-based feed
+ * (SSE, a JSONL logger, a progress UI) and `result` for the final outcome —
+ * either, both, or neither; nothing about consuming one is required to consume
+ * the other.
  */
-interface RunAgentOptions<TMachine extends AnyStateMachine> {
-  /**
-   * The host executor set backing the machine's agent actors — build it with
-   * `createAiSdkExecutors({ models })` from '@statelyai/agent/ai-sdk', or supply
-   * `{ generateText?, streamText?, decide? }` by hand. Every slot is optional
-   * here (unlike the step path's {@link AgentRequestExecutors}): each kind is
-   * bind-time-checked only when the machine actually reaches a request of that
-   * kind, so e.g. a stream-only machine may pass `{ streamText }` alone.
-   */
-  executors?: Partial<AgentRequestExecutors>;
-  /** Machine input, passed straight to `createActor(machine, { input })`. Omit when resuming via `snapshot`. */
-  input?: InputFrom<TMachine>;
-  /** A previously-settled run's `result.snapshot`, to resume from instead of starting fresh. Pair with `event` to deliver the event that unblocks the resumed idle state. */
-  snapshot?: Snapshot<unknown>;
-  /** An event to send immediately after starting/resuming the actor (e.g. the human's answer to an idle-state prompt). */
-  event?: EventFromLogic<TMachine>;
-  /**
-   * How to handle a resume `event` the restored state cannot accept (a
-   * type-level check via {@link getAcceptedEvents}, only applied when resuming
-   * from a `snapshot`). `'throw'` (default) throws {@link IllegalResumeEventError}
-   * before delivering the event; `'ignore'` restores the older silent behavior
-   * (the event is sent and the machine drops it). A type-legal event a guard
-   * rejects is never an illegal resume event.
-   */
-  onIllegalResumeEvent?: "throw" | "ignore";
-  /**
-   * The version stamped onto every settled snapshot's `agentMeta` and compared
-   * against an incoming snapshot's stamp on resume. Defaults to
-   * {@link getMachineStructuralHash} of the machine (a structural fingerprint).
-   * Set an explicit value (e.g. a semver or build id) to control migration
-   * boundaries yourself.
-   */
-  machineVersion?: string;
-  /**
-   * How to handle a resume `snapshot` whose stamped `agentMeta.version` differs
-   * from the current machine's version. `'throw'` (default) throws
-   * {@link SnapshotVersionMismatchError} with `from`/`to`; `'warn'`
-   * `console.warn`s once and proceeds; `'ignore'` proceeds silently. Ignored
-   * when {@link migrateSnapshot} is provided (that runs instead), and never
-   * triggers for an unstamped snapshot (no `agentMeta`).
-   */
-  onVersionMismatch?: "throw" | "warn" | "ignore";
-  /**
-   * Called instead of {@link onVersionMismatch} when a resume snapshot's
-   * version mismatches the current machine's: receives the incoming snapshot
-   * and `{ from, to }`, and its return value is used as the snapshot to resume
-   * from. A throw propagates.
-   */
-  migrateSnapshot?: (snapshot: Snapshot<unknown>, info: {
-    from: string;
-    to: string;
-  }) => Snapshot<unknown>;
-  /** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actorSources })` ahead of the run. */
-  actorSources?: Record<string, AnyActorLogic>;
-  /**
-   * Optional human-input handler for `agent.userInput` invokes (CLI prompt,
-   * web form, Slack, …). With a handler, input is gathered inline without
-   * settling. Without one, an `agent.userInput` invoke becomes a *pending
-   * placeholder*: it waits indefinitely, does not block idle detection, and
-   * the run settles `{ status: 'idle', pendingUserInputs, persistedSnapshot }`
-   * once no other work is in flight — resume by passing `persistedSnapshot`
-   * back as `snapshot` together with a `userInput` handler that answers it.
-   */
-  userInput?: AgentUserInputExecutor;
-  /**
-   * Host override for detecting a snapshot that is an INTENTIONAL wait for an
-   * external event — the deterministic replacement for the timing heuristic
-   * runAgent uses to settle idle. Resolution order: this option (host override)
-   * → the machine-carried predicate declared via `setupAgent({ isSuspended })`
-   * → the timing heuristic (when neither is present). When the resolved
-   * predicate returns true and nothing is in flight (no live requests/plans/
-   * invokes; the `agent.userInput` placeholder exemption still applies), runAgent
-   * settles idle immediately, without the `setTimeout` heuristic. It does NOT
-   * force-settle while agent work is in flight, and whole-machine idle semantics
-   * are unchanged; a machine with no predicate falls back to the heuristic
-   * exactly as before. Declare your own signal, e.g.
-   * `(s) => s.hasTag('awaiting-review')`.
-   *
-   * Provisional name — may change before 2.0.
-   */
-  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
-  /**
-   * The override to runAgent's DEFAULT contract. By default agent work is
-   * whatever the machine *invokes* (`agent.generateText`, TextLogic,
-   * `agent.decide`, …). With `getRequests`, whenever the machine would
-   * otherwise settle idle, this hook reads the snapshot and returns the model
-   * request(s) to run instead — prompts from state `description`s, `meta`,
-   * tags, a lookup table keyed by state value, wherever you keep them. Return
-   * nothing to settle idle (human-wait states).
-   *
-   * There is no blessed source for the prompts — this is a recipe seam.
-   * Prompts-in-descriptions, copy-paste and adapt:
-   *
-   * ```ts
-   * getRequests: (snapshot) =>
-   *   snapshot._nodes
-   *     .filter((node) => node.description && !node.tags.includes('waiting'))
-   *     .map((node) => ({
-   *       model: 'writer',
-   *       prompt: node.description!,
-   *       kind: node.tags.includes('decision') ? 'decision' : 'text',
-   *       // single-outcome states advance deterministically; else `decide`
-   *       onDone: node.ownEvents.length === 1 ? { type: node.ownEvents[0] } : undefined,
-   *       allowedEvents: node.ownEvents,
-   *     })),
-   * ```
-   *
-   * Each request runs per {@link AgentStateRequest.kind}, appends to the
-   * run's message log (see {@link RunAgentOptions.messages}), and advances
-   * the machine per {@link AgentStateRequest.onDone} — explicitly named/
-   * computed event, or a `decide` call when omitted — always gated by
-   * `snapshot.can`. Multiple requests run concurrently (parallel regions —
-   * scope each with `allowedEvents`, e.g. the node's `ownEvents`). A pass
-   * that sends no event settles idle. Every model call counts against
-   * `maxModelCalls`.
-   */
-  getRequests?: (snapshot: SnapshotFrom<TMachine>, agentContext: {
-    messages: readonly AgentMessage[];
-  }) => AgentStateRequest | readonly AgentStateRequest[] | undefined;
-  /**
-   * Adds to the run's aggregated message log (the working memory
-   * `getRequests` requests read and append to). The log starts as the resume
-   * `snapshot`'s stamped `messages` (else `[]`); an ARRAY here is APPENDED to
-   * that history — the safe default for folding in a user reply on resume,
-   * never silently erasing prior conversation. Pass a FUNCTION
-   * `(prior) => AgentMessage[]` to take full control (replace, filter,
-   * compact). The final log is stamped onto every settled result's
-   * `snapshot.messages` (like `agentMeta`), so persist/resume round-trips it
-   * with no extra wiring — read it with `getAgentMessages(snapshot)`.
-   */
-  messages?: AgentMessage[] | ((prior: AgentMessage[]) => AgentMessage[]);
-  /** Fires for each streamed chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest} that produced it (parallel states can interleave multiple streams). Purely observational. */
-  onChunk?: (chunk: string, info: {
-    request: AgentRequest;
-  }) => void;
-  /** Fires once per resolved text/decision request with its normalized output and the raw executor result (tool calls, usage, …) — the seam for tracing/observability and event-sourced replay logging. */
-  onResult?: (request: AgentStepRequest, result: {
-    output: unknown;
-    raw: unknown;
-  }) => void;
-  /** Fires a single ordered stream of run/request/chunk/transition/emit/end events. Intended for eval traces, JSONL logs, and adapter-owned telemetry/exporters. */
-  onTrace?: (event: AgentTraceEvent<TMachine>) => void;
+interface AgentRun<TMachine extends AnyStateMachine = AnyStateMachine> {
   /**
-   * Fires on every machine transition (snapshot + causing event). Pure
-   * observation — progress UIs, logging, tracing. Cannot send events.
+   * Single-consumer async stream of the run's trace events, in `runAgent`'s
+   * emission order (`run.start` → request/chunk/transition/emit events →
+   * `run.end`). Completes right after `run.end` is delivered. Events are
+   * buffered unboundedly, so a slow or absent consumer never blocks the run
+   * (see {@link createAgentRun}). Single-consumer: a second `for await` over the
+   * same iterator picks up only the events not yet pulled — it is one shared
+   * cursor, not a fresh replay.
    */
-  onTransition?: (snapshot: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine>) => void;
+  events: AsyncIterableIterator<AgentTraceEvent<TMachine>>;
   /**
-   * Fires for each message appended to the run's aggregated log (see
-   * {@link RunAgentOptions.messages}) the moment a `getRequests` request
-   * appends it — the live view of the log a caller otherwise only reads off
-   * the settled snapshot via `getAgentMessages`. Purely observational, like
-   * {@link onTransition}. Never fires for the seeded history, and never fires
-   * on a default invoke-driven run (nothing appends there).
+   * Settles exactly like {@link runAgent}'s return value: resolves with the
+   * `done | idle | error` {@link RunAgentResult}, and rejects only where
+   * `runAgent` itself rejects (bind-time programmer errors — a missing
+   * executor, an illegal resume event, a version mismatch). A run-level failure
+   * still resolves with `{ status: 'error' }`, never rejects.
    */
-  onMessage?: (message: AgentMessage, info: AgentMessageInfo) => void;
-  /**
-   * Handlers for events the machine emits (`enq.emit(...)`), keyed by emitted
-   * event type — `'*'` catches all. Typed from the machine's `emitted`
-   * schemas (`setupAgent({ emitted: { ... } })`). Purely observational, like
-   * {@link onTransition}: the machine narrates progress on its own vocabulary
-   * (not xstate internals) and the host renders it — a progress UI, an SSE
-   * stream, a log line.
-   */
-  on?: { [TType in EmittedFrom<TMachine>["type"] | "*"]?: (emitted: EmittedFrom<TMachine> & (TType extends "*" ? unknown : {
-    type: TType;
-  })) => void };
-  /**
-   * Raw xstate inspection passthrough: fires for every inspection event in
-   * the whole actor system — root machine, invoked child machines, spawned
-   * actors — each carrying its `actorRef` (`event.actorRef.id`/`.src`). This
-   * is the system-wide seam {@link onTransition} (root transitions only)
-   * cannot give you: filter `event.type === '@xstate.transition'` and read
-   * `event.actorRef` to attribute a child machine's states to the child.
-   * Purely observational, like the other callbacks. Unlike them it also
-   * fires during the final settle (a child's last transition and stop events
-   * arrive while the run is tearing down).
-   *
-   * Accepts a function or an observer (`{ next }`), matching `createActor`'s
-   * `inspect` option, so `@statelyai/inspect`'s `inspector.inspect` plugs in
-   * directly.
-   */
-  inspect?: ((inspectionEvent: InspectionEvent) => void) | {
-    next?: (inspectionEvent: InspectionEvent) => void;
-  };
-  /** Caps the number of model/decision calls this run may make (each retry of a decision counts separately); exceeding it settles `{ status: 'error', cause: 'max-model-calls' }`. Default 100. */
-  maxModelCalls?: number;
-  /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
-  signal?: AbortSignal;
+  result: Promise<RunAgentResult<TMachine>>;
 }
 /**
- * The outcome of a {@link runAgent} call — always exactly one of three
- * variants, never a throw for a waiting or failed machine (programmer
- * errors like a missing executor still throw, at bind time before any actor
- * runs). `done`: a final state was reached (`output` is the machine's
- * `OutputFrom`). `idle`: the run settled with no in-flight work — resume by
- * calling `runAgent` again with `{ snapshot, event }`. `error`: a run-level
- * failure, discriminated by `cause` (`'aborted'`, `'max-model-calls'`,
- * `'decision-exhausted'`, `'machine'` for any other machine error state, or
- * `'stopped'` for an external stop — see {@link RunAgentErrorCause}). Every
- * variant carries the final `snapshot`, and the underlying
- * actor is stopped on every settle path — there is no live actor to resume;
- * resume is always by snapshot.
- */
-/** A pending unhandled `agent.userInput` invoke surfaced on an idle settle — `id` is the invoke's id, `input` its resolved invoke input (prompt, metadata). Answer it by resuming with a `userInput` handler. */
-interface PendingUserInput {
-  id: string;
-  input: AgentUserInput | undefined;
-}
-type RunAgentResult<TMachine extends AnyStateMachine> = {
-  status: "done";
-  output: OutputFrom<TMachine>;
-  snapshot: SnapshotFrom<TMachine>;
-} | {
-  status: "idle";
-  snapshot: SnapshotFrom<TMachine>; /** Present when the machine is waiting on unhandled `agent.userInput` invokes: one entry per pending invoke. */
-  pendingUserInputs?: PendingUserInput[];
-  /**
-   * Present alongside `pendingUserInputs`: the JSON-serializable persisted
-   * snapshot (in-flight children included). Persist THIS one and resume
-   * with `runAgent(machine, { snapshot: persistedSnapshot, userInput })` —
-   * the live `snapshot` above cannot round-trip active children.
-   */
-  persistedSnapshot?: Snapshot<unknown>;
-} | {
-  status: "error";
-  cause: RunAgentErrorCause;
-  error: unknown;
-  snapshot: SnapshotFrom<TMachine>;
-};
-/**
- * Discriminates a {@link RunAgentResult} `error`:
- * - `'aborted'` — the run's `signal` fired.
- * - `'max-model-calls'` — the `maxModelCalls` budget was exceeded.
- * - `'decision-exhausted'` — the machine reached an error state whose error is
- *   (or wraps) a {@link DecisionExhaustedError} that no `onError` handled.
- * - `'machine'` — any other machine error state.
- * - `'stopped'` — the actor was stopped externally (`status === 'stopped'`).
- */
-type RunAgentErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped";
-/**
- * The set of string-keyed actor `src`s the machine's own config invokes
- * (top-level, recursing into child STATES but not into invoked child
- * machines). {@link provideExecutors} uses it to require an executor only for a
- * source the machine actually invokes — the always-registered `agent.*`
- * builtins that go unused must not force their executors to be supplied.
- * @internal
- */
-/**
- * Runs an agent machine to completion or idle: a `createActor` host that
- * binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/
- * `DecisionLogic` actor sources, starts (or resumes) the actor, and drives
- * it until it settles — {@link RunAgentResult} `done | idle | error`. Unlike
- * the step helpers ({@link initialAgentStep} etc — a pure
- * transition-at-a-time path for durable hosts), `runAgent` owns a live actor
- * internally; there is no continuation callback, so **idle always settles**
- * and the caller resumes explicitly by passing the settled `{ snapshot,
- * event }` back in. The actor is stopped on every settle path (`done`,
- * `idle`, and `error` alike) — resume is always by snapshot, never by
- * holding a reference to a live actor.
+ * Wraps {@link runAgent} in a canonical run-stream handle: the run's trace
+ * events as a pull-based {@link AgentRun.events} async iterator, alongside the
+ * unchanged {@link AgentRun.result} promise.
  *
- * Binding happens **before** the actor starts: every invoke the machine
- * could reach is walked and checked against the effective actor sources
- * (`options.actorSources` merged onto the machine), so a missing
- * `streamText`/`decide` executor or any other unbound actor source throws
- * immediately — a bind-time error, not a mid-run failure. The one exception
- * is `agent.userInput`: unhandled, it binds as a pending placeholder that
- * settles the run idle (with `pendingUserInputs`) instead of erroring.
+ * Semantics:
  *
- * @example
- * ```ts
- * const executors = createAiSdkExecutors({ models });
- * let r = await runAgent(machine, { input, executors });
- * while (r.status === 'idle') {
- *   const event = await promptUser(getAcceptedEvents(r.snapshot));
- *   r = await runAgent(machine, { snapshot: r.snapshot, event, executors });
- * }
- * if (r.status !== 'done') throw new Error(`Run did not complete: ${r.status}`);
- * console.log(r.output);
- * ```
- *
- * The `executors`' `generateText`/`streamText` accept the raw Vercel AI SDK
- * functions directly (`executors: { generateText, streamText }` with them
- * imported from `ai`) — their `{ text }`/`{ textStream }` results are unwrapped
- * natively. `decide` cannot be a raw AI SDK function: the tool-per-event mapping
- * lives in an adapter — use `createAiSdkExecutors` from '@statelyai/agent/ai-sdk'.
+ * 1. **Starts immediately.** The underlying `runAgent` is invoked on this call,
+ *    not on the first `events` iteration — work is already in flight when
+ *    `createAgentRun` returns.
+ * 2. **Buffer, don't stall.** Events are queued in an unbounded in-memory
+ *    buffer as the run emits them; a slow or absent consumer never applies
+ *    backpressure to the run. Once `run.end` is delivered, the iterator
+ *    completes.
+ * 3. **Composes `onTrace`.** If `options.onTrace` is passed, it still fires for
+ *    every event — the wrapper adds queue delivery, it does not replace the
+ *    caller's sink.
+ * 4. **`result` mirrors `runAgent`.** Same resolution and rejection behavior
+ *    (see {@link AgentRun.result}). A no-op rejection handler is attached
+ *    internally so a caller who reads only `events` never trips an unhandled
+ *    rejection on a bind-time throw; the returned promise still rejects for a
+ *    caller who awaits it.
+ * 5. **Resume is identical.** Options pass straight through, so starting from a
+ *    persisted `snapshot` (+ resume `event`) streams that run's events from its
+ *    own `run.start`, exactly as `runAgent` would run it.
+ * 6. **Early termination does not cancel the run.** Breaking out of a
+ *    `for await` (or calling `events.return()`) stops delivery, but the run
+ *    keeps going and `result` still settles. Cancelling the run itself is
+ *    future work — pass `options.signal` to abort it.
+ * 7. **`events` is single-consumer.** See {@link AgentRun.events}.
  */
-declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, options: RunAgentOptions<TMachine>): Promise<RunAgentResult<TMachine>>;
-/**
- * Runs an agent machine to a **final state** and returns its output, for
- * run-to-done flows where an idle pause is unexpected. Wraps {@link runAgent}:
- *
- * - `done` → resolves with `result.output` (the machine's `OutputFrom`).
- * - `idle` → throws {@link AgentIdleError} carrying the idle snapshot and the
- *   event types that could resume it.
- * - `error` → throws `result.error` when it is an `Error`; otherwise wraps it
- *   in an `Error` whose `.cause` is the {@link RunAgentErrorCause} and whose
- *   `.error` is the raw thrown value.
- *
- * Use {@link runAgent} directly when idle is an expected outcome you handle
- * (human-in-the-loop, resumable flows); use `runAgentToCompletion` when the
- * machine is meant to run straight through to a final state.
- */
-declare function runAgentToCompletion<TMachine extends AnyStateMachine>(machine: TMachine, options: RunAgentOptions<TMachine>): Promise<OutputFrom<TMachine>>;
-/**
- * The actor handed to an {@link inspectTransitions} handler: an
- * {@link AnyActorRef} widened with the runtime `id`/`src` used to attribute a
- * transition to the root machine or a specific invoked child (xstate's static
- * `ActorRef` type omits them, but they are always present at runtime).
- */
-type InspectedActorRef = AnyActorRef & {
-  id: string;
-  src?: string | AnyActorLogic;
-};
-/**
- * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
- * {@link RunAgentOptions.inspect}: it filters the raw inspection stream to
- * `@xstate.transition` events and hands the handler the typed
- * {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
- * transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
- * the manual `event.type === '@xstate.transition'` filtering and the snapshot/
- * actorRef casts.
- */
-declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, actorRef: InspectedActorRef) => void): (inspectionEvent: InspectionEvent) => void;
-/**
- * An xstate `inspect` handler that emits `machine.transition` trace events onto
- * `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
- * registry as {@link provideExecutors}' `onTrace`. Pair the two on one actor to
- * get a single ordered trace stream (request + transition events) for the
- * uncontrolled path:
- *
- * ```ts
- * const bound = provideExecutors(machine, executors, { onTrace });
- * const actor = createActor(bound, { inspect: traceTransitions(onTrace) });
- * ```
- *
- * Only ROOT-actor transitions are traced (matching `runAgent`'s
- * `machine.transition`); child-actor transitions are ignored. Attribute the
- * event via its envelope `runId`.
- *
- * By design this path has NO `run.start`/`run.end` events: `createActor` has no
- * run boundary the way `runAgent` does, so the stream starts at the actor's
- * first transition. It also does NOT emit `emit` trace events: in this xstate
- * build emitted events are delivered through `actor.on(...)`, not the inspection
- * protocol, so they are not observable from an `inspect` handler — subscribe
- * with `actor.on('*', ...)` if you need them.
- */
-declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
+declare function createAgentRun<TMachine extends AnyStateMachine>(machine: TMachine, options: RunAgentOptions<TMachine>): AgentRun<TMachine>;
 //#endregion
 //#region src/provide-executors.d.ts
 /** Options for {@link provideExecutors}. */
 interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
   /**
    * Extra actor-source overrides merged onto the machine BEFORE binding — the
-   * same shape as `machine.provide({ actorSources })`. Use it to supply the
+   * same shape as `machine.provide({ actors })`. Use it to supply the
    * `agent.userInput` handler, a custom non-agent actor, or to shadow an agent
    * source with your own executor-bound logic. Merged first, so an override
    * that already carries its own executor is left untouched by the binding pass.
    */
-  actorSources?: Record<string, AnyActorLogic>;
+  actors?: Record<string, AnyActorLogic>;
   /** Chunk sink threaded to every bound `mode: 'stream'` text source. */
   onChunk?: (chunk: string) => void;
   /**
@@ -997,8 +586,8 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
  *
  * behaves like a normal XState actor whose agent invokes now reach real models.
  *
- * Binding pass over `machine.implementations.actorSources` (after merging
- * `options.actorSources`):
+ * Binding pass over `machine.sources.actors` (after merging
+ * `options.actors`):
  * - `mode: 'generate'` text source → `executors.generateText`
  * - `mode: 'stream'` text source → `executors.streamText`
  * - decision / `agent.decide` source → `executors.decide` (snapshot-driven
@@ -1012,7 +601,7 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
  *
  * A source that already carries its own executor (`.withExecutor(...)`) is left
  * as-is. `agent.userInput` is left UNBOUND — an uncontrolled host handles idle
- * itself, so supply a handler via `options.actorSources` if the machine uses it.
+ * itself, so supply a handler via `options.actors` if the machine uses it.
  * Non-agent actors are untouched.
  *
  * Throws at bind time if a source needs an executor kind that `executors` does
@@ -1072,8 +661,8 @@ interface AssertAgentMachineOptions extends LintAgentMachineOptions {
  * `diagnostics` holds the findings; the message lists them one per finding,
  * so a test runner's failure output reads like the CLI's lint report.
  */
-declare class AgentLintError extends Error {
-  diagnostics: AgentLintDiagnostic[];
+declare class AgentLintError extends AgentError {
+  readonly diagnostics: AgentLintDiagnostic[];
   constructor(machineId: string, diagnostics: AgentLintDiagnostic[]);
 }
 /**
@@ -1229,4 +818,388 @@ interface CanReachResult {
  */
 declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
 //#endregion
-export { AGENT_TRACE_SCHEMA_VERSION, type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventSchemaInput, type AgentEventSchemaInputMap, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentMachine, type AgentMachineConfig, type AgentMessage, type AgentMessageInfo, type AgentModelMap, type AgentModelRef, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentRunMeta, type AgentSchemaPack, type AgentSetupStateSchema, type AgentSnapshotStore, type AgentStateNarrowing, type AgentStateRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEventPattern, type AllowedEvents, type AssertAgentMachineOptions, type AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, type NormalizedEventSchemas, type PendingUserInput, type PlanLogic, type ProvideExecutorsOptions, type ProviderOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextLogicInput, type TextLogicOutput, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, appendMessages, assertAgentMachine, assistantMessage, canReach, createAgentSchemas, createTextLogic, explorePaths, getAcceptedEvents, getAgentMessages, getStateMeta, inspectTransitions, lintAgentMachine, messagesSchema, parseAgentEvent, persistSnapshot, provideExecutors, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage };
+//#region src/trajectory.d.ts
+/** An event-shaped trajectory item: anything with a string `type`. */
+interface TrajectoryEvent {
+  type: string;
+  [key: string]: unknown;
+}
+/**
+ * One item in a trajectory, on either side of the comparison:
+ *
+ * - a state value — `'drafting'`, a dot path `'review.editing'`, or the nested
+ *   object XState reports (`{ review: 'editing' }`),
+ * - an event — an {@link AgentLogEntry} from `result.events`, a bare event
+ *   object, or just the event type as a string,
+ * - a machine snapshot, whose `value` is used.
+ */
+type TrajectoryItem = StateValue | AgentLogEntry | TrajectoryEvent | {
+  value: StateValue;
+};
+/** Options for {@link matchesTrajectory}. */
+interface MatchTrajectoryOptions {
+  /**
+   * Require the trajectories to be equal: same length, item for item. Default
+   * `false` — expected items must appear in `actual` in order, gaps allowed.
+   */
+  exact?: boolean;
+}
+/** The first expected item that could not be found. */
+interface TrajectoryMiss {
+  /** Its position in `expected`. */
+  index: number;
+  /** The expected item itself. */
+  expected: TrajectoryItem;
+  /** Where the search for it started in `actual` (everything before was already consumed). */
+  searchedFrom: number;
+}
+/**
+ * The result of {@link matchesTrajectory}: a boolean for tests, plus enough
+ * detail for a scorer's partial credit and a failure message's diagnosis.
+ */
+interface TrajectoryMatch {
+  /** Every expected item was found, in order (and, in `exact` mode, nothing else). */
+  matched: boolean;
+  /** How many expected items were matched before the first miss. */
+  matchedCount: number;
+  /** `expected.length`, so a scorer can compute its own ratio. */
+  expectedCount: number;
+  /** Partial credit, 0..1. `1` for an empty expectation. */
+  score: number;
+  /** Absent when `matched`. */
+  firstMiss?: TrajectoryMiss;
+}
+/**
+ * Matches a run's trajectory against an expected one.
+ *
+ * Both trajectories may be state values (collected from `onTransition`) or
+ * events (`result.events`, whose {@link AgentLogEntry} envelopes are unwrapped);
+ * items are compared by shape, so `['prompting', 'drafting']` scores a state
+ * path and `['PROMPT_SUBMITTED', 'SEND']` scores an event log with the same
+ * call.
+ *
+ * Semantics are an ordered subsequence: every expected item must appear in
+ * `actual`, in order, with gaps allowed. Pass `{ exact: true }` to require
+ * equality instead.
+ *
+ * @example Trajectory assertions in a test
+ * ```ts
+ * const statePath: unknown[] = [];
+ * const result = await runAgent(machine, {
+ *   input,
+ *   executors,
+ *   onTransition: (snapshot) => statePath.push(snapshot.value),
+ * });
+ *
+ * const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
+ * expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
+ * expect(matchesTrajectory(result.events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
+ * ```
+ *
+ * @example Partial credit in an eval scorer
+ * ```ts
+ * const match = matchesTrajectory(output.statePath, expected.statePath);
+ * return { name: 'state_path', score: match.score, metadata: { ...match.firstMiss } };
+ * ```
+ */
+declare function matchesTrajectory(actual: readonly unknown[], expected: readonly TrajectoryItem[], options?: MatchTrajectoryOptions): TrajectoryMatch;
+//#endregion
+//#region src/scripted-executors.d.ts
+/**
+ * A scripted `decide` answer: either the {@link ChosenEvent} itself (an object
+ * with a string `type`), or the executor envelope `{ event, reason?, usage? }`
+ * when the entry also reports a `reason` or token `usage`.
+ */
+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
+ * {@link AgentDecisionRequest} returning one (for choices that depend on the
+ * prompt, the candidate `events`, or the prior failed `attempts`).
+ */
+type ScriptedDecisionEntry = ScriptedDecisionValue | ((request: AgentDecisionRequest) => ScriptedDecisionValue | PromiseLike<ScriptedDecisionValue>);
+/**
+ * One entry in the `text` queue: the request's output value (a string, or the
+ * object a structured request declares), or a function of the
+ * {@link AgentTextRequest} returning one.
+ *
+ * An entry is taken as the raw executor envelope (instead of the value itself)
+ * only when its OWN keys are an `output` plus, optionally, `usage`/`raw` —
+ * that is how an entry reports token `usage`. Anything else, including an
+ * object that merely happens to have an `output` key alongside its own data
+ * (`{ output: 'draft', confidence: 0.9 }`), is the output value. For a
+ * structured request whose declared output is exactly `{ output }` (or
+ * `{ output, usage }`), wrap it once more: `{ output: { output: '…' } }`.
+ */
+type ScriptedTextEntry = ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => unknown) | string | number | boolean | null | object;
+/** The script {@link createScriptedExecutors} plays back. */
+interface ScriptedExecutorsScript {
+  /** Answers for `decide` (and `agent.plan`) requests, consumed in order. */
+  decisions?: ScriptedDecisionEntry[];
+  /** Answers for text requests, consumed in order. `generateText` and `streamText` share this one queue. */
+  text?: ScriptedTextEntry[];
+}
+/**
+ * Keyless executors that replay a script instead of calling a model. Every
+ * slot is provided, so any machine binds; a request with no entry left throws a
+ * descriptive error naming what was pending.
+ *
+ * Queues are consumed FIFO and are copied on creation, so the caller's arrays
+ * are never mutated and each call builds a fresh, independent playthrough.
+ * Entries may be plain values or functions of the request, which is how one
+ * script serves a machine that loops or branches: route on `request.name` (the
+ * `setupAgent({ requests })` key) or on the decision's candidate `events`.
+ *
+ * @example
+ * ```ts
+ * const result = await runAgent(moderationMachine, {
+ *   input: { comment: 'honestly this update is terrible', trust: 20 },
+ *   executors: createScriptedExecutors({
+ *     decisions: [{ type: 'FLAG', reason: 'Borderline tone.' }],
+ *   }),
+ * });
+ * ```
+ *
+ * @example Dynamic entries
+ * ```ts
+ * createScriptedExecutors({
+ *   text: [(request) => `Draft about ${request.prompt}`],
+ *   decisions: [(request) => ({ type: request.events[0]!.type })],
+ * });
+ * ```
+ */
+declare function createScriptedExecutors(script?: ScriptedExecutorsScript): Required<AgentRequestExecutors>;
+//#endregion
+//#region src/seam.d.ts
+/**
+ * Which model call is under test: the Nth call addressed either by request
+ * `name` (the `setupAgent({ requests })` key or `createTextLogic({ name })`,
+ * the better developer handle) or by `model` key (the `defineModels` key) for
+ * requests that carry no name.
+ */
+type SeamRef = {
+  /** The request's registered `name`. */request: string;
+  model?: undefined; /** 0-based occurrence among the calls matching this key. Default `0`. */
+  occurrence?: number;
+} | {
+  /** The `defineModels` key the request names. */model: string;
+  request?: undefined; /** 0-based occurrence among the calls matching this key. Default `0`. */
+  occurrence?: number;
+};
+/**
+ * One idle pause, handed to {@link RunSeamOptions.respond} so the simulated
+ * user answers off the machine's own state rather than a fixed transcript — a
+ * live seam may branch differently, and a reactive policy scores that run
+ * instead of crashing on it.
+ */
+interface SeamTurn<TMachine extends AnyStateMachine> {
+  /** The idle snapshot to answer. */
+  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>;
+  /** 0-based index of this pause within the run. */
+  turn: number;
+  /** The `idle` result that produced the pause. */
+  result: RunAgentResult<TMachine>;
+}
+/** One side of the seam: a trajectory pair ready for `matchesTrajectory`. */
+interface SeamSlice {
+  /** State values entered on this side of the seam, in order. */
+  statePath: StateValue[];
+  /** Replayable log entries on this side of the seam, in order. */
+  events: AgentLogEntry[];
+}
+/** Options for {@link runSeam}. */
+interface RunSeamOptions<TMachine extends AnyStateMachine> {
+  /** Machine input, passed straight through to `runAgent`. */
+  input?: InputFrom<TMachine>;
+  /**
+   * The call plan: scripted answers per key, consumed in order. A key is a
+   * request `name` when one is scripted under it, else a `model` key, so a
+   * machine whose requests are named routes by name and an unnamed one routes
+   * by model.
+   *
+   * Entries follow {@link ScriptedTextEntry} conventions (a value, an
+   * `{ output, usage? }` envelope, or a function of the request). The LAST
+   * entry of a queue repeats, so a live seam that sends the run down a longer
+   * branch still finds an answer instead of running dry.
+   */
+  scripts?: Record<string, ScriptedTextEntry[]>;
+  /** The call under test. */
+  seam: SeamRef;
+  /**
+   * The executor for the seam — the real model, a candidate prompt, anything
+   * request-shaped. Omit to run the seam scripted too: the whole seam run is
+   * then keyless and deterministic.
+   */
+  candidate?: AgentRequestExecutors["generateText"];
+  /**
+   * The simulated user. Called at every idle pause; return the event to send,
+   * or `null`/`undefined` to stop the run there. Omitted, the run stops at the
+   * first idle pause.
+   */
+  respond?: (turn: SeamTurn<TMachine>) => EventFromLogic<TMachine> | null | undefined;
+  /** Maximum idle pauses to answer before stopping. Default `12`. */
+  maxTurns?: number;
+  /**
+   * Base executors merged UNDER the seam routing — supply `decide` (e.g. from
+   * `createScriptedExecutors({ decisions })`) for a machine that also decides.
+   * Text slots are always owned by the routing.
+   */
+  executors?: Partial<AgentRequestExecutors>;
+  /** Passed through to `runAgent`: the deterministic idle-state predicate. */
+  isSuspended?: RunAgentOptions<TMachine>["isSuspended"];
+  /** Passed through to `runAgent`: actor implementations merged onto the machine. */
+  actors?: RunAgentOptions<TMachine>["actors"];
+}
+/** What {@link runSeam} returns: the seam's own answer, plus the run it caused. */
+interface RunSeamResult<TMachine extends AnyStateMachine> {
+  /**
+   * The final `runAgent` result. Its `events` are the WHOLE run's log (every
+   * leg's entries), while `usage` accounts only for the last leg.
+   */
+  result: RunAgentResult<TMachine>;
+  /** What the seam call returned, or `undefined` when the run never reached it. */
+  seamOutput: unknown;
+  /** Model calls made before the seam, or `-1` when the run never reached it. */
+  callsBeforeSeam: number;
+  /** Everything up to the seam's own effect completion. */
+  before: SeamSlice;
+  /**
+   * Everything from the seam's own effect completion onward — the branch the
+   * seam caused, and the score. Empty when the run never reached the seam.
+   */
+  after: SeamSlice;
+}
+/**
+ * Runs a machine end to end with one model call under test, and slices the run
+ * at that call.
+ *
+ * The `before`/`after` slices are the point: `after.statePath` is the branch
+ * the seam chose and `after.events` is the same question against the durable
+ * log, both ready for `matchesTrajectory`. The state slice splits where the
+ * state path stood when the seam answered; the event slice splits at the
+ * seam's own effect completion (the first `xstate.done.*`/`xstate.error.*`
+ * entry appended after the call was made).
+ *
+ * @example Keyless: the seam is scripted too, so the whole thing runs offline.
+ * ```ts
+ * const run = await runSeam(emailDrafter, {
+ *   scripts: { promptEvaluator: [vague, complete], emailDrafter: [draft] },
+ *   seam: { request: 'evaluatePrompt' },
+ *   respond: ({ state }) => (state === 'prompting' ? { type: 'PROMPT_SUBMITTED', prompt } : null),
+ * });
+ *
+ * matchesTrajectory(run.after.statePath, ['needsMoreInfo', 'drafting']);
+ * ```
+ *
+ * @example A candidate prompt at the seam, scored against the same rows.
+ * ```ts
+ * const { generateText } = createAiSdkExecutors({ models });
+ * const run = await runSeam(emailDrafter, { ...row, candidate: generateText });
+ * ```
+ */
+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, type AgentPlanInput, type AgentPlanOutput, type AgentPlanRequest, 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, PLAN_DONE_EVENT_TYPE, type PendingUserInput, type PlanLogic, 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 };