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

package/skills/add-evals/SKILL.md

@@ -30,7 +30,7 @@ console.log(describeMachine(machine)); // goal, states, transitions, events
 
 List:
 
-- the decision states: an `agent.decide` invoke, a `decision` tag, or a state a host answers with `decideNext`;
+- the decision states: an `agent.decide` invoke, a `decision` tag, or a state a host answers with `decideNext`. A machine whose model choice is the output of a text request (a tool call it then checks) has no decision states: eval that choice at the **request** level with `runSeam`;
 - the person's steps: idle states a person answers (`meta.interaction`, the runner's `onIdle`). What the person decides is ground truth, not something to eval; the routing after their answer is a rule;
 - the guards. `describeMachine` shows where a transition function can go and marks it `(conditional)`, but not the guard's name or logic. Read the source for those;
 - the sentinel states and the final states.
@@ -57,34 +57,49 @@ If the request names nothing ("write evals"), cover every decision state, every
 
 A guard or ordering is always a rule eval. Use a decision eval when the guards leave more than one legal option. Use an outcome eval when a person can label the right end result.
 
+Draft labels gate nothing, but rule evals need no labels, so they gate CI from day one. The label-based evals start gating as the user confirms labels (`draft: false`). Say so in the hand-back, so nobody reads a green CI as "the outcome evals pass".
+
 ## 4. Write them
 
-Name every eval `<state>: <what it checks>`, so the report reads as a map of the machine. In `test.each` titles, `$name` is a placeholder: write amounts as `100 dollars`, not `$100`.
+Name every eval `<state>: <what it checks>`, so the report reads as a map of the machine. An outcome eval over a whole run takes the final state it expects (`issued: partial-refund refunds 50 dollars`). In `test.each` titles, `$name` is a placeholder: write amounts as `100 dollars`, not `$100`.
 
 **Rule evals**, from `@statelyai/agent/testing`:
 
 ```ts
 test("paying: no refund over 100 dollars issues without approval", async () => {
-  const result = await canReach(machine, "ruleBroken", { input, payloads, outputs, errors });
+  const result = await canReach(machine, "<sentinel>", { input, payloads, outputs, errors });
   expect(result.complete).toBe(true); // reachable: false is a proof only when the search finished
   expect(result.reachable, JSON.stringify(result.witness)).toBe(false);
 });
 
-test("deciding: REFUND over the order amount is refused", () => {
-  expect(refundIsLegal({ ...context, order: { ...order, amount: 40 } }, 41)).toBe(false);
+test("deciding: REFUND over the order amount never reaches paying", async () => {
+  const result = await canReach(machine, (s) => s.matches("paying") && s.context.amount > s.context.order.amount, { input, payloads, outputs });
+  expect(result.complete).toBe(true);
+  expect(result.reachable).toBe(false);
 });
 ```
 
+Check guards through the machine, not by importing the guard and calling it: an imported `refundIsLegal` is always the one in the source, so it passes on a machine built with a loosened guard. A unit test of the guard function is fine as well, never instead.
+
 Use `explorePaths` to assert the set of reachable final states, and `await simulateAgent(...)` for one scripted path. Cover both sides of every threshold. The two treat a closed choice differently:
 
 - `explorePaths` and `canReach` use `options.payloads` **instead of** the decision's own offered options, so they explore values the machine would never offer. That is what a boundary proof needs.
 - `simulateAgent` keeps the offered options: a scripted event the decision did not offer is refused, and the run ends in the decision's `onError`. Script only offered events, or pick an input that offers the value.
 
