@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/index.d.mts

@@ -1,428 +1,1232 @@
-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 { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, O as ToolResultOutput, S as ProviderOptions, T as TextPart, _ as EventUnion, a as AgentTool, b as InferOutput, c as AgentToolExecute, d as AllowedEventPattern, f as AllowedEvents, g as EventPayload, h as DataContent, i as AgentSnapshotStore, k as ToolResultPart, l as AgentToolSchema, m as ChosenEvent, n as AgentEventSchemaInputMap, o as AgentToolChoice, p as AssistantMessage, r as AgentMessage, s as AgentToolDescriptor, t as AgentEventSchemaInput, u as AgentTools, v as FilePart, w as SystemMessage, x as NormalizedEventSchemas, y as ImagePart } from "./types-qm00QF91.mjs";
+import { A as AgentDecisionInput, C as createTextLogic, F as DecisionExhaustedError, G as AgentRequestOptions, I as DecisionLogic, K as AgentRequestSource, M as AgentPlanInput, N as AgentPlanOutput, P as DecisionAttempt, U as AgentEventDescriptor, W as AgentEventToolNameResolver, Y as parseAgentEvent, _ as TextLogicExecuteArgs, a as AgentRequestExecutorInfo, b as TextLogicOutput, c as AgentRequestMode, d as AiSdkShapedStreamResult, f as AiSdkShapedTextResult, g as TextLogicConfig, h as TextLogic, i as AgentRequestExecutor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, n as AgentModelRef, o as AgentRequestExecutorResult, p as BuiltinAgentActors, q as getAcceptedEvents, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, y as TextLogicInput, z as PlanLogic } from "./text-logic-CaKqgX4Y.mjs";
+import { c as persistSnapshot, d as userMessage, l as systemMessage, n as getAgentMessages, o as getStateMeta, t as assistantMessage, u as toolMessage } from "./utils-Do5wIJrh.mjs";
+import { i as AgentStepRequest, n as AgentRequest } from "./steps-BALp1eZo.mjs";
+import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, Snapshot, SnapshotFrom } from "xstate";
 
