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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.md +111 -0
  2. package/dist/act-B9hLQls6.mjs +19 -0
  3. package/dist/act-CrX0JwWY.cjs +42 -0
  4. package/dist/ai-sdk.cjs +63 -7
  5. package/dist/ai-sdk.d.cts +13 -3
  6. package/dist/ai-sdk.d.mts +13 -3
  7. package/dist/ai-sdk.mjs +63 -7
  8. package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
  9. package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
  10. package/dist/decision-object-B5zGSPFp.d.mts +15 -0
  11. package/dist/decision-object-DBcLWVvv.d.cts +15 -0
  12. package/dist/{run-agent-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
  13. package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
  14. package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
  15. package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
  16. package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
  17. package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
  18. package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
  19. package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
  20. package/dist/index.cjs +660 -286
  21. package/dist/index.d.cts +168 -9
  22. package/dist/index.d.mts +168 -9
  23. package/dist/index.mjs +639 -271
  24. package/dist/internal-C3Lqu538.d.cts +43 -0
  25. package/dist/internal-DUcdhk-i.d.mts +43 -0
  26. package/dist/log.cjs +2 -2
  27. package/dist/log.d.cts +1 -1
  28. package/dist/log.d.mts +1 -1
  29. package/dist/log.mjs +2 -2
  30. package/dist/machines.cjs +457 -41
  31. package/dist/machines.d.cts +114 -43
  32. package/dist/machines.d.mts +114 -43
  33. package/dist/machines.mjs +457 -42
  34. package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
  35. package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
  36. package/dist/openai.cjs +149 -36
  37. package/dist/openai.d.cts +28 -10
  38. package/dist/openai.d.mts +28 -10
  39. package/dist/openai.mjs +149 -36
  40. package/dist/otel.d.cts +1 -1
  41. package/dist/otel.d.mts +1 -1
  42. package/dist/{run-agent-BGdx5913.d.mts → run-agent-BcQ-9NRT.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.d.mts} +91 -9
  44. package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
  45. package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BIKcbVXV.d.mts} +4 -4
  46. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  47. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
  48. package/dist/tanstack-ai.cjs +62 -4
  49. package/dist/tanstack-ai.d.cts +18 -6
  50. package/dist/tanstack-ai.d.mts +18 -6
  51. package/dist/tanstack-ai.mjs +62 -4
  52. package/dist/testing.cjs +399 -20
  53. package/dist/testing.d.cts +196 -255
  54. package/dist/testing.d.mts +196 -255
  55. package/dist/testing.mjs +395 -20
  56. package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
  57. package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
  58. package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
  59. package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
  60. package/dist/{usage-BDiJKyv9.d.cts → usage-DoP0Oi84.d.mts} +1 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -1
  62. package/dist/utils-7lSa4H-i.d.cts +403 -0
  63. package/dist/utils-CBbKw2fM.d.mts +403 -0
  64. package/dist/validate.cjs +44 -12
  65. package/dist/validate.d.cts +6 -6
  66. package/dist/validate.d.mts +6 -6
  67. package/dist/validate.mjs +44 -12
  68. package/dist/verify-Bink-Drw.cjs +2304 -0
  69. package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
  70. package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
  71. package/dist/verify-Dpz1u5Pe.mjs +2251 -0
  72. package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
  73. package/dist/with-model-calls-BkOwdroS.mjs +213 -0
  74. package/docs/act.md +102 -0
  75. package/docs/advanced.md +105 -0
  76. package/docs/any-stack.md +62 -0
  77. package/docs/choosing-a-run-mode.md +55 -0
  78. package/docs/debugging.md +29 -0
  79. package/docs/decisions.md +473 -0
  80. package/docs/environment-and-policy.md +188 -0
  81. package/docs/evals.md +509 -0
  82. package/docs/event-log.md +311 -0
  83. package/docs/from-a-loop.md +528 -0
  84. package/docs/generate-machines.md +110 -0
  85. package/docs/hosts.md +414 -0
  86. package/docs/human-in-the-loop.md +177 -0
  87. package/docs/index.md +48 -0
  88. package/docs/judgments.md +281 -0
  89. package/docs/langgraph-comparison.md +198 -0
  90. package/docs/machines-as-data.md +454 -0
  91. package/docs/machines-presets.md +198 -0
  92. package/docs/machines.md +497 -0
  93. package/docs/messages.md +67 -0
  94. package/docs/meta.json +52 -0
  95. package/docs/models-and-providers.md +268 -0
  96. package/docs/multi-agent.md +68 -0
  97. package/docs/observability.md +109 -0
  98. package/docs/patterns.md +31 -0
  99. package/docs/persistence.md +136 -0
  100. package/docs/quickstart.md +121 -0
  101. package/docs/roadmap.md +22 -0
  102. package/docs/scope.md +75 -0
  103. package/docs/statechart-policy-examples.md +69 -0
  104. package/docs/steps.md +54 -0
  105. package/docs/strangler-fig.md +323 -0
  106. package/docs/text-requests.md +250 -0
  107. package/docs/thinking-in-state-machines.md +324 -0
  108. package/docs/tools.md +249 -0
  109. package/docs/upgrading.md +37 -0
  110. package/docs/usage-and-budgets.md +516 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +487 -0
  113. package/docs/xstate-4-and-5-apps.md +161 -0
  114. package/llms.txt +53 -0
  115. package/package.json +10 -3
  116. package/readme.md +30 -15
  117. package/skills/add-evals/SKILL.md +3 -1
  118. package/skills/add-traces/SKILL.md +6 -1
  119. package/skills/build-machine/SKILL.md +81 -0
  120. package/skills/generate-machine/SKILL.md +1 -1
  121. package/skills/graph-engineering/SKILL.md +13 -3
  122. package/skills/improve-machine/SKILL.md +21 -2
  123. package/skills/loop-to-machine/SKILL.md +147 -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
