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

package/dist/run-agent-DnvtcnTZ.d.cts

@@ -0,0 +1,1111 @@
+import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-QbEfCVny.cjs";
+import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
+import { G as AgentRequestSource, H as AgentEventDescriptor, M as AgentDecisionRequest, N as AgentPlanInput, W as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-BDxwQNsD.cjs";
+import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-Ruq18mGp.cjs";
+import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, ExecutableActionObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, createActor } from "xstate";
+
+//#region src/internal/registry.d.ts
+type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actors"> & {
+  models?: object;
+};
+//#endregion
+//#region src/steps.d.ts
+/**
+ * A pending text request surfaced by step discovery ({@link getAgentRequests}
+ * / {@link AgentStep.requests}): the machine has spawned a
+ * `TextLogic`-backed invoke and is waiting on its result. Resolve it with
+ * {@link executeAgentRequest} (or by hand, then feed the output into
+ * {@link resolveAgentStep} via `xstate.done.actor` + `actorId`).
+ */
+interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
+  kind: "text";
+  id: string;
+  src: AgentRequestSource;
+  mode?: AgentRequestMode;
+  input: TInput;
+  tools: AgentTools;
+  events: AgentEventDescriptor[];
+}
+/**
+ * A pending **plan** request re-surfaced by step discovery: the machine
+ * invoked `agent.plan`, which applies an ordered sequence of legal events
+ * (each one a decision) rather than a single one. Unlike text/decision
+ * requests — surfaced once and resolved once — a plan request **re-surfaces on
+ * every step** while the plan is in flight, its `events`/`applied`/
+ * `stepsRemaining` updated each time, until it terminates.
+ *
+ * All fields are plain serializable data. Resolve ONE decision per step from
+ * `events` (via {@link resolveDecision}, wiring `canTake` to
+ * `snapshot.can` exactly like a single decision) then apply it: a real machine
+ * event advances the plan (the next step re-surfaces this request); the
+ * reserved `agent.plan.done` move, a `stopOn` event, an exhausted budget, or no
+ * legal events completes it (its invoke resolves with `{ steps, stopped }`).
+ * {@link resolveAgentRequests} does all of this natively — one decision (or one
+ * completion) per call.
+ *
+ * The in-progress plan state (`applied` trail + remaining budget) lives in the
+ * plan invoke child's own `createLogic` snapshot `context`
+ * (`children.<id>.snapshot.context`), so it survives a full JSON
+ * `getPersistedSnapshot` → restore round-trip: a host that persists the step
+ * after every event and reloads resumes the plan identically.
+ */
+interface AgentPlanRequest {
+  kind: "plan";
+  /** Durable invoke id of the `agent.plan` invoke. */
+  id: string;
+  /** Invoke src (`'agent.plan'` or a registered plan-logic source name). */
+  src: AgentRequestSource;
+  /** The resolved plan input (`model`/`system`/`prompt`/`allowedEvents`/`stopOn`/`maxSteps`/…). */
+  input: AgentPlanInput;
+  /**
+   * The legal candidates for the NEXT plan step: the currently
+   * snapshot-legal machine events (∩ declared `allowedEvents`) plus the
+   * reserved `agent.plan.done` move.
+   */
+  events: AgentEventDescriptor[];
+  /** The events applied so far in this plan, in order (the trail). */
+  applied: ChosenEvent[];
+  /** How many more events the plan may apply (`maxSteps - applied.length`). */
+  stepsRemaining: number;
+}
+/** `AgentStep.requests` element: a text, decision, or plan request. */
+type AgentStepRequest = AgentRequest | AgentDecisionRequest | AgentPlanRequest;
+/**
+ * Resolves one **text** request against a host's {@link AgentRequestExecutors}
+ * — merges the request's tools, dispatches to `generateText`/`streamText` per
+ * `mode`, and validates the result against the request's `outputSchema` if
+ * present. Accepts either a `kind: 'text'` `AgentEffect` (the thin-loop shape
+ * from `getAgentEffects`) or a legacy {@link AgentRequest} envelope.
+ * **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).
+ */
+/** A `kind: 'text'` `AgentEffect` (structural, to avoid an import cycle with effects.ts). */
+interface TextEffectLike {
+  kind: "text";
+  requestId: string;
+  request: AgentTextRequest;
+  mode?: AgentRequestMode;
+}
+declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
+declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>, options: {
+  verbose: true;
+}): Promise<{
+  output: unknown;
+  raw: unknown;
+}>;
+//#endregion
+//#region src/effects.d.ts
+/**
+ * One thing a host does at the frontier. Effect kinds mirror what a machine
+ * can start in a single transition, each carrying everything the host needs to
+ * run it and to journal its completion so replay is deterministic:
+ *
+ * - `text` — a `TextLogic`/`agent.generateText` invoke. Resolve with the model
+ *   (`executeAgentRequest`), then journal `toDoneEvent(output)` (or
+ *   `toErrorEvent(error)`).
+ * - `decision` — an `agent.decide`/`DecisionLogic` invoke. Resolve with
+ *   `resolveDecision` and journal the CHOSEN machine event directly (a decision
+ *   has no output value of its own; the chosen event advances the machine).
+ * - `plan` — an `agent.plan` invoke (multi-event). Drive it a step at a time
+ *   (see `resolveAgentRequests`), journaling each applied event.
+ * - `task` — any other invoke/spawn: a plain host-run task keyed by `src` +
+ *   `input`. Run it, then journal `toDoneEvent`/`toErrorEvent`.
+ * - `delay` — an `after(...)` timer. Schedule it; when it fires, journal
+ *   `event` (a normal external entry).
+ * - `execute` — a fire-and-forget action (a custom entry action, `sendTo`,
+ *   `cancel`, …). Run `exec()` once at the frontier; NEVER journaled, never
+ *   replayed (replay re-derives it).
+ */
+type AgentEffect = {
+  kind: "text";
+  requestId: string;
+  request: AgentTextRequest; /** `'stream'` when the authored request wants `streamText`; default `'generate'`. */
+  mode?: AgentRequestMode;
+  toDoneEvent(output: unknown): EventObject;
+  toErrorEvent(error: unknown): EventObject;
+} | {
+  kind: "decision";
+  requestId: string;
+  request: AgentDecisionRequest;
+} | {
+  kind: "plan";
+  requestId: string;
+  request: AgentPlanRequest;
+} | {
+  kind: "task";
+  requestId: string;
+  id: string;
+  src: string;
+  input: unknown;
+  toDoneEvent(output: unknown): EventObject;
+  toErrorEvent(error: unknown): EventObject;
+} | {
+  kind: "delay";
+  requestId: string;
+  id: string;
+  delayMs: number; /** The `{ type: 'xstate.timer', id }` event the host journals when the timer fires. */
+  event: EventObject;
+} | {
+  kind: "execute";
+  action: ExecutableActionObject;
+  exec(): void;
+};
+/**
+ * The reserved journal event type of the {@link initEntry} first entry: it
+ * carries the machine `input` so a log replays with no side-channel. Named in
+ * the `agent.*` builtin-actor namespace so it never collides with a machine's
+ * own event vocabulary. Consumed by {@link replay}; never fed to `transition`.
+ */
+declare const AGENT_INIT_EVENT_TYPE: "@agent.init";
+/**
+ * The reserved event type `runAgent` delivers to the running machine after
+ * every settled model call that reported usage — the one seam that puts a
+ * call's tokens in reach of ordinary `context` and guards, so a token budget
+ * is a plain machine transition instead of host bookkeeping.
+ *
+ * Like {@link AGENT_INIT_EVENT_TYPE} it lives in the reserved `@agent.*`
+ * namespace: it can never collide with a machine's own vocabulary, and
+ * `getAcceptedEvents`/`parseAgentEvent` never offer it — a model can neither
+ * be shown it as a decision candidate nor forge one.
+ *
+ * Delivery is opt-in BY CONSTRUCTION: the event is sent only when the live
+ * snapshot can currently take it (i.e. the machine declares an
+ * `'@agent.usage'` transition, usually machine-level `on`). A machine without
+ * one sees no extra transition, no extra trace event, and no extra log entry.
+ * When it IS taken it rides the event log like any other external input, so
+ * events-only recovery (`runAgent({ events })`) replays the folded tokens
+ * without re-calling a model.
+ */
+declare const AGENT_USAGE_EVENT_TYPE: "@agent.usage";
+/**
+ * The payload of the reserved {@link AGENT_USAGE_EVENT_TYPE} event: the
+ * settled call's normalized usage plus enough attribution to bill it (per
+ * model, per request). Every field is JSON-safe, so the event round-trips
+ * through the durable event log unchanged.
+ *
+ * Attribution fields are optional because not every call site has them — a
+ * `getRequests` interpret-pass call reports usage with no invoke identity at
+ * all, and only text requests carry a registered `name`.
+ */
+interface AgentUsageEvent extends EventObject {
+  type: typeof AGENT_USAGE_EVENT_TYPE;
+  /** The settled call's token usage, as reported by the executor. */
+  usage: AgentCallUsage;
+  /** Which kind of request reported it. */
+  kind?: "text" | "decision" | "plan";
+  /** The reporting request's durable invoke id. */
+  id?: string;
+  /** The reporting request's invoke `src`. */
+  src?: string;
+  /** The model ref the request targeted. */
+  model?: string;
+  /** The reporting text request's registered `name`, when it declared one. */
+  name?: string;
+}
+/**
+ * Reads a settled call's token usage off a RAW executor result — the same
+ * normalization `runAgent` applies before it delivers
+ * {@link AGENT_USAGE_EVENT_TYPE}. Returns `undefined` when the executor
+ * reported none.
+ *
+ * The seam for the step-loop path, where the host holds the raw result itself:
+ *
+ * ```ts
+ * const { output, raw } = await executeAgentRequest(effect, executors, { verbose: true });
+ * const usage = getCallUsage(raw);
+ * if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
+ * append(effect.toDoneEvent(output));
+ * ```
+ *
+ * See "Token usage on this path" in docs/steps.md for the full loop.
+ */
+declare function getCallUsage(raw: unknown): AgentCallUsage | undefined;
+/** Options controlling the durable envelope created by {@link createReplayEntry}. */
+interface CreateReplayEntryOptions {
+  /** Explicit machine version; defaults to the machine's structural hash. */
+  machineVersion?: string;
+  /** Stable entry id; defaults to `evt_` plus the zero-padded index. */
+  id?: string;
+  /** RFC 3339 acceptance time; defaults to the current wall clock. */
+  recordedAt?: string;
+  causationId?: string;
+  correlationId?: string;
+  metadata?: Record<string, JsonValue>;
+  /** Omit hashes when recording only a post-snapshot suffix without its prefix. */
+  verification?: boolean;
+}
+/**
+ * Creates a JSON-safe, self-describing entry and records the state/effect
+ * hashes produced after replaying it. `entries` must be the complete prefix.
+ */
+declare function createReplayEntry<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], event: EventObject, options?: CreateReplayEntryOptions): AgentLogEntry;
+/** Reserved first replay entry carrying machine input and verification hashes. */
+declare function initEntry<TMachine extends AnyStateMachine>(machine: TMachine, input?: unknown, options?: CreateReplayEntryOptions): AgentLogEntry;
+/** Options accepted by {@link getAgentEffects} and {@link replay}. */
+interface GetAgentEffectsOptions extends Partial<AgentExecutionOptions> {
+  /**
+   * The journal so far — an `EventObject[]` OR an `AgentLogEntry[]` (both
+   * accepted). Occurrence counts (the `n` in a `requestId`) are derived from
+   * it, so requestIds are stable across replay by construction.
+   */
+  history?: readonly (EventObject | AgentLogEntry)[];
+}
+/**
+ * Maps a transition's ORDERED executable actions (plus the still-owed effects
+ * visible only on the snapshot) into an ordered {@link AgentEffect} list the
+ * host starts at the frontier.
+ *
+ * Ordering is load-bearing: a single transition's actions are emitted in
+ * document order (a custom entry action, a spawn, and a `sendTo` in that order
+ * yield `execute`, then `task`/agent effect, then `execute` — never a
+ * reordered set). Effects visible only on the snapshot (an `agent.plan` that
+ * re-surfaces every step, and children spawned by an EARLIER transition that
+ * have not completed yet — the fan-out / crash-resume case) are appended after
+ * the action-derived effects, deduped by site id.
+ *
+ * Every `requestId` is `${siteId}#${n}`, `n` the 1-based occurrence derived
+ * from `options.history` — so the same log yields identical requestIds on every
+ * replay. XState alpha.24 prunes a child when its matching completion is
+ * folded; the history check also prevents older/restored snapshots from
+ * re-surfacing completed work. A re-entered invoke site instead re-derives
+ * from the action list each fresh entry (so `#2`, `#3`, … stay correct).
+ */
+declare function getAgentEffects(machine: AnyActorLogic, snapshot: AnyMachineSnapshot, actions: readonly ExecutableActionObject[], options?: GetAgentEffectsOptions): AgentEffect[];
+/** The result of a {@link replay}: the final snapshot and the effects still owed. */
+interface ReplayResult<TMachine extends AnyActorLogic> {
+  snapshot: SnapshotFrom<TMachine>;
+  effects: AgentEffect[];
+}
+/** Options for {@link replay}. */
+interface ReplayOptions extends Partial<AgentExecutionOptions> {
+  /**
+   * Machine input, used only when `entries` has no reserved {@link initEntry}
+   * first entry. An init entry (the self-contained log) takes precedence.
+   */
+  input?: unknown;
+  /** Explicit expected machine version; defaults to the structural hash. */
+  machineVersion?: string;
+  /** Check recorded hashes when present; `'strict'` additionally requires them. */
+  verify?: boolean | "strict";
+}
+declare class AgentReplayMachineMismatchError extends AgentError {
+  readonly eventId: string;
+  readonly index: number;
+  readonly expected: {
+    machineId: string;
+    machineVersion: string;
+  };
+  readonly actual: {
+    machineId: string;
+    machineVersion: string;
+  };
+  constructor(eventId: string, index: number, expected: {
+    machineId: string;
+    machineVersion: string;
+  }, actual: {
+    machineId: string;
+    machineVersion: string;
+  });
+}
+declare class AgentReplayDivergenceError extends AgentError {
+  readonly eventId: string;
+  readonly index: number;
+  readonly kind: "state" | "effects" | "missing-verification";
+  readonly expected?: string | undefined;
+  readonly actual?: string | undefined;
+  constructor(eventId: string, index: number, kind: "state" | "effects" | "missing-verification", expected?: string | undefined, actual?: string | undefined);
+}
+/** JSON Patch operation returned by {@link diffEventLogs}. */
+type AgentLogPatchOperation = {
+  op: "add";
+  path: string;
+  value: JsonValue;
+} | {
+  op: "remove";
+  path: string;
+} | {
+  op: "replace";
+  path: string;
+  value: JsonValue;
+};
+interface AgentEffectDiff {
+  added: JsonValue[];
+  removed: JsonValue[];
+  changed: Array<{
+    before: JsonValue;
+    after: JsonValue;
+  }>;
+}
+interface AgentEventLogDiff<TMachine extends AnyStateMachine> {
+  commonPrefix: {
+    length: number;
+    throughEventId?: string;
+  };
+  parentOnly: AgentLogEntry[];
+  forkOnly: AgentLogEntry[];
+  parent: ReplayResult<TMachine>;
+  fork: ReplayResult<TMachine>;
+  stateChanges: AgentLogPatchOperation[];
+  effectChanges: AgentEffectDiff;
+}
+/**
+ * Folds a journal through `initialTransition`/`transition` WITHOUT executing
+ * anything, then returns the final snapshot plus the still-owed effects
+ * ({@link getAgentEffects} of the final frontier, occurrence counts taken from
+ * the whole log). Crash recovery, fork resume, and time travel in one call.
+ *
+ * `entries` is a versioned {@link AgentLogEntry} array. A reserved
+ * {@link initEntry} first envelope carries `{ type: '@agent.init', input }`,
+ * so a complete log replays with no side-channel; when absent,
+ * `options.input` is used instead.
+ * Raised/internal events are never in the journal — replay re-derives them
+ * deterministically from the machine's own logic.
+ */
+declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
+/** Requires and checks every entry's recorded state/effect hashes. */
+declare function verifyReplay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: Omit<ReplayOptions, "verify">): ReplayResult<TMachine>;
+/** Structural event-tail, logical-state, and owed-effect comparison. */
+declare function diffEventLogs<TMachine extends AnyStateMachine>(machine: TMachine, parentEntries: readonly AgentLogEntry[], forkEntries: readonly AgentLogEntry[], options?: ReplayOptions): AgentEventLogDiff<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 AgentIllegalResumeEventError extends AgentError {
+  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 AgentSnapshotVersionMismatchError extends AgentError {
+  readonly from: string;
+  readonly to: string;
+  readonly machineId: string;
+  constructor(from: string, to: string, machineId: string);
+}
+/**
+ * Thrown by {@link generateResult} 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 AgentError {
+  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}, else the machine's own `version`, else its 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}, else the machine's own `version`, else its structural hash. */
+  machineVersion: string;
+} & ({
+  type: "run.start";
+  input?: InputFrom<TMachine>;
+  snapshot?: Snapshot<unknown>;
+  event?: EventFromLogic<TMachine>;
+} | {
+  type: "request.start";
+  request: AgentStepRequest;
+} | {
+  type: "request.end";
+  request: AgentStepRequest;
+  output: unknown;
+  raw: unknown;
+  /** The model's reasoning, lifted off the raw executor result when the
+   * request opted into the structured-output envelope's `reasoning` field.
+   * Present only when the executor surfaced a string `reasoning`. */
+  reasoning?: string;
+  /** This call's token usage, lifted off the raw executor result's `usage`.
+   * Present only when the executor reported it. The run-level total is
+   * {@link RunAgentResult.usage}. */
+  usage?: AgentCallUsage;
+} | {
+  type: "request.error";
+  request: AgentStepRequest;
+  error: unknown;
+} | {
+  type: "stream.chunk";
+  request: AgentRequest;
+  chunk: string;
+} | {
+  type: "machine.transition";
+  snapshot: SnapshotFrom<TMachine>;
+  event: EventFromLogic<TMachine>; /** Durable replay-entry id when this transition corresponds to one. */
+  eventId?: string;
+} | {
+  type: "emit";
+  event: EmittedFrom<TMachine>;
+} | {
+  /** A reserved `@agent.usage` event the run declined to deliver. The
+   * tokens still fold into {@link RunAgentResult.usage}; only the machine
+   * event is dropped. */
+  type: "usage.dropped";
+  event: AgentUsageEvent; /** `'settled'`: the call settled after the run's cycle had resolved. */
+  reason: "settled";
+} | ({
+  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>;
+}));
+/**
+ * The JSON-safe projection of an {@link AgentTraceEvent} produced by
+ * {@link serializeTraceEvent}: the envelope fields are unchanged, and every
+ * payload field that can hold a live object (snapshots, machine events, request
+ * objects, raw SDK results, errors) is narrowed to a {@link JsonValue}. Safe to
+ * hand straight to `JSON.stringify` for a JSONL trace file.
+ */
+type JsonSerializableTraceEvent = {
+  schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
+  runId: string;
+  seq: number;
+  timestamp: string;
+  machineId: string;
+  machineVersion: string;
+} & ({
+  type: "run.start";
+  input?: JsonValue;
+  snapshot?: JsonValue;
+  event?: JsonValue;
+} | {
+  type: "request.start";
+  request: JsonValue;
+} | {
+  type: "request.end";
+  request: JsonValue;
+  output: JsonValue; /** Present only when `includeRaw` was set; the raw executor result, sanitized. */
+  raw?: JsonValue;
+  reasoning?: string; /** Present only when the executor reported it; plain numbers, passed through as-is. */
+  usage?: JsonValue;
+} | {
+  type: "request.error";
+  request: JsonValue;
+  error: JsonValue;
+} | {
+  type: "stream.chunk";
+  request: JsonValue;
+  chunk: string;
+} | {
+  type: "machine.transition";
+  snapshot: JsonValue;
+  event: JsonValue;
+  eventId?: string;
+} | {
+  type: "emit";
+  event: JsonValue;
+} | {
+  type: "usage.dropped";
+  event: JsonValue;
+  reason: "settled";
+} | {
+  type: "run.end";
+  status: "done";
+  output: JsonValue;
+  snapshot: JsonValue;
+} | {
+  type: "run.end";
+  status: "idle";
+  snapshot: JsonValue;
+  pendingUserInputs?: JsonValue;
+  persistedSnapshot?: JsonValue;
+} | {
+  type: "run.end";
+  status: "error";
+  cause: RunAgentErrorCause;
+  error: JsonValue;
+  snapshot: JsonValue;
+});
+/**
+ * Projects an {@link AgentTraceEvent} into a guaranteed JSON-safe envelope —
+ * the form the trace stream is actually sold for (one `JSON.stringify` per line
+ * in a JSONL file). Live values are sanitized rather than trusted:
+ *
+ * - Snapshots (`run.start`, `machine.transition`, `run.end`) go through the
+ *   same JSON round-trip as {@link persistSnapshot}, so what lands on disk is
+ *   what a resume would see.
+ * - `request.end`'s `raw` (a provider SDK object, frequently cyclic) is DROPPED
+ *   unless `includeRaw` is set, in which case it is sanitized like everything
+ *   else.
+ * - Non-serializable values anywhere (functions, symbols, `undefined`, cyclic
+ *   back-references) are dropped; `Error`s become `{ name, message, stack?,
+ *   code? }` instead of `{}`. Nothing throws.
+ *
+ * @example
+ * ```ts
+ * await appendFile('trace.jsonl', JSON.stringify(serializeTraceEvent(event)) + '\n');
+ * ```
+ */
+declare function serializeTraceEvent(event: AgentTraceEvent, options?: {
+  includeRaw?: boolean;
+}): JsonSerializableTraceEvent;
+/**
+ * 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>;
+  /**
+   * A prior `runAgent` result's replayable `events`, copied as the prefix of
+   * this result's event log. Pass this alongside `snapshot` + `event` when
+   * resuming so the next result retains the complete, replayable history;
+   * with a `snapshot` these events are history only (`snapshot` is the live
+   * resume source).
+   *
+   * **Events-only resume:** with NO `snapshot` and a self-contained log (a
+   * reserved `@agent.init` first entry — every log started by `runAgent` from
+   * scratch has one), the resume snapshot is derived by replaying the log:
+   * recorded model/tool results are reused, never re-executed, and a request
+   * that was still in flight when the log ended re-executes idempotently on
+   * restore. This is the crash-recovery path: persist entries via `onEvent`
+   * (or an event-log store) and resume from the log alone.
+   */
+  events?: readonly AgentLogEntry[];
+  /**
+   * 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 AgentIllegalResumeEventError}
+   * 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 the machine's
+   * own `version` (XState's `createMachine({ version })` prop) when set, else
+   * {@link getMachineStructuralHash} of the machine (a structural fingerprint
+   * that changes on any edit). Set `version` on the machine — or this option —
+   * 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 AgentSnapshotVersionMismatchError} 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({ actors })` ahead of the run. */
+  actors?: 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 (with a one-time dev warning suggesting a predicate).
+   * Declare your own signal, e.g. `(s) => s.hasTag('awaiting-review')`.
+   */
+  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 as each new replayable external input is appended to this run's
+   * event log. A fresh run begins with `@agent.init`; raised and other internal
+   * events are excluded. History supplied through {@link events} is not
+   * re-emitted. Purely observational, like {@link onTransition}.
+   */
+  onEvent?: (entry: AgentLogEntry) => 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/sdk`'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` plus a replayable `events` array. 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 RunAgentOutcome<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 RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine> & {
+  /**
+   * Versioned, JSON-safe envelopes around replayable external inputs observed
+   * through this run: machine input, effect completions/failures, user events,
+   * and timer firings. Raised/internal events are excluded because replay
+   * re-derives them. Each entry carries timestamp, machine identity/version,
+   * and strict replay hashes.
+   *
+   * A fresh run starts with `@agent.init`. When resuming from a snapshot, pass
+   * the preceding result's `events` through {@link RunAgentOptions.events} to
+   * retain a self-contained history.
+   */
+  events: AgentLogEntry[];
+  /**
+   * Aggregated model-call usage for THIS run — `modelCalls` plus the token
+   * fields every executor reported (see {@link AgentUsage} for the
+   * partial-sum rule). Present on all three variants: an `idle` or `error`
+   * result accounts for the calls made before the run settled.
+   *
+   * A resumed run counts only its own calls, not the history behind
+   * `snapshot`/`events`.
+   */
+  usage: AgentUsage;
+};
+/**
+ * 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 AgentDecisionExhaustedError} 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.actors` 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>>;
+/**
+ * A long-lived agent session returned by {@link createAgentActor}: the same
+ * engine as {@link runAgent} (executor binding at any depth, the replayable
+ * event log, budgets, traces), but the actor stays alive across idle settles.
+ *
+ * One **cycle** runs from start (or the event that re-opened the session) to
+ * the next quiescence. `settled()` resolves with the current cycle's
+ * {@link RunAgentResult}; after an `idle` settle, sending the actor an event
+ * re-opens the cycle and the next `settled()` call tracks it. The event log
+ * spans the whole session — every turn appends to one replayable history.
+ * `done`, `error`, and external stop are final: the actor stops and every
+ * later `settled()` resolves with that final result.
+ */
+interface AgentActorSession<TMachine extends AnyStateMachine> {
+  /** The live bound actor. Drive it directly: `session.actor.send(event)`. */
+  actor: ReturnType<typeof createActor<TMachine>>;
+  /** The session's replayable event log (live; grows across cycles). */
+  readonly events: readonly AgentLogEntry[];
+  /** Cumulative session usage (all cycles). */
+  usage(): AgentUsage;
+  /** Resolves with the current cycle's settled result (`done | idle | error`). */
+  settled(): Promise<RunAgentResult<TMachine>>;
+  /** Stops the actor. A not-yet-settled cycle settles `error`/`stopped`. */
+  stop(): void;
+}
+/**
+ * Session mode: {@link runAgent}'s engine with a long-lived actor. Use it when
+ * the agent is a *session* fed by external events (chat turns, device or
+ * timer events, a socket) rather than a one-shot job — you keep the log,
+ * budget, traces, and idle semantics that bare `provideExecutors` +
+ * `createActor` would forfeit.
+ *
+ * ```ts
+ * const session = createAgentActor(machine, { input, executors });
+ * let result = await session.settled();          // first quiescence
+ * while (result.status === "idle") {
+ *   session.actor.send(await nextUserEvent(result.snapshot));
+ *   result = await session.settled();            // next quiescence, same log
+ * }
+ * session.stop();
+ * ```
+ *
+ * Accepts the same options as {@link runAgent} (including `snapshot`/`events`
+ * resume). Not yet supported in session mode: `getRequests` re-interpretation
+ * across cycles behaves per-cycle exactly as in `runAgent`.
+ */
+declare function createAgentActor<TMachine extends AnyStateMachine>(machine: TMachine, options: RunAgentOptions<TMachine>): AgentActorSession<TMachine>;
+/**
+ * The resolved value of {@link generateResult}: the `done`-narrowed
+ * {@link RunAgentResult} — `output` plus run metadata (`snapshot`, replayable
+ * `events`, aggregated `usage`), mirroring how the AI SDK's `generateText`
+ * resolves `text` alongside its call metadata.
+ */
+type GenerateResult<TMachine extends AnyStateMachine> = Extract<RunAgentResult<TMachine>, {
+  status: "done";
+}>;
+/**
+ * Runs an agent machine to a **final state**, for run-to-done flows where an
+ * idle pause is unexpected. Wraps {@link runAgent}:
+ *
+ * - `done` → resolves with the done result: `result.output` (the machine's
+ *   `OutputFrom`) plus metadata — `result.snapshot`, the replayable
+ *   `result.events`, and the aggregated `result.usage` — the same shape
+ *   `generateText` users expect (`text` + call metadata).
+ * - `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 `generateResult` when the
+ * machine is meant to run straight through to a final state.
+ */
+declare function generateResult<TMachine extends AnyStateMachine>(machine: TMachine, options: RunAgentOptions<TMachine>): Promise<GenerateResult<TMachine>>;
+/**
+ * The actor handed to an {@link inspectTransitions} handler: an
+ * {@link AnyActorRef} widened with the runtime `id`/`src` used to attribute a
+ * transition to the root machine or a specific invoked child (xstate's static
+ * `ActorRef` type omits them, but they are always present at runtime).
+ */
+type InspectedActorRef = AnyActorRef & {
+  id: string;
+  src?: string | AnyActorLogic;
+};
+/**
+ * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
+ * {@link RunAgentOptions.inspect}: it filters the raw inspection stream to
+ * `@xstate.transition` events and hands the handler the typed
+ * {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
+ * transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
+ * the manual `event.type === '@xstate.transition'` filtering and the snapshot/
+ * actorRef casts.
+ */
+declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, actorRef: InspectedActorRef) => void): (inspectionEvent: InspectionEvent) => void;
+/**
+ * An xstate `inspect` handler that emits `machine.transition` trace events onto
+ * `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
+ * registry as {@link provideExecutors}' `onTrace`. Pair the two on one actor to
+ * get a single ordered trace stream (request + transition events) for the
+ * uncontrolled path:
+ *
+ * ```ts
+ * const bound = provideExecutors(machine, executors, { onTrace });
+ * const actor = createActor(bound, { inspect: traceTransitions(onTrace) });
+ * ```
+ *
+ * Only ROOT-actor transitions are traced (matching `runAgent`'s
+ * `machine.transition`); child-actor transitions are ignored. Attribute the
+ * event via its envelope `runId`.
+ *
+ * By design this path has NO `run.start`/`run.end` events: `createActor` has no
+ * run boundary the way `runAgent` does, so the stream starts at the actor's
+ * first transition. It also does NOT emit `emit` trace events: in this xstate
+ * build emitted events are delivered through `actor.on(...)`, not the inspection
+ * protocol, so they are not observable from an `inspect` handler — subscribe
+ * with `actor.on('*', ...)` if you need them.
+ */
+declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
+//#endregion
+export { AgentReplayDivergenceError as A, getCallUsage as B, AgentStateRequest as C, AgentEffectDiff as D, AgentEffect as E, ReplayOptions as F, AgentRequest as G, replay as H, ReplayResult as I, AgentStepRequest as K, createReplayEntry as L, AgentUsageEvent as M, CreateReplayEntryOptions as N, AgentEventLogDiff as O, GetAgentEffectsOptions as P, diffEventLogs as R, traceTransitions as S, AGENT_USAGE_EVENT_TYPE as T, verifyReplay as U, initEntry as V, AgentPlanRequest as W, createAgentActor as _, AgentMessageInfo as a, runAgent as b, AgentTraceEvent as c, InspectedActorRef as d, JsonSerializableTraceEvent as f, RunAgentResult as g, RunAgentOptions as h, AgentIllegalResumeEventError as i, AgentReplayMachineMismatchError as j, AgentLogPatchOperation as k, AgentUserInputExecutor as l, RunAgentErrorCause as m, AgentActorSession as n, AgentRunMeta as o, PendingUserInput as p, executeAgentRequest as q, AgentIdleError as r, AgentSnapshotVersionMismatchError as s, AGENT_TRACE_SCHEMA_VERSION as t, GenerateResult as u, generateResult as v, AGENT_INIT_EVENT_TYPE as w, serializeTraceEvent as x, inspectTransitions as y, getAgentEffects as z };