-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 {
+  /** JSON Schema reference (`"$schema"`) editors attach to a config file. Ignored by the lowering. */
+  $schema?: string;
+  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 and handled by
+ * the state's `on` transitions — a decision has no output of its own, so an
+ * `onDone` there is always a config error and is rejected at
+ * `setupAgent.fromConfig(...)` time. `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;
 };
-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;
+/**
+ * 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;
 };
-interface TransitionData {
-    eventType: string;
-    description?: string;
-    guard?: {
-        type: string;
-    };
-    target?: any;
-}
-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;
-}
-interface AgentFeedbackInput {
-    goal?: string;
-    observationId?: string;
-    correlationId?: string;
-    attributes?: Record<string, any>;
-    timestamp?: number;
-    reward?: 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 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 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>;
+type AgentSetupEmittedSchema<TEmittedSchemas extends Record<string, StandardSchemaV1>> = [keyof TEmittedSchemas] extends [never] ? {} : {
+  emitted: TEmittedSchemas;
 };
-interface AgentObservation<TActor extends AnyActorRef> {
-    id: string;
-    prevState: SnapshotFrom<TActor> | undefined;
-    event: EventFrom<TActor>;
-    state: SnapshotFrom<TActor>;
-    machineHash: string | undefined;
-    sessionId: string;
-    timestamp: number;
-}
-interface AgentObservationInput {
-    id?: string;
-    prevState: ObservedState | undefined;
-    event: AnyEventObject;
-    state: ObservedState;
-    machine?: AnyStateMachine;
-    timestamp?: number;
-}
-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;
+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`/`agent.plan` 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/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;
+}
+/**
+ * The version of the {@link AgentTraceEvent} envelope every trace event carries
+ * as `schemaVersion`. Bumped only on a breaking change to the envelope or any
+ * payload shape, so a consumer can gate on it. Emitted identically by
+ * {@link runAgent}, {@link provideExecutors}' `onTrace`, and
+ * {@link traceTransitions}.
+ */
+declare const AGENT_TRACE_SCHEMA_VERSION = 1;
+type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
+  /** The {@link AGENT_TRACE_SCHEMA_VERSION} the event was produced with. */schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
+  runId: string;
+  seq: number;
+  timestamp: string;
+  machineId: string; /** {@link RunAgentOptions.machineVersion} or the machine's structural hash. */
+  machineVersion: string;
+} & ({
+  type: "run.start";
+  input?: InputFrom<TMachine>;
+  snapshot?: Snapshot<unknown>;
+  event?: EventFromLogic<TMachine>;
 } | {
-    type: '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 TextResultMeta = {
-    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>, 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).
+   *
+   * Accepts a function or an observer (`{ next }`), matching `createActor`'s
+   * `inspect` option, so `@statelyai/inspect`'s `inspector.inspect` plugs in
+   * directly.
+   */
+  inspect?: ((inspectionEvent: InspectionEvent) => void) | {
+    next?: (inspectionEvent: InspectionEvent) => void;
+  };
+  /** Caps the number of model/decision calls this run may make (each retry of a decision counts separately); exceeding it settles `{ status: 'error', cause: 'max-model-calls' }`. Default 100. */
+  maxModelCalls?: number;
+  /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
+  signal?: AbortSignal;
+}
+/**
+ * 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>;
 };
-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>;
-}
-type ObservedStateFrom<TActor extends AnyActorRef> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
-type AgentMemoryContext = {
-    observations: AgentObservation<any>[];
-    messages: AgentMessage[];
-    plans: AgentPlan<any>[];
-    feedback: AgentFeedback[];
+/**
+ * Discriminates a {@link RunAgentResult} `error`:
+ * - `'aborted'` — the run's `signal` fired.
+ * - `'max-model-calls'` — the `maxModelCalls` budget was exceeded.
+ * - `'decision-exhausted'` — the machine reached an error state whose error is
+ *   (or wraps) a {@link DecisionExhaustedError} that no `onError` handled.
+ * - `'machine'` — any other machine error state.
+ * - `'stopped'` — the actor was stopped externally (`status === 'stopped'`).
+ */
+type RunAgentErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped";
+/**
+ * The set of string-keyed actor `src`s the machine's own config invokes
+ * (top-level, recursing into child STATES but not into invoked child
+ * machines). {@link provideExecutors} uses it to require an executor only for a
+ * source the machine actually invokes — the always-registered `agent.*`
+ * builtins that go unused must not force their executors to be supplied.
+ * @internal
+ */
+/**
+ * Runs an agent machine to completion or idle: a `createActor` host that
+ * binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/
+ * `DecisionLogic` actor sources, starts (or resumes) the actor, and drives
+ * it until it settles — {@link RunAgentResult} `done | idle | error`. Unlike
+ * the step helpers ({@link initialAgentStep} etc — a pure
+ * transition-at-a-time path for durable hosts), `runAgent` owns a live actor
+ * internally; there is no continuation callback, so **idle always settles**
+ * and the caller resumes explicitly by passing the settled `{ snapshot,
+ * event }` back in. The actor is stopped on every settle path (`done`,
+ * `idle`, and `error` alike) — resume is always by snapshot, never by
+ * holding a reference to a live actor.
+ *
+ * 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 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>;
-}
-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>;
-}
-interface AIAdapter {
-    generateText: typeof generateText;
-    streamText: typeof streamText;
-}
-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 };
+/**
+ * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
+ * {@link RunAgentOptions.inspect}: it filters the raw inspection stream to
+ * `@xstate.transition` events and hands the handler the typed
+ * {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
+ * transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
+ * the manual `event.type === '@xstate.transition'` filtering and the snapshot/
+ * actorRef casts.
+ */
+declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, actorRef: InspectedActorRef) => void): (inspectionEvent: InspectionEvent) => void;
+/**
+ * An xstate `inspect` handler that emits `machine.transition` trace events onto
+ * `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
+ * registry as {@link provideExecutors}' `onTrace`. Pair the two on one actor to
+ * get a single ordered trace stream (request + transition events) for the
+ * uncontrolled path:
+ *
+ * ```ts
+ * const bound = provideExecutors(machine, executors, { onTrace });
+ * const actor = createActor(bound, { inspect: traceTransitions(onTrace) });
+ * ```
+ *
+ * Only ROOT-actor transitions are traced (matching `runAgent`'s
+ * `machine.transition`); child-actor transitions are ignored. Attribute the
+ * event via its envelope `runId`.
+ *
+ * By design this path has NO `run.start`/`run.end` events: `createActor` has no
+ * run boundary the way `runAgent` does, so the stream starts at the actor's
+ * first transition. It also does NOT emit `emit` trace events: in this xstate
+ * build emitted events are delivered through `actor.on(...)`, not the inspection
+ * protocol, so they are not observable from an `inspect` handler — subscribe
+ * with `actor.on('*', ...)` if you need them.
+ */
+declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
+//#endregion
+//#region src/provide-executors.d.ts
+/** Options for {@link provideExecutors}. */
+interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
+  /**
+   * Extra actor-source overrides merged onto the machine BEFORE binding — the
+   * same shape as `machine.provide({ actorSources })`. Use it to supply the
+   * `agent.userInput` handler, a custom non-agent actor, or to shadow an agent
+   * source with your own executor-bound logic. Merged first, so an override
+   * that already carries its own executor is left untouched by the binding pass.
+   */
+  actorSources?: Record<string, AnyActorLogic>;
+  /** Chunk sink threaded to every bound `mode: 'stream'` text source. */
+  onChunk?: (chunk: string) => void;
+  /**
+   * A single ordered stream of request-level trace events
+   * (`request.start`/`request.end`/`request.error`/`stream.chunk`) with the
+   * SAME versioned envelope {@link runAgent} emits. Because one bound machine can
+   * back many concurrent root actors, envelope state (`runId`, monotonic `seq`)
+   * is minted per ROOT actor at runtime — two concurrent actors get distinct
+   * `runId`s and independent `seq`. Pair with {@link traceTransitions} on the
+   * actor's `inspect` to fold `machine.transition` events into the same stream.
+   * Unlike `runAgent` there are NO `run.start`/`run.end` events (no run
+   * boundary).
+   */
+  onTrace?: (event: AgentTraceEvent<TMachine>) => void;
+}
+/**
+ * Binds a machine's agent actor sources to a set of host `executors` in one
+ * call, returning a `machine.provide(...)`-ed copy ready for a plain
+ * `createActor(...)` — the uncontrolled-mode counterpart to {@link runAgent}.
+ * No run loop, no idle settling: the returned machine drives itself, so
+ *
+ * ```ts
+ * const actor = createActor(provideExecutors(machine, { generateText, decide }), { input });
+ * actor.start();
+ * ```
+ *
+ * behaves like a normal XState actor whose agent invokes now reach real models.
+ *
+ * Binding pass over `machine.implementations.actorSources` (after merging
+ * `options.actorSources`):
+ * - `mode: 'generate'` text source → `executors.generateText`
+ * - `mode: 'stream'` text source → `executors.streamText`
+ * - decision / `agent.decide` source → `executors.decide` (snapshot-driven
+ *   candidate events, guard `canTake`, and auto-delivery of the chosen event,
+ *   mirroring `runAgent` but without its model-call counting)
+ * - `agent.plan` source → `executors.decide` (iterated, same semantics)
+ *
+ * Pass `options.onTrace` to observe request-level trace events (identical in
+ * shape to `runAgent`'s); pair it with {@link traceTransitions} on the actor's
+ * `inspect` to also capture `machine.transition` events in the same stream.
+ *
+ * A source that already carries its own executor (`.withExecutor(...)`) is left
+ * as-is. `agent.userInput` is left UNBOUND — an uncontrolled host handles idle
+ * itself, so supply a handler via `options.actorSources` if the machine uses it.
+ * Non-agent actors are untouched.
+ *
+ * Throws at bind time if a source needs an executor kind that `executors` does
+ * not provide.
+ *
+ * v1 does NOT descend into invoked child state machines: a string-keyed child
+ * machine source is left untouched, so a child with its own agent invokes needs
+ * its own `provideExecutors(...)` (or `runAgent`, which does rebind children).
+ */
+declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
+//#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" | "undeclared-event" | "missing-final";
+  severity: AgentLintSeverity;
+  /** State path (`parent.child`) or config pointer (e.g. `(root)`, `context`) the finding is about. */
+  path: string;
+  message: string;
+}
+/** Options for {@link lintAgentMachine}. Reserved for future check selection. */
+interface LintAgentMachineOptions {
+  /** Skip these check codes entirely. */
+  disable?: AgentLintDiagnostic["code"][];
+}
+/**
+ * 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[];
+/** Options for {@link assertAgentMachine}. */
+interface AssertAgentMachineOptions extends LintAgentMachineOptions {
+  /** Also fail on warning-severity findings. Default: errors only. */
+  warnings?: boolean;
+}
+/**
+ * Thrown by {@link assertAgentMachine} when lint finds failing diagnostics.
+ * `diagnostics` holds the findings; the message lists them one per finding,
+ * so a test runner's failure output reads like the CLI's lint report.
+ */
+declare class AgentLintError extends Error {
+  diagnostics: AgentLintDiagnostic[];
+  constructor(machineId: string, diagnostics: AgentLintDiagnostic[]);
+}
+/**
+ * Asserts a machine passes {@link lintAgentMachine}: returns silently when
+ * clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+ * otherwise. Fails on error-severity findings; set `warnings: true` to fail on
+ * warnings too. The one-liner for tests and generation loops:
+ *
+ * @example
+ * ```ts
+ * test('agent machine is structurally sound', () => {
+ *   assertAgentMachine(machine);
+ * });
+ * ```
+ */
+declare function assertAgentMachine(machine: AnyStateMachine, options?: AssertAgentMachineOptions): void;
+/**
+ * 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`).
+ * - `invokes` — output values for scripted invokes (notably `agent.userInput`,
+ *   and any other actor whose output must be canned), keyed by src.
+ */
+interface SimulationScript {
+  text?: Record<string, unknown[]>;
+  decisions?: Record<string, ChosenEvent[]>;
+  invokes?: Record<string, unknown[]>;
+}
+/** 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;
+  };
+}
+/** 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 { AGENT_TRACE_SCHEMA_VERSION, type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventSchemaInput, type AgentEventSchemaInputMap, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentMachine, type AgentMachineConfig, type AgentMessage, type AgentMessageInfo, type AgentModelMap, type AgentModelRef, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentRunMeta, type AgentSchemaPack, type AgentSetupStateSchema, type AgentSnapshotStore, type AgentStateNarrowing, type AgentStateRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEventPattern, type AllowedEvents, type AssertAgentMachineOptions, type AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, type NormalizedEventSchemas, type PendingUserInput, type PlanLogic, type ProvideExecutorsOptions, type ProviderOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextLogicInput, type TextLogicOutput, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, appendMessages, assertAgentMachine, assistantMessage, canReach, createAgentSchemas, createTextLogic, explorePaths, getAcceptedEvents, getAgentMessages, getStateMeta, inspectTransitions, lintAgentMachine, messagesSchema, parseAgentEvent, persistSnapshot, provideExecutors, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage };