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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
  3. package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
  4. package/dist/ai-sdk.cjs +4 -4
  5. package/dist/ai-sdk.d.cts +2 -3
  6. package/dist/ai-sdk.d.mts +2 -3
  7. package/dist/ai-sdk.mjs +4 -4
  8. package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
  9. package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
  10. package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
  11. package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
  12. package/dist/effects-B9IvUPVh.mjs +23 -0
  13. package/dist/effects-DrWcUGgc.cjs +34 -0
  14. package/dist/evals.cjs +810 -0
  15. package/dist/evals.d.cts +595 -0
  16. package/dist/evals.d.mts +595 -0
  17. package/dist/evals.mjs +801 -0
  18. package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
  19. package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
  20. package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
  21. package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
  22. package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
  23. package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
  24. package/dist/index.cjs +142 -97
  25. package/dist/index.d.cts +97 -141
  26. package/dist/index.d.mts +97 -141
  27. package/dist/index.mjs +123 -74
  28. package/dist/internal-BzlpzSux.d.cts +14 -0
  29. package/dist/internal-BzlpzSux.d.mts +14 -0
  30. package/dist/log.cjs +2 -3
  31. package/dist/log.d.cts +2 -2
  32. package/dist/log.d.mts +2 -2
  33. package/dist/log.mjs +3 -3
  34. package/dist/machine-input-0YTPcnCm.mjs +27 -0
  35. package/dist/machine-input-DU3owLUr.cjs +32 -0
  36. package/dist/machines.cjs +1 -719
  37. package/dist/machines.d.cts +2 -424
  38. package/dist/machines.d.mts +2 -424
  39. package/dist/machines.mjs +2 -709
  40. package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
  41. package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
  42. package/dist/openai.cjs +3 -3
  43. package/dist/openai.d.cts +2 -3
  44. package/dist/openai.d.mts +2 -3
  45. package/dist/openai.mjs +3 -3
  46. package/dist/otel.d.cts +1 -1
  47. package/dist/otel.d.mts +1 -1
  48. package/dist/policy.cjs +77 -0
  49. package/dist/policy.d.cts +143 -0
  50. package/dist/policy.d.mts +143 -0
  51. package/dist/policy.mjs +75 -0
  52. package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-BO9RSb7i.d.cts} +33 -40
  53. package/dist/{run-agent-30mH2moE.d.cts → run-agent-BxkeuAYR.d.mts} +33 -40
  54. package/dist/{effects-DDseYtJk.cjs → run-agent-COdR9FpM.cjs} +175 -228
  55. package/dist/{effects-BT_cSY0j.mjs → run-agent-D3gW9wfd.mjs} +176 -211
  56. package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
  57. package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
  58. package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
  59. package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
  60. package/dist/tanstack-ai.cjs +4 -4
  61. package/dist/tanstack-ai.d.cts +2 -3
  62. package/dist/tanstack-ai.d.mts +2 -3
  63. package/dist/tanstack-ai.mjs +4 -4
  64. package/dist/testing.cjs +122 -996
  65. package/dist/testing.d.cts +36 -695
  66. package/dist/testing.d.mts +36 -695
  67. package/dist/testing.mjs +112 -977
  68. package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
  69. package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
  70. package/dist/trajectory-BFjXaooB.d.cts +96 -0
  71. package/dist/trajectory-BFjXaooB.d.mts +96 -0
  72. package/dist/trajectory-BUXj_1Ue.mjs +152 -0
  73. package/dist/trajectory-CoZSv4wF.cjs +157 -0
  74. package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
  75. package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
  76. package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
  77. package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
  78. package/dist/validate.cjs +4 -4
  79. package/dist/validate.d.cts +2 -2
  80. package/dist/validate.d.mts +2 -2
  81. package/dist/validate.mjs +4 -4
  82. package/dist/{verify-DJHfEfm6.d.cts → verify-CIu4mqIZ.d.mts} +56 -6
  83. package/dist/{verify-i9Hiwc5g.d.mts → verify-CTHlmBbh.d.cts} +56 -6
  84. package/dist/{verify-ChyX6jq0.mjs → verify-Cacz6XSk.mjs} +170 -46
  85. package/dist/{verify-CwlombbC.cjs → verify-D8UDqU4l.cjs} +170 -46
  86. package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
  87. package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
  88. package/docs/advanced.md +5 -5
  89. package/docs/choosing-a-run-mode.md +7 -7
  90. package/docs/debugging.md +6 -8
  91. package/docs/decisions.md +5 -4
  92. package/docs/environment-and-policy.md +1 -1
  93. package/docs/evals.md +57 -43
  94. package/docs/event-log.md +13 -15
  95. package/docs/from-a-loop.md +3 -3
  96. package/docs/generate-machines.md +4 -4
  97. package/docs/hosts.md +25 -30
  98. package/docs/human-in-the-loop.md +5 -8
  99. package/docs/index.md +4 -4
  100. package/docs/judgments.md +5 -7
  101. package/docs/langgraph-comparison.md +6 -6
  102. package/docs/machines-as-data.md +7 -12
  103. package/docs/machines-presets.md +17 -120
  104. package/docs/machines.md +13 -13
  105. package/docs/models-and-providers.md +19 -25
  106. package/docs/multi-agent.md +1 -1
  107. package/docs/observability.md +6 -8
  108. package/docs/persistence.md +10 -20
  109. package/docs/quickstart.md +3 -3
  110. package/docs/statechart-policy-examples.md +1 -1
  111. package/docs/steps.md +5 -6
  112. package/docs/strangler-fig.md +105 -33
  113. package/docs/text-requests.md +10 -12
  114. package/docs/thinking-in-state-machines.md +8 -8
  115. package/docs/tools.md +10 -12
  116. package/docs/upgrading.md +1 -1
  117. package/docs/usage-and-budgets.md +51 -56
  118. package/docs/validate-and-repair.md +9 -14
  119. package/docs/verify.md +54 -7
  120. package/docs/xstate-4-and-5-apps.md +19 -28
  121. package/llms.txt +1 -1
  122. package/package.json +31 -6
  123. package/readme.md +32 -24
  124. package/dist/internal-C3Lqu538.d.cts +0 -43
  125. package/dist/internal-DUcdhk-i.d.mts +0 -43
  126. package/dist/types-DQUOOaZO.d.cts +0 -238
  127. package/dist/types-DQUOOaZO.d.mts +0 -238
  128. package/skills/add-evals/SKILL.md +0 -152
  129. package/skills/add-traces/SKILL.md +0 -152
  130. package/skills/build-machine/SKILL.md +0 -84
  131. package/skills/generate-machine/SKILL.md +0 -335
  132. package/skills/graph-engineering/SKILL.md +0 -43
  133. package/skills/improve-machine/SKILL.md +0 -261
  134. package/skills/improve-machine/reference.md +0 -101
  135. package/skills/loop-to-machine/SKILL.md +0 -205
  136. package/skills/loop-to-machine/policy.md +0 -154
  137. package/skills/loop-to-machine/reference.md +0 -260
