@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.
- package/CHANGELOG.md +138 -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-Ct_GZw_f.mjs → effects-BT_cSY0j.mjs} +1003 -109
- package/dist/{run-agent-s5D32w99.cjs → effects-DDseYtJk.cjs} +1037 -107
- 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-30mH2moE.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-DlPzBWj-.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-BaNyz6Q3.d.cts} +4 -4
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-C1CG_nfX.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- 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 +2493 -1502
- package/dist/testing.d.cts +360 -256
- package/dist/testing.d.mts +360 -256
- package/dist/testing.mjs +2489 -1503
- 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-Bm5nvpow.d.cts} +6 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-BnikdOca.d.mts} +6 -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-ChyX6jq0.mjs +2306 -0
- package/dist/verify-CwlombbC.cjs +2359 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-DJHfEfm6.d.cts} +213 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-i9Hiwc5g.d.mts} +213 -14
- 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 +312 -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 +207 -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 +56 -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 +518 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +492 -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 +84 -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 -192
- 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.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,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
|
-
|
|
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
|
|
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
|
|
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 {
|
|
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,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
|
-
|
|
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
|
|
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
|
|
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 };
|