@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.md +138 -0
  2. package/dist/act-B9hLQls6.mjs +19 -0
  3. package/dist/act-CrX0JwWY.cjs +42 -0
  4. package/dist/ai-sdk.cjs +63 -7
  5. package/dist/ai-sdk.d.cts +13 -3
  6. package/dist/ai-sdk.d.mts +13 -3
  7. package/dist/ai-sdk.mjs +63 -7
  8. package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
  9. package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
  10. package/dist/decision-object-B5zGSPFp.d.mts +15 -0
  11. package/dist/decision-object-DBcLWVvv.d.cts +15 -0
  12. package/dist/{run-agent-Ct_GZw_f.mjs → effects-BT_cSY0j.mjs} +1003 -109
  13. package/dist/{run-agent-s5D32w99.cjs → effects-DDseYtJk.cjs} +1037 -107
  14. package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
  15. package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
  16. package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
  17. package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
  18. package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
  19. package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
  20. package/dist/index.cjs +660 -286
  21. package/dist/index.d.cts +168 -9
  22. package/dist/index.d.mts +168 -9
  23. package/dist/index.mjs +639 -271
  24. package/dist/internal-C3Lqu538.d.cts +43 -0
  25. package/dist/internal-DUcdhk-i.d.mts +43 -0
  26. package/dist/log.cjs +2 -2
  27. package/dist/log.d.cts +1 -1
  28. package/dist/log.d.mts +1 -1
  29. package/dist/log.mjs +2 -2
  30. package/dist/machines.cjs +457 -41
  31. package/dist/machines.d.cts +114 -43
  32. package/dist/machines.d.mts +114 -43
  33. package/dist/machines.mjs +457 -42
  34. package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
  35. package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
  36. package/dist/openai.cjs +149 -36
  37. package/dist/openai.d.cts +28 -10
  38. package/dist/openai.d.mts +28 -10
  39. package/dist/openai.mjs +149 -36
  40. package/dist/otel.d.cts +1 -1
  41. package/dist/otel.d.mts +1 -1
  42. package/dist/{run-agent-BGdx5913.d.mts → run-agent-30mH2moE.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-DlPzBWj-.d.mts} +91 -9
  44. package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
  45. package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BaNyz6Q3.d.cts} +4 -4
  46. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-C1CG_nfX.d.mts} +4 -4
  47. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  48. package/dist/tanstack-ai.cjs +62 -4
  49. package/dist/tanstack-ai.d.cts +18 -6
  50. package/dist/tanstack-ai.d.mts +18 -6
  51. package/dist/tanstack-ai.mjs +62 -4
  52. package/dist/testing.cjs +2493 -1502
  53. package/dist/testing.d.cts +360 -256
  54. package/dist/testing.d.mts +360 -256
  55. package/dist/testing.mjs +2489 -1503
  56. package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
  57. package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
  58. package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
  59. package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
  60. package/dist/{usage-BDiJKyv9.d.cts → usage-Bm5nvpow.d.cts} +6 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-BnikdOca.d.mts} +6 -1
  62. package/dist/utils-7lSa4H-i.d.cts +403 -0
  63. package/dist/utils-CBbKw2fM.d.mts +403 -0
  64. package/dist/validate.cjs +44 -12
  65. package/dist/validate.d.cts +6 -6
  66. package/dist/validate.d.mts +6 -6
  67. package/dist/validate.mjs +44 -12
  68. package/dist/verify-ChyX6jq0.mjs +2306 -0
  69. package/dist/verify-CwlombbC.cjs +2359 -0
  70. package/dist/{verify-BQpE8hUz.d.cts → verify-DJHfEfm6.d.cts} +213 -14
  71. package/dist/{verify-CqeuEmIk.d.mts → verify-i9Hiwc5g.d.mts} +213 -14
  72. package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
  73. package/dist/with-model-calls-BkOwdroS.mjs +213 -0
  74. package/docs/act.md +102 -0
  75. package/docs/advanced.md +105 -0
  76. package/docs/any-stack.md +62 -0
  77. package/docs/choosing-a-run-mode.md +55 -0
  78. package/docs/debugging.md +29 -0
  79. package/docs/decisions.md +473 -0
  80. package/docs/environment-and-policy.md +188 -0
  81. package/docs/evals.md +509 -0
  82. package/docs/event-log.md +312 -0
  83. package/docs/from-a-loop.md +528 -0
  84. package/docs/generate-machines.md +110 -0
  85. package/docs/hosts.md +414 -0
  86. package/docs/human-in-the-loop.md +177 -0
  87. package/docs/index.md +48 -0
  88. package/docs/judgments.md +281 -0
  89. package/docs/langgraph-comparison.md +198 -0
  90. package/docs/machines-as-data.md +454 -0
  91. package/docs/machines-presets.md +198 -0
  92. package/docs/machines.md +497 -0
  93. package/docs/messages.md +67 -0
  94. package/docs/meta.json +52 -0
  95. package/docs/models-and-providers.md +268 -0
  96. package/docs/multi-agent.md +68 -0
  97. package/docs/observability.md +109 -0
  98. package/docs/patterns.md +31 -0
  99. package/docs/persistence.md +207 -0
  100. package/docs/quickstart.md +121 -0
  101. package/docs/roadmap.md +22 -0
  102. package/docs/scope.md +75 -0
  103. package/docs/statechart-policy-examples.md +69 -0
  104. package/docs/steps.md +56 -0
  105. package/docs/strangler-fig.md +323 -0
  106. package/docs/text-requests.md +250 -0
  107. package/docs/thinking-in-state-machines.md +324 -0
  108. package/docs/tools.md +249 -0
  109. package/docs/upgrading.md +37 -0
  110. package/docs/usage-and-budgets.md +518 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +492 -0
  113. package/docs/xstate-4-and-5-apps.md +161 -0
  114. package/llms.txt +53 -0
  115. package/package.json +10 -3
  116. package/readme.md +30 -15
  117. package/skills/add-evals/SKILL.md +3 -1
  118. package/skills/add-traces/SKILL.md +6 -1
  119. package/skills/build-machine/SKILL.md +84 -0
  120. package/skills/generate-machine/SKILL.md +1 -1
  121. package/skills/graph-engineering/SKILL.md +13 -3
  122. package/skills/improve-machine/SKILL.md +21 -2
  123. package/skills/loop-to-machine/SKILL.md +147 -192
  124. package/skills/loop-to-machine/reference.md +260 -0
  125. package/dist/utils-BnXdWih3.d.mts +0 -108
  126. package/dist/utils-ebVpCYoF.d.cts +0 -108
  127. package/dist/verify-Bpahmr34.mjs +0 -1241
  128. package/dist/verify-DCLZa9R0.cjs +0 -1288
  129. package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
  130. package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
