@statelyai/agent 1.1.6 → 2.0.0-alpha.5

package/dist/index.d.mts

@@ -1,428 +1,1217 @@
-import { EventObject, AnyStateMachine, AnyEventObject, AnyActorRef, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, ActorRefFrom, Subscription, StateValue, ObservableActorLogic } from 'xstate';
-import { SomeZodObject, ZodType, TypeOf } from 'zod';
-import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, StreamTextResult, CoreTool } from 'ai';
+import { C as ToolCallPart, D as UserMessage, E as ToolResultPart, S as TextPart, T as ToolResultOutput, _ as ImagePart, a as AgentToolDescriptor, b as StandardSchemaV1, c as AgentTools, d as AssistantMessage, f as ChosenEvent, g as FilePart, h as EventUnion, i as AgentToolChoice, l as AllowedEventPattern, m as EventPayload, n as AgentSnapshotStore, o as AgentToolExecute, p as DataContent, r as AgentTool, s as AgentToolSchema, t as AgentMessage, u as AllowedEvents, v as InferOutput, w as ToolMessage, x as SystemMessage, y as ProviderOptions } from "./types-Cq1YlAQ6.mjs";
+import { A as AgentPlanInput, B as AgentEventDescriptor, C as createTextLogic, D as AgentDecisionExecutor, E as parseOutput, F as DecisionLogicConfig, G as getAcceptedEvents, H as AgentRequestOptions, I as PLAN_DONE_EVENT_TYPE, K as matchesEventPattern, L as ResolveDecisionOptions, M as DecisionAttempt, N as DecisionExhaustedError, O as AgentDecisionInput, P as DecisionLogic, R as renderDecisionAttempts, S as buildEnvelopeSchema, T as isStructuredOutputSchema, U as AgentRequestSource, V as AgentEventToolNameResolver, W as EVENT_TOOL_PREFIX, _ 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 AgentPlanOutput, k as AgentDecisionRequest, l as AgentTextRequest, m as StructuredOutputEnvelope, n as AgentModelRef, o as AgentRequestExecutorResult, p as BuiltinAgentActors, q as parseAgentEvent, r as AgentOutputMode, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, w as getAgentOutputMode, x as bindRequestExecutor, y as TextLogicInput, z as resolveDecision } from "./text-logic-2EMJIS-n.mjs";
+import { a as getMachineStructuralHash, c as persistSnapshot, d as userMessage, f as validateSchemaSync, i as getJsonSchemaSync, l as systemMessage, n as getAgentMessages, o as getStateMeta, r as getJsonSchema, s as isStandardSchema, t as assistantMessage, u as toolMessage } from "./utils-CWUCa3pF.mjs";
+import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, Snapshot, SnapshotFrom } from "xstate";
 
-type ZodEventMapping = {
-    [eventType: string]: SomeZodObject;
+//#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[];
+  };
 };
