@statelyai/agent 2.0.0-alpha.33 → 2.0.0-alpha.34

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 (64) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/dist/ai-sdk.cjs +114 -63
  3. package/dist/ai-sdk.d.cts +11 -2
  4. package/dist/ai-sdk.d.mts +11 -2
  5. package/dist/ai-sdk.mjs +115 -64
  6. package/dist/{decision-BPdEaxPf.cjs → decision-BEsATcr1.cjs} +18 -2
  7. package/dist/{decision-CV7WiV5C.mjs → decision-COkJNjOW.mjs} +18 -2
  8. package/dist/{event-log-CKWeC7H-.cjs → event-log-BWSSLUff.cjs} +139 -10
  9. package/dist/{event-log-DAqsalT1.mjs → event-log-C7jeH0y8.mjs} +123 -12
  10. package/dist/{event-log-store-C2NjVlWU.d.mts → event-log-store-BzXehP7R.d.cts} +28 -3
  11. package/dist/{event-log-store-s73r1Hxf.d.cts → event-log-store-CWjN6lmM.d.mts} +28 -3
  12. package/dist/{event-log-store-DKyE7JKr.cjs → event-log-store-CleWpsp5.cjs} +1 -1
  13. package/dist/{event-log-store-BGehvVTb.mjs → event-log-store-W49TCJXi.mjs} +1 -1
  14. package/dist/index.cjs +5 -5
  15. package/dist/index.d.cts +7 -7
  16. package/dist/index.d.mts +7 -7
  17. package/dist/index.mjs +5 -5
  18. package/dist/log.cjs +2 -2
  19. package/dist/log.d.cts +1 -1
  20. package/dist/log.d.mts +1 -1
  21. package/dist/log.mjs +2 -2
  22. package/dist/machines.cjs +1 -1
  23. package/dist/machines.mjs +1 -1
  24. package/dist/{model-source-BilDEyqk.mjs → model-source-CK3F4YuU.mjs} +1 -1
  25. package/dist/{model-source-BQ97_l1-.cjs → model-source-DmhTMK39.cjs} +1 -1
  26. package/dist/openai.cjs +377 -95
  27. package/dist/openai.d.cts +55 -20
  28. package/dist/openai.d.mts +55 -20
  29. package/dist/openai.mjs +375 -96
  30. package/dist/otel.d.cts +1 -1
  31. package/dist/otel.d.mts +1 -1
  32. package/dist/{run-agent-B5QhabdY.d.cts → run-agent-B1-Eqviq.d.cts} +13 -5
  33. package/dist/{run-agent-Atu-wEk7.d.mts → run-agent-BGdx5913.d.mts} +13 -5
  34. package/dist/{run-agent-2UnSUhDb.mjs → run-agent-Ct_GZw_f.mjs} +124 -38
  35. package/dist/{run-agent-Cg0xd3K-.cjs → run-agent-s5D32w99.cjs} +123 -37
  36. package/dist/{setup-agent-CmhB-U5P.mjs → setup-agent-05uw4dPZ.mjs} +2 -2
  37. package/dist/{setup-agent-BiF1N3td.d.cts → setup-agent-BtfeFfF6.d.cts} +2 -2
  38. package/dist/{setup-agent-J9f_Wu5T.d.mts → setup-agent-C6nqzv_X.d.mts} +2 -2
  39. package/dist/{setup-agent-CwUJyqKB.cjs → setup-agent-CXEBURdo.cjs} +2 -2
  40. package/dist/tanstack-ai.cjs +91 -59
  41. package/dist/tanstack-ai.d.cts +13 -2
  42. package/dist/tanstack-ai.d.mts +13 -2
  43. package/dist/tanstack-ai.mjs +91 -59
  44. package/dist/testing.cjs +539 -13
  45. package/dist/testing.d.cts +202 -6
  46. package/dist/testing.d.mts +202 -6
  47. package/dist/testing.mjs +536 -14
  48. package/dist/{text-logic-CYP502VT.d.cts → text-logic-CV_4KGr6.d.cts} +28 -3
  49. package/dist/{text-logic-DuK9HIFM.d.mts → text-logic-Ckh-rJFV.d.mts} +28 -3
  50. package/dist/{usage-D7JKAxLc.d.mts → usage-BDiJKyv9.d.cts} +11 -1
  51. package/dist/{usage-DVw-646x.d.cts → usage-DOoVUGVq.d.mts} +11 -1
  52. package/dist/validate.cjs +3 -3
  53. package/dist/validate.d.cts +2 -2
  54. package/dist/validate.d.mts +2 -2
  55. package/dist/validate.mjs +3 -3
  56. package/dist/{verify-Dk3Vwnha.d.cts → verify-BQpE8hUz.d.cts} +1 -1
  57. package/dist/{verify-DgB8P-Wx.mjs → verify-Bpahmr34.mjs} +2 -2
  58. package/dist/{verify-BVz4cURF.d.mts → verify-CqeuEmIk.d.mts} +1 -1
  59. package/dist/{verify-CS_WLRXn.cjs → verify-DCLZa9R0.cjs} +2 -2
  60. package/dist/with-model-calls-BXYdBdcu.cjs +45 -0
  61. package/dist/with-model-calls-Bv4V4EHC.mjs +34 -0
  62. package/package.json +5 -5
  63. package/readme.md +14 -13
  64. package/skills/loop-to-machine/SKILL.md +40 -2
