@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.
- package/CHANGELOG.md +59 -0
- package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
- package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
- package/dist/ai-sdk.cjs +4 -4
- package/dist/ai-sdk.d.cts +2 -3
- package/dist/ai-sdk.d.mts +2 -3
- package/dist/ai-sdk.mjs +4 -4
- package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
- package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
- package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
- package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
- package/dist/effects-B9IvUPVh.mjs +23 -0
- package/dist/effects-DrWcUGgc.cjs +34 -0
- package/dist/evals.cjs +810 -0
- package/dist/evals.d.cts +595 -0
- package/dist/evals.d.mts +595 -0
- package/dist/evals.mjs +801 -0
- package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
- package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
- package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
- package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
- package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
- package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
- package/dist/index.cjs +142 -97
- package/dist/index.d.cts +97 -141
- package/dist/index.d.mts +97 -141
- package/dist/index.mjs +123 -74
- package/dist/internal-BzlpzSux.d.cts +14 -0
- package/dist/internal-BzlpzSux.d.mts +14 -0
- package/dist/log.cjs +2 -3
- package/dist/log.d.cts +2 -2
- package/dist/log.d.mts +2 -2
- package/dist/log.mjs +3 -3
- package/dist/machine-input-0YTPcnCm.mjs +27 -0
- package/dist/machine-input-DU3owLUr.cjs +32 -0
- package/dist/machines.cjs +1 -719
- package/dist/machines.d.cts +2 -424
- package/dist/machines.d.mts +2 -424
- package/dist/machines.mjs +2 -709
- package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
- package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
- package/dist/openai.cjs +3 -3
- package/dist/openai.d.cts +2 -3
- package/dist/openai.d.mts +2 -3
- package/dist/openai.mjs +3 -3
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/policy.cjs +77 -0
- package/dist/policy.d.cts +143 -0
- package/dist/policy.d.mts +143 -0
- package/dist/policy.mjs +75 -0
- package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-BO9RSb7i.d.cts} +33 -40
- package/dist/{run-agent-30mH2moE.d.cts → run-agent-BxkeuAYR.d.mts} +33 -40
- package/dist/{effects-DDseYtJk.cjs → run-agent-COdR9FpM.cjs} +175 -228
- package/dist/{effects-BT_cSY0j.mjs → run-agent-D3gW9wfd.mjs} +176 -211
- package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
- package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
- package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
- package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
- package/dist/tanstack-ai.cjs +4 -4
- package/dist/tanstack-ai.d.cts +2 -3
- package/dist/tanstack-ai.d.mts +2 -3
- package/dist/tanstack-ai.mjs +4 -4
- package/dist/testing.cjs +122 -996
- package/dist/testing.d.cts +36 -695
- package/dist/testing.d.mts +36 -695
- package/dist/testing.mjs +112 -977
- package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
- package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
- package/dist/trajectory-BFjXaooB.d.cts +96 -0
- package/dist/trajectory-BFjXaooB.d.mts +96 -0
- package/dist/trajectory-BUXj_1Ue.mjs +152 -0
- package/dist/trajectory-CoZSv4wF.cjs +157 -0
- package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
- package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
- package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
- package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
- package/dist/validate.cjs +4 -4
- package/dist/validate.d.cts +2 -2
- package/dist/validate.d.mts +2 -2
- package/dist/validate.mjs +4 -4
- package/dist/{verify-DJHfEfm6.d.cts → verify-CIu4mqIZ.d.mts} +56 -6
- package/dist/{verify-i9Hiwc5g.d.mts → verify-CTHlmBbh.d.cts} +56 -6
- package/dist/{verify-ChyX6jq0.mjs → verify-Cacz6XSk.mjs} +170 -46
- package/dist/{verify-CwlombbC.cjs → verify-D8UDqU4l.cjs} +170 -46
- package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
- package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
- package/docs/advanced.md +5 -5
- package/docs/choosing-a-run-mode.md +7 -7
- package/docs/debugging.md +6 -8
- package/docs/decisions.md +5 -4
- package/docs/environment-and-policy.md +1 -1
- package/docs/evals.md +57 -43
- package/docs/event-log.md +13 -15
- package/docs/from-a-loop.md +3 -3
- package/docs/generate-machines.md +4 -4
- package/docs/hosts.md +25 -30
- package/docs/human-in-the-loop.md +5 -8
- package/docs/index.md +4 -4
- package/docs/judgments.md +5 -7
- package/docs/langgraph-comparison.md +6 -6
- package/docs/machines-as-data.md +7 -12
- package/docs/machines-presets.md +17 -120
- package/docs/machines.md +13 -13
- package/docs/models-and-providers.md +19 -25
- package/docs/multi-agent.md +1 -1
- package/docs/observability.md +6 -8
- package/docs/persistence.md +10 -20
- package/docs/quickstart.md +3 -3
- package/docs/statechart-policy-examples.md +1 -1
- package/docs/steps.md +5 -6
- package/docs/strangler-fig.md +105 -33
- package/docs/text-requests.md +10 -12
- package/docs/thinking-in-state-machines.md +8 -8
- package/docs/tools.md +10 -12
- package/docs/upgrading.md +1 -1
- package/docs/usage-and-budgets.md +51 -56
- package/docs/validate-and-repair.md +9 -14
- package/docs/verify.md +54 -7
- package/docs/xstate-4-and-5-apps.md +19 -28
- package/llms.txt +1 -1
- package/package.json +31 -6
- package/readme.md +32 -24
- package/dist/internal-C3Lqu538.d.cts +0 -43
- package/dist/internal-DUcdhk-i.d.mts +0 -43
- package/dist/types-DQUOOaZO.d.cts +0 -238
- package/dist/types-DQUOOaZO.d.mts +0 -238
- package/skills/add-evals/SKILL.md +0 -152
- package/skills/add-traces/SKILL.md +0 -152
- package/skills/build-machine/SKILL.md +0 -84
- package/skills/generate-machine/SKILL.md +0 -335
- package/skills/graph-engineering/SKILL.md +0 -43
- package/skills/improve-machine/SKILL.md +0 -261
- package/skills/improve-machine/reference.md +0 -101
- package/skills/loop-to-machine/SKILL.md +0 -205
- package/skills/loop-to-machine/policy.md +0 -154
- package/skills/loop-to-machine/reference.md +0 -260
package/docs/strangler-fig.md
CHANGED
|
@@ -24,29 +24,33 @@ export async function runTicket(ticket: Ticket, effects: SupportEffects): Promis
|
|
|
24
24
|
}
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
- Each effect is an async function.
|
|
27
|
+
- Each effect is an async function. A wrapped or recorded effect returns a Promise even when the original returns an async iterable at once: write `yield* await effects.stream()`.
|
|
28
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
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
|
|
30
|
+
- An effect whose natural result is a live object (an agent instance) returns its name or id instead. The function that starts the run keeps a `Map` from id to object, created per run. See [Live objects](#live-objects).
|
|
31
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
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
33
|
|
|
34
34
|
### Class-shaped code
|
|
35
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:
|
|
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 (a phase in the middle of a method is extracted at step 0, see [A phase in the middle of a method](#a-phase-in-the-middle-of-a-method)):
|
|
37
37
|
|
|
38
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
|
+
- One wrapped workflow serves every instance: the instance goes in as `live`, and the workflow reads it from its context. `run: (input, effects, { live }: { live: Agent }) => live.run(input)`, then `step0.run(input, { live: agent, effects })`. With `live` typed, every `run` call must pass it.
|
|
39
40
|
- 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.
|
|
41
|
+
- Install each replacement with `Object.defineProperty` (non-enumerable). A plain assignment adds an own enumerable field, which the repo's state snapshots then serialize.
|
|
42
|
+
- The seam is on both sides of `checkParity`: `before` runs the class with the seam installed, so a serialization bug in the seam shows up on both sides and parity reports equivalent. Also compare the untouched class against the port by output, with no seam on the original, and add scenarios for edge results: empty, `null`, non-JSON values, `BigInt`.
|
|
40
43
|
|
|
41
44
|
### Seams for other shapes
|
|
42
45
|
|
|
43
|
-
| Shape
|
|
44
|
-
|
|
|
45
|
-
| Effect-TS generator
|
|
46
|
-
| Redux thunk
|
|
47
|
-
| LangGraph graph
|
|
48
|
-
| A closure inside a DI or Layer factory
|
|
49
|
-
|
|
|
46
|
+
| Shape | Seam |
|
|
47
|
+
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| 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. |
|
|
49
|
+
| Redux thunk | The thunk's `extra` argument plus its nested dispatches. Wrap `dispatch` so every nested thunk gets the effects-backed `extra`. |
|
|
50
|
+
| 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. |
|
|
51
|
+
| A closure inside a DI or Layer factory | Copy the module, identical outside the carved function, and swap it in with a module mock. |
|
|
52
|
+
| Async generator the consumer pulls (yields events, `.return()` on break, `.throw()` to interrupt) | Step 0: wrap the host call that drains the generator, with the collected events as the output. Carve: the machine runs the loop head and each pass is an actor. `createGeneratorBridge` carries the pull contract across: the actor calls `bridge.forward(legacyPass())` and the original generator becomes `yield* bridge.stream(runAgent(...))`. Each value waits for the consumer's next pull, `.throw()` reaches the legacy generator, and `.return()` unwinds it and awaits the run before it resolves. Code after the `yield*` does not run on `.return()`; put cleanup in a `finally`. As with `yield*`, a consumer that pulls a value yielded while unwinding resumes the pass: it completes normally (`forward` reports `closed: false`), and the code after the `yield*` runs. |
|
|
53
|
+
| 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
54
|
|
|
51
55
|
## Step 0: wrap
|
|
52
56
|
|
|
@@ -109,9 +113,9 @@ Each effect call is two events, `effect.call` then `effect.done` or `effect.erro
|
|
|
109
113
|
|
|
110
114
|
`support.run(input, options)` takes these `runAgent` options: `signal`, `inspect`, `onTransition`, `onTrace`, `onEvent`, `metadata`, and `verification`. Two more are its own:
|
|
111
115
|
|
|
112
|
-
| Option | Purpose
|
|
113
|
-
| ---------- |
|
|
114
|
-
| `effects` | Replaces some effects for one run: fakes, stubs, replay stand-ins
|
|
116
|
+
| Option | Purpose |
|
|
117
|
+
| ---------- | --------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `effects` | Replaces some effects for one run: fakes, stubs, replay stand-ins |
|
|
115
119
|
| `recorder` | Wraps every effect with `recorder.fn(name, fn)` and records the result with `recorder.output` |
|
|
116
120
|
|
|
117
121
|
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.
|
|
@@ -179,11 +183,70 @@ resolving: {
|
|
|
179
183
|
- 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
184
|
- 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
185
|
|
|
186
|
+
### Live objects
|
|
187
|
+
|
|
188
|
+
A store, a class instance, a session or a cancellation token cannot go in context, input or events: those are journaled JSON. Bind the actors and actions that need them per run, as closures, in the function that starts the run.
|
|
189
|
+
|
|
190
|
+
```ts no-check
|
|
191
|
+
const machine = setupAgent({
|
|
192
|
+
// ...schemas
|
|
193
|
+
actions: { setStatus: (_params: { status: string }) => {} }, // default for tests and explorePaths
|
|
194
|
+
actors: { think: createAsyncLogic({ run: async () => ({ kind: "final" }) }) },
|
|
195
|
+
}).createMachine({
|
|
196
|
+
// ...
|
|
197
|
+
entry: ({ actions }, enq) => enq(actions.setStatus, { status: "thinking" }),
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
async function agenticLoop(agent: Agent, task: Task) {
|
|
201
|
+
return runAgent(machine, {
|
|
202
|
+
input: { taskId: task.id },
|
|
203
|
+
actions: { setStatus: ({ status }) => agent.store.setStatus(task, status) },
|
|
204
|
+
actors: {
|
|
205
|
+
think: createAsyncLogic({ run: () => legacy.executeThinking.call(agent, agent, task) }),
|
|
206
|
+
},
|
|
207
|
+
});
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
- `runAgent`'s `actions` and `actors` are merged onto the machine for that run only. Concurrent runs each see their own objects.
|
|
212
|
+
- `actions` keys and params are checked against the actions declared in `setupAgent`. Declare a no-op for each; it is the default for tests and `explorePaths`.
|
|
213
|
+
- Only actors and actions read live objects. A guard, a `choice` or a transition function that reads one makes a decision the log does not record, so replay, resume and `explorePaths` can reach another state. Copy what the machine branches on into an actor's output.
|
|
214
|
+
- An action runs through `enq(...)`, after the transition. A `{ context }` it returns is ignored.
|
|
215
|
+
- Resume binds the same way: the host builds the actors and actions again and passes them with the snapshot or `store`. Nothing about the live objects is journaled.
|
|
216
|
+
- An effect whose result is a live object (an agent instance) records an id. Keep the id-to-object `Map` in the same function, created per run, never at module level.
|
|
217
|
+
|
|
182
218
|
### A phase in the middle of a method
|
|
183
219
|
|
|
184
|
-
|
|
220
|
+
Extract the phase first, then carve. The carved actor calls the extracted method or function, and nothing is copied.
|
|
221
|
+
|
|
222
|
+
- The extract is a step 0 edit: move the loop body or the phase into its own method or function, with no change in behavior. In a class, make it a protected method when the carve is a subclass that builds its actors inside the class body (the drop-in runner the old suite swaps in). An actor built outside the class calls a public method instead, marked `@internal`. Either way the actor calls it on the instance, bound per run.
|
|
223
|
+
- Commit it on its own, before any carve, so the diff is a pure move.
|
|
224
|
+
- Gate it like step 0: the old suite passes unchanged, and `checkParity` against the code before the extract is equivalent on every scenario. `examples/strangler-fig/before-extract.ts` is the one-function original; `index.test.ts` checks the extracted `runTicket` against it.
|
|
225
|
+
- A loop whose head lives in a private method: extract the body (`this._cycle(state)`), so the loop head is the only line the carve replaces.
|
|
185
226
|
- 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
227
|
|
|
228
|
+
#### Code you can't edit
|
|
229
|
+
|
|
230
|
+
For vendored or third-party code (in `node_modules` or a pinned fork), copy only that phase's lines into the carved actor, with a comment listing the copied line ranges.
|
|
231
|
+
|
|
232
|
+
- `checkParity` call-args catch a drifted copy only when the drift changes an effect's arguments.
|
|
233
|
+
- Add a drift test that hashes each copied range in the original, so an upstream change fails CI:
|
|
234
|
+
|
|
235
|
+
```ts no-check
|
|
236
|
+
import { createHash } from "node:crypto";
|
|
237
|
+
import { readFileSync } from "node:fs";
|
|
238
|
+
|
|
239
|
+
const lines = readFileSync(require.resolve("vendor-lib/dist/runtime.js"), "utf8").split("\n");
|
|
240
|
+
const hash = (from: number, to: number) =>
|
|
241
|
+
createHash("sha256")
|
|
242
|
+
.update(lines.slice(from - 1, to).join("\n"))
|
|
243
|
+
.digest("hex");
|
|
244
|
+
|
|
245
|
+
test("copied ranges match the original", () => {
|
|
246
|
+
expect(hash(412, 470)).toBe("<sha256 recorded when you copied>");
|
|
247
|
+
});
|
|
248
|
+
```
|
|
249
|
+
|
|
187
250
|
## Check parity
|
|
188
251
|
|
|
189
252
|
`checkParity` from `@statelyai/agent/testing` checks a step against the original, scenario by scenario.
|
|
@@ -217,16 +280,20 @@ What it does per scenario:
|
|
|
217
280
|
2. Runs `after` on replay stand-ins: each call is answered from the recording, and no effect runs.
|
|
218
281
|
3. Compares the two recordings with `compareRecordings`: effect names, call order, arguments, results, and the output.
|
|
219
282
|
|
|
220
|
-
| Field
|
|
221
|
-
|
|
|
222
|
-
| `report.equivalent`
|
|
223
|
-
| `row.divergences`
|
|
224
|
-
| `row.before` / `row.after`
|
|
225
|
-
| `row.recording` / `row.replay` | The baseline recording, and what `after` did in replay
|
|
283
|
+
| Field | Value |
|
|
284
|
+
| ------------------------------ | ----------------------------------------------------------------- |
|
|
285
|
+
| `report.equivalent` | `true` when every scenario is |
|
|
286
|
+
| `row.divergences` | `compareRecordings` divergences: `call-args`, `missing-effect`, … |
|
|
287
|
+
| `row.before` / `row.after` | `{ output }` or `{ error }` |
|
|
288
|
+
| `row.recording` / `row.replay` | The baseline recording, and what `after` did in replay |
|
|
289
|
+
| `report.scenarios` | The rows, one per scenario, in order |
|
|
226
290
|
|
|
227
291
|
- 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
292
|
- When both sides throw, they match on the error's name and message.
|
|
293
|
+
- Replay throws a recorded error with its name, message, number and boolean fields, `cause`, and an `AggregateError`'s `errors`. It is a plain `Error` or `AggregateError`. When the code branches on `instanceof`, pass `reviveError` to build its own class: `reviveError: (recorded) => recorded.name === "AbortError" ? new AbortError(recorded.message) : undefined`. A recorder takes the same option.
|
|
294
|
+
- An effect result that is not JSON (a class instance, a `Response`) records as its JSON and replays as a plain value. Pass `recordOptions: { lookupOrder: { serialize, revive } }` to `checkParity` or `wrapWorkflow().run` to keep the class in replay.
|
|
229
295
|
- `compare` passes options through to `compareRecordings`, such as `normalize` for generated ids.
|
|
296
|
+
- `setup: (scenario, side) => liveObject` builds what one side runs on (a class instance, a session). It is called once for `before` and once for `after`, and its result is the last argument of `effects`, `before` and `after`. Effects then bind to the object without a module-level slot, and a mutable object does not carry state from `before` into `after`.
|
|
230
297
|
|
|
231
298
|
### Generated ids
|
|
232
299
|
|
|
@@ -279,26 +346,31 @@ Run the module's own tests against the port by swapping the module.
|
|
|
279
346
|
- 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
347
|
- 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
348
|
- 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.
|
|
349
|
+
- Old code that registers its in-flight call with a host registry synchronously (a store's tracked promises, a map of `AbortController`s), so that pause or stop can cancel it: register the run in the same tick, before calling `runAgent`, with a promise that settles when the run does, and pass the registry's signal as `signal`. An abort in the same tick as the `runAgent` call settles the run `aborted` before any actor starts. Otherwise a pause and resume that land before the run starts leave the first run going next to the resumed one.
|
|
282
350
|
- `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
351
|
|
|
284
352
|
## Repeat
|
|
285
353
|
|
|
286
354
|
Each carved phase adds what the machine can prove:
|
|
287
355
|
|
|
288
|
-
| Step | Change
|
|
289
|
-
| ---- |
|
|
290
|
-
| 0 | none
|
|
291
|
-
| 1 | classify retry becomes states
|
|
292
|
-
| n | the last phase becomes states
|
|
356
|
+
| Step | Change | Gained |
|
|
357
|
+
| ---- | ----------------------------- | ------------------------------------------------------------------ |
|
|
358
|
+
| 0 | none | transitions, traces, event log, `signal`, a recorded baseline |
|
|
359
|
+
| 1 | classify retry becomes states | `canReach` proves the classifier runs at most `MAX_ATTEMPTS` times |
|
|
360
|
+
| n | the last phase becomes states | the machine is the workflow; drop the wrapper |
|
|
293
361
|
|
|
294
362
|
The step 1 proof in `examples/strangler-fig/index.test.ts`:
|
|
295
363
|
|
|
296
364
|
```ts no-check
|
|
297
|
-
const tooMany = await canReach(
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
365
|
+
const tooMany = await canReach(
|
|
366
|
+
supportMachine,
|
|
367
|
+
(snapshot) => snapshot.context.attempts > MAX_ATTEMPTS,
|
|
368
|
+
{
|
|
369
|
+
input: ticket,
|
|
370
|
+
outputs: { classify: [classification], resolve: [resolved] },
|
|
371
|
+
errors: { classify: new Error("model overloaded") },
|
|
372
|
+
},
|
|
373
|
+
);
|
|
302
374
|
// { reachable: false, complete: true }
|
|
303
375
|
```
|
|
304
376
|
|
|
@@ -310,7 +382,7 @@ Step 0 cannot give this proof: its one `running` state holds the whole function.
|
|
|
310
382
|
- No resume in the middle of the function. A resumed run starts the workflow again.
|
|
311
383
|
- `canReach` and `explorePaths` prove nothing about the wrapped function's inside.
|
|
312
384
|
- 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
|
|
385
|
+
- 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 per-run map from id to object.
|
|
314
386
|
- `checkParity` runs `before` on the effects you give it for real. Give it fakes or an isolated fixture, never production writes.
|
|
315
387
|
- `effects` are async functions only. A sync function or a client object goes behind an async function first.
|
|
316
388
|
- Parity covers what goes through `effects` and the output. A change in a call made around `effects` is not seen.
|
|
@@ -318,6 +390,6 @@ Step 0 cannot give this proof: its one `running` state holds the whole function.
|
|
|
318
390
|
## Related
|
|
319
391
|
|
|
320
392
|
- [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): `
|
|
393
|
+
- [Evals](evals.md#parity-with-the-code-you-replace): which of `checkParity`, `createRecorder` with `compareRecordings`, and `compareRuns` fits the code you replace.
|
|
322
394
|
- [Verify](verify.md): `canReach` and `explorePaths`.
|
|
323
|
-
- [`
|
|
395
|
+
- [`loop-to-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/loop-to-machine/SKILL.md): the retrofit, run by a coding agent.
|
package/docs/text-requests.md
CHANGED
|
@@ -128,16 +128,16 @@ export const triageTicket = createTextLogic({
|
|
|
128
128
|
});
|
|
129
129
|
```
|
|
130
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 `
|
|
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 `runAgent`'s `onResult(request, { raw })`, and as a `reasoning` field on the `request.end` `onTrace` event. Text-mode requests ignore the option.
|
|
132
132
|
|
|
133
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
134
|
|
|
135
135
|
## Streaming requests
|
|
136
136
|
|
|
137
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
|
|
138
|
+
<!-- viz: sequence diagram of a streaming request: state invokes the request -> host streamText executor -> chunks delivered to runAgent onChunk while the invoke is pending -> final text resolves onDone -->
|
|
139
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 `
|
|
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 `runAgent`'s `onChunk`.
|
|
141
141
|
|
|
142
142
|
```ts no-check
|
|
143
143
|
export const tellJoke = createTextLogic({
|
|
@@ -148,18 +148,16 @@ export const tellJoke = createTextLogic({
|
|
|
148
148
|
prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
|
|
149
149
|
});
|
|
150
150
|
|
|
151
|
-
const result = await
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
{ input: { topic: "state machines" } },
|
|
157
|
-
);
|
|
151
|
+
const result = await runAgent(machine, {
|
|
152
|
+
executors: createAiSdkExecutors({ models }),
|
|
153
|
+
onChunk: (chunk) => process.stdout.write(chunk),
|
|
154
|
+
input: { topic: "state machines" },
|
|
155
|
+
});
|
|
158
156
|
```
|
|
159
157
|
|
|
160
158
|
- `onChunk` fires once per chunk and receives the request that produced it, so parallel streams stay distinguishable.
|
|
161
159
|
- `onChunk` is observational only. It cannot change the run.
|
|
162
|
-
- A `mode: 'stream'` request needs a `streamText` executor. Without one, `
|
|
160
|
+
- A `mode: 'stream'` request needs a `streamText` executor. Without one, `runAgent` fails at bind time.
|
|
163
161
|
|
|
164
162
|
See [parallel-streams](https://github.com/statelyai/agent/blob/next/examples/parallel-streams/index.ts).
|
|
165
163
|
|
|
@@ -169,7 +167,7 @@ See [parallel-streams](https://github.com/statelyai/agent/blob/next/examples/par
|
|
|
169
167
|
|
|
170
168
|
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
169
|
|
|
172
|
-
The reason reaches observability the way per-call usage does: `
|
|
170
|
+
The reason reaches observability the way per-call usage does: `runAgent` lifts it onto the `request.end` [trace event](observability.md), next to `usage`.
|
|
173
171
|
|
|
174
172
|
`'length'` means the output token limit cut the call off. What that costs depends on the request:
|
|
175
173
|
|
|
@@ -13,7 +13,7 @@ For the mechanical refactor of an existing codebase, see [Migrating from a hand-
|
|
|
13
13
|
|
|
14
14
|
<!-- xstate version requirement from package.json#peerDependencies -->
|
|
15
15
|
|
|
16
|
-
> **Version requirement.** Build the machine with the exact `xstate` version this package peers on, `6.0.0-beta.
|
|
16
|
+
> **Version requirement.** Build the machine with the exact `xstate` version this package peers on, `6.0.0-beta.2`. See the [Quickstart](quickstart.md). Machines authored for XState v5 usually port with few changes, but a machine object imported from a separate `xstate@5` install does not bind. Write event-transition guards as functions that return `undefined`. XState v6 drops named string guards on `on`, and the function form is what makes `snapshot.can(event)` reflect the guard.
|
|
17
17
|
|
|
18
18
|
## The loop to model
|
|
19
19
|
|
|
@@ -154,7 +154,7 @@ awaitingHuman: {
|
|
|
154
154
|
},
|
|
155
155
|
```
|
|
156
156
|
|
|
157
|
-
When no work is in flight, `
|
|
157
|
+
When no work is in flight, `runAgent` settles with `{ status: 'idle', snapshot }` instead of hanging. Persist the snapshot and show the person their options. [`getAcceptedEvents(snapshot)`](human-in-the-loop.md) lists the legal events. To resume later, in the same process or another one, pass the snapshot back with the event. See [Human in the loop](human-in-the-loop.md).
|
|
158
158
|
|
|
159
159
|
## The finished machine
|
|
160
160
|
|
|
@@ -163,7 +163,7 @@ The machine below makes the same four model calls and applies the same policy as
|
|
|
163
163
|
```ts
|
|
164
164
|
import { z } from "zod";
|
|
165
165
|
import { openai } from "@ai-sdk/openai";
|
|
166
|
-
import { createTextLogic,
|
|
166
|
+
import { createTextLogic, setupAgent, runAgent } from "@statelyai/agent";
|
|
167
167
|
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
168
168
|
|
|
169
169
|
// Model IDs here are illustrative; substitute your provider's current models.
|
|
@@ -284,10 +284,10 @@ const triageMachine = agentSetup.createMachine({
|
|
|
284
284
|
},
|
|
285
285
|
});
|
|
286
286
|
|
|
287
|
-
const result = await
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
);
|
|
287
|
+
const result = await runAgent(triageMachine, {
|
|
288
|
+
executors: createAiSdkExecutors({ models }),
|
|
289
|
+
input: { ticket: "I was charged twice for March." },
|
|
290
|
+
});
|
|
291
291
|
if (result.status === "done") console.log(result.output.reply);
|
|
292
292
|
if (result.status === "idle") console.log("waiting on a human", result.snapshot);
|
|
293
293
|
```
|
|
@@ -314,7 +314,7 @@ The design work above assumes you are writing the machine. Existing machines can
|
|
|
314
314
|
|
|
315
315
|
- The machine already exists and contains nothing agent-specific. Any machine whose invokes resolve to values and whose events you can enumerate can be driven. Use [`getAcceptedEvents(snapshot)`](human-in-the-loop.md) for the candidates and call `resolveDecision` gated by `snapshot.can(event)`. See [plain-xstate](https://github.com/statelyai/agent/blob/next/examples/plain-xstate/index.ts).
|
|
316
316
|
|
|
317
|
-
Prompts do not have to live in the machine. Leave bare `src` strings and bind a separate prompt map through the `actors` option of `
|
|
317
|
+
Prompts do not have to live in the machine. Leave bare `src` strings and bind a separate prompt map through the `actors` option of `runAgent`, which is shorthand for `machine.provide({ actors })`. The explicit invokes remain part of the graph, which is what lets a machine round-trip through JSON with `setupAgent.fromConfig`. See [Machines as data](machines-as-data.md).
|
|
318
318
|
|
|
319
319
|
## Related
|
|
320
320
|
|
package/docs/tools.md
CHANGED
|
@@ -105,13 +105,13 @@ export const toolCallingMachine = agentSetup.createMachine({
|
|
|
105
105
|
Run the machine with any executor set. The machine is the same for scripted and real models.
|
|
106
106
|
|
|
107
107
|
```ts
|
|
108
|
-
import {
|
|
108
|
+
import { runAgent } from "@statelyai/agent";
|
|
109
109
|
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
110
110
|
|
|
111
|
-
const result = await
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
);
|
|
111
|
+
const result = await runAgent(toolCallingMachine, {
|
|
112
|
+
executors: createAiSdkExecutors({ models }),
|
|
113
|
+
input: { query: "What is 42 times 17?" },
|
|
114
|
+
});
|
|
115
115
|
```
|
|
116
116
|
|
|
117
117
|
For approval and progress around real tools, see [review-tool-calls](https://github.com/statelyai/agent/blob/next/examples/review-tool-calls/index.ts).
|
|
@@ -135,7 +135,7 @@ Two consequences follow:
|
|
|
135
135
|
- Tool-carrying requests do not retry. The AI SDK adapter retries invalid structured output only when the request has no tools, because a tool loop may already have caused side effects.
|
|
136
136
|
- `metadata` is host-owned. A host that does not understand a key ignores it, so requests stay portable.
|
|
137
137
|
|
|
138
|
-
The raw executor result, including tool calls and results, reaches host code through `
|
|
138
|
+
The raw executor result, including tool calls and results, reaches host code through `runAgent`'s `onResult(request, { raw })` and the `request.end` trace event. See [Observability](observability.md).
|
|
139
139
|
|
|
140
140
|
## Tool results in messages
|
|
141
141
|
|
|
@@ -161,14 +161,12 @@ answering: {
|
|
|
161
161
|
|
|
162
162
|
Build these parts by hand only when the machine owns the loop, such as in a ReAct-style machine or when replaying a transcript. With a host-run tool loop, the intermediate calls stay inside the executor. See [Messages](messages.md).
|
|
163
163
|
|
|
164
|
-
##
|
|
165
|
-
|
|
166
|
-
`createToolLoopMachine` from `@statelyai/agent/machines` is a prebuilt version of the machine above: one `answering` state and one tool-carrying request. See [Preset machines](machines-presets.md) for its options, including `maxSteps`.
|
|
164
|
+
## Beyond one request
|
|
167
165
|
|
|
168
|
-
|
|
166
|
+
Model the tool loop as machine states when it needs states of its own:
|
|
169
167
|
|
|
170
168
|
- To approve or reject each of a turn's tool calls before it runs, use `createApprovalBatchMachine`. See [Approval gate](#approval-gate).
|
|
171
|
-
- To model approval as machine states, with approve, edit, and reject steps that persist and resume,
|
|
169
|
+
- To model approval as machine states, with approve, edit, and reject steps that persist and resume, start from [examples/review-tool-calls](https://github.com/statelyai/agent/blob/next/examples/review-tool-calls/index.ts).
|
|
172
170
|
- To model each think, act, and observe turn as its own transition, use explicit request, tool, and observation states.
|
|
173
171
|
|
|
174
172
|
> **Note:** There is no built-in MCP client. MCP discovery, auth, and transport are the host's responsibility. Pass the discovered tool descriptors into `tools` like any other tool. See [Scope](scope.md).
|
|
@@ -246,4 +244,4 @@ await generateText({
|
|
|
246
244
|
- Read more about [Text requests](text-requests.md), the request a tool attaches to, including structured and streaming output.
|
|
247
245
|
- Read more about [Hosts](hosts.md), including executors, model aliases, and writing your own adapter.
|
|
248
246
|
- Read more about [Messages](messages.md), the message model that tool parts live in.
|
|
249
|
-
- Read more about [Preset machines](machines-presets.md), including `
|
|
247
|
+
- Read more about [Preset machines](machines-presets.md), including `createApprovalBatchMachine`.
|
package/docs/upgrading.md
CHANGED
|
@@ -9,7 +9,7 @@ This page lists the breaking changes an app on an earlier 2.0 alpha is most like
|
|
|
9
9
|
|
|
10
10
|
## Peer versions
|
|
11
11
|
|
|
12
|
-
- **XState:** exactly the version in the package's `peerDependencies` (`6.0.0-beta.
|
|
12
|
+
- **XState:** exactly the version in the package's `peerDependencies` (`6.0.0-beta.2` today). Upgrade it in the same change as the agent package.
|
|
13
13
|
- **AI SDK:** `ai` 7.0.128 or newer for `@statelyai/agent/ai-sdk`, which imports `experimental_decide`. An older `ai` fails at import time with `does not provide an export named 'experimental_decide'`. Adapter SDKs are optional peers with no version range, so npm installs the core next to any `ai`, `openai`, `@tanstack/ai`, or `ajv`.
|
|
14
14
|
- **Ajv:** `ajv` 8.20.0 or newer for `@statelyai/agent/validate`, which imports `ajv/dist/2020.js`. Ajv 6 installs, then fails when that subpath is imported.
|
|
15
15
|
|
|
@@ -17,7 +17,7 @@ Usage is available at three layers, listed from coarsest to finest.
|
|
|
17
17
|
|
|
18
18
|
The first two layers are observational. Only the third can change what the agent does.
|
|
19
19
|
|
|
20
|
-
<!-- viz: usage flow: executor result ->
|
|
20
|
+
<!-- viz: usage flow: executor result -> runAgent aggregation into result.usage, -> onResult/onTrace on the host, -> @agent.usage event into machine context and guards -->
|
|
21
21
|
|
|
22
22
|
## The usage result
|
|
23
23
|
|
|
@@ -26,7 +26,7 @@ The first two layers are observational. Only the third can change what the agent
|
|
|
26
26
|
Every settled `AgentRunResult` carries `usage`, on all three variants: `done`, `idle`, and `error`.
|
|
27
27
|
|
|
28
28
|
```ts
|
|
29
|
-
const result = await
|
|
29
|
+
const result = await runAgent(machine, { executors, input });
|
|
30
30
|
|
|
31
31
|
result.usage.modelCalls; // number, always present
|
|
32
32
|
result.usage.totalTokens; // number | undefined (only calls that reported it)
|
|
@@ -44,7 +44,7 @@ Four things affect how you read these numbers.
|
|
|
44
44
|
- Usage is per run, not per conversation. A resumed run counts only its own calls, not the history behind `snapshot` or `events`. Add prior results' totals yourself for a conversation-wide figure.
|
|
45
45
|
- A tool loop is one request but several model calls. An executor reports its steps as `modelCalls` on its result, and the adapters do. An executor that reports none counts as one call.
|
|
46
46
|
- Judgments are not counted. An `experimental_decide` actor is an ordinary actor, so its calls appear in neither `usage` nor `maxModelCalls`. See [Judgments](judgments.md).
|
|
47
|
-
- Usage comes from your executor. `
|
|
47
|
+
- Usage comes from your executor. `runAgent` reads `usage` from the raw executor result. That is the `usage` field alongside `result`, on the flat field names the AI SDK also uses, from an adapter or any custom executor following that shape. Non-finite values are dropped.
|
|
48
48
|
|
|
49
49
|
### Billing
|
|
50
50
|
|
|
@@ -80,23 +80,21 @@ Two callbacks report usage per call. Both are live and read-only.
|
|
|
80
80
|
- `onTrace` on a `request.end` event: `usage?: AgentCallUsage` is normalized, and present only when the executor reported usage. See [Observability](observability.md#trace-one-run).
|
|
81
81
|
|
|
82
82
|
```ts
|
|
83
|
-
await
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
{ input },
|
|
99
|
-
);
|
|
83
|
+
await runAgent(machine, {
|
|
84
|
+
executors,
|
|
85
|
+
onResult: (request, { raw }) => {
|
|
86
|
+
const usage = (raw as { usage?: AgentCallUsage }).usage;
|
|
87
|
+
if (usage) {
|
|
88
|
+
console.log(request.kind, request.id, usage);
|
|
89
|
+
}
|
|
90
|
+
},
|
|
91
|
+
onTrace: (event) => {
|
|
92
|
+
if (event.type === "request.end" && event.usage) {
|
|
93
|
+
console.log(event.request.id, event.usage.totalTokens);
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
input,
|
|
97
|
+
});
|
|
100
98
|
```
|
|
101
99
|
|
|
102
100
|
Use these for dashboards, per-tenant metering, and cost alerts. Neither can stop the run. To deliver usage to the machine, use [`@agent.usage`](#the-agentusage-event).
|
|
@@ -106,10 +104,7 @@ Use these for dashboards, per-tenant metering, and cost alerts. Neither can stop
|
|
|
106
104
|
`maxModelCalls` caps the number of model and decision calls one run may make. The default is `100`. Decision retries count separately.
|
|
107
105
|
|
|
108
106
|
```ts
|
|
109
|
-
const result = await
|
|
110
|
-
createAgentRuntime(machine, { executors, maxModelCalls: 20 }),
|
|
111
|
-
{ input },
|
|
112
|
-
);
|
|
107
|
+
const result = await runAgent(machine, { executors, maxModelCalls: 20, input });
|
|
113
108
|
|
|
114
109
|
if (result.status === "error" && result.cause === "max-model-calls") {
|
|
115
110
|
result.usage.modelCalls; // 20
|
|
@@ -128,10 +123,13 @@ if (result.status === "error" && result.cause === "max-model-calls") {
|
|
|
128
123
|
`maxModelCalls` is per run. For a conversation that resumes once per turn, pass the calls earlier turns spent as `modelCallsSpent`. They count against `maxModelCalls` and appear in `budget.modelCalls`, but not in this run's `usage.modelCalls`.
|
|
129
124
|
|
|
130
125
|
```ts no-check
|
|
131
|
-
const result = await
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
126
|
+
const result = await runAgent(machine, {
|
|
127
|
+
executors,
|
|
128
|
+
maxModelCalls: 30,
|
|
129
|
+
modelCallsSpent: thread.modelCalls,
|
|
130
|
+
snapshot,
|
|
131
|
+
event,
|
|
132
|
+
});
|
|
135
133
|
thread.modelCalls += result.usage.modelCalls;
|
|
136
134
|
```
|
|
137
135
|
|
|
@@ -172,9 +170,7 @@ function withBudget(base: AgentRequestExecutors, maxCalls: number): AgentRequest
|
|
|
172
170
|
};
|
|
173
171
|
}
|
|
174
172
|
|
|
175
|
-
await
|
|
176
|
-
input,
|
|
177
|
-
});
|
|
173
|
+
await runAgent(machine, { executors: withBudget(executors, 20), input });
|
|
178
174
|
```
|
|
179
175
|
|
|
180
176
|
A wrapper is still host-side. The machine cannot read its counts or react to them. For that, use `@agent.usage` and a guard.
|
|
@@ -215,7 +211,7 @@ Model-call results reach the machine with usage stripped out.
|
|
|
215
211
|
- A text invoke's `onDone` receives `{ result, messages }` only: the validated result and the executor's response messages. The runner drops the rest of the executor result, including usage (`src/run-agent.ts`).
|
|
216
212
|
- A decision delivers only the chosen event. `resolveDecision` returns the validated event and drops the executor's `usage` (`src/decision.ts`).
|
|
217
213
|
|
|
218
|
-
`@agent.usage` carries the tokens instead. After every settled model call that reported usage, `
|
|
214
|
+
`@agent.usage` carries the tokens instead. After every settled model call that reported usage, `runAgent` delivers the event to the machine, so `context` can fold it and guards can read it. You can then keep both counters in `context`: increment turns in `onDone`, and fold tokens in the `@agent.usage` handler.
|
|
219
215
|
|
|
220
216
|
### Rules
|
|
221
217
|
|
|
@@ -224,8 +220,8 @@ Model-call results reach the machine with usage stripped out.
|
|
|
224
220
|
| **Not model-facing** | The `@agent.*` namespace is excluded from `getAcceptedEvents` and `parseAgentEvent`. The event is never a decision candidate, even under `allowedEvents: ['*']`, and cannot be forged from a wire message. |
|
|
225
221
|
| **Durability** | The event is folded into machine context, so a native snapshot from `result.persist()` retains the counters when a later runtime resumes with `{ snapshot }`. |
|
|
226
222
|
| **Run scope** | `result.usage` counts calls made during that run only. Persist cumulative counters in machine context when they must survive snapshot resume. |
|
|
227
|
-
| **Stragglers** | A call that settles after a `
|
|
228
|
-
| **Coverage** | Only usage your executor reports is delivered. No `usage` on the result means no event. [`simulateAgent`](verify.md) scripts return no usage, so a token counter stays `0` under simulation. Test budgets with `
|
|
223
|
+
| **Stragglers** | A call that settles after a `runAgent` leg resolved still folds into `result.usage`, but its machine event is dropped. Watch `usage.dropped` on `onTrace` if a counter looks short. |
|
|
224
|
+
| **Coverage** | Only usage your executor reports is delivered. No `usage` on the result means no event. [`simulateAgent`](verify.md) scripts return no usage, so a token counter stays `0` under simulation. Test budgets with `runAgent` and a usage-reporting mock. |
|
|
229
225
|
|
|
230
226
|
Opt in with a transition.
|
|
231
227
|
|
|
@@ -267,8 +263,8 @@ import {
|
|
|
267
263
|
AGENT_USAGE_EVENT_TYPE,
|
|
268
264
|
createAgentSchemas,
|
|
269
265
|
createTextLogic,
|
|
270
|
-
runToQuiescence,
|
|
271
266
|
setupAgent,
|
|
267
|
+
runAgent,
|
|
272
268
|
} from "@statelyai/agent";
|
|
273
269
|
|
|
274
270
|
const researchStep = createTextLogic({
|
|
@@ -357,10 +353,11 @@ const executors = {
|
|
|
357
353
|
}),
|
|
358
354
|
};
|
|
359
355
|
|
|
360
|
-
const result = await
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
356
|
+
const result = await runAgent(machine, {
|
|
357
|
+
maxModelCalls: 20,
|
|
358
|
+
executors,
|
|
359
|
+
input: { topic: "otter migration", maxTurns: 5, maxTokens: 1500 },
|
|
360
|
+
});
|
|
364
361
|
|
|
365
362
|
if (result.status === "done") {
|
|
366
363
|
result.output.stoppedBy; // 'tokens' (3 calls, 1560 >= 1500)
|
|
@@ -397,11 +394,11 @@ deciding: {
|
|
|
397
394
|
}
|
|
398
395
|
```
|
|
399
396
|
|
|
400
|
-
## Usage without
|
|
397
|
+
## Usage without runAgent
|
|
401
398
|
|
|
402
399
|
### Uncontrolled: `provideExecutors` + `createActor`
|
|
403
400
|
|
|
404
|
-
Delivery is built in, but it follows the binding boundary. `provideExecutors` does not descend into invoked child machines, so a child with its own agent invokes needs its own `provideExecutors(...)` call. Until it has one, its calls report no usage anywhere. `
|
|
401
|
+
Delivery is built in, but it follows the binding boundary. `provideExecutors` does not descend into invoked child machines, so a child with its own agent invokes needs its own `provideExecutors(...)` call. Until it has one, its calls report no usage anywhere. `runAgent` rebinds children and reports their usage to the root. A [long-lived actor](choosing-a-run-mode.md#long-lived-actor) has no run cycle, so no stragglers are dropped either.
|
|
405
402
|
|
|
406
403
|
```ts no-check
|
|
407
404
|
import { createActor, toPromise } from "xstate";
|
|
@@ -481,21 +478,19 @@ estimateCost("openai/gpt-6-luna", result.usage);
|
|
|
481
478
|
```ts no-check
|
|
482
479
|
let spentUsd = 0;
|
|
483
480
|
|
|
484
|
-
await
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
{ input },
|
|
498
|
-
);
|
|
481
|
+
await runAgent(machine, {
|
|
482
|
+
executors,
|
|
483
|
+
onTrace: (event) => {
|
|
484
|
+
if (event.type !== "request.end" || !event.usage) {
|
|
485
|
+
return;
|
|
486
|
+
}
|
|
487
|
+
// A decision carries `model` directly; a text request carries it on `input`.
|
|
488
|
+
const model =
|
|
489
|
+
event.request.kind === "decision" ? event.request.model : event.request.input.model;
|
|
490
|
+
spentUsd += estimateCost(model, event.usage);
|
|
491
|
+
},
|
|
492
|
+
input,
|
|
493
|
+
});
|
|
499
494
|
```
|
|
500
495
|
|
|
501
496
|
`@agent.usage` carries the same `model` attribution, so the machine can keep a per-model spend counter in `context` and guard on it, instead of only reporting one from the host.
|