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

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 (137) hide show
  1. package/CHANGELOG.md +59 -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 +142 -97
  25. package/dist/index.d.cts +97 -141
  26. package/dist/index.d.mts +97 -141
  27. package/dist/index.mjs +123 -74
  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/machine-input-0YTPcnCm.mjs +27 -0
  35. package/dist/machine-input-DU3owLUr.cjs +32 -0
  36. package/dist/machines.cjs +1 -719
  37. package/dist/machines.d.cts +2 -424
  38. package/dist/machines.d.mts +2 -424
  39. package/dist/machines.mjs +2 -709
  40. package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
  41. package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
  42. package/dist/openai.cjs +3 -3
  43. package/dist/openai.d.cts +2 -3
  44. package/dist/openai.d.mts +2 -3
  45. package/dist/openai.mjs +3 -3
  46. package/dist/otel.d.cts +1 -1
  47. package/dist/otel.d.mts +1 -1
  48. package/dist/policy.cjs +77 -0
  49. package/dist/policy.d.cts +143 -0
  50. package/dist/policy.d.mts +143 -0
  51. package/dist/policy.mjs +75 -0
  52. package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-BO9RSb7i.d.cts} +33 -40
  53. package/dist/{run-agent-30mH2moE.d.cts → run-agent-BxkeuAYR.d.mts} +33 -40
  54. package/dist/{effects-DDseYtJk.cjs → run-agent-COdR9FpM.cjs} +175 -228
  55. package/dist/{effects-BT_cSY0j.mjs → run-agent-D3gW9wfd.mjs} +176 -211
  56. package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
  57. package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
  58. package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
  59. package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
  60. package/dist/tanstack-ai.cjs +4 -4
  61. package/dist/tanstack-ai.d.cts +2 -3
  62. package/dist/tanstack-ai.d.mts +2 -3
  63. package/dist/tanstack-ai.mjs +4 -4
  64. package/dist/testing.cjs +122 -996
  65. package/dist/testing.d.cts +36 -695
  66. package/dist/testing.d.mts +36 -695
  67. package/dist/testing.mjs +112 -977
  68. package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
  69. package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
  70. package/dist/trajectory-BFjXaooB.d.cts +96 -0
  71. package/dist/trajectory-BFjXaooB.d.mts +96 -0
  72. package/dist/trajectory-BUXj_1Ue.mjs +152 -0
  73. package/dist/trajectory-CoZSv4wF.cjs +157 -0
  74. package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
  75. package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
  76. package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
  77. package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
  78. package/dist/validate.cjs +4 -4
  79. package/dist/validate.d.cts +2 -2
  80. package/dist/validate.d.mts +2 -2
  81. package/dist/validate.mjs +4 -4
  82. package/dist/{verify-DJHfEfm6.d.cts → verify-CIu4mqIZ.d.mts} +56 -6
  83. package/dist/{verify-i9Hiwc5g.d.mts → verify-CTHlmBbh.d.cts} +56 -6
  84. package/dist/{verify-ChyX6jq0.mjs → verify-Cacz6XSk.mjs} +170 -46
  85. package/dist/{verify-CwlombbC.cjs → verify-D8UDqU4l.cjs} +170 -46
  86. package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
  87. package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
  88. package/docs/advanced.md +5 -5
  89. package/docs/choosing-a-run-mode.md +7 -7
  90. package/docs/debugging.md +6 -8
  91. package/docs/decisions.md +5 -4
  92. package/docs/environment-and-policy.md +1 -1
  93. package/docs/evals.md +57 -43
  94. package/docs/event-log.md +13 -15
  95. package/docs/from-a-loop.md +3 -3
  96. package/docs/generate-machines.md +4 -4
  97. package/docs/hosts.md +25 -30
  98. package/docs/human-in-the-loop.md +5 -8
  99. package/docs/index.md +4 -4
  100. package/docs/judgments.md +5 -7
  101. package/docs/langgraph-comparison.md +6 -6
  102. package/docs/machines-as-data.md +7 -12
  103. package/docs/machines-presets.md +17 -120
  104. package/docs/machines.md +13 -13
  105. package/docs/models-and-providers.md +19 -25
  106. package/docs/multi-agent.md +1 -1
  107. package/docs/observability.md +6 -8
  108. package/docs/persistence.md +10 -20
  109. package/docs/quickstart.md +3 -3
  110. package/docs/statechart-policy-examples.md +1 -1
  111. package/docs/steps.md +5 -6
  112. package/docs/strangler-fig.md +105 -33
  113. package/docs/text-requests.md +10 -12
  114. package/docs/thinking-in-state-machines.md +8 -8
  115. package/docs/tools.md +10 -12
  116. package/docs/upgrading.md +1 -1
  117. package/docs/usage-and-budgets.md +51 -56
  118. package/docs/validate-and-repair.md +9 -14
  119. package/docs/verify.md +54 -7
  120. package/docs/xstate-4-and-5-apps.md +19 -28
  121. package/llms.txt +1 -1
  122. package/package.json +31 -6
  123. package/readme.md +32 -24
  124. package/dist/internal-C3Lqu538.d.cts +0 -43
  125. package/dist/internal-DUcdhk-i.d.mts +0 -43
  126. package/dist/types-DQUOOaZO.d.cts +0 -238
  127. package/dist/types-DQUOOaZO.d.mts +0 -238
  128. package/skills/add-evals/SKILL.md +0 -152
  129. package/skills/add-traces/SKILL.md +0 -152
  130. package/skills/build-machine/SKILL.md +0 -84
  131. package/skills/generate-machine/SKILL.md +0 -335
  132. package/skills/graph-engineering/SKILL.md +0 -43
  133. package/skills/improve-machine/SKILL.md +0 -261
  134. package/skills/improve-machine/reference.md +0 -101
  135. package/skills/loop-to-machine/SKILL.md +0 -205
  136. package/skills/loop-to-machine/policy.md +0 -154
  137. package/skills/loop-to-machine/reference.md +0 -260
@@ -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.
@@ -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.
@@ -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).
@@ -316,7 +309,7 @@ Each operation is described in [The runtime loop](steps.md).
316
309
 
317
310
  ### Host events mid-run
318
311
 
319
- `runtime.send(event)` puts a host event in the run's mailbox, behind whatever already arrived. A `nextEvent()` parked on a pending request resolves with it; the loop applies it with `transition` like any other event.
312
+ `runtime.send(event)` queues a host event behind earlier host sends and ahead of completions the run holds but has not handed out. A `nextEvent()` parked on a pending request resolves with it; the loop applies it with `transition` like any other event.
320
313
 
321
314
  ```ts no-check
322
315
  const runtime = createAgentRuntime(machine, { executors });
@@ -332,7 +325,7 @@ for (let event; (event = await runtime.nextEvent());) {
332
325
  const result = await runtime.finish();
333
326
  ```
334
327
 
335
- - **Ordering.** One FIFO with request completions, child messages, and timers. A send during a pending invoke is handed out by the next `nextEvent()`; the invoke keeps running unless the transition leaves its state, which aborts its `signal`.
328
+ - **Ordering.** Host sends keep their own order and go ahead of request completions, child messages, and timers the run already holds, which keep theirs. A send during a pending invoke is handed out by the next `nextEvent()`; the invoke keeps running unless the transition leaves its state, which aborts its `signal`.
336
329
  - **Journal.** A sent event is a log entry, the same as `runAgent({ event })`. Replaying `result.events` lands on the same state.
337
330
  - **Unhandled.** A sent event the state has no transition for is reported as `result.ignored`.
338
331
  - **Before `start`.** Queued; the first `nextEvent()` hands it out. Returns `true`.
@@ -387,6 +380,8 @@ const result = await runAgent(machine, {
387
380
  - the loop never applies it;
388
381
  - the machine handled it but settles still `active` (an idle wait nothing will answer), immediately and without waiting for `timeout`;
389
382
  - `timeout` ms pass while the machine is still active and working.
383
+ - `event` is a function and it throws; the run's `error` is what it threw.
384
+ - **Per reason.** `event` can be a function of `signal.reason`, so a pause and a stop send different events: `abortWith: { event: (reason) => ({ type: reason === "pause" ? ("PAUSE" as const) : ("STOP" as const) }) }`. As with `onIdle`, an event built in a function needs `as const` for its `type`.
390
385
  - **Journal.** The abort event is a log entry; replay reaches the same final state.
391
386
 
392
387
  ### runAgent inbox
@@ -402,7 +397,7 @@ const result = await run;
402
397
 
403
398
  - **Same as `runtime.send`.** Each `inbox.send` goes to the run's mailbox and returns the same boolean. See [Host events mid-run](#host-events-mid-run).
404
399
  - **Before start.** Queued; delivered after the init event and after `runAgent`'s own `event`. Returns `true`.
405
- - **While idle.** An inbox event resumes the run, ahead of a pending `onIdle` answer; that answer is dropped. Without `onIdle`, `runAgent` returns at the first idle.
400
+ - **While idle.** An inbox event resumes the run, ahead of a pending `onIdle` answer; that answer is dropped. Without `onIdle`, `runAgent` returns at the first idle. With `onIdle: "inbox"`, an idle state waits for the next `inbox.send` (a resume after a pause) and has no answer of its own.
406
401
  - **Ignored.** An inbox event the state does not handle is reported as `result.ignored`. Unlike an ignored `onIdle` answer, it does not end the `onIdle` loop.
407
402
  - **After `runAgent` returns.** Returns `false`.
408
403
  - **One call.** An inbox serves one `runAgent` call; reusing it throws `AgentError` `inbox-in-use`.
@@ -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
 
package/docs/index.md CHANGED
@@ -11,7 +11,7 @@ Stately Agent is XState plus typed model requests, decisions, and host executors
11
11
  ## Start here
12
12
 
13
13
  - Greenfield, a new agent: [Quickstart](quickstart.md), then [Thinking in state machines](thinking-in-state-machines.md) or a copied [agent pattern](patterns.md).
14
- - Brownfield, an existing agent loop: [Migrating from a loop](from-a-loop.md), or the shipped `loop-to-machine` skill in `node_modules/@statelyai/agent/skills/`.
14
+ - Brownfield, an existing agent loop: [Migrating from a loop](from-a-loop.md), or the [`loop-to-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/loop-to-machine/SKILL.md) skill from [statelyai/skills](https://github.com/statelyai/skills).
15
15
  - Brownfield, an existing async workflow: [Strangler-fig retrofit](strangler-fig.md). Wrap it unchanged with `wrapWorkflow`, then move one phase at a time into states, checked with `checkParity`.
16
16
  - [Choosing a run mode](choosing-a-run-mode.md)
17
17
  - [Advanced: bare XState actors and hand-written executors](advanced.md)
@@ -23,9 +23,7 @@ Stately Agent is XState plus typed model requests, decisions, and host executors
23
23
  | `runAgent` | Run a machine to done or idle; the default entry point |
24
24
  | `setupAgent` | Schema-first XState setup with Agent request actors |
25
25
  | `createAgentRuntime` | Advanced, own the loop: bind executors, expose one durable transition loop |
26
- | `runToQuiescence` | Advanced, own the loop: drive a runtime to done, idle, or error |
27
26
  | `getInteraction` / `eventFromInteraction` | Render and validate human interactions |
28
- | `decideNext` | Ask a model for one event a plain XState machine accepts |
29
27
  | `describeMachine` | Render a machine as plain text for a model |
30
28
  | `wrapWorkflow` | Wrap an existing async workflow, unchanged, as a machine |
31
29
  | `isAgentIdle` | Distinguish a human wait from a stuck settled machine |
@@ -36,13 +34,15 @@ Stately Agent is XState plus typed model requests, decisions, and host executors
36
34
  | Entry | Purpose |
37
35
  | ------------------------------ | ------------------------------------------------------------------------------------------ |
38
36
  | `@statelyai/agent` | Authoring, running, human interaction, and the executor contract |
37
+ | `@statelyai/agent/evals` | Trace analytics: `foldTraces`, `traceCoverage`, `repeatRuns`, `judgeAgreement` |
39
38
  | `@statelyai/agent/testing` | `lintAgentMachine`, `simulateAgent`, `canReach`, `checkParity`, trajectories, seams |
40
39
  | `@statelyai/agent/log` | The event log: `replay`, `forkEventLog`, `getDecisionAttempts`, hand-built entries, stores |
41
40
  | `@statelyai/agent/ai-sdk` | `createAiSdkExecutors`: the Vercel AI SDK adapter, for language and decision models |
42
41
  | `@statelyai/agent/openai` | Executors over the raw `openai` package |
43
42
  | `@statelyai/agent/tanstack-ai` | `createTanStackAiExecutors`, the TanStack AI adapter |
44
- | `@statelyai/agent/machines` | Preset machines: tool loop, sequential, parallel, router, supervisor, handoff |
43
+ | `@statelyai/agent/machines` | `createApprovalBatchMachine`, a preset that gates a turn's tool calls on approval |
45
44
  | `@statelyai/agent/otel` | OpenTelemetry trace handler |
45
+ | `@statelyai/agent/policy` | `decideNext` for any XState snapshot, and `createPolicyDecider` for a policy machine |
46
46
  | `@statelyai/agent/validate` | JSON workflow config validation and `verifyAgentConfig` pre-run gates |
47
47
 
48
48
  Core has no runtime dependency on the AI SDK.
package/docs/judgments.md CHANGED
@@ -236,7 +236,7 @@ A decision model is any object that implements the AI SDK's decision-model spec:
236
236
 
237
237
  ```ts
238
238
  import type { Experimental_DecisionModel } from "ai";
239
- import { runToQuiescence } from "@statelyai/agent";
239
+ import { runAgent } from "@statelyai/agent";
240
240
  import { expect, test } from "vitest";
241
241
 
242
242
  const scripted: Experimental_DecisionModel = {
@@ -254,12 +254,10 @@ const scripted: Experimental_DecisionModel = {
254
254
  };
255
255
 
256
256
  test("routes a double charge to billing", async () => {
257
- const result = await runToQuiescence(
258
- createAgentRuntime(triageMachine, {
259
- actors: { classifyTicket: createClassifyTicket(scripted) },
260
- }),
261
- { input: { ticket: "I was charged twice this month.", plan: "pro" } },
262
- );
257
+ const result = await runAgent(triageMachine, {
258
+ actors: { classifyTicket: createClassifyTicket(scripted) },
259
+ input: { ticket: "I was charged twice this month.", plan: "pro" },
260
+ });
263
261
 
264
262
  expect(result.status === "done" && result.output).toEqual({ team: "billing", urgent: false });
265
263
  });