@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.37

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 (130) hide show
  1. package/CHANGELOG.md +138 -0
  2. package/dist/act-B9hLQls6.mjs +19 -0
  3. package/dist/act-CrX0JwWY.cjs +42 -0
  4. package/dist/ai-sdk.cjs +63 -7
  5. package/dist/ai-sdk.d.cts +13 -3
  6. package/dist/ai-sdk.d.mts +13 -3
  7. package/dist/ai-sdk.mjs +63 -7
  8. package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
  9. package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
  10. package/dist/decision-object-B5zGSPFp.d.mts +15 -0
  11. package/dist/decision-object-DBcLWVvv.d.cts +15 -0
  12. package/dist/{run-agent-Ct_GZw_f.mjs → effects-BT_cSY0j.mjs} +1003 -109
  13. package/dist/{run-agent-s5D32w99.cjs → effects-DDseYtJk.cjs} +1037 -107
  14. package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
  15. package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
  16. package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
  17. package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
  18. package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
  19. package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
  20. package/dist/index.cjs +660 -286
  21. package/dist/index.d.cts +168 -9
  22. package/dist/index.d.mts +168 -9
  23. package/dist/index.mjs +639 -271
  24. package/dist/internal-C3Lqu538.d.cts +43 -0
  25. package/dist/internal-DUcdhk-i.d.mts +43 -0
  26. package/dist/log.cjs +2 -2
  27. package/dist/log.d.cts +1 -1
  28. package/dist/log.d.mts +1 -1
  29. package/dist/log.mjs +2 -2
  30. package/dist/machines.cjs +457 -41
  31. package/dist/machines.d.cts +114 -43
  32. package/dist/machines.d.mts +114 -43
  33. package/dist/machines.mjs +457 -42
  34. package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
  35. package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
  36. package/dist/openai.cjs +149 -36
  37. package/dist/openai.d.cts +28 -10
  38. package/dist/openai.d.mts +28 -10
  39. package/dist/openai.mjs +149 -36
  40. package/dist/otel.d.cts +1 -1
  41. package/dist/otel.d.mts +1 -1
  42. package/dist/{run-agent-BGdx5913.d.mts → run-agent-30mH2moE.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-DlPzBWj-.d.mts} +91 -9
  44. package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
  45. package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BaNyz6Q3.d.cts} +4 -4
  46. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-C1CG_nfX.d.mts} +4 -4
  47. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  48. package/dist/tanstack-ai.cjs +62 -4
  49. package/dist/tanstack-ai.d.cts +18 -6
  50. package/dist/tanstack-ai.d.mts +18 -6
  51. package/dist/tanstack-ai.mjs +62 -4
  52. package/dist/testing.cjs +2493 -1502
  53. package/dist/testing.d.cts +360 -256
  54. package/dist/testing.d.mts +360 -256
  55. package/dist/testing.mjs +2489 -1503
  56. package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
  57. package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
  58. package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
  59. package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
  60. package/dist/{usage-BDiJKyv9.d.cts → usage-Bm5nvpow.d.cts} +6 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-BnikdOca.d.mts} +6 -1
  62. package/dist/utils-7lSa4H-i.d.cts +403 -0
  63. package/dist/utils-CBbKw2fM.d.mts +403 -0
  64. package/dist/validate.cjs +44 -12
  65. package/dist/validate.d.cts +6 -6
  66. package/dist/validate.d.mts +6 -6
  67. package/dist/validate.mjs +44 -12
  68. package/dist/verify-ChyX6jq0.mjs +2306 -0
  69. package/dist/verify-CwlombbC.cjs +2359 -0
  70. package/dist/{verify-BQpE8hUz.d.cts → verify-DJHfEfm6.d.cts} +213 -14
  71. package/dist/{verify-CqeuEmIk.d.mts → verify-i9Hiwc5g.d.mts} +213 -14
  72. package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
  73. package/dist/with-model-calls-BkOwdroS.mjs +213 -0
  74. package/docs/act.md +102 -0
  75. package/docs/advanced.md +105 -0
  76. package/docs/any-stack.md +62 -0
  77. package/docs/choosing-a-run-mode.md +55 -0
  78. package/docs/debugging.md +29 -0
  79. package/docs/decisions.md +473 -0
  80. package/docs/environment-and-policy.md +188 -0
  81. package/docs/evals.md +509 -0
  82. package/docs/event-log.md +312 -0
  83. package/docs/from-a-loop.md +528 -0
  84. package/docs/generate-machines.md +110 -0
  85. package/docs/hosts.md +414 -0
  86. package/docs/human-in-the-loop.md +177 -0
  87. package/docs/index.md +48 -0
  88. package/docs/judgments.md +281 -0
  89. package/docs/langgraph-comparison.md +198 -0
  90. package/docs/machines-as-data.md +454 -0
  91. package/docs/machines-presets.md +198 -0
  92. package/docs/machines.md +497 -0
  93. package/docs/messages.md +67 -0
  94. package/docs/meta.json +52 -0
  95. package/docs/models-and-providers.md +268 -0
  96. package/docs/multi-agent.md +68 -0
  97. package/docs/observability.md +109 -0
  98. package/docs/patterns.md +31 -0
  99. package/docs/persistence.md +207 -0
  100. package/docs/quickstart.md +121 -0
  101. package/docs/roadmap.md +22 -0
  102. package/docs/scope.md +75 -0
  103. package/docs/statechart-policy-examples.md +69 -0
  104. package/docs/steps.md +56 -0
  105. package/docs/strangler-fig.md +323 -0
  106. package/docs/text-requests.md +250 -0
  107. package/docs/thinking-in-state-machines.md +324 -0
  108. package/docs/tools.md +249 -0
  109. package/docs/upgrading.md +37 -0
  110. package/docs/usage-and-budgets.md +518 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +492 -0
  113. package/docs/xstate-4-and-5-apps.md +161 -0
  114. package/llms.txt +53 -0
  115. package/package.json +10 -3
  116. package/readme.md +30 -15
  117. package/skills/add-evals/SKILL.md +3 -1
  118. package/skills/add-traces/SKILL.md +6 -1
  119. package/skills/build-machine/SKILL.md +84 -0
  120. package/skills/generate-machine/SKILL.md +1 -1
  121. package/skills/graph-engineering/SKILL.md +13 -3
  122. package/skills/improve-machine/SKILL.md +21 -2
  123. package/skills/loop-to-machine/SKILL.md +147 -192
  124. package/skills/loop-to-machine/reference.md +260 -0
  125. package/dist/utils-BnXdWih3.d.mts +0 -108
  126. package/dist/utils-ebVpCYoF.d.cts +0 -108
  127. package/dist/verify-Bpahmr34.mjs +0 -1241
  128. package/dist/verify-DCLZa9R0.cjs +0 -1288
  129. package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
  130. package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
@@ -0,0 +1,323 @@
1
+ ---
2
+ title: Strangler-fig retrofit
3
+ description: Wrap an existing async workflow as a machine with no rewrite, record a baseline, then move one phase at a time into states with a parity check after each.
4
+ ---
5
+
6
+ > **Alpha:** `@statelyai/agent` 2.0 is in alpha. APIs can change between releases; pin an exact version. Feedback: [github.com/statelyai/agent](https://github.com/statelyai/agent/issues).
7
+
8
+ A strangler-fig retrofit moves an existing workflow onto a machine without a rewrite. Step 0 wraps the function unchanged. Each later step moves one phase into states and checks the result against the original with `checkParity`.
9
+
10
+ - Step 0 takes minutes: inspection, traces, the event log, `signal`, and a recorded baseline, with no change to the workflow.
11
+ - Reliability proofs (`canReach`, `explorePaths`) arrive per phase, as each phase becomes states.
12
+ - [Migrating from a hand-rolled loop](from-a-loop.md) is the other path: port the whole loop at once.
13
+
14
+ The code on this page is in [`examples/strangler-fig`](https://github.com/statelyai/agent/blob/next/examples/strangler-fig).
15
+
16
+ ## The workflow's one requirement
17
+
18
+ The workflow reaches the outside world only through an `effects` object: model calls, tools, reads, and writes.
19
+
20
+ ```ts no-check
21
+ export async function runTicket(ticket: Ticket, effects: SupportEffects): Promise<SupportResult> {
22
+ const classification = await classifyTicket(ticket, effects); // retries effects.generate
23
+ return resolveTicket(ticket, classification, effects); // lookupOrder, issueRefund, escalate
24
+ }
25
+ ```
26
+
27
+ - Each effect is an async function.
28
+ - A call made around `effects` (a module-level client, `fetch`) is invisible to the machine, to traces, and to recordings. Move it into `effects` first.
29
+ - Keep effect arguments and results JSON-shaped where you can: they are journaled and recorded. Pass live objects (a chat session, an `AbortSignal`) by closure, not as arguments.
30
+ - An effect whose natural result is a live object (an agent instance) returns its name or id instead. The host keeps a registry from id to object.
31
+ - An effect that writes host state by reference (a tool mutating a shared `state` object) returns the change instead, and the wrapper applies it.
32
+ - A synchronous host callback (a stop predicate) or a diagnostic logger is not an effect. The workflow or the machine factory closes over it.
33
+
34
+ ### Class-shaped code
35
+
36
+ When the loop is a class method that calls its own private methods for the model and the tools, there is no `(input, effects)` function to pass. Wrap it with no edit to the class:
37
+
38
+ - `run: (input, effects) => { const executor = createExecutor(input); executor.callModel = (...args) => effects.callModel(...args); return executor.run(); }`, with each effect calling the original method.
39
+ - Route the old test suite through the wrap with a factory or a static `create` stand-in, not a subclass, when the constructor is private.
40
+
41
+ ### Seams for other shapes
42
+
43
+ | Shape | Seam |
44
+ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
45
+ | Effect-TS generator | Transliterate the generator to async, statement for statement, and bridge each effect from Effect to Promise, keeping the fiber context, typed failures, and interrupts. The parity baseline is the async transliteration; the old suite covers the original. |
46
+ | Redux thunk | The thunk's `extra` argument plus its nested dispatches. Wrap `dispatch` so every nested thunk gets the effects-backed `extra`. |
47
+ | LangGraph graph | Wrap `graph.invoke`. Fake the model factory with the test runner's module mock (`vi.mock`); the fake calls the run's effects. |
48
+ | A closure inside a DI or Layer factory | Copy the module, identical outside the carved function, and swap it in with a module mock. |
49
+ | A step loop inside the model SDK (`stopWhen`, `maxSteps`) | No loop to carve. The SDK call stays one effect; carve the control flow around it, such as handoff or approval. |
50
+
51
+ ## Step 0: wrap
52
+
53
+ `wrapWorkflow` turns the function into a machine. The function runs unchanged.
54
+
55
+ ```ts
56
+ import { wrapWorkflow } from "@statelyai/agent";
57
+
58
+ interface Ticket {
59
+ id: string;
60
+ message: string;
61
+ }
62
+
63
+ const effects = {
64
+ lookupOrder: async (orderId: string) => ({ orderId, total: 20 }),
65
+ // Keyed, so a retried or resumed run cannot refund twice.
66
+ issueRefund: async (orderId: string, amount: number, idempotencyKey: string) => ({
67
+ refundId: `rf_${orderId}`,
68
+ }),
69
+ };
70
+
71
+ async function runTicket(ticket: Ticket, fx: typeof effects) {
72
+ const order = await fx.lookupOrder(ticket.id);
73
+ return fx.issueRefund(order.orderId, order.total, `refund:${ticket.id}`);
74
+ }
75
+
76
+ const support = wrapWorkflow({
77
+ id: "support",
78
+ effects,
79
+ run: (ticket: Ticket, fx) => runTicket(ticket, fx),
80
+ });
81
+
82
+ const result = await support.run({ id: "A-100", message: "Refund my mug." });
83
+ // result: { refundId: "rf_A-100" }, what runTicket returned
84
+ ```
85
+
86
+ - `support.run(input, options)` resolves with what the workflow returned and rethrows what it threw, the same error object.
87
+ - `support.machine` is an ordinary agent machine: `running` invokes the workflow, `done` is final with its result as output. It works with `runAgent`, `describeMachine`, `canReach`, and the inspector.
88
+ - A thrown error settles `runAgent(support.machine, …)` as `{ status: "error", cause: "machine" }`.
89
+ - `options.signal` reaches the workflow as the `run` callback's third argument, `{ signal }`. The workflow decides what an abort returns, as it did before: one that returns an `aborted` result still returns it.
90
+
91
+ ### Effect calls as events
92
+
93
+ Each effect call is two events, `effect.call` then `effect.done` or `effect.error`, handled in `running`:
94
+
95
+ | Event | Payload | Context |
96
+ | -------------- | ------------------------ | ---------------------- |
97
+ | `effect.call` | `name`, `call`, `args` | `calls` goes up by one |
98
+ | `effect.done` | `name`, `call`, `result` | unchanged |
99
+ | `effect.error` | `name`, `call`, `error` | `failures` goes up |
100
+
101
+ - `call` is the 0-based call number across the run; it pairs a call with its result.
102
+ - Payloads are JSON-safe, so they land in the event log and traces as they are. Pass `redact: (name, part, value) => …` to strip secrets and private records first; the workflow still gets the real values.
103
+ - Once the run's `signal` aborts, an effect throws the abort reason instead of running, even in a workflow that ignores its signal.
104
+ - `effects` can be a class instance: its prototype methods count, bound to it.
105
+ - `onTransition`, `onTrace`, `onEvent`, and `inspect` see every effect call.
106
+ - An effect that returns a stream settles once the stream is read: `effect.done` carries the chunks (`{ chunks, returned }` when a generator returned a value), and a throw mid-stream is `effect.error`.
107
+
108
+ ### Run options
109
+
110
+ `support.run(input, options)` takes these `runAgent` options: `signal`, `inspect`, `onTransition`, `onTrace`, `onEvent`, `metadata`, and `verification`. Two more are its own:
111
+
112
+ | Option | Purpose |
113
+ | ---------- | ------------------------------------------------------------------------------------------- |
114
+ | `effects` | Replaces some effects for one run: fakes, stubs, replay stand-ins |
115
+ | `recorder` | Wraps every effect with `recorder.fn(name, fn)` and records the result with `recorder.output` |
116
+
117
+ Effects bound to one call's live objects (a request context, a span) go in per call: create the workflow once and pass `run(input, { effects })` on every call. The `effects` given to `wrapWorkflow` are then the defaults.
118
+
119
+ ## Record a baseline
120
+
121
+ A `recorder` on a normal run produces a golden recording of what the workflow did.
122
+
123
+ ```ts
124
+ import { wrapWorkflow } from "@statelyai/agent";
125
+ import { createRecorder } from "@statelyai/agent/testing";
126
+
127
+ const support = wrapWorkflow({
128
+ id: "support",
129
+ effects: { lookupOrder: async (orderId: string) => ({ orderId, total: 20 }) },
130
+ run: async (orderId: string, fx) => (await fx.lookupOrder(orderId)).total,
131
+ });
132
+
133
+ const recorder = createRecorder();
134
+ await support.run("A-100", { recorder });
135
+ recorder.recording.effects;
136
+ // [
137
+ // { kind: "call", name: "lookupOrder", call: 0, args: ["A-100"], result: { orderId: "A-100", total: 20 } },
138
+ // { kind: "output", value: 20 },
139
+ // ]
140
+ ```
141
+
142
+ Save `recorder.recording` as a fixture. `createRecorder({ replay: recording })` answers each call from it with no effect running. See [Parity with the code you replace](evals.md#parity-with-the-code-you-replace).
143
+
144
+ ## Carve one phase
145
+
146
+ A carved phase becomes states. The rest of the workflow stays a function, invoked as one actor. The runner keeps the `(input, effects)` signature.
147
+
148
+ In the example, `step1.ts` carves the classifier's retry loop:
149
+
150
+ ```ts no-check
151
+ classifying: {
152
+ invoke: {
153
+ src: "classify", // effects.generate({ task: "classify", ... })
154
+ input: ({ context }) => context.ticket,
155
+ onDone: ({ context, output }) => ({
156
+ target: "resolving",
157
+ context: { attempts: context.attempts + 1, classification: output },
158
+ }),
159
+ onError: ({ context }) => ({ target: "retrying", context: { attempts: context.attempts + 1 } }),
160
+ },
161
+ },
162
+ retrying: {
163
+ type: "choice",
164
+ choice: ({ context }) =>
165
+ context.attempts < MAX_ATTEMPTS
166
+ ? { target: "classifying" }
167
+ : { target: "resolving", context: { classification: UNCLASSIFIED } },
168
+ },
169
+ resolving: {
170
+ invoke: { src: "resolve", /* resolveTicket from before.ts, unchanged */ },
171
+ },
172
+ ```
173
+
174
+ - Build the actors per run from `effects`, and pass them as `runAgent`'s `actors`.
175
+ - Give the runner a third `options` argument passed through to `runAgent` (`threadId`, `store`, `metadata`, `onTrace`, `inspect`). Traces and inspection then need no copy of it.
176
+ - Move prompt or warning text the carved phase sends into a versioned request config as you carve. That file is the lever `improve-machine` may edit later.
177
+ - Carve one phase per commit.
178
+ - A phase in the middle of a `try`/`finally`: the setup before it moves into the runner, and the `finally` becomes a state every exit passes through, so a proof can say cleanup runs first.
179
+ - A legacy body that owns abort (it returns its own `stopped` result): pass the `signal` to the legacy body only, not to `runAgent`. Its result then reaches the machine as a normal final; `runAgent`'s `signal` would settle the run as `aborted` instead.
180
+ - An invoke whose error must reach the caller unchanged: omit `onError`. The run settles `{ status: "error", error }` with the original error, and the runner rethrows it. Pass `disable: ["invoke-without-on-error"]` to `lintAgentMachine` for that machine, or `ignore: [{ code: "invoke-without-on-error", path }]` for one state.
181
+
182
+ ### A phase in the middle of a method
183
+
184
+ - Copy only that phase's lines into the carved actor, with a comment listing the copied line ranges. `checkParity` call-args keep the copy honest: a drifted copy calls its effects with other arguments.
185
+ - When the class has a public per-turn hook, replace that method on the instance instead, and let the machine decide at that boundary. The rest of the method stays legacy.
186
+
187
+ ## Check parity
188
+
189
+ `checkParity` from `@statelyai/agent/testing` checks a step against the original, scenario by scenario.
190
+
191
+ ```ts
192
+ import { wrapWorkflow } from "@statelyai/agent";
193
+ import { checkParity } from "@statelyai/agent/testing";
194
+
195
+ const createEffects = () => ({
196
+ lookupOrder: async (orderId: string) => ({ orderId, total: 20 }),
197
+ });
198
+
199
+ async function before(orderId: string, fx: ReturnType<typeof createEffects>) {
200
+ return (await fx.lookupOrder(orderId)).total;
201
+ }
202
+
203
+ const step0 = wrapWorkflow({ id: "support", effects: createEffects(), run: before });
204
+
205
+ const report = await checkParity({
206
+ scenarios: [{ id: "mug", input: "A-100" }],
207
+ effects: () => createEffects(),
208
+ before,
209
+ after: (input, fx) => step0.run(input, { effects: fx }),
210
+ });
211
+ report.equivalent; // true
212
+ ```
213
+
214
+ What it does per scenario:
215
+
216
+ 1. Runs `before` on fresh `effects(scenario)`, each function wrapped with `recorder.fn`, and records the output.
217
+ 2. Runs `after` on replay stand-ins: each call is answered from the recording, and no effect runs.
218
+ 3. Compares the two recordings with `compareRecordings`: effect names, call order, arguments, results, and the output.
219
+
220
+ | Field | Value |
221
+ | ---------------------------- | ---------------------------------------------------------------------- |
222
+ | `report.equivalent` | `true` when every scenario is |
223
+ | `row.divergences` | `compareRecordings` divergences: `call-args`, `missing-effect`, … |
224
+ | `row.before` / `row.after` | `{ output }` or `{ error }` |
225
+ | `row.recording` / `row.replay` | The baseline recording, and what `after` did in replay |
226
+
227
+ - An `after` that throws is a row with `after: { error }`, never a thrown `checkParity`. A call the recording cannot answer throws `RecordingDivergenceError` inside `after`.
228
+ - When both sides throw, they match on the error's name and message.
229
+ - `compare` passes options through to `compareRecordings`, such as `normalize` for generated ids.
230
+
231
+ ### Generated ids
232
+
233
+ Ids and timestamps differ on every run. Scrub them on both sides:
234
+
235
+ ```ts
236
+ import { randomUUID } from "node:crypto";
237
+ import { wrapWorkflow } from "@statelyai/agent";
238
+ import { checkParity } from "@statelyai/agent/testing";
239
+
240
+ const createEffects = () => ({
241
+ saveDraft: async (draft: { id: string; text: string }) => ({ saved: draft.id }),
242
+ });
243
+
244
+ async function before(text: string, fx: ReturnType<typeof createEffects>) {
245
+ const id = randomUUID();
246
+ if (!text) throw new Error(`Draft ${id} is empty`);
247
+ await fx.saveDraft({ id, text });
248
+ return { id, text };
249
+ }
250
+
251
+ const step0 = wrapWorkflow({ id: "drafts", effects: createEffects(), run: before });
252
+
253
+ const UUID = /[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}/g;
254
+ const scrub = <T>(value: T): T => JSON.parse(JSON.stringify(value).replace(UUID, "<id>"));
255
+
256
+ const report = await checkParity({
257
+ scenarios: [
258
+ { id: "saved", input: "Hello" },
259
+ { id: "empty", input: "" },
260
+ ],
261
+ effects: () => createEffects(),
262
+ before,
263
+ after: (input, fx) => step0.run(input, { effects: fx }),
264
+ compare: { normalize: scrub }, // effect arguments and results, and the recorded output
265
+ normalizeOutput: scrub, // the output, before it is recorded
266
+ normalizeError: (error) => String(error).replace(UUID, "<id>"), // thrown errors
267
+ });
268
+ report.equivalent; // true
269
+ ```
270
+
271
+ - `compare.normalize` maps every recorded effect on both sides. Without it, `saved` diverges on `call-args`.
272
+ - `normalizeOutput` maps each side's output before it is recorded. Use it when the scrub is not on every effect, or for a value only the output carries.
273
+ - `normalizeError` maps each side's thrown error. Errors are compared outside the recording, so without it `empty` diverges on `output`.
274
+
275
+ ### The old suite on the port
276
+
277
+ Run the module's own tests against the port by swapping the module.
278
+
279
+ - Snapshot files are named after the test file that runs them. A swap file that imports the old suite writes fresh snapshots on its first run, and `toMatchSnapshot` passes without comparing. Copy the old `__snapshots__/<old>.snap` to the swap file's name, and run with `CI=true` so a missing snapshot fails.
280
+ - A module mock whose factory imports the port deadlocks or recurses when the port imports the mocked module. Load the port with a dynamic import in `beforeAll`, and call it from inside the mocked functions.
281
+ - When a module mock does not reach the code's own import of the module (one runner did not apply it to a relative import inside the package), patch the class prototype from a setup file instead. Import both modules dynamically in its `beforeAll`: a static import loads the module before the test file's mocks apply.
282
+ - `runAgent` starts asynchronously. Fire-and-forget work the old code starts at the same time may settle in a different order. An old test that asserts the exact order of actions across concurrent tasks is a structural failure only when those actions commute and their order is not part of the contract; an order that reaches users or storage is behavioral.
283
+
284
+ ## Repeat
285
+
286
+ Each carved phase adds what the machine can prove:
287
+
288
+ | Step | Change | Gained |
289
+ | ---- | ------------------------------ | --------------------------------------------------------------- |
290
+ | 0 | none | transitions, traces, event log, `signal`, a recorded baseline |
291
+ | 1 | classify retry becomes states | `canReach` proves the classifier runs at most `MAX_ATTEMPTS` times |
292
+ | n | the last phase becomes states | the machine is the workflow; drop the wrapper |
293
+
294
+ The step 1 proof in `examples/strangler-fig/index.test.ts`:
295
+
296
+ ```ts no-check
297
+ const tooMany = await canReach(supportMachine, (snapshot) => snapshot.context.attempts > MAX_ATTEMPTS, {
298
+ input: ticket,
299
+ outputs: { classify: [classification], resolve: [resolved] },
300
+ errors: { classify: new Error("model overloaded") },
301
+ });
302
+ // { reachable: false, complete: true }
303
+ ```
304
+
305
+ Step 0 cannot give this proof: its one `running` state holds the whole function.
306
+
307
+ ## Limits
308
+
309
+ - A wrapped workflow is a black box. The machine has one state for all of it.
310
+ - No resume in the middle of the function. A resumed run starts the workflow again.
311
+ - `canReach` and `explorePaths` prove nothing about the wrapped function's inside.
312
+ - Effect arguments and results are journaled JSON-safe. A value that is not JSON (a class instance) loses what JSON cannot hold. A stream is journaled as the chunks read through `for await` or `next()`; one read another way (a `ReadableStream` reader) never settles its effect.
313
+ - Parity cannot see an effect that mutates host state by reference, or one whose result is a live object. Return a change, a name, or an id, and keep a registry on the host side.
314
+ - `checkParity` runs `before` on the effects you give it for real. Give it fakes or an isolated fixture, never production writes.
315
+ - `effects` are async functions only. A sync function or a client object goes behind an async function first.
316
+ - Parity covers what goes through `effects` and the output. A change in a call made around `effects` is not seen.
317
+
318
+ ## Related
319
+
320
+ - [Migrating from a hand-rolled loop](from-a-loop.md): port a whole loop at once.
321
+ - [Evals](evals.md#parity-with-the-code-you-replace): `createRecorder`, `compareRecordings`, and `compareRuns`.
322
+ - [Verify](verify.md): `canReach` and `explorePaths`.
323
+ - [`skills/loop-to-machine`](https://github.com/statelyai/agent/blob/next/skills/loop-to-machine/SKILL.md): the retrofit, run by a coding agent.
@@ -0,0 +1,250 @@
1
+ ---
2
+ title: Text requests
3
+ description: Declare typed model calls on an agent machine and invoke them from a state, parsing structured or streamed output.
4
+ ---
5
+
6
+ > **Alpha:** `@statelyai/agent` 2.0 is in alpha. APIs can change between releases; pin an exact version. Feedback: [github.com/statelyai/agent](https://github.com/statelyai/agent/issues).
7
+
8
+ This page covers declaring text requests, invoking them from a state, and reading structured or streamed output.
9
+
10
+ ## Request declarations in setupAgent
11
+
12
+ <!-- requests config surface from src/setup-agent.ts and src/text-logic.ts -->
13
+
14
+ A **text request** is a typed model call that your machine invokes by name. You declare it once with its own input and output schemas, a model reference, and a prompt built from that input. The machine decides when the call happens. The host executes it.
15
+
16
+ Pass a `requests` map to `setupAgent`. Each entry becomes an invokable actor under the same name.
17
+
18
+ ```ts
19
+ import { z } from "zod";
20
+ import { setupAgent } from "@statelyai/agent";
21
+ import {} from "@statelyai/agent/ai-sdk";
22
+ import { openai } from "@ai-sdk/openai";
23
+
24
+ // Model IDs here are illustrative; substitute your provider's current models.
25
+ const models = {
26
+ quick: openai("gpt-6-luna"),
27
+ careful: openai("gpt-6.1-sol"),
28
+ };
29
+ const answerSchema = z.object({ answer: z.string() });
30
+
31
+ const agentSetup = setupAgent({
32
+ models,
33
+ context: z.object({ prompt: z.string(), answer: z.string().nullable() }),
34
+ input: z.object({ prompt: z.string() }),
35
+ output: answerSchema,
36
+ requests: {
37
+ answerQuestion: {
38
+ schemas: { input: z.object({ prompt: z.string() }), output: answerSchema },
39
+ model: "quick",
40
+ system: "Answer the question directly.",
41
+ prompt: ({ input }) => input.prompt,
42
+ },
43
+ },
44
+ });
45
+ ```
46
+
47
+ - Each schema field accepts any [Standard Schema](https://standardschema.dev) validator.
48
+ - Both schema slots are optional. Omit `output` and the request resolves to `string`. Omit `input` and the invoke needs no `input`. A request with neither writes `schemas: {}`. The `schemas` key itself stays required on `requests` entries, while a standalone `createTextLogic` can omit it entirely.
49
+ - Each request-shaping field, such as `system`, `prompt`, `messages`, `temperature`, and `maxOutputTokens`, is either a static value or a `({ input }) => value` function.
50
+ - `prompt` and `messages` are mutually exclusive: a request must resolve exactly one of them. Resolving both, or neither, throws.
51
+
52
+ ### Model references
53
+
54
+ `model` is a key into the `models` registry, or any bare string that the [host](hosts.md) resolves at run time. See [Authoring forms](machines.md#authoring-forms).
55
+
56
+ ### Standalone requests
57
+
58
+ The samples later on this page use `createTextLogic`, which declares the same request as a standalone value instead of an entry in the `requests` map. The two forms take identical options. See [Reusable request logic with createTextLogic](#reusable-request-logic-with-createtextlogic).
59
+
60
+ ## Invoking a request from a state
61
+
62
+ Invoke the request by name with `src`, pass `input`, and read the typed result in `onDone`. The [quickstart](quickstart.md) shows a full machine.
63
+
64
+ ```ts no-check
65
+ // inside states: { ... }
66
+ answering: {
67
+ invoke: {
68
+ id: "answer",
69
+ src: "answerQuestion",
70
+ input: ({ context }) => ({ prompt: context.prompt }),
71
+ onDone: ({ output }) => ({ target: "done", context: { answer: output.result.answer } }),
72
+ },
73
+ },
74
+ ```
75
+
76
+ In `onDone`, `output` is `{ result, messages }`. `output.result` is already validated against the request's output schema and typed from it. In this example the type is `{ answer: string }`, so you read `output.result.answer` directly. The machine needs no parsing step. `output.messages` holds the response messages the executor returned, ready to append to context; see [Messages](messages.md).
77
+
78
+ > **Note:** Route on `request.name`. Every lowered request carries its `setupAgent({ requests })` key as `name`. A mock executor, or a router that picks providers per request, tells requests apart with `request.name === 'answerQuestion'`. Do not inspect the `system` or `prompt` text. See [examples/context-compaction/index.test.ts](https://github.com/statelyai/agent/blob/next/examples/context-compaction/index.test.ts).
79
+
80
+ ### Narrowing an unknown output outside the machine
81
+
82
+ The `parseOutput(schema, output)` helper validates a value against a schema and returns the parsed value. It throws on a mismatch. Use it in host code that holds a raw, still-untyped output, such as a value from a persisted snapshot or an inline `agent.generateText` result typed `unknown`. You never need it inside `onDone`.
83
+
84
+ ```ts
85
+ import { parseOutput } from "@statelyai/agent";
86
+
87
+ const answer = parseOutput(answerSchema, rawOutput); // typed as { answer: string }
88
+ ```
89
+
90
+ ## Structured output vs plain text
91
+
92
+ <!-- output-mode derivation from src/text-logic.ts (getAgentOutputMode) -->
93
+
94
+ Output is structured when the schema describes an object, an array, or a top-level union of them built with `z.union` or `z.discriminatedUnion`. Otherwise the output is plain text. An `output: z.object({ ... })` schema returns a validated object. An `output: z.string()` schema returns the model's text.
95
+
96
+ > **Note for host implementers:** Every structured request is sent to the provider as a root object `{ result: <your schema> }`, built by `providerOutputSchema`. The parsed `result` is what the executor returns and what the machine validates. The wrapper keeps a bare union or array root portable, because providers that reject one at the root still accept it nested under `result`. Machine authors declare and receive the bare schema.
97
+
98
+ ```ts
99
+ export const triageTicket = createTextLogic({
100
+ schemas: {
101
+ input: z.object({ ticket: z.string() }),
102
+ output: z.object({
103
+ sentiment: z.enum(["positive", "neutral", "negative"]),
104
+ category: z.enum(["billing", "technical", "other"]),
105
+ reply: z.string(),
106
+ }),
107
+ },
108
+ model: "quick",
109
+ system: "Triage the support ticket: sentiment, category, and a short reply.",
110
+ prompt: ({ input }) => input.ticket,
111
+ });
112
+ ```
113
+
114
+ The mode is derived from the schema automatically. You never set it. See [examples/triage/index.ts](https://github.com/statelyai/agent/blob/next/examples/triage/index.ts).
115
+
116
+ ### Reasoning
117
+
118
+ <!-- reasoning opt-in from src/text-logic.ts (AgentTextRequest.includeReasoning) -->
119
+
120
+ Set `includeReasoning: true` on a structured request to add an optional string `reasoning` field to the provider's output schema. The field is listed before `result`, so the property order prompts the model to reason before answering:
121
+
122
+ ```ts
123
+ export const triageTicket = createTextLogic({
124
+ schemas: { input: z.object({ ticket: z.string() }), output: triageSchema },
125
+ model: "quick",
126
+ includeReasoning: true, // opt in
127
+ prompt: ({ input }) => input.ticket,
128
+ });
129
+ ```
130
+
131
+ The reasoning never enters machine context or output. It surfaces in three places: on the raw executor result as `result.reasoning` from the `generateText` executor of `createAiSdkExecutors`, on `runToQuiescence`'s `onResult(request, { raw })`, and as a `reasoning` field on the `request.end` `onTrace` event. Text-mode requests ignore the option.
132
+
133
+ `includeReasoning` is not the provider's reasoning-effort setting. Effort is the host's business, because what it means differs per provider: an enum for one, a thinking-token budget for another, nothing at all for a third. A machine that named an effort level would stop being portable. Set it where the executors are built, with [`createAiSdkExecutors({ settings })`](models-and-providers.md#host-owned-model-settings).
134
+
135
+ ## Streaming requests
136
+
137
+ <!-- stream mode from src/text-logic.ts and examples/joke -->
138
+ <!-- viz: sequence diagram of a streaming request: state invokes the request -> host streamText executor -> chunks delivered to runToQuiescence onChunk while the invoke is pending -> final text resolves onDone -->
139
+
140
+ A request streams when its `mode` is `'stream'`. Without `mode`, the request is single-shot, equivalent to `'generate'`. A streaming request resolves to the final text and delivers intermediate chunks to `runToQuiescence`'s `onChunk`.
141
+
142
+ ```ts no-check
143
+ export const tellJoke = createTextLogic({
144
+ mode: "stream",
145
+ schemas: { input: z.object({ topic: z.string() }), output: z.string() },
146
+ model: "quick",
147
+ system: "You tell short, punchy jokes.",
148
+ prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
149
+ });
150
+
151
+ const result = await runToQuiescence(
152
+ createAgentRuntime(machine, {
153
+ executors: createAiSdkExecutors({ models }),
154
+ onChunk: (chunk) => process.stdout.write(chunk),
155
+ }),
156
+ { input: { topic: "state machines" } },
157
+ );
158
+ ```
159
+
160
+ - `onChunk` fires once per chunk and receives the request that produced it, so parallel streams stay distinguishable.
161
+ - `onChunk` is observational only. It cannot change the run.
162
+ - A `mode: 'stream'` request needs a `streamText` executor. Without one, `runToQuiescence` fails at bind time.
163
+
164
+ See [parallel-streams](https://github.com/statelyai/agent/blob/next/examples/parallel-streams/index.ts).
165
+
166
+ ## Finish reason and truncation
167
+
168
+ <!-- finishReason from src/text-logic.ts (AgentFinishReason) and src/errors.ts -->
169
+
170
+ An executor result can report why the call stopped, as a normalized `finishReason`: `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'other'`. `createAiSdkExecutors` sets it on every text, structured, and streamed result, mapping the provider's own vocabulary onto those five; the provider's raw value stays on the result's `raw`.
171
+
172
+ The reason reaches observability the way per-call usage does: `runToQuiescence` lifts it onto the `request.end` [trace event](observability.md), next to `usage`.
173
+
174
+ `'length'` means the output token limit cut the call off. What that costs depends on the request:
175
+
176
+ - A text request returns the text it did produce, with `finishReason: 'length'`. Nothing throws. The machine decides whether a half-finished draft is worth keeping.
177
+ - A structured request has nothing usable: a JSON object that never closed does not parse, and one that stopped mid-thought is not an answer. `createAiSdkExecutors` throws an `AgentTruncatedError`.
178
+
179
+ `AgentTruncatedError` extends `AgentError` with the code `'truncated'`, so an invoke's `onError` branches on the code without an `instanceof` check across bundles:
180
+
181
+ ```ts no-check
182
+ answering: {
183
+ invoke: {
184
+ id: "answer",
185
+ src: "answerQuestion",
186
+ input: ({ context }) => ({ prompt: context.prompt }),
187
+ onDone: ({ output }) => ({ target: "done", context: { answer: output.result.answer } }),
188
+ onError: [
189
+ { guard: ({ event }) => event.error.code === "truncated", target: "askingForLess" },
190
+ { target: "failed" },
191
+ ],
192
+ },
193
+ },
194
+ ```
195
+
196
+ The error carries `requestName`, the `requestId` when the host knows it, and `partialOutput` when the model produced something before it ran out. Core never throws it: truncation is a host observation, and only an adapter knows a call ran out of tokens. See [Hosts](hosts.md#finish-reasons-and-truncation).
197
+
198
+ ## Tools and multi-step loops
199
+
200
+ <!-- tools and maxSteps from src/types.ts (AgentTool), src/text-logic.ts and src/ai-sdk/index.ts -->
201
+
202
+ A text request can carry `tools`, a map of tool name to tool. The tool type is a minimal structural contract, so tools from any SDK work. See [Tools](tools.md) for the contract, how to attach tools, and how the host runs the tool loop.
203
+
204
+ To let one request run a bounded tool-call loop, set the typed `maxSteps` field on the request. The shipped AI SDK adapter forwards it as `stopWhen: stepCountIs(maxSteps)`. A request with no `maxSteps` stays single-step.
205
+
206
+ ```ts no-check
207
+ export const research = createTextLogic({
208
+ schemas: { input: z.object({ question: z.string() }), output: z.string() },
209
+ model: "careful",
210
+ prompt: ({ input }) => input.question,
211
+ tools: { getWeather },
212
+ maxSteps: 5,
213
+ });
214
+ ```
215
+
216
+ > **Note:** `metadata` is host-owned per-call data. Core passes it through untouched. A host that does not understand a key ignores it, so requests stay portable across hosts.
217
+
218
+ ## Reusable request logic with createTextLogic
219
+
220
+ <!-- createTextLogic from src/text-logic.ts and examples/email-drafter -->
221
+
222
+ The inline `requests` map shown above is the default form. Use `createTextLogic` when a request should be standalone, meaning exported, tested on its own, or shared across machines, and registered under `actors`. `setupAgent` builds each `requests` entry from `createTextLogic` internally, so the two forms are interchangeable. See [Authoring forms](machines.md#authoring-forms).
223
+
224
+ ```ts
225
+ import { createTextLogic, setupAgent, type AgentMessage } from "@statelyai/agent";
226
+
227
+ export const draftEmail = createTextLogic({
228
+ schemas: {
229
+ input: z.object({
230
+ prompt: z.string(),
231
+ messages: z.custom<AgentMessage[]>((value) => Array.isArray(value)),
232
+ }),
233
+ output: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
234
+ },
235
+ model: "careful",
236
+ system: "Draft a polished email from the request.",
237
+ messages: ({ input }) => [...input.messages, userMessage(input.prompt)],
238
+ });
239
+
240
+ const agentSetup = setupAgent({ models, context, input, output, actors: { draftEmail } });
241
+ ```
242
+
243
+ Because `draftEmail` is a value, a test can import it and drive it with a fake executor without a machine. [examples/email-drafter/agent-logic.ts](https://github.com/statelyai/agent/blob/next/examples/email-drafter/agent-logic.ts) shows structured, streaming, and message-based `createTextLogic` requests across a multi-state workflow.
244
+
245
+ ## Related
246
+
247
+ - Read more about [Tools](tools.md), including defining tools, attaching them to a request, and how the host runs the tool loop.
248
+ - Read more about [Hosts](hosts.md), including the executors that run text requests and how model aliases reach a provider.
249
+ - Read more about [Messages](messages.md), the `messages` field a request can send instead of a bare `prompt`.
250
+ - Read more about [Decisions](decisions.md), the other request kind, which chooses a legal machine event instead of producing text.