package/dist/testing.mjs CHANGED
@@ -1,13 +1,14 @@
1
- import { $ as getStateMeta, F as normalizeGeneratorResult, N as getCallUsage, lt as isRecord, ut as AgentError } from "./event-log-DAqsalT1.mjs";
2
- import { p as runToQuiescence, s as createAgentRuntime } from "./run-agent-2UnSUhDb.mjs";
3
- import { a as explorePaths, c as simulateAgent, i as canReach, n as AgentUnknownStateError, o as isExplorationComplete, r as assertAgentMachine, s as lintAgentMachine, t as AgentLintError } from "./verify-DgB8P-Wx.mjs";
1
+ import { F as getCallUsage, L as normalizeGeneratorResult, d as canonicalEventJson, dt as isPlainObject, ft as isRecord, pt as AgentError, tt as getStateMeta, ut as isError } from "./event-log-C7jeH0y8.mjs";
2
+ import { p as runToQuiescence, s as createAgentRuntime } from "./run-agent-Ct_GZw_f.mjs";
3
+ import { a as explorePaths, c as simulateAgent, i as canReach, n as AgentUnknownStateError, o as isExplorationComplete, r as assertAgentMachine, s as lintAgentMachine, t as AgentLintError } from "./verify-Bpahmr34.mjs";
4
+ import { getInitialMicrosteps, getMicrosteps } from "xstate";
4
5
  //#region src/trajectory.ts
5
6
  /**
6
7
  * Classifies one item. Event-shaped things (log entries, events) become events;
7
8
  * everything else is a state value. A snapshot is unwrapped to its `value`.
8
9
  * @internal
9
10
  */
