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

package/dist/validate.cjs

@@ -21,9 +21,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_setup_agent = require("./setup-agent-DTF3NQg3.cjs");
-const require_verify = require("./verify-Cqghu4gz.cjs");
+const require_event_log = require("./event-log-BZRfBRd7.cjs");
+const require_setup_agent = require("./setup-agent-DoUk7EdC.cjs");
+const require_verify = require("./verify-CVlsTZ-V.cjs");
 let ajv_dist_2020_js = require("ajv/dist/2020.js");
 ajv_dist_2020_js = __toESM(ajv_dist_2020_js, 1);
 //#region schemas/agent-workflow.json

package/dist/validate.d.cts

@@ -1,5 +1,5 @@
-import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-DlbgwsIJ.cjs";
-import { l as ExplorePathsOptions } from "./verify-DYH_2VzU.cjs";
+import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-CLPCkXsu.cjs";
+import { l as ExplorePathsOptions } from "./verify-Dzwd4Mvk.cjs";
 import { AnyActorLogic, AnyStateMachine } from "xstate";
 //#region src/validate/validate-config.d.ts
 /**

package/dist/validate.d.mts

@@ -1,5 +1,5 @@
-import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-tsc3vm5I.mjs";
-import { l as ExplorePathsOptions } from "./verify-CBuYIpsa.mjs";
+import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-CGELn1qZ.mjs";
+import { l as ExplorePathsOptions } from "./verify-Cn86rT8l.mjs";
 import { AnyActorLogic, AnyStateMachine } from "xstate";
 //#region src/validate/validate-config.d.ts
 /**

package/dist/validate.mjs

@@ -1,6 +1,6 @@
-import { D as STREAM_TEXT_ACTOR, E as GENERATE_TEXT_ACTOR, T as DECIDE_ACTOR } from "./event-log-GPZO9p7_.mjs";
-import { i as setupAgentFromConfig } from "./setup-agent-DniLvDu7.mjs";
-import { a as explorePaths, o as lintAgentMachine } from "./verify-B5qGC5WN.mjs";
+import { D as STREAM_TEXT_ACTOR, E as GENERATE_TEXT_ACTOR, T as DECIDE_ACTOR } from "./event-log-DJCMHek_.mjs";
+import { i as setupAgentFromConfig } from "./setup-agent-7rV_cujV.mjs";
+import { a as explorePaths, o as lintAgentMachine } from "./verify-COFWyprJ.mjs";
 import Ajv2020 from "ajv/dist/2020.js";
 //#region schemas/agent-workflow.json
 var agent_workflow_default = {

package/dist/{verify-B5qGC5WN.mjs → verify-COFWyprJ.mjs}

@@ -1,5 +1,5 @@
-import { P as isTextLogic, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, X as getJsonSchemaSync, st as AgentError } from "./event-log-GPZO9p7_.mjs";
-import { d as getAcceptedEvents, l as resolveDecision, m as isRecord, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-Bl_rKQnU.mjs";
+import { P as isTextLogic, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, X as getJsonSchemaSync, st as AgentError } from "./event-log-DJCMHek_.mjs";
+import { d as getAcceptedEvents, l as resolveDecision, m as isRecord, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-BHkvuImD.mjs";
 import { getNextTransitions, initialTransition, transition } from "xstate";
 //#region src/steps.ts
 /**

package/dist/{verify-Cqghu4gz.cjs → verify-CVlsTZ-V.cjs}

@@ -1,5 +1,5 @@
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.cjs");
+const require_event_log = require("./event-log-BZRfBRd7.cjs");
+const require_decision = require("./decision-CIb7ddIv.cjs");
 let xstate = require("xstate");
 //#region src/steps.ts
 /**

package/dist/{verify-CBuYIpsa.d.mts → verify-Cn86rT8l.d.mts}

@@ -1,5 +1,5 @@
 import { u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
-import { Q as AgentError } from "./text-logic-BDbGjYMh.mjs";
+import { Q as AgentError } from "./text-logic-BRYOPWvY.mjs";
 import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
 //#region src/verify.d.ts
 /** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */

