@statelyai/agent 2.0.0-alpha.34 → 2.0.0-alpha.36

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 +124 -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-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
  13. package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
  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-BcQ-9NRT.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.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-BIKcbVXV.d.mts} +4 -4
  46. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  47. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
  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 +536 -67
  53. package/dist/testing.d.cts +197 -180
  54. package/dist/testing.d.mts +197 -180
  55. package/dist/testing.mjs +532 -67
  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-DoP0Oi84.d.mts} +1 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -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-Bink-Drw.cjs +2304 -0
  69. package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
  70. package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
  71. package/dist/verify-Dpz1u5Pe.mjs +2251 -0
  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 +311 -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 +136 -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 +54 -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 +516 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +487 -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 +81 -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 -190
  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.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,83 @@ 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. More precise and often cheaper
381
+ * than `"explore"` for authored child machines; `"explore"` remains the
382
+ * over-approximation for a child whose behavior you do not want to trust.
383
+ */
384
+ children?: "outputs" | "explore" | "coupled";
385
+ /**
386
+ * With `children: "explore"`: per child src, the event types that can
387
+ * reach the child at its waits (the ones the parent forwards with
388
+ * `sendTo`/`forwardTo`, or the host sends it directly). Unlisted types are
389
+ * never offered to the child. With `children: "coupled"`: only the types
390
+ * the host sends the child directly; the parent's sends are delivered as
391
+ * the parent makes them.
392
+ */
393
+ childEvents?: Record<string, string[]>;
394
+ /**
395
+ * The event types the host can send the machine at its waits (and, with
396
+ * `interleave: "pending"`, while work is pending). Default: every type the
397
+ * active states accept. List them when some accepted types only ever come
398
+ * from the machine's own children (a child's status events), so the search
399
+ * does not offer them as if the host sent them.
265
400
  */
266
- errors?: Record<string, unknown>;
401
+ hostEvents?: string[];
267
402
  /**
268
403
  * Payloads to try per event type at each branch point, given the settled
269
404
  * snapshot there. At a decision or an idle wait, an event type with an
@@ -292,6 +427,32 @@ interface ExplorePathsOptions {
292
427
  * Without it, every path is explored in full.
293
428
  */
294
429
  dedupeBy?: (snapshot: ExploreSnapshot) => string;
430
+ /**
431
+ * Armed timers: `after` delays, state and invoke `timeout`s, and delayed
432
+ * `enq.raise` events (`snapshot.timers` entries the machine delivers to
433
+ * itself). `"fire"` (default): each armed timer whose event the active
434
+ * states take is an event that may arrive, offered where host events are
435
+ * (at idle waits, and while work is pending under `interleave: "pending"`),
436
+ * in any order regardless of its delay. A fired timer records its event in
437
+ * the path, e.g. `{ type: 'xstate.after', delay: 1000, stateId: 'm.waiting' }`.
438
+ * `"ignore"`: timers never fire; a wait with an armed timer adds an
439
+ * `unexplored` note and lists the timer's event type in `unexpandedEvents`,
440
+ * so the report is not complete.
441
+ */
442
+ timers?: "fire" | "ignore";
443
+ /**
444
+ * Usage values to try per text-request src. When a request with an entry
445
+ * settles at the root and the active states take `@agent.usage`, the
446
+ * search delivers `{ type: '@agent.usage', kind: 'text', id, src, model,
447
+ * name?, usage }` to the root immediately before the request's completion,
448
+ * as a run does: once per listed value, each a fork that counts against
449
+ * `maxDepth` and records the usage event in the path. One value with one
450
+ * canned output is no fork, but its usage event is still recorded. No `budget`
451
+ * field is sent. A settling request with no entry while a usage transition
452
+ * is active lists `@agent.usage` in `vacuous`. Requests inside child
453
+ * machines and decisions deliver no usage.
454
+ */
455
+ usage?: Record<string, AgentCallUsage[]>;
295
456
  }
296
457
  /** A single explored path's terminal outcome. */
