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

package/dist/testing.d.mts

@@ -1,347 +1,8 @@
-import { u as ChosenEvent } from "./types-BgNbNKnJ.mjs";
-import { Z as AgentError, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-D-czVPYp.mjs";
-import { c as AgentRunResult, d as AgentRuntimeOptions, o as AgentRunInit } from "./run-agent-COXXc0RW.mjs";
-import { t as MetaOfSnapshot } from "./utils-_q7F-AZu.mjs";
-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
+import { c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BDbGjYMh.mjs";
+import { f as AgentRuntimeOptions, l as AgentRunResult, o as AgentRunInit } from "./run-agent-CxSyZmIE.mjs";
+import { t as MetaOfSnapshot } from "./utils-BnXdWih3.mjs";
+import { _ as explorePaths, a as AgentPathTerminal, c as CanReachResult, d as SimulateAgentOptions, f as SimulateAgentResult, g as canReach, h as assertAgentMachine, i as AgentPathReport, l as ExplorePathsOptions, m as SimulationTrailEntry, n as AgentLintError, o as AgentUnknownStateError, p as SimulationScript, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as LintAgentMachineOptions, v as lintAgentMachine, y as simulateAgent } from "./verify-CBuYIpsa.mjs";
+import { AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 //#region src/trajectory.d.ts
 /** An event-shaped trajectory item: anything with a string `type`. */
 interface TrajectoryEvent {
@@ -434,7 +95,7 @@ interface TrajectoryMatch {
  * return { name: 'state_path', score: match.score, metadata: { ...match.firstMiss } };
  * ```
  */
-declare function matchesTrajectory(actual: readonly unknown[], expected: readonly TrajectoryItem[], options?: MatchTrajectoryOptions): TrajectoryMatch;
+export declare function matchesTrajectory(actual: readonly unknown[], expected: readonly TrajectoryItem[], options?: MatchTrajectoryOptions): TrajectoryMatch;
 //#endregion
 //#region src/seam.d.ts
 /**
@@ -614,6 +275,49 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  * const run = await runSeam(emailDrafter, { ...row, candidate: generateText });
  * ```
  */
-declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
+export declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
+//#endregion
+//#region src/fold-traces.d.ts
+/** One state's numbers across many runs. See {@link foldTraces}. */
+interface StateStats {
+  /** The state's dot-joined path from the root, e.g. `'deciding'` or `'work.review'`. */
+  state: string;
+  /** Runs that were in this state at least once. */
+  visits: number;
+  /** Of those runs, the ones `failed` flagged. */
+  failures: number;
+  /** Options withheld by the guards at decisions made in this state, summed over runs. */
+  withheld: number;
+}
+/** Options for {@link foldTraces}. */
+interface FoldTracesOptions<TTrace> {
+  /** Whether a run failed, judged from its whole trace. */
+  failed: (trace: TTrace) => boolean;
+}
+/**
+ * Folds many runs' traces into per-state stats: how many runs visited each
+ * state, how many of those failed, and how many options the guards withheld
+ * at decisions made there. Pure; reads only:
+ *
+ * - `machine.transition`: the run visited `from.value` and `snapshot.value`.
+ * - `request.start` of a decision, first attempt only: its `request.withheld`
+ *   counts toward the state the run was in, the `from.value` of the
+ *   transition its choice causes.
+ *
+ * A trace is one run's events, live (`AgentTraceEvent`) or serialized
+ * (`serializeTraceEvent`). A host-driven `decideNext` traces nothing; push
+ * `{ type: 'request.start', request: result.request }` onto the trace before
+ * sending its event. Parallel states count once per active leaf.
+ *
+ * @example
+ * ```ts no-check
+ * const stats = foldTraces(traces, {
+ *   failed: (trace) => trace.at(-1)?.type === 'run.end' && trace.at(-1).status === 'error',
+ * });
+ * ```
+ */
+export declare function foldTraces<TTrace extends readonly {
+  readonly type: string;
+}[]>(traces: Iterable<TTrace>, options: FoldTracesOptions<TTrace>): StateStats[];
 //#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 SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };
+export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, type FoldTracesOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateStats, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, simulateAgent };