@statelyai/agent 2.0.0-alpha.39 → 2.0.0-alpha.41

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 (45) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/dist/evals.cjs +1 -1
  3. package/dist/evals.d.cts +1 -1
  4. package/dist/evals.d.mts +1 -1
  5. package/dist/evals.mjs +1 -1
  6. package/dist/index.cjs +17 -10
  7. package/dist/index.d.cts +29 -12
  8. package/dist/index.d.mts +29 -12
  9. package/dist/index.mjs +17 -10
  10. package/dist/machine-input-0YTPcnCm.mjs +27 -0
  11. package/dist/machine-input-DU3owLUr.cjs +32 -0
  12. package/dist/otel.d.cts +1 -1
  13. package/dist/otel.d.mts +1 -1
  14. package/dist/policy.cjs +1 -1
  15. package/dist/policy.d.cts +1 -1
  16. package/dist/policy.d.mts +1 -1
  17. package/dist/policy.mjs +1 -1
  18. package/dist/{run-agent-Dq0oSFRm.d.cts → run-agent-BO9RSb7i.d.cts} +16 -7
  19. package/dist/{run-agent-DHlq87G7.d.mts → run-agent-BxkeuAYR.d.mts} +16 -7
  20. package/dist/{run-agent-De3xVFGw.cjs → run-agent-COdR9FpM.cjs} +26 -27
  21. package/dist/{run-agent-BE7DOWD6.mjs → run-agent-D3gW9wfd.mjs} +27 -28
  22. package/dist/testing.cjs +377 -18
  23. package/dist/testing.d.cts +181 -5
  24. package/dist/testing.d.mts +181 -5
  25. package/dist/testing.mjs +377 -20
  26. package/dist/{utils-DAclF-kw.d.cts → utils-BMxUcjay.d.cts} +57 -1
  27. package/dist/{utils-B8k-YPYI.d.mts → utils-BV7pxhD-.d.mts} +57 -1
  28. package/dist/validate.cjs +1 -1
  29. package/dist/validate.d.cts +1 -1
  30. package/dist/validate.d.mts +1 -1
  31. package/dist/validate.mjs +1 -1
  32. package/dist/{verify-H3Pr2gNw.d.mts → verify-C1UU84eq.d.mts} +22 -2
  33. package/dist/{verify-BM0sGmsf.d.cts → verify-DlN6tK8_.d.cts} +22 -2
  34. package/dist/{verify-Dek6gHCS.cjs → verify-IVYsI026.cjs} +84 -17
  35. package/dist/{verify-CWlg3j7B.mjs → verify-lKyu3buS.mjs} +84 -17
  36. package/docs/evals.md +1 -0
  37. package/docs/hosts.md +5 -3
  38. package/docs/index.md +2 -2
  39. package/docs/meta.json +1 -0
  40. package/docs/strangler-fig.md +36 -29
  41. package/docs/verify-in-place.md +326 -0
  42. package/docs/verify.md +70 -4
  43. package/llms.txt +1 -0
  44. package/package.json +1 -1
  45. package/readme.md +1 -0
@@ -39,6 +39,23 @@ interface RecordedModelCall {
39
39
  /** The stream's parts or chunks, in order. */
40
40
  stream?: unknown[];
41
41
  error?: RecordedError;
42
+ /**
43
+ * This call failed, and model call `retriedBy` sent the same request after
44
+ * it: a retry, by the AI SDK (`maxRetries`) or by the code. Compare
45
+ * {@link RecordedModelCall.aiSdkCall} to tell which.
46
+ */
47
+ retriedBy?: number;
48
+ /**
49
+ * The 0-based `generateText` or `streamText` call this attempt belongs to,
50
+ * when {@link recordAiSdk} routed that call. Attempts with the same value
51
+ * are one call the code made: its tool-loop steps and the SDK's retries. A
52
+ * failed attempt whose `retriedBy` attempt has the same `aiSdkCall` was
53
+ * retried by the SDK; one with a different `aiSdkCall` was resent by the code.
54
+ * Absent when the attempt was not routed through `recordAiSdk`, or its model
55
+ * was not a `recorder.model` wrapper passed as is (a proxy around one, one
56
+ * with a replaced method): who resent it is then unknown.
57
+ */
58
+ aiSdkCall?: number;
42
59
  /** In replay, the recorded call (its `call`) whose answer served this one. */
43
60
  replayed?: number;
44
61
  /** In replay, `translate` adapted the recorded answer to this call. */
@@ -254,6 +271,45 @@ interface Recorder {
254
271
  /** What this run did so far. */
255
272
  readonly recording: Recording;
256
273
  }
274
+ /** What {@link recordAiSdk} routes an AI SDK call through. */
275
+ interface AiSdkSeam {
276
+ recorder: Recorder;
277
+ /**
278
+ * Replaces the model the code passes, such as `openai("gpt-…")` built inline.
279
+ * Pass `recorder.model(standIn)`, so the stand-in's calls are recorded.
280
+ */
281
+ model?: unknown;
282
+ }
283
+ /**
284
+ * Records AI SDK code that builds its model inline or passes module-level
285
+ * tools to `generateText`: there is nothing to inject, so the test mocks `"ai"`
286
+ * and routes each call through the recorder. Every `generateText` and
287
+ * `streamText` call runs on the real AI SDK with `seam.model` in place of the
288
+ * code's model (also in place of a model `prepareStep` returns) and its
289
+ * `tools` wrapped with `recorder.tools`. Everything else in `"ai"` stays real,
290
+ * so the code's own tool loop runs.
291
+ *
292
+ * Each model attempt made during the call carries the call's index as
293
+ * {@link RecordedModelCall.aiSdkCall} when its model is a `recorder.model`
294
+ * wrapper passed as is and the recorder came from `createRecorder`. Other
295
+ * attempts carry no index, and who resent them is unknown.
296
+ *
297
+ * `current` returns the seam of the run being recorded. A call while it returns
298
+ * `undefined` throws, so no test reaches a real provider.
299
+ *
300
+ * @example
301
+ * ```ts
302
+ * vi.mock("ai", async (importOriginal) => {
303
+ * const ai = await importOriginal<typeof import("ai")>();
304
+ * const { currentSeam } = await import("./seam"); // { recorder, model: recorder.model(standIn) }
305
+ * return { ...ai, ...recordAiSdk(ai, currentSeam) };
306
+ * });
307
+ * ```
308
+ */
309
+ declare function recordAiSdk<TAi extends {
310
+ generateText: AnyFunction;
311
+ streamText?: AnyFunction;
312
+ }>(ai: TAi, current: () => AiSdkSeam | undefined): Pick<TAi, "generateText" | "streamText">;
257
313
  /**
258
314
  * Thrown in replay when the port asks for something the recording cannot
259
315
  * answer: a model call past the last recorded one, or a tool call the original
@@ -406,4 +462,4 @@ declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string
406
462
  */
407
463
  declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
408
464
  //#endregion
409
- export { RecordedToolCall as A, RecordableLanguageModel as C, RecordedError as D, RecordedEffect as E, createRecorder as F, sameModelCallShape as I, Recording as M, RecordingDivergenceError as N, RecordedModelCall as O, compareRecordings as P, RecordableDecisionModel as S, RecordedCall as T, ModelAnswer as _, getMessageText as a, RecordCallOptions as b, isStandardSchema as c, userMessage as d, CompareRecordingsOptions as f, EquivalenceReport as g, EffectDivergenceReason as h, getJsonSchemaSync as i, Recorder as j, RecordedOutput as k, systemMessage as l, EffectDivergence as m, assistantMessage as n, getStateMeta as o, CreateRecorderOptions as p, getJsonSchema as r, getStatePath as s, MetaOfSnapshot as t, toolMessage as u, ModelCallMatch as v, RecordableModel as w, RecordClientOptions as x, NormalizeEffect as y };
465
+ export { RecordedOutput as A, RecordableDecisionModel as C, RecordedEffect as D, RecordedCall as E, compareRecordings as F, createRecorder as I, recordAiSdk as L, Recorder as M, Recording as N, RecordedError as O, RecordingDivergenceError as P, sameModelCallShape as R, RecordClientOptions as S, RecordableModel as T, EquivalenceReport as _, getMessageText as a, NormalizeEffect as b, isStandardSchema as c, userMessage as d, AiSdkSeam as f, EffectDivergenceReason as g, EffectDivergence as h, getJsonSchemaSync as i, RecordedToolCall as j, RecordedModelCall as k, systemMessage as l, CreateRecorderOptions as m, assistantMessage as n, getStateMeta as o, CompareRecordingsOptions as p, getJsonSchema as r, getStatePath as s, MetaOfSnapshot as t, toolMessage as u, ModelAnswer as v, RecordableLanguageModel as w, RecordCallOptions as x, ModelCallMatch as y };
@@ -39,6 +39,23 @@ interface RecordedModelCall {
39
39
  /** The stream's parts or chunks, in order. */
40
40
  stream?: unknown[];
41
41
  error?: RecordedError;
42
+ /**
43
+ * This call failed, and model call `retriedBy` sent the same request after
44
+ * it: a retry, by the AI SDK (`maxRetries`) or by the code. Compare
45
+ * {@link RecordedModelCall.aiSdkCall} to tell which.
46
+ */
47
+ retriedBy?: number;
48
+ /**
49
+ * The 0-based `generateText` or `streamText` call this attempt belongs to,
50
+ * when {@link recordAiSdk} routed that call. Attempts with the same value
51
+ * are one call the code made: its tool-loop steps and the SDK's retries. A
52
+ * failed attempt whose `retriedBy` attempt has the same `aiSdkCall` was
53
+ * retried by the SDK; one with a different `aiSdkCall` was resent by the code.
54
+ * Absent when the attempt was not routed through `recordAiSdk`, or its model
55
+ * was not a `recorder.model` wrapper passed as is (a proxy around one, one
56
+ * with a replaced method): who resent it is then unknown.
57
+ */
58
+ aiSdkCall?: number;
42
59
  /** In replay, the recorded call (its `call`) whose answer served this one. */
43
60
  replayed?: number;
44
61
  /** In replay, `translate` adapted the recorded answer to this call. */
@@ -254,6 +271,45 @@ interface Recorder {
254
271
  /** What this run did so far. */
255
272
  readonly recording: Recording;
256
273
  }
274
+ /** What {@link recordAiSdk} routes an AI SDK call through. */
275
+ interface AiSdkSeam {
276
+ recorder: Recorder;
277
+ /**
278
+ * Replaces the model the code passes, such as `openai("gpt-…")` built inline.
279
+ * Pass `recorder.model(standIn)`, so the stand-in's calls are recorded.
280
+ */
281
+ model?: unknown;
282
+ }
283
+ /**
284
+ * Records AI SDK code that builds its model inline or passes module-level
285
+ * tools to `generateText`: there is nothing to inject, so the test mocks `"ai"`
286
+ * and routes each call through the recorder. Every `generateText` and
287
+ * `streamText` call runs on the real AI SDK with `seam.model` in place of the
288
+ * code's model (also in place of a model `prepareStep` returns) and its
289
+ * `tools` wrapped with `recorder.tools`. Everything else in `"ai"` stays real,
290
+ * so the code's own tool loop runs.
291
+ *
292
+ * Each model attempt made during the call carries the call's index as
293
+ * {@link RecordedModelCall.aiSdkCall} when its model is a `recorder.model`
294
+ * wrapper passed as is and the recorder came from `createRecorder`. Other
295
+ * attempts carry no index, and who resent them is unknown.
296
+ *
297
+ * `current` returns the seam of the run being recorded. A call while it returns
298
+ * `undefined` throws, so no test reaches a real provider.
299
+ *
300
+ * @example
301
+ * ```ts
302
+ * vi.mock("ai", async (importOriginal) => {
303
+ * const ai = await importOriginal<typeof import("ai")>();
304
+ * const { currentSeam } = await import("./seam"); // { recorder, model: recorder.model(standIn) }
305
+ * return { ...ai, ...recordAiSdk(ai, currentSeam) };
306
+ * });
307
+ * ```
308
+ */
309
+ declare function recordAiSdk<TAi extends {
310
+ generateText: AnyFunction;
311
+ streamText?: AnyFunction;
312
+ }>(ai: TAi, current: () => AiSdkSeam | undefined): Pick<TAi, "generateText" | "streamText">;
257
313
  /**
258
314
  * Thrown in replay when the port asks for something the recording cannot
259
315
  * answer: a model call past the last recorded one, or a tool call the original
@@ -406,4 +462,4 @@ declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string
406
462
  */
407
463
  declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
408
464
  //#endregion
409
- export { RecordedToolCall as A, RecordableLanguageModel as C, RecordedError as D, RecordedEffect as E, createRecorder as F, sameModelCallShape as I, Recording as M, RecordingDivergenceError as N, RecordedModelCall as O, compareRecordings as P, RecordableDecisionModel as S, RecordedCall as T, ModelAnswer as _, getMessageText as a, RecordCallOptions as b, isStandardSchema as c, userMessage as d, CompareRecordingsOptions as f, EquivalenceReport as g, EffectDivergenceReason as h, getJsonSchemaSync as i, Recorder as j, RecordedOutput as k, systemMessage as l, EffectDivergence as m, assistantMessage as n, getStateMeta as o, CreateRecorderOptions as p, getJsonSchema as r, getStatePath as s, MetaOfSnapshot as t, toolMessage as u, ModelCallMatch as v, RecordableModel as w, RecordClientOptions as x, NormalizeEffect as y };
465
+ export { RecordedOutput as A, RecordableDecisionModel as C, RecordedEffect as D, RecordedCall as E, compareRecordings as F, createRecorder as I, recordAiSdk as L, Recorder as M, Recording as N, RecordedError as O, RecordingDivergenceError as P, sameModelCallShape as R, RecordClientOptions as S, RecordableModel as T, EquivalenceReport as _, getMessageText as a, NormalizeEffect as b, isStandardSchema as c, userMessage as d, AiSdkSeam as f, EffectDivergenceReason as g, EffectDivergence as h, getJsonSchemaSync as i, RecordedToolCall as j, RecordedModelCall as k, systemMessage as l, CreateRecorderOptions as m, assistantMessage as n, getStateMeta as o, CompareRecordingsOptions as p, getJsonSchema as r, getStatePath as s, MetaOfSnapshot as t, toolMessage as u, ModelAnswer as v, RecordableLanguageModel as w, RecordCallOptions as x, ModelCallMatch as y };
package/dist/validate.cjs CHANGED
@@ -24,7 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
24
24
  const require_event_log = require("./event-log-dSOnXHuG.cjs");
25
25
  const require_decision = require("./decision-D8bcIGXQ.cjs");
26
26
  const require_setup_agent = require("./setup-agent-Dv5VpuHe.cjs");
27
- const require_verify = require("./verify-Dek6gHCS.cjs");
27
+ const require_verify = require("./verify-IVYsI026.cjs");
28
28
  let ajv_dist_2020_js = require("ajv/dist/2020.js");
29
29
  ajv_dist_2020_js = __toESM(ajv_dist_2020_js, 1);
30
30
  //#region schemas/agent-workflow.json
@@ -1,4 +1,4 @@
1
- import { d as ExplorePathsOptions } from "./verify-BM0sGmsf.cjs";
1
+ import { d as ExplorePathsOptions } from "./verify-DlN6tK8_.cjs";
2
2
  import { _ as FromConfigOptions, f as AgentWorkflowConfig, y as SchemaCompiler } from "./setup-agent-Cv8Hk3mX.cjs";
3
3
  import { AnyActorLogic, AnyStateMachine } from "xstate";
4
4
  //#region src/validate/validate-config.d.ts
@@ -1,4 +1,4 @@
1
- import { d as ExplorePathsOptions } from "./verify-H3Pr2gNw.mjs";
1
+ import { d as ExplorePathsOptions } from "./verify-C1UU84eq.mjs";
2
2
  import { _ as FromConfigOptions, f as AgentWorkflowConfig, y as SchemaCompiler } from "./setup-agent-DgFAhaPJ.mjs";
3
3
  import { AnyActorLogic, AnyStateMachine } from "xstate";
4
4
  //#region src/validate/validate-config.d.ts
package/dist/validate.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  import { D as DECIDE_ACTOR, O as GENERATE_TEXT_ACTOR, T as ACT_ACTOR, k as STREAM_TEXT_ACTOR } from "./event-log-CEq_bVXQ.mjs";
2
2
  import { p as payloadNeedsFillModel } from "./decision-B41YBx5U.mjs";
3
3
  import { i as setupAgentFromConfig } from "./setup-agent-CLm6QVGy.mjs";
4
- import { a as explorePaths, s as lintAgentMachine } from "./verify-CWlg3j7B.mjs";
4
+ import { a as explorePaths, s as lintAgentMachine } from "./verify-lKyu3buS.mjs";
5
5
  import Ajv2020 from "ajv/dist/2020.js";
6
6
  //#region schemas/agent-workflow.json
7
7
  var agent_workflow_default = {
@@ -169,6 +169,11 @@ interface SimulationTrailEntry {
169
169
  }
170
170
  /** Options for {@link simulateAgent}. */
171
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
+ */
172
177
  input?: unknown;
173
178
  script: SimulationScript;
174
179
  /** Max steps before returning `'exhausted'`. Default 100. */
@@ -268,12 +273,21 @@ interface ExploreStep {
268
273
  interface CanReachOrdering {
269
274
  /** The trigger: an event type, or a step predicate. */
270
275
  after: string | ((step: ExploreStep) => boolean);
271
- /** Checked on every step after the first `after` step, not on that step itself. */
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
+ */
272
281
  reach: (step: ExploreStep) => boolean;
273
282
  }
274
283
  /** What {@link canReach} looks for: a state id or path, a snapshot predicate, or an ordering. */
275
284
  type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean) | CanReachOrdering;
276
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
+ */
277
291
  input?: unknown;
278
292
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
279
293
  maxDepth?: number;
@@ -453,7 +467,13 @@ interface ExplorePathsOptions {
453
467
  * at a shallower depth), so payload and output branching that converges
454
468
  * stays tractable. Return everything a guard, choice, or output reads:
455
469
  * a key that drops a field the machine reads makes the search unsound.
456
- * Without it, every path is explored in full.
470
+ * Without it, `explorePaths` explores every path in full, and `canReach`
471
+ * uses a default key: the state value, context, status, history, pending
472
+ * requests and their invoke inputs, children and their inputs, armed
473
+ * timers, and coupled children's states. A step whose context or inputs
474
+ * are not plain data (a `Map`, a class instance) is not deduplicated. The
475
+ * key holds structure, not identity: a guard that compares context with an
476
+ * object held outside the snapshot needs its own `dedupeBy`.
457
477
  */
458
478
  dedupeBy?: (snapshot: ExploreSnapshot) => string;
459
479
  /**
@@ -169,6 +169,11 @@ interface SimulationTrailEntry {
169
169
  }
170
170
  /** Options for {@link simulateAgent}. */
171
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
+ */
172
177
  input?: unknown;
173
178
  script: SimulationScript;
174
179
  /** Max steps before returning `'exhausted'`. Default 100. */
@@ -268,12 +273,21 @@ interface ExploreStep {
268
273
  interface CanReachOrdering {
269
274
  /** The trigger: an event type, or a step predicate. */
270
275
  after: string | ((step: ExploreStep) => boolean);
271
- /** Checked on every step after the first `after` step, not on that step itself. */
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
+ */
272
281
  reach: (step: ExploreStep) => boolean;
273
282
  }
274
283
  /** What {@link canReach} looks for: a state id or path, a snapshot predicate, or an ordering. */
275
284
  type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean) | CanReachOrdering;
276
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
+ */
277
291
  input?: unknown;
278
292
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
279
293
  maxDepth?: number;
@@ -453,7 +467,13 @@ interface ExplorePathsOptions {
453
467
  * at a shallower depth), so payload and output branching that converges
454
468
  * stays tractable. Return everything a guard, choice, or output reads:
455
469
  * a key that drops a field the machine reads makes the search unsound.
456
- * Without it, every path is explored in full.
470
+ * Without it, `explorePaths` explores every path in full, and `canReach`
471
+ * uses a default key: the state value, context, status, history, pending
472
+ * requests and their invoke inputs, children and their inputs, armed
473
+ * timers, and coupled children's states. A step whose context or inputs
474
+ * are not plain data (a `Map`, a class instance) is not deduplicated. The
475
+ * key holds structure, not identity: a guard that compares context with an
476
+ * object held outside the snapshot needs its own `dedupeBy`.
457
477
  */
458
478
  dedupeBy?: (snapshot: ExploreSnapshot) => string;
459
479
  /**
@@ -1,5 +1,6 @@
1
1
  const require_event_log = require("./event-log-dSOnXHuG.cjs");
2
2
  const require_decision = require("./decision-D8bcIGXQ.cjs");
3
+ const require_machine_input = require("./machine-input-DU3owLUr.cjs");
3
4
  let xstate = require("xstate");
4
5
  //#region src/steps.ts
5
6
  /**
@@ -578,6 +579,7 @@ function takeFromQueue(channel, src) {
578
579
  * ```
579
580
  */
580
581
  async function simulateAgent(machine, options) {
582
+ options = withMachineInput(machine, options, "simulateAgent");
581
583
  const maxSteps = options.maxSteps ?? 100;
582
584
  const script = {
583
585
  text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
@@ -805,6 +807,65 @@ function scriptDryError(kind, src, id, request) {
805
807
  const MAX_ADVANCE_STEPS = 1e3;
806
808
  const FINITE_PAYLOAD_CAP = 64;
807
809
  const DEFAULT_MAX_NODES = 1e5;
810
+ function isDataProperty(target, key) {
811
+ const descriptor = Object.getOwnPropertyDescriptor(target, key);
812
+ return descriptor !== void 0 && "value" in descriptor;
813
+ }
814
+ function strictKey(value, refs = /* @__PURE__ */ new Map()) {
815
+ if (value === void 0) return "u";
816
+ if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
817
+ if (typeof value === "number") return Object.is(value, -0) ? "n-0" : `n${String(value)}`;
818
+ if (typeof value !== "object") throw new TypeError(`unkeyable ${typeof value}`);
819
+ const ref = refs.get(value);
820
+ if (ref !== void 0) return `@${ref}`;
821
+ refs.set(value, refs.size);
822
+ const proto = Object.getPrototypeOf(value);
823
+ const own = Reflect.ownKeys(value).length;
824
+ if (Array.isArray(value)) {
825
+ if (proto !== Array.prototype) throw new TypeError("unkeyable array");
826
+ for (let index = 0; index < value.length; index++) if (!isDataProperty(value, index)) throw new TypeError("unkeyable sparse array");
827
+ if (own !== value.length + 1) throw new TypeError("unkeyable array");
828
+ return `[${value.map((item) => strictKey(item, refs)).join(",")}]`;
829
+ }
830
+ if (proto !== Object.prototype && proto !== null) throw new TypeError("unkeyable object");
831
+ const keys = Object.keys(value);
832
+ if (own !== keys.length || !keys.every((k) => isDataProperty(value, k))) throw new TypeError("unkeyable object");
833
+ return `${proto === null ? "N" : ""}{${keys.map((k) => `${JSON.stringify(k)}:${strictKey(value[k], refs)}`).join(",")}}`;
834
+ }
835
+ function tryKey(key) {
836
+ try {
837
+ return key();
838
+ } catch {
839
+ return;
840
+ }
841
+ }
842
+ function stepKeyParts(step) {
843
+ const snapshot = step.snapshot;
844
+ const children = snapshot.children ?? {};
845
+ return [
846
+ snapshot.value,
847
+ snapshot.context,
848
+ snapshot.status,
849
+ snapshot.historyValue ?? null,
850
+ step.requests.map((request) => request.id),
851
+ pendingInvokes(step).map((invoke) => [
852
+ invoke.id,
853
+ invoke.src,
854
+ invoke.input
855
+ ]),
856
+ Object.keys(children).sort().map((id) => [id, children[id]?.options?.input]),
857
+ (snapshot.timers ?? []).map((timer) => [
858
+ timer["id"],
859
+ timer["type"],
860
+ timer["delay"],
861
+ timer["event"],
862
+ timer["target"] === "self" ? "self" : timer["target"]?.id
863
+ ])
864
+ ];
865
+ }
866
+ function defaultStepKey(step) {
867
+ return strictKey(stepKeyParts(step));
868
+ }
808
869
  const MAX_CHILD_NESTING = 4;
809
870
  const DEFAULT_BUDGET_NODES = 25e4;
810
871
  const DEFAULT_CHILD_CACHE = 64;
@@ -1050,7 +1111,7 @@ function finishedChildren(step) {
1050
1111
  return [];
1051
1112
  });
1052
1113
  }
1053
- function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef, trackTransits = nesting === 0 && hasTransientStates(machine.root), budget = startBudget(options.budget), stepping = false, ordering, stateTarget = false) {
1114
+ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef, trackTransits = nesting === 0 && hasTransientStates(machine.root), budget = startBudget(options.budget), stepping = false, ordering, stateTarget = false, defaultDedupe = false) {
1054
1115
  const maxDepth = options.maxDepth ?? 8;
1055
1116
  const maxPaths = options.maxPaths ?? 200;
1056
1117
  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
@@ -1093,13 +1154,13 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1093
1154
  if (!logging) return next;
1094
1155
  const before = prev && logs.get(prev);
1095
1156
  const step = exploreStep(prev, next, timerDelivers.get(event) ?? event);
1096
- const after = before?.after ?? false;
1097
1157
  const trigger = ordering?.after;
1158
+ const after = (before?.after ?? false) || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step));
1098
1159
  logs.set(next, {
1099
1160
  step,
1100
1161
  prev: before,
1101
1162
  length: (before?.length ?? 0) + 1,
1102
- after: after || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step)),
1163
+ after,
1103
1164
  violated: (before?.violated ?? false) || after && ordering.reach(step)
1104
1165
  });