297
458
  interface AgentPathTerminal {
@@ -308,6 +469,8 @@ interface AgentPathTerminal {
308
469
  missingSrc?: string;
309
470
  /** For `error`: the failure value that errored the machine. */
310
471
  error?: unknown;
472
+ /** For `done`: the machine's output (absent when it has none). */
473
+ output?: unknown;
311
474
  }
312
475
  /** The report returned by {@link explorePaths}. */
313
476
  interface AgentPathReport {
@@ -321,14 +484,36 @@ interface AgentPathReport {
321
484
  unexplored: string[];
322
485
  /** Total paths explored. */
323
486
  pathsExplored: number;
324
- /** True when a cap (`maxPaths` or `maxNodes`) cut exploration short (report is partial). */
487
+ /** True when `maxPaths` or `maxNodes` cut exploration short (report is partial). */
325
488
  hitPathCap: boolean;
489
+ /**
490
+ * True when a cap or the `budget` cut exploration short: `hitPathCap`, or
491
+ * a `budget-exhausted` note in `unexplored`.
492
+ */
493
+ partial: boolean;
494
+ /**
495
+ * True when the report covers every path: not `partial`, every payload
496
+ * expanded, and every branch ended `done`, `idle`, or `error`.
497
+ */
498
+ complete: boolean;
326
499
  /**
327
500
  * Event types whose payload variants were not all tried: their schema has
328
501
  * a non-finite field or a product over the fill cap, and `payloads` has no
329
502
  * entry for them. Add a `payloads` entry for each to cover them.
330
503
  */
331
504
  unexpandedEvents: string[];
505
+ /**
506
+ * Event types offered only as the bare `{ type }` fallback at a snapshot
507
+ * where a transition for them may read the payload (a function transition,
508
+ * guard, `matches`, or context mapper): no `payloads` entry, no decision
509
+ * option, and no schema variant beyond `{ type }` (no schema, or one whose
510
+ * fields the fill cannot enumerate). A subset of `unexpandedEvents`: the
511
+ * payload-reading logic was exercised with no payload at all. Also lists
512
+ * `@agent.usage` when a text request settled while a usage transition was
513
+ * active and `usage` had no entry for its src. Data only; it does not
514
+ * change completeness.
515
+ */
516
+ vacuous: string[];
332
517
  }
333
518
  /**
334
519
  * Enumerates a machine's decision and external-event branches to a bounded
@@ -356,8 +541,9 @@ interface AgentPathReport {
356
541
  * payload table tractable.
357
542
  *
358
543
  * Combinatorics are bounded by `maxDepth` (default 8), `maxPaths` (default
359
- * 200), and `maxNodes` (default 100,000), the last two reported via
360
- * `hitPathCap`.
544
+ * 200), and `maxNodes` (default 100,000) per search, the last two reported
545
+ * via `hitPathCap`, and by `budget` across the whole call, child searches
546
+ * included. A cut-short report is `partial` and not `complete`.
361
547
  *
362
548
  * @example
363
549
  * ```ts
@@ -376,13 +562,21 @@ interface CanReachResult {
376
562
  witness?: ChosenEvent[];
377
563
  /**
378
564
  * 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
565
+ * cap (`maxPaths` or `maxNodes`) or the `budget` cut it short, a path reached `maxDepth`, a
380
566
  * branch stopped `needs-output` on a src with no `outputs` entry, or an event type
381
567
  * was not expanded to all its payload variants (`unexpandedEvents` in the
382
568
  * {@link explorePaths} report). `reachable: false` is a proof of
383
569
  * unreachability only when `complete` is true.
384
570
  */
385
571
  complete: boolean;
572
+ /**
573
+ * Why the search is not complete, present only when `complete` is false:
574
+ * the {@link explorePaths} report's `unexplored` notes (such as
575
+ * `needs-output: no \`outputs\` entry for src 'resume' at path []`), plus a
576
+ * `path-cap`, `unexpanded-events`, or `max-depth` note for the causes the
577
+ * report records elsewhere.
578
+ */
579
+ unexplored?: string[];
386
580
  }
387
581
  /** Thrown when a string reachability target is not a state in the machine. */
388
582
  declare class AgentUnknownStateError extends AgentError {
@@ -419,4 +613,4 @@ declare class AgentUnknownStateError extends AgentError {
419
613
  */
420
614
  declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
421
615
  //#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 };
616
+ 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.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,83 @@ 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. More precise and often cheaper
381
+ * than `"explore"` for authored child machines; `"explore"` remains the
382
+ * over-approximation for a child whose behavior you do not want to trust.
383
+ */
384
+ children?: "outputs" | "explore" | "coupled";
385
+ /**
386
+ * With `children: "explore"`: per child src, the event types that can
387
+ * reach the child at its waits (the ones the parent forwards with
388
+ * `sendTo`/`forwardTo`, or the host sends it directly). Unlisted types are
389
+ * never offered to the child. With `children: "coupled"`: only the types
390
+ * the host sends the child directly; the parent's sends are delivered as
391
+ * the parent makes them.
392
+ */
393
+ childEvents?: Record<string, string[]>;
394
+ /**
395
+ * The event types the host can send the machine at its waits (and, with
396
+ * `interleave: "pending"`, while work is pending). Default: every type the
397
+ * active states accept. List them when some accepted types only ever come
398
+ * from the machine's own children (a child's status events), so the search
399
+ * does not offer them as if the host sent them.
265
400
  */
266
- errors?: Record<string, unknown>;
401
+ hostEvents?: string[];
267
402
  /**
268
403
  * Payloads to try per event type at each branch point, given the settled
269
404
  * snapshot there. At a decision or an idle wait, an event type with an
@@ -292,6 +427,32 @@ interface ExplorePathsOptions {
292
427
  * Without it, every path is explored in full.
293
428
  */
294
429
  dedupeBy?: (snapshot: ExploreSnapshot) => string;
430
+ /**
431
+ * Armed timers: `after` delays, state and invoke `timeout`s, and delayed
432
+ * `enq.raise` events (`snapshot.timers` entries the machine delivers to
433
+ * itself). `"fire"` (default): each armed timer whose event the active
434
+ * states take is an event that may arrive, offered where host events are
435
+ * (at idle waits, and while work is pending under `interleave: "pending"`),
436
+ * in any order regardless of its delay. A fired timer records its event in
437
+ * the path, e.g. `{ type: 'xstate.after', delay: 1000, stateId: 'm.waiting' }`.
438
+ * `"ignore"`: timers never fire; a wait with an armed timer adds an
439
+ * `unexplored` note and lists the timer's event type in `unexpandedEvents`,
440
+ * so the report is not complete.
441
+ */
442
+ timers?: "fire" | "ignore";
443
+ /**
444
+ * Usage values to try per text-request src. When a request with an entry
445
+ * settles at the root and the active states take `@agent.usage`, the
446
+ * search delivers `{ type: '@agent.usage', kind: 'text', id, src, model,
447
+ * name?, usage }` to the root immediately before the request's completion,
448
+ * as a run does: once per listed value, each a fork that counts against
449
+ * `maxDepth` and records the usage event in the path. One value with one
450
+ * canned output is no fork, but its usage event is still recorded. No `budget`
451
+ * field is sent. A settling request with no entry while a usage transition
452
+ * is active lists `@agent.usage` in `vacuous`. Requests inside child
453
+ * machines and decisions deliver no usage.
454
+ */
455
+ usage?: Record<string, AgentCallUsage[]>;
295
456
  }
296
457
  /** A single explored path's terminal outcome. */
297
458
  interface AgentPathTerminal {
@@ -308,6 +469,8 @@ interface AgentPathTerminal {
308
469
  missingSrc?: string;
309
470
  /** For `error`: the failure value that errored the machine. */
310
471
  error?: unknown;
472
+ /** For `done`: the machine's output (absent when it has none). */
473
+ output?: unknown;
311
474
  }
312
475
  /** The report returned by {@link explorePaths}. */
313
476
  interface AgentPathReport {
@@ -321,14 +484,36 @@ interface AgentPathReport {
321
484
  unexplored: string[];
322
485
  /** Total paths explored. */
323
486
  pathsExplored: number;
324
- /** True when a cap (`maxPaths` or `maxNodes`) cut exploration short (report is partial). */
487
+ /** True when `maxPaths` or `maxNodes` cut exploration short (report is partial). */
325
488
  hitPathCap: boolean;
489
+ /**
490
+ * True when a cap or the `budget` cut exploration short: `hitPathCap`, or
491
+ * a `budget-exhausted` note in `unexplored`.
492
+ */
493
+ partial: boolean;
494
+ /**
495
+ * True when the report covers every path: not `partial`, every payload
496
+ * expanded, and every branch ended `done`, `idle`, or `error`.
497
+ */
498
+ complete: boolean;
326
499
  /**
327
500
  * Event types whose payload variants were not all tried: their schema has
328
501
  * a non-finite field or a product over the fill cap, and `payloads` has no
329
502
  * entry for them. Add a `payloads` entry for each to cover them.
330
503
  */
331
504
  unexpandedEvents: string[];
505
+ /**
506
+ * Event types offered only as the bare `{ type }` fallback at a snapshot
507
+ * where a transition for them may read the payload (a function transition,
508
+ * guard, `matches`, or context mapper): no `payloads` entry, no decision
509
+ * option, and no schema variant beyond `{ type }` (no schema, or one whose
510
+ * fields the fill cannot enumerate). A subset of `unexpandedEvents`: the
511
+ * payload-reading logic was exercised with no payload at all. Also lists
512
+ * `@agent.usage` when a text request settled while a usage transition was
513
+ * active and `usage` had no entry for its src. Data only; it does not
514
+ * change completeness.
515
+ */
516
+ vacuous: string[];
332
517
  }
333
518
  /**
334
519
  * Enumerates a machine's decision and external-event branches to a bounded
@@ -356,8 +541,9 @@ interface AgentPathReport {
356
541
  * payload table tractable.
357
542
  *
358
543
  * Combinatorics are bounded by `maxDepth` (default 8), `maxPaths` (default
359
- * 200), and `maxNodes` (default 100,000), the last two reported via
360
- * `hitPathCap`.
544
+ * 200), and `maxNodes` (default 100,000) per search, the last two reported
545
+ * via `hitPathCap`, and by `budget` across the whole call, child searches
546
+ * included. A cut-short report is `partial` and not `complete`.
361
547
  *
362
548
  * @example
363
549
  * ```ts
@@ -376,13 +562,21 @@ interface CanReachResult {
376
562
  witness?: ChosenEvent[];
377
563
  /**
378
564
  * 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
565
+ * cap (`maxPaths` or `maxNodes`) or the `budget` cut it short, a path reached `maxDepth`, a
380
566
  * branch stopped `needs-output` on a src with no `outputs` entry, or an event type
381
567
  * was not expanded to all its payload variants (`unexpandedEvents` in the
382
568
  * {@link explorePaths} report). `reachable: false` is a proof of
383
569
  * unreachability only when `complete` is true.
384
570
  */
385
571
  complete: boolean;
572
+ /**
573
+ * Why the search is not complete, present only when `complete` is false:
574
+ * the {@link explorePaths} report's `unexplored` notes (such as
575
+ * `needs-output: no \`outputs\` entry for src 'resume' at path []`), plus a
576
+ * `path-cap`, `unexpanded-events`, or `max-depth` note for the causes the
577
+ * report records elsewhere.
578
+ */
579
+ unexplored?: string[];
386
580
  }
387
581
  /** Thrown when a string reachability target is not a state in the machine. */
388
582
  declare class AgentUnknownStateError extends AgentError {
@@ -419,4 +613,4 @@ declare class AgentUnknownStateError extends AgentError {
419
613
  */
420
614
  declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
421
615
  //#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 };
616
+ 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 };