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

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 (135) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
  3. package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
  4. package/dist/ai-sdk.cjs +4 -4
  5. package/dist/ai-sdk.d.cts +2 -3
  6. package/dist/ai-sdk.d.mts +2 -3
  7. package/dist/ai-sdk.mjs +4 -4
  8. package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
  9. package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
  10. package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
  11. package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
  12. package/dist/effects-B9IvUPVh.mjs +23 -0
  13. package/dist/effects-DrWcUGgc.cjs +34 -0
  14. package/dist/evals.cjs +810 -0
  15. package/dist/evals.d.cts +595 -0
  16. package/dist/evals.d.mts +595 -0
  17. package/dist/evals.mjs +801 -0
  18. package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
  19. package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
  20. package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
  21. package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
  22. package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
  23. package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
  24. package/dist/index.cjs +131 -93
  25. package/dist/index.d.cts +73 -134
  26. package/dist/index.d.mts +73 -134
  27. package/dist/index.mjs +112 -70
  28. package/dist/internal-BzlpzSux.d.cts +14 -0
  29. package/dist/internal-BzlpzSux.d.mts +14 -0
  30. package/dist/log.cjs +2 -3
  31. package/dist/log.d.cts +2 -2
  32. package/dist/log.d.mts +2 -2
  33. package/dist/log.mjs +3 -3
  34. package/dist/machines.cjs +1 -719
  35. package/dist/machines.d.cts +2 -424
  36. package/dist/machines.d.mts +2 -424
  37. package/dist/machines.mjs +2 -709
  38. package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
  39. package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
  40. package/dist/openai.cjs +3 -3
  41. package/dist/openai.d.cts +2 -3
  42. package/dist/openai.d.mts +2 -3
  43. package/dist/openai.mjs +3 -3
  44. package/dist/otel.d.cts +1 -1
  45. package/dist/otel.d.mts +1 -1
  46. package/dist/policy.cjs +77 -0
  47. package/dist/policy.d.cts +143 -0
  48. package/dist/policy.d.mts +143 -0
  49. package/dist/policy.mjs +75 -0
  50. package/dist/{effects-BT_cSY0j.mjs → run-agent-BE7DOWD6.mjs} +150 -184
  51. package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-DHlq87G7.d.mts} +18 -34
  52. package/dist/{effects-DDseYtJk.cjs → run-agent-De3xVFGw.cjs} +149 -201
  53. package/dist/{run-agent-30mH2moE.d.cts → run-agent-Dq0oSFRm.d.cts} +18 -34
  54. package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
  55. package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
  56. package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
  57. package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
  58. package/dist/tanstack-ai.cjs +4 -4
  59. package/dist/tanstack-ai.d.cts +2 -3
  60. package/dist/tanstack-ai.d.mts +2 -3
  61. package/dist/tanstack-ai.mjs +4 -4
  62. package/dist/testing.cjs +122 -996
  63. package/dist/testing.d.cts +36 -695
  64. package/dist/testing.d.mts +36 -695
  65. package/dist/testing.mjs +112 -977
  66. package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
  67. package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
  68. package/dist/trajectory-BFjXaooB.d.cts +96 -0
  69. package/dist/trajectory-BFjXaooB.d.mts +96 -0
  70. package/dist/trajectory-BUXj_1Ue.mjs +152 -0
  71. package/dist/trajectory-CoZSv4wF.cjs +157 -0
  72. package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
  73. package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
  74. package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
  75. package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
  76. package/dist/validate.cjs +4 -4
  77. package/dist/validate.d.cts +2 -2
  78. package/dist/validate.d.mts +2 -2
  79. package/dist/validate.mjs +4 -4
  80. package/dist/{verify-DJHfEfm6.d.cts → verify-BM0sGmsf.d.cts} +42 -6
  81. package/dist/{verify-ChyX6jq0.mjs → verify-CWlg3j7B.mjs} +153 -45
  82. package/dist/{verify-CwlombbC.cjs → verify-Dek6gHCS.cjs} +153 -45
  83. package/dist/{verify-i9Hiwc5g.d.mts → verify-H3Pr2gNw.d.mts} +42 -6
  84. package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
  85. package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
  86. package/docs/advanced.md +5 -5
  87. package/docs/choosing-a-run-mode.md +7 -7
  88. package/docs/debugging.md +6 -8
  89. package/docs/decisions.md +5 -4
  90. package/docs/environment-and-policy.md +1 -1
  91. package/docs/evals.md +57 -43
  92. package/docs/event-log.md +13 -15
  93. package/docs/from-a-loop.md +3 -3
  94. package/docs/generate-machines.md +4 -4
  95. package/docs/hosts.md +20 -27
  96. package/docs/human-in-the-loop.md +5 -8
  97. package/docs/index.md +4 -4
  98. package/docs/judgments.md +5 -7
  99. package/docs/langgraph-comparison.md +6 -6
  100. package/docs/machines-as-data.md +7 -12
  101. package/docs/machines-presets.md +17 -120
  102. package/docs/machines.md +13 -13
  103. package/docs/models-and-providers.md +19 -25
  104. package/docs/multi-agent.md +1 -1
  105. package/docs/observability.md +6 -8
  106. package/docs/persistence.md +10 -20
  107. package/docs/quickstart.md +3 -3
  108. package/docs/statechart-policy-examples.md +1 -1
  109. package/docs/steps.md +5 -6
  110. package/docs/strangler-fig.md +72 -7
  111. package/docs/text-requests.md +10 -12
  112. package/docs/thinking-in-state-machines.md +8 -8
  113. package/docs/tools.md +10 -12
  114. package/docs/upgrading.md +1 -1
  115. package/docs/usage-and-budgets.md +51 -56
  116. package/docs/validate-and-repair.md +9 -14
  117. package/docs/verify.md +53 -7
  118. package/docs/xstate-4-and-5-apps.md +19 -28
  119. package/llms.txt +1 -1
  120. package/package.json +31 -6
  121. package/readme.md +32 -24
  122. package/dist/internal-C3Lqu538.d.cts +0 -43
  123. package/dist/internal-DUcdhk-i.d.mts +0 -43
  124. package/dist/types-DQUOOaZO.d.cts +0 -238
  125. package/dist/types-DQUOOaZO.d.mts +0 -238
  126. package/skills/add-evals/SKILL.md +0 -152
  127. package/skills/add-traces/SKILL.md +0 -152
  128. package/skills/build-machine/SKILL.md +0 -84
  129. package/skills/generate-machine/SKILL.md +0 -335
  130. package/skills/graph-engineering/SKILL.md +0 -43
  131. package/skills/improve-machine/SKILL.md +0 -261
  132. package/skills/improve-machine/reference.md +0 -101
  133. package/skills/loop-to-machine/SKILL.md +0 -205
  134. package/skills/loop-to-machine/policy.md +0 -154
  135. package/skills/loop-to-machine/reference.md +0 -260
