@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.23

package/dist/run-agent-0fpEZ1wJ.d.mts

@@ -1,1098 +0,0 @@
-import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-CvWRGFxP.mjs";
-import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { N as AgentDecisionRequest, U as AgentRequestOptions, V as AgentEventDescriptor, W as AgentRequestSource, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-DhfFWzu9.mjs";
-import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-hrA1vqtN.mjs";
-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/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).
- * - `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: "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";
-  /** 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;
-}
-/** 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 (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;
-}
-declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): 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/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[];
-}
-/** `AgentStep.requests` element: a text or decision request. */
-type AgentStepRequest = AgentRequest | AgentDecisionRequest;
-/**
- * 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 step-path shape
- * from `getAgentEffects`) or an {@link AgentRequest} envelope.
- * **Text-only**: passing a `kind: 'decision'` request throws, directing the
- * caller to `resolveDecision(request, executors, ...)` instead. Always
- * returns both the normalized `output` and 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(requestOrEffect: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<{
-  output: unknown;
-  raw: unknown;
-}>;
-//#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). Always enforced; there is no opt-out.
- */
-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 the machine's own
- * `version` (XState's `createMachine({ version })`) or, when unversioned, 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;
-  /** 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; /** 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>;
-}));
-/**
- * Fields a JSON projection keeps VERBATIM: {@link TRACE_ENVELOPE_KEYS} (the
- * envelope, the `type`/`status`/`cause` discriminants, and the payload fields
- * that are already plain strings) plus `usage.dropped`'s `reason`, which is a
- * string literal — sanitizing it is the identity, so it keeps its literal type.
- * Every other payload field narrows to {@link JsonValue}. @internal
- */
-type TraceVerbatimKey = (typeof TRACE_ENVELOPE_KEYS)[number] | "reason";
-/** One trace variant's JSON projection. Homomorphic, so `?` modifiers survive. @internal */
-type JsonProjectedTraceVariant<TEvent> = { [K in keyof TEvent]: K extends TraceVerbatimKey ? TEvent[K] : JsonValue };
-/**
- * `raw` is written only when `includeRaw` was set, so it is optional on the
- * JSON side even though the live trace always carries it. @internal
- */
-type WithOptionalRaw<T> = "raw" extends keyof T ? Omit<T, "raw"> & {
-  raw?: JsonValue;
-} : T;
-/**
- * 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.
- *
- * DERIVED from {@link AgentTraceEvent}, so a new trace variant cannot silently
- * miss the JSON side. `src/serialize-trace-event.test.ts` pins the result to
- * the shape this type had when it was hand-maintained.
- */
-type JsonSerializableTraceEvent = AgentTraceEvent extends infer TEvent ? TEvent extends unknown ? WithOptionalRaw<JsonProjectedTraceVariant<TEvent>> : never : never;
-declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "timestamp", "machineId", "machineVersion", "type", "status", "cause", "eventId", "reasoning", "chunk"];
-/**
- * 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 `machine.getPersistedSnapshot(...)`, 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. Validated against the machine's declared input schema —
-   * defaults filled, transforms applied — before it reaches
-   * `createActor(machine, { input })` and the replayable event log; invalid
-   * input throws an {@link AgentError} with code `invalid-machine-input`.
-   * Typed as {@link AgentInputFrom}, so fields the schema defaults are optional
-   * here. Omit when resuming via `snapshot`.
-   */
-  input?: AgentInputFrom<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 `snapshot` whose stamped `agentMeta.version` differs
-   * from the current machine's `version` (XState's `createMachine({ version })`
-   * prop — the single source of truth; an unversioned machine falls back to its
-   * {@link getMachineStructuralHash}). `'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.
-   *
-   * Prefer XState's own `createMachine({ version, migrate })` hook when the
-   * migration belongs to the machine: a machine that declares `migrate` is left
-   * to xstate, and runAgent neither throws nor rewrites the snapshot's version
-   * before restore. This option stays for host-owned migrations (a machine you
-   * do not control, or a migration that needs run-scoped context).
-   */
-  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({ isIdle })`
-   * → the timing heuristic (when neither is present). When the resolved
-   * predicate returns true and nothing is in flight (no live requests/
-   * 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')`.
-   */
-  isIdle?: (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. The
-   * shipped prompts-in-descriptions recipe is {@link getSnapshotRequests}:
-   *
-   * ```ts
-   * getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
-   * ```
-   *
-   * Reach for {@link getSnapshotNodes} when you want to build requests some
-   * other way — between them, host code never touches `snapshot._nodes`.
-   *
-   * 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[]);
-  /**
-   * Sugar over {@link onTrace}'s `stream.chunk` events: 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;
-  /**
-   * Sugar over {@link onTrace}'s `request.end` events: 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;
-  /**
-   * Sugar over {@link onTrace}'s `machine.transition` events: fires on every
-   * root-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). Default 100. The overrun is thrown into the
-   * invoke that would have made the call, as an
-   * {@link AgentMaxModelCallsExceededError} with `code: 'max-model-calls'` — so
-   * an `onError` can branch on it and route to a degraded state. Unhandled, it
-   * settles `{ status: 'error', cause: 'max-model-calls' }`.
-   */
-  maxModelCalls?: number;
-  /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
-  signal?: AbortSignal;
-}
-/**
- * One active state node of a snapshot, as {@link getSnapshotRequests} and
- * {@link getSnapshotNodes} surface it: the prompt-bearing `description`, the
- * `tags` a recipe branches on, the state `meta`, and `ownEvents` (the event
- * types this node itself declares transitions for). The shape hosts used to
- * reach for through the private `snapshot._nodes` array.
- */
-interface AgentSnapshotNode {
-  /** The node's full id (e.g. `writer.drafting`). */
-  id: string;
-  /** The node's own key (e.g. `drafting`). */
-  key: string;
-  /** The node's `description` — the prompt, in the prompts-in-descriptions recipe. */
-  description?: string;
-  tags: string[];
-  meta?: unknown;
-  /** Event types this node declares transitions for (xstate's `ownEvents`). */
-  ownEvents: string[];
-  /** True when the node has no child states. */
-  leaf: boolean;
-}
-/**
- * The active state nodes of a snapshot, as plain {@link AgentSnapshotNode}
- * descriptors. The escape hatch under {@link getSnapshotRequests}: use it when
- * your `getRequests` hook needs to build requests some other way, so host code
- * never touches xstate's private `snapshot._nodes`.
- */
-declare function getSnapshotNodes(snapshot: AnyMachineSnapshot): AgentSnapshotNode[];
-/** Options for {@link getSnapshotRequests}. */
-interface GetSnapshotRequestsOptions {
-  /** Executor model name every produced request carries. */
-  model: string;
-  /**
-   * Which active nodes produce a request. Default: every node with a
-   * `description` that is NOT tagged `'waiting'` (a human-wait state settles
-   * idle instead).
-   */
-  filter?: (node: AgentSnapshotNode) => boolean;
-  /**
-   * Shapes (or drops, by returning `undefined`) each node's request before it
-   * is returned — set `system`, `allowedEvents`, a custom `onDone`, …
-   */
-  map?: (request: AgentStateRequest, node: AgentSnapshotNode) => AgentStateRequest | undefined;
-}
-/**
- * Builds the {@link AgentStateRequest}s for a snapshot straight from its active
- * state nodes — the prompts-in-descriptions recipe as a function, so a
- * {@link RunAgentOptions.getRequests} hook is one line and never reaches into
- * xstate's private `snapshot._nodes`:
- *
- * ```ts
- * runAgent(machine, {
- *   executors,
- *   getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
- * });
- * ```
- *
- * Each described active node becomes one request: `prompt` from the node's
- * `description`, `kind: 'decision'` when it is tagged `'decision'`, `system`
- * from `meta.role` when present, `allowedEvents` scoped to the node's own
- * events, and an explicit `onDone` when the node has exactly one own event
- * (single-outcome states advance deterministically; anything else falls
- * through to a `decide` call). Nodes tagged `'waiting'` produce nothing, so the
- * run settles idle for a human. Override any of it with `filter`/`map`.
- */
-declare function getSnapshotRequests(snapshot: AnyMachineSnapshot, options: GetSnapshotRequestsOptions): AgentStateRequest[];
-/**
- * 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[];
-  /**
-   * The JSON-serializable persisted snapshot (in-flight children included,
-   * WITH their own state). Persist THIS one and resume with
-   * `runAgent(machine, { snapshot: persistedSnapshot, ... })` — the live
-   * `snapshot` above cannot round-trip active children, so resuming from
-   * it restarts every invoked child from scratch.
-   */
-  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";
-/**
- * Thrown into the invoke that would have made the call once
- * {@link RunAgentOptions.maxModelCalls} is spent. It reaches the machine
- * through the normal error channel, so an invoke's `onError` can branch on it
- * (`error.code === 'max-model-calls'`, the same string the settled result's
- * `cause` uses) and route to a degraded/finish state instead of failing the
- * run. Unhandled, it settles `{ status: 'error', cause: 'max-model-calls' }`.
- *
- * ```ts
- * onError: [
- *   { guard: ({ event }) => event.error?.code === 'max-model-calls', target: 'budgetSpent' },
- *   { target: 'failed' },
- * ]
- * ```
- */
-declare class AgentMaxModelCallsExceededError extends AgentError {
-  /** The budget that was exceeded (`options.maxModelCalls`). */
-  readonly maxModelCalls: number;
-  constructor(maxModelCalls: number);
-}
-/**
- * The machine input a run accepts, which is the schema's *pre*-validation side.
- *
- * XState's `schemas` are types only — it never validates, and it resolves
- * `schemas.input` to one type shared by `createActor`'s `input` option and the
- * `context: ({ input })` factory. A schema field declared with a default
- * therefore reads as required at the call site even though the caller is meant
- * to omit it. `setupAgent` brands the machine's input type with its own schema
- * ({@link WithAgentInputSchema}), so this recovers the looser caller-facing
- * side while the factory keeps seeing the validated one. Machines with no
- * declared input schema — and machines reached through `.provide(...)`, which
- * drops the brand — fall back to xstate's `InputFrom`.
- */
-type AgentInputFrom<TMachine extends AnyStateMachine> = [NonNullable<InputFrom<TMachine>>] extends [WithAgentInputSchema<infer TInputSchema>] ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
-/**
- * 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 { AgentRequest as A, AgentReplayMachineMismatchError as B, getSnapshotNodes as C, serializeTraceEvent as D, runAgent as E, AgentEffect as F, ReplayResult as G, CreateReplayEntryOptions as H, AgentEffectDiff as I, getAgentEffects as J, createReplayEntry as K, AgentEventLogDiff as L, executeAgentRequest as M, AGENT_INIT_EVENT_TYPE as N, traceTransitions as O, AGENT_USAGE_EVENT_TYPE as P, AgentLogPatchOperation as R, generateResult as S, inspectTransitions as T, GetAgentEffectsOptions as U, AgentUsageEvent as V, ReplayOptions as W, replay as X, initEntry as Y, PendingUserInput as _, AgentInputFrom as a, RunAgentResult as b, AgentRunMeta as c, AgentTraceEvent as d, AgentUserInputExecutor as f, JsonSerializableTraceEvent as g, InspectedActorRef as h, AgentIllegalResumeEventError as i, AgentStepRequest as j, AgentStateRequest as k, AgentSnapshotNode as l, GetSnapshotRequestsOptions as m, AgentActorSession as n, AgentMaxModelCallsExceededError as o, GenerateResult as p, diffEventLogs as q, AgentIdleError as r, AgentMessageInfo as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentSnapshotVersionMismatchError as u, RunAgentErrorCause as v, getSnapshotRequests as w, createAgentActor as x, RunAgentOptions as y, AgentReplayDivergenceError as z };