package/dist/{verify-DYH_2VzU.d.cts → verify-Dzwd4Mvk.d.cts}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.29",
+  "version": "2.0.0-alpha.30",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",

package/readme.md

@@ -32,7 +32,7 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
 <!-- 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.
@@ -59,7 +59,7 @@ Classification, grading, relevance, and yes/no checks are judgments: call the AI
 
 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.
 
@@ -151,7 +151,7 @@ import { openai } from "@ai-sdk/openai";
 import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
 
 // In the setupAgent({ ... }) call above:
-//   models: { fast: openai("gpt-5.4-mini") },
+//   models: { fast: openai("gpt-6-luna") },
 
 const liveResult = await runAgent(refundMachine, {
   input: { request: "I was charged twice for the same order.", amount: 75 },

package/skills/add-evals/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: add-evals
+description: Write evals for a @statelyai/agent or XState agent machine at the right level — rule checks with no model, decision evals at one decision state, outcome evals over whole runs, and per-state stats from traces — each tied to the states it covers. Use when asked to "write evals", "add evals for the approval logic", "test the agent", "measure the agent", "build an eval suite", or "what should I eval" for an agent built as a state machine.
+---
+
+# Add evals to an agent machine
+
+The machine tells you what to eval and at which level. Every eval names the states it covers, so a failing eval points at a part of the machine.
+
+```
+read the machine → map the request to states → pick the level per state → write the evals → baseline → hand back
+```
+
+This is step 3 of 4. Before: `loop-to-machine`, `add-traces`. Next: `improve-machine`.
+
+## Hard rules
+
+- **The cheapest level that can catch the failure.** A rule is checked without a model. Only judgment needs a model in the eval.
+- **Ground truth, never a model's opinion of itself.** Outcome evals read terminal states and effects in the world. A model grades text only where no ground truth exists, and that eval says so in its name.
+- **Labels belong to people.** Draft expected outcomes and expected events; ask the user to confirm them before they gate anything. Keep drafts in their own list, marked unconfirmed, and out of every gate.
+- **Never edit the machine to make an eval pass.** A failing eval is a finding. Report it.
+- **Held-out scenarios stay held out.** Evals may run on them; nobody tunes against them.
+
+## 1. Read the machine
+
+```ts
+import { describeMachine } from "@statelyai/agent";
+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 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.
+
+## 2. Map the request to states
+
+Turn the user's words into states. "Evals for the approval logic" means every state and guard that touches approval: the guard that routes a refund over the threshold, the approval step and each answer to it, the sentinel check before the payment, and the final states they lead to. Write the mapping down:
+
+| Asked about | States and guards                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------------- |
+| approval    | `deciding` (REFUND: over threshold → `awaitingApproval`), `awaitingApproval` (APPROVE, REJECT), `paying` (sentinel check), `issued`, `closed` |
+
+If the request names nothing ("write evals"), cover every decision state, every sentinel, and the run as a whole.
+
+## 3. Pick the level
+
+| Level        | Catches                                              | Runs a model          | Tools                                                              |
+| ------------ | ---------------------------------------------------- | --------------------- | ------------------------------------------------------------------ |
+| **Rule**     | A guard, an ordering, an invariant that must hold    | No                    | Exported guard functions, `canReach`, `explorePaths`, `simulateAgent` |
+| **Decision** | A wrong choice at one decision state                 | The decider under test | The decider called on recorded or written decision requests        |
+| **Request**  | A bad text output from one request                   | That request          | `runSeam`, scored on `seamOutput` and the path after it. Not applicable when the machine has no text requests; say so |
+| **Outcome**  | A wrong end result for a whole scenario              | The whole agent       | Scenarios, the runner, an objective over terminal states and effects |
+| **Stats**    | Which state the failures cluster in                  | No (reads traces)     | `foldTraces`                                                       |
+
+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.
+
+## 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`.
+
+**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 });
+  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);
+});
+```
+
+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.
+
+```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");
+
+test.each(rows)("deciding: $id", async ({ request, expected }) => {
+  const { event } = await decide(request); // the policy decider, or the model executor
+  expect(event).toEqual(expected);
+});
+```
+
+Which deciders gate CI: a deterministic reference decider (a scripted or rules-based one) gates. A live model is a measurement, not a unit test: run it outside CI, several times, and report the rate. A seeded random decider is measured over several seeds, never gated.
+
+**Request evals.** For a text request (a drafted question, a summary), `runSeam(machine, { input, scripts, seam: { request: "draftQuestion" }, candidate })` runs the whole machine with only that request live. Score `seamOutput`, and the states the run reached after it.
+
+**Outcome evals.** One function over a batch of scenario runs, reading ground truth. Score the effects as well as the outcome: a run that ends `issued` with the wrong amount is wrong.
+
+```ts
+export function objective(runs: Array<{ scenario: Scenario; outcome: string; refund?: Refund; violations: number; modelCalls: number }>) {
+  return {
+    accuracy: runs.filter((r) => r.outcome === r.scenario.expected && sameRefund(r.refund, r.scenario.expectedRefund)).length / runs.length,
+    violations: runs.reduce((n, r) => n + r.violations, 0), // must be 0
+    modelCalls: runs.reduce((n, r) => n + r.modelCalls, 0), // cost
+  };
+}
+```
+
+Read the terminal state from the event logs `add-traces` recorded (`replay(machine, entries).snapshot`, `replay` from `@statelyai/agent/log`). Effects and violations live in the world, not the log: save them next to the thread id when the run ends, so the objective can be recomputed without running anything. Use `matchesTrajectory` only for an ordering a person requires (approval before payment), never to pin the whole path; build its input from the `machine.transition` trace events' `snapshot.value`.
+
+**Stats.** `foldTraces(traces, { failed })` (from `@statelyai/agent/testing`) returns `{ state, visits, failures, withheld }` per state. A failed run counts against **every** state it visited, so states after a bad decision rank as high as the decision itself. Use the table to see which states failing runs pass through, then look at the decision states among them, their `withheld` counts, and their decision attempts. `failed` sees only the trace: to judge a run against its label, keep a map from trace to scenario.
+
+## 5. Coverage
+
+If every decider scores the same on the confirmed scenarios, the scenarios cannot tell a better decider from a worse one. Draft scenarios on the boundaries the evals found (an amount just under and over a threshold, a partial request), label them as drafts, and ask the user to confirm them and add them to the scenario set. They become part of the train or held-out split only once confirmed.
+
+## 6. Baseline
+
+Run every eval once on the current machine and record the numbers: which pass, the outcome scores per split, the stats table. Failing evals are findings, not bugs in the eval, unless the label was wrong; then ask.
+
+## 7. Hand back
+
+1. The state mapping from step 2.
+2. The evals by level, each named by state.
+3. The baseline numbers, train and held-out separately.
+4. Every failing eval and the state it points at.
+5. Next step: `improve-machine`, with the objective from step 4 as its scorer.

package/skills/add-traces/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: add-traces
+description: Make every run of a @statelyai/agent or XState machine leave a replayable, stamped trace — an event log thread plus trace events — so evals and self-improvement can read what happened and what produced it. Use when asked to "add tracing", "add logging", "persist runs", "stamp traces", "record what the agent did", or "set up observability" for an agent machine, or before writing evals or improving a policy from traces.
+---
+
+# Add traces to an agent machine
+
+Every run should leave two records, both stamped with what produced it:
+
+| Record           | What it is                                                                     | Read by                                              |
+| ---------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| Event log thread | The external inputs the machine consumed, in order. The source of truth        | `replay`, `getDecisionAttempts`, `getUsageFromEvents` |
+| Trace events     | Observations: transitions with `from`, decision requests with offered options  | `foldTraces`, OpenTelemetry, debugging               |
+
+```
+version the machines → pick a store → name threads → stamp → collect trace events → prove replay → hand back
+```
+
+This is step 2 of 4. Before: `loop-to-machine`. Next: `add-evals`, then `improve-machine`.
+
+## Hard rules
+
+- **Traces never change behavior.** Recording is an observer. No branch reads a trace.
+- **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.
+
+## 1. Version the machines
+
+Declare `version` on every machine whose runs you record: the environment and, if there is one, the policy machine.
+
+```ts
+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.
+
+- 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.
+
+## 2. Pick a store
+
+- **Tests and local runs:** `createInMemoryEventLogStore()` from `@statelyai/agent/log`, or write each thread's `result.events` to a JSON file after the run.
+- **Production:** implement `AgentEventLogStore` against your database and check it with `assertEventLogStoreConformance`. Implement the optional `listThreads` so a split can be paged by prefix.
+
+Pass it with a `threadId`. The store is write-ahead: no model call starts until the entries before it are durable.
+
+```ts
+const result = await runAgent(deskMachine, { input, executors, store, threadId, metadata });
+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.
+
+## 3. Name threads
+
+A thread id is how runs are found later. Use a prefix scheme and keep it in one function:
+
+| Runs                     | Thread id                                    |
+| ------------------------ | -------------------------------------------- |
+| Scenario runs for evals  | `<split>:<deciderVersion>:<scenarioId>:r<k>`, `k` = the repeat index |
+| Production               | `prod:<domain id>` (ticket id, session id)   |
+
+`store.listThreads?.({ prefix: "train:careful:" })` then pages through one split of one decider. `listThreads` is optional on a custom store.
+
+## 4. Stamp each run
+
+`metadata` lands on the log's first (`@agent.init`) entry. Put there everything needed to tell two runs' producers apart:
+
+```ts
+const metadata = {
+  environmentVersion: deskMachine.version ?? "unversioned",
+  deciderVersion, // see step 1
+  models: { decider: "openai/gpt-6-luna" }, // the machine's model refs → what the host resolved them to
+  scenario: scenario.id, // eval runs only
+  split: scenario.split, // eval runs only
+};
+```
+
+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`.
+
+## 5. Collect trace events
+
+`onTrace` sees every trace event. Serialize and keep them per thread:
+
+```ts
+import { serializeTraceEvent, type JsonSerializableTraceEvent } from "@statelyai/agent";
+
+const trace: JsonSerializableTraceEvent[] = [];
+const result = await runAgent(deskMachine, { ..., onTrace: (event) => trace.push(serializeTraceEvent(event)) });
+await result.drain();
+
+// For local batches: one file per thread. Encoding keeps colons and path separators out of the name.
+const file = encodeURIComponent(threadId);
+await mkdir("runs", { recursive: true });
+await writeFile(`runs/${file}.events.json`, JSON.stringify(result.events));
+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.
+- **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.
+
+## 6. Prove it
+
+Write these tests, with the stand-in model from `loop-to-machine`:
+
+```ts
+import { getDecisionAttempts, replay } from "@statelyai/agent/log";
+import { foldTraces } from "@statelyai/agent/testing";
+
+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]!.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.
+
+## 7. Hand back
+
+1. Where runs are stored and how thread ids are built.
+2. The stamp fields.
+3. Where trace events go.
+4. The replay test passing.
+5. Next step: `add-evals`.

