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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/evals.cjs +1 -1
  3. package/dist/evals.d.cts +1 -1
  4. package/dist/evals.d.mts +1 -1
  5. package/dist/evals.mjs +1 -1
  6. package/dist/index.cjs +17 -10
  7. package/dist/index.d.cts +28 -11
  8. package/dist/index.d.mts +28 -11
  9. package/dist/index.mjs +17 -10
  10. package/dist/machine-input-0YTPcnCm.mjs +27 -0
  11. package/dist/machine-input-DU3owLUr.cjs +32 -0
  12. package/dist/otel.d.cts +1 -1
  13. package/dist/otel.d.mts +1 -1
  14. package/dist/policy.cjs +1 -1
  15. package/dist/policy.d.cts +1 -1
  16. package/dist/policy.d.mts +1 -1
  17. package/dist/policy.mjs +1 -1
  18. package/dist/{run-agent-Dq0oSFRm.d.cts → run-agent-BO9RSb7i.d.cts} +16 -7
  19. package/dist/{run-agent-DHlq87G7.d.mts → run-agent-BxkeuAYR.d.mts} +16 -7
  20. package/dist/{run-agent-De3xVFGw.cjs → run-agent-COdR9FpM.cjs} +26 -27
  21. package/dist/{run-agent-BE7DOWD6.mjs → run-agent-D3gW9wfd.mjs} +27 -28
  22. package/dist/testing.cjs +2 -2
  23. package/dist/testing.d.cts +2 -2
  24. package/dist/testing.d.mts +2 -2
  25. package/dist/testing.mjs +2 -2
  26. package/dist/validate.cjs +1 -1
  27. package/dist/validate.d.cts +1 -1
  28. package/dist/validate.d.mts +1 -1
  29. package/dist/validate.mjs +1 -1
  30. package/dist/{verify-H3Pr2gNw.d.mts → verify-CIu4mqIZ.d.mts} +15 -1
  31. package/dist/{verify-BM0sGmsf.d.cts → verify-CTHlmBbh.d.cts} +15 -1
  32. package/dist/{verify-CWlg3j7B.mjs → verify-Cacz6XSk.mjs} +19 -3
  33. package/dist/{verify-Dek6gHCS.cjs → verify-D8UDqU4l.cjs} +19 -3
  34. package/docs/hosts.md +5 -3
  35. package/docs/strangler-fig.md +36 -29
  36. package/docs/verify.md +3 -2
  37. package/package.json +1 -1
@@ -36,20 +36,21 @@ export async function runTicket(ticket: Ticket, effects: SupportEffects): Promis
36
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.
40
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.
41
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`.
42
43
 
43
44
  ### Seams for other shapes
44
45
 
45
- | Shape | Seam |
46
- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47
- | 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. |
48
- | Redux thunk | The thunk's `extra` argument plus its nested dispatches. Wrap `dispatch` so every nested thunk gets the effects-backed `extra`. |
49
- | 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. |
50
- | A closure inside a DI or Layer factory | Copy the module, identical outside the carved function, and swap it in with a module mock. |
51
- | 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`. |
52
- | 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. |
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. |
53
54
 
54
55
  ## Step 0: wrap
55
56
 
@@ -112,9 +113,9 @@ Each effect call is two events, `effect.call` then `effect.done` or `effect.erro
112
113
 
113
114
  `support.run(input, options)` takes these `runAgent` options: `signal`, `inspect`, `onTransition`, `onTrace`, `onEvent`, `metadata`, and `verification`. Two more are its own:
114
115
 
115
- | Option | Purpose |
116
- | ---------- | ------------------------------------------------------------------------------------------- |
117
- | `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 |
118
119
  | `recorder` | Wraps every effect with `recorder.fn(name, fn)` and records the result with `recorder.output` |
119
120
 
120
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.
@@ -237,7 +238,9 @@ import { readFileSync } from "node:fs";
237
238
 
238
239
  const lines = readFileSync(require.resolve("vendor-lib/dist/runtime.js"), "utf8").split("\n");
239
240
  const hash = (from: number, to: number) =>
240
- createHash("sha256").update(lines.slice(from - 1, to).join("\n")).digest("hex");
241
+ createHash("sha256")
242
+ .update(lines.slice(from - 1, to).join("\n"))
243
+ .digest("hex");
241
244
 
242
245
  test("copied ranges match the original", () => {
243
246
  expect(hash(412, 470)).toBe("<sha256 recorded when you copied>");
@@ -277,13 +280,13 @@ What it does per scenario:
277
280
  2. Runs `after` on replay stand-ins: each call is answered from the recording, and no effect runs.
278
281
  3. Compares the two recordings with `compareRecordings`: effect names, call order, arguments, results, and the output.
279
282
 
280
- | Field | Value |
281
- | ---------------------------- | ---------------------------------------------------------------------- |
282
- | `report.equivalent` | `true` when every scenario is |
283
- | `row.divergences` | `compareRecordings` divergences: `call-args`, `missing-effect`, … |
284
- | `row.before` / `row.after` | `{ output }` or `{ error }` |
285
- | `row.recording` / `row.replay` | The baseline recording, and what `after` did in replay |
286
- | `report.scenarios` | The rows, one per scenario, in order |
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 |
287
290
 
288
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`.
289
292
  - When both sides throw, they match on the error's name and message.
@@ -350,20 +353,24 @@ Run the module's own tests against the port by swapping the module.
350
353
 
351
354
  Each carved phase adds what the machine can prove:
352
355
 
353
- | Step | Change | Gained |
354
- | ---- | ------------------------------ | --------------------------------------------------------------- |
355
- | 0 | none | transitions, traces, event log, `signal`, a recorded baseline |
356
- | 1 | classify retry becomes states | `canReach` proves the classifier runs at most `MAX_ATTEMPTS` times |
357
- | n | the last phase becomes states | the machine is the workflow; drop the wrapper |
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 |
358
361
 
359
362
  The step 1 proof in `examples/strangler-fig/index.test.ts`:
360
363
 
361
364
  ```ts no-check
362
- const tooMany = await canReach(supportMachine, (snapshot) => snapshot.context.attempts > MAX_ATTEMPTS, {
363
- input: ticket,
364
- outputs: { classify: [classification], resolve: [resolved] },
365
- errors: { classify: new Error("model overloaded") },
366
- });
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
+ );
367
374
  // { reachable: false, complete: true }
368
375
  ```
369
376
 
package/docs/verify.md CHANGED
@@ -45,7 +45,7 @@ assertAgentMachine(machine, { warnings: true });
45
45
  | `decide-without-events` | error | A state invokes `agent.decide` but neither it nor any ancestor handles any event, so the chosen event can never be delivered. |
46
46
  | `decide-allows-human-event` | error | A decision's literal `allowedEvents` names an event the state or an ancestor handles through a transition tagged `meta: { actor: "human" }`, so the model is never offered it. See [Events a person sends](decisions.md#events-a-person-sends). |
47
47
  | `invoke-without-on-error` | warning | An invoke declares no `onError`, and neither its state nor any ancestor handles an actor error, so a rejected request or actor lands the machine in an error state with no modeled recovery. Add `onError` targeting a `failed` final state or a bounded retry. |
48
- | `direct-object-src` | warning | An invoke `src` is a direct object or machine value that `runAgent` cannot rebind, so it inherits no host executors. |
48
+ | `direct-object-src` | warning | An invoke `src` is a direct object or machine value that `runAgent` cannot rebind, so it inherits no host executors. |
49
49
 
50
50
  ## Test assertions
51
51
 
@@ -173,6 +173,7 @@ settled?.resolvedRequest; // { kind: 'text', src: 'parse', id: 'parse', outcome:
173
173
 
174
174
  `explorePaths(machine, { input, maxDepth?, maxPaths?, maxNodes?, budget?, outputs?, errors?, payloads?, dedupeBy?, interleave?, children?, timers?, usage?, steps? })` enumerates decision and external-event branches without a model, and reports coverage.
175
175
 
176
+ - `input` is validated against the machine's input schema, as `runAgent` does. Input the schema rejects throws `AgentError` with code `invalid-machine-input`, so a misspelled field fails loudly instead of proving a rule over a start state no run can reach. The parsed value, with defaults filled, seeds the search. `canReach` and `simulateAgent` validate `input` the same way.
176
177
  - At each decision, it forks one branch per candidate event. Guard-rejected candidates count in `prunedByGuard` and are not explored.
177
178
  - A decision with no candidate the snapshot takes, because its guards refuse every one or the closed choice offers nothing, exhausts as it does in a live run. That branch records `{ type: 'xstate.error.actor', actorId }` and takes the invoke's `onError`. With no `onError`, it ends in an `error` terminal.
178
179
  - At an idle wait, it forks one branch per externally accepted event and per armed timer. See [Timers](#timers).
@@ -505,7 +506,7 @@ const turnAfterStop = await canReach(
505
506
  ```
506
507
 
507
508
  - `after` and `reach` match [steps](#steps). `after` is an event type or a step predicate.
508
- - `reach` is checked on each step after the first step that matched `after`, not on that step itself.
509
+ - `reach` is checked on the first step that matched `after` and every step after it. On the trigger's own step, `started`, `settled` and `state` are what the trigger's transition did, so a turn it starts is a violation. That step's `event` is the trigger itself: match its effects, not its event.
509
510
  - `after` and `reach` may read an event's payload, so an event with no schema is unexpanded until `payloads` lists its variants, even when no transition reads it. A timer's step carries the event the timer delivers.
510
511
  - The witness is the event sequence to the first violation.
511
512
  - A turn already running when STOP arrives started before it, so it is not a violation. Check that turn with `settled` if the rule covers it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statelyai/agent",
3
- "version": "2.0.0-alpha.39",
3
+ "version": "2.0.0-alpha.40",
4
4
  "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
5
5
  "keywords": [
6
6
  "agent",