10
- function normalize(item) {
11
+ function normalize$1(item) {
11
12
  if (isRecord(item)) {
12
13
  const nested = item["event"];
13
14
  if (isRecord(nested) && typeof nested["type"] === "string") return {
@@ -60,17 +61,17 @@ function deepEqual(a, b) {
60
61
  */
61
62
  function matcherFor(expected) {
62
63
  if (typeof expected === "string") return (actual) => {
63
- const actualItem = normalize(actual);
64
+ const actualItem = normalize$1(actual);
64
65
  return actualItem.kind === "event" ? actualItem.event.type === expected : stateMatchesPath(expected, actualItem.value);
65
66
  };
66
- const expectedItem = normalize(expected);
67
+ const expectedItem = normalize$1(expected);
67
68
  switch (expectedItem.kind) {
68
69
  case "event": return (actual) => {
69
- const actualItem = normalize(actual);
70
+ const actualItem = normalize$1(actual);
70
71
  return actualItem.kind === "event" && Object.keys(expectedItem.event).every((key) => deepEqual(expectedItem.event[key], actualItem.event[key]));
71
72
  };
72
73
  case "state": return (actual) => {
73
- const actualItem = normalize(actual);
74
+ const actualItem = normalize$1(actual);
74
75
  return actualItem.kind === "state" && deepEqual(expectedItem.value, actualItem.value);
75
76
  };
76
77
  }
@@ -383,7 +384,7 @@ function statePaths(value, prefix = "") {
383
384
  /**
384
385
  * A trace's `machine.transition` events as steps, skipping `@xstate.init`.
385
386
  * A first-attempt decision's `request.start` names the decision on the step
386
- * that follows it. Reads live and serialized traces alike.
387
+ * that follows it, skipping `@agent.usage` steps. Reads live and serialized traces alike.
387
388
  * @internal
388
389
  */
389
390
  function traceSteps(trace) {
@@ -408,9 +409,9 @@ function traceSteps(trace) {
408
409
  to: statePaths(toValue),
409
410
  toValue,
410
411
  ignored: event.ignored === true,
411
- ...decision === void 0 ? {} : { decision }
412
+ ...decision === void 0 || type === "@agent.usage" ? {} : { decision }
412
413
  });
413
- decision = void 0;
414
+ if (type !== "@agent.usage") decision = void 0;
414
415
  }
415
416
  return steps;
416
417
  }
@@ -520,6 +521,37 @@ function candidateAt(node, type, event) {
520
521
  return keys.find((key) => node.transitions.get(key).some((d) => matchesPattern(d, event)));
521
522
  }
522
523
  const pathOf = (node) => node.path.join(".");
524
+ const sameLeaves = (a, b) => statePaths(a).sort().join("|") === statePaths(b).sort().join("|");
525
+ /**
526
+ * The leaves a trace passed through inside its macrosteps: states an `always`
527
+ * transition left before the step ended, which no traced snapshot holds.
528
+ * Re-derived with XState's pure `getMicrosteps` from the snapshot before each
529
+ * step (the previous step's, or the fresh start's microsteps from its input).
530
+ * A step that cannot be recomputed, or whose recomputation ends elsewhere
531
+ * than the traced snapshot, adds none. Only `value` and `context` are rebuilt,
532
+ * so a guard that reads live children can take another route to the same
533
+ * leaves, and that route is credited.
534
+ */
535
+ function passedThrough(machine, trace) {
536
+ const leaves = /* @__PURE__ */ new Set();
537
+ let resumed = false;
538
+ let previous;
539
+ for (const event of trace) {
540
+ if (event.type === "run.start") resumed = event.snapshot !== void 0;
541
+ if (event.type !== "machine.transition" || !isRecord(event.event)) continue;
542
+ const snapshot = isRecord(event.snapshot) ? event.snapshot : void 0;
543
+ try {
544
+ const microsteps = event.event.type === "@xstate.init" ? resumed ? [] : getInitialMicrosteps(machine, event.event.input) : previous && sameLeaves(previous.value, valueOf(event.from)) ? getMicrosteps(machine, machine.resolveState({
545
+ value: previous.value,
546
+ context: previous.context
547
+ }), event.event) : [];
548
+ const last = microsteps.at(-1)?.[0];
549
+ if (last && snapshot && sameLeaves(last.value, snapshot.value)) for (const [step] of microsteps) for (const leaf of statePaths(step.value)) leaves.add(leaf);
550
+ } catch {}
551
+ previous = snapshot;
552
+ }
553
+ return leaves;
554
+ }
523
555
  const ratioOf = (visited, total) => total === 0 ? 1 : visited / total;
524
556
  /**
525
557
  * Measures how much of a machine a set of runs exercised: which atomic and
@@ -537,7 +569,8 @@ const ratioOf = (visited, total) => total === 0 ? 1 : visited / total;
537
569
  * bare type (`xstate.done.actor`), one per state however many invokes; a
538
570
  * definition's `matches` (an invoke's `actorId`) must accept the traced event
539
571
  * for its state to be credited. Ignored steps credit no handler. `always`
540
- * handlers are listed as `unobservable`, never as unvisited.
572
+ * handlers are listed as `unobservable`, never as unvisited; a state one
573
+ * passes through is visited, re-derived from each step's microsteps.
541
574
  *
542
575
  * @example
543
576
  * ```ts no-check
@@ -593,6 +626,7 @@ function traceCoverage(machine, traces, options = {}) {
593
626
  if (event.event.type !== "@xstate.init" || !isRecord(event.snapshot)) continue;
594
627
  for (const leaf of statePaths(event.snapshot.value)) visited.add(leaf);
595
628
  }
629
+ if (unobservable.length > 0) for (const leaf of passedThrough(machine, trace)) visited.add(leaf);
596
630
  const credited = /* @__PURE__ */ new Set();
597
631
  for (const step of steps) {
598
632
  for (const leaf of step.to) visited.add(leaf);
@@ -654,6 +688,35 @@ function traceCoverage(machine, traces, options = {}) {
654
688
  //#endregion
655
689
  //#region src/first-divergence.ts
656
690
  const defaultKey = (step) => `${step.from.join(",")}|${step.event}|${step.to.join(",")}`;
691
+ const isErrorLike = (value) => isError(value) || isRecord(value) && typeof value.name === "string" && typeof value.message === "string";
692
+ const normalizeErrors = (value, seen = /* @__PURE__ */ new WeakSet()) => {
693
+ if (value === null || typeof value !== "object") return value;
694
+ if (seen.has(value)) return "[circular]";
695
+ seen.add(value);
696
+ try {
697
+ if (isErrorLike(value) && (isError(value) || "stack" in value || "code" in value)) {
698
+ const { name, message, code, cause } = value;
699
+ return {
700
+ name,
701
+ message,
702
+ ...typeof code === "string" ? { code } : {},
703
+ ...cause !== void 0 ? { cause: normalizeErrors(cause, seen) } : {}
704
+ };
705
+ }
706
+ if (Array.isArray(value)) return value.map((item) => normalizeErrors(item, seen));
707
+ if (!isPlainObject(value)) return value;
708
+ const copy = Object.create(null);
709
+ for (const key of Object.keys(value)) copy[key] = normalizeErrors(value[key], seen);
710
+ return copy;
711
+ } finally {
712
+ seen.delete(value);
713
+ }
714
+ };
715
+ const payloadKey = (step) => {
716
+ if (!isRecord(step.payload)) return `${defaultKey(step)}|${canonicalEventJson(step.payload)}`;
717
+ const { sessionId: _sessionId, ...payload } = step.payload;
718
+ return `${defaultKey(step)}|${canonicalEventJson(normalizeErrors(payload))}`;
719
+ };
657
720
  const isTrace = (items) => items.length === 0 || items.some((item) => isRecord(item) && (item.type === "machine.transition" || item.type === "run.start" || item.type === "run.end"));
658
721
  /**
659
722
  * Finds the first step where a run departs from a reference, so a failure is
@@ -684,7 +747,7 @@ const isTrace = (items) => items.length === 0 || items.some((item) => isRecord(i
684
747
  */
685
748
  function firstDivergence(actual, reference, options = {}) {
686
749
  const steps = traceSteps(actual).filter((step) => !step.ignored);
687
- return isTrace(reference) ? againstTrace(steps, traceSteps(reference).filter((step) => !step.ignored), options.key ?? defaultKey) : againstTrajectory(actual, steps, reference);
750
+ return isTrace(reference) ? againstTrace(steps, traceSteps(reference).filter((step) => !step.ignored), options.key === "payload" ? payloadKey : options.key ?? defaultKey) : againstTrajectory(actual, steps, reference);
688
751
  }
689
752
  function diverged(steps, index, expected, initial = steps[0]?.fromValue) {
690
753
  const step = steps[index];
@@ -1070,4 +1133,463 @@ function structurallyEqual(a, b) {
1070
1133
  return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && structurallyEqual(a[key], b[key]));
1071
1134
  }
1072
1135
  //#endregion
1073
- export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, compareRuns, explorePaths, firstDivergence, foldTraces, getDecisionRequests, judgeAgreement, lintAgentMachine, matchesTrajectory, repeatRuns, runSeam, simulateAgent, summarizeRepeats, traceCoverage };
1136
+ //#region src/equivalence.ts
1137
+ /**
1138
+ * Thrown in replay when the port asks for something the recording cannot
1139
+ * answer: a model call past the last recorded one, or a tool call the original
1140
+ * never made. The effect is still recorded, so {@link compareRecordings}
1141
+ * reports it.
1142
+ */
1143
+ var RecordingDivergenceError = class extends Error {
1144
+ name = "RecordingDivergenceError";
1145
+ };
1146
+ function toRecordedError(error) {
1147
+ if (error instanceof Error) {
1148
+ const code = error.code;
1149
+ return code === void 0 ? {
1150
+ name: error.name,
1151
+ message: error.message
1152
+ } : {
1153
+ name: error.name,
1154
+ message: error.message,
1155
+ code: toJson(code)
1156
+ };
1157
+ }
1158
+ return {
1159
+ name: "Error",
1160
+ message: String(error)
1161
+ };
1162
+ }
1163
+ function fromRecordedError(error) {
1164
+ return Object.assign(new Error(error.message), error);
1165
+ }
1166
+ /** A JSON-safe copy: Dates become ISO strings, Errors become {@link RecordedError}. */
1167
+ function toJson(value) {
1168
+ if (value === void 0) return void 0;
1169
+ return JSON.parse(JSON.stringify(value, function(key, item) {
1170
+ const raw = this[key];
1171
+ if (raw instanceof Date) return raw.toISOString();
1172
+ if (item instanceof Error) return toRecordedError(item);
1173
+ if (typeof item === "bigint") return item.toString();
1174
+ if (item instanceof Uint8Array) return Array.from(item);
1175
+ return item;
1176
+ }));
1177
+ }
1178
+ /** Restores the `Date` timestamps the AI SDK puts on responses. */
1179
+ function reviveTimestamps(value) {
1180
+ if (value && typeof value === "object") {
1181
+ for (const holder of [value, value.response]) if (holder && typeof holder["timestamp"] === "string") holder["timestamp"] = new Date(holder["timestamp"]);
1182
+ }
1183
+ return value;
1184
+ }
1185
+ function omit(value, keys) {
1186
+ if (!value || typeof value !== "object") return value;
1187
+ return Object.fromEntries(Object.entries(value).filter(([key]) => !keys.includes(key)));
1188
+ }
1189
+ /** Key-order-independent JSON, for equality. */
1190
+ function stableStringify(value) {
1191
+ if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
1192
+ if (value && typeof value === "object") return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
1193
+ return JSON.stringify(value) ?? "undefined";
1194
+ }
1195
+ function jsonEqual(a, b) {
1196
+ return stableStringify(toJson(a)) === stableStringify(toJson(b));
1197
+ }
1198
+ function streamFrom(parts) {
1199
+ return new ReadableStream({ start(controller) {
1200
+ for (const part of parts) controller.enqueue(reviveTimestamps(structuredClone(part)));
1201
+ controller.close();
1202
+ } });
1203
+ }
1204
+ async function* iterate(chunks) {
1205
+ for (const chunk of chunks) yield structuredClone(chunk);
1206
+ }
1207
+ /**
1208
+ * Creates a {@link Recorder}. With no options it records: every wrapped call
1209
+ * runs for real. With `replay` it answers from a recording instead.
1210
+ */
1211
+ function createRecorder(options = {}) {
1212
+ const effects = [];
1213
+ const replay = options.replay?.effects;
1214
+ const replayedModels = replay?.filter((effect) => effect.kind === "model");
1215
+ const usedTools = /* @__PURE__ */ new Set();
1216
+ const normalizeEffect = options.normalize ?? ((effect) => effect);
1217
+ let modelCalls = 0;
1218
+ let toolsInFlight = 0;
1219
+ function nextReplayedModel(effect) {
1220
+ const recorded = replayedModels[effect.call];
1221
+ if (!recorded) throw new RecordingDivergenceError(`Model call #${effect.call} was never made by the recorded run (it made ${replayedModels.length}).`);
1222
+ if (recorded.method !== effect.method) throw new RecordingDivergenceError(`Model call #${effect.call} uses ${effect.method}; the recorded run used ${recorded.method}.`);
1223
+ if (!modelCallsMatch(options.modelCalls, recorded, effect)) throw new RecordingDivergenceError(shapeMessage(recorded, effect));
1224
+ return recorded;
1225
+ }
1226
+ /** Records a model call around `run`, or answers it from the recording. */
1227
+ async function modelCall(seam, method, request, streamed, run) {
1228
+ const effect = {
1229
+ kind: "model",
1230
+ seam,
1231
+ method,
1232
+ call: modelCalls++,
1233
+ request: toJson(omit(request, [
1234
+ "abortSignal",
1235
+ "headers",
1236
+ "signal"
1237
+ ]))
1238
+ };
1239
+ effects.push(effect);
1240
+ if (replay) {
1241
+ let recorded;
1242
+ try {
1243
+ recorded = nextReplayedModel(effect);
1244
+ } catch (error) {
1245
+ effect.error = toRecordedError(error);
1246
+ throw error;
1247
+ }
1248
+ if (recorded.error) {
1249
+ effect.error = recorded.error;
1250
+ throw fromRecordedError(recorded.error);
1251
+ }
1252
+ effect.response = recorded.response;
1253
+ effect.stream = recorded.stream;
1254
+ if (seam === "openai") return streamed ? iterate(recorded.stream ?? []) : structuredClone(recorded.response);
1255
+ return streamed ? {
1256
+ ...reviveTimestamps(structuredClone(recorded.response) ?? {}),
1257
+ stream: streamFrom(recorded.stream ?? [])
1258
+ } : reviveTimestamps(structuredClone(recorded.response));
1259
+ }
1260
+ let result;
1261
+ try {
1262
+ result = await run();
1263
+ } catch (error) {
1264
+ effect.error = toRecordedError(error);
1265
+ throw error;
1266
+ }
1267
+ if (!streamed) {
1268
+ effect.response = toJson(result);
1269
+ return result;
1270
+ }
1271
+ const parts = [];
1272
+ effect.stream = parts;
1273
+ if (seam === "openai") {
1274
+ const source = result;
1275
+ return (async function* () {
1276
+ for await (const chunk of source) {
1277
+ parts.push(toJson(chunk));
1278
+ yield chunk;
1279
+ }
1280
+ })();
1281
+ }
1282
+ const { stream, ...rest } = result;
1283
+ effect.response = toJson(rest);
1284
+ return {
1285
+ ...rest,
1286
+ stream: stream.pipeThrough(new TransformStream({ transform(part, controller) {
1287
+ parts.push(toJson(part));
1288
+ controller.enqueue(part);
1289
+ } }))
1290
+ };
1291
+ }
1292
+ /** `inputOf` picks the recorded input from the call's arguments. */
1293
+ function tool(name, fn, inputOf = (args) => args.length === 1 ? args[0] : args) {
1294
+ return ((...args) => {
1295
+ const input = toJson(inputOf(args));
1296
+ const effect = {
1297
+ kind: "tool",
1298
+ name,
1299
+ step: modelCalls,
1300
+ input,
1301
+ ...toolsInFlight > 0 ? { concurrent: true } : {}
1302
+ };
1303
+ effects.push(effect);
1304
+ return track(call(effect, args));
1305
+ });
1306
+ function call(effect, args) {
1307
+ const { input } = effect;
1308
+ if (replay && options.tools !== "live") {
1309
+ const wanted = normalizeEffect(effect).input;
1310
+ const recorded = replay.find((candidate) => candidate.kind === "tool" && !usedTools.has(candidate) && candidate.step === effect.step && candidate.name === name && jsonEqual(normalizeEffect(candidate).input, wanted));
1311
+ const settle = (value) => {
1312
+ if (recorded?.sync) return value();
1313
+ try {
1314
+ return Promise.resolve(value());
1315
+ } catch (error) {
1316
+ return Promise.reject(error);
1317
+ }
1318
+ };
1319
+ return settle(() => {
1320
+ if (!recorded) {
1321
+ const error = new RecordingDivergenceError(`Tool '${name}' was called with ${JSON.stringify(input)} ${effect.step === 0 ? "before any model call" : `after model call #${effect.step - 1}`}; the recorded run made no such call.`);
1322
+ effect.error = toRecordedError(error);
1323
+ throw error;
1324
+ }
1325
+ usedTools.add(recorded);
1326
+ if (recorded.sync) effect.sync = true;
1327
+ if (recorded.error) {
1328
+ effect.error = recorded.error;
1329
+ throw fromRecordedError(recorded.error);
1330
+ }
1331
+ effect.output = recorded.output;
1332
+ return structuredClone(recorded.output);
1333
+ });
1334
+ }
1335
+ let output;
1336
+ try {
1337
+ output = fn(...args);
1338
+ } catch (error) {
1339
+ effect.sync = true;
1340
+ effect.error = toRecordedError(error);
1341
+ throw error;
1342
+ }
1343
+ if (!(output instanceof Promise)) {
1344
+ effect.sync = true;
1345
+ effect.output = toJson(output);
1346
+ return output;
1347
+ }
1348
+ return output.then((value) => {
1349
+ effect.output = toJson(value);
1350
+ return value;
1351
+ }, (error) => {
1352
+ effect.error = toRecordedError(error);
1353
+ throw error;
1354
+ });
1355
+ }
1356
+ }
1357
+ /** Counts an async tool call as running until it settles. */
1358
+ function track(result) {
1359
+ if (result instanceof Promise) {
1360
+ toolsInFlight++;
1361
+ const settled = () => {
1362
+ toolsInFlight--;
1363
+ };
1364
+ result.then(settled, settled);
1365
+ }
1366
+ return result;
1367
+ }
1368
+ return {
1369
+ model(model) {
1370
+ const base = model;
1371
+ const wrapped = Object.create(base);
1372
+ wrapped["doGenerate"] = (callOptions) => modelCall("ai-sdk", "doGenerate", callOptions, false, () => base["doGenerate"].call(base, callOptions));
1373
+ wrapped["doStream"] = (callOptions) => modelCall("ai-sdk", "doStream", callOptions, true, () => base["doStream"].call(base, callOptions));
1374
+ return wrapped;
1375
+ },
1376
+ openai(client) {
1377
+ const wrapCreate = (resource, method) => new Proxy(resource, { get(target, key, receiver) {
1378
+ if (key !== "create") return Reflect.get(target, key, receiver);
1379
+ return (params, requestOptions) => {
1380
+ let api;
1381
+ const promise = modelCall("openai", method, params, params?.stream === true, () => {
1382
+ api = Reflect.get(target, "create").call(target, params, requestOptions);
1383
+ return Promise.resolve(api);
1384
+ });
1385
+ return Object.assign(promise, { withResponse: async () => {
1386
+ const data = await promise;
1387
+ const meta = await api?.withResponse?.();
1388
+ return {
1389
+ data,
1390
+ response: meta?.response ?? new Response(null),
1391
+ request_id: meta?.request_id ?? null
1392
+ };
1393
+ } });
1394
+ };
1395
+ } });
1396
+ const wrapped = /* @__PURE__ */ new Map();
1397
+ const wrap = (key, make) => {
1398
+ if (!wrapped.has(key)) wrapped.set(key, make());
1399
+ return wrapped.get(key);
1400
+ };
1401
+ return new Proxy(client, { get(target, key, receiver) {
1402
+ const value = Reflect.get(target, key, receiver);
1403
+ if (key === "responses" && value) return wrap(key, () => wrapCreate(value, "responses.create"));
1404
+ if (key === "chat" && value) return wrap(key, () => new Proxy(value, { get(chat, chatKey, chatReceiver) {
1405
+ const inner = Reflect.get(chat, chatKey, chatReceiver);
1406
+ return chatKey === "completions" && inner ? wrap("chat.completions", () => wrapCreate(inner, "chat.completions.create")) : inner;
1407
+ } }));
1408
+ return value;
1409
+ } });
1410
+ },
1411
+ tool: (name, fn) => tool(name, fn),
1412
+ tools(tools) {
1413
+ return Object.fromEntries(Object.entries(tools).map(([name, definition]) => [name, definition.execute ? {
1414
+ ...definition,
1415
+ execute: tool(name, definition.execute, (args) => args[0])
1416
+ } : definition]));
1417
+ },
1418
+ output(value) {
1419
+ effects.push({
1420
+ kind: "output",
1421
+ value: toJson(value)
1422
+ });
1423
+ },
1424
+ get recording() {
1425
+ return {
1426
+ version: 1,
1427
+ effects: toJson(effects)
1428
+ };
1429
+ }
1430
+ };
1431
+ }
1432
+ /** True when two model calls offer the same tool names and response format. */
1433
+ function sameModelCallShape(expected, actual) {
1434
+ return jsonEqual(modelCallShape(expected), modelCallShape(actual));
1435
+ }
1436
+ function modelCallsMatch(match, expected, actual) {
1437
+ if (match === "none") return true;
1438
+ if (typeof match === "function") return match(expected, actual);
1439
+ return sameModelCallShape(expected, actual);
1440
+ }
1441
+ function shapeMessage(expected, actual) {
1442
+ return `Model call #${expected.call} changed shape: ${JSON.stringify(modelCallShape(expected))} → ${JSON.stringify(modelCallShape(actual))}. A recorded answer only fits a call of the same shape.`;
1443
+ }
1444
+ /** Offered tool names and the response format: what a recorded answer depends on. */
1445
+ function modelCallShape(effect) {
1446
+ const request = effect.request ?? {};
1447
+ return {
1448
+ tools: (Array.isArray(request["tools"]) ? request["tools"] : []).map((tool) => tool["name"] ?? tool["function"]?.["name"]).sort(),
1449
+ format: request["responseFormat"]?.["type"] ?? request["response_format"]?.["type"] ?? (request["text"]?.["format"])?.["type"] ?? "text"
1450
+ };
1451
+ }
1452
+ /**
1453
+ * Puts each group of concurrent tool calls in a stable order, so parallel tool
1454
+ * calls that finished in a different order still compare equal. A tool call
1455
+ * that started after the previous one settled begins a new group, so
1456
+ * sequential calls keep their order.
1457
+ */
1458
+ function normalize(effects) {
1459
+ const result = [];
1460
+ let batch = [];
1461
+ const flush = () => {
1462
+ result.push(...batch.sort((a, b) => stableStringify([a.name, a.input]).localeCompare(stableStringify([b.name, b.input]))));
1463
+ batch = [];
1464
+ };
1465
+ for (const effect of effects) {
1466
+ if (effect.kind !== "tool" || !effect.concurrent) flush();
1467
+ if (effect.kind === "tool") batch.push(effect);
1468
+ else result.push(effect);
1469
+ }
1470
+ flush();
1471
+ return result;
1472
+ }
1473
+ function describe(effect) {
1474
+ switch (effect.kind) {
1475
+ case "model": return `model call #${effect.call} (${effect.method})`;
1476
+ case "tool": return `tool '${effect.name}' with ${JSON.stringify(effect.input)}`;
1477
+ case "output": return `output ${JSON.stringify(effect.value)}`;
1478
+ }
1479
+ }
1480
+ /** Why two effects differ, or `undefined` when they are the same. */
1481
+ function differ(left, right, options) {
1482
+ if (left.kind !== right.kind) return {
1483
+ reason: "kind",
1484
+ message: `Expected ${describe(left)}; the port made ${describe(right)}.`
1485
+ };
1486
+ if (left.kind === "model" && right.kind === "model") {
1487
+ if (left.method !== right.method) return {
1488
+ reason: "model-method",
1489
+ message: `Model call #${left.call} used ${left.method}; the port used ${right.method}.`
1490
+ };
1491
+ if (!modelCallsMatch(options.modelCalls, left, right)) return {
1492
+ reason: "model-call-shape",
1493
+ message: shapeMessage(left, right)
1494
+ };
1495
+ if (!jsonEqual(left.error, right.error)) {
1496
+ const outcome = (error) => error ? `failed with ${error.name}: ${error.message}` : "succeeded";
1497
+ return {
1498
+ reason: "model-error",
1499
+ message: `Model call #${left.call} ${outcome(left.error)}; in the port it ${outcome(right.error)}.`
1500
+ };
1501
+ }
1502
+ return;
1503
+ }
1504
+ if (left.kind === "tool" && right.kind === "tool") {
1505
+ if (left.name !== right.name) return {
1506
+ reason: "tool-name",
1507
+ message: `Expected ${describe(left)}; the port made ${describe(right)}.`
1508
+ };
1509
+ if (!jsonEqual(left.input, right.input)) return {
1510
+ reason: "tool-input",
1511
+ message: `Expected ${describe(left)}; the port passed ${JSON.stringify(right.input)}.`
1512
+ };
1513
+ if (!jsonEqual(left.output, right.output) || !jsonEqual(left.error, right.error)) return {
1514
+ reason: "tool-result",
1515
+ message: `Tool '${left.name}' returned a different result.`
1516
+ };
1517
+ return;
1518
+ }
1519
+ if (left.kind === "output" && right.kind === "output" && !jsonEqual(left.value, right.value)) return {
1520
+ reason: "output",
1521
+ message: `Expected ${describe(left)}; the port returned ${JSON.stringify(right.value)}.`
1522
+ };
1523
+ }
1524
+ /**
1525
+ * Compares two recordings and reports every effect that differs. `expected`
1526
+ * is the original's recording, `actual` the port's. Effects that are the same
1527
+ * on both sides are lined up first (longest common subsequence), so one extra
1528
+ * call does not shift every effect after it; between them, effects of the same
1529
+ * kind pair up and report what changed, and the rest are missing or extra.
1530
+ */
1531
+ function compareRecordings(expected, actual, options = {}) {
1532
+ const map = options.normalize ?? ((effect) => effect);
1533
+ const a = normalize(expected.effects.map(map));
1534
+ const b = normalize(actual.effects.map(map));
1535
+ const same = a.map((left) => b.map((right) => !differ(left, right, options)));
1536
+ const lcs = Array.from({ length: a.length + 1 }, () => Array.from({ length: b.length + 1 }, () => 0));
1537
+ for (let i = a.length - 1; i >= 0; i--) for (let j = b.length - 1; j >= 0; j--) lcs[i][j] = same[i][j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
1538
+ const divergences = [];
1539
+ let lefts = [];
1540
+ let rights = [];
1541
+ const flushGap = (at) => {
1542
+ const unpairedRights = [...rights];
1543
+ const changed = [];
1544
+ for (const index of lefts) {
1545
+ const left = a[index];
1546
+ const k = unpairedRights.findIndex((j) => b[j].kind === left.kind);
1547
+ if (k === -1) {
1548
+ changed.push({
1549
+ index,
1550
+ reason: "missing-effect",
1551
+ expected: left,
1552
+ message: `The port never made ${describe(left)}.`
1553
+ });
1554
+ continue;
1555
+ }
1556
+ const right = b[unpairedRights.splice(k, 1)[0]];
1557
+ const difference = differ(left, right, options);
1558
+ if (difference) changed.push({
1559
+ index,
1560
+ expected: left,
1561
+ actual: right,
1562
+ ...difference
1563
+ });
1564
+ }
1565
+ for (const j of unpairedRights) divergences.push({
1566
+ index: lefts[0] ?? at,
1567
+ reason: "extra-effect",
1568
+ actual: b[j],
1569
+ message: `The port made ${describe(b[j])}, which the original never made.`
1570
+ });
1571
+ divergences.push(...changed);
1572
+ lefts = [];
1573
+ rights = [];
1574
+ };
1575
+ let i = 0;
1576
+ let j = 0;
1577
+ while (i < a.length || j < b.length) if (i < a.length && j < b.length && same[i][j]) {
1578
+ flushGap(i);
1579
+ i++;
1580
+ j++;
1581
+ } else if (j < b.length && (i === a.length || lcs[i][j + 1] >= lcs[i + 1][j])) rights.push(j++);
1582
+ else lefts.push(i++);
1583
+ flushGap(i);
1584
+ divergences.sort((x, y) => x.index - y.index);
1585
+ return divergences.length ? {
1586
+ equivalent: false,
1587
+ divergence: divergences[0],
1588
+ divergences
1589
+ } : {
1590
+ equivalent: true,
1591
+ divergences
1592
+ };
1593
+ }
1594
+ //#endregion
1595
+ export { AgentLintError, AgentUnknownStateError, RecordingDivergenceError, assertAgentMachine, canReach, compareRecordings, compareRuns, createRecorder, explorePaths, firstDivergence, foldTraces, getDecisionRequests, judgeAgreement, lintAgentMachine, matchesTrajectory, repeatRuns, runSeam, sameModelCallShape, simulateAgent, summarizeRepeats, traceCoverage };
@@ -402,14 +402,35 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
402
402
  * …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
403
403
  * report this attempt's tokens there and the runtime folds them into the run's
404
404
  * aggregated {@link AgentUsage}.
405
+ *
406
+ * An answer that names no valid event (no tool call, a tool that was not
407
+ * offered, arguments that are not JSON) is returned as `rejected` instead of
408
+ * `event`: {@link resolveDecision} records it as a failed attempt with that
409
+ * reason and asks again.
405
410
  */
406
- type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
411
+ type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<({
407
412
  event: ChosenEvent;
413
+ rejected?: undefined;
414
+ } | {
415
+ event?: undefined;
416
+ rejected: AgentDecisionRejection;
417
+ }) & {
408
418
  reason?: string;
409
419
  /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
410
420
  usage?: AgentCallUsage;
411
421
  [key: string]: unknown;
412
422
  }>;
423
+ /**
424
+ * An answer a decide executor could not read as a candidate event, returned as
425
+ * `rejected` (see {@link AgentDecisionExecutor}). `reason` is fed back to the
426
+ * model as written.
427
+ */
428
+ type AgentDecisionRejection = {
429
+ failure: "unknown-event" | "invalid-payload";
430
+ reason: string;
431
+ /** What the model sent, as far as it could be read. */
432
+ event?: ChosenEvent;
433
+ };
413
434
  /**
414
435
  * Options for {@link resolveDecision}. The `TEvent` parameter (the machine's
415
436
  * event union, defaulting to the loose {@link ChosenEvent}) types both
@@ -784,6 +805,8 @@ type AgentRequestExecutorResult<TOutput = unknown, TMessage = unknown> = {
784
805
  usage?: AgentCallUsage;
785
806
  /** Why this call stopped, normalized (see {@link AgentFinishReason}). Surfaced on the `request.end` trace event. */
786
807
  finishReason?: AgentFinishReason;
808
+ /** Provider calls this request made: a tool loop's steps. Default 1. Counted in `usage.modelCalls` and against `maxModelCalls`. */
809
+ modelCalls?: number;
787
810
  [key: string]: unknown;
788
811
  };
789
812
  /**
@@ -816,7 +839,9 @@ interface AgentRequestExecutorInfo {
816
839
  * the first attempt's result instead of paying for it twice. A decision
817
840
  * retry appends its attempt ordinal (`${executionId}:${requestId}#${n}.${a}`,
818
841
  * `a` being the number of prior failed attempts), so a retry never collides
819
- * with the rejected attempt it is replacing.
842
+ * with the rejected attempt it is replacing. A call inside an invoked child
843
+ * machine is keyed under the root-level child that owns it:
844
+ * `${executionId}:${childId}#${m}/${requestId}#${k}`.
820
845
  *
821
846
  * It identifies the CALL SITE, not the request: a version bridge keeps the
822
847
  * lineage id, so a migrated machine can ask something else under the same
@@ -907,4 +932,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
907
932
  */
908
933
  declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
909
934
  //#endregion
910
- export { AgentTruncatedError as $, AgentDecisionExhaustedError as A, createDecisionLogic as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, CreateDecisionRequestOptions as F, AgentInvalidEventPayloadError as G, renderDecisionAttempts as H, DecisionAttempt as I, AgentSchemas as J, AgentRequestOptions as K, DecisionLogic as L, AgentDecisionOption as M, AgentDecisionRequest as N, providerOutputSchema as O, AgentExecutorDecisionRequest as P, AgentError as Q, DecisionLogicConfig as R, createTextLogic as S, getCallUsage as T, resolveDecision as U, createDecisionRequest as V, AgentEventDescriptor as W, getAcceptedEvents as X, EventFromSnapshot as Y, parseAgentEvent as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentRequestSource as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, ResolveDecisionOptions as z };
935
+ export { AgentError as $, AgentDecisionExhaustedError as A, ResolveDecisionOptions as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentExecutorDecisionRequest as F, AgentEventDescriptor as G, createDecisionRequest as H, CreateDecisionRequestOptions as I, AgentRequestSource as J, AgentInvalidEventPayloadError as K, DecisionAttempt as L, AgentDecisionOption as M, AgentDecisionRejection as N, providerOutputSchema as O, AgentDecisionRequest as P, parseAgentEvent as Q, DecisionLogic as R, createTextLogic as S, getCallUsage as T, renderDecisionAttempts as U, createDecisionLogic as V, resolveDecision as W, EventFromSnapshot as X, AgentSchemas as Y, getAcceptedEvents as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTruncatedError as et, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentRequestOptions as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, DecisionLogicConfig as z };