@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.
- package/CHANGELOG.md +124 -0
- package/dist/act-B9hLQls6.mjs +19 -0
- package/dist/act-CrX0JwWY.cjs +42 -0
- package/dist/ai-sdk.cjs +63 -7
- package/dist/ai-sdk.d.cts +13 -3
- package/dist/ai-sdk.d.mts +13 -3
- package/dist/ai-sdk.mjs +63 -7
- package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
- package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
- package/dist/decision-object-B5zGSPFp.d.mts +15 -0
- package/dist/decision-object-DBcLWVvv.d.cts +15 -0
- package/dist/{run-agent-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
- package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
- package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
- package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
- package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
- package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
- package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
- package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
- package/dist/index.cjs +660 -286
- package/dist/index.d.cts +168 -9
- package/dist/index.d.mts +168 -9
- package/dist/index.mjs +639 -271
- package/dist/internal-C3Lqu538.d.cts +43 -0
- package/dist/internal-DUcdhk-i.d.mts +43 -0
- package/dist/log.cjs +2 -2
- package/dist/log.d.cts +1 -1
- package/dist/log.d.mts +1 -1
- package/dist/log.mjs +2 -2
- package/dist/machines.cjs +457 -41
- package/dist/machines.d.cts +114 -43
- package/dist/machines.d.mts +114 -43
- package/dist/machines.mjs +457 -42
- package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
- package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
- package/dist/openai.cjs +149 -36
- package/dist/openai.d.cts +28 -10
- package/dist/openai.d.mts +28 -10
- package/dist/openai.mjs +149 -36
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-BGdx5913.d.mts → run-agent-BcQ-9NRT.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.d.mts} +91 -9
- package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
- package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BIKcbVXV.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
- package/dist/tanstack-ai.cjs +62 -4
- package/dist/tanstack-ai.d.cts +18 -6
- package/dist/tanstack-ai.d.mts +18 -6
- package/dist/tanstack-ai.mjs +62 -4
- package/dist/testing.cjs +536 -67
- package/dist/testing.d.cts +197 -180
- package/dist/testing.d.mts +197 -180
- package/dist/testing.mjs +532 -67
- package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
- package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
- package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
- package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
- package/dist/{usage-BDiJKyv9.d.cts → usage-DoP0Oi84.d.mts} +1 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -1
- package/dist/utils-7lSa4H-i.d.cts +403 -0
- package/dist/utils-CBbKw2fM.d.mts +403 -0
- package/dist/validate.cjs +44 -12
- package/dist/validate.d.cts +6 -6
- package/dist/validate.d.mts +6 -6
- package/dist/validate.mjs +44 -12
- package/dist/verify-Bink-Drw.cjs +2304 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
- package/dist/verify-Dpz1u5Pe.mjs +2251 -0
- package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
- package/dist/with-model-calls-BkOwdroS.mjs +213 -0
- package/docs/act.md +102 -0
- package/docs/advanced.md +105 -0
- package/docs/any-stack.md +62 -0
- package/docs/choosing-a-run-mode.md +55 -0
- package/docs/debugging.md +29 -0
- package/docs/decisions.md +473 -0
- package/docs/environment-and-policy.md +188 -0
- package/docs/evals.md +509 -0
- package/docs/event-log.md +311 -0
- package/docs/from-a-loop.md +528 -0
- package/docs/generate-machines.md +110 -0
- package/docs/hosts.md +414 -0
- package/docs/human-in-the-loop.md +177 -0
- package/docs/index.md +48 -0
- package/docs/judgments.md +281 -0
- package/docs/langgraph-comparison.md +198 -0
- package/docs/machines-as-data.md +454 -0
- package/docs/machines-presets.md +198 -0
- package/docs/machines.md +497 -0
- package/docs/messages.md +67 -0
- package/docs/meta.json +52 -0
- package/docs/models-and-providers.md +268 -0
- package/docs/multi-agent.md +68 -0
- package/docs/observability.md +109 -0
- package/docs/patterns.md +31 -0
- package/docs/persistence.md +136 -0
- package/docs/quickstart.md +121 -0
- package/docs/roadmap.md +22 -0
- package/docs/scope.md +75 -0
- package/docs/statechart-policy-examples.md +69 -0
- package/docs/steps.md +54 -0
- package/docs/strangler-fig.md +323 -0
- package/docs/text-requests.md +250 -0
- package/docs/thinking-in-state-machines.md +324 -0
- package/docs/tools.md +249 -0
- package/docs/upgrading.md +37 -0
- package/docs/usage-and-budgets.md +516 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +487 -0
- package/docs/xstate-4-and-5-apps.md +161 -0
- package/llms.txt +53 -0
- package/package.json +10 -3
- package/readme.md +30 -15
- package/skills/add-evals/SKILL.md +3 -1
- package/skills/add-traces/SKILL.md +6 -1
- package/skills/build-machine/SKILL.md +81 -0
- package/skills/generate-machine/SKILL.md +1 -1
- package/skills/graph-engineering/SKILL.md +13 -3
- package/skills/improve-machine/SKILL.md +21 -2
- package/skills/loop-to-machine/SKILL.md +147 -190
- package/skills/loop-to-machine/reference.md +260 -0
- package/dist/utils-BnXdWih3.d.mts +0 -108
- package/dist/utils-ebVpCYoF.d.cts +0 -108
- package/dist/verify-Bpahmr34.mjs +0 -1241
- package/dist/verify-DCLZa9R0.cjs +0 -1288
- package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
- package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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: [] }`)
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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 {
|
|
2
|
-
import {
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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: [] }`)
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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 };
|