1105
1166
  return next;
@@ -1808,17 +1869,8 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1808
1869
  return `\u0003${[...kids.values()].map((kid) => `${kid.id}\u0000${kid.src}\u0000${kid.engine.stateKey(kid)}`).sort().join("")}`;
1809
1870
  };
1810
1871
  const stateKey = (kid) => {
1811
- const snapshot = kid.step.snapshot;
1812
1872
  try {
1813
- return JSON.stringify([
1814
- snapshot.value,
1815
- snapshot.context,
1816
- snapshot.status,
1817
- snapshot.historyValue ?? null,
1818
- kid.step.requests.map((request) => request.id),
1819
- Object.keys(snapshot.children ?? {}),
1820
- pumped.has(kid.step)
1821
- ]) + kidsKey(kid.kids);
1873
+ return strictKey([...stepKeyParts(kid.step), pumped.has(kid.step)]) + kidsKey(kid.kids);
1822
1874
  } catch {
1823
1875
  return `\u0002${unkeyable++}`;
1824
1876
  }
@@ -1854,8 +1906,9 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1854
1906
  return;
1855
1907
  }
1856
1908
  }
1857
- if (options.dedupeBy) {
1858
- const key = options.dedupeBy(withKidSnapshots(settled.snapshot, nodeKids)) + (delivered?.size ? `\u0001${[...delivered].sort().join("")}` : "") + kidsKey(nodeKids) + (logs.get(settled)?.after ? "after" : "");
1909
+ const base = options.dedupeBy ? options.dedupeBy(withKidSnapshots(settled.snapshot, nodeKids)) : defaultDedupe ? tryKey(() => defaultStepKey(settled)) : void 0;
1910
+ if (base !== void 0) {
1911
+ const key = base + (delivered?.size ? `\u0001${[...delivered].sort().join("")}` : "") + kidsKey(nodeKids) + (logs.get(settled)?.after ? "after" : "");
1859
1912
  const seenAt = visited.get(key);
1860
1913
  if (seenAt !== void 0 && seenAt <= depth) return;
1861
1914
  visited.set(key, depth);
@@ -2293,6 +2346,19 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2293
2346
  };
2294
2347
  }
2295
2348
  /**
2349
+ * Validates `options.input` against the machine's input schema, as a run
2350
+ * would, and seeds the search with the parsed value (defaults filled). Input
2351
+ * the machine would reject throws `invalid-machine-input` instead of giving a
2352
+ * proof over a start state no run can reach.
2353
+ */
2354
+ function withMachineInput(machine, options, caller) {
2355
+ if (options.input === void 0) return options;
2356
+ return {
2357
+ ...options,
2358
+ input: require_machine_input.resolveMachineInput(machine, options.input, caller)
2359
+ };
2360
+ }
2361
+ /**
2296
2362
  * Enumerates a machine's decision and external-event branches to a bounded
2297
2363
  * depth, model-free, and reports which states are reached and how each path
2298
2364
  * terminates. At each decision request it forks one branch per candidate event
@@ -2329,7 +2395,7 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2329
2395
  * ```
2330
2396
  */
2331
2397
  async function explorePaths(machine, options = {}) {
2332
- return explore(machine, options).report;
2398
+ return explore(machine, withMachineInput(machine, options, "explorePaths")).report;
2333
2399
  }
2334
2400
  /** Thrown when a string reachability target is not a state in the machine. */
2335
2401
  var AgentUnknownStateError = class extends require_event_log.AgentError {
@@ -2378,9 +2444,10 @@ function resolveStateTarget(machine, target) {
2378
2444
  * ```
2379
2445
  */
2380
2446
  async function canReach(machine, target, options = {}) {
2447
+ options = withMachineInput(machine, options, "canReach");
2381
2448
  const resolvedTarget = typeof target === "string" ? resolveStateTarget(machine, target) : void 0;
2382
2449
  const ordering = typeof target === "object" ? target : void 0;
2383
- const { witness, report } = explore(machine, options, typeof target === "function" ? target : ordering ? () => false : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget), 0, void 0, void 0, resolvedTarget !== void 0 && hasTransientStates(machine.getStateNodeById(resolvedTarget)), void 0, false, ordering, resolvedTarget !== void 0);
2450
+ const { witness, report } = explore(machine, options, typeof target === "function" ? target : ordering ? () => false : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget), 0, void 0, void 0, resolvedTarget !== void 0 && hasTransientStates(machine.getStateNodeById(resolvedTarget)), void 0, false, ordering, resolvedTarget !== void 0, options.dedupeBy === void 0);
2384
2451
  if (witness !== void 0) return {
2385
2452
  reachable: true,
2386
2453
  witness,
@@ -1,5 +1,6 @@
1
1
  import { $ as getJsonSchemaSync, C as AGENT_USAGE_EVENT_TYPE, K as getRegisteredAgentExecutionOptions, L as isTextLogic, W as executorBoundLogics, ft as isRecord, pt as AgentError } from "./event-log-CEq_bVXQ.mjs";
2
2
  import { _ as isEventPattern, g as getHumanEventTypes, h as getAcceptedEvents, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError, u as resolveDecision } from "./decision-B41YBx5U.mjs";
3
+ import { t as resolveMachineInput } from "./machine-input-0YTPcnCm.mjs";
3
4
  import { getInitialMicrosteps, getMicrosteps, getNextTransitions, initialTransition, machineToJSON, transition } from "xstate";
4
5
  //#region src/steps.ts
5
6
  /**
@@ -578,6 +579,7 @@ function takeFromQueue(channel, src) {
578
579
  * ```
579
580
  */
580
581
  async function simulateAgent(machine, options) {
582
+ options = withMachineInput(machine, options, "simulateAgent");
581
583
  const maxSteps = options.maxSteps ?? 100;
582
584
  const script = {
583
585
  text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
@@ -805,6 +807,65 @@ function scriptDryError(kind, src, id, request) {
805
807
  const MAX_ADVANCE_STEPS = 1e3;
806
808
  const FINITE_PAYLOAD_CAP = 64;
807
809
  const DEFAULT_MAX_NODES = 1e5;
810
+ function isDataProperty(target, key) {
811
+ const descriptor = Object.getOwnPropertyDescriptor(target, key);
812
+ return descriptor !== void 0 && "value" in descriptor;
813
+ }
814
+ function strictKey(value, refs = /* @__PURE__ */ new Map()) {
815
+ if (value === void 0) return "u";
816
+ if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
817
+ if (typeof value === "number") return Object.is(value, -0) ? "n-0" : `n${String(value)}`;
818
+ if (typeof value !== "object") throw new TypeError(`unkeyable ${typeof value}`);
819
+ const ref = refs.get(value);
820
+ if (ref !== void 0) return `@${ref}`;
821
+ refs.set(value, refs.size);
822
+ const proto = Object.getPrototypeOf(value);
823
+ const own = Reflect.ownKeys(value).length;
824
+ if (Array.isArray(value)) {
825
+ if (proto !== Array.prototype) throw new TypeError("unkeyable array");
826
+ for (let index = 0; index < value.length; index++) if (!isDataProperty(value, index)) throw new TypeError("unkeyable sparse array");
827
+ if (own !== value.length + 1) throw new TypeError("unkeyable array");
828
+ return `[${value.map((item) => strictKey(item, refs)).join(",")}]`;
829
+ }
830
+ if (proto !== Object.prototype && proto !== null) throw new TypeError("unkeyable object");
831
+ const keys = Object.keys(value);
832
+ if (own !== keys.length || !keys.every((k) => isDataProperty(value, k))) throw new TypeError("unkeyable object");
833
+ return `${proto === null ? "N" : ""}{${keys.map((k) => `${JSON.stringify(k)}:${strictKey(value[k], refs)}`).join(",")}}`;
834
+ }
835
+ function tryKey(key) {
836
+ try {
837
+ return key();
838
+ } catch {
839
+ return;
840
+ }
841
+ }
842
+ function stepKeyParts(step) {
843
+ const snapshot = step.snapshot;
844
+ const children = snapshot.children ?? {};
845
+ return [
846
+ snapshot.value,
847
+ snapshot.context,
848
+ snapshot.status,
849
+ snapshot.historyValue ?? null,
850
+ step.requests.map((request) => request.id),
851
+ pendingInvokes(step).map((invoke) => [
852
+ invoke.id,
853
+ invoke.src,
854
+ invoke.input
855
+ ]),
856
+ Object.keys(children).sort().map((id) => [id, children[id]?.options?.input]),
857
+ (snapshot.timers ?? []).map((timer) => [
858
+ timer["id"],
859
+ timer["type"],
860
+ timer["delay"],
861
+ timer["event"],
862
+ timer["target"] === "self" ? "self" : timer["target"]?.id
863
+ ])
864
+ ];
865
+ }
866
+ function defaultStepKey(step) {
867
+ return strictKey(stepKeyParts(step));
868
+ }
808
869
  const MAX_CHILD_NESTING = 4;
809
870
  const DEFAULT_BUDGET_NODES = 25e4;
810
871
  const DEFAULT_CHILD_CACHE = 64;
@@ -1050,7 +1111,7 @@ function finishedChildren(step) {
1050
1111
  return [];
1051
1112
  });
1052
1113
  }
1053
- function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef, trackTransits = nesting === 0 && hasTransientStates(machine.root), budget = startBudget(options.budget), stepping = false, ordering, stateTarget = false) {
1114
+ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef, trackTransits = nesting === 0 && hasTransientStates(machine.root), budget = startBudget(options.budget), stepping = false, ordering, stateTarget = false, defaultDedupe = false) {
1054
1115
  const maxDepth = options.maxDepth ?? 8;
1055
1116
  const maxPaths = options.maxPaths ?? 200;
1056
1117
  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
@@ -1093,13 +1154,13 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1093
1154
  if (!logging) return next;
1094
1155
  const before = prev && logs.get(prev);
1095
1156
  const step = exploreStep(prev, next, timerDelivers.get(event) ?? event);
1096
- const after = before?.after ?? false;
1097
1157
  const trigger = ordering?.after;
1158
+ const after = (before?.after ?? false) || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step));
1098
1159
  logs.set(next, {
1099
1160
  step,
1100
1161
  prev: before,
1101
1162
  length: (before?.length ?? 0) + 1,
1102
- after: after || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step)),
1163
+ after,
1103
1164
  violated: (before?.violated ?? false) || after && ordering.reach(step)
1104
1165
  });