@@ -1,427 +1,5 @@
1
- import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.mjs";
2
- import { i as PresetRequestEntry, n as PresetMachine, r as PresetMachineEntry, t as PresetEntry } from "./internal-DUcdhk-i.mjs";
1
+ import { t as PresetMachine } from "./internal-BzlpzSux.mjs";
3
2
  import { ActorLogic } from "xstate";
4
- //#region src/machines/tool-loop.d.ts
5
- /** Config for {@link createToolLoopMachine}. */
6
- interface CreateToolLoopMachineConfig {
7
- /** Model ref, or an alias from the host's `models` registry. */
8
- model: string;
9
- /** System prompt. */
10
- instructions?: string;
11
- /** Tools the host runs inside the one request. */
12
- tools?: AgentTools;
13
- /** Structured output schema. Omitted means the output is plain text. */
14
- outputSchema?: StandardSchemaV1;
15
- /**
16
- * Bounds the host-side tool loop — lowered to the request's typed
17
- * {@link AgentTextRequest.maxSteps}. It bounds MODEL STEPS inside one
18
- * request, not machine turns, hence the name.
19
- */
20
- maxSteps?: number;
21
- }
22
- /** Context of a {@link createToolLoopMachine} machine. */
23
- type ToolLoopContext = {
24
- prompt: string;
25
- result: unknown;
26
- };
27
- /** Machine input of a {@link createToolLoopMachine} machine. */
28
- type ToolLoopInput = {
29
- prompt: string;
30
- };
31
- /** Machine output of a {@link createToolLoopMachine} machine. */
32
- type ToolLoopOutput = {
33
- result: unknown;
34
- };
35
- /** The machine {@link createToolLoopMachine} returns. */
36
- type ToolLoopMachine = PresetMachine<ToolLoopContext, ToolLoopInput, ToolLoopOutput>;
37
- /**
38
- * The single-state tool loop: one text request carries the `tools`, and the
39
- * host runs the tool loop inside it (`maxSteps` bounds it). Selecting and
40
- * executing tools is the model + host's business, not machine states.
41
- *
42
- * States: `answering` → `done`.
43
- *
44
- * ```ts
45
- * const machine = createToolLoopMachine({
46
- * model: "quick",
47
- * instructions: "Answer using the tools.",
48
- * tools: { calculate },
49
- * maxSteps: 5,
50
- * });
51
- *
52
- * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), {
53
- * input: { prompt: "What is 42 * 17?" },
54
- * });
55
- * // Snapshots and log entries carry machine.version ("1") automatically.
56
- * ```
57
- */
58
- export declare function createToolLoopMachine(config: CreateToolLoopMachineConfig): ToolLoopMachine;
59
- //#endregion
60
- //#region src/machines/sequential.d.ts
61
- /** Arguments a {@link SequentialStep}'s `prompt` receives. */
62
- interface SequentialPromptArgs {
63
- /** The machine's `input.prompt`. */
64
- prompt: string;
65
- /** Every completed step's output, keyed by step name. */
66
- results: Record<string, unknown>;
67
- /** The previous step's output (`null` for the first step). */
68
- previous: unknown;
69
- }
70
- /** One step of a {@link createSequentialMachine} chain. */
71
- interface SequentialStep {
72
- /** Step name. Becomes the state name and the `results` key. */
73
- name: string;
74
- /** System prompt for this step. */
75
- instructions?: string;
76
- /** Builds this step's prompt. Defaults to the previous step's output (the machine's `prompt` for the first step). */
77
- prompt?: (args: SequentialPromptArgs) => string;
78
- /** Structured output schema for this step. */
79
- outputSchema?: StandardSchemaV1;
80
- /** Model ref for this step. Falls back to the factory's `model`. */
81
- model?: string;
82
- /** Tools the host runs inside this step's request. */
83
- tools?: AgentTools;
84
- /** Bounds this step's host-side tool loop (the request's typed `maxSteps`). */
85
- maxSteps?: number;
86
- }
87
- /** Config for {@link createSequentialMachine}. */
88
- interface CreateSequentialMachineConfig {
89
- /** Default model ref for every step. */
90
- model: string;
91
- /** The chain, run in array order. */
92
- steps: readonly SequentialStep[];
93
- }
94
- /** Context of a {@link createSequentialMachine} machine. */
95
- type SequentialContext = {
96
- prompt: string;
97
- results: Record<string, unknown>;
98
- previous: unknown;
99
- };
100
- /** Machine input of a {@link createSequentialMachine} machine. */
101
- type SequentialInput = {
102
- prompt: string;
103
- };
104
- /** Machine output of a {@link createSequentialMachine} machine. */
105
- type SequentialOutput = {
106
- results: Record<string, unknown>;
107
- output: unknown;
108
- };
109
- /** The machine {@link createSequentialMachine} returns. */
110
- type SequentialMachine = PresetMachine<SequentialContext, SequentialInput, SequentialOutput>;
111
- /**
112
- * A prompt chain: each step is one state, and each step's output feeds the
113
- * next. The default prompt for a step is the previous step's output, so a
114
- * chain needs no `prompt` functions at all.
115
- *
116
- * States: one per step, in order → `done`.
117
- *
118
- * ```ts
119
- * const machine = createSequentialMachine({
120
- * model: "quick",
121
- * steps: [
122
- * { name: "outline", instructions: "Outline the post." },
123
- * { name: "draft", instructions: "Write the post from the outline." },
124
- * { name: "polish", instructions: "Tighten the prose." },
125
- * ],
126
- * });
127
- * ```
128
- */
129
- export declare function createSequentialMachine(config: CreateSequentialMachineConfig): SequentialMachine;
130
- //#endregion
131
- //#region src/machines/router.d.ts
132
- /** Config for {@link createRouterMachine}. */
133
- interface CreateRouterMachineConfig<TRoutes extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
134
- /** Model ref for the routing decision, and the default for request routes. */
135
- model: string;
136
- /** System prompt for the routing decision. */
137
- instructions?: string;
138
- /** The legal destinations, keyed by route name. Each is an inline request or a child machine. */
139
- routes: TRoutes;
140
- /** Route taken when the routing decision errors. Without it, a failed decision ends the run. */
141
- fallback?: keyof TRoutes & string;
142
- }
143
- /** Context of a {@link createRouterMachine} machine. */
144
- type RouterContext<TRoute extends string = string> = {
145
- prompt: string;
146
- route: TRoute | null;
147
- result: unknown;
148
- };
149
- /** Machine input of a {@link createRouterMachine} machine. */
150
- type RouterInput = {
151
- prompt: string;
152
- };
153
- /** Machine output of a {@link createRouterMachine} machine. */
154
- type RouterOutput<TRoute extends string = string> = {
155
- route: TRoute | null;
156
- result: unknown;
157
- };
158
- /** The events a {@link createRouterMachine} machine accepts: one per declared route. */
159
- type RouterEvent<TRoute extends string = string> = {
160
- type: `ROUTE_${TRoute}`;
161
- };
162
- /** The machine {@link createRouterMachine} returns. */
163
- type RouterMachine<TRoute extends string = string> = PresetMachine<RouterContext<TRoute>, RouterInput, RouterOutput<TRoute>, RouterEvent<TRoute>>;
164
- /** The event a route decision chooses: `ROUTE_<name>`. */
165
- export declare function routeEventType(route: string): string;
166
- /**
167
- * One `agent.decide` picks exactly one declared route, then the machine runs
168
- * it. Only the declared routes have events and transitions, so a model naming
169
- * anything else is rejected before any work happens — illegal routes are
170
- * impossible, not discouraged.
171
- *
172
- * States: `routing` → one state per route → `done`.
173
- *
174
- * ```ts
175
- * const machine = createRouterMachine({
176
- * model: "quick",
177
- * routes: {
178
- * billing: { description: "Payments and invoices", instructions: "Answer the billing question." },
179
- * technical: { description: "Bugs and outages", machine: technicalMachine },
180
- * },
181
- * fallback: "technical",
182
- * });
183
- * ```
184
- */
185
- export declare function createRouterMachine<const TRoutes extends Record<string, PresetEntry>>(config: CreateRouterMachineConfig<TRoutes>): RouterMachine<keyof TRoutes & string>;
186
- //#endregion
187
- //#region src/machines/parallel.d.ts
188
- /** Config for {@link createParallelMachine}. */
189
- interface CreateParallelMachineConfig {
190
- /** Default model ref for request branches. */
191
- model: string;
192
- /** The branches, run concurrently. Each is an inline request or a child machine. */
193
- branches: Record<string, PresetEntry>;
194
- }
195
- /** Context of a {@link createParallelMachine} machine. */
196
- type ParallelContext = {
197
- prompt: string;
198
- results: Record<string, unknown>;
199
- };
200
- /** Machine input of a {@link createParallelMachine} machine. */
201
- type ParallelInput = {
202
- prompt: string;
203
- };
204
- /** Machine output of a {@link createParallelMachine} machine. */
205
- type ParallelOutput = {
206
- results: Record<string, unknown>;
207
- };
208
- /** The machine {@link createParallelMachine} returns. */
209
- type ParallelMachine = PresetMachine<ParallelContext, ParallelInput, ParallelOutput>;
210
- /**
211
- * Static fan-out: every branch runs concurrently as its own region of one
212
- * parallel state, and the run joins when all of them finish. Results are keyed
213
- * by branch name.
214
- *
215
- * Branch count is fixed at author time. For an N decided at run time (a planner
216
- * choosing subtopics), eject to `examples/fan-out`, which spawns branches
217
- * dynamically.
218
- *
219
- * States: `running` (one region per branch) → `done`.
220
- *
221
- * ```ts
222
- * const machine = createParallelMachine({
223
- * model: "quick",
224
- * branches: {
225
- * security: { instructions: "Review for security issues." },
226
- * performance: { instructions: "Review for performance issues." },
227
- * },
228
- * });
229
- * ```
230
- */
231
- export declare function createParallelMachine(config: CreateParallelMachineConfig): ParallelMachine;
232
- //#endregion
233
- //#region src/machines/loop.d.ts
234
- /** The accumulated state a {@link CreateLoopMachineConfig.until} predicate reads. */
235
- interface LoopState {
236
- /** The machine's `input.prompt`. */
237
- prompt: string;
238
- /** Completed iterations. */
239
- iterations: number;
240
- /** Every iteration's output, in order. */
241
- results: unknown[];
242
- /** The latest iteration's output. */
243
- last: unknown;
244
- }
245
- /** Config for {@link createLoopMachine}. */
246
- interface CreateLoopMachineConfig {
247
- /** Default model ref for a request body. */
248
- model: string;
249
- /** The repeated unit of work: an inline request or a child machine. */
250
- body: PresetEntry & {
251
- /** Builds each iteration's prompt. Defaults to the machine's `prompt`. */
252
- prompt?: (state: LoopState) => string;
253
- };
254
- /** Stop condition, checked after each iteration. */
255
- until: (state: LoopState) => boolean;
256
- /** Hard upper bound on machine turns (iterations), enforced by a guard. */
257
- maxTurns: number;
258
- }
259
- /** Context of a {@link createLoopMachine} machine. */
260
- type LoopContext = {
261
- prompt: string;
262
- iterations: number;
263
- results: unknown[];
264
- last: unknown;
265
- };
266
- /** Machine input of a {@link createLoopMachine} machine. */
267
- type LoopInput = {
268
- prompt: string;
269
- };
270
- /** Machine output of a {@link createLoopMachine} machine. */
271
- type LoopOutput = {
272
- iterations: number;
273
- results: unknown[];
274
- last: unknown;
275
- };
276
- /** The machine {@link createLoopMachine} returns. */
277
- type LoopMachine = PresetMachine<LoopContext, LoopInput, LoopOutput>;
278
- /**
279
- * A bounded repeat: run the body, check `until` over the accumulated state,
280
- * and either stop or go again. `maxTurns` is a guard, so the loop cannot
281
- * run away even if `until` never returns `true`.
282
- *
283
- * States: `running` → `checking` → (`running` | `done`).
284
- *
285
- * ```ts
286
- * const machine = createLoopMachine({
287
- * model: "quick",
288
- * body: { instructions: "Improve the draft. Return only the draft." },
289
- * until: ({ last }) => String(last).length > 500,
290
- * maxTurns: 4,
291
- * });
292
- * ```
293
- */
294
- export declare function createLoopMachine(config: CreateLoopMachineConfig): LoopMachine;
295
- //#endregion
296
- //#region src/machines/supervisor.d.ts
297
- /** Config for {@link createSupervisorMachine}. */
298
- interface CreateSupervisorMachineConfig<TWorkers extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
299
- /** Model ref for the supervising decision, and the default for request workers. */
300
- model: string;
301
- /** System prompt for the supervising decision. */
302
- instructions?: string;
303
- /** The workers the supervisor may delegate to, keyed by name. */
304
- workers: TWorkers;
305
- /** Hard upper bound on delegations, enforced by a guard. Default 6. */
306
- maxTurns?: number;
307
- }
308
- /** Context of a {@link createSupervisorMachine} machine. */
309
- type SupervisorContext<TWorker extends string = string> = {
310
- task: string;
311
- results: Record<string, unknown>;
312
- turns: number;
313
- worker: TWorker | null;
314
- };
315
- /** Machine input of a {@link createSupervisorMachine} machine. */
316
- type SupervisorInput = {
317
- task: string;
318
- };
319
- /** Machine output of a {@link createSupervisorMachine} machine. */
320
- type SupervisorOutput = {
321
- results: Record<string, unknown>;
322
- turns: number;
323
- };
324
- /** The events a {@link createSupervisorMachine} machine accepts: one per worker, plus `FINISH`. */
325
- type SupervisorEvent<TWorker extends string = string> = {
326
- type: `DELEGATE_${TWorker}`;
327
- } | {
328
- type: typeof FINISH_EVENT_TYPE;
329
- };
330
- /** The machine {@link createSupervisorMachine} returns. */
331
- type SupervisorMachine<TWorker extends string = string> = PresetMachine<SupervisorContext<TWorker>, SupervisorInput, SupervisorOutput, SupervisorEvent<TWorker>>;
332
- /** The event a supervising decision chooses to delegate to a worker: `DELEGATE_<name>`. */
333
- export declare function delegateEventType(worker: string): string;
334
- /** The event a supervising decision chooses to stop. */
335
- export declare const FINISH_EVENT_TYPE = "FINISH";
336
- /**
337
- * A supervisor delegating to typed workers: each turn, one `agent.decide`
338
- * picks a worker or `FINISH`. Worker results accumulate in context and are fed
339
- * back into the next decision.
340
- *
341
- * Control always returns to the supervisor after a worker finishes — that is
342
- * what separates this from {@link createHandoffMachine}, where control
343
- * transfers and does not come back.
344
- *
345
- * `maxTurns` bounds the delegations twice over: a spent budget removes every
346
- * `DELEGATE_*` from the decision's candidate events, and a guard on each
347
- * delegate transition rejects one anyway. `FINISH` is all that is left.
348
- *
349
- * States: `supervising` → one state per worker → `supervising` → … → `done`.
350
- *
351
- * ```ts
352
- * const machine = createSupervisorMachine({
353
- * model: "quick",
354
- * workers: {
355
- * researcher: { description: "Facts and background", instructions: "Research it." },
356
- * writer: { description: "Prose and summaries", instructions: "Write it up." },
357
- * },
358
- * maxTurns: 4,
359
- * });
360
- * ```
361
- */
362
- export declare function createSupervisorMachine<const TWorkers extends Record<string, PresetEntry>>(config: CreateSupervisorMachineConfig<TWorkers>): SupervisorMachine<keyof TWorkers & string>;
363
- //#endregion
364
- //#region src/machines/handoff.d.ts
365
- /** Config for {@link createHandoffMachine}. */
366
- interface CreateHandoffMachineConfig<TAgents extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
367
- /** The peer agents, keyed by name. Each is an inline request or a child machine. */
368
- agents: TAgents;
369
- /** Which agent holds the mic at the start of a run. */
370
- defaultActiveAgent: keyof TAgents & string;
371
- /** Default model ref for request agents that declare none. */
372
- model?: string;
373
- }
374
- /** Context of a {@link createHandoffMachine} machine. */
375
- type HandoffContext<TAgent extends string = string> = {
376
- message: string;
377
- activeAgent: TAgent;
378
- reply: unknown;
379
- };
380
- /** Machine input of a {@link createHandoffMachine} machine. */
381
- type HandoffInput<TAgent extends string = string> = {
382
- message: string;
383
- activeAgent?: TAgent;
384
- };
385
- /** The events a {@link createHandoffMachine} machine accepts: one per peer agent. */
386
- type HandoffEvent<TAgent extends string = string> = {
387
- type: `transfer_to_${TAgent}`;
388
- message?: string;
389
- };
390
- /** The machine {@link createHandoffMachine} returns. There is no final state, so it has no output. */
391
- type HandoffMachine<TAgent extends string = string> = PresetMachine<HandoffContext<TAgent>, HandoffInput<TAgent>, undefined, HandoffEvent<TAgent>>;
392
- /** The event that hands the mic to a peer: `transfer_to_<name>`. */
393
- export declare function transferEventType(agent: string): string;
394
- /**
395
- * Peer handoff (the swarm shape): `context.activeAgent` holds the mic, runs one
396
- * turn, then the machine settles idle in `waiting`. A `transfer_to_<name>`
397
- * event moves the mic to a peer and re-routes.
398
- *
399
- * Control TRANSFERS and does not return — the opposite of
400
- * {@link createSupervisorMachine}, where every worker hands control back.
401
- *
402
- * There is no final state: a conversation ends when the host stops resuming it.
403
- * Persist the idle snapshot between turns; `activeAgent` round-trips with it.
404
- *
405
- * States: `routing` → one turn state per agent → `waiting` → `routing` → …
406
- *
407
- * ```ts
408
- * const machine = createHandoffMachine({
409
- * model: "quick",
410
- * defaultActiveAgent: "travel",
411
- * agents: {
412
- * travel: { description: "Destinations and itineraries", instructions: "You are a travel concierge." },
413
- * food: { description: "Restaurants and dishes", instructions: "You are a food concierge." },
414
- * },
415
- * });
416
- *
417
- * const next = await runToQuiescence(createAgentRuntime(machine, { executors }), {
418
- * snapshot,
419
- * event: { type: "transfer_to_food", message: "What should I eat there?" },
420
- * });
421
- * ```
422
- */
423
- export declare function createHandoffMachine<const TAgents extends Record<string, PresetEntry>>(config: CreateHandoffMachineConfig<TAgents>): HandoffMachine<keyof TAgents & string>;
424
- //#endregion
425
3
  //#region src/machines/approval-batch.d.ts