-type ZodContextMapping = {
-    [contextKey: string]: ZodType;
+/**
+ * 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;
 };
-
-type GenerateTextOptions = Parameters<typeof generateText>[0];
-type StreamTextOptions = Parameters<typeof streamText>[0];
-type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'prompt' | 'messages' | 'tools'> & {
-    /**
-     * The currently observed state.
-     */
-    state: ObservedState;
-    /**
-     * The goal for the agent to accomplish.
-     * The agent will create a plan based on this goal.
-     */
-    goal: string;
-    /**
-     * The events that the agent can trigger. This is a mapping of
-     * event types to Zod event schemas.
-     */
-    events: ZodEventMapping;
-    /**
-     * The state machine that represents the environment the agent
-     * is interacting with.
-     */
-    machine?: AnyStateMachine;
-    /**
-     * The previous plan.
-     */
-    previousPlan?: AgentPlan<TEvent>;
+/**
+ * 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 Record<string, StandardSchemaV1>> = 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 Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>, 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: 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 Record<string, StandardSchemaV1>, 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 Record<string, StandardSchemaV1> = {}, 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 Record<string, StandardSchemaV1>> = [keyof TEventSchemas] extends [never] ? {} : {
+  events: TEventSchemas;
 };
-type AgentPlan<TEvent extends EventObject> = {
-    goal: string;
-    state: ObservedState;
-    content?: string;
-    /**
-     * Executes the plan based on the given `state` and resolves with
-     * a potential next `event` to trigger to achieve the `goal`.
-     */
-    execute: (state: ObservedState) => Promise<TEvent | undefined>;
-    nextEvent: TEvent | undefined;
-    sessionId: string;
-    timestamp: number;
+type AgentSetupEmittedSchema<TEmittedSchemas extends Record<string, StandardSchemaV1>> = [keyof TEmittedSchemas] extends [never] ? {} : {
+  emitted: TEmittedSchemas;
 };
-interface TransitionData {
-    eventType: string;
-    description?: string;
-    guard?: {
-        type: string;
+type AgentSetupXStateConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, 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"]>;
+};
+type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, 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, SetupStateSchema> = Record<string, SetupStateSchema>> = ({
+  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 })`: declare a
+   * `schemas.context` on a state to narrow `context` inside that state
+   * (invoke `input`, transition fns, final `output`) — e.g. mark a field
+   * non-null in states only reachable after it is set.
+   */
+  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 Record<string, StandardSchemaV1>, 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>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, 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 Record<string, StandardSchemaV1>, 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>> = 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[];
     };
-    target?: any;
+    event: any;
+  }) => AgentMessage | AgentMessage[])): ReturnType<typeof appendMessages<ContextOf<TContextSchema> & {
+    messages: AgentMessage[];
+  }, EventsOf<TEventSchemas>>>;
+};
+/**
+ * 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 Record<string, StandardSchemaV1>, 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, SetupStateSchema> = Record<string, SetupStateSchema>>(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;
 }
-type PromptTemplate<TEvents extends EventObject> = (data: {
-    goal: string;
-    /**
-     * The observed state
-     */
-    state?: ObservedState;
-    /**
-     * The context to provide.
-     * This overrides the observed state.context, if provided.
-     */
-    context?: any;
-    /**
-     * The state machine model of the observed environment
-     */
-    machine?: unknown;
-    /**
-     * The potential next transitions that can be taken
-     * in the state machine
-     */
-    transitions?: TransitionData[];
-    /**
-     * Past observations
-     */
-    observations?: AgentObservation<any>[];
-    feedback?: AgentFeedback[];
-    messages?: AgentMessage[];
-    plans?: AgentPlan<TEvents>[];
-}) => string;
-type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
-type AgentDecideOptions = {
-    goal: string;
-    model?: LanguageModel;
-    context?: any;
-    state: ObservedState;
-    machine: AnyStateMachine;
-    execute?: (event: AnyEventObject) => Promise<void>;
-    planner?: AgentPlanner<any>;
-    events?: ZodEventMapping;
-} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt' | 'messages'>;
-interface AgentFeedback {
-    goal?: string;
-    observationId?: string;
-    /**
-     * The message correlation that the feedback is relevant for
-     */
-    correlationId?: string;
-    attributes: Record<string, any>;
-    reward: number;
-    timestamp: number;
-    sessionId: string;
+//#endregion
+//#region src/internal/registry.d.ts
+type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actorSources">;
+//#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[];
 }
-interface AgentFeedbackInput {
-    goal?: string;
-    observationId?: string;
-    correlationId?: string;
-    attributes?: Record<string, any>;
-    timestamp?: number;
-    reward?: number;
+/**
+ * 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;
 }
-type AgentMessage = CoreMessage & {
-    timestamp: number;
-    id: string;
-    /**
-     * The response ID of the message, which references
-     * which message this message is responding to, if any.
-     */
-    responseId?: string;
-    result?: GenerateTextResult<any>;
-    sessionId: string;
-    correlationId: string;
-    parentCorrelationId?: string;
-};
-type AgentMessageInput = CoreMessage & {
-    timestamp?: number;
-    id?: string;
-    /**
-     * The response ID of the message, which references
-     * which message this message is responding to, if any.
-     */
-    responseId?: string;
-    correlationId?: string;
-    parentCorrelationId?: string;
-    result?: GenerateTextResult<any>;
-};
-interface AgentObservation<TActor extends AnyActorRef> {
-    id: string;
-    prevState: SnapshotFrom<TActor> | undefined;
-    event: EventFrom<TActor>;
-    state: SnapshotFrom<TActor>;
-    machineHash: string | undefined;
-    sessionId: string;
-    timestamp: 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);
 }
-interface AgentObservationInput {
-    id?: string;
-    prevState: ObservedState | undefined;
-    event: AnyEventObject;
-    state: ObservedState;
-    machine?: AnyStateMachine;
-    timestamp?: number;
+/**
+ * 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[]);
 }
-type AgentDecisionInput = {
-    goal: string;
-    model?: LanguageModel;
-    context?: any;
-} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
-type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<AgentPlan<TEvents> | undefined, AgentDecisionInput | string>;
-type AgentEmitted<TEvents extends EventObject> = {
-    type: 'feedback';
-    feedback: AgentFeedback;
+/** Handler for `agent.userInput` invokes passed as {@link RunAgentOptions.userInput}. */
+interface AgentUserInputExecutor {
+  (input: AgentUserInput): PromiseLike<unknown>;
+}
+type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
+  runId: string;
+  seq: number;
+  timestamp: string;
+} & ({
+  type: "run.start";
+  input?: InputFrom<TMachine>;
+  snapshot?: Snapshot<unknown>;
+  event?: EventFromLogic<TMachine>;
 } | {
-    type: 'observation';
-    observation: AgentObservation<any>;
+  type: "request.start";
+  request: AgentStepRequest;
 } | {
-    type: 'message';
-    message: AgentMessage;
+  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: 'plan';
-    plan: AgentPlan<TEvents>;
-};
-type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<AgentMemoryContext>, {
-    type: 'agent.feedback';
-    feedback: AgentFeedback;
+  type: "request.error";
+  request: AgentStepRequest;
+  error: unknown;
 } | {
-    type: 'agent.observe';
-    observation: AgentObservation<any>;
+  type: "stream.chunk";
+  request: AgentRequest;
+  chunk: string;
 } | {
-    type: 'agent.message';
-    message: AgentMessage;
+  type: "machine.transition";
+  snapshot: SnapshotFrom<TMachine>;
+  event: EventFromLogic<TMachine>;
 } | {
-    type: 'agent.plan';
-    plan: AgentPlan<TEvents>;
-}, any, // TODO: input
-any, AgentEmitted<TEvents>>;
-type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
-    [K in keyof TEventSchemas & string]: {
-        type: K;
-    } & TypeOf<TEventSchemas[K]>;
-}>;
-type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
-    [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
-};
-type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
-    /**
-     * The name of the agent. All agents with the same name are related and
-     * able to share experiences (observations, feedback) with each other.
-     */
-    name?: string;
-    /**
-     * The unique identifier for the agent.
-     */
-    id?: string;
-    description?: string;
-    events: ZodEventMapping;
-    types: {
-        events: TEvents;
-        context: Compute<TContext>;
-    };
-    model: LanguageModel;
-    defaultOptions: GenerateTextOptions;
-    memory: AgentLongTermMemory | undefined;
-    /**
-     * The adapter used to perform LLM actions such as
-     * `.generateText(…)` and `.streamText(…)`.
-     *
-     * Defaults to the Vercel AI SDK.
-     */
-    adapter: AIAdapter;
-    /**
-     * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
-     *
-     * - The `goal` for the agent to achieve
-     * - The observed current `state`
-     * - The `machine` (e.g. a state machine) that specifies what can happen next
-     * - Additional `context`
-     */
-    decide: (options: AgentDecideOptions) => Promise<AgentPlan<TEvents> | undefined>;
-    generateText: (options: AgentGenerateTextOptions) => Promise<AgentGenerateTextResult>;
-    streamText: (options: AgentStreamTextOptions) => Promise<AgentStreamTextResult>;
-    addObservation: (observationInput: AgentObservationInput) => AgentObservation<any>;
-    addMessage: (messageInput: AgentMessageInput) => AgentMessage;
-    addFeedback: (feedbackInput: AgentFeedbackInput) => AgentFeedback;
-    addPlan: (plan: AgentPlan<TEvents>) => void;
-    /**
-     * Called whenever the agent (LLM assistant) receives or sends a message.
-     */
-    onMessage: (callback: (message: AgentMessage) => void) => void;
-    /**
-     * Selects agent data from its context.
-     *
-     * @deprecated Select from `agent.getSnapshot().context` directly or:
-     * - `agent.getMessages()`
-     * - `agent.getObservations()`
-     * - `agent.getFeedback()`
-     * - `agent.getPlans()`
-     */
-    select: <T>(selector: (context: AgentMemoryContext) => T) => T;
-    /**
-     * Retrieves messages from the agent's short-term (local) memory.
-     */
-    getMessages: () => AgentMessage[];
-    /**
-     * Retrieves observations from the agent's short-term (local) memory.
-     */
-    getObservations: () => AgentObservation<Agent<TContext, TEvents>>[];
-    /**
-     * Retrieves feedback from the agent's short-term (local) memory.
-     */
-    getFeedback: () => AgentFeedback[];
-    /**
-     * Retrieves strategies from the agent's short-term (local) memory.
-     */
-    getPlans: () => AgentPlan<TEvents>[];
-    /**
-     * Interacts with this state machine actor by inspecting state transitions and storing them as observations.
-     *
-     * Observations contain the `prevState`, `event`, and current `state` of this
-     * actor, as well as other properties that are useful when recalled.
-     * These observations are stored in the `agent`'s short-term (local) memory
-     * and can be retrieved via `agent.getObservations()`.
-     *
-     * @example
-     * ```ts
-     * // Only observes the actor's state transitions
-     * agent.interact(actor);
-     *
-     * actor.start();
-     * ```
-     */
-    interact<TActor extends AnyActorRef>(actorRef: TActor): Subscription;
-    /**
-     * Interacts with this state machine actor by:
-     * 1. Inspecting state transitions and storing them as observations
-     * 2. Deciding what to do next (which event to send the actor) based on
-     * the agent input returned from `getInput(observation)`, if `getInput(…)` is provided as the 2nd argument.
-     *
-     * Observations contain the `prevState`, `event`, and current `state` of this
-     * actor, as well as other properties that are useful when recalled.
-     * These observations are stored in the `agent`'s short-term (local) memory
-     * and can be retrieved via `agent.getObservations()`.
-     *
-     * @example
-     * ```ts
-     * // Observes the actor's state transitions and
-     * // makes a decision if on the "summarize" state
-     * agent.interact(actor, observed => {
-     *   if (observed.state.matches('summarize')) {
-     *     return {
-     *       context: observed.state.context,
-     *       goal: 'Summarize the message'
-     *     }
-     *   }
-     * });
-     *
-     * actor.start();
-     * ```
-     */
-    interact<TActor extends AnyActorRef>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
-};
-type AnyAgent = Agent<any, any>;
-type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
-type CommonTextOptions = {
-    prompt: FromAgent<string>;
-    model?: LanguageModel;
-    context?: Record<string, any>;
-    messages?: FromAgent<CoreMessage[]>;
-    template?: PromptTemplate<any>;
-    correlationId?: string;
-    parentCorrelationId?: string;
+  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>, context: {
+    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) => 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, schema, …). 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>;
 };
-type TextResultMeta = {
-    correlationId: string;
-    parentCorrelationId?: string;
+/**
+ * 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;
 };
-type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-type AgentGenerateTextResult = GenerateTextResult<any> & TextResultMeta;
-type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-type AgentStreamTextResult = StreamTextResult<any> & TextResultMeta;
-interface ObservedState {
-    /**
-     * The current state value of the state machine, e.g.
-     * `"loading"` or `"processing"` or `"ready"`
-     */
-    value: StateValue;
-    /**
-     * Additional contextual data related to the current state
-     */
-    context: Record<string, unknown>;
+/**
+ * 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
+//#region src/verify.d.ts
+/** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
+type AgentLintSeverity = "error" | "warning";
+/**
+ * One static-analysis finding from {@link lintAgentMachine}. `code` names the
+ * check (stable, machine-readable), `path` points at the offending state path
+ * or config location, and `message` explains the problem and its remedy.
+ */
+interface AgentLintDiagnostic {
+  code: "unreachable-state" | "decide-without-events" | "unserializable-context" | "direct-object-src" | "final-without-output" | "final-output-reads-event" | "missing-final";
+  severity: AgentLintSeverity;
+  /** State path (`parent.child`) or config pointer (e.g. `(root)`, `context`) the finding is about. */
+  path: string;
+  message: string;
 }
-type ObservedStateFrom<TActor extends AnyActorRef> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
-type AgentMemoryContext = {
-    observations: AgentObservation<any>[];
-    messages: AgentMessage[];
-    plans: AgentPlan<any>[];
-    feedback: AgentFeedback[];
-};
-type AgentMemory = AppendOnlyStorage<AgentMemoryContext>;
-interface AppendOnlyStorage<T extends Record<string, any[]>> {
-    append<K extends keyof T>(sessionId: string, key: K, item: T[K][0]): Promise<void>;
-    getAll<K extends keyof T>(sessionId: string, key: K): Promise<T[K] | undefined>;
+/** Options for {@link lintAgentMachine}. Reserved for future check selection. */
+interface LintAgentMachineOptions {
+  /** Skip these check codes entirely. */
+  disable?: AgentLintDiagnostic["code"][];
 }
-interface AgentLongTermMemory {
-    get<K extends keyof AgentMemoryContext>(key: K): Promise<AgentMemoryContext[K]>;
-    append<K extends keyof AgentMemoryContext>(key: K, item: AgentMemoryContext[K][0]): Promise<void>;
-    set<K extends keyof AgentMemoryContext>(key: K, items: AgentMemoryContext[K]): Promise<void>;
+/**
+ * Runs static structural checks over a built agent machine and returns the
+ * findings ({@link AgentLintDiagnostic}[], empty when clean). Works for
+ * TS-authored (`setupAgent(...).createMachine(...)`) and
+ * `setupAgent.fromConfig(...)`-compiled machines alike, reading `machine.config`
+ * plus the schemas/actor sources the library already retains per machine.
+ *
+ * No model calls, no API keys — a coding agent that emits an agent machine can
+ * call this to catch dead states, undeliverable decisions, un-rebindable
+ * invoke srcs, and output-contract gaps before ever running it.
+ *
+ * @example
+ * ```ts
+ * const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
+ * if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
+ * ```
+ */
+declare function lintAgentMachine(machine: AnyStateMachine, options?: LintAgentMachineOptions): AgentLintDiagnostic[];
+/**
+ * Scripted responses for a {@link simulateAgent} playthrough. Each channel is a
+ * by-`src` map of FIFO queues, consumed in the order the machine reaches the
+ * requests:
+ * - `text` — output values for text requests, keyed by request src (the
+ *   `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`).
+ * - `decisions` — the {@link ChosenEvent} to apply for a decision request,
+ *   keyed by decision src (usually `agent.decide`).
+ * - `userInput` — output values for `agent.userInput` invokes, keyed by src
+ *   (usually `agent.userInput`).
+ */
+interface SimulationScript {
+  text?: Record<string, unknown[]>;
+  decisions?: Record<string, ChosenEvent[]>;
+  userInput?: Record<string, unknown[]>;
 }
-interface AIAdapter {
-    generateText: typeof generateText;
-    streamText: typeof streamText;
+/** One entry in a {@link SimulateAgentResult.trail}: the state after this step, plus what drove the step. */
+interface SimulationTrailEntry {
+  /** The machine state value after applying this step. */
+  state: unknown;
+  /** The chosen event applied (for a decision request). */
+  appliedEvent?: ChosenEvent;
+  /** The resolved request (for a text/userInput invoke): its kind and src. */
+  resolvedRequest?: {
+    kind: "text" | "userInput";
+    src: string;
+    id: string;
+  };
 }
-type Compute<A extends any> = {
-    [K in keyof A]: A[K];
-} & unknown;
-
-declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ name, description, model, events, context, planner, stringify, getMemory, logic, adapter, ...generateTextOptions }: {
-    /**
-     * The unique identifier for the agent.
-     *
-     * This should be the same across all sessions of a specific agent, as it can be
-     * used to retrieve memory for this agent.
-     *
-     * @example
-     * ```ts
-     * const agent = createAgent({
-     *  id: 'recipe-assistant',
-     *  // ...
-     * });
-     * ```
-     */
-    id?: string;
-    /**
-     * The name of the agent
-     */
-    name?: string;
-    /**
-     * A description of the role of the agent
-     */
-    description?: string;
-    /**
-     * Events that the agent can cause (send) in an environment
-     * that the agent knows about.
-     */
-    events: TEventSchemas;
-    context?: TContextSchema;
-    planner?: AgentPlanner<Agent<TContext, TEvents>>;
-    stringify?: typeof JSON.stringify;
-    /**
-     * A function that retrieves the agent's long term memory
-     */
-    getMemory?: (agent: Agent<TContext, TEvents>) => AgentLongTermMemory;
-    /**
-     * Agent logic
-     */
-    logic?: AgentLogic<TEvents>;
-    adapter?: AIAdapter;
-} & GenerateTextOptions): Agent<TContext, TEvents>;
-
-declare function fromTextStream<T extends AnyAgent>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
-    textDelta: string;
-}, Omit<AgentStreamTextOptions, 'context'> & {
-    context?: AgentStreamTextOptions['context'];
-}>;
-declare function fromText<T extends AnyAgent>(agent: T, defaultOptions?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
-    context?: AgentGenerateTextOptions['context'];
-}>;
-
-declare function fromDecision(agent: AnyAgent, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
-
-export { type AIAdapter, type Agent, type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentGenerateTextResult, type AgentLogic, type AgentLongTermMemory, type AgentMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStreamTextOptions, type AgentStreamTextResult, type AnyAgent, type AppendOnlyStorage, type CommonTextOptions, type Compute, type ContextFromZodContextMapping, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TextResultMeta, type TransitionData, createAgent, fromDecision, fromText, fromTextStream };
+/** Options for {@link simulateAgent}. */
+interface SimulateAgentOptions {
+  input?: unknown;
+  script: SimulationScript;
+  /** Max steps before returning `'exhausted'`. Default 100. */
+  maxSteps?: number;
+}
+/** The outcome of a {@link simulateAgent} playthrough. */
+interface SimulateAgentResult {
+  /** `'done'` = reached a final state; `'idle'` = paused with no pending work; `'exhausted'` = hit `maxSteps`. */
+  status: "done" | "idle" | "exhausted";
+  snapshot: AnyMachineSnapshot;
+  trail: SimulationTrailEntry[];
+}
+/**
+ * Deterministically plays a machine through, resolving each request from a
+ * {@link SimulationScript} instead of a model — no API keys, no model calls.
+ * Runs on the pure step path ({@link initialAgentStep} etc.), so it exercises
+ * the real transition logic. Returns the terminal `status`, final `snapshot`,
+ * and a `trail` of every step taken.
+ *
+ * Throws a descriptive error when the script runs dry mid-request, naming the
+ * pending request's kind, src, and id so the missing scripted response is
+ * obvious.
+ *
+ * @example
+ * ```ts
+ * const { status, snapshot } = simulateAgent(machine, {
+ *   input: { topic: 'state machines' },
+ *   script: { decisions: { 'agent.decide': [{ type: 'END' }] } },
+ * });
+ * ```
+ */
+declare function simulateAgent(machine: AnyStateMachine, options: SimulateAgentOptions): Promise<SimulateAgentResult>;
+/** Options for {@link explorePaths}. */
+interface ExplorePathsOptions {
+  input?: unknown;
+  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
+  maxDepth?: number;
+  /** Total path cap before exploration stops (reported via `hitPathCap`). Default 200. */
+  maxPaths?: number;
+  /** Canned outputs for text/userInput invokes, keyed by src. A missing src halts that branch with a `needs-output` note. */
+  textOutputs?: Record<string, unknown>;
+}
+/** A single explored path's terminal outcome. */
+interface AgentPathTerminal {
+  status: "done" | "idle" | "needs-output" | "max-depth";
+  /** The chosen/applied events, in order, that produced this terminal. */
+  path: ChosenEvent[];
+  /** The final state value on this path. */
+  state: unknown;
+  /** For `needs-output`: the src whose canned output was missing. */
+  missingSrc?: string;
+}
+/** The report returned by {@link explorePaths}. */
+interface AgentPathReport {
+  /** Every distinct state value (JSON) encountered across all explored paths. */
+  reachedStates: unknown[];
+  /** One entry per explored path. */
+  terminals: AgentPathTerminal[];
+  /** How many candidate events were pruned because a guard rejected them. */
+  prunedByGuard: number;
+  /** Notes about coverage the exploration could not complete (missing outputs, depth/path caps). */
+  unexplored: string[];
+  /** Total paths explored. */
+  pathsExplored: number;
+  /** True when the total-paths cap was hit (report is partial). */
+  hitPathCap: boolean;
+}
+/**
+ * Enumerates a machine's decision and external-event branches to a bounded
+ * depth, model-free, and reports which states are reached and how each path
+ * terminates. At each decision request it forks one branch per candidate event
+ * (guard-rejected candidates are counted in `prunedByGuard`, not explored); at
+ * an idle wait it forks per externally-accepted event. A `agent.plan` request
+ * forks the same way — one branch per candidate, including the reserved
+ * `agent.plan.done` move — advancing each branch through the real plan protocol
+ * (`resolveAgentRequests`), so a plan can consume several depth units. Text/`userInput` invokes
+ * are resolved from `textOutputs` (a by-src canned-output map) — a missing src
+ * halts that branch with a `needs-output` terminal rather than throwing.
+ *
+ * Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
+ * 200, reported via `hitPathCap`).
+ *
+ * @example
+ * ```ts
+ * const report = await explorePaths(refundMachine, { input: { request: 'x', amount: 5000 } });
+ * // report.terminals → both 'refunded' and 'denied'; report.prunedByGuard → 1
+ * ```
+ */
+declare function explorePaths(machine: AnyStateMachine, options?: ExplorePathsOptions): Promise<AgentPathReport>;
+/** The result of a {@link canReach} query. */
+interface CanReachResult {
+  canReach: boolean;
+  /** When reachable, the sequence of chosen/applied events that gets there. */
+  witness?: ChosenEvent[];
+}
+/**
+ * Answers "can the machine reach `statePath`?" by exploring its branches (a
+ * thin wrapper over {@link explorePaths}). Returns `{ canReach: true, witness }`
+ * with the event sequence that reaches it, or `{ canReach: false }`.
+ *
+ * @example
+ * ```ts
+ * const { canReach, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+ * // canReach → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+ * ```
+ */
+declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
+//#endregion
+export { type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, type AgentLintSeverity, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentPlanRequest, type AgentRequest, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentSchemaPack, type AgentSnapshotStore, type AgentStateRequest, type AgentStep, type AgentStepRequest, 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 AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type DecisionLogicConfig, EVENT_TOOL_PREFIX, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, PLAN_DONE_EVENT_TYPE, type PendingUserInput, type ProviderOptions, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type StructuredOutputEnvelope, 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, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseOutput, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };