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

package/dist/verify-Dzwd4Mvk.d.cts

@@ -0,0 +1,414 @@
+import { u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
+import { Q as AgentError } from "./text-logic-DmciuVUQ.cjs";
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.28",
+  "version": "2.0.0-alpha.30",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",
@@ -88,6 +88,16 @@
         "default": "./dist/otel.cjs"
       }
     },
+    "./tanstack-ai": {
+      "import": {
+        "types": "./dist/tanstack-ai.d.mts",
+        "default": "./dist/tanstack-ai.mjs"
+      },
+      "require": {
+        "types": "./dist/tanstack-ai.d.cts",
+        "default": "./dist/tanstack-ai.cjs"
+      }
+    },
     "./testing": {
       "import": {
         "types": "./dist/testing.d.mts",
@@ -114,50 +124,53 @@
     "access": "public"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^4.0.0",
-    "@ai-sdk/typesafe-ai": "3.0.6",
-    "@anthropic-ai/sdk": "^0.120.0",
-    "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.31.1",
-    "@earendil-works/pi-ai": "0.83.0",
-    "@flue/runtime": "2.0.3",
-    "@langchain/core": "^1.2.9",
-    "@langchain/openai": "^1.5.10",
-    "@mastra/core": "^1.61.0",
+    "@ai-sdk/openai": "^4.0.89",
+    "@ai-sdk/typesafe-ai": "3.0.16",
+    "@anthropic-ai/sdk": "^0.132.1",
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^3.0.3",
+    "@langchain/core": "^1.2.17",
+    "@langchain/openai": "^1.6.2",
+    "@mastra/core": "^1.75.0",
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/context-async-hooks": "^2.10.0",
-    "@opentelemetry/sdk-trace-base": "^2.10.0",
-    "@types/node": "^20.19.43",
-    "@types/react": "^19.2.18",
-    "ai": "^7.0.113",
+    "@opentelemetry/context-async-hooks": "^2.12.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
+    "@tanstack/ai": "^0.66.0",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@typescript/typescript6": "^6.0.2",
+    "ai": "^7.0.133",
     "ajv": "^8.20.0",
-    "braintrust": "^3.28.0",
-    "dotenv": "^16.6.1",
-    "knip": "6.24.0",
-    "langchain": "^1.5.10",
-    "openai": "^7.5.0",
-    "oxfmt": "0.57.0",
-    "oxlint": "1.72.0",
-    "tsdown": "^0.21.10",
-    "tsx": "^4.23.12",
+    "braintrust": "^3.37.1",
+    "dotenv": "^18.0.6",
+    "knip": "6.40.0",
+    "langchain": "^1.5.16",
+    "openai": "^7.30.1",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.87.0",
+    "tsdown": "^0.23.0",
+    "tsx": "^4.23.15",
     "twoslash": "^0.3.9",
-    "typescript": "^5.9.3",
-    "valibot": "^1.4.2",
-    "vitest": "^4.1.11",
-    "xstate": "6.0.0-alpha.64",
-    "zod": "^4.4.3"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3",
+    "xstate": "6.0.0-alpha.69",
+    "zod": "^4.6.5"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1",
+    "@tanstack/ai": ">=0.66.0 <1",
     "ai": "^7.0.0",
     "ajv": "^8.20.0",
     "openai": ">=5.0.0 <8",
-    "xstate": "6.0.0-alpha.64"
+    "xstate": "6.0.0-alpha.69"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
     },
+    "@tanstack/ai": {
+      "optional": true
+    },
     "ai": {
       "optional": true
     },

package/readme.md

@@ -10,22 +10,29 @@ Stately Agent adds model requests and decisions to XState:
 - Your application chooses the model, runs the requests, and stores the state.
 - The model proposes an event; the machine decides whether it is allowed and what happens next.
 
+Environment and policy:
+
+- The environment is code you own and can verify; the policy is something a model can write inside it.
+- The environment holds the rules and invariants as TypeScript states and guards, fixed and checked with `canReach`.
+- The policy is a JSON machine a model can author and improve from traces, gated before it runs and promoted only on a measured gain. See [Environment and policy](docs/environment-and-policy.md).
+
 Stately Agent 2 is in alpha. APIs may change before the stable release.
 
 [Documentation](https://stately.ai/docs/packages/agent) · [Examples](examples/README.md) · [XState](https://github.com/statelyai/xstate)
 
-## Three starting points
+## Four starting points
 
-- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runToQuiescence`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Use in any stack](docs/any-stack.md).
+- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runAgent`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Use in any stack](docs/any-stack.md).
 - **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](docs/from-a-loop.md).
 - **Copy a known pattern.** ReAct, reflection, plan-and-execute, RAG, supervisor, and more, each a single runnable file you lift in 60 seconds. See [Agent patterns](docs/patterns.md).
+- **Let an agent improve its own logic.** Keep the rules in a fixed TypeScript environment and let a model rewrite the JSON policy inside it, gated by `verifyAgentConfig` and promoted only when held-out scenarios improve. See [Environment and policy](docs/environment-and-policy.md) and the [`improve-machine` skill](skills/improve-machine/SKILL.md).
 
 ## Install
 
 <!-- install command matching the package prerelease channel and package.json peers -->
 
 ```sh
-pnpm add @statelyai/agent@alpha xstate@6.0.0-alpha.64 zod
+pnpm add @statelyai/agent@alpha xstate@6.0.0-alpha.69 zod
 ```
 
 XState is pinned while its experimental durable restoration API evolves.
