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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.md +138 -0
  2. package/dist/act-B9hLQls6.mjs +19 -0
  3. package/dist/act-CrX0JwWY.cjs +42 -0
  4. package/dist/ai-sdk.cjs +63 -7
  5. package/dist/ai-sdk.d.cts +13 -3
  6. package/dist/ai-sdk.d.mts +13 -3
  7. package/dist/ai-sdk.mjs +63 -7
  8. package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
  9. package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
  10. package/dist/decision-object-B5zGSPFp.d.mts +15 -0
  11. package/dist/decision-object-DBcLWVvv.d.cts +15 -0
  12. package/dist/{run-agent-Ct_GZw_f.mjs → effects-BT_cSY0j.mjs} +1003 -109
  13. package/dist/{run-agent-s5D32w99.cjs → effects-DDseYtJk.cjs} +1037 -107
  14. package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
  15. package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
  16. package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
  17. package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
  18. package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
  19. package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
  20. package/dist/index.cjs +660 -286
  21. package/dist/index.d.cts +168 -9
  22. package/dist/index.d.mts +168 -9
  23. package/dist/index.mjs +639 -271
  24. package/dist/internal-C3Lqu538.d.cts +43 -0
  25. package/dist/internal-DUcdhk-i.d.mts +43 -0
  26. package/dist/log.cjs +2 -2
  27. package/dist/log.d.cts +1 -1
  28. package/dist/log.d.mts +1 -1
  29. package/dist/log.mjs +2 -2
  30. package/dist/machines.cjs +457 -41
  31. package/dist/machines.d.cts +114 -43
  32. package/dist/machines.d.mts +114 -43
  33. package/dist/machines.mjs +457 -42
  34. package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
  35. package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
  36. package/dist/openai.cjs +149 -36
  37. package/dist/openai.d.cts +28 -10
  38. package/dist/openai.d.mts +28 -10
  39. package/dist/openai.mjs +149 -36
  40. package/dist/otel.d.cts +1 -1
  41. package/dist/otel.d.mts +1 -1
  42. package/dist/{run-agent-BGdx5913.d.mts → run-agent-30mH2moE.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-DlPzBWj-.d.mts} +91 -9
  44. package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
  45. package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BaNyz6Q3.d.cts} +4 -4
  46. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-C1CG_nfX.d.mts} +4 -4
  47. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  48. package/dist/tanstack-ai.cjs +62 -4
  49. package/dist/tanstack-ai.d.cts +18 -6
  50. package/dist/tanstack-ai.d.mts +18 -6
  51. package/dist/tanstack-ai.mjs +62 -4
  52. package/dist/testing.cjs +2493 -1502
  53. package/dist/testing.d.cts +360 -256
  54. package/dist/testing.d.mts +360 -256
  55. package/dist/testing.mjs +2489 -1503
  56. package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
  57. package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
  58. package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
  59. package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
  60. package/dist/{usage-BDiJKyv9.d.cts → usage-Bm5nvpow.d.cts} +6 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-BnikdOca.d.mts} +6 -1
  62. package/dist/utils-7lSa4H-i.d.cts +403 -0
  63. package/dist/utils-CBbKw2fM.d.mts +403 -0
  64. package/dist/validate.cjs +44 -12
  65. package/dist/validate.d.cts +6 -6
  66. package/dist/validate.d.mts +6 -6
  67. package/dist/validate.mjs +44 -12
  68. package/dist/verify-ChyX6jq0.mjs +2306 -0
  69. package/dist/verify-CwlombbC.cjs +2359 -0
  70. package/dist/{verify-BQpE8hUz.d.cts → verify-DJHfEfm6.d.cts} +213 -14
  71. package/dist/{verify-CqeuEmIk.d.mts → verify-i9Hiwc5g.d.mts} +213 -14
  72. package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
  73. package/dist/with-model-calls-BkOwdroS.mjs +213 -0
  74. package/docs/act.md +102 -0
  75. package/docs/advanced.md +105 -0
  76. package/docs/any-stack.md +62 -0
  77. package/docs/choosing-a-run-mode.md +55 -0
  78. package/docs/debugging.md +29 -0
  79. package/docs/decisions.md +473 -0
  80. package/docs/environment-and-policy.md +188 -0
  81. package/docs/evals.md +509 -0
  82. package/docs/event-log.md +312 -0
  83. package/docs/from-a-loop.md +528 -0
  84. package/docs/generate-machines.md +110 -0
  85. package/docs/hosts.md +414 -0
  86. package/docs/human-in-the-loop.md +177 -0
  87. package/docs/index.md +48 -0
  88. package/docs/judgments.md +281 -0
  89. package/docs/langgraph-comparison.md +198 -0
  90. package/docs/machines-as-data.md +454 -0
  91. package/docs/machines-presets.md +198 -0
  92. package/docs/machines.md +497 -0
  93. package/docs/messages.md +67 -0
  94. package/docs/meta.json +52 -0
  95. package/docs/models-and-providers.md +268 -0
  96. package/docs/multi-agent.md +68 -0
  97. package/docs/observability.md +109 -0
  98. package/docs/patterns.md +31 -0
  99. package/docs/persistence.md +207 -0
  100. package/docs/quickstart.md +121 -0
  101. package/docs/roadmap.md +22 -0
  102. package/docs/scope.md +75 -0
  103. package/docs/statechart-policy-examples.md +69 -0
  104. package/docs/steps.md +56 -0
  105. package/docs/strangler-fig.md +323 -0
  106. package/docs/text-requests.md +250 -0
  107. package/docs/thinking-in-state-machines.md +324 -0
  108. package/docs/tools.md +249 -0
  109. package/docs/upgrading.md +37 -0
  110. package/docs/usage-and-budgets.md +518 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +492 -0
  113. package/docs/xstate-4-and-5-apps.md +161 -0
  114. package/llms.txt +53 -0
  115. package/package.json +10 -3
  116. package/readme.md +30 -15
  117. package/skills/add-evals/SKILL.md +3 -1
  118. package/skills/add-traces/SKILL.md +6 -1
  119. package/skills/build-machine/SKILL.md +84 -0
  120. package/skills/generate-machine/SKILL.md +1 -1
  121. package/skills/graph-engineering/SKILL.md +13 -3
  122. package/skills/improve-machine/SKILL.md +21 -2
  123. package/skills/loop-to-machine/SKILL.md +147 -192
  124. package/skills/loop-to-machine/reference.md +260 -0
  125. package/dist/utils-BnXdWih3.d.mts +0 -108
  126. package/dist/utils-ebVpCYoF.d.cts +0 -108
  127. package/dist/verify-Bpahmr34.mjs +0 -1241
  128. package/dist/verify-DCLZa9R0.cjs +0 -1288
  129. package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
  130. package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