@@ -1,5 +1,5 @@
1
- import { u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
2
- import { $ as AgentError } from "./text-logic-CV_4KGr6.cjs";
1
+ import { p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.cjs";
2
+ import { at as AgentError, p as AgentTextResult, t as AgentCallUsage } from "./text-logic-CSf9bqpP.cjs";
3
3
  import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
4
4
  //#region src/verify.d.ts
5
5
  /** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
@@ -20,6 +20,15 @@ interface AgentLintDiagnostic {
20
20
  interface LintAgentMachineOptions {
21
21
  /** Skip these check codes entirely. */
22
22
  disable?: AgentLintDiagnostic["code"][];
23
+ /**
24
+ * Skip one check at one state: `{ code: "invoke-without-on-error", path:
25
+ * "listening" }` for a callback bridge that cannot fail. `path` is the
26
+ * diagnostic's `path`.
27
+ */
28
+ ignore?: Array<{
29
+ code: AgentLintDiagnostic["code"];
30
+ path: string;
31
+ }>;
23
32
  /**
24
33
  * Throw {@link AgentLintError} on failing diagnostics instead of returning
25
34
  * them. Fails on error-severity findings; add `warnings: true` to fail on
@@ -211,6 +220,23 @@ interface SimulateAgentResult {
211
220
  * ```
212
221
  */
213
222
  declare function simulateAgent(machine: AnyStateMachine, options: SimulateAgentOptions): Promise<SimulateAgentResult>;
223
+ /**
224
+ * Marks a canned text-request output for {@link explorePaths},
225
+ * {@link canReach}, or {@link simulateAgent} as the whole
226
+ * `{ result, messages }` envelope the invoke resolves with, so a machine that
227
+ * reads `output.messages` sees them. A plain canned value is the `result`,
228
+ * with `messages: []`.
229
+ *
230
+ * @example
231
+ * ```ts
232
+ * await explorePaths(machine, {
233
+ * outputs: { reply: [textOutput('hi', { messages: [{ role: 'assistant', content: 'hi' }] })] },
234
+ * });
235
+ * ```
236
+ */
237
+ declare function textOutput<TResult>(result: TResult, options?: {
238
+ messages?: AgentMessage[];
239
+ }): AgentTextResult<TResult>;
214
240
  /** Options for {@link explorePaths}. */
215
241
  /**
216
242
  * The snapshot type the exploration callbacks (`payloads`, `dedupeBy`, a
@@ -224,26 +250,60 @@ interface ExplorePathsOptions {
224
250
  input?: unknown;
225
251
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
226
252
  maxDepth?: number;
227
- /** Total path cap before exploration stops (reported via `hitPathCap`). Default 200. */
253
+ /**
254
+ * Path cap per search before it stops (reported via `hitPathCap`). Default
255
+ * 200. Each explored child search has its own; see `budget` for a total.
256
+ */
228
257
  maxPaths?: number;
229
258
  /**
230
- * Total branch points expanded before exploration stops (reported via
259
+ * Branch points expanded per search before it stops (reported via
231
260
  * `hitPathCap`). Default 100,000. It bounds work and memory where
232
261
  * `maxPaths` cannot: a loopy machine expands many nodes per terminal.
262
+ * Each explored child search has its own; see `budget` for a total.
233
263
  */
234
264
  maxNodes?: number;
265
+ /**
266
+ * Limits on the whole call. When one runs out, the search stops cleanly:
267
+ * the report is `partial` and not `complete`, and `unexplored` notes
268
+ * `budget-exhausted: nodes` or `budget-exhausted: ms` with the counts so
269
+ * far. {@link canReach} returns what it found, with `complete: false`.
270
+ */
271
+ budget?: {
272
+ /**
273
+ * Branch points expanded in total: the top-level search and every child
274
+ * search it triggers (`children: "explore"`). A cached child outcome
275
+ * counts once, when it is computed; a cache hit costs nothing. Default
276
+ * 250,000; raise it explicitly for a bigger machine.
277
+ */
278
+ nodes?: number;
279
+ /**
280
+ * Wall-clock milliseconds from the start of the call, checked at each
281
+ * branch point, in child searches too. A slow `payloads` or guard call
282
+ * is not interrupted: the check runs between them.
283
+ */
284
+ ms?: number;
285
+ /**
286
+ * Explored-child outcomes kept for reuse per search, keyed by logic, src,
287
+ * and input; the least recently used is evicted first. An evicted child
288
+ * is explored again when reached, and counts again. Default 64.
289
+ */
290
+ childCache?: number;
291
+ };
235
292
  /**
236
293
  * Every output to try per src: a text request's src (the
237
294
  * `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`)
238
295
  * or any other invoked actor's src. A one-element list is a canned output,
239
296
  * reused every time that src is reached; a text request resolves with it as
240
- * its `result` (`{ result, messages: [] }`). A src with two or more outputs
297
+ * its `result` (`{ result, messages: [] }`), or with the whole envelope a
298
+ * {@link textOutput} value carries. A src with two or more outputs
241
299
  * forks one branch per output (plus the `errors` branch when the src is
242
300
  * listed there too), so a machine whose `onDone` branches on the output is
243
301
  * explored down every arm. Each fork counts against `maxDepth`, and each
244
- * forked branch records `{ type: 'xstate.done.actor.<id>', output }` in the
302
+ * forked branch records `{ type: 'xstate.done.actor', actorId, output }` in the
245
303
  * path. A src with no entry (and no `errors` entry) halts that branch with a
246
- * `needs-output` terminal.
304
+ * `needs-output` terminal. An empty list, `[]`, is a src that never settles
305
+ * (a callback bridge, a long-lived listener): its invoke stays pending and
306
+ * only events move the machine on.
247
307
  */
248
308
  outputs?: Record<string, unknown[]>;
249
309
  /**
@@ -253,7 +313,7 @@ interface ExplorePathsOptions {
253
313
  * are explored. When the src also has an output, both branches are explored;
254
314
  * when it has only an error, only the failing one is. Each fork counts
255
315
  * against `maxDepth`, and the failing branch records
256
- * `{ type: 'xstate.error.actor.<id>' }` in the path.
316
+ * `{ type: 'xstate.error.actor', actorId }` in the path.
257
317
  *
258
318
  * A decision invoke can be keyed here too — by its src (usually
259
319
  * `agent.decide`) or by its invoke id — standing in for retry exhaustion.
@@ -262,8 +322,85 @@ interface ExplorePathsOptions {
262
322
  *
263
323
  * A rejection that reaches no `onError` errors the machine, and that path
264
324
  * ends in an `error` terminal.
325
+ *
326
+ * An array forks one failing branch per element, each recording its value
327
+ * as `error` in the path entry; `[]` is no entry. Any other value is a
328
+ * single failure. A single failure that is itself an array must be wrapped:
329
+ * `[[...]]`.
330
+ */
331
+ errors?: Record<string, unknown | unknown[]>;
332
+ /**
333
+ * Where external events fork. `"idle"` (default): only at idle waits.
334
+ * `"pending"`: also wherever an invoke is outstanding — before a text or
335
+ * scripted invoke resolves (straight through or forked), at a
336
+ * `needs-output` block, and at a decision — each event the active states
337
+ * accept (decision candidates excepted) forks as "the event arrives before
338
+ * the actor settles". Each such branch counts against `maxDepth`;
339
+ * `payloads` and `dedupeBy` apply as at idle waits.
340
+ */
341
+ interleave?: "idle" | "pending";
342
+ /**
343
+ * How a child state machine (invoked, or spawned with `enq.spawn`) with no
344
+ * `outputs` entry settles. `"outputs"` (default): it is a `needs-output`
345
+ * block like any other src. `"explore"`: the child is explored on its own
346
+ * with the same options (and its own invoke or spawn input), to at most 4
347
+ * nested levels. Each distinct `output` of its `done` terminals forks the
348
+ * parent as an output, each distinct failure of its `error` terminals
349
+ * forks a failing branch, each distinct event it sends its parent
350
+ * (`sendTo(parent, …)`) forks the parent receiving it, and a child that
351
+ * can stall `idle` adds an `idle` terminal. Child idle waits are not
352
+ * parent fork points. A child search that was incomplete also ends the
353
+ * parent branch `needs-output` for that src, so the parent report is not
354
+ * complete.
355
+ *
356
+ * Bounded: each child is explored independently. Its events and outputs
357
+ * are not correlated: any of its events, each at most once per path and
358
+ * in any order, can reach the parent before it settles. While an
359
+ * explored child is pending, it and every other pending invoke or text
360
+ * request settle in any order; other combinations are not
361
+ * enumerated beyond `interleave`. A child receives only the events its
362
+ * parent forwards or the host sends it, so the child search offers
363
+ * external events only for the types
364
+ * {@link ExplorePathsOptions.childEvents} lists for its src (none by
365
+ * default). A child wait that accepts an event not listed leaves the
366
+ * child search incomplete.
367
+ *
368
+ * `"coupled"`: each child machine is stepped inside the parent's search,
369
+ * one move at a time, so a witness is a run the machines can make
370
+ * together. A child's events reach the parent in the order the child sends
371
+ * them on its own path, its output follows them, and an event the parent
372
+ * sends it (`sendTo`/`forwardTo`) is applied to the child's current state,
373
+ * in order, instead of arriving at any time. `childEvents` then lists only
374
+ * the types the host sends the child directly; the parent's own sends need
375
+ * no entry. A child's pending work and the events that can reach it race
376
+ * as with `interleave: "pending"`. Child moves count against `maxDepth`
377
+ * like the parent's, and appear on a path with `actor` set to the child's
378
+ * id (the child's own events, its choices, its settled work); the events
379
+ * it sends the parent appear as the parent receives them. With `dedupeBy`,
380
+ * each child's state is part of the key. A target predicate and `dedupeBy`
381
+ * read each child's explored state through `snapshot.children[id]
382
+ * .getSnapshot()`. More precise and often cheaper
383
+ * than `"explore"` for authored child machines; `"explore"` remains the
384
+ * over-approximation for a child whose behavior you do not want to trust.
385
+ */
386
+ children?: "outputs" | "explore" | "coupled";
387
+ /**
388
+ * With `children: "explore"`: per child src, the event types that can
389
+ * reach the child at its waits (the ones the parent forwards with
390
+ * `sendTo`/`forwardTo`, or the host sends it directly). Unlisted types are
391
+ * never offered to the child. With `children: "coupled"`: only the types
392
+ * the host sends the child directly; the parent's sends are delivered as
393
+ * the parent makes them.
394
+ */
395
+ childEvents?: Record<string, string[]>;
396
+ /**
397
+ * The event types the host can send the machine at its waits (and, with
398
+ * `interleave: "pending"`, while work is pending). Default: every type the
399
+ * active states accept. List them when some accepted types only ever come
400
+ * from the machine's own children (a child's status events), so the search
401
+ * does not offer them as if the host sent them.
265
402
  */
266
- errors?: Record<string, unknown>;
403
+ hostEvents?: string[];
267
404
  /**
268
405
  * Payloads to try per event type at each branch point, given the settled
269
406
  * snapshot there. At a decision or an idle wait, an event type with an
@@ -292,6 +429,35 @@ interface ExplorePathsOptions {
292
429
  * Without it, every path is explored in full.
293
430
  */
294
431
  dedupeBy?: (snapshot: ExploreSnapshot) => string;
432
+ /**
433
+ * Armed timers: `after` delays, state and invoke `timeout`s, and delayed
434
+ * `enq.raise` events (`snapshot.timers` entries the machine delivers to
435
+ * itself). `"fire"` (default): each armed timer whose event the active
436
+ * states take is an event that may arrive, offered where host events are
437
+ * (at idle waits, and while work is pending under `interleave: "pending"`),
438
+ * in any order regardless of its delay. A fired timer records its event in
439
+ * the path, e.g. `{ type: 'xstate.after', delay: 1000, stateId: 'm.waiting' }`.
440
+ * `"ignore"`: timers never fire; a wait with an armed timer adds an
441
+ * `unexplored` note and lists the timer's event type in `unexpandedEvents`,
442
+ * so the report is not complete.
443
+ */
444
+ timers?: "fire" | "ignore";
445
+ /**
446
+ * Usage values to try per text-request src. When a request with an entry
447
+ * settles at the root and the active states take `@agent.usage`, the
448
+ * search delivers `{ type: '@agent.usage', kind: 'text', id, src, model,
449
+ * name?, usage }` to the root immediately before the request's completion,
450
+ * as a run does (a value the active states refuse is dropped, as a run drops it): once per listed value, each a fork that counts against
451
+ * `maxDepth` and records the usage event in the path. One value with one
452
+ * canned output is no fork, but its usage event is still recorded. No `budget`
453
+ * field is sent. A settling request with no entry while a usage transition
454
+ * is active lists `@agent.usage` in `vacuous`. With `children:
455
+ * "coupled"`, a child's text request forks once per value and its usage
456
+ * event goes to the root, which takes or drops it the same way (no
457
+ * `vacuous` entry). Requests inside other children, and decisions, deliver
458
+ * no usage.
459
+ */
460
+ usage?: Record<string, AgentCallUsage[]>;
295
461
  }
296
462
  /** A single explored path's terminal outcome. */
297
463
  interface AgentPathTerminal {
@@ -308,6 +474,8 @@ interface AgentPathTerminal {
308
474
  missingSrc?: string;
309
475
  /** For `error`: the failure value that errored the machine. */
310
476
  error?: unknown;
477
+ /** For `done`: the machine's output (absent when it has none). */
478
+ output?: unknown;
311
479
  }
312
480
  /** The report returned by {@link explorePaths}. */
313
481
  interface AgentPathReport {
@@ -321,14 +489,36 @@ interface AgentPathReport {
321
489
  unexplored: string[];
322
490
  /** Total paths explored. */
323
491
  pathsExplored: number;
324
- /** True when a cap (`maxPaths` or `maxNodes`) cut exploration short (report is partial). */
492
+ /** True when `maxPaths` or `maxNodes` cut exploration short (report is partial). */
325
493
  hitPathCap: boolean;
494
+ /**
495
+ * True when a cap or the `budget` cut exploration short: `hitPathCap`, or
496
+ * a `budget-exhausted` note in `unexplored`.
497
+ */
498
+ partial: boolean;
499
+ /**
500
+ * True when the report covers every path: not `partial`, every payload
501
+ * expanded, and every branch ended `done`, `idle`, or `error`.
502
+ */
503
+ complete: boolean;
326
504
  /**
327
505
  * Event types whose payload variants were not all tried: their schema has
328
506
  * a non-finite field or a product over the fill cap, and `payloads` has no
329
507
  * entry for them. Add a `payloads` entry for each to cover them.
330
508
  */
331
509
  unexpandedEvents: string[];
510
+ /**
511
+ * Event types offered only as the bare `{ type }` fallback at a snapshot
512
+ * where a transition for them may read the payload (a function transition,
513
+ * guard, `matches`, or context mapper): no `payloads` entry, no decision
514
+ * option, and no schema variant beyond `{ type }` (no schema, or one whose
515
+ * fields the fill cannot enumerate). A subset of `unexpandedEvents`: the
516
+ * payload-reading logic was exercised with no payload at all. Also lists
517
+ * `@agent.usage` when a text request settled while a usage transition was
518
+ * active and `usage` had no entry for its src. Data only; it does not
519
+ * change completeness.
520
+ */
521
+ vacuous: string[];
332
522
  }
333
523
  /**
334
524
  * Enumerates a machine's decision and external-event branches to a bounded
@@ -356,8 +546,9 @@ interface AgentPathReport {
356
546
  * payload table tractable.
357
547
  *
358
548
  * Combinatorics are bounded by `maxDepth` (default 8), `maxPaths` (default
359
- * 200), and `maxNodes` (default 100,000), the last two reported via
360
- * `hitPathCap`.
549
+ * 200), and `maxNodes` (default 100,000) per search, the last two reported
550
+ * via `hitPathCap`, and by `budget` across the whole call, child searches
551
+ * included. A cut-short report is `partial` and not `complete`.
361
552
  *
362
553
  * @example
363
554
  * ```ts
@@ -376,13 +567,21 @@ interface CanReachResult {
376
567
  witness?: ChosenEvent[];
377
568
  /**
378
569
  * False when the search left a branch it could not rule out unexplored: a
379
- * cap (`maxPaths` or `maxNodes`) cut it short, a path reached `maxDepth`, a
570
+ * cap (`maxPaths` or `maxNodes`) or the `budget` cut it short, a path reached `maxDepth`, a
380
571
  * branch stopped `needs-output` on a src with no `outputs` entry, or an event type
381
572
  * was not expanded to all its payload variants (`unexpandedEvents` in the
382
573
  * {@link explorePaths} report). `reachable: false` is a proof of
383
574
  * unreachability only when `complete` is true.
384
575
  */
385
576
  complete: boolean;
577
+ /**
578
+ * Why the search is not complete, present only when `complete` is false:
579
+ * the {@link explorePaths} report's `unexplored` notes (such as
580
+ * `needs-output: no \`outputs\` entry for src 'resume' at path []`), plus a
581
+ * `path-cap`, `unexpanded-events`, or `max-depth` note for the causes the
582
+ * report records elsewhere.
583
+ */
584
+ unexplored?: string[];
386
585
  }
387
586
  /** Thrown when a string reachability target is not a state in the machine. */
388
587
  declare class AgentUnknownStateError extends AgentError {
@@ -419,4 +618,4 @@ declare class AgentUnknownStateError extends AgentError {
419
618
  */
420
619
  declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
421
620
  //#endregion
422
- export { assertAgentMachine as _, AgentPathTerminal as a, lintAgentMachine as b, CanReachResult as c, ExploreSnapshot as d, LintAgentMachineOptions as f, SimulationTrailEntry as g, SimulationScript as h, AgentPathReport as i, CanReachTarget as l, SimulateAgentResult as m, AgentLintError as n, AgentUnknownStateError as o, SimulateAgentOptions as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, ExplorePathsOptions as u, canReach as v, simulateAgent as x, explorePaths as y };
621
+ export { textOutput as S, assertAgentMachine as _, AgentPathTerminal as a, lintAgentMachine as b, CanReachResult as c, ExploreSnapshot as d, LintAgentMachineOptions as f, SimulationTrailEntry as g, SimulationScript as h, AgentPathReport as i, CanReachTarget as l, SimulateAgentResult as m, AgentLintError as n, AgentUnknownStateError as o, SimulateAgentOptions as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, ExplorePathsOptions as u, canReach as v, simulateAgent as x, explorePaths as y };
@@ -1,5 +1,5 @@
1
- import { u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
2
- import { $ as AgentError } from "./text-logic-Ckh-rJFV.mjs";
1
+ import { p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.mjs";
2
+ import { at as AgentError, p as AgentTextResult, t as AgentCallUsage } from "./text-logic-BqxalgMr.mjs";
3
3
  import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
4
4
  //#region src/verify.d.ts
5
5
  /** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
@@ -20,6 +20,15 @@ interface AgentLintDiagnostic {
20
20
  interface LintAgentMachineOptions {
21
21
  /** Skip these check codes entirely. */
22
22
  disable?: AgentLintDiagnostic["code"][];
23
+ /**
24
+ * Skip one check at one state: `{ code: "invoke-without-on-error", path:
25
+ * "listening" }` for a callback bridge that cannot fail. `path` is the
26
+ * diagnostic's `path`.
27
+ */
28
+ ignore?: Array<{
29
+ code: AgentLintDiagnostic["code"];
30
+ path: string;
31
+ }>;
23
32
  /**
24
33
  * Throw {@link AgentLintError} on failing diagnostics instead of returning
25
34
  * them. Fails on error-severity findings; add `warnings: true` to fail on
@@ -211,6 +220,23 @@ interface SimulateAgentResult {
211
220
  * ```
212
221
  */
213
222
  declare function simulateAgent(machine: AnyStateMachine, options: SimulateAgentOptions): Promise<SimulateAgentResult>;
223
+ /**
224
+ * Marks a canned text-request output for {@link explorePaths},
225
+ * {@link canReach}, or {@link simulateAgent} as the whole
226
+ * `{ result, messages }` envelope the invoke resolves with, so a machine that
227
+ * reads `output.messages` sees them. A plain canned value is the `result`,
228
+ * with `messages: []`.
229
+ *
230
+ * @example
231
+ * ```ts
232
+ * await explorePaths(machine, {
233
+ * outputs: { reply: [textOutput('hi', { messages: [{ role: 'assistant', content: 'hi' }] })] },
234
+ * });
235
+ * ```
236
+ */
237
+ declare function textOutput<TResult>(result: TResult, options?: {
238
+ messages?: AgentMessage[];
239
+ }): AgentTextResult<TResult>;
214
240
  /** Options for {@link explorePaths}. */
215
241
  /**
216
242
  * The snapshot type the exploration callbacks (`payloads`, `dedupeBy`, a
@@ -224,26 +250,60 @@ interface ExplorePathsOptions {
224
250
  input?: unknown;
225
251
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
226
252
  maxDepth?: number;
227
- /** Total path cap before exploration stops (reported via `hitPathCap`). Default 200. */
253
+ /**
254
+ * Path cap per search before it stops (reported via `hitPathCap`). Default
255
+ * 200. Each explored child search has its own; see `budget` for a total.
256
+ */
228
257
  maxPaths?: number;
229
258
  /**
230
- * Total branch points expanded before exploration stops (reported via
259
+ * Branch points expanded per search before it stops (reported via
231
260
  * `hitPathCap`). Default 100,000. It bounds work and memory where
232
261
  * `maxPaths` cannot: a loopy machine expands many nodes per terminal.
262
+ * Each explored child search has its own; see `budget` for a total.
233
263
  */
234
264
  maxNodes?: number;
265
+ /**
266
+ * Limits on the whole call. When one runs out, the search stops cleanly:
267
+ * the report is `partial` and not `complete`, and `unexplored` notes
268
+ * `budget-exhausted: nodes` or `budget-exhausted: ms` with the counts so
269
+ * far. {@link canReach} returns what it found, with `complete: false`.
270
+ */
271
+ budget?: {
272
+ /**
273
+ * Branch points expanded in total: the top-level search and every child
274
+ * search it triggers (`children: "explore"`). A cached child outcome
275
+ * counts once, when it is computed; a cache hit costs nothing. Default
276
+ * 250,000; raise it explicitly for a bigger machine.
277
+ */
278
+ nodes?: number;
279
+ /**
280
+ * Wall-clock milliseconds from the start of the call, checked at each
281
+ * branch point, in child searches too. A slow `payloads` or guard call
282
+ * is not interrupted: the check runs between them.
283
+ */
284
+ ms?: number;
285
+ /**
286
+ * Explored-child outcomes kept for reuse per search, keyed by logic, src,
287
+ * and input; the least recently used is evicted first. An evicted child
288
+ * is explored again when reached, and counts again. Default 64.
289
+ */
290
+ childCache?: number;
291
+ };
235
292
  /**
236
293
  * Every output to try per src: a text request's src (the
237
294
  * `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`)
238
295
  * or any other invoked actor's src. A one-element list is a canned output,
239
296
  * reused every time that src is reached; a text request resolves with it as
240
- * its `result` (`{ result, messages: [] }`). A src with two or more outputs
297
+ * its `result` (`{ result, messages: [] }`), or with the whole envelope a
298
+ * {@link textOutput} value carries. A src with two or more outputs
241
299
  * forks one branch per output (plus the `errors` branch when the src is
242
300
  * listed there too), so a machine whose `onDone` branches on the output is
243
301
  * explored down every arm. Each fork counts against `maxDepth`, and each
244
- * forked branch records `{ type: 'xstate.done.actor.<id>', output }` in the
302
+ * forked branch records `{ type: 'xstate.done.actor', actorId, output }` in the
245
303
  * path. A src with no entry (and no `errors` entry) halts that branch with a
246
- * `needs-output` terminal.
304
+ * `needs-output` terminal. An empty list, `[]`, is a src that never settles
305
+ * (a callback bridge, a long-lived listener): its invoke stays pending and
306
+ * only events move the machine on.
247
307
  */
248
308
  outputs?: Record<string, unknown[]>;
249
309
  /**
@@ -253,7 +313,7 @@ interface ExplorePathsOptions {
253
313
  * are explored. When the src also has an output, both branches are explored;
254
314
  * when it has only an error, only the failing one is. Each fork counts
255
315
  * against `maxDepth`, and the failing branch records
256
- * `{ type: 'xstate.error.actor.<id>' }` in the path.
316
+ * `{ type: 'xstate.error.actor', actorId }` in the path.
257
317
  *
258
318
  * A decision invoke can be keyed here too — by its src (usually
259
319
  * `agent.decide`) or by its invoke id — standing in for retry exhaustion.
@@ -262,8 +322,85 @@ interface ExplorePathsOptions {
262
322
  *
263
323
  * A rejection that reaches no `onError` errors the machine, and that path
264
324
  * ends in an `error` terminal.
325
+ *
326
+ * An array forks one failing branch per element, each recording its value
327
+ * as `error` in the path entry; `[]` is no entry. Any other value is a
328
+ * single failure. A single failure that is itself an array must be wrapped:
329
+ * `[[...]]`.
330
+ */
331
+ errors?: Record<string, unknown | unknown[]>;
332
+ /**
333
+ * Where external events fork. `"idle"` (default): only at idle waits.
334
+ * `"pending"`: also wherever an invoke is outstanding — before a text or
335
+ * scripted invoke resolves (straight through or forked), at a
336
+ * `needs-output` block, and at a decision — each event the active states
337
+ * accept (decision candidates excepted) forks as "the event arrives before
338
+ * the actor settles". Each such branch counts against `maxDepth`;
339
+ * `payloads` and `dedupeBy` apply as at idle waits.
340
+ */
341
+ interleave?: "idle" | "pending";
342
+ /**
343
+ * How a child state machine (invoked, or spawned with `enq.spawn`) with no
344
+ * `outputs` entry settles. `"outputs"` (default): it is a `needs-output`
345
+ * block like any other src. `"explore"`: the child is explored on its own
346
+ * with the same options (and its own invoke or spawn input), to at most 4
347
+ * nested levels. Each distinct `output` of its `done` terminals forks the
348
+ * parent as an output, each distinct failure of its `error` terminals
349
+ * forks a failing branch, each distinct event it sends its parent
350
+ * (`sendTo(parent, …)`) forks the parent receiving it, and a child that
351
+ * can stall `idle` adds an `idle` terminal. Child idle waits are not
352
+ * parent fork points. A child search that was incomplete also ends the
353
+ * parent branch `needs-output` for that src, so the parent report is not
354
+ * complete.
355
+ *
356
+ * Bounded: each child is explored independently. Its events and outputs
357
+ * are not correlated: any of its events, each at most once per path and
358
+ * in any order, can reach the parent before it settles. While an
359
+ * explored child is pending, it and every other pending invoke or text
360
+ * request settle in any order; other combinations are not
361
+ * enumerated beyond `interleave`. A child receives only the events its
362
+ * parent forwards or the host sends it, so the child search offers
363
+ * external events only for the types
364
+ * {@link ExplorePathsOptions.childEvents} lists for its src (none by
365
+ * default). A child wait that accepts an event not listed leaves the
366
+ * child search incomplete.
367
+ *
368
+ * `"coupled"`: each child machine is stepped inside the parent's search,
369
+ * one move at a time, so a witness is a run the machines can make
370
+ * together. A child's events reach the parent in the order the child sends
371
+ * them on its own path, its output follows them, and an event the parent
372
+ * sends it (`sendTo`/`forwardTo`) is applied to the child's current state,
373
+ * in order, instead of arriving at any time. `childEvents` then lists only
374
+ * the types the host sends the child directly; the parent's own sends need
375
+ * no entry. A child's pending work and the events that can reach it race
376
+ * as with `interleave: "pending"`. Child moves count against `maxDepth`
377
+ * like the parent's, and appear on a path with `actor` set to the child's
378
+ * id (the child's own events, its choices, its settled work); the events
379
+ * it sends the parent appear as the parent receives them. With `dedupeBy`,
380
+ * each child's state is part of the key. A target predicate and `dedupeBy`
381
+ * read each child's explored state through `snapshot.children[id]
382
+ * .getSnapshot()`. More precise and often cheaper
383
+ * than `"explore"` for authored child machines; `"explore"` remains the
384
+ * over-approximation for a child whose behavior you do not want to trust.
385
+ */
386
+ children?: "outputs" | "explore" | "coupled";
387
+ /**
388
+ * With `children: "explore"`: per child src, the event types that can
389
+ * reach the child at its waits (the ones the parent forwards with
390
+ * `sendTo`/`forwardTo`, or the host sends it directly). Unlisted types are
391
+ * never offered to the child. With `children: "coupled"`: only the types
392
+ * the host sends the child directly; the parent's sends are delivered as
393
+ * the parent makes them.
394
+ */
395
+ childEvents?: Record<string, string[]>;
396
+ /**
397
+ * The event types the host can send the machine at its waits (and, with
398
+ * `interleave: "pending"`, while work is pending). Default: every type the
399
+ * active states accept. List them when some accepted types only ever come
400
+ * from the machine's own children (a child's status events), so the search
401
+ * does not offer them as if the host sent them.
265
402
  */
266
- errors?: Record<string, unknown>;
403
+ hostEvents?: string[];
267
404
  /**
268
405
  * Payloads to try per event type at each branch point, given the settled
269
406
  * snapshot there. At a decision or an idle wait, an event type with an
@@ -292,6 +429,35 @@ interface ExplorePathsOptions {
292
429
  * Without it, every path is explored in full.
293
430
  */
294
431
  dedupeBy?: (snapshot: ExploreSnapshot) => string;
432
+ /**
433
+ * Armed timers: `after` delays, state and invoke `timeout`s, and delayed
434
+ * `enq.raise` events (`snapshot.timers` entries the machine delivers to
435
+ * itself). `"fire"` (default): each armed timer whose event the active
436
+ * states take is an event that may arrive, offered where host events are
437
+ * (at idle waits, and while work is pending under `interleave: "pending"`),
438
+ * in any order regardless of its delay. A fired timer records its event in
439
+ * the path, e.g. `{ type: 'xstate.after', delay: 1000, stateId: 'm.waiting' }`.
440
+ * `"ignore"`: timers never fire; a wait with an armed timer adds an
441
+ * `unexplored` note and lists the timer's event type in `unexpandedEvents`,
442
+ * so the report is not complete.
443
+ */
444
+ timers?: "fire" | "ignore";
445
+ /**
446
+ * Usage values to try per text-request src. When a request with an entry
447
+ * settles at the root and the active states take `@agent.usage`, the
448
+ * search delivers `{ type: '@agent.usage', kind: 'text', id, src, model,
449
+ * name?, usage }` to the root immediately before the request's completion,
450
+ * as a run does (a value the active states refuse is dropped, as a run drops it): once per listed value, each a fork that counts against
451
+ * `maxDepth` and records the usage event in the path. One value with one
452
+ * canned output is no fork, but its usage event is still recorded. No `budget`
453
+ * field is sent. A settling request with no entry while a usage transition
454
+ * is active lists `@agent.usage` in `vacuous`. With `children:
455
+ * "coupled"`, a child's text request forks once per value and its usage
456
+ * event goes to the root, which takes or drops it the same way (no
457
+ * `vacuous` entry). Requests inside other children, and decisions, deliver
458
+ * no usage.
459
+ */
460
+ usage?: Record<string, AgentCallUsage[]>;
295
461
  }
296
462
  /** A single explored path's terminal outcome. */
297
463
  interface AgentPathTerminal {
@@ -308,6 +474,8 @@ interface AgentPathTerminal {
308
474
  missingSrc?: string;
309
475
  /** For `error`: the failure value that errored the machine. */
310
476
  error?: unknown;
477
+ /** For `done`: the machine's output (absent when it has none). */
478
+ output?: unknown;
311
479
  }
312
480
  /** The report returned by {@link explorePaths}. */
313
481
  interface AgentPathReport {
@@ -321,14 +489,36 @@ interface AgentPathReport {
321
489
  unexplored: string[];
322
490
  /** Total paths explored. */
323
491
  pathsExplored: number;
324
- /** True when a cap (`maxPaths` or `maxNodes`) cut exploration short (report is partial). */
492
+ /** True when `maxPaths` or `maxNodes` cut exploration short (report is partial). */
325
493
  hitPathCap: boolean;
494
+ /**
495
+ * True when a cap or the `budget` cut exploration short: `hitPathCap`, or
496
+ * a `budget-exhausted` note in `unexplored`.
497
+ */
498
+ partial: boolean;
499
+ /**
500
+ * True when the report covers every path: not `partial`, every payload
501
+ * expanded, and every branch ended `done`, `idle`, or `error`.
502
+ */
503
+ complete: boolean;
326
504
  /**
327
505
  * Event types whose payload variants were not all tried: their schema has
328
506
  * a non-finite field or a product over the fill cap, and `payloads` has no
329
507
  * entry for them. Add a `payloads` entry for each to cover them.
330
508
  */
331
509
  unexpandedEvents: string[];
510
+ /**
511
+ * Event types offered only as the bare `{ type }` fallback at a snapshot
512
+ * where a transition for them may read the payload (a function transition,
513
+ * guard, `matches`, or context mapper): no `payloads` entry, no decision
514
+ * option, and no schema variant beyond `{ type }` (no schema, or one whose
515
+ * fields the fill cannot enumerate). A subset of `unexpandedEvents`: the
516
+ * payload-reading logic was exercised with no payload at all. Also lists
517
+ * `@agent.usage` when a text request settled while a usage transition was
518
+ * active and `usage` had no entry for its src. Data only; it does not
519
+ * change completeness.
520
+ */
521
+ vacuous: string[];
332
522
  }
333
523
  /**
334
524
  * Enumerates a machine's decision and external-event branches to a bounded
@@ -356,8 +546,9 @@ interface AgentPathReport {
356
546
  * payload table tractable.
357
547
  *
358
548
  * Combinatorics are bounded by `maxDepth` (default 8), `maxPaths` (default
359
- * 200), and `maxNodes` (default 100,000), the last two reported via
360
- * `hitPathCap`.
549
+ * 200), and `maxNodes` (default 100,000) per search, the last two reported
550
+ * via `hitPathCap`, and by `budget` across the whole call, child searches
551
+ * included. A cut-short report is `partial` and not `complete`.
361
552
  *
362
553
  * @example
363
554
  * ```ts
@@ -376,13 +567,21 @@ interface CanReachResult {
376
567
  witness?: ChosenEvent[];
377
568
  /**
378
569
  * False when the search left a branch it could not rule out unexplored: a
379
- * cap (`maxPaths` or `maxNodes`) cut it short, a path reached `maxDepth`, a
570
+ * cap (`maxPaths` or `maxNodes`) or the `budget` cut it short, a path reached `maxDepth`, a
380
571
  * branch stopped `needs-output` on a src with no `outputs` entry, or an event type
381
572
  * was not expanded to all its payload variants (`unexpandedEvents` in the
382
573
  * {@link explorePaths} report). `reachable: false` is a proof of
383
574
  * unreachability only when `complete` is true.
384
575
  */
385
576
  complete: boolean;
577
+ /**
578
+ * Why the search is not complete, present only when `complete` is false:
579
+ * the {@link explorePaths} report's `unexplored` notes (such as
580
+ * `needs-output: no \`outputs\` entry for src 'resume' at path []`), plus a
581
+ * `path-cap`, `unexpanded-events`, or `max-depth` note for the causes the
582
+ * report records elsewhere.
583
+ */
584
+ unexplored?: string[];
386
585
  }
387
586
  /** Thrown when a string reachability target is not a state in the machine. */
388
587
  declare class AgentUnknownStateError extends AgentError {
@@ -419,4 +618,4 @@ declare class AgentUnknownStateError extends AgentError {
419
618
  */
420
619
  declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
421
620
  //#endregion
422
- export { assertAgentMachine as _, AgentPathTerminal as a, lintAgentMachine as b, CanReachResult as c, ExploreSnapshot as d, LintAgentMachineOptions as f, SimulationTrailEntry as g, SimulationScript as h, AgentPathReport as i, CanReachTarget as l, SimulateAgentResult as m, AgentLintError as n, AgentUnknownStateError as o, SimulateAgentOptions as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, ExplorePathsOptions as u, canReach as v, simulateAgent as x, explorePaths as y };
621
+ export { textOutput as S, assertAgentMachine as _, AgentPathTerminal as a, lintAgentMachine as b, CanReachResult as c, ExploreSnapshot as d, LintAgentMachineOptions as f, SimulationTrailEntry as g, SimulationScript as h, AgentPathReport as i, CanReachTarget as l, SimulateAgentResult as m, AgentLintError as n, AgentUnknownStateError as o, SimulateAgentOptions as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, ExplorePathsOptions as u, canReach as v, simulateAgent as x, explorePaths as y };