1105
1166
  return next;
@@ -1808,17 +1869,8 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1808
1869
  return `\u0003${[...kids.values()].map((kid) => `${kid.id}\u0000${kid.src}\u0000${kid.engine.stateKey(kid)}`).sort().join("")}`;
1809
1870
  };
1810
1871
  const stateKey = (kid) => {
1811
- const snapshot = kid.step.snapshot;
1812
1872
  try {
1813
- return JSON.stringify([
1814
- snapshot.value,
1815
- snapshot.context,
1816
- snapshot.status,
1817
- snapshot.historyValue ?? null,
1818
- kid.step.requests.map((request) => request.id),
1819
- Object.keys(snapshot.children ?? {}),
1820
- pumped.has(kid.step)
1821
- ]) + kidsKey(kid.kids);
1873
+ return strictKey([...stepKeyParts(kid.step), pumped.has(kid.step)]) + kidsKey(kid.kids);
1822
1874
  } catch {
1823
1875
  return `\u0002${unkeyable++}`;
1824
1876
  }
@@ -1854,8 +1906,9 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1854
1906
  return;
1855
1907
  }
1856
1908
  }
1857
- if (options.dedupeBy) {
1858
- const key = options.dedupeBy(withKidSnapshots(settled.snapshot, nodeKids)) + (delivered?.size ? `\u0001${[...delivered].sort().join("")}` : "") + kidsKey(nodeKids) + (logs.get(settled)?.after ? "after" : "");
1909
+ const base = options.dedupeBy ? options.dedupeBy(withKidSnapshots(settled.snapshot, nodeKids)) : defaultDedupe ? tryKey(() => defaultStepKey(settled)) : void 0;
1910
+ if (base !== void 0) {
1911
+ const key = base + (delivered?.size ? `\u0001${[...delivered].sort().join("")}` : "") + kidsKey(nodeKids) + (logs.get(settled)?.after ? "after" : "");
1859
1912
  const seenAt = visited.get(key);
1860
1913
  if (seenAt !== void 0 && seenAt <= depth) return;
1861
1914
  visited.set(key, depth);
@@ -2293,6 +2346,19 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2293
2346
  };
2294
2347
  }