@@ -42,22 +49,28 @@ For the optional raw OpenAI SDK executor (`@statelyai/agent/openai`):
 pnpm add openai
 ```
 
-Classification, grading, relevance, and yes/no checks are judgments: call the AI SDK's `experimental_evaluate` with `@ai-sdk/typesafe-ai` (`pnpm add ai @ai-sdk/typesafe-ai`) from an ordinary actor; see [Judgments with the AI SDK](docs/judgments.md).
+For the optional TanStack AI executor (`@statelyai/agent/tanstack-ai`):
+
+```sh
+pnpm add @tanstack/ai @tanstack/ai-openai
+```
+
+Classification, grading, relevance, and yes/no checks are judgments: call the AI SDK's `experimental_decide` with `@ai-sdk/typesafe-ai` (`pnpm add ai @ai-sdk/typesafe-ai`) from an ordinary actor; see [Judgments with the AI SDK](docs/judgments.md).
 
 Requirements:
 
-- Node 22.18 or newer, and XState v6 alpha.46 or newer.
+- Node 22.18 or newer, and XState `6.0.0-alpha.69`.
 - The package is ESM-first. CommonJS builds are published too, so `require()` works.
 - Provider packages must match your `ai` major: `@ai-sdk/openai@^4` pairs with `ai@^7`. A bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer.
 
 ## Quick start
 
-<!-- refund decision example using setupAgent, agent.decide, a machine guard, and the AI SDK runToQuiescence host -->
+<!-- refund decision example using setupAgent, agent.decide, a machine guard, and the AI SDK runAgent host -->
 
 This agent reviews refund requests. The model may propose an automatic refund, but the state machine owns the $100 limit.
 
 ```ts
-import { createAgentRuntime, runToQuiescence, setupAgent } from "@statelyai/agent";
+import { runAgent, setupAgent } from "@statelyai/agent";
 import { z } from "zod";
 
 const agentSetup = setupAgent({
@@ -108,19 +121,15 @@ const refundMachine = agentSetup.createMachine({
   },
 });
 
-const result = await runToQuiescence(
-  createAgentRuntime(refundMachine, {
-    // An executor is a plain function, so this run needs no API key and no
-    // provider package.
-    executors: { decide: async () => ({ event: { type: "AUTO_REFUND" } }) },
-  }),
-  {
-    input: {
-      request: "I was charged twice for the same order.",
-      amount: 75,
-    },
+const result = await runAgent(refundMachine, {
+  input: {
+    request: "I was charged twice for the same order.",
+    amount: 75,
   },
-);
+  // An executor is a plain function, so this run needs no API key and no
+  // provider package.
+  executors: { decide: async () => ({ event: { type: "AUTO_REFUND" } }) },
+});
 
 if (result.status === "done") {
   console.log(result.output);
@@ -135,29 +144,32 @@ When the machine reaches `refunded`, the result is:
 
 The model chooses between the events allowed in `deciding`. The `AUTO_REFUND` transition only works when the amount is at most $100. If the model chooses it for a larger amount, the guard rejects the choice and the decision is tried again.
 
-To call a real model, leave the machine unchanged and swap the executors:
+To call a real model, leave the states unchanged. Declare the model once on the setup by adding `models` to the `setupAgent` call above, and hand the machine to the AI SDK adapter:
 
 ```ts
 import { openai } from "@ai-sdk/openai";
 import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
 
-const liveResult = await runToQuiescence(
-  createAgentRuntime(refundMachine, {
-    executors: createAiSdkExecutors({ models: { fast: openai("gpt-5.4-mini") } }),
-  }),
-  { input: { request: "I was charged twice for the same order.", amount: 75 } },
-);
+// In the setupAgent({ ... }) call above:
+//   models: { fast: openai("gpt-6-luna") },
+
+const liveResult = await runAgent(refundMachine, {
+  input: { request: "I was charged twice for the same order.", amount: 75 },
+  executors: createAiSdkExecutors(refundMachine),
+});
 ```
 
+`createAiSdkExecutors(refundMachine)` reads the `models` declared in `setupAgent({ models })`, which also type the machine's model refs. `createAiSdkExecutors({ models })` still works when the host owns the map. Executors are always explicit, and core does not import the AI SDK. See [Models and providers](docs/models-and-providers.md) and [Hosts and executors](docs/hosts.md).
+
 For a machine with several requests, the executor routes on `request.name`, or `MockLanguageModelV3` from `ai/test` stands in for the provider behind `createAiSdkExecutors`. See [Evals](docs/evals.md#testing-without-a-provider).
 
-Passing the same `models` map to `setupAgent({ models })` types the machine's model refs. Executors are always explicit, and core does not import the AI SDK. See [Hosts and executors](docs/hosts.md).
+A host that needs the transition loop itself (a durable object, events pushed mid-run, a custom checkpoint policy) uses `createAgentRuntime` directly. See [Write your own host loop](docs/hosts.md#write-your-own-host-loop).
 
 ## Architecture
 
 ```mermaid
 flowchart LR
-  M["Agent machine<br/>states · guards · requests"] -->|request| R["runToQuiescence"]
+  M["Agent machine<br/>states · guards · requests"] -->|request| R["runAgent"]
   R -->|executor call| E["Host executors<br/>generateText · streamText · decide"]
   E -->|API call| L["Model"]
   L -->|result| E