-**Decision evals.** A row is a decision request and the event a person says is right. Write rows by hand, or take them from recorded traces: the first attempt of each decision is a `request.start` event with `request.kind === "decision"` and `request.attempts.length === 0`, and its `request` carries `name`, `options`, and `metadata`. Cast the serialized `request` to `AgentExecutorDecisionRequest`, and compare events without caring about key order. If the decider reads anything outside the request (the ticket, the tool history), store that in the row too.
+**Decision evals.** A row is a decision request and the event a person says is right. Write rows by hand, or take them from recorded traces with `getDecisionRequests(trace, { name })` from `@statelyai/agent/testing`: each decision's first attempt, with the states it was asked in, its `options`, and its `metadata`. Compare events without caring about key order. If the decider reads anything outside the request (the ticket, the tool history), store that in the row too.
 
 ```ts
-// Your helper: rows for one decision state, from traces or a fixture file.
-const rows: Array<{ id: string; request: AgentExecutorDecisionRequest; expected: ChosenEvent }> = loadDecisionRows("deciding");
+import { getDecisionRequests } from "@statelyai/agent/testing";
+
+// One row per recorded decision; `expected` is the label a person confirmed for that decision.
+// A scenario can decide more than once, so label each decision by its position, not the scenario alone.
+const rows = traces.flatMap(({ scenario, trace }) =>
+  getDecisionRequests(trace, { name: "chooseResolution" }).map(({ request }, i) => ({
+    id: `${scenario.id}#${i}`,
+    request,
+    expected: labels[`${scenario.id}#${i}`],
+  })),
+);
 
 test.each(rows)("deciding: $id", async ({ request, expected }) => {
   const { event } = await decide(request); // the policy decider, or the model executor

package/skills/add-traces/SKILL.md

@@ -20,7 +20,7 @@ This is step 2 of 4. Before: `loop-to-machine`. Next: `add-evals`, then `improve
 
 ## Hard rules
 
-- **Traces never change behavior.** Recording is an observer. No branch reads a trace.
+- **Traces never change behavior.** Recording is an observer. No branch reads a trace. An `onTrace` or `onTransition` handler that throws is reported with `console.error` and skipped. The store is different: it is write-ahead, so a failed write stops the run with `cause: "journal"`. Ask the user whether a run should fail when its log cannot be written (the store) or carry on unrecorded (record from `onEvent` instead).
 - **A trace must name what produced it.** A run with no machine version or policy version cannot be used to compare versions, so it is useless to the improver.
 - **Replay is the test.** A log that does not replay to the run's final state with zero model calls is not a trace yet.
 - **No secrets or personal data in metadata or thread ids.** Use ids, not names or emails. The log itself holds the machine's input and every event verbatim (a ticket's text, a customer's reply), and trace snapshots hold the context: in production, redact or encrypt them per your data rules, and ask the user which applies.
@@ -33,10 +33,11 @@ Declare `version` on every machine whose runs you record: the environment and, i
 export const deskMachine = deskSetup.createMachine({ id: "refund-desk", version: "1", ... });
 ```
 
-Also name the **decider version**: what answers the decisions. It is the policy machine's `version` when there is one; otherwise a label for the model and prompt that decide (`gpt-6-luna.p1`), or for a stand-in model in tests (`careful`). Runs by different deciders must never share a version label.
+Also name the **decider version**: whatever produces the model's answers. It is the policy machine's `version` when there is one. Otherwise it is a label for the model, its settings, and its prompts (`gpt-6-luna.xhigh.p<hash of the prompts>`); this holds for a machine with only text requests too. When the prompts are private to another module (a route file), export a prompt version from that module rather than guessing; a release or commit id is the fallback. In tests it is the stand-in model's name (`careful`). Runs by different deciders must never share a label.
 
 - Every log entry carries `machineVersion`. Without a declared `version` it falls back to a structural hash that skips functions, and in XState v6 the guards and targets live in transition functions. Changing a guard would not change the hash.
 - Bump `version` on every behavior change. Adding recording is not one: it only observes. `improve-machine` bumps the policy's on promotion.
+- A test-only variant built from the same factory (a loosened guard) gets its own `version` (`"1-loose"`), so its runs are never mistaken for the real machine's.
 
 ## 2. Pick a store
 
@@ -50,7 +51,9 @@ const result = await runAgent(deskMachine, { input, executors, store, threadId,
 await result.drain(); // late usage entries, before you read the store or exit
 ```
 
-**A thread that already has entries is resumed, not overwritten.** Give every new run a new thread id; reuse one only to continue that run.
+**A thread that already has entries is resumed, not overwritten.** Give every new run a new thread id; reuse one only to continue that run. Passing different `input` to a thread that already has entries throws `thread-input-mismatch` instead of handing back another run's result.
+
+For a production store, use a table of its own (`threadId`, `index`, the entry as JSON, a unique key on both), not a table that already means something else, such as a usage counter.
 
 ## 3. Name threads
 
@@ -77,7 +80,7 @@ const metadata = {
 };
 ```
 
-Read it back with `entries[0].metadata`. A resumed run keeps the stamp of the run that started the log. `executionId` is reserved. The value type is `JsonValue` from `@statelyai/agent/log`.
+Read it back with `entries[0].metadata`. It also holds `executionId` (and `migratedFrom` after a version bridge), which the library adds and reserves, so compare with `toMatchObject`, not `toEqual`. A resumed run keeps the stamp of the run that started the log. Type the stamp as `Record<string, JsonValue>` (`JsonValue` from `@statelyai/agent/log`); an interface without an index signature does not fit.
 
 ## 5. Collect trace events
 
@@ -99,8 +102,8 @@ await writeFile(`runs/${file}.trace.json`, JSON.stringify(trace));
 
 Decide with the user whether `runs/` is committed or gitignored.
 
-- In production, send them to OpenTelemetry instead: `createOtelTraceHandler({ tracer })` from `@statelyai/agent/otel` is an `onTrace` handler.
-- **A policy run inside a decider** is a separate run. Pass it the same `onTrace` (and its own `store` thread, `<threadId>:policy:<n>`) if you want per-state stats for the policy too.
+- In production, send them to OpenTelemetry: `createOtelTraceHandler({ tracer })` from `@statelyai/agent/otel` is an `onTrace` handler. It needs the optional peer `@opentelemetry/api`; without OpenTelemetry in the app, write the serialized events next to the log instead.
+- **A policy run inside a decider** is a separate run. Pass it the same `onTrace` (and a `store`) if you want per-state stats for the policy too. `createPolicyDecider` gives each decision's policy run its own thread, `policy:<callKey>:<SHA-256 of its input>`; never give it one fixed `threadId`, or the second decision resumes the first.
 - **A plain XState machine** (built with `createMachine` or `setup`, decided with `decideNext`): drive it with `createAgentRuntime` and `runToQuiescence`, which accept plain machines, and pass each `decideNext` result as `{ event, attempts }` so refused choices reach the log. Push `{ type: "request.start", request: result.request }` onto the trace before sending the event, since a host-driven decision emits no trace itself.
 - **A plain `createActor` run you cannot change:** attach `recordLog(actor)` from `@statelyai/agent/log` before `actor.start()`, and pass `inspect: traceTransitions((event) => trace.push(serializeTraceEvent(event)))` to `createActor`. `recordLog` cannot record decision attempts.
 
@@ -116,15 +119,24 @@ test("a recorded run replays to its final state with no model calls", async () =
   const result = await runAgent(deskMachine, { input, executors, store, threadId: "test:careful:small-clean:r1", metadata });
   await result.drain();
   const entries = await store.read("test:careful:small-clean:r1");
-  const { snapshot } = replay(deskMachine, entries); // a pure fold: nothing runs
-  expect(snapshot.value).toEqual(result.snapshot.value);
+  expect(entries[0]?.event.type).toBe("@agent.init"); // a log was written at all; a run with no outside input has only this entry
+  const { snapshot } = replay(deskMachine, entries, { verify: "strict" }); // a pure fold: nothing runs
+  // Compare more than the state value: context and output catch a field the log does not keep.
+  expect({ status: snapshot.status, value: snapshot.value, context: snapshot.context, output: snapshot.output }).toEqual({
+    status: result.snapshot.status,
+    value: result.snapshot.value,
+    context: result.snapshot.context,
+    output: result.snapshot.output,
+  });
   expect(entries[0]!.metadata).toMatchObject({ environmentVersion: "1" });
 });
 ```
 
-- `foldTraces(traces, { failed })` over a batch returns a row for every decision state. `failed` judges one whole trace; start with "the last event is not a `run.end` with status `done`, or the run ended in a failure or sentinel state", and ask the user whether a wrong outcome counts too. `withheld` is above 0 only for a closed choice (`payloads`), where the guards refused an option.
-- `getDecisionAttempts(entries)` lists the refused choices of a run. A stand-in model that picks from the offered options can never propose an illegal one, so write a raw decide executor for this test that proposes a refused event first: `decide: async (request) => ({ event: request.attempts.length ? request.options![0]!.event : { type: "REFUND", amount: 1000 } })`.
-- Running a scenario with and without recording leaves the same world and the same final state.
+`verify: "strict"` checks that every entry carries a hash and that each matches the fold. It does not show the log is complete (a dropped last entry leaves the rest intact), nor that the fold matches the live run, which is why the test compares the snapshots too. A journaled `Error` replays as an `Error` with its `name`, `message`, and a string or number `code`; any other property of the thrown value is not kept. A thrown plain object replays as a plain object.
+
+- `foldTraces(traces, { failed })` over a batch returns a row for every state a run rested in. A `choice` state the run passes through in the same step gets no row. `failed` judges one whole trace; start with "the last event is not a `run.end` with status `done`, or the run ended in a failure or sentinel state", and ask the user whether a wrong outcome counts too. A serialized `run.end` is `{ type: "run.end", status, snapshot: { value, context, … } }`: `failed: (t) => { const end = t.at(-1); return end?.type !== "run.end" || end.status !== "done" || ["failed", "invariantBroken"].includes(String(end.snapshot?.value)); }`. `withheld` is above 0 only for a closed choice (`payloads`), where the guards refused an option.
+- `getDecisionAttempts(entries)` lists the refused choices of a run; for a machine with no decisions (`agent.decide` or `decideNext`) it is always empty, so skip this test. A stand-in model that picks from the offered options can never propose an illegal one, so write a raw decide executor for this test that proposes a refused event first: `decide: async (request) => ({ event: request.attempts.length ? request.options![0]!.event : { type: "REFUND", amount: 1000 } })`.
+- Running a scenario with and without recording leaves the same world, the same model calls, and the same final state, and the recorded run's log is not empty.
 
 ## 7. Hand back
 

package/skills/generate-machine/SKILL.md

@@ -31,13 +31,13 @@ import { describeMachine } from "@statelyai/agent";
 const text = describeMachine(machine); // "Machine <id>", then "Goal: …", states, transitions, events
 ```
 
-Pass `{ snapshot }` to mark the active states with `*`. Concept page: [Environment and policy](https://github.com/statelyai/agent/blob/main/docs/environment-and-policy.md).
+Pass `{ snapshot }` to mark the active states with `*`. Concept page: [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md).
 
 ## 1. Read the schema
 
 The config shape is fixed by a shipped JSON Schema. Read it first; it is the contract.
 
-- Consuming the package: `node_modules/@statelyai/agent/agent-workflow.json` (importable as `@statelyai/agent/agent-workflow.json`)
+- Consuming the package: `node_modules/@statelyai/agent/schemas/agent-workflow.json` (importable as `@statelyai/agent/agent-workflow.json`)
 - In the `statelyai/agent` repo: `schemas/agent-workflow.json`
 
 ## 2. Author the config

package/skills/graph-engineering/SKILL.md

@@ -18,7 +18,7 @@ Four steps, in order. Each one needs the one before it.
 
 Check in this order and start at the first step that is not done:
 
-1. Is the agent's control flow a machine (`setupAgent`, `createMachine`, an `AgentWorkflowConfig`)? If it is a loop or ad-hoc code, step 1.
+1. Does the code path production actually runs go through a machine (`setupAgent`, `createMachine`, an `AgentWorkflowConfig`)? Follow the route or entry point to the model call; a machine that nothing calls does not count. If the path is a loop or ad-hoc code, step 1.
 2. Do runs persist to an event log store with a declared machine `version` and a `metadata` stamp? If not, step 2.
 3. Is there an objective over ground truth, and evals that name the states they cover? If not, step 3.
 4. Otherwise, step 4.

package/skills/improve-machine/SKILL.md

@@ -11,7 +11,7 @@ You improve a **policy**: the machine that decides how the agent works toward it
 locate inputs → read traces → diagnose → propose one diff → gate (≤ 3 repairs) → replay train → replay held-out → recommend or discard → record → pull request
 ```
 
-This is step 4 of 4, after `loop-to-machine`, `add-traces`, and `add-evals`. To author a JSON policy from scratch, use the `generate-machine` skill. Concept page: [Environment and policy](https://github.com/statelyai/agent/blob/main/docs/environment-and-policy.md).
+This is step 4 of 4, after `loop-to-machine`, `add-traces`, and `add-evals`. To author a JSON policy from scratch, use the `generate-machine` skill. Concept page: [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md).
 
 ## Hard rules
 
@@ -37,7 +37,7 @@ The rounds are the same for both formats. What differs is what the diff may touc
 **No policy yet.** `loop-to-machine` leaves a single model decision inside the environment when the old code had no policy logic. Then:
 
 - Record `v0` in a new `CHANGELOG.md` next to the environment (in a `policy/` directory): "the model decides directly". This entry goes in the working tree.
-- The first recommended candidate introduces the policy as `v1`: a policy file that reproduces the current behavior (it passes the environment's prompt and facts through to the model) plus the one rule the diagnosis found, and the routing line in the runner (`withPolicy(modelExecutors)`). The pattern is in `../loop-to-machine/policy.md`.
+- The first recommended candidate introduces the policy as `v1`: a policy file that reproduces the current behavior (it passes the environment's prompt and facts through to the model) plus the one rule the diagnosis found, and the routing line in the runner (`withPolicy(modelExecutors)`). The policy runs as the decider through `createPolicyDecider` from `@statelyai/agent`; the pattern is in `../loop-to-machine/policy.md`.
 - Its `description` is the environment's goal with measurable success criteria. If the environment's goal has none, draft them from the confirmed objective and list the draft under questions for the user.
 - If the policy needs a fact the environment does not pass in the decision's `metadata.facts`, that is an environment change request.
 
@@ -83,8 +83,9 @@ Then find the training threads and compute one outcome row per episode:
 ```ts
 import { getDecisionAttempts, getUsageFromEvents, replay } from "@statelyai/agent/log";
 
-// Thread ids name the split and policy version: "train:v<n>:<scenario>:r<k>".
-const prefix = `train:v${currentVersion}:`;
+// Thread ids name the split and the decider version, as add-traces set up: "train:<deciderVersion>:<scenario>:r<k>".
+// With a policy, the decider version is the policy's version ("v3"); before one exists, the model's label.
+const prefix = `train:${deciderVersion}:`;
 const threadIds: string[] = [];
 let cursor: string | undefined;
 do {
@@ -151,7 +152,7 @@ Run every check; a failure's output is the repair prompt. Cap repairs at 3.
 1. **Environment unchanged:** every environment file hashes as recorded. A change is never repaired; discard the candidate.
 2. **Types:** `tsc --noEmit` passes.
 3. **Lint:** `lintAgentMachine(policy)` from `@statelyai/agent/testing` reports no errors.
-4. **Paths:** for probe inputs built from recorded decision requests (one per training scenario that reaches the decision: its facts and offered options), `canReach(policy, (snapshot) => snapshot.status === "done" && !isOfferedEvent(snapshot.output), { input })` is `{ reachable: false, complete: true }`: every final output is one of the offered events. Pass `outputs` for any actor the policy invokes, and `errors: { "agent.decide": new Error("down") }` so the fallback path is checked too.
+4. **Paths:** for probe inputs built from recorded decision requests (`getDecisionRequests(trace, { name })` from `@statelyai/agent/testing`, one per training scenario that reaches the decision: its facts and offered options), `canReach(policy, (snapshot) => snapshot.status === "done" && !isOfferedEvent(snapshot.output), { input })` is `{ reachable: false, complete: true }`: every final output is one of the offered events. Pass `outputs` for any actor the policy invokes, and `errors: { "agent.decide": new Error("down") }` so the fallback path is checked too.
 5. **Source rules:** the policy file is still one `setupAgent` machine; its imports from the environment are only schemas, types, constants, and exported guard functions; it names no actor the environment owns. These are source checks: read the diff, or grep its imports and actor names.
 6. **Overfit:** the diff contains no literal from the scenarios (ids, ticket text, customer ids, order ids). A branch that matches one scenario's data is memorization; discard it.
 7. **Existing evals:** the rule and decision evals from `add-evals` still pass. Tests that pin measured numbers of the current version (a baseline failure list, a call count) are expected to change; update them in the same pull request and list each change in its body.
@@ -231,7 +232,7 @@ Report to the user: rounds run, each candidate with its hypothesis and decision,
 
 ## Worked example
 
-[`examples/self-improving-refunds`](https://github.com/statelyai/agent/blob/main/examples/self-improving-refunds) in the `statelyai/agent` repo (not in the installed package) runs this loop end to end for a JSON policy:
+[`examples/self-improving-refunds`](https://github.com/statelyai/agent/blob/next/examples/self-improving-refunds) in the `statelyai/agent` repo (not in the installed package) runs this loop end to end for a JSON policy:
 
 - the refund desk is the environment: business rules as guards, and an `illegallyIssued` sentinel proven unreachable,
 - `playbooks/*.json` are policy versions, with the vocabulary listed in `playbooks/README.md`,

package/skills/loop-to-machine/SKILL.md

@@ -30,7 +30,11 @@ Read the loop and fill this table before writing anything. Each row maps to a ma
 | A tool with a side effect someone must gate (refund, send)                   | An actor invoked by one state, entered only through a guarded transition |
 | A read-only tool (search, lookup)                                            | An actor the machine invokes itself, or a tool on a text request         |
 | A rule: an `if`, a prompt line, a check after the fact                       | A guard on the transition it protects                                    |
+| A model call that produces content (a draft, generated code, a summary)      | A text request in `setupAgent({ requests })`, invoked by one state       |
+| One SDK tool call that both picks the action and carries its content (`edit_graph({ … })`, `send_email({ … })`) | A text request with those tools, then guards on the returned call: exactly one, a tool that was offered, input that passes the tool's schema. Keep it a text request: `agent.decide` would rename the tools to `send_event_<TYPE>` with the description "Choose the '<TYPE>' move.", so the model would no longer see your tool names and descriptions |
+| A tool the browser runs (no `execute`; the client sends results back)        | The request ends with the tool calls; an idle state waits for a `TOOL_RESULTS` event the route sends when the client posts results |
 | A point where the model picks what to do                                     | A decision state: `agent.decide`, usually a closed choice                |
+| A check on the model's output, then a retry or a repair call                 | An actor or guard that checks it, and a `choice` state that routes to the repair request, the next candidate, or a failure final |
 | A value the model pulled out of the input (an order id, an amount)           | Code when the format is fixed (a regex); a text request when it is not   |
 | A step every correct run takes in the same order (verify, then look up)      | A state the machine enters itself; the model no longer chooses it        |
 | A person in the loop: `await approve()`, a returned `pending`, or a tool that asks a person (`askCustomer`, `requestApproval`), even a synchronous one | An idle state with `meta.interaction`, answered by `onIdle` in the runner |
@@ -41,14 +45,17 @@ Read the loop and fill this table before writing anything. Each row maps to a ma
 
 List the rules as a numbered list in your notes. Every one must end as a guard, a state ordering, or a written reason it was dropped.
 
+A loop with no decision point (generate, validate, repair) is still worth converting: the machine makes the retry cap, the validation rules, and every failure path explicit and provable. It has no `agent.decide`, so step 4 and the decision parts of step 5 do not apply.
+
 ## 2. Pin the baseline
 
 The parity test exists before the machine does.
 
 1. **Scenarios.** Reuse the code's tests, fixtures, or benchmark cases. Each has an `id` and, where people know it, the `expected` outcome. If there are none, draft 6–10 that cover every terminal and every rule, and ask the user to confirm them.
-2. **Deterministic stand-in models.** Parity with a live model drifts between runs. Use the code's scripted or mock models if it has them; otherwise write one keyed on the input (see [`examples/mock-model.ts`](https://github.com/statelyai/agent/blob/main/examples/mock-model.ts) in the `statelyai/agent` repo). You want two: one that follows the rules, and one that breaks them. A seeded random model needs its seed derived from the scenario id and a fresh instance per run, or every scenario replays the same draws.
+2. **Deterministic stand-in models.** Parity with a live model drifts between runs. Use the code's scripted or mock models if it has them; otherwise write one: a function from the request (its prompt, or its `name`) to a fixed answer. ([`examples/mock-model.ts`](https://github.com/statelyai/agent/blob/next/examples/mock-model.ts) in the `statelyai/agent` repo is one, built on the AI SDK's `MockLanguageModelV3`; it is not in the package.) You want two: one that follows the rules, and one that breaks them. A seeded random model needs its seed derived from the scenario id and a fresh instance per run, or every scenario replays the same draws.
 3. **Ground truth.** Read outcomes and effects from the world, not from the agent's own report. `effects` holds **every write the world records**: the refunds, and also the approvals, the verifications, the questions asked, the escalations. A refund issued without its approval looks correct if `effects` holds only refunds. Text a model wrote (an escalation reason) differs on every run: compare its count or presence, not the text. If the world can check rules after the fact, return those violations. If it cannot, write the check as a plain function over the effects.
-4. **The harness check.** Run the old code on both sides with each stand-in model. Each row's baseline must equal its candidate (the runs are deterministic), and with the rule-following model every row must be `same`. With a rule-breaking model, rows are `regression` by design: the candidate breaks rules.
+4. **A baseline with no function to call.** When the loop lives inline in a framework handler (a tRPC procedure, a route), call the handler itself in the test, with its model client and storage replaced by the stand-ins (a module mock, or the framework's test caller). Do not extract the loop into a function first: that changes the code you are trying to pin.
+5. **The harness check.** Run the old code on both sides with each stand-in model. Each row's baseline must equal its candidate (the runs are deterministic), and with the rule-following model every row must be `same`. With a rule-breaking model, rows are `regression` by design: the candidate breaks rules.
 
 ```ts
 import { compareRuns, type ParityResult, type ParityRun } from "@statelyai/agent/testing";
@@ -99,15 +106,16 @@ deciding: {
       // The facts a decider reads. Arrives as `request.metadata.facts`.
       metadata: { facts: { order: context.order, requestedAmount: context.requestedAmount } },
     }),
-    onError: { target: "escalated" }, // retries exhausted, or no option legal
+    onError: { target: "escalating" }, // retries exhausted, or no option legal
   },
   on: {
     REFUND: ({ context, event }) =>
       refundIsLegal(context, event.amount)
         ? { target: event.amount > APPROVAL_THRESHOLD ? "awaitingApproval" : "paying", context: { amount: event.amount } }
         : undefined, // undefined rejects: the decision retries with feedback
-    ESCALATE: { target: "escalated" },
-    CLOSE: { target: "closed" },
+    // `escalate` and `close` are tools with side effects: states that invoke them, then the final states.
+    ESCALATE: { target: "escalating" },
+    CLOSE: { target: "closing" },
   },
 },
 ```
@@ -130,9 +138,14 @@ If the code does have that logic, port it as a policy machine that answers `choo
 
 Write `runMachine` with the old function's signature and result type, so callers and the parity test change one line.
 
+- **The existing SDK call becomes the executor.** Write `generateText` (or `streamText`) in `executors` as the old call, with the same model, system prompt, tools, and options, and return `{ result }`. The request still needs `prompt` or `messages` in `setupAgent({ requests })` (`setupAgent` throws `invalid-request` otherwise): pass the conversation as `messages: ({ input }) => input.messages` and read `request.messages` in the executor.
+- **A streaming route keeps its response, not its function signature.** `createAiSdkExecutors().streamText` forwards text chunks only, so a UI stream with tool calls cannot come out of it. Write the `streamText` executor around the old call, pipe its UI stream to the route's response yourself, and return the final messages as `{ result }`.
+
 - `runAgent(machine, { input, executors, actors, onIdle })`.
 - `onIdle` answers each idle state with the old code's call (`tools.askCustomer(...)`, `tools.requestApproval(...)`). Write the returned events with `as const` on `type`, or the event union does not narrow.
 - `executors.decide` adapts the code's model to the decision: the closed choice arrives as `request.options` (each `{ event }`), and the facts as `request.metadata?.facts`, typed `unknown`: parse it with the exported facts schema. Every executor slot is optional in the type; check or assert the ones you call.
+- In an `onError` function, the error is `event.error`: `onError: ({ event }) => ({ target: "failed", context: { error: String(event.error) } })`. There is no `error` argument.
+- Make input and events JSON-safe at the boundary: no `Date`, `Map`, class instances, or functions (fields set to `undefined` are dropped). With a store, a value the log cannot hold fails the run; without one, the log stops with a warning.
 - Rebuild the old result from `result.output` and the world. A field that has no meaning anymore (a turn count with no loop) keeps its type and gets a comment saying what it now holds.
 
 ## 6. Proofs that need no model
@@ -141,12 +154,26 @@ From `@statelyai/agent/testing`:
 
 - `lintAgentMachine(machine)`: no errors.
 - `canReach(machine, "<sentinel>", options)` returns `reachable: false` **and** `complete: true`, for each distinct input shape (an input with an order id and one without lead to different paths; loop over them).
-- `options.payloads` lists values on both sides of every guard boundary (`0, 40, 41, 100, 101, 240, 241, 1000`). Without it, a closed choice is explored only with its own `payloads`, and `complete: true` then proves nothing about the boundaries.
+- `options.payloads` is a function of the snapshot that returns payload lists per event type. List values on both sides of every guard boundary: `0`, the threshold and one over, and each order amount the outputs below can produce and one over. Without it, a closed choice is explored only with its own `payloads`, and `complete: true` then proves nothing about the boundaries.
+- A free-text event from a person's step (`CUSTOMER_REPLIED`) needs an entry too, one payload per branch it can take, or the search cannot send it.
+
+```ts
+const proofOptions: ExplorePathsOptions = {
+  payloads: () => ({
+    REFUND: [0, 40, 41, 100, 101, 240, 241, 800, 801].map((amount) => ({ amount })),
+    CUSTOMER_REPLIED: [{ reply: "It's ORD-1001" }, { reply: "no idea" }],
+  }),
+  outputs: { lookupOrder: [ownedOrder, otherCustomersOrder, refundedOrder, { found: false }] },
+  errors: { lookupOrder: new Error("down"), "agent.decide": new Error("exhausted") },
+};
+```
 - `options.outputs` lists every output each actor can return (found and not found, owned and not, refunded and not); `options.errors` makes each actor fail once.
+- **A machine with a loop** (a repair cycle, a resubmit) needs `options.dedupeBy`, or the search runs to `maxDepth` and reports `complete: false`. Return every context field a guard or choice reads: `dedupeBy: (s) => JSON.stringify([s.value, s.context.attempts, s.context.lastError])`. `outputs` are canned per actor src, not per call: to explore "fails twice, then succeeds", let the guard read a counter from context instead of the output.
+- `explorePaths(...).reachedStates` lists only states a run settles in; a `choice` state it passes through is not listed.
 - A loosened guard makes `canReach` true. Write this test too, or the proof proves nothing.
 - Each normal final state is reachable, so the search is not vacuous.
 
-Type the options with `ExplorePathsOptions` from `@statelyai/agent/testing`. `errors` takes one error per actor src, and `"agent.decide"` is a valid key.
+Type the options with `ExplorePathsOptions`, and a `payloads`, `dedupeBy`, or predicate callback's snapshot with `ExploreSnapshot`, both from `@statelyai/agent/testing`. Do not use `AnyMachineSnapshot` from your app's own `xstate`, which may be another version. `errors` takes one error per actor src, and `"agent.decide"` is a valid key.
 
 ## 7. Parity
 

package/skills/loop-to-machine/policy.md

@@ -10,12 +10,15 @@ A policy answers one decision of the environment. It is a `setupAgent` machine,
 
 ## What the environment exports
 
-The event schemas and the facts schema, so the policy reuses them instead of redeclaring them. The `agent.decide` input passes the facts as `metadata: { facts }`.
+The event schemas and the facts schema, so the policy reuses them instead of redeclaring them. The `agent.decide` input passes the facts as `metadata: { facts }`. The facts must carry everything any decider reads: the policy's rules, and the adapter that turns a request into a call to your model (the ticket, the customer, the order's owner). A field the adapter needs and the facts lack changes what the model sees, so the policy no longer reproduces the current behavior.
 
 ```ts
 // In the environment file (exported there):
+// Everything a decider reads: the policy's rules, and the model adapter when the policy asks the model.
 export const factsSchema = z.object({
-  order: z.object({ orderId: z.string(), amount: z.number(), refunded: z.boolean() }).nullable(),
+  ticket: z.string(),
+  customerId: z.string(),
+  order: z.object({ orderId: z.string(), customerId: z.string(), amount: z.number(), refunded: z.boolean() }).nullable(),
   requestedAmount: z.number().nullable(),
 });
 export const deskEvents = {
@@ -29,7 +32,7 @@ export const deskEvents = {
 
 ```ts
 import { z } from "zod";
-import { runAgent, setupAgent, type AgentDecisionExecutor, type AgentRequestExecutors } from "@statelyai/agent";
+import { createPolicyDecider, setupAgent, type AgentDecisionExecutor, type AgentRequestExecutors } from "@statelyai/agent";
 import { deskEvents, factsSchema } from "./desk.js";
 
 /** One proposal: an environment event with its `type`. */
@@ -116,22 +119,13 @@ export const policyMachine = policySetup.createMachine({
   },
 });
 
-/** Runs the policy as the environment's decider. */
+/**
+ * Runs the policy as the environment's decider. createPolicyDecider passes the request's
+ * `metadata.facts`, offered events, `system`, and `prompt` as the policy's input (its input
+ * schema validates them), and returns the policy's output event with its token usage.
+ */
 export function policyDecider(executors: AgentRequestExecutors): AgentDecisionExecutor {
-  return async (request, info) => {
-    const result = await runAgent(policyMachine, {
-      input: {
-        facts: factsSchema.parse(request.metadata?.facts),
-        options: (request.options ?? []).map((option) => proposalSchema.parse(option.event)),
-        system: request.system,
-        prompt: request.prompt,
-      },
-      executors,
-      signal: info?.signal,
-    });
-    if (result.status !== "done") throw new Error(`policy settled '${result.status}'`);
-    return { event: result.output };
-  };
+  return createPolicyDecider(policyMachine, { executors });
 }
 ```
 
@@ -156,3 +150,5 @@ export function withPolicy(modelExecutors: AgentRequestExecutors): AgentRequestE
 ```
 
 Pass `withPolicy(modelExecutors)` as the environment's `executors` in the runner. That one line is the only runner change a policy needs. Decisions with any other name still reach the model.
+
+A runner that already takes a decide executor for the decision (`runMachine({ decide })`) needs no routing: pass `policyDecider(modelExecutors)` there. If your model is not an executor (a function that returns an option index, say), wrap it in a decide executor first, the same adapter the runner uses, and keep that adapter out of the environment's imports.