@@ -1,4 +1,5 @@
1
1
  import { createAsyncLogic, initialTransition, isMachineSnapshot, transition } from "xstate";
2
+ import { restoreActor } from "xstate/persist";
2
3
  //#region src/errors.ts
3
4
  /**
4
5
  * Base class for every error this package throws. Carries a stable, kebab-case
@@ -98,7 +99,7 @@ function getMessageText(message) {
98
99
  /**
99
100
  * Walks a context value and returns the dot-paths of the first few values that
100
101
  * would NOT survive a JSON persist/resume round-trip (persist with XState's
101
- * `actor.getPersistedSnapshot()`, resume with `createActor(machine, { snapshot })`):
102
+ * `actor.getPersistedSnapshot()`, resume with `restoreActor(machine, snapshot)` from `xstate/persist`):
102
103
  * `Date`, `Map`, `Set`, `RegExp`, functions, `undefined`, `bigint`, class
103
104
  * instances (non-plain objects), and circular references. Plain objects,
104
105
  * arrays, and JSON primitives are walked/allowed. Returns `[]` for a
@@ -408,6 +409,7 @@ function getRegisteredAgentExecutionOptions(machine, options) {
408
409
  const GENERATE_TEXT_ACTOR = "agent.generateText";
409
410
  const STREAM_TEXT_ACTOR = "agent.streamText";
410
411
  const DECIDE_ACTOR = "agent.decide";
412
+ const ACT_ACTOR = "agent.act";
411
413
  const AGENT_FINISH_REASONS = /* @__PURE__ */ new Set([
412
414
  "stop",
413
415
  "length",
@@ -844,6 +846,18 @@ function invalidGeneratorResult(id) {
844
846
  return /* @__PURE__ */ new Error(`Executor for '${id}' returned an invalid result: executors must return { result } (the text string or structured object as \`result\`, plus optional \`messages\`, \`usage\` and other passthrough fields). Wrap a raw SDK result with an adapter such as createAiSdkExecutors.`);
845
847
  }
846
848
  //#endregion
849
+ //#region src/internal/restore-snapshot.ts
850
+ /**
851
+ * The snapshot `machine` resumes from for `persisted`, with no actor started.
852
+ * XState reports a snapshot it cannot restore as an `'error'` snapshot; this
853
+ * throws that error instead, unless the persisted snapshot was itself an error.
854
+ */
855
+ function restoreMachineSnapshot(machine, persisted) {
856
+ const snapshot = restoreActor(machine, persisted).getSnapshot();
857
+ if (snapshot.status === "error" && persisted?.status !== "error") throw snapshot.error;
858
+ return snapshot;
859
+ }
860
+ //#endregion
847
861
  //#region src/usage.ts
848
862
  /** Reserved event delivered after a model call reports token usage. */
849
863
  const AGENT_USAGE_EVENT_TYPE = "@agent.usage";
@@ -979,11 +993,8 @@ function assertAgentLogEntry(entry) {
979
993
  const candidate = entry;
980
994
  if (candidate.schemaVersion !== 1) throw new AgentEventLogError(`Unsupported agent event schema version '${String(candidate.schemaVersion)}'; expected '1'.`);
981
995
  if (!Number.isInteger(candidate.index) || candidate.index < 0) throw new AgentEventLogError(`Agent event entry.index must be a non-negative integer; got ${String(candidate.index)}.`);
982
- for (const field of [
983
- "id",
984
- "machineId",
985
- "machineVersion"
986
- ]) requireNonEmptyString(candidate[field], `entry.${field}`);
996
+ for (const field of ["id", "machineVersion"]) requireNonEmptyString(candidate[field], `entry.${field}`);
997
+ if (typeof candidate.machineId !== "string") throw new AgentEventLogError(`Agent event entry.machineId must be a string; got ${String(candidate.machineId)}.`);
987
998
  if (typeof candidate.recordedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(candidate.recordedAt) || Number.isNaN(Date.parse(candidate.recordedAt))) throw new AgentEventLogError(`Agent event entry.recordedAt is not RFC 3339: '${String(candidate.recordedAt)}'.`);
988
999
  if (candidate.event === null || typeof candidate.event !== "object" || Array.isArray(candidate.event) || typeof candidate.event.type !== "string" || !candidate.event.type) throw new AgentEventLogError("Agent event entry.event requires a non-empty string type.");
989
1000
  if (candidate.causationId !== void 0) requireNonEmptyString(candidate.causationId, "entry.causationId", " when present");
@@ -1073,8 +1084,9 @@ const SNAPSHOT_VOLATILE_KEYS = /* @__PURE__ */ new Set([
1073
1084
  "_nextActorIds"
1074
1085
  ]);
1075
1086
  const CHILD_VOLATILE_KEYS = /* @__PURE__ */ new Set(["sessionId"]);
1087
+ const TIMER_VOLATILE_KEYS = /* @__PURE__ */ new Set(["scheduledAt"]);
1076
1088
  function positionOf(parent, key) {
1077
- if (parent === "snapshot") return key === "children" ? "children" : "data";
1089
+ if (parent === "snapshot") return key === "children" ? "children" : key === "timers" ? "timers" : "data";
1078
1090
  if (parent === "children") return "child";
1079
1091
  if (parent === "child") return key === "snapshot" ? "snapshot" : "data";
1080
1092
  return "data";
@@ -1104,8 +1116,11 @@ function canonicalizeForHash(value, seen = /* @__PURE__ */ new WeakSet(), positi
1104
1116
  try {
1105
1117
  if (value instanceof Set) return [...value].map((item) => canonicalizeForHash(item, seen, "data")).sort((a, b) => stableJson(a).localeCompare(stableJson(b)));
1106
1118
  if (value instanceof Map) return [...value.entries()].map(([key, item]) => [canonicalizeForHash(key, seen, "data"), canonicalizeForHash(item, seen, "data")]).sort(([a], [b]) => stableJson(a).localeCompare(stableJson(b)));
1107
- if (Array.isArray(value)) return value.map((item) => canonicalizeForHash(item, seen, "data"));
1108
- const volatileKeys = position === "snapshot" ? SNAPSHOT_VOLATILE_KEYS : position === "child" ? CHILD_VOLATILE_KEYS : void 0;
1119
+ if (Array.isArray(value)) {
1120
+ const itemPosition = position === "timers" ? "timer" : "data";
1121
+ return value.map((item) => canonicalizeForHash(item, seen, itemPosition));
1122
+ }
1123
+ const volatileKeys = position === "snapshot" ? SNAPSHOT_VOLATILE_KEYS : position === "child" ? CHILD_VOLATILE_KEYS : position === "timer" ? TIMER_VOLATILE_KEYS : void 0;
1109
1124
  const result = Object.create(null);
1110
1125
  for (const key of Object.keys(value).sort()) {
1111
1126
  if (volatileKeys?.has(key)) continue;
@@ -1156,7 +1171,7 @@ function getSnapshotStateHash(snapshot) {
1156
1171
  return djb2Hex(stableJson(canonicalizeForHash(snapshot)));
1157
1172
  }
1158
1173
  function machineIdOf(machine) {
1159
- return machine.config.id ?? machine.id ?? "(machine)";
1174
+ return machine.config.id ?? machine.id;
1160
1175
  }
1161
1176
  function toPersisted(machine, snapshot) {
1162
1177
  return typeof snapshot.matches === "function" ? machine.getPersistedSnapshot(snapshot) : snapshot;
@@ -1531,7 +1546,7 @@ function verifyEntry(entry, persisted, mode) {
1531
1546
  *
1532
1547
  * The first entry is the reserved {@link initEntry}: `input` folds from
1533
1548
  * `initialTransition`, `snapshot` restores the persisted snapshot purely
1534
- * (`machine.restoreSnapshot`) and folds the rest of the log onto it.
1549
+ * (`restoreActor` from `xstate/persist`) and folds the rest of the log onto it.
1535
1550
  */
1536
1551
  function replay(machine, entries, options = {}) {
1537
1552
  const fold = foldLog(machine, entries, options);
@@ -1554,7 +1569,7 @@ function foldLog(machine, entries, options = {}) {
1554
1569
  });
1555
1570
  if (entries.length === 0) throw new AgentEventLogError(`Cannot replay an empty event log; it must start with a '${AGENT_INIT_EVENT_TYPE}' entry.`);
1556
1571
  const initEvent = entries[0].event;
1557
- let snapshot = initEvent.snapshot !== void 0 ? machine.restoreSnapshot(initEvent.snapshot) : initialTransition(machine, initEvent.input)[0];
1572
+ let snapshot = initEvent.snapshot !== void 0 ? restoreMachineSnapshot(machine, initEvent.snapshot) : initialTransition(machine, initEvent.input)[0];
1558
1573
  let persisted = machine.getPersistedSnapshot(snapshot);
1559
1574
  verifyEntry(entries[0], persisted, options.verify);
1560
1575
  const starts = /* @__PURE__ */ new Map();
@@ -1599,7 +1614,7 @@ function foldLog(machine, entries, options = {}) {
1599
1614
  for (const id of path.slice(0, -1)) holder = holder.children[id].snapshot;
1600
1615
  holder.children[path[path.length - 1]].snapshot = child.logic.getPersistedSnapshot(next);
1601
1616
  const before = snapshot;
1602
- snapshot = machine.restoreSnapshot(root);
1617
+ snapshot = restoreMachineSnapshot(machine, root);
1603
1618
  const reminted = /* @__PURE__ */ new Map();
1604
1619
  collectSessionRemints(before, snapshot, reminted);
1605
1620
  for (const map of sessions.values()) for (const [recorded, current] of map) {
@@ -1644,10 +1659,10 @@ function recordLog(actor) {
1644
1659
  const entries = [];
1645
1660
  let fold;
1646
1661
  let failure;
1662
+ const restored = actor._restored ? actor.getPersistedSnapshot() : void 0;
1647
1663
  const record = (event) => {
1648
1664
  if (fold === void 0) {
1649
1665
  if (event.type !== "xstate.init") throw new AgentEventLogError("recordLog must be attached before actor.start(): it missed the init event.");
1650
- const restored = actor.options.snapshot;
1651
1666
  const init = restored ? { snapshot: restored } : { input: event.input };
1652
1667
  entries.push(initEntry(machine, init, { machineVersion }));
1653
1668
  fold = foldLog(machine, entries, {
@@ -1681,4 +1696,4 @@ function recordLog(actor) {
1681
1696
  };
1682
1697
  }
1683
1698
  //#endregion
1684
- export { getMachineStructuralHash as $, builtinTextActors as A, providerOutputSchema as B, validateReplayEntries as C, GENERATE_TEXT_ACTOR as D, DECIDE_ACTOR as E, getCallUsage as F, getRegisteredAgentExecutionOptions as G, responseMessagesOf as H, isTextLogic as I, setAgentExecutionOptions as J, isUnboundPlaceholder as K, normalizeGeneratorResult as L, getAgentOutputMode as M, getCallFinishReason as N, STREAM_TEXT_ACTOR as O, getCallModelCalls as P, getJsonSchemaSync as Q, parseOutput as R, replay as S, AGENT_USAGE_TOKEN_FIELDS as T, executorBoundLogics as U, resolveTextLogicValue as V, getAgentExecutionOptions as W, findNonSerializableContextPaths as X, assistantMessage as Y, getJsonSchema as Z, getSnapshotStateHash as _, AgentReplayDivergenceError as a, systemMessage as at, rebindActorSession as b, agentCallSite as c, validateSchemaSync as ct, canonicalEventJson as d, isPlainObject as dt, getMessageText as et, createReplayEntry as f, isRecord as ft, getLogExecutionId as g, getDecisionAttempts as h, AgentMachineVersionMismatchError as i, resolveMachineVersion as it, createTextLogic as j, bindRequestExecutor as k, assertAgentLogEntry as l, canonicalJson as lt, forkEventLog as m, AgentTruncatedError as mt, AGENT_INIT_EVENT_TYPE as n, getStatePath as nt, NonSerializableAgentEventError as o, toolMessage as ot, foldLog as p, AgentError as pt, missingActor as q, AgentEventLogError as r, isStandardSchema as rt, agentCallOccurrence as s, userMessage as st, AGENT_EVENT_SCHEMA_VERSION as t, getStateMeta as tt, assertJsonSerializable as u, isError as ut, getUsageFromEvents as v, AGENT_USAGE_EVENT_TYPE as w, recordLog as x, initEntry as y, parseProviderOutput as z };
1699
+ export { getJsonSchema as $, STREAM_TEXT_ACTOR as A, parseOutput as B, validateReplayEntries as C, AGENT_USAGE_TOKEN_FIELDS as D, ACT_ACTOR as E, getCallFinishReason as F, executorBoundLogics as G, providerOutputSchema as H, getCallModelCalls as I, isUnboundPlaceholder as J, getAgentExecutionOptions as K, getCallUsage as L, builtinTextActors as M, createTextLogic as N, DECIDE_ACTOR as O, getAgentOutputMode as P, findNonSerializableContextPaths as Q, isTextLogic as R, replay as S, restoreMachineSnapshot as T, resolveTextLogicValue as U, parseProviderOutput as V, responseMessagesOf as W, setAgentExecutionOptions as X, missingActor as Y, assistantMessage as Z, getSnapshotStateHash as _, AgentReplayDivergenceError as a, isStandardSchema as at, rebindActorSession as b, agentCallSite as c, toolMessage as ct, canonicalEventJson as d, canonicalJson as dt, getJsonSchemaSync as et, createReplayEntry as f, isError as ft, getLogExecutionId as g, AgentTruncatedError as gt, getDecisionAttempts as h, AgentError as ht, AgentMachineVersionMismatchError as i, getStatePath as it, bindRequestExecutor as j, GENERATE_TEXT_ACTOR as k, assertAgentLogEntry as l, userMessage as lt, forkEventLog as m, isRecord as mt, AGENT_INIT_EVENT_TYPE as n, getMessageText as nt, NonSerializableAgentEventError as o, resolveMachineVersion as ot, foldLog as p, isPlainObject as pt, getRegisteredAgentExecutionOptions as q, AgentEventLogError as r, getStateMeta as rt, agentCallOccurrence as s, systemMessage as st, AGENT_EVENT_SCHEMA_VERSION as t, getMachineStructuralHash as tt, assertJsonSerializable as u, validateSchemaSync as ut, getUsageFromEvents as v, AGENT_USAGE_EVENT_TYPE as w, recordLog as x, initEntry as y, normalizeGeneratorResult as z };
@@ -1,4 +1,5 @@
1
1
  let xstate = require("xstate");
2
+ let xstate_persist = require("xstate/persist");
2
3
  //#region src/errors.ts
3
4
  /**
4
5
  * Base class for every error this package throws. Carries a stable, kebab-case
@@ -98,7 +99,7 @@ function getMessageText(message) {
98
99
  /**
99
100
  * Walks a context value and returns the dot-paths of the first few values that
100
101
  * would NOT survive a JSON persist/resume round-trip (persist with XState's
101
- * `actor.getPersistedSnapshot()`, resume with `createActor(machine, { snapshot })`):
102
+ * `actor.getPersistedSnapshot()`, resume with `restoreActor(machine, snapshot)` from `xstate/persist`):
102
103
  * `Date`, `Map`, `Set`, `RegExp`, functions, `undefined`, `bigint`, class
103
104
  * instances (non-plain objects), and circular references. Plain objects,
104
105
  * arrays, and JSON primitives are walked/allowed. Returns `[]` for a
@@ -408,6 +409,7 @@ function getRegisteredAgentExecutionOptions(machine, options) {
408
409
  const GENERATE_TEXT_ACTOR = "agent.generateText";
409
410
  const STREAM_TEXT_ACTOR = "agent.streamText";
410
411
  const DECIDE_ACTOR = "agent.decide";
412
+ const ACT_ACTOR = "agent.act";
411
413
  const AGENT_FINISH_REASONS = /* @__PURE__ */ new Set([
412
414
  "stop",
413
415
  "length",
@@ -844,6 +846,18 @@ function invalidGeneratorResult(id) {
844
846
  return /* @__PURE__ */ new Error(`Executor for '${id}' returned an invalid result: executors must return { result } (the text string or structured object as \`result\`, plus optional \`messages\`, \`usage\` and other passthrough fields). Wrap a raw SDK result with an adapter such as createAiSdkExecutors.`);
845
847
  }
846
848
  //#endregion
849
+ //#region src/internal/restore-snapshot.ts
850
+ /**
851
+ * The snapshot `machine` resumes from for `persisted`, with no actor started.
852
+ * XState reports a snapshot it cannot restore as an `'error'` snapshot; this
853
+ * throws that error instead, unless the persisted snapshot was itself an error.
854
+ */
855
+ function restoreMachineSnapshot(machine, persisted) {
856
+ const snapshot = (0, xstate_persist.restoreActor)(machine, persisted).getSnapshot();
857
+ if (snapshot.status === "error" && persisted?.status !== "error") throw snapshot.error;
858
+ return snapshot;
859
+ }
860
+ //#endregion
847
861
  //#region src/usage.ts
848
862
  /** Reserved event delivered after a model call reports token usage. */
849
863
  const AGENT_USAGE_EVENT_TYPE = "@agent.usage";
@@ -979,11 +993,8 @@ function assertAgentLogEntry(entry) {
979
993
  const candidate = entry;
980
994
  if (candidate.schemaVersion !== 1) throw new AgentEventLogError(`Unsupported agent event schema version '${String(candidate.schemaVersion)}'; expected '1'.`);
981
995
  if (!Number.isInteger(candidate.index) || candidate.index < 0) throw new AgentEventLogError(`Agent event entry.index must be a non-negative integer; got ${String(candidate.index)}.`);
982
- for (const field of [
983
- "id",
984
- "machineId",
985
- "machineVersion"
986
- ]) requireNonEmptyString(candidate[field], `entry.${field}`);
996
+ for (const field of ["id", "machineVersion"]) requireNonEmptyString(candidate[field], `entry.${field}`);
997
+ if (typeof candidate.machineId !== "string") throw new AgentEventLogError(`Agent event entry.machineId must be a string; got ${String(candidate.machineId)}.`);
987
998
  if (typeof candidate.recordedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(candidate.recordedAt) || Number.isNaN(Date.parse(candidate.recordedAt))) throw new AgentEventLogError(`Agent event entry.recordedAt is not RFC 3339: '${String(candidate.recordedAt)}'.`);
988
999
  if (candidate.event === null || typeof candidate.event !== "object" || Array.isArray(candidate.event) || typeof candidate.event.type !== "string" || !candidate.event.type) throw new AgentEventLogError("Agent event entry.event requires a non-empty string type.");
989
1000
  if (candidate.causationId !== void 0) requireNonEmptyString(candidate.causationId, "entry.causationId", " when present");
@@ -1073,8 +1084,9 @@ const SNAPSHOT_VOLATILE_KEYS = /* @__PURE__ */ new Set([
1073
1084
  "_nextActorIds"
1074
1085
  ]);
1075
1086
  const CHILD_VOLATILE_KEYS = /* @__PURE__ */ new Set(["sessionId"]);
1087
+ const TIMER_VOLATILE_KEYS = /* @__PURE__ */ new Set(["scheduledAt"]);
1076
1088
  function positionOf(parent, key) {
1077
- if (parent === "snapshot") return key === "children" ? "children" : "data";
1089
+ if (parent === "snapshot") return key === "children" ? "children" : key === "timers" ? "timers" : "data";
1078
1090
  if (parent === "children") return "child";
1079
1091
  if (parent === "child") return key === "snapshot" ? "snapshot" : "data";
1080
1092
  return "data";
@@ -1104,8 +1116,11 @@ function canonicalizeForHash(value, seen = /* @__PURE__ */ new WeakSet(), positi
1104
1116
  try {
1105
1117
  if (value instanceof Set) return [...value].map((item) => canonicalizeForHash(item, seen, "data")).sort((a, b) => stableJson(a).localeCompare(stableJson(b)));
1106
1118
  if (value instanceof Map) return [...value.entries()].map(([key, item]) => [canonicalizeForHash(key, seen, "data"), canonicalizeForHash(item, seen, "data")]).sort(([a], [b]) => stableJson(a).localeCompare(stableJson(b)));
1107
- if (Array.isArray(value)) return value.map((item) => canonicalizeForHash(item, seen, "data"));
1108
- const volatileKeys = position === "snapshot" ? SNAPSHOT_VOLATILE_KEYS : position === "child" ? CHILD_VOLATILE_KEYS : void 0;
1119
+ if (Array.isArray(value)) {
1120
+ const itemPosition = position === "timers" ? "timer" : "data";
1121
+ return value.map((item) => canonicalizeForHash(item, seen, itemPosition));
1122
+ }
1123
+ const volatileKeys = position === "snapshot" ? SNAPSHOT_VOLATILE_KEYS : position === "child" ? CHILD_VOLATILE_KEYS : position === "timer" ? TIMER_VOLATILE_KEYS : void 0;
1109
1124
  const result = Object.create(null);
1110
1125
  for (const key of Object.keys(value).sort()) {
1111
1126
  if (volatileKeys?.has(key)) continue;
@@ -1156,7 +1171,7 @@ function getSnapshotStateHash(snapshot) {
1156
1171
  return djb2Hex(stableJson(canonicalizeForHash(snapshot)));
1157
1172
  }
1158
1173
  function machineIdOf(machine) {
1159
- return machine.config.id ?? machine.id ?? "(machine)";
1174
+ return machine.config.id ?? machine.id;
1160
1175
  }
1161
1176
  function toPersisted(machine, snapshot) {
1162
1177
  return typeof snapshot.matches === "function" ? machine.getPersistedSnapshot(snapshot) : snapshot;
@@ -1531,7 +1546,7 @@ function verifyEntry(entry, persisted, mode) {
1531
1546
  *
1532
1547
  * The first entry is the reserved {@link initEntry}: `input` folds from
1533
1548
  * `initialTransition`, `snapshot` restores the persisted snapshot purely
1534
- * (`machine.restoreSnapshot`) and folds the rest of the log onto it.
1549
+ * (`restoreActor` from `xstate/persist`) and folds the rest of the log onto it.
1535
1550
  */
1536
1551
  function replay(machine, entries, options = {}) {
1537
1552
  const fold = foldLog(machine, entries, options);
@@ -1554,7 +1569,7 @@ function foldLog(machine, entries, options = {}) {
1554
1569
  });
1555
1570
  if (entries.length === 0) throw new AgentEventLogError(`Cannot replay an empty event log; it must start with a '${AGENT_INIT_EVENT_TYPE}' entry.`);
1556
1571
  const initEvent = entries[0].event;
1557
- let snapshot = initEvent.snapshot !== void 0 ? machine.restoreSnapshot(initEvent.snapshot) : (0, xstate.initialTransition)(machine, initEvent.input)[0];
1572
+ let snapshot = initEvent.snapshot !== void 0 ? restoreMachineSnapshot(machine, initEvent.snapshot) : (0, xstate.initialTransition)(machine, initEvent.input)[0];
1558
1573
  let persisted = machine.getPersistedSnapshot(snapshot);
1559
1574
  verifyEntry(entries[0], persisted, options.verify);
1560
1575
  const starts = /* @__PURE__ */ new Map();
@@ -1599,7 +1614,7 @@ function foldLog(machine, entries, options = {}) {
1599
1614
  for (const id of path.slice(0, -1)) holder = holder.children[id].snapshot;
1600
1615
  holder.children[path[path.length - 1]].snapshot = child.logic.getPersistedSnapshot(next);
1601
1616
  const before = snapshot;
1602
- snapshot = machine.restoreSnapshot(root);
1617
+ snapshot = restoreMachineSnapshot(machine, root);
1603
1618
  const reminted = /* @__PURE__ */ new Map();
1604
1619
  collectSessionRemints(before, snapshot, reminted);
1605
1620
  for (const map of sessions.values()) for (const [recorded, current] of map) {
@@ -1644,10 +1659,10 @@ function recordLog(actor) {
1644
1659
  const entries = [];
1645
1660
  let fold;
1646
1661
  let failure;
1662
+ const restored = actor._restored ? actor.getPersistedSnapshot() : void 0;
1647
1663
  const record = (event) => {
1648
1664
  if (fold === void 0) {
1649
1665
  if (event.type !== "xstate.init") throw new AgentEventLogError("recordLog must be attached before actor.start(): it missed the init event.");
1650
- const restored = actor.options.snapshot;
1651
1666
  const init = restored ? { snapshot: restored } : { input: event.input };
1652
1667
  entries.push(initEntry(machine, init, { machineVersion }));
1653
1668
  fold = foldLog(machine, entries, {
@@ -1681,6 +1696,12 @@ function recordLog(actor) {
1681
1696
  };
1682
1697
  }
1683
1698
  //#endregion
1699
+ Object.defineProperty(exports, "ACT_ACTOR", {
1700
+ enumerable: true,
1701
+ get: function() {
1702
+ return ACT_ACTOR;
1703
+ }
1704
+ });
1684
1705
  Object.defineProperty(exports, "AGENT_EVENT_SCHEMA_VERSION", {
1685
1706
  enumerable: true,
1686
1707
  get: function() {
@@ -2053,6 +2074,12 @@ Object.defineProperty(exports, "responseMessagesOf", {
2053
2074
  return responseMessagesOf;
2054
2075
  }
2055
2076
  });
2077
+ Object.defineProperty(exports, "restoreMachineSnapshot", {
2078
+ enumerable: true,
2079
+ get: function() {
2080
+ return restoreMachineSnapshot;
2081
+ }
2082
+ });
2056
2083
  Object.defineProperty(exports, "setAgentExecutionOptions", {
2057
2084
  enumerable: true,
2058
2085
  get: function() {
@@ -1,4 +1,4 @@
1
- import { $ as AgentError, L as DecisionAttempt, t as AgentCallUsage } from "./text-logic-CV_4KGr6.cjs";
1
+ import { B as DecisionAttempt, at as AgentError, t as AgentCallUsage } from "./text-logic-BqxalgMr.mjs";
2
2
  import { Actor, AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
3
3
  //#region src/event-log.d.ts
4
4
  /** The durable entry envelope version. */
@@ -322,7 +322,7 @@ interface ReplayResult<TMachine extends AnyStateMachine> {
322
322
  *
323
323
  * The first entry is the reserved {@link initEntry}: `input` folds from
324
324
  * `initialTransition`, `snapshot` restores the persisted snapshot purely
325
- * (`machine.restoreSnapshot`) and folds the rest of the log onto it.
325
+ * (`restoreActor` from `xstate/persist`) and folds the rest of the log onto it.
326
326
  */
327
327
  declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
328
328
  /** A log being recorded from a plain actor. See {@link recordLog}. */
@@ -1,4 +1,4 @@
1
- import { l as assertAgentLogEntry, m as forkEventLog, pt as AgentError } from "./event-log-C7jeH0y8.mjs";
1
+ import { ht as AgentError, l as assertAgentLogEntry, m as forkEventLog } from "./event-log-DkVlk3Rh.mjs";
2
2
  //#region src/event-log-store.ts
3
3
  /**
4
4
  * Durable storage for {@link AgentLogEntry} logs: the one interface a host
@@ -1,4 +1,4 @@
1
- const require_event_log = require("./event-log-BWSSLUff.cjs");
1
+ const require_event_log = require("./event-log-Dkc-yIYu.cjs");
2
2
  //#region src/event-log-store.ts
3
3
  /**
4
4
  * Durable storage for {@link AgentLogEntry} logs: the one interface a host
@@ -1,4 +1,4 @@
1
- import { $ as AgentError, L as DecisionAttempt, t as AgentCallUsage } from "./text-logic-Ckh-rJFV.mjs";
1
+ import { B as DecisionAttempt, at as AgentError, t as AgentCallUsage } from "./text-logic-CSf9bqpP.cjs";
2
2
  import { Actor, AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
3
3
  //#region src/event-log.d.ts
4
4
  /** The durable entry envelope version. */
@@ -322,7 +322,7 @@ interface ReplayResult<TMachine extends AnyStateMachine> {
322
322
  *
323
323
  * The first entry is the reserved {@link initEntry}: `input` folds from
324
324
  * `initialTransition`, `snapshot` restores the persisted snapshot purely
325
- * (`machine.restoreSnapshot`) and folds the rest of the log onto it.
325
+ * (`restoreActor` from `xstate/persist`) and folds the rest of the log onto it.
326
326
  */
327
327
  declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
328
328
  /** A log being recorded from a plain actor. See {@link recordLog}. */