package/skills/generate-machine/SKILL.md

@@ -31,7 +31,7 @@ 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: `docs/environment-and-policy.md`.
+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).
 
 ## 1. Read the schema
 
@@ -58,7 +58,7 @@ Rules the runtime enforces. Each one maps to a build error or a lint diagnostic:
 - A request invoke resolves with `{ result, messages }`, so `onDone.assign` reads its result from `"{{ event.output.result.<field> }}"` (`"{{ event.output.result }}"` for a plain-text request). A non-request `actors` invoke reads `"{{ event.output.<field> }}"` directly.
 - Every path must reach a `"type": "final"` state, and each final state needs an `output` when `schemas.output` is declared.
 - Do not invent guard or action names. Only `"{{ }}"` guards, `assign`, and `emit` exist unless the host tells you which named guards/actions it implements.
-- Model refs are strings (`"openai/gpt-5.4-mini"`); the host resolves them.
+- Model refs are strings (`"openai/gpt-6-luna"`); the host resolves them.
 - To make a decision a closed choice, add `payloads` to the `agent.decide` input: one payload list per event type, without `type` (`"payloads": { "REFUND": [{ "amount": 20 }, { "amount": 50 }], "ESCALATE": [] }`). The model then picks one listed event instead of writing a payload. A type with no key is offered as `{ type }`; `[]` withholds it.
 - An idle human step can carry `meta.interaction` for the host to render with `getInteraction`: a `label`, `events` (one button per event type), `choices` (one button per full event, `{ "label": "Refund $20", "event": { "type": "REFUND", "amount": 20 } }`, or a context path string holding such a list), and `textEvent` for free text. A bare `"textEvent": "REJECT"` puts the text in a `text` field; `{ "type": "REJECT", "field": "reason" }` names the field. `meta` is not template-evaluated.
 
@@ -102,7 +102,7 @@ Reference config — decision, text request, idle human step, one final state:
   "context": { "ticket": "{{ input.ticket }}" },
   "requests": {
     "draftReply": {
-      "model": "openai/gpt-5.4-mini",
+      "model": "openai/gpt-6-luna",
       "system": "Draft a short, courteous support reply.",
       "prompt": "{{ input.ticket }}",
       "input": {
@@ -124,7 +124,7 @@ Reference config — decision, text request, idle human step, one final state:
         "id": "triageDecision",
         "src": "agent.decide",
         "input": {
-          "model": "openai/gpt-5.4-mini",
+          "model": "openai/gpt-6-luna",
           "system": "Decide whether this ticket needs escalation or a drafted reply.",
           "prompt": "{{ context.ticket }}",
           "allowedEvents": ["ESCALATE", "REPLY"],
@@ -217,7 +217,7 @@ const result = await verifyAgentConfig(candidate, {
     guards: [],
     actions: [],
     events: ["ESCALATE", "REPLY", "APPROVE", "REJECT"],
-    models: ["openai/gpt-5.4-mini"],
+    models: ["openai/gpt-6-luna"],
   },
   explore: {
     inputs: [{ ticket: "Export downloads a 0-byte CSV on Safari." }],

package/skills/graph-engineering/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: graph-engineering
+description: Route an agent-reliability request to the right @statelyai/agent skill and keep the four steps in order — make it a state machine, add traces, add evals, self-improve. Use when asked to "make my agent reliable", "graph engineering", "turn my agent into a state machine and improve it", "where do I start with this agent", or any request that spans more than one of those steps.
+---
+
+# Graph engineering
+
+Four steps, in order. Each one needs the one before it.
+
+| Step | Skill | Done when |
+| --- | --- | --- |
+| 1. Make it a state machine | `loop-to-machine` (existing code) or `generate-machine` (from scratch) | Rules are guards and the sentinel is unreachable (`canReach`). From existing code: the parity report has no unreviewed regressions. From scratch: every `verifyAgentConfig` gate passes |
+| 2. Add traces | `add-traces` | Every run leaves a stamped log thread that replays to its final state |
+| 3. Add evals | `add-evals` | Evals per state at the cheapest level, an objective, baseline numbers per split |
+| 4. Self-improve | `improve-machine` | A pull request with one policy change and its held-out scorecard, or a report that none helped |
+
+## Find where the project is
+
+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.
+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.
+
+Tell the user which step you are starting at and why, in one line, then load that skill.
+
+## Across all steps
+
+- **The environment is people's code.** Rules, guards, invariants, and the sentinel change only by human review. No step rewrites them on its own.
+- **Ground truth scores everything.** Outcomes and effects in the world, labeled by people. A model never grades its own runs.
+- **Ask for labels and rules; decide the mechanics.** Expected outcomes, thresholds, the objective, and the train/held-out split are the user's. File layout, test names, and helper code are yours.
+- **Hand back between steps.** Finish one step's hand-back before starting the next, unless the user asked for several in one go.