@statelyai/agent 2.0.0-alpha.38 → 2.0.0-alpha.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
  3. package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
  4. package/dist/ai-sdk.cjs +4 -4
  5. package/dist/ai-sdk.d.cts +2 -3
  6. package/dist/ai-sdk.d.mts +2 -3
  7. package/dist/ai-sdk.mjs +4 -4
  8. package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
  9. package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
  10. package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
  11. package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
  12. package/dist/effects-B9IvUPVh.mjs +23 -0
  13. package/dist/effects-DrWcUGgc.cjs +34 -0
  14. package/dist/evals.cjs +810 -0
  15. package/dist/evals.d.cts +595 -0
  16. package/dist/evals.d.mts +595 -0
  17. package/dist/evals.mjs +801 -0
  18. package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
  19. package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
  20. package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
  21. package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
  22. package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
  23. package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
  24. package/dist/index.cjs +131 -93
  25. package/dist/index.d.cts +73 -134
  26. package/dist/index.d.mts +73 -134
  27. package/dist/index.mjs +112 -70
  28. package/dist/internal-BzlpzSux.d.cts +14 -0
  29. package/dist/internal-BzlpzSux.d.mts +14 -0
  30. package/dist/log.cjs +2 -3
  31. package/dist/log.d.cts +2 -2
  32. package/dist/log.d.mts +2 -2
  33. package/dist/log.mjs +3 -3
  34. package/dist/machines.cjs +1 -719
  35. package/dist/machines.d.cts +2 -424
  36. package/dist/machines.d.mts +2 -424
  37. package/dist/machines.mjs +2 -709
  38. package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
  39. package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
  40. package/dist/openai.cjs +3 -3
  41. package/dist/openai.d.cts +2 -3
  42. package/dist/openai.d.mts +2 -3
  43. package/dist/openai.mjs +3 -3
  44. package/dist/otel.d.cts +1 -1
  45. package/dist/otel.d.mts +1 -1
  46. package/dist/policy.cjs +77 -0
  47. package/dist/policy.d.cts +143 -0
  48. package/dist/policy.d.mts +143 -0
  49. package/dist/policy.mjs +75 -0
  50. package/dist/{effects-BT_cSY0j.mjs → run-agent-BE7DOWD6.mjs} +150 -184
  51. package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-DHlq87G7.d.mts} +18 -34
  52. package/dist/{effects-DDseYtJk.cjs → run-agent-De3xVFGw.cjs} +149 -201
  53. package/dist/{run-agent-30mH2moE.d.cts → run-agent-Dq0oSFRm.d.cts} +18 -34
  54. package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
  55. package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
  56. package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
  57. package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
  58. package/dist/tanstack-ai.cjs +4 -4
  59. package/dist/tanstack-ai.d.cts +2 -3
  60. package/dist/tanstack-ai.d.mts +2 -3
  61. package/dist/tanstack-ai.mjs +4 -4
  62. package/dist/testing.cjs +122 -996
  63. package/dist/testing.d.cts +36 -695
  64. package/dist/testing.d.mts +36 -695
  65. package/dist/testing.mjs +112 -977
  66. package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
  67. package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
  68. package/dist/trajectory-BFjXaooB.d.cts +96 -0
  69. package/dist/trajectory-BFjXaooB.d.mts +96 -0
  70. package/dist/trajectory-BUXj_1Ue.mjs +152 -0
  71. package/dist/trajectory-CoZSv4wF.cjs +157 -0
  72. package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
  73. package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
  74. package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
  75. package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
  76. package/dist/validate.cjs +4 -4
  77. package/dist/validate.d.cts +2 -2
  78. package/dist/validate.d.mts +2 -2
  79. package/dist/validate.mjs +4 -4
  80. package/dist/{verify-DJHfEfm6.d.cts → verify-BM0sGmsf.d.cts} +42 -6
  81. package/dist/{verify-ChyX6jq0.mjs → verify-CWlg3j7B.mjs} +153 -45
  82. package/dist/{verify-CwlombbC.cjs → verify-Dek6gHCS.cjs} +153 -45
  83. package/dist/{verify-i9Hiwc5g.d.mts → verify-H3Pr2gNw.d.mts} +42 -6
  84. package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
  85. package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
  86. package/docs/advanced.md +5 -5
  87. package/docs/choosing-a-run-mode.md +7 -7
  88. package/docs/debugging.md +6 -8
  89. package/docs/decisions.md +5 -4
  90. package/docs/environment-and-policy.md +1 -1
  91. package/docs/evals.md +57 -43
  92. package/docs/event-log.md +13 -15
  93. package/docs/from-a-loop.md +3 -3
  94. package/docs/generate-machines.md +4 -4
  95. package/docs/hosts.md +20 -27
  96. package/docs/human-in-the-loop.md +5 -8
  97. package/docs/index.md +4 -4
  98. package/docs/judgments.md +5 -7
  99. package/docs/langgraph-comparison.md +6 -6
  100. package/docs/machines-as-data.md +7 -12
  101. package/docs/machines-presets.md +17 -120
  102. package/docs/machines.md +13 -13
  103. package/docs/models-and-providers.md +19 -25
  104. package/docs/multi-agent.md +1 -1
  105. package/docs/observability.md +6 -8
  106. package/docs/persistence.md +10 -20
  107. package/docs/quickstart.md +3 -3
  108. package/docs/statechart-policy-examples.md +1 -1
  109. package/docs/steps.md +5 -6
  110. package/docs/strangler-fig.md +72 -7
  111. package/docs/text-requests.md +10 -12
  112. package/docs/thinking-in-state-machines.md +8 -8
  113. package/docs/tools.md +10 -12
  114. package/docs/upgrading.md +1 -1
  115. package/docs/usage-and-budgets.md +51 -56
  116. package/docs/validate-and-repair.md +9 -14
  117. package/docs/verify.md +53 -7
  118. package/docs/xstate-4-and-5-apps.md +19 -28
  119. package/llms.txt +1 -1
  120. package/package.json +31 -6
  121. package/readme.md +32 -24
  122. package/dist/internal-C3Lqu538.d.cts +0 -43
  123. package/dist/internal-DUcdhk-i.d.mts +0 -43
  124. package/dist/types-DQUOOaZO.d.cts +0 -238
  125. package/dist/types-DQUOOaZO.d.mts +0 -238
  126. package/skills/add-evals/SKILL.md +0 -152
  127. package/skills/add-traces/SKILL.md +0 -152
  128. package/skills/build-machine/SKILL.md +0 -84
  129. package/skills/generate-machine/SKILL.md +0 -335
  130. package/skills/graph-engineering/SKILL.md +0 -43
  131. package/skills/improve-machine/SKILL.md +0 -261
  132. package/skills/improve-machine/reference.md +0 -101
  133. package/skills/loop-to-machine/SKILL.md +0 -205
  134. package/skills/loop-to-machine/policy.md +0 -154
  135. package/skills/loop-to-machine/reference.md +0 -260
