@statelyai/agent 2.0.0-alpha.24 → 2.0.0-alpha.25

package/dist/testing.d.cts

@@ -0,0 +1,602 @@
+import { u as ChosenEvent } from "./types-B1Qs2q3q.cjs";
+import { Z as AgentError, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BFEOxyxv.cjs";
+import { d as RunAgentOptions, f as RunAgentResult } from "./run-agent-BOfoJg5B.cjs";
+import { _ as ScriptedExecutorsScript, g as ScriptedExecutors, h as ScriptedDecisionValue, m as ScriptedDecisionEntry, p as ScriptedByName, t as MetaOfSnapshot, v as ScriptedTextEntry, y as createScriptedExecutors } from "./utils-RalRn9sk.cjs";
+import { AnyMachineSnapshot, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
+
+//#region src/verify.d.ts
+/** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
+type AgentLintSeverity = "error" | "warning";
+/**
+ * One static-analysis finding from {@link lintAgentMachine}. `code` names the
+ * check (stable, machine-readable), `path` points at the offending state path
+ * or config location, and `message` explains the problem and its remedy.
+ */
+interface AgentLintDiagnostic {
+  code: "decide-without-events" | "direct-object-src" | "invoke-without-on-error";
+  severity: AgentLintSeverity;
+  /** State path (`parent.child`) or config pointer (e.g. `(root)`, `context`) the finding is about. */
+  path: string;
+  message: string;
+}
+/** Options for {@link lintAgentMachine}. */
+interface LintAgentMachineOptions {
+  /** Skip these check codes entirely. */
+  disable?: AgentLintDiagnostic["code"][];
+  /**
+   * Throw {@link AgentLintError} on failing diagnostics instead of returning
+   * them. Fails on error-severity findings; add `warnings: true` to fail on
+   * warnings too.
+   */
+  throw?: boolean;
+  /** With `throw: true`, also fail on warning-severity findings. Default: errors only. */
+  warnings?: boolean;
+}
+/**
+ * Runs static structural checks over a built agent machine and returns the
+ * findings ({@link AgentLintDiagnostic}[], empty when clean). Works for
+ * TS-authored (`setupAgent(...).createMachine(...)`) and
+ * `setupAgent.fromConfig(...)`-compiled machines alike, reading `machine.config`
+ * plus the schemas/actor sources the library already retains per machine.
+ *
+ * No model calls, no API keys — a coding agent that emits an agent machine can
+ * call this to catch agent-specific mistakes such as undeliverable decisions,
+ * un-rebindable request sources, and an unhandled transcript event. General
+ * state-machine lint belongs to XState tooling.
+ *
+ * Pass `{ throw: true }` for the one-liner form used in tests and generation
+ * loops: it returns silently when the machine is clean and throws
+ * {@link AgentLintError} (findings on `.diagnostics`) on error-severity
+ * findings, or on warnings too with `{ throw: true, warnings: true }`.
+ *
+ * @example
+ * ```ts
+ * const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
+ * if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
+ * ```
+ *
+ * @example Throwing form
+ * ```ts
+ * test('agent machine is structurally sound', () => {
+ *   lintAgentMachine(machine, { throw: true });
+ * });
+ * ```
+ */
+declare function lintAgentMachine(machine: AnyStateMachine, options?: LintAgentMachineOptions): AgentLintDiagnostic[];
+/**
+ * Thrown by `lintAgentMachine(machine, { throw: true })` (and its
+ * {@link assertAgentMachine} alias) when lint finds failing diagnostics.
+ * `diagnostics` holds the findings; the message lists them one per finding,
+ * so a test runner's failure output reads like the CLI's lint report.
+ */
+declare class AgentLintError extends AgentError {
+  readonly diagnostics: AgentLintDiagnostic[];
+  constructor(machineId: string, diagnostics: AgentLintDiagnostic[]);
+}
+/** Options for {@link assertAgentMachine}. */
+interface AssertAgentMachineOptions extends LintAgentMachineOptions {
+  /** Also fail on warning-severity findings. Default: errors only. */
+  warnings?: boolean;
+}
+/**
+ * Asserts a machine passes {@link lintAgentMachine}: returns silently when
+ * clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+ * otherwise — sugar for `lintAgentMachine(machine, { ...options, throw: true })`.
+ * Fails on error-severity findings; set `warnings: true` to fail on warnings
+ * too. The one-liner for tests and generation loops:
+ *
+ * @example
+ * ```ts
+ * test('agent machine is structurally sound', () => {
+ *   assertAgentMachine(machine);
+ * });
+ * ```
+ */
+declare function assertAgentMachine(machine: AnyStateMachine, options?: AssertAgentMachineOptions): void;
+/**
+ * Scripted responses for a {@link simulateAgent} playthrough. Each channel is a
+ * by-`src` map of FIFO queues, consumed in the order the machine reaches the
+ * requests:
+ * - `text` — output values for text requests, keyed by request src (the
+ *   `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`).
+ * - `decisions` — the {@link ChosenEvent} to apply for a decision request,
+ *   keyed by decision src (usually `agent.decide`). An invoke whose src is an
+ *   inline logic object has only an auto-generated src, so its queue may be
+ *   keyed by the invoke's `id` instead.
+ * - `invokes` — output values for scripted invokes (any actor whose output must
+ *   be canned), keyed by src.
+ * - `errors` — failure values to reject a request or invoke with instead of
+ *   resolving it, keyed by the same srcs the other channels use. An entry here
+ *   is consumed BEFORE that src's output queue, so a script can fail the first
+ *   call and let the second succeed. The invoke is rejected with
+ *   {@link rejectAgentStep}, so the machine takes its `onError`; for
+ *   `agent.decide` the entry stands in for retry exhaustion. A value can be
+ *   anything — an `Error`, a string, or an object such as `{ code: 'truncated' }`
+ *   for a machine that branches on `event.error.code`.
+ * - `events` — a flat FIFO queue of external (human/host-sent) events. When the
+ *   machine settles idle with no pending request or invoke — a human gate — the
+ *   next queued event is applied, so a simulation can cross states that a live
+ *   run crosses via `actor.send(...)`. An event the current state cannot take
+ *   (no handler, or guard-rejected) throws rather than silently vanishing.
+ */
+interface SimulationScript {
+  text?: Record<string, unknown[]>;
+  decisions?: Record<string, ChosenEvent[]>;
+  invokes?: Record<string, unknown[]>;
+  errors?: Record<string, unknown[]>;
+  events?: ChosenEvent[];
+}
+/**
+ * One entry in a {@link SimulateAgentResult.trail}: the state after this step,
+ * plus what drove the step. The first entry is always the machine's initial
+ * state, with no `appliedEvent`/`resolvedRequest` — so `trail.map((e) =>
+ * e.state)` is the complete state path, directly comparable with
+ * `matchesTrajectory` without prepending the initial state by hand.
+ */
+interface SimulationTrailEntry {
+  /** The machine state value after applying this step. */
+  state: unknown;
+  /** The chosen event applied (for a decision request), or the external event applied (when `external`). */
+  appliedEvent?: ChosenEvent;
+  /** True when `appliedEvent` came from the script's `events` queue (an external/user event), not a decision. */
+  external?: boolean;
+  /**
+   * Scripted decisions that failed validation (unknown event, invalid payload,
+   * or guard-rejected — live-run retry parity, see {@link simulateAgent})
+   * before this step settled. Present with an `appliedEvent` when a later
+   * scripted attempt succeeded, or alone when every attempt failed and the
+   * exhaustion error was routed through the decision invoke's `onError`.
+   */
+  rejectedEvents?: ChosenEvent[];
+  /**
+   * The request this step settled (a text, decision, or scripted invoke): its
+   * kind, src, and how it settled. `outcome` is `'output'` when a scripted
+   * output resolved it and `'error'` when a `script.errors` entry rejected it,
+   * in which case `error` carries the scripted failure value.
+   */
+  resolvedRequest?: {
+    kind: "text" | "invoke" | "decision";
+    src: string;
+    id: string;
+    outcome: "output" | "error";
+    error?: unknown;
+  };
+}
+/** Options for {@link simulateAgent}. */
+interface SimulateAgentOptions {
+  input?: unknown;
+  script: SimulationScript;
+  /** Max steps before returning `'exhausted'`. Default 100. */
+  maxSteps?: number;
+}
+/** The outcome of a {@link simulateAgent} playthrough. */
+interface SimulateAgentResult {
+  /** `'done'` = reached a final state; `'idle'` = paused with no pending work; `'exhausted'` = hit `maxSteps`. */
+  status: "done" | "idle" | "exhausted";
+  snapshot: AnyMachineSnapshot;
+  trail: SimulationTrailEntry[];
+}
+/**
+ * Deterministically plays a machine through, resolving each request from a
+ * {@link SimulationScript} instead of a model — no API keys, no model calls.
+ * Runs on the pure step path ({@link initialAgentStep} etc.), so it exercises
+ * the real transition logic. Returns the terminal `status`, final `snapshot`,
+ * and a `trail` of every step taken.
+ *
+ * Decisions run through the live run's own validation/retry core,
+ * {@link resolveDecision}, with the script standing in for the model: each
+ * attempt consumes the next queued {@link ChosenEvent} for that src, so an
+ * unknown, payload-invalid, or guard-rejected event is NOT silently swallowed
+ * — the next queued decision is tried, exactly as a live run re-asks the
+ * model. The decision logic's `maxRetries` caps attempts as it would live;
+ * when retries continue past the end of the queue, the last queued decision
+ * repeats (a scripted model that insists). The repeat applies only within one
+ * decision request's retries — each new decision request must have its own
+ * queued entry, or the dry-script error throws as usual. Exhausting all
+ * attempts delivers
+ * the resulting {@link AgentDecisionExhaustedError} to the machine as the
+ * decision invoke's error (so an `onError` transition observes it, as it
+ * would live); with no `onError` to catch it, it is thrown.
+ *
+ * Throws a descriptive error when the script runs dry mid-request, naming the
+ * pending request's kind, src, and id so the missing scripted response is
+ * obvious.
+ *
+ * @example
+ * ```ts
+ * const { status, snapshot } = simulateAgent(machine, {
+ *   input: { topic: 'state machines' },
+ *   script: {
+ *     decisions: { 'agent.decide': [{ type: 'ESCALATE' }] },
+ *     events: [{ type: 'APPROVE' }], // crosses the human gate
+ *   },
+ * });
+ * ```
+ */
+declare function simulateAgent(machine: AnyStateMachine, options: SimulateAgentOptions): Promise<SimulateAgentResult>;
+/** Options for {@link explorePaths}. */
+interface ExplorePathsOptions {
+  input?: unknown;
+  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
+  maxDepth?: number;
+  /** Total path cap before exploration stops (reported via `hitPathCap`). Default 200. */
+  maxPaths?: number;
+  /**
+   * Canned output for each text request, keyed by src (the
+   * `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`).
+   * One value per src, reused every time that src is reached. A missing src
+   * halts that branch with a `needs-output` terminal.
+   */
+  text?: Record<string, unknown>;
+  /** Canned output for scripted invokes, keyed by src. Same one-value-per-src rule as `text`. */
+  invokes?: Record<string, unknown>;
+  /**
+   * A canned failure per src, keyed like `text`/`invokes`. A src listed here
+   * forks an extra branch at that invoke, where the invoke is rejected and the
+   * machine takes its `onError` — so states reachable only through a failure
+   * are explored. When the src also has an output, both branches are explored;
+   * when it has only an error, only the failing one is. Each fork counts
+   * against `maxDepth`, and the failing branch records
+   * `{ type: 'xstate.error.actor.<id>' }` in the path.
+   *
+   * A decision invoke can be keyed here too — by its src (usually
+   * `agent.decide`) or by its invoke id — standing in for retry exhaustion.
+   * Its success branch is the usual per-candidate-event fork, so the failing
+   * branch is explored in addition to, not instead of, the candidates.
+   *
+   * A rejection that reaches no `onError` errors the machine, and that path
+   * ends in an `error` terminal.
+   */
+  errors?: Record<string, unknown>;
+}
+/** A single explored path's terminal outcome. */
+interface AgentPathTerminal {
+  /**
+   * `'error'` is a scripted failure the machine had no `onError` for: the
+   * snapshot is errored, exactly as a live run's unhandled invoke failure.
+   */
+  status: "done" | "idle" | "needs-output" | "max-depth" | "error";
+  /** The chosen/applied events, in order, that produced this terminal. */
+  path: ChosenEvent[];
+  /** The final state value on this path. */
+  state: unknown;
+  /** For `needs-output`: the src whose canned output was missing. */
+  missingSrc?: string;
+  /** For `error`: the failure value that errored the machine. */
+  error?: unknown;
+}
+/** The report returned by {@link explorePaths}. */
+interface AgentPathReport {
+  /** Every distinct state value (JSON) encountered across all explored paths. */
+  reachedStates: unknown[];
+  /** One entry per explored path. */
+  terminals: AgentPathTerminal[];
+  /** How many candidate events were pruned because a guard rejected them. */
+  prunedByGuard: number;
+  /** Notes about coverage the exploration could not complete (missing outputs, depth/path caps). */
+  unexplored: string[];
+  /** Total paths explored. */
+  pathsExplored: number;
+  /** True when the total-paths cap was hit (report is partial). */
+  hitPathCap: boolean;
+}
+/**
+ * Enumerates a machine's decision and external-event branches to a bounded
+ * depth, model-free, and reports which states are reached and how each path
+ * terminates. At each decision request it forks one branch per candidate event
+ * (guard-rejected candidates are counted in `prunedByGuard`, not explored); at
+ * an idle wait it forks per externally-accepted event. Text requests resolve
+ * from `text`, other invokes from `invokes` — all by-src canned-output maps, and a missing src halts
+ * that branch with a `needs-output` terminal rather than throwing. A src in
+ * `errors` forks an extra branch where that invoke is rejected, so states
+ * behind an `onError` are explored too.
+ *
+ * Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
+ * 200, reported via `hitPathCap`).
+ *
+ * @example
+ * ```ts
+ * const report = await explorePaths(refundMachine, { input: { request: 'x', amount: 5000 } });
+ * // report.terminals → both 'refunded' and 'denied'; report.prunedByGuard → 1
+ * ```
+ */
+declare function explorePaths(machine: AnyStateMachine, options?: ExplorePathsOptions): Promise<AgentPathReport>;
+/** The result of a {@link canReach} query. */
+interface CanReachResult {
+  /** True when the target state was reached within the exploration bounds. */
+  reachable: boolean;
+  /** Resolved XState state-node id for a string target. */
+  target?: string;
+  /** When reachable, the sequence of chosen/applied events that gets there. */
+  witness?: ChosenEvent[];
+}
+/** Thrown when a string reachability target is not a state in the machine. */
+declare class AgentUnknownStateError extends AgentError {
+  readonly target: string;
+  constructor(machineId: string, target: string);
+}
+/**
+ * Answers "can the machine reach this?" by exploring its branches (a thin
+ * wrapper over {@link explorePaths}). The target is either a state path string
+ * (`snapshot.matches(...)` semantics) or a snapshot predicate — the predicate
+ * form checks any property (a context invariant, a tag, a state+context
+ * combination) without reifying a sentinel state for it. Returns
+ * `{ reachable: true, witness }` with the event sequence that reaches it, or
+ * `{ reachable: false }`.
+ *
+ * @example
+ * ```ts
+ * const { reachable, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+ * // reachable → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+ * ```
+ *
+ * @example Predicate target — a violation property, no sentinel state needed
+ * ```ts
+ * const violation = await canReach(
+ *   refundMachine,
+ *   (snapshot) => snapshot.matches('issued') && !snapshot.context.approved,
+ *   { input: { amount: 5000 } },
+ * );
+ * // violation.reachable → false is the safety proof
+ * ```
+ */
+declare function canReach(machine: AnyStateMachine, target: string | ((snapshot: AnyMachineSnapshot) => boolean), options?: ExplorePathsOptions): Promise<CanReachResult>;
+//#endregion
+//#region src/trajectory.d.ts
+/** An event-shaped trajectory item: anything with a string `type`. */
+interface TrajectoryEvent {
+  type: string;
+  [key: string]: unknown;
+}
+/** Any host-owned envelope around an event. */
+interface TrajectoryEventEnvelope {
+  event: TrajectoryEvent;
+}
+/**
+ * One item in a trajectory, on either side of the comparison:
+ *
+ * - a state value — `'drafting'`, a dot path `'review.editing'`, or the nested
+ *   object XState reports (`{ review: 'editing' }`),
+ * - an event object, or just the event type as a string,
+ * - a machine snapshot, whose `value` is used.
+ */
+type TrajectoryItem = StateValue | TrajectoryEvent | TrajectoryEventEnvelope | {
+  value: StateValue;
+};
+/** Options for {@link matchesTrajectory}. */
+interface MatchTrajectoryOptions {
+  /**
+   * Require the trajectories to be equal: same length, item for item. Default
+   * `false` — expected items must appear in `actual` in order, gaps allowed.
+   */
+  exact?: boolean;
+}
+/** The first expected item that could not be found. */
+interface TrajectoryMiss {
+  /** Its position in `expected`. */
+  index: number;
+  /** The expected item itself. */
+  expected: TrajectoryItem;
+  /** Where the search for it started in `actual` (everything before was already consumed). */
+  searchedFrom: number;
+}
+/**
+ * The result of {@link matchesTrajectory}: a boolean for tests, plus enough
+ * detail for a scorer's partial credit and a failure message's diagnosis.
+ */
+interface TrajectoryMatch {
+  /** Every expected item was found, in order (and, in `exact` mode, nothing else). */
+  matched: boolean;
+  /** How many expected items were matched before the first miss. */
+  matchedCount: number;
+  /** `expected.length`, so a scorer can compute its own ratio. */
+  expectedCount: number;
+  /**
+   * Partial credit, 0..1. `1` for an empty expectation. Denominator is
+   * `max(expectedCount, actual.length)` in `exact` mode, `expectedCount` otherwise.
+   */
+  score: number;
+  /** Absent when `matched`. */
+  firstMiss?: TrajectoryMiss;
+}
+/**
+ * Matches a run's trajectory against an expected one.
+ *
+ * Both trajectories may be state values or events collected from
+ * `onTransition`;
+ * items are compared by shape, so `['prompting', 'drafting']` scores a state
+ * path and `['PROMPT_SUBMITTED', 'SEND']` scores an event log with the same
+ * call.
+ *
+ * Semantics are an ordered subsequence: every expected item must appear in
+ * `actual`, in order, with gaps allowed. Pass `{ exact: true }` to require
+ * equality instead.
+ *
+ * @example Trajectory assertions in a test
+ * ```ts
+ * const statePath: unknown[] = [];
+ * const result = await runAgent(machine, {
+ *   input,
+ *   executors,
+ *   onTransition: (snapshot) => statePath.push(snapshot.value),
+ * });
+ *
+ * const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
+ * expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
+ * expect(matchesTrajectory(events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
+ * ```
+ *
+ * @example Partial credit in an eval scorer
+ * ```ts
+ * const match = matchesTrajectory(output.statePath, expected.statePath);
+ * return { name: 'state_path', score: match.score, metadata: { ...match.firstMiss } };
+ * ```
+ */
+declare function matchesTrajectory(actual: readonly unknown[], expected: readonly TrajectoryItem[], options?: MatchTrajectoryOptions): TrajectoryMatch;
+//#endregion
+//#region src/seam.d.ts
+/**
+ * Which model call is under test: the Nth call with this request `name` (the
+ * `setupAgent({ requests })` key, or `createTextLogic({ name })`). Name the
+ * requests you want to score — a seam is a developer-facing handle, not a
+ * model binding, so there is no addressing by model key.
+ */
+interface SeamRef {
+  /** The request's registered `name`. */
+  request: string;
+  /** 0-based occurrence among the calls with this name. Default `0`. */
+  occurrence?: number;
+}
+/**
+ * One idle pause, handed to {@link RunSeamOptions.respond} so the simulated
+ * user answers off the machine's own state rather than a fixed transcript — a
+ * live seam may branch differently, and a reactive policy scores that run
+ * instead of crashing on it.
+ */
+interface SeamTurn<TMachine extends AnyStateMachine> {
+  /** The idle snapshot to answer. */
+  snapshot: SnapshotFrom<TMachine>;
+  /** Its state value, for a `switch` on flat machines. */
+  state: StateValue;
+  /**
+   * The merged `meta` of the active state(s), e.g. a declared `interaction`.
+   * Typed from the machine's own meta schema (`setupAgent({ meta })`).
+   */
+  meta: Partial<MetaOfSnapshot<SnapshotFrom<TMachine>>>;
+  /** 0-based index of this pause within the run. */
+  turn: number;
+  /** The `idle` result that produced the pause. */
+  result: RunAgentResult<TMachine>;
+}
+/**
+ * One text call in a {@link runSeam} run's ledger, in call order — the receipt
+ * that says which answers came from the script and which one came from the
+ * candidate, so "everything else stayed scripted" is a plain assertion on
+ * {@link RunSeamResult.calls} rather than a recording function wrapped around
+ * every script entry. Text calls only: `decide` and other base executors are
+ * not routed by the seam and do not appear.
+ */
+interface SeamCall {
+  /** The request's `name`, when it has one. */
+  name?: string;
+  /** The request's model key. */
+  model: string;
+  /** The `scripts` queue key that routed this call. */
+  key: string;
+  /** Where the answer came from: the script, or the seam's `candidate`. */
+  source: "script" | "candidate";
+  /** True for the seam call itself — scripted or candidate. */
+  seam: boolean;
+}
+/** One side of the seam: a trajectory pair ready for `matchesTrajectory`. */
+interface SeamSlice {
+  /** State values entered on this side of the seam, in order. */
+  statePath: StateValue[];
+  /** Root-machine transition events on this side of the seam, in order. */
+  events: TrajectoryEvent[];
+}
+/** Options for {@link runSeam}. */
+interface RunSeamOptions<TMachine extends AnyStateMachine> {
+  /** Machine input, passed straight through to `runAgent`. */
+  input?: InputFrom<TMachine>;
+  /**
+   * The call plan: scripted answers per key, consumed in order. A key is a
+   * request `name` when one is scripted under it, else a `model` key, so a
+   * machine whose requests are named routes by name and an unnamed one routes
+   * by model.
+   *
+   * Entries follow {@link ScriptedTextEntry} conventions (a value, an
+   * `{ result, usage? }` object, or a function of the request). A queue that
+   * runs dry throws; set {@link RunSeamOptions.repeatLast} to replay its last
+   * entry instead.
+   */
+  scripts?: Record<string, ScriptedTextEntry[]>;
+  /**
+   * Replay the LAST entry of a queue once it is exhausted, so a live seam that
+   * sends the run down a longer branch still finds an answer. Off by default:
+   * a dry queue throws, the same as every other scripted surface.
+   */
+  repeatLast?: boolean;
+  /** The call under test. */
+  seam: SeamRef;
+  /**
+   * The executor for the seam — the real model, a candidate prompt, anything
+   * request-shaped. Omit to run the seam scripted too: the whole seam run is
+   * then deterministic.
+   */
+  candidate?: AgentRequestExecutor;
+  /**
+   * The simulated user. Called at every idle pause; return the event to send,
+   * or `null`/`undefined` to stop the run there. Omitted, the run stops at the
+   * first idle pause.
+   */
+  respond?: (turn: SeamTurn<TMachine>) => EventFromLogic<TMachine> | null | undefined;
+  /** Maximum idle pauses to answer before stopping. Default `12`. */
+  maxTurns?: number;
+  /**
+   * Base executors merged UNDER the seam routing — supply `decide` (e.g. from
+   * `createScriptedExecutors({ decisions })`) for a machine that also decides.
+   * Text slots are always owned by the routing.
+   */
+  executors?: Partial<AgentRequestExecutors>;
+  /** Passed through to `runAgent`: actor implementations merged onto the machine. */
+  actors?: RunAgentOptions<TMachine>["actors"];
+}
+/** What {@link runSeam} returns: the seam's own answer, plus the run it caused. */
+interface RunSeamResult<TMachine extends AnyStateMachine> {
+  /**
+   * The final `runAgent` result. `usage` accounts for the last leg.
+   */
+  result: RunAgentResult<TMachine>;
+  /** What the seam call returned, or `undefined` when the run never reached it. */
+  seamOutput: unknown;
+  /**
+   * The seam call's own reported token usage — the cost of the one live call
+   * when a `candidate` is a real model. `undefined` when the run never reached
+   * the seam or its answer reported no usage (scripted entries report usage
+   * only via the `{ result, usage }` form).
+   */
+  seamUsage?: AgentCallUsage;
+  /** Model calls made before the seam, or `-1` when the run never reached it. */
+  callsBeforeSeam: number;
+  /** The run's text calls in order: what was served, and by whom. */
+  calls: SeamCall[];
+  /** Everything up to the seam's own effect completion. */
+  before: SeamSlice;
+  /**
+   * Everything from the seam's own effect completion onward — the branch the
+   * seam caused, and the score. Empty when the run never reached the seam.
+   */
+  after: SeamSlice;
+}
+/**
+ * Runs a machine end to end with one model call under test, and slices the run
+ * at that call.
+ *
+ * The `before`/`after` slices are the point: `after.statePath` is the branch
+ * the seam chose and `after.events` is the same question against the durable
+ * log, both ready for `matchesTrajectory`. The state slice splits where the
+ * state path stood when the seam answered; the event slice splits at the
+ * seam's own effect completion (the first `xstate.done.*`/`xstate.error.*`
+ * entry appended after the call was made).
+ *
+ * @example No API key: the seam is scripted too, so the whole thing runs offline.
+ * ```ts
+ * const run = await runSeam(emailDrafter, {
+ *   scripts: { promptEvaluator: [vague, complete], emailDrafter: [draft] },
+ *   seam: { request: 'evaluatePrompt' },
+ *   respond: ({ state }) => (state === 'prompting' ? { type: 'PROMPT_SUBMITTED', prompt } : null),
+ * });
+ *
+ * matchesTrajectory(run.after.statePath, ['needsMoreInfo', 'drafting']);
+ * ```
+ *
+ * @example A candidate prompt at the seam, scored against the same rows.
+ * ```ts
+ * const { generateText } = createAiSdkExecutors({ models });
+ * const run = await runSeam(emailDrafter, { ...row, candidate: generateText });
+ * ```
+ */
+declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
+//#endregion
+export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type RunSeamOptions, type RunSeamResult, type ScriptedByName, type ScriptedDecisionEntry, type ScriptedDecisionValue, type ScriptedExecutors, type ScriptedExecutorsScript, type ScriptedTextEntry, type SeamCall, type SeamRef, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, createScriptedExecutors, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };