@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.
- package/CHANGELOG.md +14 -0
- package/dist/evals.cjs +1 -1
- package/dist/evals.d.cts +1 -1
- package/dist/evals.d.mts +1 -1
- package/dist/evals.mjs +1 -1
- package/dist/index.cjs +17 -10
- package/dist/index.d.cts +28 -11
- package/dist/index.d.mts +28 -11
- package/dist/index.mjs +17 -10
- package/dist/machine-input-0YTPcnCm.mjs +27 -0
- package/dist/machine-input-DU3owLUr.cjs +32 -0
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/policy.cjs +1 -1
- package/dist/policy.d.cts +1 -1
- package/dist/policy.d.mts +1 -1
- package/dist/policy.mjs +1 -1
- package/dist/{run-agent-Dq0oSFRm.d.cts → run-agent-BO9RSb7i.d.cts} +16 -7
- package/dist/{run-agent-DHlq87G7.d.mts → run-agent-BxkeuAYR.d.mts} +16 -7
- package/dist/{run-agent-De3xVFGw.cjs → run-agent-COdR9FpM.cjs} +26 -27
- package/dist/{run-agent-BE7DOWD6.mjs → run-agent-D3gW9wfd.mjs} +27 -28
- package/dist/testing.cjs +2 -2
- package/dist/testing.d.cts +2 -2
- package/dist/testing.d.mts +2 -2
- package/dist/testing.mjs +2 -2
- package/dist/validate.cjs +1 -1
- package/dist/validate.d.cts +1 -1
- package/dist/validate.d.mts +1 -1
- package/dist/validate.mjs +1 -1
- package/dist/{verify-H3Pr2gNw.d.mts → verify-CIu4mqIZ.d.mts} +15 -1
- package/dist/{verify-BM0sGmsf.d.cts → verify-CTHlmBbh.d.cts} +15 -1
- package/dist/{verify-CWlg3j7B.mjs → verify-Cacz6XSk.mjs} +19 -3
- package/dist/{verify-Dek6gHCS.cjs → verify-D8UDqU4l.cjs} +19 -3
- package/docs/hosts.md +5 -3
- package/docs/strangler-fig.md +36 -29
- package/docs/verify.md +3 -2
- package/package.json +1 -1
package/docs/strangler-fig.md
CHANGED
|
@@ -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
|
|
46
|
-
|
|
|
47
|
-
| Effect-TS generator
|
|
48
|
-
| Redux thunk
|
|
49
|
-
| LangGraph graph
|
|
50
|
-
| A closure inside a DI or Layer factory
|
|
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`)
|
|
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")
|
|
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
|
|
281
|
-
|
|
|
282
|
-
| `report.equivalent`
|
|
283
|
-
| `row.divergences`
|
|
284
|
-
| `row.before` / `row.after`
|
|
285
|
-
| `row.recording` / `row.replay` | The baseline recording, and what `after` did in replay
|
|
286
|
-
| `report.scenarios`
|
|
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
|
|
354
|
-
| ---- |
|
|
355
|
-
| 0 | none
|
|
356
|
-
| 1 | classify retry becomes states
|
|
357
|
-
| 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 |
|
|
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(
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
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
|
|
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