package/docs/verify.md CHANGED
@@ -45,7 +45,7 @@ assertAgentMachine(machine, { warnings: true });
45
45
  | `decide-without-events` | error | A state invokes `agent.decide` but neither it nor any ancestor handles any event, so the chosen event can never be delivered. |
46
46
  | `decide-allows-human-event` | error | A decision's literal `allowedEvents` names an event the state or an ancestor handles through a transition tagged `meta: { actor: "human" }`, so the model is never offered it. See [Events a person sends](decisions.md#events-a-person-sends). |
47
47
  | `invoke-without-on-error` | warning | An invoke declares no `onError`, and neither its state nor any ancestor handles an actor error, so a rejected request or actor lands the machine in an error state with no modeled recovery. Add `onError` targeting a `failed` final state or a bounded retry. |
48
- | `direct-object-src` | warning | An invoke `src` is a direct object or machine value that `runToQuiescence` cannot rebind, so it inherits no host executors. |
48
+ | `direct-object-src` | warning | An invoke `src` is a direct object or machine value that `runAgent` cannot rebind, so it inherits no host executors. |
49
49
 
50
50
  ## Test assertions
51
51
 
@@ -75,7 +75,7 @@ test("happy path settles done", async () => {
75
75
  });
76
76
  ```
77
77
 
78
- Guards stay in force throughout. `canReach` and `simulateAgent` traverse the same machine transitions as `runToQuiescence`, so a graph path that a guard rejects never counts as reachable. These tests pin the machine's shape as prompts and models change.
78
+ Guards stay in force throughout. `canReach` and `simulateAgent` traverse the same machine transitions as `runAgent`, so a graph path that a guard rejects never counts as reachable. These tests pin the machine's shape as prompts and models change.
79
79
 
80
80
  ## Deterministic executors
81
81
 
@@ -93,13 +93,13 @@ const machine = emailDrafter.provide({
93
93
 
94
94
  [examples/email-drafter/agent-logic.ts](https://github.com/statelyai/agent/blob/next/examples/email-drafter/agent-logic.ts) drives a full run this way, with fixed values and no model call.
95
95
 
96
- Use deterministic executors when the test should exercise the real `runToQuiescence` path with canned model output. Use [`simulateAgent`](#scripted-playthroughs) when a model-free transition playthrough is enough.
96
+ Use deterministic executors when the test should exercise the real `runAgent` path with canned model output. Use [`simulateAgent`](#scripted-playthroughs) when a model-free transition playthrough is enough.
97
97
 
98
98
  ## Scripted playthroughs
99
99
 
100
100
  `simulateAgent(machine, { input, script, maxSteps? })` runs a deterministic, model-free transition playthrough. The `script` supplies responses as FIFO queues, so runs are reproducible.
101
101
 
102
- This script keys by invoke **src**, not by request name. Executors that run the real `runToQuiescence` path route by request name instead. See [Testing without a provider](evals.md#testing-without-a-provider).
102
+ This script keys by invoke **src**, not by request name. Executors that run the real `runAgent` path route by request name instead. See [Testing without a provider](evals.md#testing-without-a-provider).
103
103
 
104
104
  - `decisions` holds the `ChosenEvent` to apply per decision, keyed by decision src, usually `agent.decide`.
105
105
  - `text` holds output values for text requests, keyed by request src.
@@ -171,13 +171,13 @@ settled?.resolvedRequest; // { kind: 'text', src: 'parse', id: 'parse', outcome:
171
171
 
172
172
  ## Branch exploration
173
173
 
174
- `explorePaths(machine, { input, maxDepth?, maxPaths?, maxNodes?, budget?, outputs?, errors?, payloads?, dedupeBy?, interleave?, children?, timers?, usage? })` enumerates decision and external-event branches without a model, and reports coverage.
174
+ `explorePaths(machine, { input, maxDepth?, maxPaths?, maxNodes?, budget?, outputs?, errors?, payloads?, dedupeBy?, interleave?, children?, timers?, usage?, steps? })` enumerates decision and external-event branches without a model, and reports coverage.
175
175
 
176
176
  - At each decision, it forks one branch per candidate event. Guard-rejected candidates count in `prunedByGuard` and are not explored.
177
177
  - A decision with no candidate the snapshot takes, because its guards refuse every one or the closed choice offers nothing, exhausts as it does in a live run. That branch records `{ type: 'xstate.error.actor', actorId }` and takes the invoke's `onError`. With no `onError`, it ends in an `error` terminal.
178
178
  - At an idle wait, it forks one branch per externally accepted event and per armed timer. See [Timers](#timers).
179
179
  - `outputs` is a map of output lists, keyed by src: a text request's src 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`. A longer list forks one branch per output. See [Payloads and invoke outputs](#payloads-and-invoke-outputs).
180
- - A src with one canned output resolves without a fork, so it does not appear in the path.
180
+ - A src with one canned output resolves without a fork, so it does not appear in the path. `steps: true` records it. See [Steps](#steps).
181
181
  - Each `done` terminal carries the machine's `output`, so one report lists every output the search reached.
182
182
  - A src with no `outputs` entry halts that branch with a `needs-output` terminal instead of throwing. The terminal's `missingSrc` names it.
183
183
  - `errors` is a map of canned failures per src. A src listed there forks an extra branch where that invoke is rejected, so states behind an `onError` are explored. A decision keys on its src, usually `agent.decide`, or on its invoke id; its success branch stays the per-candidate-event fork, so the failure is explored in addition to the candidates. The failure and the candidates are sibling branches: each spends one level of `maxDepth`.
@@ -219,6 +219,29 @@ const report = await explorePaths(machine, {
219
219
  // report.terminals → one path per branch: the parsed state and the onError state
220
220
  ```
221
221
 
222
+ ### Steps
223
+
224
+ `path` lists branch points only. `steps: true` adds `steps` to each terminal: every macrostep from the start, as an `ExploreStep`.
225
+
226
+ - `event`: the event the step processed. A host event, a fork, a canned output settling (`xstate.done.actor` or `xstate.error.actor`), or `xstate.init` for the start.
227
+ - `state`: the state value after the step.
228
+ - `started`: srcs of the invokes and spawned actors that started in the step. An actor restarted under the same id counts again.
229
+ - `settled`: srcs of the actors that finished, done or error, in the step.
230
+
231
+ ```ts no-check
232
+ const report = await explorePaths(loopMachine, {
233
+ outputs: { turn: [{ kind: "continue" }] },
234
+ steps: true,
235
+ });
236
+ // report.terminals[0].steps → [
237
+ // { event: { type: "xstate.init" }, state: "running", started: ["turn"], settled: [] },
238
+ // { event: { type: "xstate.done.actor", actorId: "turn", … }, state: "running", started: ["turn"], settled: ["turn"] },
239
+ // …
240
+ // ]
241
+ ```
242
+
243
+ Steps are off by default: they cost memory for every step of every path. Steps cover the root machine. With `children: "coupled"`, a child's own moves show up through the events and outputs they deliver to the root.
244
+
222
245
  ### Payloads and invoke outputs
223
246
 
224
247
  By default, events are applied as `{ type }`. A guard that reads the payload, such as `event.amount <= 100`, rejects every such event, so its target is never explored. Supply payloads to explore it.
@@ -416,6 +439,7 @@ Set `budget.ms` under the test runner's timeout, so a long search fails its asse
416
439
 
417
440
  - A state path or state-node ID.
418
441
  - A snapshot predicate, `(snapshot) => boolean`, for a property no single state names: a context invariant, a tag, a state plus context.
442
+ - An ordering, `{ after, reach }`, for a rule about order: "no turn starts after STOP". See [Ordering targets](#ordering-targets).
419
443
 
420
444
  ```ts no-check
421
445
  const violation = await canReach(
@@ -467,6 +491,28 @@ const failure = await canReach(machine, "failed", {
467
491
  // failure.reachable → true; failure.witness → [{ type: 'xstate.error.actor', actorId: 'parse' }]
468
492
  ```
469
493
 
494
+ ### Ordering targets
495
+
496
+ A snapshot predicate sees one snapshot, so it cannot ask what happened earlier on the path. An ordering target can:
497
+
498
+ ```ts no-check
499
+ const turnAfterStop = await canReach(
500
+ loopMachine,
501
+ { after: "STOP", reach: (step) => step.started.includes("turn") },
502
+ { outputs: { turn: [{ kind: "continue" }] }, interleave: "pending" },
503
+ );
504
+ // turnAfterStop.reachable → false with complete: true: no turn starts after STOP
505
+ ```
506
+
507
+ - `after` and `reach` match [steps](#steps). `after` is an event type or a step predicate.
508
+ - `reach` is checked on each step after the first step that matched `after`, not on that step itself.
509
+ - `after` and `reach` may read an event's payload, so an event with no schema is unexpanded until `payloads` lists its variants, even when no transition reads it. A timer's step carries the event the timer delivers.
510
+ - The witness is the event sequence to the first violation.
511
+ - A turn already running when STOP arrives started before it, so it is not a violation. Check that turn with `settled` if the rule covers it.
512
+ - `dedupeBy` stays sound: the search adds "`after` has matched" to each key, so a snapshot reached before and after the trigger is explored both ways.
513
+ - Test the rule with a mutant that breaks it (a loop that starts another turn after STOP), as with a loosened guard.
514
+ - Don't match strings over `terminal.path` for an ordering rule: it lists branch points only and names actors by generated id.
515
+
470
516
  ## CI checks
471
517
 
472
518
  Everything on this page runs without an API key, so a small script is enough for CI or a generation loop.
@@ -486,7 +532,7 @@ For machines authored as data, validate the config with `validateAgentConfig(con
486
532
  - [Crash testing](persistence.md#crash-testing): `checkCrashRecovery` kills a run at every log append and in-flight effect, and checks each resume.
487
533
  - [Debugging](debugging.md): scripted reproduction and the diagnostic codes in context.
488
534
  - [Evals](evals.md): scoring runs on output, trajectory, and budget.
489
- - [Quickstart](quickstart.md#define-and-run-one-artifact): a plain-function executor for `runToQuiescence`.
535
+ - [Quickstart](quickstart.md#define-and-run-one-artifact): a plain-function executor for `runAgent`.
490
536
  - [Machines as data](machines-as-data.md): verifying a machine lowered from a config.
491
537
  - [Migrating from a hand-rolled loop](from-a-loop.md): pinning behavior across a refactor.
492
538
  - [examples/verification](https://github.com/statelyai/agent/blob/next/examples/verification/index.ts): every API on this page run over one refund-approval machine, with no API key, including `canReach` proving that an over-limit payout without human approval is unreachable.
@@ -7,7 +7,7 @@ description: Isolate @statelyai/agent behind a workspace package so an app on XS
7
7
 
8
8
  <!-- versions from package.json version and peerDependencies.xstate -->
9
9
 
10
- `@statelyai/agent` peers on exactly `xstate@6.0.0-beta.0`. An app already using XState 4 or 5 for its own machines cannot install both versions into one `node_modules` tree and have each resolve the one it needs. This page isolates the agent in its own workspace package so the app keeps its XState version and never imports XState 6.
10
+ The current source of `@statelyai/agent` peers on exactly `xstate@6.0.0-beta.2`. The published `2.0.0-alpha.29` release used in this recipe peers on `xstate@6.0.0-alpha.69`; use that matching pair until a beta.2-compatible agent release is published. An app already using XState 4 or 5 for its own machines cannot install both versions into one `node_modules` tree and have each resolve the one it needs. This page isolates the agent in its own workspace package so the app keeps its XState version and never imports XState 6.
11
11
 
12
12
  The same page applies to an app with no XState at all that cannot take a prerelease dependency in its main tree.
13
13
 
@@ -34,7 +34,7 @@ Put the agent in a workspace package that owns its own dependencies, and give th
34
34
  "@statelyai/agent": "2.0.0-alpha.29",
35
35
  "@ai-sdk/openai": "^4.0.0",
36
36
  "ai": "^7.0.128",
37
- "xstate": "6.0.0-beta.0",
37
+ "xstate": "6.0.0-alpha.69",
38
38
  "zod": "^4.4.3"
39
39
  }
40
40
  }
@@ -48,7 +48,7 @@ One async function in, one JSON-safe object out. Everything XState is inside it.
48
48
 
49
49
  ```ts no-check
50
50
  // packages/agent/src/index.ts
51
- import { createAgentRuntime, runToQuiescence } from "@statelyai/agent";
51
+ import { runAgent } from "@statelyai/agent";
52
52
  import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
53
53
  import { models, generationMachine } from "./machine.js";
54
54
 
@@ -72,13 +72,11 @@ export async function runGeneration(
72
72
  input: GenerationInput,
73
73
  deps: GenerationDeps,
74
74
  ): Promise<GenerationOutput> {
75
- const result = await runToQuiescence(
76
- createAgentRuntime(generationMachine(deps.lookup), {
77
- executors: createAiSdkExecutors({ models }),
78
- onTransition: (snapshot) => deps.onProgress?.(String(snapshot.value)),
79
- }),
80
- { input },
81
- );
75
+ const result = await runAgent(generationMachine(deps.lookup), {
76
+ executors: createAiSdkExecutors({ models }),
77
+ onTransition: (snapshot) => deps.onProgress?.(String(snapshot.value)),
78
+ input,
79
+ });
82
80
  if (result.status !== "done") {
83
81
  throw new Error(`Generation did not complete: ${result.status}`);
84
82
  }
@@ -109,9 +107,9 @@ export async function POST(request: Request) {
109
107
 
110
108
  ## What can cross the boundary
111
109
 
112
- Persisted snapshots are JSON. `result.persist()` returns a plain JSON value, and `runToQuiescence(createAgentRuntime(machine, {}), { snapshot, event })` takes one back, so a paused run can be stored by the app, in its own database, and resumed by a later call into the package. Pair `snapshot` with the `event` that unblocks the idle state: a resume with `snapshot` alone starts the run back at the same wait.
110
+ Persisted snapshots are JSON. `result.persist()` returns a plain JSON value, and `runAgent(machine, { snapshot, event })` takes one back, so a paused run can be stored by the app, in its own database, and resumed by a later call into the package. Pair `snapshot` with the `event` that unblocks the idle state: a resume with `snapshot` alone starts the run back at the same wait.
113
111
 
114
- <!-- runToQuiescence snapshot/event resume from src/run-agent.ts; exercised by src/docs-integration-recipes.test.ts -->
112
+ <!-- runAgent snapshot/event resume from src/run-agent.ts; exercised by src/docs-integration-recipes.test.ts -->
115
113
 
116
114
  ```ts no-check
117
115
  // Inside the package: the app stores and returns the value, and never reads it.
@@ -121,12 +119,10 @@ export async function startGeneration(
121
119
  input: GenerationInput,
122
120
  deps: GenerationDeps,
123
121
  ): Promise<{ snapshot: unknown }> {
124
- const result = await runToQuiescence(
125
- createAgentRuntime(generationMachine(deps.lookup), {
126
- executors: createAiSdkExecutors({ models }),
127
- }),
128
- { input },
129
- );
122
+ const result = await runAgent(generationMachine(deps.lookup), {
123
+ executors: createAiSdkExecutors({ models }),
124
+ input,
125
+ });
130
126
  return { snapshot: result.status === "idle" ? result.persist() : null };
131
127
  }
132
128
 
@@ -135,16 +131,11 @@ export async function resumeGeneration(
135
131
  answer: string,
136
132
  deps: GenerationDeps,
137
133
  ): Promise<GenerationOutput> {
138
- const result = await runToQuiescence(
139
- createAgentRuntime(generationMachine(deps.lookup), {
140
- executors: createAiSdkExecutors({ models }),
141
- }),
142
- {
143
- // Opaque to the app, typed again here at the package boundary.
144
- snapshot: snapshot as Snapshot<unknown>,
145
- event: { type: "ANSWER", answer },
146
- },
147
- );
134
+ const result = await runAgent(generationMachine(deps.lookup), {
135
+ executors: createAiSdkExecutors({ models }), // Opaque to the app, typed again here at the package boundary.
136
+ snapshot: snapshot as Snapshot<unknown>,
137
+ event: { type: "ANSWER", answer },
138
+ });
148
139
  if (result.status !== "done") {
149
140
  throw new Error(`Generation did not complete: ${result.status}`);
150
141
  }
package/llms.txt CHANGED
@@ -21,7 +21,7 @@ Not v5: transitions are plain functions returning `{ target, context }` (no `ass
21
21
  - [Tools](docs/tools.md): Define tools, attach them to a text request, and let the host run the tool loop while the machine stays in one state.
22
22
  - [Judgments with the AI SDK](docs/judgments.md): Ask classification, grading, relevance, and yes/no questions with the AI SDK's experimental_decide and Jev, and branch on the typed answers in a machine.
23
23
  - [Messages](docs/messages.md): Build and store conversation history as a parts-based message model that mirrors the AI SDK without depending on it.
24
- - [Preset machines](docs/machines-presets.md): Factories for proven agent shapes (tool loop, sequential, router, parallel, loop, supervisor, handoff) that return ordinary, inspectable agent machines.
24
+ - [Preset machines](docs/machines-presets.md): `createApprovalBatchMachine`, which gates one model turn's tool calls on approval.
25
25
  - [Choosing a run mode](docs/choosing-a-run-mode.md): Three ways to execute the same agent machine, what each one owns, and which to reach for.
26
26
  - [Hosts and executors](docs/hosts.md): Give an agent machine the executor functions that call a model, and choose between the shipped AI SDK adapter or your own.
27
27
  - [Use in any stack](docs/any-stack.md): One agent machine runs unchanged in a local script, an HTTP route, or an edge runtime. Only the executors are host-specific.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statelyai/agent",
3
- "version": "2.0.0-alpha.38",
3
+ "version": "2.0.0-alpha.39",
4
4
  "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
5
5
  "keywords": [
6
6
  "agent",
@@ -21,7 +21,6 @@
21
21
  "files": [
22
22
  "dist",
23
23
  "schemas",
24
- "skills",
25
24
  "docs",
26
25
  "!docs/snippet-globals.ts",
27
26
  "llms.txt",
@@ -36,6 +35,9 @@
36
35
  "ai-sdk": [
37
36
  "./dist/ai-sdk.d.mts"
38
37
  ],
38
+ "evals": [
39
+ "./dist/evals.d.mts"
40
+ ],
39
41
  "log": [
40
42
  "./dist/log.d.mts"
41
43
  ],
@@ -48,6 +50,9 @@
48
50
  "otel": [
49
51
  "./dist/otel.d.mts"
50
52
  ],
53
+ "policy": [
54
+ "./dist/policy.d.mts"
55
+ ],
51
56
  "tanstack-ai": [
52
57
  "./dist/tanstack-ai.d.mts"
53
58
  ],
@@ -80,6 +85,16 @@
80
85
  "default": "./dist/ai-sdk.cjs"
81
86
  }
82
87
  },
88
+ "./evals": {
89
+ "import": {
90
+ "types": "./dist/evals.d.mts",
91
+ "default": "./dist/evals.mjs"
92
+ },
93
+ "require": {
94
+ "types": "./dist/evals.d.cts",
95
+ "default": "./dist/evals.cjs"
96
+ }
97
+ },
83
98
  "./log": {
84
99
  "import": {
85
100
  "types": "./dist/log.d.mts",
@@ -120,6 +135,16 @@
120
135
  "default": "./dist/otel.cjs"
121
136
  }
122
137
  },
138
+ "./policy": {
139
+ "import": {
140
+ "types": "./dist/policy.d.mts",
141
+ "default": "./dist/policy.mjs"
142
+ },
143
+ "require": {
144
+ "types": "./dist/policy.d.cts",
145
+ "default": "./dist/policy.cjs"
146
+ }
147
+ },
123
148
  "./tanstack-ai": {
124
149
  "import": {
125
150
  "types": "./dist/tanstack-ai.d.mts",
@@ -168,7 +193,7 @@
168
193
  "@opentelemetry/api": "^1.9.1",
169
194
  "@opentelemetry/context-async-hooks": "^2.12.0",
170
195
  "@opentelemetry/sdk-trace-base": "^2.12.0",
171
- "@statelyai/sdk": "0.45.0",
196
+ "@statelyai/sdk": "0.47.0",
172
197
  "@tanstack/ai": "^0.66.0",
173
198
  "@types/node": "^22.20.5",
174
199
  "@types/react": "^19.3.0",
@@ -187,7 +212,7 @@
187
212
  "twoslash": "^0.3.9",
188
213
  "typescript": "^7.0.2",
189
214
  "vitest": "^5.0.3",
190
- "xstate": "6.0.0-beta.0",
215
+ "xstate": "6.0.0-beta.2",
191
216
  "zod": "^4.6.5"
192
217
  },
193
218
  "peerDependencies": {
@@ -196,7 +221,7 @@
196
221
  "ai": "*",
197
222
  "ajv": "*",
198
223
  "openai": "*",
199
- "xstate": "6.0.0-beta.0"
224
+ "xstate": "6.0.0-beta.2"
200
225
  },
201
226
  "peerDependenciesMeta": {
202
227
  "@opentelemetry/api": {
@@ -227,7 +252,7 @@
227
252
  "proto:prefabs": "tsx .scratch/prefabs/demo.ts",
228
253
  "docs:check": "tsx scripts/check-docs-snippets.ts",
229
254
  "typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples && pnpm run typecheck:example-packages",
230
- "typecheck:src": "tsc --noEmit",
255
+ "typecheck:src": "tsc --noEmit && tsc -p tsconfig.exact-optional.json",
231
256
  "typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",
232
257
  "typecheck:example-packages": "pnpm run build && tsc -p examples/next-host --noEmit && tsc -p examples/tanstack-ai-stream --noEmit && tsc -p examples/cloudflare-agent-host --noEmit && tsc -p examples/cloudflare-workers-ai-host --noEmit && tsc -p demo --noEmit",
233
258
  "test:cloudflare": "pnpm --filter @statelyai/example-cloudflare-agent-host test && pnpm --filter @statelyai/example-cloudflare-workers-ai-host test",
package/readme.md CHANGED
@@ -8,7 +8,7 @@ What you get:
8
8
 
9
9
  - **Proofs with no model.** Put the rule that must never break behind a sentinel state, then `canReach(machine, "refundedOverLimit", options)` returns `reachable: false` and `complete: true` with no API key. See [Testing and verification](https://github.com/statelyai/agent/blob/next/docs/verify.md).
10
10
  - **Resume and replay from the event log.** A paused run resumes with `runAgent(machine, { snapshot, event })`, and `replay(machine, result.events)` rebuilds any point of a run with no model calls. See [The event log](https://github.com/statelyai/agent/blob/next/docs/event-log.md).
11
- - **Checked ports.** `createRecorder` records the old loop's model and tool calls, `compareRecordings` replays them against the machine, and `compareRuns` labels every scenario `same`, `intended`, or `regression`. See [Parity with the code you replace](https://github.com/statelyai/agent/blob/next/docs/evals.md#parity-with-the-code-you-replace).
11
+ - **Checked ports.** `checkParity` records the old code's side effects, replays them against the machine, and reports every scenario where the two differ. `compareRuns` labels outcome-level differences `same`, `intended`, or `regression`. See [Parity with the code you replace](https://github.com/statelyai/agent/blob/next/docs/evals.md#parity-with-the-code-you-replace).
12
12
 
13
13
  The machine is also a diagram: stream any run to the Stately inspector with `runAgent`'s `inspect` option. See [Inspect a run](https://github.com/statelyai/agent/blob/next/docs/observability.md#inspect-a-run).
14
14
 
@@ -32,8 +32,8 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
32
32
  ### Brownfield: an existing agent
33
33
 
34
34
  - **Wrap an existing workflow, then carve it.** `wrapWorkflow` runs an async workflow unchanged inside a machine. In minutes and with no rewrite, you get inspection, traces, the event log, and a recorded baseline. Reliability proofs such as `canReach` arrive per phase, as each phase moves into states, with `checkParity` against the original after each. See [Strangler-fig retrofit](https://github.com/statelyai/agent/blob/next/docs/strangler-fig.md).
35
- - **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](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md). A coding agent does it with the shipped `loop-to-machine` skill (see [Agent skills](#agent-skills)): "Use the loop-to-machine skill to convert `src/support-agent.ts` to a machine."
36
- - **Let an agent improve its own logic (experimental).** 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](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md) and the [`improve-machine` skill](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md).
35
+ - **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](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md). A coding agent does it with the `loop-to-machine` skill (see [Agent skills](#agent-skills)): "Use the loop-to-machine skill to convert `src/support-agent.ts` to a machine."
36
+ - **Let an agent improve its own logic (experimental).** 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](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md) and the [`improve-machine` skill](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md).
37
37
 
38
38
  ## Environment and policy
39
39
 
@@ -43,13 +43,13 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
43
43
 
44
44
  ## Install
45
45
 
46
- <!-- install command matching the package prerelease channel and package.json peers -->
46
+ <!-- Match the published agent release with its published XState peer. -->
47
47
 
48
48
  ```sh
49
- pnpm add @statelyai/agent@alpha xstate@6.0.0-beta.0 zod
49
+ pnpm add @statelyai/agent@2.0.0-alpha.38 xstate@6.0.0-beta.0 zod
50
50
  ```
51
51
 
52
- XState is pinned while its experimental durable restoration API evolves.
52
+ This is the published pair as of November 11, 2026. This source checkout requires XState `6.0.0-beta.2`; use that version when building the checkout. XState is pinned while its experimental durable restoration API evolves.
53
53
 
54
54
  For the optional Vercel AI SDK executor:
55
55
 
@@ -75,7 +75,7 @@ Upgrading from an earlier alpha: see [Upgrading between alphas](https://github.c
75
75
 
76
76
  Requirements:
77
77
 
78
- - Node 22 or newer, and XState exactly `6.0.0-beta.0`.
78
+ - Node 22 or newer. This source checkout requires XState exactly `6.0.0-beta.2`; the published release above requires `6.0.0-beta.0`.
79
79
  - TypeScript 5.4 or newer. Older versions accept the code, but callback parameters in `createMachine` silently become `any`.
80
80
  - A [Standard Schema](https://standardschema.dev) library: zod 4, zod 3.24 or newer, Valibot, or ArkType. `setupAgent` throws `invalid-schema` for zod 3.23 and earlier.
81
81
  - The package is ESM-first. CommonJS builds are published too, so `require()` works. Subpath imports (`@statelyai/agent/testing`) resolve under every `moduleResolution`, including `node`.
@@ -84,30 +84,38 @@ Requirements:
84
84
 
85
85
  An app that already uses XState 4 or 5 keeps it: put the agent in its own workspace package. See [Use in an XState 4 or 5 app](https://github.com/statelyai/agent/blob/next/docs/xstate-4-and-5-apps.md). If both versions land in one `node_modules`, the package fails with errors that do not mention a version:
86
86
 
87
- | Error | Cause |
88
- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
89
- | `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
90
- | `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
91
- | `unmet peer dependency "xstate@6.0.0-beta.0"` (pnpm, npm) or `has incorrect peer dependency "xstate@6.0.0-beta.0"` (yarn 1) | The install's only warning of the two above |
87
+ | Error | Cause |
88
+ | ---------------------------------------------------- | ------------------------------------------- |
89
+ | `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
90
+ | `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
91
+ | An unmet or incorrect XState peer dependency warning | The install's only warning of the two above |
92
92
 
93
93
  ## Agent skills
94
94
 
95
- The package ships agent skills in `node_modules/@statelyai/agent/skills/`, and its docs in `node_modules/@statelyai/agent/docs/` with an index in `llms.txt`. Copy the skills into your coding agent's skills directory (for Claude Code, `.claude/skills/`):
95
+ The agent skills live in [statelyai/skills](https://github.com/statelyai/skills), in the `stately-agent` plugin. The package ships its docs in `node_modules/@statelyai/agent/docs/` with an index in `llms.txt`.
96
+
97
+ In Claude Code:
98
+
99
+ ```text
100
+ /plugin marketplace add statelyai/skills
101
+ /plugin install stately-agent@stately
102
+ ```
103
+
104
+ For other coding agents:
96
105
 
97
106
  ```sh
98
- mkdir -p .claude/skills
99
- cp -R node_modules/@statelyai/agent/skills/* .claude/skills/
107
+ npx skills add statelyai/skills
100
108
  ```
101
109
 
102
- | Skill | What it does |
103
- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
104
- | [`graph-engineering`](https://github.com/statelyai/agent/blob/next/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill |
105
- | [`loop-to-machine`](https://github.com/statelyai/agent/blob/next/skills/loop-to-machine/SKILL.md) | Converts existing agent code into a machine and checks parity with `compareRuns` |
106
- | [`build-machine`](https://github.com/statelyai/agent/blob/next/skills/build-machine/SKILL.md) | Builds a TypeScript machine from a spec and proves its invariants |
107
- | [`generate-machine`](https://github.com/statelyai/agent/blob/next/skills/generate-machine/SKILL.md) | Authors a JSON policy machine from scratch and runs `verifyAgentConfig` |
108
- | [`add-traces`](https://github.com/statelyai/agent/blob/next/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
109
- | [`add-evals`](https://github.com/statelyai/agent/blob/next/skills/add-evals/SKILL.md) | Writes evals per state, at the cheapest level that catches the failure |
110
- | [`improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md) | Experimental. Improves a policy from traces; a person reviews the pull request |
110
+ | Skill | What it does |
111
+ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
112
+ | [`graph-engineering`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill |
113
+ | [`loop-to-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/loop-to-machine/SKILL.md) | Converts existing agent code into a machine and checks parity with `compareRuns` |
114
+ | [`build-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/build-machine/SKILL.md) | Builds a TypeScript machine from a spec and proves its invariants |
115
+ | [`generate-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/generate-machine/SKILL.md) | Authors a JSON policy machine from scratch and runs `verifyAgentConfig` |
116
+ | [`add-traces`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
117
+ | [`add-evals`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-evals/SKILL.md) | Writes evals per state, at the cheapest level that catches the failure |
118
+ | [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md) | Experimental. Improves a policy from traces; a person reviews the pull request |
111
119
 
112
120
  ## Quick start
113
121
 
@@ -1,43 +0,0 @@
1
- import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.cjs";
2
- import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
3
- //#region src/machines/internal.d.ts
4
- /**
5
- * The machine type a preset factory returns: its context, event union, input
6
- * and output are all concrete, so callers get typed run input and
7
- * output instead of `AnyStateMachine`. The remaining slots (children, state
8
- * value/tags/config, source maps) are left permissive — a preset builds its
9
- * states dynamically, so there is no literal state schema to infer.
10
- *
11
- * @internal
12
- */
13
- type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
14
- /** One delegated unit of work, lowered to an inline text request. */
15
- interface PresetRequestEntry {
16
- /** What this entry is for. Shown to the routing/supervising model. */
17
- description?: string;
18
- /** System prompt for this entry's model call. */
19
- instructions?: string;
20
- /** Model ref (or `models` alias). Falls back to the factory's `model`. */
21
- model?: string;
22
- /** Structured output schema. Omitted means plain text. */
23
- outputSchema?: StandardSchemaV1;
24
- /** Tools the host runs inside this one request. */
25
- tools?: AgentTools;
26
- /** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
27
- maxSteps?: number;
28
- }
29
- /** One delegated unit of work, lowered to an invoked child machine. */
30
- interface PresetMachineEntry {
31
- /** What this entry is for. Shown to the routing/supervising model. */
32
- description?: string;
33
- /** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
34
- machine: AnyStateMachine;
35
- /** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
36
- input?: (args: {
37
- prompt: string;
38
- }) => unknown;
39
- }
40
- /** A route/branch/worker/agent entry: an inline request, or a child machine. */
41
- type PresetEntry = PresetRequestEntry | PresetMachineEntry;
42
- //#endregion
43
- export { PresetRequestEntry as i, PresetMachine as n, PresetMachineEntry as r, PresetEntry as t };
@@ -1,43 +0,0 @@
1
- import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.mjs";
2
- import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
3
- //#region src/machines/internal.d.ts
4
- /**
5
- * The machine type a preset factory returns: its context, event union, input
6
- * and output are all concrete, so callers get typed run input and
7
- * output instead of `AnyStateMachine`. The remaining slots (children, state
8
- * value/tags/config, source maps) are left permissive — a preset builds its
9
- * states dynamically, so there is no literal state schema to infer.
10
- *
11
- * @internal
12
- */
13
- type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
14
- /** One delegated unit of work, lowered to an inline text request. */
15
- interface PresetRequestEntry {
16
- /** What this entry is for. Shown to the routing/supervising model. */
17
- description?: string;
18
- /** System prompt for this entry's model call. */
19
- instructions?: string;
20
- /** Model ref (or `models` alias). Falls back to the factory's `model`. */
21
- model?: string;
22
- /** Structured output schema. Omitted means plain text. */
23
- outputSchema?: StandardSchemaV1;
24
- /** Tools the host runs inside this one request. */
25
- tools?: AgentTools;
26
- /** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
27
- maxSteps?: number;
28
- }
29
- /** One delegated unit of work, lowered to an invoked child machine. */
30
- interface PresetMachineEntry {
31
- /** What this entry is for. Shown to the routing/supervising model. */
32
- description?: string;
33
- /** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
34
- machine: AnyStateMachine;
35
- /** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
36
- input?: (args: {
37
- prompt: string;
38
- }) => unknown;
39
- }
40
- /** A route/branch/worker/agent entry: an inline request, or a child machine. */
41
- type PresetEntry = PresetRequestEntry | PresetMachineEntry;
42
- //#endregion
43
- export { PresetRequestEntry as i, PresetMachine as n, PresetMachineEntry as r, PresetEntry as t };