@statelyai/agent 2.0.0-alpha.7 → 2.0.0-alpha.9

package/dist/run-agent-DzYJb3CK.d.mts

@@ -0,0 +1,1103 @@
+import { C as StandardSchemaV1, _ as EventUnion, b as InferOutput, m as ChosenEvent, n as AgentEventSchemaInputMap, o as AgentToolChoice, r as AgentMessage, u as AgentTools, x as NormalizedEventSchemas } from "./types-qm00QF91.mjs";
+import { G as AgentRequestSource, H as AgentEventDescriptor, M as AgentPlanInput, W as AgentRequestOptions, c as AgentRequestMode, g as TextLogicConfig, h as TextLogic, j as AgentDecisionRequest, l as AgentTextRequest, n as AgentModelRef, p as BuiltinAgentActors, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput } from "./text-logic-C7WJpCIc.mjs";
+import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, Snapshot, SnapshotFrom } from "xstate";
+
+//#region src/messages.d.ts
+/**
+ * Builds a transition-function result that appends one or more
+ * {@link AgentMessage}s to a context's `messages` array. `resolve` is either
+ * a message (or array of messages) or a function of `{ context, event }`
+ * returning them; the returned function is meant to be used directly as (or
+ * composed into) a transition's result, e.g. `on: { USER_REPLIED:
+ * agent.appendMessages(({ event }) => userMessage(event.text)) }`. Requires
+ * `messages: AgentMessage[]` on context — see {@link messagesSchema} for a
+ * ready-made schema for that field.
+ *
+ * @example
+ * ```ts
+ * on: {
+ *   USER_REPLIED: appendMessages(({ event }) => userMessage(event.text)),
+ * }
+ * ```
+ */
+declare function appendMessages<TContext extends {
+  messages: AgentMessage[];
+}, TEvent extends EventObject>(resolve: AgentMessage | AgentMessage[] | ((args: {
+  context: TContext;
+  event: TEvent;
+}) => AgentMessage | AgentMessage[])): (args: {
+  context: TContext;
+  event: TEvent;
+}) => {
+  context: {
+    messages: AgentMessage[];
+  };
+};
+/**
+ * A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
+ * checks that every message has a known `role` (`system`/`user`/`assistant`/
+ * `tool`) and that `content` is either a string (where the role allows it) or
+ * an array of parts with a known `type`. Use it directly as a context
+ * schema's `messages` field when authoring with `createAgentSchemas`.
+ */
+declare const messagesSchema: StandardSchemaV1<AgentMessage[]>;
+//#endregion
+//#region src/workflow-config.d.ts
+type JsonSchemaObject = {
+  type?: string | string[];
+  properties?: Record<string, JsonSchemaObject>;
+  required?: string[];
+  items?: JsonSchemaObject;
+  enum?: unknown[];
+  const?: unknown;
+  additionalProperties?: unknown;
+  [key: string]: unknown;
+};
+/**
+ * Compiles a JSON Schema object (from an `AgentWorkflowConfig`) into a
+ * runtime `StandardSchemaV1` validator. `setupAgent.fromConfig(...)` calls
+ * this once per schema in the config (context/events/input/output/meta,
+ * request input/output) — bring your own engine (Ajv, @cfworker/json-schema,
+ * a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no
+ * JSON Schema engine.
+ */
+type SchemaCompiler = (jsonSchema: Record<string, unknown>, name: string) => StandardSchemaV1;
+/**
+ * Serializable JSON/YAML machine definition — the config a database, visual
+ * editor, or LLM could produce and hand to `setupAgent.fromConfig(config, {
+ * compileSchema })` to get back the same kind of `AnyStateMachine`
+ * TypeScript `setupAgent(...)` authoring would build. JS/TS authoring should
+ * use `setupAgent(...)` directly instead of this JSON form. Any `unknown`-
+ * typed field here (`model`, `guard`, action `params`, …) accepts either a
+ * literal JSON value or a `"{{ path.to.value }}"` template-expression string
+ * resolved against `{ context, event, input, output }` at machine-build/
+ * transition time — see the sibling `evaluateWorkflowConfigValue` lowering.
+ */
+interface AgentWorkflowConfig {
+  key?: string;
+  id?: string;
+  version?: string;
+  description?: string;
+  schemas?: {
+    input?: JsonSchemaObject;
+    context?: JsonSchemaObject;
+    events?: Record<string, JsonSchemaObject>;
+    emitted?: Record<string, JsonSchemaObject>;
+    output?: JsonSchemaObject;
+    meta?: JsonSchemaObject;
+  };
+  context?: Record<string, unknown>;
+  requests?: Record<string, AgentWorkflowRequestConfig>;
+  actors?: Record<string, AgentWorkflowActorConfig>;
+  initial: string;
+  states: Record<string, AgentWorkflowStateConfig>;
+  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}). */
+interface AgentWorkflowRequestConfig {
+  mode?: AgentRequestMode;
+  description?: string;
+  model: unknown;
+  system?: unknown;
+  prompt?: unknown;
+  messages?: unknown;
+  input: JsonSchemaObject;
+  output: JsonSchemaObject;
+  tools?: AgentTools;
+  toolChoice?: AgentToolChoice | unknown;
+  /** Opt into the structured-output envelope's `reasoning` field (see `AgentTextRequest.reasoning`). */
+  reasoning?: boolean;
+  temperature?: unknown;
+  maxOutputTokens?: unknown;
+  topP?: unknown;
+  topK?: unknown;
+  seed?: unknown;
+  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(...)`. */
+interface AgentWorkflowActorConfig {
+  input?: JsonSchemaObject;
+  output?: JsonSchemaObject;
+  description?: string;
+}
+/** A `states` entry in {@link AgentWorkflowConfig} — the JSON equivalent of an XState state node config. */
+interface AgentWorkflowStateConfig {
+  description?: string;
+  type?: "parallel" | "history" | "final" | "choice";
+  initial?: string;
+  states?: Record<string, AgentWorkflowStateConfig>;
+  choice?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  invoke?: AgentWorkflowInvokeConfig | AgentWorkflowInvokeConfig[];
+  on?: Record<string, AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[]>;
+  always?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  onDone?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  after?: Record<string, AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[]>;
+  entry?: AgentWorkflowActionConfig | AgentWorkflowActionConfig[];
+  exit?: AgentWorkflowActionConfig | AgentWorkflowActionConfig[];
+  tags?: string[];
+  output?: unknown;
+  meta?: Record<string, unknown>;
+}
+/**
+ * An `invoke` entry in {@link AgentWorkflowStateConfig}. For `src:
+ * 'agent.decide'`, the chosen event is delivered automatically — its
+ * transition usually exits the state and ends the invoke, so an `onDone` is
+ * rarely needed; declare one only to observe a chosen event whose transition
+ * stays in-state. `onError` handles retries-exhausted.
+ */
+interface AgentWorkflowInvokeConfig {
+  id?: string;
+  src: string;
+  input?: unknown;
+  onDone?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  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. */
+interface AgentWorkflowTransitionConfig {
+  target?: string | string[];
+  guard?: unknown;
+  assign?: Record<string, unknown>;
+  actions?: AgentWorkflowActionConfig | AgentWorkflowActionConfig[];
+  description?: string;
+  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`. */
+interface AgentWorkflowActionConfig {
+  type?: string;
+  params?: unknown;
+  assign?: Record<string, unknown>;
+  emit?: unknown;
+  [key: string]: unknown;
+}
+/** Options for `setupAgent.fromConfig(...)`. */
+interface FromConfigOptions {
+  /**
+   * Compile a JSON Schema from the config into a runtime validator. Bring
+   * your own engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema
+   * pipeline, ...). Core intentionally ships no JSON Schema engine.
+   */
+  compileSchema: SchemaCompiler;
+}
+//#endregion
+//#region src/setup-agent.d.ts
+type Constrain<T, TConstraint> = T extends TConstraint ? T : TConstraint;
+type ContextOf<TContextSchema extends StandardSchemaV1> = Constrain<InferOutput<TContextSchema>, MachineContext>;
+type EventsOf<TEventSchemas extends AgentEventSchemaInputMap> = Constrain<EventUnion<TEventSchemas>, EventObject>;
+type SetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic }> = { [K in keyof TActors]: TActors[K] extends AsyncActorLogic<infer TOutput, infer TInput> ? AsyncActorLogic<TOutput, TInput> : TActors[K] };
+type AgentSetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic }, TEvent extends string = string, TModel extends string = string> = TActors & BuiltinAgentActors<TEvent, TModel>;
+/**
+ * A machine's full schema set — context, event payloads, machine input/
+ * output, and state/transition meta — as returned by {@link createAgentSchemas}
+ * and retained on `setupAgent(...)`'s `result.schemas` for runtime
+ * validation (e.g. by the step path to validate `initialAgentStep` input, or
+ * by `getAcceptedEvents` to attach event payload schemas). Unlike
+ * `AgentSchemaConfig` (the input to `createAgentSchemas`), every field here
+ * is required — `events`/`input`/`output`/`meta` default to empty/unknown
+ * schemas when not supplied.
+ */
+interface AgentSchemaPack<TContextSchema extends StandardSchemaV1<Record<string, unknown>> = StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap = AgentEventSchemaInputMap, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TEmittedSchemas extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> {
+  context: TContextSchema;
+  events: NormalizedEventSchemas<TEventSchemas>;
+  input: TInputSchema;
+  output: TOutputSchema;
+  meta: TMetaSchema;
+  /** Schemas for events the machine emits (`enq.emit(...)`), keyed by event type — they type `enq.emit` in the machine and the `on` handlers of {@link runAgent}. Optional: omitted means emitted events stay untyped. */
+  emitted?: TEmittedSchemas;
+}
+type AgentSchemaConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TEmittedSchemas extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> = {
+  context: TContextSchema;
+  events?: TEventSchemas;
+  input?: TInputSchema;
+  output?: TOutputSchema;
+  meta?: TMetaSchema;
+  emitted?: TEmittedSchemas;
+};
+/**
+ * Builds a machine's {@link AgentSchemaPack} from a partial schema
+ * declaration — only `context` is required; `events`/`input`/`output`/`meta`
+ * default to empty/unknown schemas when omitted. Pass the result as
+ * `setupAgent({ schemas })`'s `schemas` (or spread the individual fields
+ * 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;
+};
+type AgentRequestSchemaMap = Record<string, {
+  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> & {
+  schemas: TRequestSchemas[K];
+} };
+type RequestActors<TRequestSchemas extends AgentRequestSchemaMap> = { [K in keyof TRequestSchemas]: TextLogic<TRequestSchemas[K]["input"], TRequestSchemas[K]["output"]> };
+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 AgentSetupEmittedSchema<TEmittedSchemas extends Record<string, StandardSchemaV1>> = [keyof TEmittedSchemas] extends [never] ? {} : {
+  emitted: TEmittedSchemas;
+};
+type AgentSetupXStateConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = {
+  schemas: {
+    context: TContextSchema;
+    input: TInputSchema;
+    output: TOutputSchema;
+    meta: TMetaSchema;
+  } & AgentSetupEventsSchema<TEventSchemas> & AgentSetupEmittedSchema<TEmittedSchemas>;
+  states?: TStateSchemas;
+  actorSources: SetupActors<AgentSetupActors<AgentAllActors<TActors, TRequestSchemas>, keyof TEventSchemas & string, AgentModelRef<TModels>>>;
+  actions?: NonNullable<AnySetupConfig["actions"]>;
+  guards?: NonNullable<AnySetupConfig["guards"]>;
+  delays?: NonNullable<AnySetupConfig["delays"]>;
+};
+/**
+ * Field-level context-narrowing sugar for one `setupAgent({ states })` entry:
+ * each `context` entry overrides that field's schema inside the state; every
+ * other field keeps the base context schema. Sugar for the full xstate form —
+ * `{ context: { draft: z.string() } }` resolves to
+ * `{ schemas: { context: <base with draft: string> } }` — so only the fields
+ * that change are declared, not the whole context schema.
+ */
+interface AgentStateNarrowing {
+  context: Record<string, StandardSchemaV1>;
+  states?: Record<string, AgentSetupStateSchema>;
+}
+/** One `setupAgent({ states })` entry: xstate's {@link SetupStateSchema} full form, or the {@link AgentStateNarrowing} field-level sugar. */
+type AgentSetupStateSchema = SetupStateSchema | AgentStateNarrowing;
+type NarrowedContext<TContextSchema extends StandardSchemaV1, TFields extends Record<string, StandardSchemaV1>> = Omit<InferOutput<TContextSchema>, keyof TFields> & { [K in keyof TFields]: InferOutput<TFields[K]> };
+type ResolveAgentStateSchema<TContextSchema extends StandardSchemaV1, T> = T extends {
+  context: infer TFields extends Record<string, StandardSchemaV1>;
+} ? {
+  schemas: {
+    context: StandardSchemaV1<NarrowedContext<TContextSchema, TFields>>;
+  };
+} & (T extends {
+  states: infer TChildren extends Record<string, AgentSetupStateSchema>;
+} ? {
+  states: ResolveAgentStateSchemas<TContextSchema, TChildren>;
+} : {}) : T extends {
+  states: infer TChildren extends Record<string, AgentSetupStateSchema>;
+} ? Omit<T, "states"> & {
+  states: ResolveAgentStateSchemas<TContextSchema, TChildren>;
+} : T;
+type ResolveAgentStateSchemas<TContextSchema extends StandardSchemaV1, TStates extends Record<string, AgentSetupStateSchema>> = Constrain<{ [K in keyof TStates]: ResolveAgentStateSchema<TContextSchema, TStates[K]> }, Record<string, SetupStateSchema>>;
+type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic }, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TRequestSchemas extends AgentRequestSchemaMap, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = ({
+  schemas: AgentSchemaPack<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
+} | AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>) & {
+  models?: TModels;
+  actorSources?: TActors;
+  /**
+   * Per-state schemas, mirroring xstate's `setup({ states })`: narrow
+   * `context` inside a state (invoke `input`, transition fns, final `output`)
+   * — e.g. mark a field non-null in states only reachable after it is set.
+   * Two forms per state: the {@link AgentStateNarrowing} sugar
+   * (`{ context: { draft: z.string() } }` — only the fields that change) or
+   * xstate's full `{ schemas: { context } }` with a complete context schema.
+   */
+  states?: TStateSchemas;
+  requests?: AgentRequestInput<TRequestSchemas, AgentModelRef<TModels>>;
+  actions?: NonNullable<AnySetupConfig["actions"]>;
+  guards?: NonNullable<AnySetupConfig["guards"]>;
+  delays?: NonNullable<AnySetupConfig["delays"]>;
+  /**
+   * Detects a snapshot that is an INTENTIONAL wait for an external event (a
+   * human approval, an inbound webhook, …) — the machine's own declaration of
+   * what "suspended" means for it, so `runAgent` settles those snapshots idle
+   * deterministically instead of using its timing heuristic. Travels with the
+   * machine through `machine.provide(...)`. A `runAgent({ isSuspended })` host
+   * override takes precedence; with neither, `runAgent` falls back to the timing
+   * heuristic. Declare your own signal — e.g. `(s) => s.hasTag('awaiting-review')`
+   * or `(s) => getStateMeta(s).interaction !== undefined`.
+   */
+  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
+};
+type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, ResolveAgentStateSchemas<TContextSchema, TStateSchemas>>>;
+/**
+ * The object returned by {@link setupAgent}: an xstate `setup(...)` result
+ * (`createMachine`, `assign`, …) extended with `schemas` (the resolved
+ * {@link AgentSchemaPack}), `models`, `requests` (the built request actors),
+ * and {@link appendMessages}. Machines created here are registered so
+ * `runAgent` and the free step helpers can resolve their schemas/actors
+ * without re-passing them each call.
+ */
+type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = Omit<SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>, "createMachine"> & {
+  /**
+   * Creates the agent machine — XState's own `createMachine`, plus: the
+   * machine is registered so step helpers and {@link runAgent} can resolve
+   * 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`). */
+  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: {
+    context: ContextOf<TContextSchema> & {
+      messages: AgentMessage[];
+    };
+    event: any;
+  }) => AgentMessage | AgentMessage[])): ReturnType<typeof appendMessages<ContextOf<TContextSchema> & {
+    messages: AgentMessage[];
+  }, EventsOf<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
+ * {@link runAgent} or the step helpers) against host-supplied model/decision
+ * executors. Context, events, machine input, machine output, and
+ * 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` builtin actors and lowers `requests`/`actorSources` 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
+ * `setupAgent.fromConfig(...)` namespace member for building a machine from
+ * a serializable {@link AgentWorkflowConfig} instead of this TS API.
+ *
+ * @example
+ * ```ts
+ * const schemas = createAgentSchemas({
+ *   context: z.object({ topic: z.string(), joke: z.string().nullable() }),
+ *   input: z.object({ topic: z.string() }),
+ *   output: z.object({ joke: z.string() }),
+ * });
+ *
+ * const agent = setupAgent({
+ *   schemas,
+ *   actorSources: { tellJoke },
+ * });
+ *
+ * const jokeMachine = agent.createMachine({
+ *   context: ({ input }) => ({ topic: input.topic, joke: null }),
+ *   initial: 'telling',
+ *   states: {
+ *     telling: {
+ *       invoke: {
+ *         id: 'joke',
+ *         src: 'tellJoke',
+ *         input: ({ context }) => ({ topic: context.topic }),
+ *         onDone: ({ output }) => ({ target: 'done', context: { joke: output } }),
+ *       },
+ *     },
+ *     done: { type: 'final', output: ({ context }) => ({ joke: context.joke ?? '' }) },
+ *   },
+ * });
+ * ```
+ */
+declare function setupAgent<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TModels extends AgentModelMap = {}, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, const TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>>(config: SetupAgentBaseConfig<TContextSchema, TEventSchemas, TActors, TInputSchema, TOutputSchema, TMetaSchema, TRequestSchemas, TModels, TEmittedSchemas, TStateSchemas>): SetupAgentResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>;
+declare namespace setupAgent {
+  /**
+   * Builds a state machine from a serializable {@link AgentWorkflowConfig}
+   * (JSON/YAML) instead of the TypeScript `setupAgent(...)` API — the same
+   * kind of machine a database, visual editor, or LLM could produce and hand
+   * back. Requires a `compileSchema` (see {@link FromConfigOptions}) since
+   * the library bundles no JSON Schema engine itself; bring Ajv,
+   * @cfworker/json-schema, or another compiler that returns Standard Schema.
+   *
+   * @example
+   * ```ts
+   * const machine = setupAgent.fromConfig(workflowConfig, {
+   *   compileSchema,
+   * });
+   * const result = await runAgent(machine, { input: { ticket }, executors: { generateText, decide } });
+   * ```
+   */
+  function fromConfig(config: AgentWorkflowConfig, options: FromConfigOptions): AnyStateMachine;
+}
+//#endregion
+//#region src/internal/registry.d.ts
+type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actorSources"> & {
+  models?: object;
+};
+//#endregion
+//#region src/steps.d.ts
+/**
+ * A pending text request surfaced by step discovery ({@link getAgentRequests}
+ * / {@link AgentStep.requests}): the machine has spawned a
+ * `TextLogic`-backed invoke and is waiting on its result. Resolve it with
+ * {@link executeAgentRequest} (or by hand, then feed the output into
+ * {@link resolveAgentStep} via `xstate.done.actor.<id>`).
+ */
+interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
+  kind: "text";
+  id: string;
+  src: AgentRequestSource;
+  mode?: AgentRequestMode;
+  input: TInput;
+  tools: AgentTools;
+  events: AgentEventDescriptor[];
+}
+/**
+ * A pending **plan** request re-surfaced by step discovery: the machine
+ * invoked `agent.plan`, which applies an ordered sequence of legal events
+ * (each one a decision) rather than a single one. Unlike text/decision
+ * requests — surfaced once and resolved once — a plan request **re-surfaces on
+ * every step** while the plan is in flight, its `events`/`applied`/
+ * `stepsRemaining` updated each time, until it terminates.
+ *
+ * All fields are plain serializable data. Resolve ONE decision per step from
+ * `events` (via {@link resolveDecision}, wiring `canTake` to
+ * `snapshot.can` exactly like a single decision) then apply it: a real machine
+ * event advances the plan (the next step re-surfaces this request); the
+ * reserved `agent.plan.done` move, a `stopOn` event, an exhausted budget, or no
+ * legal events completes it (its invoke resolves with `{ steps, stopped }`).
+ * {@link resolveAgentRequests} does all of this natively — one decision (or one
+ * completion) per call.
+ *
+ * The in-progress plan state (`applied` trail + remaining budget) lives in the
+ * plan invoke child's own `createLogic` snapshot `context`
+ * (`children.<id>.snapshot.context`), so it survives a full JSON
+ * `getPersistedSnapshot` → restore round-trip: a host that persists the step
+ * after every event and reloads resumes the plan identically.
+ */
+interface AgentPlanRequest {
+  kind: "plan";
+  /** Durable invoke id of the `agent.plan` invoke. */
+  id: string;
+  /** Invoke src (`'agent.plan'` or a registered plan-logic source name). */
+  src: AgentRequestSource;
+  /** The resolved plan input (`model`/`system`/`prompt`/`allowedEvents`/`stopOn`/`maxSteps`/…). */
+  input: AgentPlanInput;
+  /**
+   * The legal candidates for the NEXT plan step: the currently
+   * snapshot-legal machine events (∩ declared `allowedEvents`) plus the
+   * reserved `agent.plan.done` move.
+   */
+  events: AgentEventDescriptor[];
+  /** The events applied so far in this plan, in order (the trail). */
+  applied: ChosenEvent[];
+  /** How many more events the plan may apply (`maxSteps - applied.length`). */
+  stepsRemaining: number;
+}
+/** `AgentStep.requests` element: a text, decision, or plan request. */
+type AgentStepRequest = AgentRequest | AgentDecisionRequest | AgentPlanRequest;
+/**
+ * One durable checkpoint on the step path: the machine's current snapshot,
+ * the executable actions that produced it, the pending
+ * {@link AgentStepRequest}s (text/decision work still to resolve), and
+ * whether the machine has reached a final state. This is the
+ * per-model-call-checkpoint path for durable hosts (Workflows, Temporal,
+ * queues, …) — a peer of `runAgent`, not a lesser version of it. Produced by
+ * {@link initialAgentStep}/{@link transitionAgentStep}/{@link resolveAgentStep}.
+ */
+interface AgentStep<TSnapshot extends AnyMachineSnapshot = AnyMachineSnapshot> {
+  snapshot: TSnapshot;
+  actions: readonly {
+    type?: string;
+    params?: unknown;
+  }[];
+  requests: AgentStepRequest[];
+  done: boolean;
+}
+/**
+ * Starts a machine and returns its first {@link AgentStep} — the step-path
+ * equivalent of `initialTransition` plus request discovery. Begins the
+ * durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+ * (via {@link executeAgentRequest} for `kind: 'text'`, or
+ * {@link resolveDecision} for `kind: 'decision'`), then advance with
+ * {@link resolveAgentStep} or {@link transitionAgentStep}.
+ */
+declare function initialAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, input?: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Applies an externally-sent event (e.g. a decision's chosen event, or a
+ * human's reply) and returns the next {@link AgentStep}. Accepts **either**
+ * a raw snapshot **or** a prior `AgentStep` as the second argument —
+ * `.snapshot` is unwrapped automatically, so callers can thread the whole
+ * step object through without manually plucking the snapshot out.
+ */
+declare function transitionAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, snapshotOrStep: SnapshotFrom<TMachine> | AgentStep<SnapshotFrom<TMachine>>, event: EventFromLogic<TMachine>, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Applies a resolved text request's output (a `kind: 'text'`
+ * {@link AgentRequest} — not a decision) as a done event and returns the
+ * next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+ * (which returns a {@link ChosenEvent}) and apply it with
+ * {@link transitionAgentStep} instead — a decision has no output value of
+ * its own to feed here.
+ */
+declare function resolveAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, request: Pick<AgentRequest, "id"> | string, output: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Snapshot in, requests out: scans executable actions for spawned agent
+ * invokes and lowers each into an {@link AgentStepRequest}, pre-filled with
+ * the machine's registered `setupAgent` schemas/actorSources (so callers
+ * don't pass them by hand each call) — merged with any `options` passed here,
+ * which take precedence. The step path's public discovery primitive;
+ * `initialAgentStep`/`transitionAgentStep`/`resolveAgentStep` call it
+ * internally to populate `AgentStep.requests`.
+ */
+declare function getAgentRequests(machine: AnyActorLogic, actions: readonly {
+  type?: string;
+  params?: unknown;
+}[], snapshot?: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "eventToolName"> & Partial<AgentExecutionOptions>): AgentStepRequest[];
+/**
+ * Resolves one **text** {@link AgentRequest} against a host's
+ * {@link AgentRequestExecutors} — merges the request's tools, dispatches to
+ * `generateText`/`streamText` per `request.mode`, and validates the result
+ * against `request.input.outputSchema` if present. **Text-only**: passing a
+ * `kind: 'decision'` request throws, directing the caller to
+ * `resolveDecision(request, executors.decide, ...)` instead. By default
+ * returns the normalized output; pass `{ verbose: true }` to also get the
+ * raw executor result (tool calls, usage, finish reason — needed for
+ * observability and event-sourced replay).
+ */
+declare function executeAgentRequest(request: AgentRequest, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
+declare function executeAgentRequest(request: AgentRequest, executors: Partial<AgentRequestExecutors>, options: {
+  verbose: true;
+}): Promise<{
+  output: unknown;
+  raw: unknown;
+}>;
+/**
+ * Options for {@link resolveAgentRequests}.
+ */
+interface ResolveAgentRequestsOptions extends Partial<AgentExecutionOptions> {
+  /** Retries per decision, passed to `resolveDecision`. Default `2`. */
+  maxRetries?: number;
+}
+/**
+ * Resolves the current step's pending requests and returns the next
+ * {@link AgentStep} — one iteration of the durable step loop, collapsing the
+ * manual `request.kind` dispatch a host would otherwise write by hand.
+ *
+ * For each pending request, in order: a `kind: 'text'` request is run with
+ * {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+ * `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+ * `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+ * applied with {@link transitionAgentStep}. The **current** step is re-read
+ * after each application — the machine may advance and its `requests` change —
+ * so this always resolves against the live step, never a stale list.
+ *
+ * A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+ * step per call. It resolves a single decision from `request.events` (wiring
+ * `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+ * move and `stopOn` events), then either applies the chosen machine event and
+ * lets the next step re-surface the plan, or completes the plan (feeding its
+ * `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+ * exhausted budget / no legal events. The plan's applied trail is carried in
+ * the invoke child's snapshot, so persisting the step between calls resumes the
+ * plan identically.
+ *
+ * Missing the executor a request needs throws a clear error
+ * (`generateText`/`streamText` for text, `decide` for decisions and plans).
+ *
+ * A complete durable host is two lines:
+ *
+ * ```ts
+ * let step = initialAgentStep(machine, input);
+ * while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+ * ```
+ *
+ * All pending **text** requests of a step are resolved in parallel
+ * (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+ * their model calls run concurrently — then their outputs apply in
+ * **request-array order** (deterministic for durable replay regardless of which
+ * call finishes first). Decisions and plans stay **one at a time**: applying
+ * either changes the set of legal candidates for what follows, so they cannot be
+ * resolved against a stale snapshot. A host that instead wants strictly
+ * sequential text resolution loops the manual per-request helpers
+ * ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+ */
+declare function resolveAgentRequests<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, executors: Partial<AgentRequestExecutors>, options?: ResolveAgentRequestsOptions): Promise<AgentStep<SnapshotFrom<TMachine>>>;
+//#endregion
+//#region src/internal/state-request-pass.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;
+}
+type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
+  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}.
+ *
+ * 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.
+ */
+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;
+  /**
+   * Fires on every machine transition (snapshot + causing event). Pure
+   * observation — progress UIs, logging, tracing. Cannot send events.
+   */
+  onTransition?: (snapshot: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine>) => void;
+  /**
+   * 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).
+   */
+  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).
+   */
+  inspect?: (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;
+}
+/**
+ * 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";
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @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'.
+ */
+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;
+//#endregion
+export { AgentSchemaPack as A, AgentWorkflowStateConfig as B, initialAgentStep as C, AgentMachine as D, transitionAgentStep as E, AgentWorkflowActionConfig as F, messagesSchema as G, FromConfigOptions as H, AgentWorkflowActorConfig as I, AgentWorkflowConfig as L, AgentStateNarrowing as M, createAgentSchemas as N, AgentMachineConfig as O, setupAgent as P, AgentWorkflowInvokeConfig as R, getAgentRequests as S, resolveAgentStep as T, SchemaCompiler as U, AgentWorkflowTransitionConfig as V, appendMessages as W, AgentRequest as _, AgentUserInputExecutor as a, ResolveAgentRequestsOptions as b, PendingUserInput as c, SnapshotVersionMismatchError as d, inspectTransitions as f, AgentPlanRequest as g, AgentStateRequest as h, AgentTraceEvent as i, AgentSetupStateSchema as j, AgentRequestConfig as k, RunAgentOptions as l, runAgentToCompletion as m, AgentMessageInfo as n, IllegalResumeEventError as o, runAgent as p, AgentRunMeta as r, InspectedActorRef as s, AgentIdleError as t, RunAgentResult as u, AgentStep as v, resolveAgentRequests as w, executeAgentRequest as x, AgentStepRequest as y, AgentWorkflowRequestConfig as z };