@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
|
@@ -163,10 +163,7 @@ The machine's own cap is `checkingRepairBudget`. It is the one the app reasons a
|
|
|
163
163
|
`maxModelCalls` is the second cap, and a different kind. It is the host's runaway backstop, it counts every model and decision call in the run, and the machine cannot read it. See [Usage and budgets](usage-and-budgets.md#the-global-backstop-maxmodelcalls).
|
|
164
164
|
|
|
165
165
|
```ts no-check
|
|
166
|
-
const result = await
|
|
167
|
-
createAgentRuntime(machine, { executors, maxModelCalls: 10 }),
|
|
168
|
-
{ input },
|
|
169
|
-
);
|
|
166
|
+
const result = await runAgent(machine, { executors, maxModelCalls: 10, input });
|
|
170
167
|
```
|
|
171
168
|
|
|
172
169
|
With three author calls and `maxRepairs: 2`, a worst-case run makes five calls, so `result.usage.modelCalls` is `5`.
|
|
@@ -182,17 +179,15 @@ const answers: Record<string, string[]> = {
|
|
|
182
179
|
};
|
|
183
180
|
const calls: string[] = [];
|
|
184
181
|
|
|
185
|
-
const result = await
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
return { result: answers[request.name].shift() };
|
|
191
|
-
},
|
|
182
|
+
const result = await runAgent(machine, {
|
|
183
|
+
executors: {
|
|
184
|
+
generateText: async (request) => {
|
|
185
|
+
calls.push(request.name);
|
|
186
|
+
return { result: answers[request.name].shift() };
|
|
192
187
|
},
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
);
|
|
188
|
+
},
|
|
189
|
+
input: { prompt: "a turnstile" },
|
|
190
|
+
});
|
|
196
191
|
|
|
197
192
|
expect(result.output.repairs).toBe(1);
|
|
198
193
|
expect(calls).toEqual(["generateConfig", "generateConfig", "generateConfig", "repairConfig"]);
|
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 `
|
|
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
|
|
|
@@ -75,7 +75,7 @@ test("happy path settles done", async () => {
|
|
|
75
75
|
});
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
Guards stay in force throughout. `canReach` and `simulateAgent` traverse the same machine transitions as `
|
|
78
|
+
Guards stay in force throughout. `canReach` and `simulateAgent` traverse the same machine transitions as `runAgent`, so a graph path that a guard rejects never counts as reachable. These tests pin the machine's shape as prompts and models change.
|
|
79
79
|
|
|
80
80
|
## Deterministic executors
|
|
81
81
|
|
|
@@ -93,13 +93,13 @@ const machine = emailDrafter.provide({
|
|
|
93
93
|
|
|
94
94
|
[examples/email-drafter/agent-logic.ts](https://github.com/statelyai/agent/blob/next/examples/email-drafter/agent-logic.ts) drives a full run this way, with fixed values and no model call.
|
|
95
95
|
|
|
96
|
-
Use deterministic executors when the test should exercise the real `
|
|
96
|
+
Use deterministic executors when the test should exercise the real `runAgent` path with canned model output. Use [`simulateAgent`](#scripted-playthroughs) when a model-free transition playthrough is enough.
|
|
97
97
|
|
|
98
98
|
## Scripted playthroughs
|
|
99
99
|
|
|
100
100
|
`simulateAgent(machine, { input, script, maxSteps? })` runs a deterministic, model-free transition playthrough. The `script` supplies responses as FIFO queues, so runs are reproducible.
|
|
101
101
|
|
|
102
|
-
This script keys by invoke **src**, not by request name. Executors that run the real `
|
|
102
|
+
This script keys by invoke **src**, not by request name. Executors that run the real `runAgent` path route by request name instead. See [Testing without a provider](evals.md#testing-without-a-provider).
|
|
103
103
|
|
|
104
104
|
- `decisions` holds the `ChosenEvent` to apply per decision, keyed by decision src, usually `agent.decide`.
|
|
105
105
|
- `text` holds output values for text requests, keyed by request src.
|
|
@@ -171,13 +171,14 @@ settled?.resolvedRequest; // { kind: 'text', src: 'parse', id: 'parse', outcome:
|
|
|
171
171
|
|
|
172
172
|
## Branch exploration
|
|
173
173
|
|
|
174
|
-
`explorePaths(machine, { input, maxDepth?, maxPaths?, maxNodes?, budget?, outputs?, errors?, payloads?, dedupeBy?, interleave?, children?, timers?, usage? })` enumerates decision and external-event branches without a model, and reports coverage.
|
|
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).
|
|
179
180
|
- `outputs` is a map of output lists, keyed by src: a text request's src or any other invoked actor's src. A one-element list is a canned output, reused every time that src is reached. A text request resolves with it as its `result`. A longer list forks one branch per output. See [Payloads and invoke outputs](#payloads-and-invoke-outputs).
|
|
180
|
-
- A src with one canned output resolves without a fork, so it does not appear in the path.
|
|
181
|
+
- A src with one canned output resolves without a fork, so it does not appear in the path. `steps: true` records it. See [Steps](#steps).
|
|
181
182
|
- Each `done` terminal carries the machine's `output`, so one report lists every output the search reached.
|
|
182
183
|
- A src with no `outputs` entry halts that branch with a `needs-output` terminal instead of throwing. The terminal's `missingSrc` names it.
|
|
183
184
|
- `errors` is a map of canned failures per src. A src listed there forks an extra branch where that invoke is rejected, so states behind an `onError` are explored. A decision keys on its src, usually `agent.decide`, or on its invoke id; its success branch stays the per-candidate-event fork, so the failure is explored in addition to the candidates. The failure and the candidates are sibling branches: each spends one level of `maxDepth`.
|
|
@@ -219,6 +220,29 @@ const report = await explorePaths(machine, {
|
|
|
219
220
|
// report.terminals → one path per branch: the parsed state and the onError state
|
|
220
221
|
```
|
|
221
222
|
|
|
223
|
+
### Steps
|
|
224
|
+
|
|
225
|
+
`path` lists branch points only. `steps: true` adds `steps` to each terminal: every macrostep from the start, as an `ExploreStep`.
|
|
226
|
+
|
|
227
|
+
- `event`: the event the step processed. A host event, a fork, a canned output settling (`xstate.done.actor` or `xstate.error.actor`), or `xstate.init` for the start.
|
|
228
|
+
- `state`: the state value after the step.
|
|
229
|
+
- `started`: srcs of the invokes and spawned actors that started in the step. An actor restarted under the same id counts again.
|
|
230
|
+
- `settled`: srcs of the actors that finished, done or error, in the step.
|
|
231
|
+
|
|
232
|
+
```ts no-check
|
|
233
|
+
const report = await explorePaths(loopMachine, {
|
|
234
|
+
outputs: { turn: [{ kind: "continue" }] },
|
|
235
|
+
steps: true,
|
|
236
|
+
});
|
|
237
|
+
// report.terminals[0].steps → [
|
|
238
|
+
// { event: { type: "xstate.init" }, state: "running", started: ["turn"], settled: [] },
|
|
239
|
+
// { event: { type: "xstate.done.actor", actorId: "turn", … }, state: "running", started: ["turn"], settled: ["turn"] },
|
|
240
|
+
// …
|
|
241
|
+
// ]
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Steps are off by default: they cost memory for every step of every path. Steps cover the root machine. With `children: "coupled"`, a child's own moves show up through the events and outputs they deliver to the root.
|
|
245
|
+
|
|
222
246
|
### Payloads and invoke outputs
|
|
223
247
|
|
|
224
248
|
By default, events are applied as `{ type }`. A guard that reads the payload, such as `event.amount <= 100`, rejects every such event, so its target is never explored. Supply payloads to explore it.
|
|
@@ -416,6 +440,7 @@ Set `budget.ms` under the test runner's timeout, so a long search fails its asse
|
|
|
416
440
|
|
|
417
441
|
- A state path or state-node ID.
|
|
418
442
|
- A snapshot predicate, `(snapshot) => boolean`, for a property no single state names: a context invariant, a tag, a state plus context.
|
|
443
|
+
- An ordering, `{ after, reach }`, for a rule about order: "no turn starts after STOP". See [Ordering targets](#ordering-targets).
|
|
419
444
|
|
|
420
445
|
```ts no-check
|
|
421
446
|
const violation = await canReach(
|
|
@@ -467,6 +492,28 @@ const failure = await canReach(machine, "failed", {
|
|
|
467
492
|
// failure.reachable → true; failure.witness → [{ type: 'xstate.error.actor', actorId: 'parse' }]
|
|
468
493
|
```
|
|
469
494
|
|
|
495
|
+
### Ordering targets
|
|
496
|
+
|
|
497
|
+
A snapshot predicate sees one snapshot, so it cannot ask what happened earlier on the path. An ordering target can:
|
|
498
|
+
|
|
499
|
+
```ts no-check
|
|
500
|
+
const turnAfterStop = await canReach(
|
|
501
|
+
loopMachine,
|
|
502
|
+
{ after: "STOP", reach: (step) => step.started.includes("turn") },
|
|
503
|
+
{ outputs: { turn: [{ kind: "continue" }] }, interleave: "pending" },
|
|
504
|
+
);
|
|
505
|
+
// turnAfterStop.reachable → false with complete: true: no turn starts after STOP
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
- `after` and `reach` match [steps](#steps). `after` is an event type or a step predicate.
|
|
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.
|
|
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.
|
|
511
|
+
- The witness is the event sequence to the first violation.
|
|
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.
|
|
513
|
+
- `dedupeBy` stays sound: the search adds "`after` has matched" to each key, so a snapshot reached before and after the trigger is explored both ways.
|
|
514
|
+
- Test the rule with a mutant that breaks it (a loop that starts another turn after STOP), as with a loosened guard.
|
|
515
|
+
- Don't match strings over `terminal.path` for an ordering rule: it lists branch points only and names actors by generated id.
|
|
516
|
+
|
|
470
517
|
## CI checks
|
|
471
518
|
|
|
472
519
|
Everything on this page runs without an API key, so a small script is enough for CI or a generation loop.
|
|
@@ -486,7 +533,7 @@ For machines authored as data, validate the config with `validateAgentConfig(con
|
|
|
486
533
|
- [Crash testing](persistence.md#crash-testing): `checkCrashRecovery` kills a run at every log append and in-flight effect, and checks each resume.
|
|
487
534
|
- [Debugging](debugging.md): scripted reproduction and the diagnostic codes in context.
|
|
488
535
|
- [Evals](evals.md): scoring runs on output, trajectory, and budget.
|
|
489
|
-
- [Quickstart](quickstart.md#define-and-run-one-artifact): a plain-function executor for `
|
|
536
|
+
- [Quickstart](quickstart.md#define-and-run-one-artifact): a plain-function executor for `runAgent`.
|
|
490
537
|
- [Machines as data](machines-as-data.md): verifying a machine lowered from a config.
|
|
491
538
|
- [Migrating from a hand-rolled loop](from-a-loop.md): pinning behavior across a refactor.
|
|
492
539
|
- [examples/verification](https://github.com/statelyai/agent/blob/next/examples/verification/index.ts): every API on this page run over one refund-approval machine, with no API key, including `canReach` proving that an over-limit payout without human approval is unreachable.
|
|
@@ -7,7 +7,7 @@ description: Isolate @statelyai/agent behind a workspace package so an app on XS
|
|
|
7
7
|
|
|
8
8
|
<!-- versions from package.json version and peerDependencies.xstate -->
|
|
9
9
|
|
|
10
|
-
`@statelyai/agent` peers on exactly `xstate@6.0.0-beta.
|
|
10
|
+
The current source of `@statelyai/agent` peers on exactly `xstate@6.0.0-beta.2`. The published `2.0.0-alpha.29` release used in this recipe peers on `xstate@6.0.0-alpha.69`; use that matching pair until a beta.2-compatible agent release is published. An app already using XState 4 or 5 for its own machines cannot install both versions into one `node_modules` tree and have each resolve the one it needs. This page isolates the agent in its own workspace package so the app keeps its XState version and never imports XState 6.
|
|
11
11
|
|
|
12
12
|
The same page applies to an app with no XState at all that cannot take a prerelease dependency in its main tree.
|
|
13
13
|
|
|
@@ -34,7 +34,7 @@ Put the agent in a workspace package that owns its own dependencies, and give th
|
|
|
34
34
|
"@statelyai/agent": "2.0.0-alpha.29",
|
|
35
35
|
"@ai-sdk/openai": "^4.0.0",
|
|
36
36
|
"ai": "^7.0.128",
|
|
37
|
-
"xstate": "6.0.0-
|
|
37
|
+
"xstate": "6.0.0-alpha.69",
|
|
38
38
|
"zod": "^4.4.3"
|
|
39
39
|
}
|
|
40
40
|
}
|
|
@@ -48,7 +48,7 @@ One async function in, one JSON-safe object out. Everything XState is inside it.
|
|
|
48
48
|
|
|
49
49
|
```ts no-check
|
|
50
50
|
// packages/agent/src/index.ts
|
|
51
|
-
import {
|
|
51
|
+
import { runAgent } from "@statelyai/agent";
|
|
52
52
|
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
53
53
|
import { models, generationMachine } from "./machine.js";
|
|
54
54
|
|
|
@@ -72,13 +72,11 @@ export async function runGeneration(
|
|
|
72
72
|
input: GenerationInput,
|
|
73
73
|
deps: GenerationDeps,
|
|
74
74
|
): Promise<GenerationOutput> {
|
|
75
|
-
const result = await
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
{ input },
|
|
81
|
-
);
|
|
75
|
+
const result = await runAgent(generationMachine(deps.lookup), {
|
|
76
|
+
executors: createAiSdkExecutors({ models }),
|
|
77
|
+
onTransition: (snapshot) => deps.onProgress?.(String(snapshot.value)),
|
|
78
|
+
input,
|
|
79
|
+
});
|
|
82
80
|
if (result.status !== "done") {
|
|
83
81
|
throw new Error(`Generation did not complete: ${result.status}`);
|
|
84
82
|
}
|
|
@@ -109,9 +107,9 @@ export async function POST(request: Request) {
|
|
|
109
107
|
|
|
110
108
|
## What can cross the boundary
|
|
111
109
|
|
|
112
|
-
Persisted snapshots are JSON. `result.persist()` returns a plain JSON value, and `
|
|
110
|
+
Persisted snapshots are JSON. `result.persist()` returns a plain JSON value, and `runAgent(machine, { snapshot, event })` takes one back, so a paused run can be stored by the app, in its own database, and resumed by a later call into the package. Pair `snapshot` with the `event` that unblocks the idle state: a resume with `snapshot` alone starts the run back at the same wait.
|
|
113
111
|
|
|
114
|
-
<!--
|
|
112
|
+
<!-- runAgent snapshot/event resume from src/run-agent.ts; exercised by src/docs-integration-recipes.test.ts -->
|
|
115
113
|
|
|
116
114
|
```ts no-check
|
|
117
115
|
// Inside the package: the app stores and returns the value, and never reads it.
|
|
@@ -121,12 +119,10 @@ export async function startGeneration(
|
|
|
121
119
|
input: GenerationInput,
|
|
122
120
|
deps: GenerationDeps,
|
|
123
121
|
): Promise<{ snapshot: unknown }> {
|
|
124
|
-
const result = await
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
{ input },
|
|
129
|
-
);
|
|
122
|
+
const result = await runAgent(generationMachine(deps.lookup), {
|
|
123
|
+
executors: createAiSdkExecutors({ models }),
|
|
124
|
+
input,
|
|
125
|
+
});
|
|
130
126
|
return { snapshot: result.status === "idle" ? result.persist() : null };
|
|
131
127
|
}
|
|
132
128
|
|
|
@@ -135,16 +131,11 @@ export async function resumeGeneration(
|
|
|
135
131
|
answer: string,
|
|
136
132
|
deps: GenerationDeps,
|
|
137
133
|
): Promise<GenerationOutput> {
|
|
138
|
-
const result = await
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
}
|
|
142
|
-
|
|
143
|
-
// Opaque to the app, typed again here at the package boundary.
|
|
144
|
-
snapshot: snapshot as Snapshot<unknown>,
|
|
145
|
-
event: { type: "ANSWER", answer },
|
|
146
|
-
},
|
|
147
|
-
);
|
|
134
|
+
const result = await runAgent(generationMachine(deps.lookup), {
|
|
135
|
+
executors: createAiSdkExecutors({ models }), // Opaque to the app, typed again here at the package boundary.
|
|
136
|
+
snapshot: snapshot as Snapshot<unknown>,
|
|
137
|
+
event: { type: "ANSWER", answer },
|
|
138
|
+
});
|
|
148
139
|
if (result.status !== "done") {
|
|
149
140
|
throw new Error(`Generation did not complete: ${result.status}`);
|
|
150
141
|
}
|
package/llms.txt
CHANGED
|
@@ -21,7 +21,7 @@ Not v5: transitions are plain functions returning `{ target, context }` (no `ass
|
|
|
21
21
|
- [Tools](docs/tools.md): Define tools, attach them to a text request, and let the host run the tool loop while the machine stays in one state.
|
|
22
22
|
- [Judgments with the AI SDK](docs/judgments.md): Ask classification, grading, relevance, and yes/no questions with the AI SDK's experimental_decide and Jev, and branch on the typed answers in a machine.
|
|
23
23
|
- [Messages](docs/messages.md): Build and store conversation history as a parts-based message model that mirrors the AI SDK without depending on it.
|
|
24
|
-
- [Preset machines](docs/machines-presets.md):
|
|
24
|
+
- [Preset machines](docs/machines-presets.md): `createApprovalBatchMachine`, which gates one model turn's tool calls on approval.
|
|
25
25
|
- [Choosing a run mode](docs/choosing-a-run-mode.md): Three ways to execute the same agent machine, what each one owns, and which to reach for.
|
|
26
26
|
- [Hosts and executors](docs/hosts.md): Give an agent machine the executor functions that call a model, and choose between the shipped AI SDK adapter or your own.
|
|
27
27
|
- [Use in any stack](docs/any-stack.md): One agent machine runs unchanged in a local script, an HTTP route, or an edge runtime. Only the executors are host-specific.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statelyai/agent",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
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",
|
|
@@ -21,7 +21,6 @@
|
|
|
21
21
|
"files": [
|
|
22
22
|
"dist",
|
|
23
23
|
"schemas",
|
|
24
|
-
"skills",
|
|
25
24
|
"docs",
|
|
26
25
|
"!docs/snippet-globals.ts",
|
|
27
26
|
"llms.txt",
|
|
@@ -36,6 +35,9 @@
|
|
|
36
35
|
"ai-sdk": [
|
|
37
36
|
"./dist/ai-sdk.d.mts"
|
|
38
37
|
],
|
|
38
|
+
"evals": [
|
|
39
|
+
"./dist/evals.d.mts"
|
|
40
|
+
],
|
|
39
41
|
"log": [
|
|
40
42
|
"./dist/log.d.mts"
|
|
41
43
|
],
|
|
@@ -48,6 +50,9 @@
|
|
|
48
50
|
"otel": [
|
|
49
51
|
"./dist/otel.d.mts"
|
|
50
52
|
],
|
|
53
|
+
"policy": [
|
|
54
|
+
"./dist/policy.d.mts"
|
|
55
|
+
],
|
|
51
56
|
"tanstack-ai": [
|
|
52
57
|
"./dist/tanstack-ai.d.mts"
|
|
53
58
|
],
|
|
@@ -80,6 +85,16 @@
|
|
|
80
85
|
"default": "./dist/ai-sdk.cjs"
|
|
81
86
|
}
|
|
82
87
|
},
|
|
88
|
+
"./evals": {
|
|
89
|
+
"import": {
|
|
90
|
+
"types": "./dist/evals.d.mts",
|
|
91
|
+
"default": "./dist/evals.mjs"
|
|
92
|
+
},
|
|
93
|
+
"require": {
|
|
94
|
+
"types": "./dist/evals.d.cts",
|
|
95
|
+
"default": "./dist/evals.cjs"
|
|
96
|
+
}
|
|
97
|
+
},
|
|
83
98
|
"./log": {
|
|
84
99
|
"import": {
|
|
85
100
|
"types": "./dist/log.d.mts",
|
|
@@ -120,6 +135,16 @@
|
|
|
120
135
|
"default": "./dist/otel.cjs"
|
|
121
136
|
}
|
|
122
137
|
},
|
|
138
|
+
"./policy": {
|
|
139
|
+
"import": {
|
|
140
|
+
"types": "./dist/policy.d.mts",
|
|
141
|
+
"default": "./dist/policy.mjs"
|
|
142
|
+
},
|
|
143
|
+
"require": {
|
|
144
|
+
"types": "./dist/policy.d.cts",
|
|
145
|
+
"default": "./dist/policy.cjs"
|
|
146
|
+
}
|
|
147
|
+
},
|
|
123
148
|
"./tanstack-ai": {
|
|
124
149
|
"import": {
|
|
125
150
|
"types": "./dist/tanstack-ai.d.mts",
|
|
@@ -168,7 +193,7 @@
|
|
|
168
193
|
"@opentelemetry/api": "^1.9.1",
|
|
169
194
|
"@opentelemetry/context-async-hooks": "^2.12.0",
|
|
170
195
|
"@opentelemetry/sdk-trace-base": "^2.12.0",
|
|
171
|
-
"@statelyai/sdk": "0.
|
|
196
|
+
"@statelyai/sdk": "0.47.0",
|
|
172
197
|
"@tanstack/ai": "^0.66.0",
|
|
173
198
|
"@types/node": "^22.20.5",
|
|
174
199
|
"@types/react": "^19.3.0",
|
|
@@ -187,7 +212,7 @@
|
|
|
187
212
|
"twoslash": "^0.3.9",
|
|
188
213
|
"typescript": "^7.0.2",
|
|
189
214
|
"vitest": "^5.0.3",
|
|
190
|
-
"xstate": "6.0.0-beta.
|
|
215
|
+
"xstate": "6.0.0-beta.2",
|
|
191
216
|
"zod": "^4.6.5"
|
|
192
217
|
},
|
|
193
218
|
"peerDependencies": {
|
|
@@ -196,7 +221,7 @@
|
|
|
196
221
|
"ai": "*",
|
|
197
222
|
"ajv": "*",
|
|
198
223
|
"openai": "*",
|
|
199
|
-
"xstate": "6.0.0-beta.
|
|
224
|
+
"xstate": "6.0.0-beta.2"
|
|
200
225
|
},
|
|
201
226
|
"peerDependenciesMeta": {
|
|
202
227
|
"@opentelemetry/api": {
|
|
@@ -227,7 +252,7 @@
|
|
|
227
252
|
"proto:prefabs": "tsx .scratch/prefabs/demo.ts",
|
|
228
253
|
"docs:check": "tsx scripts/check-docs-snippets.ts",
|
|
229
254
|
"typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples && pnpm run typecheck:example-packages",
|
|
230
|
-
"typecheck:src": "tsc --noEmit",
|
|
255
|
+
"typecheck:src": "tsc --noEmit && tsc -p tsconfig.exact-optional.json",
|
|
231
256
|
"typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",
|
|
232
257
|
"typecheck:example-packages": "pnpm run build && tsc -p examples/next-host --noEmit && tsc -p examples/tanstack-ai-stream --noEmit && tsc -p examples/cloudflare-agent-host --noEmit && tsc -p examples/cloudflare-workers-ai-host --noEmit && tsc -p demo --noEmit",
|
|
233
258
|
"test:cloudflare": "pnpm --filter @statelyai/example-cloudflare-agent-host test && pnpm --filter @statelyai/example-cloudflare-workers-ai-host test",
|
package/readme.md
CHANGED
|
@@ -8,7 +8,7 @@ What you get:
|
|
|
8
8
|
|
|
9
9
|
- **Proofs with no model.** Put the rule that must never break behind a sentinel state, then `canReach(machine, "refundedOverLimit", options)` returns `reachable: false` and `complete: true` with no API key. See [Testing and verification](https://github.com/statelyai/agent/blob/next/docs/verify.md).
|
|
10
10
|
- **Resume and replay from the event log.** A paused run resumes with `runAgent(machine, { snapshot, event })`, and `replay(machine, result.events)` rebuilds any point of a run with no model calls. See [The event log](https://github.com/statelyai/agent/blob/next/docs/event-log.md).
|
|
11
|
-
- **Checked ports.** `
|
|
11
|
+
- **Checked ports.** `checkParity` records the old code's side effects, replays them against the machine, and reports every scenario where the two differ. `compareRuns` labels outcome-level differences `same`, `intended`, or `regression`. See [Parity with the code you replace](https://github.com/statelyai/agent/blob/next/docs/evals.md#parity-with-the-code-you-replace).
|
|
12
12
|
|
|
13
13
|
The machine is also a diagram: stream any run to the Stately inspector with `runAgent`'s `inspect` option. See [Inspect a run](https://github.com/statelyai/agent/blob/next/docs/observability.md#inspect-a-run).
|
|
14
14
|
|
|
@@ -32,8 +32,8 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
|
|
|
32
32
|
### Brownfield: an existing agent
|
|
33
33
|
|
|
34
34
|
- **Wrap an existing workflow, then carve it.** `wrapWorkflow` runs an async workflow unchanged inside a machine. In minutes and with no rewrite, you get inspection, traces, the event log, and a recorded baseline. Reliability proofs such as `canReach` arrive per phase, as each phase moves into states, with `checkParity` against the original after each. See [Strangler-fig retrofit](https://github.com/statelyai/agent/blob/next/docs/strangler-fig.md).
|
|
35
|
-
- **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md). A coding agent does it with the
|
|
36
|
-
- **Let an agent improve its own logic (experimental).** Keep the rules in a fixed TypeScript environment and let a model rewrite the JSON policy inside it, gated by `verifyAgentConfig` and promoted only when held-out scenarios improve. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md) and the [`improve-machine` skill](https://github.com/statelyai/
|
|
35
|
+
- **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md). A coding agent does it with the `loop-to-machine` skill (see [Agent skills](#agent-skills)): "Use the loop-to-machine skill to convert `src/support-agent.ts` to a machine."
|
|
36
|
+
- **Let an agent improve its own logic (experimental).** Keep the rules in a fixed TypeScript environment and let a model rewrite the JSON policy inside it, gated by `verifyAgentConfig` and promoted only when held-out scenarios improve. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md) and the [`improve-machine` skill](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md).
|
|
37
37
|
|
|
38
38
|
## Environment and policy
|
|
39
39
|
|
|
@@ -43,13 +43,13 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
|
|
|
43
43
|
|
|
44
44
|
## Install
|
|
45
45
|
|
|
46
|
-
<!--
|
|
46
|
+
<!-- Match the published agent release with its published XState peer. -->
|
|
47
47
|
|
|
48
48
|
```sh
|
|
49
|
-
pnpm add @statelyai/agent@alpha xstate@6.0.0-beta.0 zod
|
|
49
|
+
pnpm add @statelyai/agent@2.0.0-alpha.38 xstate@6.0.0-beta.0 zod
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
XState is pinned while its experimental durable restoration API evolves.
|
|
52
|
+
This is the published pair as of November 11, 2026. This source checkout requires XState `6.0.0-beta.2`; use that version when building the checkout. XState is pinned while its experimental durable restoration API evolves.
|
|
53
53
|
|
|
54
54
|
For the optional Vercel AI SDK executor:
|
|
55
55
|
|
|
@@ -75,7 +75,7 @@ Upgrading from an earlier alpha: see [Upgrading between alphas](https://github.c
|
|
|
75
75
|
|
|
76
76
|
Requirements:
|
|
77
77
|
|
|
78
|
-
- Node 22 or newer
|
|
78
|
+
- Node 22 or newer. This source checkout requires XState exactly `6.0.0-beta.2`; the published release above requires `6.0.0-beta.0`.
|
|
79
79
|
- TypeScript 5.4 or newer. Older versions accept the code, but callback parameters in `createMachine` silently become `any`.
|
|
80
80
|
- A [Standard Schema](https://standardschema.dev) library: zod 4, zod 3.24 or newer, Valibot, or ArkType. `setupAgent` throws `invalid-schema` for zod 3.23 and earlier.
|
|
81
81
|
- The package is ESM-first. CommonJS builds are published too, so `require()` works. Subpath imports (`@statelyai/agent/testing`) resolve under every `moduleResolution`, including `node`.
|
|
@@ -84,30 +84,38 @@ Requirements:
|
|
|
84
84
|
|
|
85
85
|
An app that already uses XState 4 or 5 keeps it: put the agent in its own workspace package. See [Use in an XState 4 or 5 app](https://github.com/statelyai/agent/blob/next/docs/xstate-4-and-5-apps.md). If both versions land in one `node_modules`, the package fails with errors that do not mention a version:
|
|
86
86
|
|
|
87
|
-
| Error
|
|
88
|
-
|
|
|
89
|
-
| `createAsyncLogic is not a function`
|
|
90
|
-
| `Cannot find module '…/node_modules/xstate/durable'`
|
|
91
|
-
|
|
|
87
|
+
| Error | Cause |
|
|
88
|
+
| ---------------------------------------------------- | ------------------------------------------- |
|
|
89
|
+
| `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
|
|
90
|
+
| `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
|
|
91
|
+
| An unmet or incorrect XState peer dependency warning | The install's only warning of the two above |
|
|
92
92
|
|
|
93
93
|
## Agent skills
|
|
94
94
|
|
|
95
|
-
The
|
|
95
|
+
The agent skills live in [statelyai/skills](https://github.com/statelyai/skills), in the `stately-agent` plugin. The package ships its docs in `node_modules/@statelyai/agent/docs/` with an index in `llms.txt`.
|
|
96
|
+
|
|
97
|
+
In Claude Code:
|
|
98
|
+
|
|
99
|
+
```text
|
|
100
|
+
/plugin marketplace add statelyai/skills
|
|
101
|
+
/plugin install stately-agent@stately
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
For other coding agents:
|
|
96
105
|
|
|
97
106
|
```sh
|
|
98
|
-
|
|
99
|
-
cp -R node_modules/@statelyai/agent/skills/* .claude/skills/
|
|
107
|
+
npx skills add statelyai/skills
|
|
100
108
|
```
|
|
101
109
|
|
|
102
|
-
| Skill
|
|
103
|
-
|
|
|
104
|
-
| [`graph-engineering`](https://github.com/statelyai/
|
|
105
|
-
| [`loop-to-machine`](https://github.com/statelyai/
|
|
106
|
-
| [`build-machine`](https://github.com/statelyai/
|
|
107
|
-
| [`generate-machine`](https://github.com/statelyai/
|
|
108
|
-
| [`add-traces`](https://github.com/statelyai/
|
|
109
|
-
| [`add-evals`](https://github.com/statelyai/
|
|
110
|
-
| [`improve-machine`](https://github.com/statelyai/
|
|
110
|
+
| Skill | What it does |
|
|
111
|
+
| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
112
|
+
| [`graph-engineering`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill |
|
|
113
|
+
| [`loop-to-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/loop-to-machine/SKILL.md) | Converts existing agent code into a machine and checks parity with `compareRuns` |
|
|
114
|
+
| [`build-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/build-machine/SKILL.md) | Builds a TypeScript machine from a spec and proves its invariants |
|
|
115
|
+
| [`generate-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/generate-machine/SKILL.md) | Authors a JSON policy machine from scratch and runs `verifyAgentConfig` |
|
|
116
|
+
| [`add-traces`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
|
|
117
|
+
| [`add-evals`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-evals/SKILL.md) | Writes evals per state, at the cheapest level that catches the failure |
|
|
118
|
+
| [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md) | Experimental. Improves a policy from traces; a person reviews the pull request |
|
|
111
119
|
|
|
112
120
|
## Quick start
|
|
113
121
|
|
|
@@ -1,43 +0,0 @@
|
|
|
1
|
-
import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.cjs";
|
|
2
|
-
import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
|
|
3
|
-
//#region src/machines/internal.d.ts
|
|
4
|
-
/**
|
|
5
|
-
* The machine type a preset factory returns: its context, event union, input
|
|
6
|
-
* and output are all concrete, so callers get typed run input and
|
|
7
|
-
* output instead of `AnyStateMachine`. The remaining slots (children, state
|
|
8
|
-
* value/tags/config, source maps) are left permissive — a preset builds its
|
|
9
|
-
* states dynamically, so there is no literal state schema to infer.
|
|
10
|
-
*
|
|
11
|
-
* @internal
|
|
12
|
-
*/
|
|
13
|
-
type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
|
|
14
|
-
/** One delegated unit of work, lowered to an inline text request. */
|
|
15
|
-
interface PresetRequestEntry {
|
|
16
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
17
|
-
description?: string;
|
|
18
|
-
/** System prompt for this entry's model call. */
|
|
19
|
-
instructions?: string;
|
|
20
|
-
/** Model ref (or `models` alias). Falls back to the factory's `model`. */
|
|
21
|
-
model?: string;
|
|
22
|
-
/** Structured output schema. Omitted means plain text. */
|
|
23
|
-
outputSchema?: StandardSchemaV1;
|
|
24
|
-
/** Tools the host runs inside this one request. */
|
|
25
|
-
tools?: AgentTools;
|
|
26
|
-
/** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
|
|
27
|
-
maxSteps?: number;
|
|
28
|
-
}
|
|
29
|
-
/** One delegated unit of work, lowered to an invoked child machine. */
|
|
30
|
-
interface PresetMachineEntry {
|
|
31
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
32
|
-
description?: string;
|
|
33
|
-
/** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
|
|
34
|
-
machine: AnyStateMachine;
|
|
35
|
-
/** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
|
|
36
|
-
input?: (args: {
|
|
37
|
-
prompt: string;
|
|
38
|
-
}) => unknown;
|
|
39
|
-
}
|
|
40
|
-
/** A route/branch/worker/agent entry: an inline request, or a child machine. */
|
|
41
|
-
type PresetEntry = PresetRequestEntry | PresetMachineEntry;
|
|
42
|
-
//#endregion
|
|
43
|
-
export { PresetRequestEntry as i, PresetMachine as n, PresetMachineEntry as r, PresetEntry as t };
|
|
@@ -1,43 +0,0 @@
|
|
|
1
|
-
import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.mjs";
|
|
2
|
-
import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
|
|
3
|
-
//#region src/machines/internal.d.ts
|
|
4
|
-
/**
|
|
5
|
-
* The machine type a preset factory returns: its context, event union, input
|
|
6
|
-
* and output are all concrete, so callers get typed run input and
|
|
7
|
-
* output instead of `AnyStateMachine`. The remaining slots (children, state
|
|
8
|
-
* value/tags/config, source maps) are left permissive — a preset builds its
|
|
9
|
-
* states dynamically, so there is no literal state schema to infer.
|
|
10
|
-
*
|
|
11
|
-
* @internal
|
|
12
|
-
*/
|
|
13
|
-
type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
|
|
14
|
-
/** One delegated unit of work, lowered to an inline text request. */
|
|
15
|
-
interface PresetRequestEntry {
|
|
16
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
17
|
-
description?: string;
|
|
18
|
-
/** System prompt for this entry's model call. */
|
|
19
|
-
instructions?: string;
|
|
20
|
-
/** Model ref (or `models` alias). Falls back to the factory's `model`. */
|
|
21
|
-
model?: string;
|
|
22
|
-
/** Structured output schema. Omitted means plain text. */
|
|
23
|
-
outputSchema?: StandardSchemaV1;
|
|
24
|
-
/** Tools the host runs inside this one request. */
|
|
25
|
-
tools?: AgentTools;
|
|
26
|
-
/** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
|
|
27
|
-
maxSteps?: number;
|
|
28
|
-
}
|
|
29
|
-
/** One delegated unit of work, lowered to an invoked child machine. */
|
|
30
|
-
interface PresetMachineEntry {
|
|
31
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
32
|
-
description?: string;
|
|
33
|
-
/** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
|
|
34
|
-
machine: AnyStateMachine;
|
|
35
|
-
/** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
|
|
36
|
-
input?: (args: {
|
|
37
|
-
prompt: string;
|
|
38
|
-
}) => unknown;
|
|
39
|
-
}
|
|
40
|
-
/** A route/branch/worker/agent entry: an inline request, or a child machine. */
|
|
41
|
-
type PresetEntry = PresetRequestEntry | PresetMachineEntry;
|
|
42
|
-
//#endregion
|
|
43
|
-
export { PresetRequestEntry as i, PresetMachine as n, PresetMachineEntry as r, PresetEntry as t };
|