package/dist/validate.mjs CHANGED
@@ -1,6 +1,7 @@
1
- import { D as GENERATE_TEXT_ACTOR, E as DECIDE_ACTOR, O as STREAM_TEXT_ACTOR } from "./event-log-C7jeH0y8.mjs";
2
- import { i as setupAgentFromConfig } from "./setup-agent-05uw4dPZ.mjs";
3
- import { a as explorePaths, s as lintAgentMachine } from "./verify-Bpahmr34.mjs";
1
+ import { A as STREAM_TEXT_ACTOR, E as ACT_ACTOR, O as DECIDE_ACTOR, k as GENERATE_TEXT_ACTOR } from "./event-log-DkVlk3Rh.mjs";
2
+ import { p as payloadNeedsFillModel } from "./decision-m5hGmHpF.mjs";
3
+ import { i as setupAgentFromConfig } from "./setup-agent-BDmNr6PC.mjs";
4
+ import { a as explorePaths, s as lintAgentMachine } from "./verify-ChyX6jq0.mjs";
4
5
  import Ajv2020 from "ajv/dist/2020.js";
5
6
  //#region schemas/agent-workflow.json
6
7
  var agent_workflow_default = {
@@ -403,6 +404,7 @@ function validateAgentConfig(config) {
403
404
  //#region src/validate/verify-config.ts
404
405
  const BUILTIN_SRCS = [
405
406
  DECIDE_ACTOR,
407
+ ACT_ACTOR,
406
408
  GENERATE_TEXT_ACTOR,
407
409
  STREAM_TEXT_ACTOR
408
410
  ];
@@ -417,8 +419,8 @@ const MAX_DETAIL_LINES = 10;
417
419
  * - `lower`: `setupAgent.fromConfig` (unresolved guards/actions, bad targets).
418
420
  * - `lint`: `lintAgentMachine` (errors fail; warnings fail with `lint.warnings`).
419
421
  * - `explore`: `explorePaths` from each `explore.inputs` entry; every terminal
420
- * must be one of `explore.terminals`, no cap (`maxPaths`, `maxNodes`) may cut
421
- * it short, every event's payloads must be tried (`unexpandedEvents`), and
422
+ * must be one of `explore.terminals`, no cap (`maxPaths`, `maxNodes`) or
423
+ * `budget` may cut it short, every event's payloads must be tried (`unexpandedEvents`), and
422
424
  * every reached text request or invoke needs an `explore.outputs` entry.
423
425
  *
424
426
  * @example
@@ -459,7 +461,7 @@ async function verifyAgentConfig(config, options) {
459
461
  record("lower", [errorMessage(error)]);
460
462
  return fail({ config: typed });
461
463
  }
462
- record("lower", []);
464
+ if (!record("lower", checkFillModels(typed, machine))) return fail({ config: typed });
463
465
  const diagnostics = lintAgentMachine(machine).map((d) => ({
464
466
  failing: d.severity === "error" || options.lint?.warnings === true,
465
467
  line: `${d.severity} ${d.code} at '${d.path}': ${d.message}`
@@ -479,6 +481,32 @@ async function verifyAgentConfig(config, options) {
479
481
  machine
480
482
  };
481
483
  }
484
+ /**
485
+ * An `agent.decide` invoke whose strategy is `'pick-then-fill'` (explicit, or
486
+ * `'auto'` with a `fillModel`) needs a `fillModel` when any literal
487
+ * candidate event has open payload fields. Omitted `allowedEvents` is resolved
488
+ * from the lowered state's own and ancestor event handlers.
489
+ */
490
+ function checkFillModels(config, machine) {
491
+ const schemas = config.schemas?.events ?? {};
492
+ const problems = [];
493
+ for (const { path, state } of walkStates(config.states)) for (const invoke of nodes(state.invoke)) {
494
+ if (invoke.src !== "agent.decide" || !isPlainObject(invoke.input)) continue;
495
+ const input = invoke.input;
496
+ if (input.strategy !== "pick-then-fill" || input.fillModel !== void 0) continue;
497
+ if (input.payloads !== void 0) continue;
498
+ const open = (Array.isArray(input.allowedEvents) ? input.allowedEvents : loweredEventTypes(machine, path)).filter((type) => typeof type === "string" && payloadNeedsFillModel(schemas[type]));
499
+ if (open.length) problems.push(`state '${path}': agent.decide uses strategy 'pick-then-fill' but ${list(open)} has open payload fields and no fillModel is set`);
500
+ }
501
+ return problems;
502
+ }
503
+ function loweredEventTypes(machine, path) {
504
+ let node = machine.root;
505
+ for (const key of path.split(".")) node = node?.states[key];
506
+ const types = /* @__PURE__ */ new Set();
507
+ for (let current = node; current; current = current.parent) for (const [type, transitions] of current.transitions) if (!transitions.every((t) => t.meta?.actor === "human")) types.add(type);
508
+ return [...types];
509
+ }
482
510
  /** A config's `T | T[]` field as a list of objects. */
483
511
  const nodes = (value) => (value === void 0 ? [] : Array.isArray(value) ? value : [value]).filter((node) => !!node && typeof node === "object");
484
512
  const hasTemplate = (value) => typeof value === "string" && value.includes("{{");
@@ -551,18 +579,21 @@ function checkVocabulary(config, allow) {
551
579
  }
552
580
  if (!BUILTIN_SRCS.includes(src)) continue;
553
581
  const input = invoke.input;
554
- if ((allow.models || src === "agent.decide" && allow.events) && !isPlainObject(input)) {
582
+ if ((allow.models || (src === "agent.decide" || src === "agent.act") && allow.events) && !isPlainObject(input)) {
555
583
  problems.push(`state '${path}': '${src}' input must be a literal object`);
556
584
  continue;
557
585
  }
558
586
  checkModel(`state '${path}': '${src}'`, input?.model);
559
- if (src !== "agent.decide" || !allow.events) continue;
560
- const allowedEvents = input.allowedEvents;
587
+ const fillModel = input?.fillModel;
588
+ if (fillModel !== void 0) checkModel(`state '${path}': '${src}' fillModel`, fillModel);
589
+ if (src !== "agent.decide" && src !== "agent.act" || !allow.events) continue;
590
+ const allowedEvents = input?.allowedEvents;
591
+ if (src === "agent.act" && allowedEvents === void 0) continue;
561
592
  if (!Array.isArray(allowedEvents) || allowedEvents.length === 0) {
562
- problems.push(`state '${path}': agent.decide needs a literal, non-empty allowedEvents list; allowed: ${list(allow.events)}`);
593
+ problems.push(`state '${path}': ${src} needs a literal, non-empty allowedEvents list; allowed: ${list(allow.events)}`);
563
594
  continue;
564
595
  }
565
- for (const type of allowedEvents) if (typeof type !== "string" || !allow.events.includes(type)) problems.push(`state '${path}': agent.decide allowedEvents entry '${String(type)}' is not allowed; allowed: ${list(allow.events)}`);
596
+ for (const type of allowedEvents) if (typeof type !== "string" || !allow.events.includes(type)) problems.push(`state '${path}': ${src} allowedEvents entry '${String(type)}' is not allowed; allowed: ${list(allow.events)}`);
566
597
  }
567
598
  const actionsAt = [["entry", state.entry], ["exit", state.exit]];
568
599
  for (const transition of transitionsOf(state)) {
@@ -596,7 +627,7 @@ async function checkExplore(machine, options) {
596
627
  }
597
628
  for (const terminal of report.terminals) {
598
629
  if (allowed.includes(terminal.status)) continue;
599
- const trail = `path [${terminal.path.map((event) => event.type).join(", ")}]`;
630
+ const trail = `path [${terminal.path.map((event) => typeof event.actorId === "string" ? `${event.type}(${event.actorId})` : event.type).join(", ")}]`;
600
631
  const state = JSON.stringify(terminal.state);
601
632
  switch (terminal.status) {
602
633
  case "max-depth":
@@ -612,6 +643,7 @@ async function checkExplore(machine, options) {
612
643
  }
613
644
  }
614
645
  if (report.hitPathCap) problems.add(`${at}a cap (maxPaths ${options.maxPaths ?? 200} or maxNodes ${options.maxNodes ?? 1e5}) cut exploration short; the workflow branches too much to verify`);
646
+ for (const note of report.unexplored) if (note.startsWith("budget-exhausted")) problems.add(`${at}the explore budget ran out (${note}); exploration is incomplete, so raise explore.budget or narrow the workflow`);
615
647
  if (report.unexpandedEvents.length > 0) problems.add(`${at}explore did not try every payload of: ${report.unexpandedEvents.join(", ")}; add explore.payloads entries for them`);
616
648
  }
617
649
  return [...problems];