@statelyai/agent 2.0.0-alpha.36 → 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.
- package/CHANGELOG.md +27 -0
- package/dist/{effects-CuOUNYtZ.mjs → effects-BT_cSY0j.mjs} +95 -11
- package/dist/{effects-B23bFZEs.cjs → effects-DDseYtJk.cjs} +95 -11
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.mts +3 -3
- package/dist/index.mjs +1 -1
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-BcQ-9NRT.d.cts → run-agent-30mH2moE.d.cts} +2 -2
- package/dist/{run-agent-C86drZtN.d.mts → run-agent-DlPzBWj-.d.mts} +2 -2
- package/dist/{setup-agent-jlo4vtaZ.d.cts → setup-agent-BaNyz6Q3.d.cts} +1 -1
- package/dist/{setup-agent-BIKcbVXV.d.mts → setup-agent-C1CG_nfX.d.mts} +1 -1
- package/dist/testing.cjs +2411 -1799
- package/dist/testing.d.cts +167 -4
- package/dist/testing.d.mts +167 -4
- package/dist/testing.mjs +2412 -1801
- package/dist/{usage-HtnrUsl9.d.cts → usage-Bm5nvpow.d.cts} +5 -0
- package/dist/{usage-DoP0Oi84.d.mts → usage-BnikdOca.d.mts} +5 -0
- package/dist/validate.cjs +1 -1
- package/dist/validate.d.cts +2 -2
- package/dist/validate.d.mts +2 -2
- package/dist/validate.mjs +1 -1
- package/dist/{verify-Dpz1u5Pe.mjs → verify-ChyX6jq0.mjs} +75 -20
- package/dist/{verify-Bink-Drw.cjs → verify-CwlombbC.cjs} +75 -20
- package/dist/{verify-CciG8UP-.d.cts → verify-DJHfEfm6.d.cts} +9 -4
- package/dist/{verify-Buh8XSUr.d.mts → verify-i9Hiwc5g.d.mts} +9 -4
- package/docs/event-log.md +2 -1
- package/docs/persistence.md +71 -0
- package/docs/steps.md +2 -0
- package/docs/usage-and-budgets.md +2 -0
- package/docs/verify.md +7 -2
- package/package.json +1 -1
- package/skills/build-machine/SKILL.md +4 -1
|
@@ -190,6 +190,7 @@ A wrapper is still host-side. The machine cannot read its counts or react to the
|
|
|
190
190
|
- Delivery is opt-in. The event is delivered only when an active state declares a transition that matches it, either `'@agent.usage'` or the wildcard `'*'`. Otherwise no usage event is sent to the machine. Wildcard matching follows XState semantics, so a catch-all `on: { '*': … }` does receive `@agent.usage`. Narrow the handler on `event.type` when the catch-all is meant for other events.
|
|
191
191
|
- Declare the handler at machine level. A root `on: { '@agent.usage': … }` catches every call regardless of which state made it. A state-scoped handler drops calls made in other states.
|
|
192
192
|
- Delivery goes to the run's root machine, including usage from requests inside an invoked child machine. Attribute those calls with `id`, `src`, and `model`.
|
|
193
|
+
- Usage counts real spend across a crash. A call that re-executes on resume reports its usage again, so a token budget sees both attempts when the first attempt's usage was journaled before the crash. A call in flight at the crash that never reported usage is not counted.
|
|
193
194
|
|
|
194
195
|
The payload has this shape.
|
|
195
196
|
|
|
@@ -202,6 +203,7 @@ The payload has this shape.
|
|
|
202
203
|
src?: string, // the request's invoke src
|
|
203
204
|
model?: string, // the model ref it targeted
|
|
204
205
|
name?: string, // a text request's registered name
|
|
206
|
+
callKey?: string, // the call's idempotency key, with an event log
|
|
205
207
|
budget?: { modelCalls, maxModelCalls }, // counted against maxModelCalls so far, this call included
|
|
206
208
|
}
|
|
207
209
|
```
|
package/docs/verify.md
CHANGED
|
@@ -310,9 +310,11 @@ const result = await canReach(waitingMachine, "timedOut");
|
|
|
310
310
|
- The event is `{ type: '@agent.usage', kind: 'text', id, src, model, name?, usage }`, the run's shape without `budget`.
|
|
311
311
|
- Each listed value forks one branch, recorded in the path before `xstate.done.actor`.
|
|
312
312
|
- One value with one canned output is no fork: the output resolves straight through, but the usage event is still recorded in the path.
|
|
313
|
-
- A usage
|
|
313
|
+
- A usage value the active states refuse (`snapshot.can` is false) is dropped, as a run drops it: the request settles with no usage event delivered or recorded.
|
|
314
|
+
- A usage transition that leaves the invoking state, or restarts its invoke, cancels the request: its completion is not recorded, and a restarted invoke settles later on its own.
|
|
314
315
|
- A settling request with no `usage` entry while a usage transition is active lists `@agent.usage` in `vacuous`. Completeness is unchanged.
|
|
315
|
-
-
|
|
316
|
+
- With `children: "coupled"`, a child's text request with an entry forks one branch per value. The usage event goes to the root before the child's completion reaches its parent. The root takes it or drops it by the same rules. A child's request with no entry is not listed in `vacuous`.
|
|
317
|
+
- Requests inside `"outputs"` or `"explore"` children, and decisions, deliver no usage.
|
|
316
318
|
|
|
317
319
|
```ts no-check
|
|
318
320
|
const overBudget = await canReach(researchMachine, "outOfBudget", {
|
|
@@ -360,7 +362,9 @@ const report = await explorePaths(parentMachine, {
|
|
|
360
362
|
- The parent's host events arrive at its idle waits, including while every child waits on the host. While a child or the parent has work pending, they race it only with `interleave: "pending"`.
|
|
361
363
|
- What a child's move sends its own children, and their replies, happen in the same move. A child's send to a sibling is delivered to that sibling, entry sends included. A child's sends reach their targets in the order it made them, each run to quiescence before the next, as a live run does. A send to an actor the search does not model lists the event type in `unexpandedEvents`, so the report is not complete.
|
|
362
364
|
- Child moves count against `maxDepth` like the parent's own branches. On a path they carry `actor` with the child's id (a grandchild's as `child.grandchild`): the host events it received, its choices, its settled work. The events it sends the parent appear as the parent receives them.
|
|
365
|
+
- A target predicate and `dedupeBy` see each coupled child's explored state: `snapshot.children[id].getSnapshot()` returns the state the search stepped the child to, its own coupled children likewise. A parent's send and the child's receipt are one state, so a cross-actor invariant such as "every chunk the parent forwarded, a child received" can be a target.
|
|
363
366
|
- With `dedupeBy`, each child's state joins the key. Without it, every interleaving is explored in full.
|
|
367
|
+
- A coupled child's text requests deliver `@agent.usage` to the root, as a run does. See [Usage events](#usage-events).
|
|
364
368
|
- A child that stops on `needs-output` or `max-depth` ends the parent branch the same way, so the parent report is not complete.
|
|
365
369
|
|
|
366
370
|
Pass `hostEvents` when some types the parent accepts come only from its children, such as a child's status events. The search then offers only the listed types at the parent's waits.
|
|
@@ -479,6 +483,7 @@ For machines authored as data, validate the config with `validateAgentConfig(con
|
|
|
479
483
|
|
|
480
484
|
## Related
|
|
481
485
|
|
|
486
|
+
- [Crash testing](persistence.md#crash-testing): `checkCrashRecovery` kills a run at every log append and in-flight effect, and checks each resume.
|
|
482
487
|
- [Debugging](debugging.md): scripted reproduction and the diagnostic codes in context.
|
|
483
488
|
- [Evals](evals.md): scoring runs on output, trajectory, and budget.
|
|
484
489
|
- [Quickstart](quickstart.md#define-and-run-one-artifact): a plain-function executor for `runToQuiescence`.
|
package/package.json
CHANGED
|
@@ -62,7 +62,10 @@ expect(result).toMatchObject({ reachable: false, complete: true });
|
|
|
62
62
|
|
|
63
63
|
## 5. Crash and resume
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
Call `checkCrashRecovery(machine, { input, events, executors })` from `@statelyai/agent/testing` for each scenario, and assert `report.failures` is `[]`. It kills the run after every log append and while every effect is in flight, resumes each from the log, and checks the resume against an uninterrupted run. See `docs/persistence.md#crash-testing`.
|
|
66
|
+
|
|
67
|
+
- Executors and fake tools must answer from the request, not call order. A fake that keeps state passes `reset`.
|
|
68
|
+
- A failure names the crash point and the problem (`reran`, `skipped`, `outcome`, `stuck`, …). Fix the machine or the effect, never the check.
|
|
66
69
|
|
|
67
70
|
- A completed model call never runs again. An in-flight one re-runs with the same `info.callKey`.
|
|
68
71
|
- A plain actor (`createAsyncLogic`) in flight at the crash re-runs. It gets no call key, so derive an idempotency key from the domain (the ticket id, the booking key) and dedupe in the effect.
|