2295
2348
  /**
2349
+ * Validates `options.input` against the machine's input schema, as a run
2350
+ * would, and seeds the search with the parsed value (defaults filled). Input
2351
+ * the machine would reject throws `invalid-machine-input` instead of giving a
2352
+ * proof over a start state no run can reach.
2353
+ */
2354
+ function withMachineInput(machine, options, caller) {
2355
+ if (options.input === void 0) return options;
2356
+ return {
2357
+ ...options,
2358
+ input: resolveMachineInput(machine, options.input, caller)
2359
+ };
2360
+ }
2361
+ /**
2296
2362
  * Enumerates a machine's decision and external-event branches to a bounded
2297
2363
  * depth, model-free, and reports which states are reached and how each path
2298
2364
  * terminates. At each decision request it forks one branch per candidate event
@@ -2329,7 +2395,7 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2329
2395
  * ```
2330
2396
  */
2331
2397
  async function explorePaths(machine, options = {}) {
2332
- return explore(machine, options).report;
2398
+ return explore(machine, withMachineInput(machine, options, "explorePaths")).report;
2333
2399
  }
2334
2400
  /** Thrown when a string reachability target is not a state in the machine. */
2335
2401
  var AgentUnknownStateError = class extends AgentError {
@@ -2378,9 +2444,10 @@ function resolveStateTarget(machine, target) {
2378
2444
  * ```
2379
2445
  */
2380
2446
  async function canReach(machine, target, options = {}) {
2447
+ options = withMachineInput(machine, options, "canReach");
2381
2448
  const resolvedTarget = typeof target === "string" ? resolveStateTarget(machine, target) : void 0;
2382
2449
  const ordering = typeof target === "object" ? target : void 0;
2383
- const { witness, report } = explore(machine, options, typeof target === "function" ? target : ordering ? () => false : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget), 0, void 0, void 0, resolvedTarget !== void 0 && hasTransientStates(machine.getStateNodeById(resolvedTarget)), void 0, false, ordering, resolvedTarget !== void 0);
2450
+ const { witness, report } = explore(machine, options, typeof target === "function" ? target : ordering ? () => false : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget), 0, void 0, void 0, resolvedTarget !== void 0 && hasTransientStates(machine.getStateNodeById(resolvedTarget)), void 0, false, ordering, resolvedTarget !== void 0, options.dedupeBy === void 0);
2384
2451
  if (witness !== void 0) return {
2385
2452
  reachable: true,
2386
2453
  witness,
package/docs/evals.md CHANGED
@@ -337,6 +337,7 @@ replay.output(await runPort(replay.client("anthropic", stand, { methods })));
337
337
  compareRecordings(recorder.recording, replay.recording); // { equivalent: true, divergences: [] }
338
338
  ```
339
339
 
340
+ - `recorder.model` records each provider attempt as a `model` effect. A failed attempt followed by the same request, such as an AI SDK retry, has `retriedBy` set to the call that retried it. Attempts made inside a `generateText` or `streamText` call that `recordAiSdk` routed carry that call's index as `aiSdkCall`, so a retry by the SDK (same `aiSdkCall`) is told apart from one by the code (a different `aiSdkCall`).
340
341
  - Each call is a `call` effect named `<name>.<method>`, such as `anthropic.messages.create`, with its arguments and its result or error.
341
342
  - `recorder.fn(name, asyncFn, options?)` wraps one async function the same way, for a client that is a function.
342
343
  - Replay answers each call with the next unused recorded call of the same name, in order, whatever its arguments. A call past the recorded ones throws `RecordingDivergenceError`.