426
4
  /** One tool call a model proposed: its call id, tool name, and arguments. */
427
5
  type ProposedCall = {
@@ -532,4 +110,4 @@ type ApprovalBatchMachine = PresetMachine<ApprovalBatchContext, ApprovalBatchInp
532
110
  */
533
111
  export declare function createApprovalBatchMachine(config: CreateApprovalBatchMachineConfig): ApprovalBatchMachine;
534
112
  //#endregion
535
- export type { ApprovalBatchContext, ApprovalBatchEvent, ApprovalBatchInput, ApprovalBatchMachine, ApprovalBatchOutput, ApprovalCallInput, ApprovalCallResult, ApprovalDecision, ApproveAlwaysRule, CreateApprovalBatchMachineConfig, CreateHandoffMachineConfig, CreateLoopMachineConfig, CreateParallelMachineConfig, CreateRouterMachineConfig, CreateSequentialMachineConfig, CreateSupervisorMachineConfig, CreateToolLoopMachineConfig, HandoffContext, HandoffEvent, HandoffInput, HandoffMachine, LoopContext, LoopInput, LoopMachine, LoopOutput, LoopState, ParallelContext, ParallelInput, ParallelMachine, ParallelOutput, PresetEntry, PresetMachine, PresetMachineEntry, PresetRequestEntry, ProposedCall, RouterContext, RouterEvent, RouterInput, RouterMachine, RouterOutput, SequentialContext, SequentialInput, SequentialMachine, SequentialOutput, SequentialPromptArgs, SequentialStep, SupervisorContext, SupervisorEvent, SupervisorInput, SupervisorMachine, SupervisorOutput, ToolLoopContext, ToolLoopInput, ToolLoopMachine, ToolLoopOutput };
113
+ export type { ApprovalBatchContext, ApprovalBatchEvent, ApprovalBatchInput, ApprovalBatchMachine, ApprovalBatchOutput, ApprovalCallInput, ApprovalCallResult, ApprovalDecision, ApproveAlwaysRule, CreateApprovalBatchMachineConfig, ProposedCall };