@statelyai/agent 2.0.0-alpha.37 → 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 +51 -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 +136 -98
  25. package/dist/index.d.cts +73 -134
  26. package/dist/index.d.mts +73 -134
  27. package/dist/index.mjs +117 -75
  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 +6 -5
  90. package/docs/environment-and-policy.md +1 -1
  91. package/docs/evals.md +57 -43
  92. package/docs/event-log.md +14 -16
  93. package/docs/from-a-loop.md +3 -3
  94. package/docs/generate-machines.md +4 -4
  95. package/docs/hosts.md +22 -29
  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 +12 -17
  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 +15 -25
  107. package/docs/quickstart.md +4 -4
  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/decisions.md CHANGED
@@ -52,7 +52,7 @@ deciding: {
52
52
 
53
53
  The `allowedEvents` list is typed against the machine's user-authored event schema, so a typo is a compile error. Framework events such as `@agent.usage` can be handled by the machine but are never model-facing candidates. Listing events explicitly also makes the candidate set visible in the machine.
54
54
 
55
- > **Note:** `agent.decide` needs a snapshot-aware host such as `runToQuiescence` to know which events are currently legal. With a [long-lived actor](choosing-a-run-mode.md#long-lived-actor), list `allowedEvents` explicitly. Wildcards and the omitted default cannot expand there.
55
+ > **Note:** `agent.decide` needs a snapshot-aware host such as `runAgent` to know which events are currently legal. With a [long-lived actor](choosing-a-run-mode.md#long-lived-actor), list `allowedEvents` explicitly. Wildcards and the omitted default cannot expand there.
56
56
 
57
57
  ### `allowedEvents` patterns
58
58
 
@@ -100,7 +100,7 @@ Guards are transition functions that return `undefined`. See [Transitions](machi
100
100
 
101
101
  The candidate set is the `allowedEvents` list intersected with the events the state statically accepts. After the model picks one, `snapshot.can(event)` decides whether it is legal in the current snapshot. A chosen `ASK` on the final turn is rejected, and the model is asked again.
102
102
 
103
- `runToQuiescence` performs this check for you. When you call `resolveDecision` directly with a [long-lived actor](choosing-a-run-mode.md#long-lived-actor), pass the check through `canTake`:
103
+ `runAgent` performs this check for you. When you call `resolveDecision` directly with a [long-lived actor](choosing-a-run-mode.md#long-lived-actor), pass the check through `canTake`:
104
104
 
105
105
  ```ts
106
106
  import { resolveDecision } from "@statelyai/agent";
@@ -170,7 +170,7 @@ Retry behavior:
170
170
 
171
171
  Core validates and retries. It never calls a model. Coercing the model into choosing exactly one option is the host's responsibility. The shipped AI SDK, OpenAI, and TanStack AI executors offer two modes, set by the `decideMode` option on each adapter:
172
172
 
173
- - `'object'` (default for object payloads): one structured-output call. An open choice answers `{ event }`, where `event` is one candidate event, `type` included. Root unions of object payloads become separate event variants. A closed choice answers `{ choice }`, an enum of option ids. The answer holds one event by construction.
173
+ - `'object'` (default for object payloads): one structured-output call. An open choice answers `{ event }`, where `event` is one candidate event, `type` included. Root unions of object payloads become separate event variants. A closed choice answers `{ choice }`, an enum of option ids. The schema allows only one event per answer.
174
174
  - `'tool'`: one tool per candidate event under a forced tool choice. Parallel tool calls are turned off where the provider allows it, and an answer that still calls more than one tool is rejected.
175
175
  - A function of the request picks the mode per request. Returning `undefined` uses the default: `'object'` when every payload can be represented as object variants, otherwise `'tool'`. This avoids unsupported `allOf` schemas in strict structured-output providers.
176
176
 
@@ -375,7 +375,8 @@ A decision model such as Jev answers only closed choices. `'pick-then-fill'` tur
375
375
  A decision can be answered by another machine: a policy that applies a rule when the facts are enough and asks a model only for the rest. `createPolicyDecider` turns a policy machine into a decide executor.
376
376
 
377
377
  ```ts no-check
378
- import { createPolicyDecider, runAgent } from "@statelyai/agent";
378
+ import { runAgent } from "@statelyai/agent";
379
+ import { createPolicyDecider } from "@statelyai/agent/policy";
379
380
 
380
381
  const decide = createPolicyDecider(policyMachine, { executors: modelExecutors });
381
382
 
@@ -408,7 +409,7 @@ A machine does not have to know about AI. `decideNext` asks a model to pick one
408
409
  - It never sends. The host sends the event, after checking `can` again, because the actor may have moved while the model was choosing.
409
410
 
410
411
  ```ts
411
- import { decideNext } from "@statelyai/agent";
412
+ import { decideNext } from "@statelyai/agent/policy";
412
413
  import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
413
414
  import { openai } from "@ai-sdk/openai";
414
415
  import { createActor, createMachine } from "xstate";
@@ -182,7 +182,7 @@ The split pays off when there is a policy worth learning. Skip it in these cases
182
182
  - [Machines as data](machines-as-data.md): the config format and `describeMachine`.
183
183
  - [Testing and verification](verify.md): `canReach`, `explorePaths`, and payload variants.
184
184
  - [Event log](event-log.md) and [Persistence](persistence.md): stores, threads, and replay.
185
- - The [`graph-engineering`](https://github.com/statelyai/agent/blob/next/skills/graph-engineering/SKILL.md) skill routes existing code to [`loop-to-machine`](https://github.com/statelyai/agent/blob/next/skills/loop-to-machine/SKILL.md), which converts the loop and checks parity with `compareRuns`. It routes new policies to [`generate-machine`](https://github.com/statelyai/agent/blob/next/skills/generate-machine/SKILL.md). Then [`add-traces`](https://github.com/statelyai/agent/blob/next/skills/add-traces/SKILL.md) persists runs, [`add-evals`](https://github.com/statelyai/agent/blob/next/skills/add-evals/SKILL.md) writes evaluations for each state, and [`improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md) proposes a pull request from traces, or reports that no candidate beat the current policy.
185
+ - The [`graph-engineering`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/graph-engineering/SKILL.md) skill routes existing code to [`loop-to-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/loop-to-machine/SKILL.md), which converts the loop and checks parity with `compareRuns`. It routes new policies to [`generate-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/generate-machine/SKILL.md). Then [`add-traces`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-traces/SKILL.md) persists runs, [`add-evals`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-evals/SKILL.md) writes evaluations for each state, and [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md) proposes a pull request from traces, or reports that no candidate beat the current policy.
186
186
  - [examples/self-improving-refunds](https://github.com/statelyai/agent/blob/next/examples/self-improving-refunds): a refund desk as the environment, JSON playbooks as the policy, an improvement loop, and a benchmark against a raw tool loop.
187
187
  - [examples/code-review-loop](https://github.com/statelyai/agent/blob/next/examples/code-review-loop): review gates as the environment, a triage policy improved from traces against hidden tests, run with Claude Code in headless mode.
188
188
  - [examples/tic-tac-toe](https://github.com/statelyai/agent/blob/next/examples/tic-tac-toe): a game as the environment, a policy over board features, and a `canReach` proof that it never loses as the bar for promotion.
package/docs/evals.md CHANGED
@@ -4,7 +4,7 @@ Agent requests are independently executable, while the machine gives them meanin
4
4
 
5
5
  ## Testing without a provider
6
6
 
7
- A test runs the real machine through `runToQuiescence` and replaces only the model. `@statelyai/agent` ships no model mock. There are two ways to replace the model:
7
+ A test runs the real machine through `runAgent` and replaces only the model. `@statelyai/agent` ships no model mock. There are two ways to replace the model:
8
8
 
9
9
  - Mock the provider with the AI SDK's `MockLanguageModelV3`. The call still runs through `createAiSdkExecutors`, so the test covers prompt rendering, structured output parsing, and decision tool calls.
10
10
  - Pass plain functions as executors. The test covers the machine only.
@@ -68,7 +68,7 @@ const machine = agent.createMachine({
68
68
 
69
69
  ```ts
70
70
  import { MockLanguageModelV3 } from "ai/test";
71
- import { runToQuiescence } from "@statelyai/agent";
71
+ import { runAgent } from "@statelyai/agent";
72
72
  import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
73
73
 
74
74
  function mockModel(text: string) {
@@ -88,10 +88,10 @@ function mockModel(text: string) {
88
88
  const writer = mockModel("Checkout now supports saved cards.");
89
89
  const judge = mockModel(JSON.stringify({ result: { score: 4 } }));
90
90
 
91
- const result = await runToQuiescence(
92
- createAgentRuntime(machine, { executors: createAiSdkExecutors({ models: { writer, judge } }) }),
93
- { input: { topic: "saved cards at checkout" } },
94
- );
91
+ const result = await runAgent(machine, {
92
+ executors: createAiSdkExecutors({ models: { writer, judge } }),
93
+ input: { topic: "saved cards at checkout" },
94
+ });
95
95
 
96
96
  if (result.status === "done") {
97
97
  console.log(result.output); // { draft: "Checkout now supports saved cards.", score: 4 }
@@ -112,28 +112,26 @@ The mock answers in the provider's format, not the request's:
112
112
  An executor is a function of the request. Route on `request.name` to answer each request, and return the output value as `result`.
113
113
 
114
114
  ```ts
115
- import { runToQuiescence } from "@statelyai/agent";
115
+ import { runAgent } from "@statelyai/agent";
116
116
 
117
117
  const calls: string[] = [];
118
118
 
119
- const result = await runToQuiescence(
120
- createAgentRuntime(machine, {
121
- executors: {
122
- generateText: async (request) => {
123
- calls.push(request.name ?? "");
124
- switch (request.name) {
125
- case "draftEmail":
126
- return { result: "Checkout now supports saved cards." };
127
- case "scoreDraft":
128
- return { result: { score: 4 } };
129
- default:
130
- throw new Error(`No answer for request "${request.name}"`);
131
- }
132
- },
119
+ const result = await runAgent(machine, {
120
+ executors: {
121
+ generateText: async (request) => {
122
+ calls.push(request.name ?? "");
123
+ switch (request.name) {
124
+ case "draftEmail":
125
+ return { result: "Checkout now supports saved cards." };
126
+ case "scoreDraft":
127
+ return { result: { score: 4 } };
128
+ default:
129
+ throw new Error(`No answer for request "${request.name}"`);
130
+ }
133
131
  },
134
- }),
135
- { input: { topic: "saved cards at checkout" } },
136
- );
132
+ },
133
+ input: { topic: "saved cards at checkout" },
134
+ });
137
135
 
138
136
  console.log(calls); // ["draftEmail", "scoreDraft"]
139
137
  ```
@@ -199,10 +197,10 @@ A queue that runs dry throws an `AgentError` with code `seam-script-exhausted`,
199
197
 
200
198
  ## Per-state stats
201
199
 
202
- `foldTraces` (from `@statelyai/agent/testing`) folds many runs' traces into one row per state: how many runs visited it, how many of those failed, how many options the guards withheld at decisions made there, and how many events it ignored.
200
+ `foldTraces` (from `@statelyai/agent/evals`) folds many runs' traces into one row per state: how many runs visited it, how many of those failed, how many options the guards withheld at decisions made there, and how many events it ignored.
203
201
 
204
202
  ```ts no-check
205
- import { foldTraces } from "@statelyai/agent/testing";
203
+ import { foldTraces } from "@statelyai/agent/evals";
206
204
 
207
205
  // One AgentTraceEvent[] per run, collected with onTrace.
208
206
  const stats = foldTraces(traces, {
@@ -224,10 +222,10 @@ const stats = foldTraces(traces, {
224
222
 
225
223
  ## Decision requests from traces
226
224
 
227
- `getDecisionRequests` (from `@statelyai/agent/testing`) lists the decisions a run asked for, read from its trace: each decision's first `request.start`, and the states the run was in.
225
+ `getDecisionRequests` (from `@statelyai/agent/evals`) lists the decisions a run asked for, read from its trace: each decision's first `request.start`, and the states the run was in.
228
226
 
229
227
  ```ts no-check
230
- import { getDecisionRequests } from "@statelyai/agent/testing";
228
+ import { getDecisionRequests } from "@statelyai/agent/evals";
231
229
 
232
230
  for (const { states, request } of getDecisionRequests(trace, { name: "chooseResolution" })) {
233
231
  const { event } = await decide(request); // a candidate decider
@@ -245,6 +243,20 @@ for (const { states, request } of getDecisionRequests(trace, { name: "chooseReso
245
243
 
246
244
  ## Parity with the code you replace
247
245
 
246
+ Start with `checkParity`. Pick a lower-level tool only when the old code does not route its side effects through one object.
247
+
248
+ | The old code | Use | Compares |
249
+ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
250
+ | Sends every side effect through one `effects` object | `checkParity`, see [Check parity](strangler-fig.md#check-parity) | Each effect's name, order, arguments, and result |
251
+ | Calls a model client or SDK directly | `createRecorder` and `compareRecordings`, see [Any model client](#any-model-client) | Each recorded call and the output |
252
+ | Changes on purpose, or a live model makes calls differ each run | `compareRuns`, see [Outcome labels](#outcome-labels) | The terminal outcome, the effects, and rule breaks |
253
+
254
+ `checkParity` records `before` with `createRecorder`, replays `after` against the recording, and compares the two with `compareRecordings`, in one call per scenario.
255
+
256
+ `compareRuns` labels a difference `intended` only when the candidate fixes a rule the baseline broke, or only the candidate reaches the scenario's `expected` outcome. Any other difference is a `regression`, including an effect the candidate adds on purpose with the same outcome. See [Outcome labels](#outcome-labels).
257
+
258
+ ### Outcome labels
259
+
248
260
  `compareRuns` (from `@statelyai/agent/testing`) runs every scenario through the existing implementation and its replacement, and labels each difference. Use it when you port a loop to a machine and need to show where they behave the same and where the machine differs on purpose.
249
261
 
250
262
  ```ts no-check
@@ -335,10 +347,11 @@ compareRecordings(recorder.recording, replay.recording); // { equivalent: true,
335
347
 
336
348
  ## Suite coverage
337
349
 
338
- `traceCoverage` (from `@statelyai/agent/testing`) reports which states and handlers no trace exercised, so a suite can say how much of the machine it covers.
350
+ `traceCoverage` (from `@statelyai/agent/evals`) reports which states and handlers no trace exercised, so a suite can say how much of the machine it covers.
339
351
 
340
352
  ```ts no-check
341
- import { explorePaths, traceCoverage } from "@statelyai/agent/testing";
353
+ import { explorePaths } from "@statelyai/agent/testing";
354
+ import { traceCoverage } from "@statelyai/agent/evals";
342
355
 
343
356
  const report = traceCoverage(machine, traces, {
344
357
  reachable: await explorePaths(machine, { input }),
@@ -362,10 +375,10 @@ report.handlers[0];
362
375
 
363
376
  ## Where failures start
364
377
 
365
- `firstDivergence` (from `@statelyai/agent/testing`) finds the first step where a run departs from a reference, and names the state the run was in.
378
+ `firstDivergence` (from `@statelyai/agent/evals`) finds the first step where a run departs from a reference, and names the state the run was in.
366
379
 
367
380
  ```ts no-check
368
- import { firstDivergence, foldTraces } from "@statelyai/agent/testing";
381
+ import { firstDivergence, foldTraces } from "@statelyai/agent/evals";
369
382
 
370
383
  firstDivergence(failingTrace, passingTrace);
371
384
  // { index: 0, state: "deciding", decision: "chooseResolution", actual: { event: "escalate", … }, expected: { event: "refund", … } }
@@ -391,10 +404,10 @@ const stats = foldTraces(traces, {
391
404
 
392
405
  ## Proposals from traces
393
406
 
394
- `proposeApprovalRules` and `proposeCaps` (from `@statelyai/agent/testing`) read many runs' traces and propose changes for a machine with no decision point: which approvals a rule could answer, and what each cap should be. They are proposals for a person. Nothing promotes them or edits the machine.
407
+ `proposeApprovalRules` and `proposeCaps` (from `@statelyai/agent/evals`) read many runs' traces and propose changes for a machine with no decision point: which approvals a rule could answer, and what each cap should be. They are proposals for a person. Nothing promotes them or edits the machine.
395
408
 
396
409
  ```ts no-check
397
- import { proposeApprovalRules, proposeCaps } from "@statelyai/agent/testing";
410
+ import { proposeApprovalRules, proposeCaps } from "@statelyai/agent/evals";
398
411
 
399
412
  const rules = proposeApprovalRules(traces, {
400
413
  approvalState: "awaitingApproval",
@@ -424,20 +437,21 @@ const caps = proposeCaps(traces, {
424
437
 
425
438
  ## Repeated runs
426
439
 
427
- `repeatRuns` (from `@statelyai/agent/testing`) runs every scenario `k` times and reports how reliably each one passes. With a live model, one run per scenario says little: τ-bench found the rate at which all `k` runs of a task pass (pass^k) falls well below the single-run rate.
440
+ `repeatRuns` (from `@statelyai/agent/evals`) runs every scenario `k` times and reports how reliably each one passes. With a live model, one run per scenario says little: τ-bench found the rate at which all `k` runs of a task pass (pass^k) falls well below the single-run rate.
428
441
 
429
442
  ```ts no-check
430
- import { repeatRuns } from "@statelyai/agent/testing";
443
+ import { repeatRuns } from "@statelyai/agent/evals";
431
444
 
432
445
  const report = await repeatRuns({
433
446
  scenarios, // [{ id, ...your fields }]
434
447
  k: 5,
435
448
  run: async (scenario, attempt) => {
436
449
  const trace: AgentTraceEvent[] = [];
437
- const result = await runToQuiescence(
438
- createAgentRuntime(machine, { executors, onTrace: (event) => trace.push(event) }),
439
- { input: scenario.input },
440
- );
450
+ const result = await runAgent(machine, {
451
+ executors,
452
+ onTrace: (event) => trace.push(event),
453
+ input: scenario.input,
454
+ });
441
455
  return { trace, outcome: String(result.snapshot.value) };
442
456
  },
443
457
  passed: (scenario, { outcome }) => outcome === scenario.expected,
@@ -459,7 +473,7 @@ report.passHat(5); // the chance 5 runs of a scenario all pass
459
473
  For runs collected elsewhere, such as CI shards or production replays, `summarizeRepeats` takes the runs per scenario and returns the same report. `repeatRuns` collects runs and calls it.
460
474
 
461
475
  ```ts no-check
462
- import { summarizeRepeats } from "@statelyai/agent/testing";
476
+ import { summarizeRepeats } from "@statelyai/agent/evals";
463
477
 
464
478
  const report = summarizeRepeats([
465
479
  {
@@ -475,10 +489,10 @@ const report = summarizeRepeats([
475
489
 
476
490
  ## Judge agreement
477
491
 
478
- `judgeAgreement` (from `@statelyai/agent/testing`) measures how well a judge agrees with people on the same cases. Check it before a judge-graded eval gates anything.
492
+ `judgeAgreement` (from `@statelyai/agent/evals`) measures how well a judge agrees with people on the same cases. Check it before a judge-graded eval gates anything.
479
493
 
480
494
  ```ts no-check
481
- import { judgeAgreement } from "@statelyai/agent/testing";
495
+ import { judgeAgreement } from "@statelyai/agent/evals";
482
496
 
483
497
  const report = judgeAgreement(
484
498
  confirmed.map((row) => ({
package/docs/event-log.md CHANGED
@@ -38,6 +38,7 @@ interface AgentLogEntry {
38
38
  attempts?: DecisionAttempt[];
39
39
  decidedBy?: string;
40
40
  actorPath?: string[];
41
+ ignored?: true;
41
42
  }
42
43
  ```
43
44
 
@@ -49,12 +50,13 @@ interface AgentLogEntry {
49
50
  - `attempts` holds the decision attempts the machine did not accept before this entry's event landed. Replay ignores it. See [Decision attempts](#decision-attempts).
50
51
  - `decidedBy` names the `agent.decide` call an entry settles, as `<requestId>#<n>`: the chosen event, and the invoke's `xstate.done.actor` when the event left it running. A decision usually ends by sending its event, so its invoke never completes; a [`callKey`](hosts.md#idempotency-keys) for a log that cannot be folded counts it from this field. Inside an invoked child machine the call is named by the child's path, as `<childId>/<requestId>#<n>`. Replay ignores it.
51
52
  - `actorPath` names the invoked child machine an entry was delivered to, as the invoke ids from the root down (`["worker"]`, `["worker", "review"]`). It is omitted for an entry the root received. Replay applies the event to that child's snapshot with the child's own logic.
53
+ - `ignored` is set when the machine had no transition for an event sent to it, in the state the event arrived in. It is never set on an `xstate.*` event. Only `recordLog` sets it. It records what happened in the live run. Replay does not read it and applies the event like any other.
52
54
 
53
55
  Entries are strict JSON, and plain objects and arrays from another realm (a jest test's vm context) count as JSON. Object fields set to `undefined` in an input or event are dropped, as `JSON.stringify` drops them. `createReplayEntry`, `initEntry`, and every store append reject the other values JSON would drop or coerce (functions, symbols, bigint, non-finite numbers, `Date`, `Map`, `Set`, class instances, cycles, `undefined` array items) with `NonSerializableAgentEventError`, which carries the offending `path`. `Error` payloads on `xstate.error.actor` are normalized to `{ name, message, code?, cause?, "@error": true }`, keeping `code` when it is a string or a number; an `AgentDecisionExhaustedError` also keeps its `attempts`. `replay` turns objects marked `"@error"` back into `Error` objects, so an `onError` that checks `instanceof Error` takes the same branch on replay. A thrown plain object stays a plain object. Other properties of the thrown value are not kept. Use `assertJsonSerializable` and `assertAgentLogEntry` at custom transport boundaries.
54
56
 
55
57
  ## Record a log
56
58
 
57
- `runToQuiescence` returns a complete, self-contained segment as `result.events`. Two ways to get it into storage:
59
+ `runAgent` returns a complete, self-contained segment as `result.events`. Two ways to get it into storage:
58
60
 
59
61
  | | `store` | `onEvent` |
60
62
  | -------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
@@ -68,10 +70,7 @@ Entries are strict JSON, and plain objects and arrays from another realm (a jest
68
70
  Pass a [store](#stores) and the thread to write to. The run reads that thread as its resume log and appends to it.
69
71
 
70
72
  ```ts no-check
71
- const result = await runToQuiescence(
72
- createAgentRuntime(machine, { store, threadId: "session-1", executors }),
73
- { input },
74
- );
73
+ const result = await runAgent(machine, { store, threadId: "session-1", executors, input });
75
74
  ```
76
75
 
77
76
  - Entries are written in batches, each at its first entry's `index` as `expectedIndex`, so a concurrent writer conflicts instead of interleaving.
@@ -79,7 +78,7 @@ const result = await runToQuiescence(
79
78
  - No model call starts until every entry before it is durable. Pure transitions never wait.
80
79
  - A rejected write (an `AgentEventLogConflictError`, or any storage failure) aborts in-flight work and settles the run `{ status: "error", cause: "journal" }`. No further calls run.
81
80
  - A `@agent.usage` entry that arrives after the run settled is still written, but the result does not wait for it. Await `result.drain()` before terminating the process if you care about those straggler entries; it resolves once every write issued so far has landed, and never rejects (a failed write already settled the run with `cause: "journal"`).
82
- - `threadId` is required with a `store`; without it `runToQuiescence` throws `AgentError` with code `missing-thread-id`.
81
+ - `threadId` is required with a `store`; without it `runAgent` throws `AgentError` with code `missing-thread-id`.
83
82
  - A thread that already has entries is resumed. `input` that differs from the input the thread started with throws `AgentError` with code `thread-input-mismatch`, since two runs sharing a thread id would otherwise get one result.
84
83
  - If an entry cannot be written (an `input` or event that is not JSON), the run settles `{ status: "error", cause: "journal" }` instead of running without a log. Without a store, the log stops at that entry with a `console.warn`, and the run goes on.
85
84
  - Passing `events` as well makes that log the resume, and it must BE the thread's log: a different length throws `AgentEventLogConflictError`, and an entry-for-entry mismatch at the same length throws `AgentError` with code `event-log-conflict`.
@@ -91,10 +90,11 @@ const result = await runToQuiescence(
91
90
  ```ts no-check
92
91
  const appended: AgentLogEntry[] = [];
93
92
 
94
- const result = await runToQuiescence(
95
- createAgentRuntime(machine, { executors, onEvent: (entry) => appended.push(entry) }),
96
- { input },
97
- );
93
+ const result = await runAgent(machine, {
94
+ executors,
95
+ onEvent: (entry) => appended.push(entry),
96
+ input,
97
+ });
98
98
  ```
99
99
 
100
100
  ### `recordLog`: a plain actor
@@ -141,6 +141,7 @@ const { snapshot } = replay(orderMachine, log.entries);
141
141
 
142
142
  - An actor created from a `snapshot` starts its log from that snapshot.
143
143
  - Each entry carries `verification.stateHash`, so `replay` verifies the fold.
144
+ - A sent event the machine had no transition for is recorded with `ignored: true`, so a refused attempt can be read from the log without a replay.
144
145
  - Attached after `start()`, it misses the init event, and reading `log.entries` throws `AgentEventLogError`. An event that cannot be journaled (a payload that is not JSON) stops the recording the same way.
145
146
 
146
147
  To build entries yourself, use `initEntry` for index 0 and `createReplayEntry` for each subsequent external input.
@@ -154,7 +155,7 @@ const { snapshot, persistedSnapshot } = replay(machine, entries);
154
155
  ```
155
156
 
156
157
  - The first entry seeds the fold: `input` folds from `initialTransition`, `snapshot` restores purely and the rest of the log folds onto it.
157
- - `replay(machine, entries.slice(0, n))` rebuilds the state as of any point in the log — time travel with no side effects.
158
+ - `replay(machine, entries.slice(0, n))` rebuilds the state as of any point in the log, with no side effects.
158
159
  - Journaled child sessions are rebound to the sessions the current fold minted, so completions still apply.
159
160
 
160
161
  ## Verification
@@ -192,7 +193,7 @@ Replayability rests on pure transitions.
192
193
  - Journal external inputs only when building entries by hand.
193
194
  - Keep context JSON-serializable. Hold sessions, clients, and sockets in closures and store only their ids.
194
195
  - Replay against the machine the runtime folded. When actors come in through `createAgentRuntime(machine, { actors })`, call `replay(machine.provide({ actors }), entries)`. The executor-bound machine is never needed; recorded results replace executors.
195
- - A run whose initial state cannot be serialized to JSON produces no log: `result.events` is empty, `onEvent` never fires, and nothing is written to a `store`. `replay` rejects a log without an init entry, so `runToQuiescence` journals nothing rather than a suffix.
196
+ - A run whose initial state cannot be serialized to JSON produces no log: `result.events` is empty, `onEvent` never fires, and nothing is written to a `store`. `replay` rejects a log without an init entry, so `runAgent` journals nothing rather than a suffix.
196
197
  - `onEvent` alone does not make a call append-before-execute. A crash between an entry and the host's flush loses it. Use `store` when that matters.
197
198
 
198
199
  ## Fork
@@ -243,10 +244,7 @@ A host that decides with `decideNext` sends the event itself. Pass its `attempts
243
244
  const { event, attempts } = await decideNext(snapshot, { decide, model, allowedEvents: "desk.*" });
244
245
 
245
246
  if (event) {
246
- await runToQuiescence(createAgentRuntime(machine, { store, threadId }), {
247
- event,
248
- attempts,
249
- });
247
+ await runAgent(machine, { store, threadId, event, attempts });
250
248
  }
251
249
  ```
252
250
 
@@ -504,10 +504,10 @@ pnpm exec tsx examples/code-review-loop/run.ts --improve --policy v0
504
504
  4. Replay the train and held-out tasks with the candidate.
505
505
  5. Promote only with zero violations on both splits, a held-out objective no lower than before, and a combined objective strictly higher. `run.ts` writes a promoted policy to `policies/current.json`.
506
506
 
507
- Inside Claude Code, the [`improve-machine` skill](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md) runs the same round with Claude Code as the improver:
507
+ Inside Claude Code, the [`improve-machine` skill](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md) runs the same round with Claude Code as the improver:
508
508
 
509
509
  ```bash
510
- mkdir -p .claude/skills && cp -R skills/improve-machine .claude/skills/
510
+ npx skills add statelyai/skills --skill improve-machine -a claude-code
511
511
  pnpm exec tsx examples/code-review-loop/run.ts --policy v0 --no-human
512
512
  claude -p "Use the improve-machine skill on examples/code-review-loop. ..."
513
513
  ```
@@ -525,4 +525,4 @@ The full prompt and its allowed tools are in the [example's README](https://gith
525
525
  - [Human in the loop](human-in-the-loop.md): idle states, `meta.interaction`, and resuming.
526
526
  - [Environment and policy](environment-and-policy.md): the fixed environment, the generated policy, the objective, and the improvement loop.
527
527
  - [code-review-loop](https://github.com/statelyai/agent/blob/next/examples/code-review-loop): Part 2's factory: `before.ts`, the machine, the policies, and the improvement round on Claude Code.
528
- - [`skills/improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md): one improvement round from traces, run by an agent.
528
+ - [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md): one improvement round from traces, run by an agent.
@@ -86,13 +86,13 @@ A failed gate's `detail` is the repair prompt. Send it back to the model with th
86
86
 
87
87
  ## The skill
88
88
 
89
- The full authoring procedure ships as an agent skill. It covers the environment and policy split, the schema location, the rules a config must follow, a few-shot config, the Ajv adapter, `verifyAgentConfig`, the repair loop, and persisting traces.
89
+ The full authoring procedure is an agent skill in [statelyai/skills](https://github.com/statelyai/skills). It covers the environment and policy split, the schema location, the rules a config must follow, a few-shot config, the Ajv adapter, `verifyAgentConfig`, the repair loop, and persisting traces.
90
90
 
91
- **[`skills/generate-machine/SKILL.md`](https://github.com/statelyai/agent/blob/next/skills/generate-machine/SKILL.md)**
91
+ **[`generate-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/generate-machine/SKILL.md)**
92
92
 
93
- Copy that directory into your coding agent's skills directory. For Claude Code this is `.claude/skills/`. Other harnesses use their own location. The agent then loads the skill on requests such as "author an agent machine for X" and runs the gates itself.
93
+ Install it with `npx skills add statelyai/skills --skill generate-machine`, or in Claude Code with `/plugin install stately-agent@stately` after `/plugin marketplace add statelyai/skills`. The agent then loads the skill on requests such as "author an agent machine for X" and runs the gates itself.
94
94
 
95
- To improve a generated policy from its run traces, use [`skills/improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md). See [Environment and policy](environment-and-policy.md).
95
+ To improve a generated policy from its run traces, use [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md). See [Environment and policy](environment-and-policy.md).
96
96
 
97
97
  ## Limits
98
98
 
package/docs/hosts.md CHANGED
@@ -3,21 +3,19 @@
3
3
  The machine owns agent control flow. A host supplies model request executors.
4
4
 
5
5
  ```ts no-check
6
- const result = await runToQuiescence(
7
- createAgentRuntime(machine, {
8
- executors: {
9
- generateText: async (request, { signal }) => {
10
- const response = await mySdk.generate({
11
- model: request.model,
12
- prompt: request.prompt,
13
- signal,
14
- });
15
- return { result: response.text, messages: response.messages };
16
- },
6
+ const result = await runAgent(machine, {
7
+ executors: {
8
+ generateText: async (request, { signal }) => {
9
+ const response = await mySdk.generate({
10
+ model: request.model,
11
+ prompt: request.prompt,
12
+ signal,
13
+ });
14
+ return { result: response.text, messages: response.messages };
17
15
  },
18
- }),
19
- { input },
20
- );
16
+ },
17
+ input,
18
+ });
21
19
  ```
22
20
 
23
21
  Text, stream, and decision executors all receive `(request, info)`; cancellation is `info.signal`.
@@ -35,7 +33,7 @@ Execution is at-least-once. A host runs the request and then journals its comple
35
33
  - A [decision strategy](decisions.md#decision-strategies)'s sub-calls append their role: `<executionId>:<requestId>#<n>.<attempt>.pick`, `.group`, or `.fill`.
36
34
  - A resumed run re-executing an in-flight request passes the same `callKey` as the original attempt.
37
35
  - A fork mints its own lineage id (see [Fork](event-log.md#fork)), so none of its calls shares a key with its parent's.
38
- - It is `undefined` off the `runToQuiescence` path (a bare `provideExecutors` bind) and on a run with no event log.
36
+ - It is `undefined` off the `runAgent` path (a bare `provideExecutors` bind) and on a run with no event log.
39
37
  - Only model calls get one. A plain actor (`createAsyncLogic`, a tool) in flight at a crash runs again on resume with no key. Derive an idempotency key from the domain (an order id, a booking key) and dedupe inside the effect.
40
38
 
41
39
  The key names the call _site_, not the request. A version bridge keeps the lineage id, so a migrated machine that asks something else at the same invoke site produces the same key for a different request. Cache on `callKey` **and** a fingerprint of the request, and reuse the cached result only when the request also matches. Pass `callKey` to a provider as its dedupe key for that identical request:
@@ -63,10 +61,7 @@ import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
63
61
  const models = { fast: openai("gpt-6-luna") };
64
62
  const agent = setupAgent({ models /* schemas and requests */ });
65
63
 
66
- await runToQuiescence(
67
- createAgentRuntime(machine, { executors: createAiSdkExecutors({ models }) }),
68
- { input },
69
- );
64
+ await runAgent(machine, { executors: createAiSdkExecutors({ models }), input });
70
65
  ```
71
66
 
72
67
  Passing the same `models` map to `setupAgent({ models })` types the machine's model refs, so a request naming a model the host does not have is a compile error. Executors are always passed explicitly. Core does not import or require the AI SDK at runtime.
@@ -97,7 +92,7 @@ const executors = createOpenAiExecutors({
97
92
  },
98
93
  });
99
94
 
100
- await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
95
+ await runAgent(machine, { executors, input });
101
96
  ```
102
97
 
103
98
  `client` is injected, so the API key, base URL, and transport stay with the host. `openai` 5 or newer is required. It is an optional peer dependency with no version range, so an app on `openai` 4 still installs the core, and it is imported for types only. A client wrapper must forward both `responses.create` and `chat.completions.create` unless `api` pins one of them.
@@ -131,7 +126,7 @@ Decisions follow `decideMode`:
131
126
  - `'tool'`: one function tool per candidate event, with `tool_choice: 'required'` and `parallel_tool_calls: false`. Function tools are sent with `strict: false`, since the Responses API defaults strict mode on and arbitrary JSON Schema may fall outside it.
132
127
  - An answer the adapter cannot read as one event comes back as `rejected`, and the runtime retries it. See [Coercion](decisions.md#coercion).
133
128
 
134
- `generateText` runs the tool loop host-side. Each step that comes back with function calls runs the request's tools, appends the calls and one `function_call_output` item per result, and asks again. The replay is stateless: calls go back without their item ids, and reasoning items are left out. An incomplete turn, such as one cut off at `max_output_tokens`, never runs its calls, and an incomplete decision throws instead of choosing. A `failed` response throws on both paths, with its error code and message. The request's `maxSteps` bounds the number of OpenAI calls; the default is one, so a single-step request behaves as before. A tool that throws, a call to a tool the request did not offer, and arguments that are not JSON go back to the model as error results. The loop also ends early on a tool with no `execute` — a client-side tool, whose call is handed back with `finishReason: 'tool-calls'` and the raw response. Every step's `usage` is summed onto the one result the run aggregates. `modelCalls` reports the steps, and a loop that throws after a step records them on the error, so the run's budget counts them.
129
+ `generateText` runs the tool loop host-side. Each step that comes back with function calls runs the request's tools, appends the calls and one `function_call_output` item per result, and asks again. The replay is stateless: calls go back without their item ids, and reasoning items are left out. An incomplete turn, such as one cut off at `max_output_tokens`, never runs its calls, and an incomplete decision throws instead of choosing. A `failed` response throws on both paths, with its error code and message. The request's `maxSteps` bounds the number of OpenAI calls; the default is one, so a single-step request behaves as before. A tool that throws, a call to a tool the request did not offer, and arguments that are not JSON go back to the model as error results. The loop also ends early when the model calls a client-side tool (one with no `execute`). The call is handed back with `finishReason: 'tool-calls'` and the raw response. Every step's `usage` is summed onto the one result the run aggregates. `modelCalls` reports the steps, and a loop that throws after a step records them on the error, so the run's budget counts them.
135
130
 
136
131
  `toolChoice` maps onto `tool_choice`: `'auto'`, `'none'`, and `'required'` pass through, and `{ type: 'tool', name }` becomes `{ type: 'function', name }`. It is sent on the first step only, so a forced choice cannot re-fire every step and burn the step budget.
137
132
 
@@ -164,7 +159,7 @@ const executors = createTanStackAiExecutors({
164
159
  },
165
160
  });
166
161
 
167
- await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
162
+ await runAgent(machine, { executors, input });
168
163
  ```
169
164
 
170
165
  The options mirror `createAiSdkExecutors`:
@@ -197,7 +192,7 @@ The rest of the contract matches the other adapters:
197
192
 
198
193
  ## Finish reasons and truncation
199
194
 
200
- An executor result may report `finishReason`, normalized to `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'other'`. Map the provider's own vocabulary onto those five and leave the raw value on `raw`. `runToQuiescence` lifts the normalized reason onto the `request.end` trace event, beside `usage`.
195
+ An executor result may report `finishReason`, normalized to `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'other'`. Map the provider's own vocabulary onto those five and leave the raw value on `raw`. `runAgent` lifts the normalized reason onto the `request.end` trace event, beside `usage`.
201
196
 
202
197
  A `'length'` finish is the host's to interpret, because only the host sees it:
203
198
 
@@ -255,7 +250,7 @@ Tool-bearing calls are not retried here because tools may have side effects. Use
255
250
 
256
251
  ## Resume events off the wire
257
252
 
258
- A host that resumes a run from an HTTP request or a socket frame parses the payload at the boundary, then hands the parsed event to `runToQuiescence`:
253
+ A host that resumes a run from an HTTP request or a socket frame parses the payload at the boundary, then hands the parsed event to `runAgent`:
259
254
 
260
255
  ```ts no-check
261
256
  let event;
@@ -265,9 +260,7 @@ try {
265
260
  return Response.json({ error: String(error) }, { status: 400 });
266
261
  }
267
262
 
268
- const result = await runToQuiescence(createAgentRuntime(machine, { store, threadId, executors }), {
269
- event,
270
- });
263
+ const result = await runAgent(machine, { store, threadId, executors, event });
271
264
 
272
265
  if (result.ignored) {
273
266
  return Response.json(
@@ -279,7 +272,7 @@ if (result.ignored) {
279
272
 
280
273
  - `parseAgentEvent(machineOrSnapshot, payload)` takes `unknown` and returns the event typed as the machine's event union. Give it the machine to read the event schemas `setupAgent` registered, or any snapshot of it.
281
274
  - It throws `AgentInvalidEventPayloadError` (code `invalid-event-payload`) for a payload that is not an object with a string `type`, a reserved `@agent.*` type, or fields that fail the schema. That is the 400.
282
- - It does not ask whether the current state handles the event, and `runToQuiescence` adds no check of its own.
275
+ - It does not ask whether the current state handles the event, and `runAgent` adds no check of its own.
283
276
  - An event the resumed state has no transition for is ignored: the run settles normally and `result.ignored` holds the event. Answer 409 if the client should know nothing happened.
284
277
 
285
278
  See [Persistence](persistence.md#resume-with-an-event-off-the-wire).
@@ -411,4 +404,4 @@ const result = await run;
411
404
 
412
405
  `provideExecutors(machine, executors)` binds the executors onto the machine so a plain `createActor` runs it, for an application that owns the actor or embeds the agent machine in a larger XState system. See [Advanced](advanced.md).
413
406
 
414
- Framework-owned concerns—storage, durable execution, retries, queues, and tool-loop interruption recovery—remain with the framework.
407
+ Framework-owned concerns (storage, durable execution, retries, queues, and tool-loop interruption recovery) remain with the framework.
@@ -1,7 +1,7 @@
1
1
  # Human in the loop
2
2
 
3
3
  A human wait is an ordinary XState state with accepted events. Once no child,
4
- request, or in-process timer remains active, `runToQuiescence` settles as
4
+ request, or in-process timer remains active, `runAgent` settles as
5
5
  `idle`. Use `isAgentIdle(snapshot)` afterward to distinguish an intentional
6
6
  human wait from a stuck machine.
7
7
 
@@ -126,7 +126,7 @@ asking: {
126
126
  ## Render and validate
127
127
 
128
128
  ```ts no-check
129
- const paused = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
129
+ const paused = await runAgent(machine, { executors, input });
130
130
 
131
131
  if (paused.status === "idle") {
132
132
  const interaction = getInteraction(paused.snapshot);
@@ -151,10 +151,7 @@ Both functions are typed off the snapshot, so `eventFromInteraction` returns the
151
151
 
152
152
  ```ts no-check
153
153
  const event = eventFromInteraction(paused.snapshot, { type: "APPROVE" });
154
- await runToQuiescence(createAgentRuntime(machine, { executors }), {
155
- snapshot: paused.persist(),
156
- event,
157
- });
154
+ await runAgent(machine, { executors, snapshot: paused.persist(), event });
158
155
  ```
159
156
 
160
157
  When the answer arrives over the wire instead of from your own code, parse it at the boundary with `parseAgentEvent(machine, await request.json())` and pass the result as `event`. A bad payload throws, which is a 400; an event the paused state has no transition for is ignored and comes back as `result.ignored`. See [Persistence](persistence.md#resume-with-an-event-off-the-wire).
@@ -162,13 +159,13 @@ When the answer arrives over the wire instead of from your own code, parse it at
162
159
  ## Drive several turns
163
160
 
164
161
  ```ts no-check
165
- let result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
162
+ let result = await runAgent(machine, { executors, input });
166
163
 
167
164
  while (result.status === "idle") {
168
165
  const snapshot = result.persist();
169
166
  await storage.put(id, snapshot);
170
167
  const event = await promptUser(getInteraction(result.snapshot));
171
- result = await runToQuiescence(createAgentRuntime(machine, { executors }), { snapshot, event });
168
+ result = await runAgent(machine, { executors, snapshot, event });
172
169
  }
173
170
  ```
174
171