@statelyai/agent 2.0.0-alpha.28 → 2.0.0-alpha.30

package/dist/verify-Cn86rT8l.d.mts

@@ -0,0 +1,414 @@
+import { u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
+import { Q as AgentError } from "./text-logic-BRYOPWvY.mjs";
+import { AnyMachineSnapshot, AnyStateMachine } 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;
+  /**
+   * Total branch points expanded before exploration stops (reported via
+   * `hitPathCap`). Default 100,000. It bounds work and memory where
+   * `maxPaths` cannot: a loopy machine expands many nodes per terminal.
+   */
+  maxNodes?: number;
+  /**
+   * Every output to try per src: a text request's src (the
+   * `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`)
+   * or any other invoked actor's src. A one-element list is a canned output,
+   * reused every time that src is reached; a text request resolves with it as
+   * its `result` (`{ result, messages: [] }`). A src with two or more outputs
+   * forks one branch per output (plus the `errors` branch when the src is
+   * listed there too), so a machine whose `onDone` branches on the output is
+   * explored down every arm. Each fork counts against `maxDepth`, and each
+   * forked branch records `{ type: 'xstate.done.actor.<id>', output }` in the
+   * path. A src with no entry (and no `errors` entry) halts that branch with a
+   * `needs-output` terminal.
+   */
+  outputs?: Record<string, unknown[]>;
+  /**
+   * A canned failure per src, keyed like `outputs`. 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>;
+  /**
+   * Payloads to try per event type at each branch point, given the settled
+   * snapshot there. At a decision or an idle wait, an event type with an
+   * entry forks once per payload as `{ ...payload, type }`; guard-rejected
+   * variants count in `prunedByGuard`. An entry here overrides the
+   * decision request's own `options` (from the decide input's `payloads`)
+   * for that type.
+   *
+   * A type with no entry and no request option is filled from its event
+   * schema when that schema exposes JSON Schema (Standard JSON Schema, e.g.
+   * Zod 4) and its fields are finite domains (`enum`, `const`, `boolean`,
+   * `null`, or a union of those): it forks over the cartesian product, up to
+   * 64 combinations, each optional field also omitted. A type with a required
+   * non-finite field, or a product over the cap, is applied as `{ type }`; an
+   * optional non-finite field is left out. Either way the type's real variants
+   * were not all tried, so it is listed in `unexpandedEvents`. A type with no
+   * schema at all is applied as `{ type }`.
+   */
+  payloads?: (snapshot: AnyMachineSnapshot) => Partial<Record<string, Record<string, unknown>[]>>;
+  /**
+   * A projection of the snapshot that determines its future. Settled
+   * snapshots with an equal key are explored once (again only when reached
+   * at a shallower depth), so payload and output branching that converges
+   * stays tractable. Return everything a guard, choice, or output reads:
+   * a key that drops a field the machine reads makes the search unsound.
+   * Without it, every path is explored in full.
+   */
+  dedupeBy?: (snapshot: AnyMachineSnapshot) => string;
+}
+/** 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 with no `outputs` entry. */
+  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 a cap (`maxPaths` or `maxNodes`) cut exploration short (report is partial). */
+  hitPathCap: boolean;
+  /**
+   * Event types whose payload variants were not all tried: their schema has
+   * a non-finite field or a product over the fill cap, and `payloads` has no
+   * entry for them. Add a `payloads` entry for each to cover them.
+   */
+  unexpandedEvents: string[];
+}
+/**
+ * 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); a
+ * decision with no takeable candidate exhausts as it does live, taking its
+ * `onError` (an `error` terminal without one). At an idle wait it forks per
+ * externally-accepted event. Text requests and other
+ * invokes resolve from `outputs`, a by-src map of outputs to try (a
+ * one-element list is a canned output; several fork one branch each), 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.
+ *
+ * Events are applied as `{ type }` unless a payload is known: `payloads`
+ * forks a type once per listed payload, a decide input's own `payloads`
+ * become the branch set, and an event schema whose fields are finite (enums,
+ * booleans, consts) expands to their product, each optional field also
+ * omitted. A type that could not be fully expanded is listed in
+ * `unexpandedEvents`, as is a type with no schema whose transition could read
+ * the payload (a function transition, guard, `matches`, or context mapper).
+ * `dedupeBy` explores each projected snapshot once, which keeps a large
+ * payload table tractable.
+ *
+ * Combinatorics are bounded by `maxDepth` (default 8), `maxPaths` (default
+ * 200), and `maxNodes` (default 100,000), the last two 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[];
+  /**
+   * False when the search left a branch it could not rule out unexplored: a
+   * cap (`maxPaths` or `maxNodes`) cut it short, a path reached `maxDepth`, a
+   * branch stopped `needs-output` on a src with no `outputs` entry, or an event type
+   * was not expanded to all its payload variants (`unexpandedEvents` in the
+   * {@link explorePaths} report). `reachable: false` is a proof of
+   * unreachability only when `complete` is true.
+   */
+  complete: boolean;
+}
+/** 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 }`. Check `complete` before treating `reachable: false`
+ * as a proof: it is false when a cap or `maxDepth` cut exploration short, a
+ * branch needed an `outputs` entry it did not have, or an event's payloads were
+ * not all tried.
+ *
+ * @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
+export { explorePaths as _, AgentPathTerminal as a, CanReachResult as c, SimulateAgentOptions as d, SimulateAgentResult as f, canReach as g, assertAgentMachine as h, AgentPathReport as i, ExplorePathsOptions as l, SimulationTrailEntry as m, AgentLintError as n, AgentUnknownStateError as o, SimulationScript as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, LintAgentMachineOptions as u, lintAgentMachine as v, simulateAgent as y };