@@ -1,6 +1,5 @@
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
- import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
1
+ import { at as AgentError, lt as AgentMessage, p as AgentTextResult, t as AgentCallUsage, yt as ChosenEvent } from "./text-logic-x17uLBwA.mjs";
2
+ import { AnyMachineSnapshot, AnyStateMachine, EventObject } from "xstate";
4
3
  //#region src/verify.d.ts
5
4
  /** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
6
5
  type AgentLintSeverity = "error" | "warning";
@@ -170,6 +169,11 @@ interface SimulationTrailEntry {
170
169
  }
171
170
  /** Options for {@link simulateAgent}. */
172
171
  interface SimulateAgentOptions {
172
+ /**
173
+ * The machine input. A machine with a declared input schema validates it as
174
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
175
+ * the parsed value (defaults filled) seeds the search.
176
+ */
173
177
  input?: unknown;
174
178
  script: SimulationScript;
175
179
  /** Max steps before returning `'exhausted'`. Default 100. */
@@ -244,9 +248,46 @@ declare function textOutput<TResult>(result: TResult, options?: {
244
248
  * own `xstate`, which can be another version than the one this package uses.
245
249
  */
246
250
  type ExploreSnapshot = AnyMachineSnapshot;
247
- /** What {@link canReach} looks for: a state id or path, or a snapshot predicate. */
248
- type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean);
251
+ /**
252
+ * One macrostep on an explored path, recorded with `steps: true` or for an
253
+ * ordering target: every event the machine processed, not only branch points.
254
+ */
255
+ interface ExploreStep {
256
+ /**
257
+ * The event this macrostep processed: a host event, a fork, a canned
258
+ * output settling (`xstate.done.actor`), or `xstate.init` for the start.
259
+ */
260
+ event: EventObject;
261
+ /** The state value after the step. */
262
+ state: unknown;
263
+ /** Srcs of the invokes and spawned actors that started in this step. */
264
+ started: string[];
265
+ /** Srcs of the actors that settled (done or error) in this step. */
266
+ settled: string[];
267
+ }
268
+ /**
269
+ * An ordering target for {@link canReach}: a step matching `reach` after a
270
+ * step matching `after`. `reachable: false` with `complete: true` proves
271
+ * `reach` never happens after `after`.
272
+ */
273
+ interface CanReachOrdering {
274
+ /** The trigger: an event type, or a step predicate. */
275
+ after: string | ((step: ExploreStep) => boolean);
276
+ /**
277
+ * Checked on the first `after` step and every step after it. On the
278
+ * trigger's own step, `started`, `settled` and `state` are its effects;
279
+ * `event` is the trigger itself.
280
+ */
281
+ reach: (step: ExploreStep) => boolean;
282
+ }
283
+ /** What {@link canReach} looks for: a state id or path, a snapshot predicate, or an ordering. */
284
+ type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean) | CanReachOrdering;
249
285
  interface ExplorePathsOptions {
286
+ /**
287
+ * The machine input. A machine with a declared input schema validates it as
288
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
289
+ * the parsed value (defaults filled) seeds the search.
290
+ */
250
291
  input?: unknown;
251
292
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
252
293
  maxDepth?: number;
@@ -458,6 +499,13 @@ interface ExplorePathsOptions {
458
499
  * no usage.
459
500
  */
460
501
  usage?: Record<string, AgentCallUsage[]>;
502
+ /**
503
+ * Record every macrostep of each path in its terminal's `steps`, with the
504
+ * srcs each step started and settled. `path` lists only branch points, so
505
+ * an invoke with one canned output never appears there. Off by default:
506
+ * it costs memory per step of every path.
507
+ */
508
+ steps?: boolean;
461
509
  }
462
510
  /** A single explored path's terminal outcome. */
463
511
  interface AgentPathTerminal {
@@ -476,6 +524,8 @@ interface AgentPathTerminal {
476
524
  error?: unknown;
477
525
  /** For `done`: the machine's output (absent when it has none). */
478
526
  output?: unknown;
527
+ /** With `steps: true`: every macrostep on this path, from the start. */
528
+ steps?: ExploreStep[];
479
529
  }
480
530
  /** The report returned by {@link explorePaths}. */
481
531
  interface AgentPathReport {
@@ -618,4 +668,4 @@ declare class AgentUnknownStateError extends AgentError {
618
668
  */
619
669
  declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
620
670
  //#endregion
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 };
671
+ export { simulateAgent as C, lintAgentMachine as S, SimulationScript as _, AgentPathTerminal as a, canReach as b, CanReachOrdering as c, ExplorePathsOptions as d, ExploreSnapshot as f, SimulateAgentResult as g, SimulateAgentOptions as h, AgentPathReport as i, CanReachResult as l, LintAgentMachineOptions as m, AgentLintError as n, AgentUnknownStateError as o, ExploreStep as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, CanReachTarget as u, SimulationTrailEntry as v, textOutput as w, explorePaths as x, assertAgentMachine as y };
@@ -1,6 +1,5 @@
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
- import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
1
+ import { at as AgentError, lt as AgentMessage, p as AgentTextResult, t as AgentCallUsage, yt as ChosenEvent } from "./text-logic-x17uLBwA.cjs";
2
+ import { AnyMachineSnapshot, AnyStateMachine, EventObject } from "xstate";
4
3
  //#region src/verify.d.ts
5
4
  /** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
6
5
  type AgentLintSeverity = "error" | "warning";
@@ -170,6 +169,11 @@ interface SimulationTrailEntry {
170
169
  }
171
170
  /** Options for {@link simulateAgent}. */
172
171
  interface SimulateAgentOptions {
172
+ /**
173
+ * The machine input. A machine with a declared input schema validates it as
174
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
175
+ * the parsed value (defaults filled) seeds the search.
176
+ */
173
177
  input?: unknown;
174
178
  script: SimulationScript;
175
179
  /** Max steps before returning `'exhausted'`. Default 100. */
@@ -244,9 +248,46 @@ declare function textOutput<TResult>(result: TResult, options?: {
244
248
  * own `xstate`, which can be another version than the one this package uses.
245
249
  */
246
250
  type ExploreSnapshot = AnyMachineSnapshot;
247
- /** What {@link canReach} looks for: a state id or path, or a snapshot predicate. */
248
- type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean);
251
+ /**
252
+ * One macrostep on an explored path, recorded with `steps: true` or for an
253
+ * ordering target: every event the machine processed, not only branch points.
254
+ */
255
+ interface ExploreStep {
256
+ /**
257
+ * The event this macrostep processed: a host event, a fork, a canned
258
+ * output settling (`xstate.done.actor`), or `xstate.init` for the start.
259
+ */
260
+ event: EventObject;
261
+ /** The state value after the step. */
262
+ state: unknown;
263
+ /** Srcs of the invokes and spawned actors that started in this step. */
264
+ started: string[];
265
+ /** Srcs of the actors that settled (done or error) in this step. */
266
+ settled: string[];
267
+ }
268
+ /**
269
+ * An ordering target for {@link canReach}: a step matching `reach` after a
270
+ * step matching `after`. `reachable: false` with `complete: true` proves
271
+ * `reach` never happens after `after`.
272
+ */
273
+ interface CanReachOrdering {
274
+ /** The trigger: an event type, or a step predicate. */
275
+ after: string | ((step: ExploreStep) => boolean);
276
+ /**
277
+ * Checked on the first `after` step and every step after it. On the
278
+ * trigger's own step, `started`, `settled` and `state` are its effects;
279
+ * `event` is the trigger itself.
280
+ */
281
+ reach: (step: ExploreStep) => boolean;
282
+ }
283
+ /** What {@link canReach} looks for: a state id or path, a snapshot predicate, or an ordering. */
284
+ type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean) | CanReachOrdering;
249
285
  interface ExplorePathsOptions {
286
+ /**
287
+ * The machine input. A machine with a declared input schema validates it as
288
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
289
+ * the parsed value (defaults filled) seeds the search.
290
+ */
250
291
  input?: unknown;
251
292
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
252
293
  maxDepth?: number;
@@ -458,6 +499,13 @@ interface ExplorePathsOptions {
458
499
  * no usage.
459
500
  */
460
501
  usage?: Record<string, AgentCallUsage[]>;
502
+ /**
503
+ * Record every macrostep of each path in its terminal's `steps`, with the
504
+ * srcs each step started and settled. `path` lists only branch points, so
505
+ * an invoke with one canned output never appears there. Off by default:
506
+ * it costs memory per step of every path.
507
+ */
508
+ steps?: boolean;
461
509
  }
462
510
  /** A single explored path's terminal outcome. */
463
511
  interface AgentPathTerminal {
@@ -476,6 +524,8 @@ interface AgentPathTerminal {
476
524
  error?: unknown;
477
525
  /** For `done`: the machine's output (absent when it has none). */
478
526
  output?: unknown;
527
+ /** With `steps: true`: every macrostep on this path, from the start. */
528
+ steps?: ExploreStep[];
479
529
  }
480
530
  /** The report returned by {@link explorePaths}. */
481
531
  interface AgentPathReport {
@@ -618,4 +668,4 @@ declare class AgentUnknownStateError extends AgentError {
618
668
  */
619
669
  declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
620
670
  //#endregion
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 };
671
+ export { simulateAgent as C, lintAgentMachine as S, SimulationScript as _, AgentPathTerminal as a, canReach as b, CanReachOrdering as c, ExplorePathsOptions as d, ExploreSnapshot as f, SimulateAgentResult as g, SimulateAgentOptions as h, AgentPathReport as i, CanReachResult as l, LintAgentMachineOptions as m, AgentLintError as n, AgentUnknownStateError as o, ExploreStep as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, CanReachTarget as u, SimulationTrailEntry as v, textOutput as w, explorePaths as x, assertAgentMachine as y };