@warlock.js/ai 4.4.0 → 4.6.0

package/esm/utils/resolve-attachment.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-attachment.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/resolve-attachment.ts"],"sourcesContent":["import type {\n  Attachment,\n  AttachmentSource,\n  ResolvedAttachment,\n} from \"../contracts/attachment.type\";\nimport { InvalidRequestError } from \"../errors\";\n\nconst REMOTE_URL_PATTERN = /^https?:\\/\\//i;\n\n/**\n * Normalize a user-supplied `Attachment` (or bare `AttachmentSource`)\n * into a `ResolvedAttachment` the agent can hand to file-reading code\n * without re-discriminating the input variant.\n *\n * Resolution rules:\n * - `{ base64, mediaType }` → `{ type: \"base64\", value, mediaType }`.\n * - `StorageFileShape` (`{ url?, absolutePath? }`) → URL wins over\n *   absolute path. URL becomes `{ type: \"url\" }`; absolute path\n *   becomes `{ type: \"path\" }`.\n * - String starting with `http://` / `https://` → `{ type: \"url\" }`.\n * - Any other string → `{ type: \"path\" }`.\n * - Tagged `{ type: \"image\" | \"text\", source }` → recurses into `source`.\n *\n * Throws `InvalidRequestError` on obviously invalid input (empty\n * string, storage object with neither url nor absolutePath, missing\n * source field).\n *\n * @example\n * resolveAttachment(\"https://cdn.example.com/doc.pdf\");\n * // → { type: \"url\", value: \"https://cdn.example.com/doc.pdf\" }\n *\n * @example\n * resolveAttachment({ type: \"image\", source: \"/tmp/x.png\" });\n * // → { type: \"path\", value: \"/tmp/x.png\" }\n */\nexport function resolveAttachment(attachment: Attachment): ResolvedAttachment {\n  if (\n    typeof attachment === \"object\" &&\n    attachment !== null &&\n    \"type\" in attachment\n  ) {\n    return resolveSource(attachment.source);\n  }\n\n  return resolveSource(attachment);\n}\n\nfunction resolveSource(source: AttachmentSource): ResolvedAttachment {\n  if (typeof source === \"string\") {\n    if (!source) {\n      throw new InvalidRequestError(\"Cannot resolve empty attachment string\");\n    }\n\n    if (REMOTE_URL_PATTERN.test(source)) {\n      return { type: \"url\", value: source };\n    }\n\n    return { type: \"path\", value: source };\n  }\n\n  // StorageFile objects (from @warlock.js/core) can expose a `base64`\n  // property alongside `url` / `absolutePath`. Check storage shape\n  // first so we don't treat a StorageFile as an inline-bytes payload.\n  if (\"url\" in source || \"absolutePath\" in source) {\n    const storage = source as { url?: string; absolutePath?: string };\n\n    if (storage.absolutePath) {\n      return { type: \"path\", value: storage.absolutePath };\n    }\n\n    if (storage.url) {\n      return { type: \"url\", value: storage.url };\n    }\n\n    throw new InvalidRequestError(\n      \"Storage attachment has neither url nor absolutePath\",\n    );\n  }\n\n  if (\"base64\" in source) {\n    if (!source.base64 || !source.mediaType) {\n      throw new InvalidRequestError(\n        \"Inline attachment requires both `base64` and `mediaType`\",\n      );\n    }\n\n    return {\n      type: \"base64\",\n      value: source.base64,\n      mediaType: source.mediaType,\n    };\n  }\n\n  throw new InvalidRequestError(\n    \"Unrecognized attachment source — expected a string path/URL, a StorageFile, or `{ base64, mediaType }`\",\n  );\n}\n"],"mappings":";;;;AAOA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4B3B,SAAgB,kBAAkB,YAA4C;CAC5E,IACE,OAAO,eAAe,YACtB,eAAe,QACf,UAAU,YAEV,OAAO,cAAc,WAAW,MAAM;CAGxC,OAAO,cAAc,UAAU;AACjC;AAEA,SAAS,cAAc,QAA8C;CACnE,IAAI,OAAO,WAAW,UAAU;EAC9B,IAAI,CAAC,QACH,MAAM,IAAI,oBAAoB,wCAAwC;EAGxE,IAAI,mBAAmB,KAAK,MAAM,GAChC,OAAO;GAAE,MAAM;GAAO,OAAO;EAAO;EAGtC,OAAO;GAAE,MAAM;GAAQ,OAAO;EAAO;CACvC;CAKA,IAAI,SAAS,UAAU,kBAAkB,QAAQ;EAC/C,MAAM,UAAU;EAEhB,IAAI,QAAQ,cACV,OAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;EAAa;EAGrD,IAAI,QAAQ,KACV,OAAO;GAAE,MAAM;GAAO,OAAO,QAAQ;EAAI;EAG3C,MAAM,IAAI,oBACR,qDACF;CACF;CAEA,IAAI,YAAY,QAAQ;EACtB,IAAI,CAAC,OAAO,UAAU,CAAC,OAAO,WAC5B,MAAM,IAAI,oBACR,0DACF;EAGF,OAAO;GACL,MAAM;GACN,OAAO,OAAO;GACd,WAAW,OAAO;EACpB;CACF;CAEA,MAAM,IAAI,oBACR,wGACF;AACF"}
+{"version":3,"file":"resolve-attachment.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/resolve-attachment.ts"],"sourcesContent":["import type {\n  Attachment,\n  AttachmentSource,\n  ResolvedAttachment,\n} from \"../contracts/attachment.type\";\nimport { InvalidRequestError } from \"../errors\";\n\nconst REMOTE_URL_PATTERN = /^https?:\\/\\//i;\n\n/**\n * Normalize a user-supplied `Attachment` (or bare `AttachmentSource`)\n * into a `ResolvedAttachment` the agent can hand to file-reading code\n * without re-discriminating the input variant.\n *\n * Resolution rules:\n * - `{ base64, mediaType }` → `{ type: \"base64\", value, mediaType }`.\n * - `StorageFileShape` (`{ url?, absolutePath? }`) → `absolutePath` wins\n *   over `url` when both are present (prefer the local file over an extra\n *   remote hop). Absolute path becomes `{ type: \"path\" }`; url becomes\n *   `{ type: \"url\" }`.\n * - String starting with `http://` / `https://` → `{ type: \"url\" }`.\n * - Any other string → `{ type: \"path\" }`.\n * - Tagged `{ type: \"image\" | \"text\", source }` → recurses into `source`.\n *\n * Throws `InvalidRequestError` on obviously invalid input (empty\n * string, storage object with neither url nor absolutePath, missing\n * source field).\n *\n * @example\n * resolveAttachment(\"https://cdn.example.com/doc.pdf\");\n * // → { type: \"url\", value: \"https://cdn.example.com/doc.pdf\" }\n *\n * @example\n * resolveAttachment({ type: \"image\", source: \"/tmp/x.png\" });\n * // → { type: \"path\", value: \"/tmp/x.png\" }\n */\nexport function resolveAttachment(attachment: Attachment): ResolvedAttachment {\n  if (\n    typeof attachment === \"object\" &&\n    attachment !== null &&\n    \"type\" in attachment\n  ) {\n    return resolveSource(attachment.source);\n  }\n\n  return resolveSource(attachment);\n}\n\nfunction resolveSource(source: AttachmentSource): ResolvedAttachment {\n  if (typeof source === \"string\") {\n    if (!source) {\n      throw new InvalidRequestError(\"Cannot resolve empty attachment string\");\n    }\n\n    if (REMOTE_URL_PATTERN.test(source)) {\n      return { type: \"url\", value: source };\n    }\n\n    return { type: \"path\", value: source };\n  }\n\n  // StorageFile objects (from @warlock.js/core) can expose a `base64`\n  // property alongside `url` / `absolutePath`. Check storage shape\n  // first so we don't treat a StorageFile as an inline-bytes payload.\n  if (\"url\" in source || \"absolutePath\" in source) {\n    const storage = source as { url?: string; absolutePath?: string };\n\n    if (storage.absolutePath) {\n      return { type: \"path\", value: storage.absolutePath };\n    }\n\n    if (storage.url) {\n      return { type: \"url\", value: storage.url };\n    }\n\n    throw new InvalidRequestError(\n      \"Storage attachment has neither url nor absolutePath\",\n    );\n  }\n\n  if (\"base64\" in source) {\n    if (!source.base64 || !source.mediaType) {\n      throw new InvalidRequestError(\n        \"Inline attachment requires both `base64` and `mediaType`\",\n      );\n    }\n\n    return {\n      type: \"base64\",\n      value: source.base64,\n      mediaType: source.mediaType,\n    };\n  }\n\n  throw new InvalidRequestError(\n    \"Unrecognized attachment source — expected a string path/URL, a StorageFile, or `{ base64, mediaType }`\",\n  );\n}\n"],"mappings":";;;;AAOA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6B3B,SAAgB,kBAAkB,YAA4C;CAC5E,IACE,OAAO,eAAe,YACtB,eAAe,QACf,UAAU,YAEV,OAAO,cAAc,WAAW,MAAM;CAGxC,OAAO,cAAc,UAAU;AACjC;AAEA,SAAS,cAAc,QAA8C;CACnE,IAAI,OAAO,WAAW,UAAU;EAC9B,IAAI,CAAC,QACH,MAAM,IAAI,oBAAoB,wCAAwC;EAGxE,IAAI,mBAAmB,KAAK,MAAM,GAChC,OAAO;GAAE,MAAM;GAAO,OAAO;EAAO;EAGtC,OAAO;GAAE,MAAM;GAAQ,OAAO;EAAO;CACvC;CAKA,IAAI,SAAS,UAAU,kBAAkB,QAAQ;EAC/C,MAAM,UAAU;EAEhB,IAAI,QAAQ,cACV,OAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;EAAa;EAGrD,IAAI,QAAQ,KACV,OAAO;GAAE,MAAM;GAAO,OAAO,QAAQ;EAAI;EAG3C,MAAM,IAAI,oBACR,qDACF;CACF;CAEA,IAAI,YAAY,QAAQ;EACtB,IAAI,CAAC,OAAO,UAAU,CAAC,OAAO,WAC5B,MAAM,IAAI,oBACR,0DACF;EAGF,OAAO;GACL,MAAM;GACN,OAAO,OAAO;GACd,WAAW,OAAO;EACpB;CACF;CAEA,MAAM,IAAI,oBACR,wGACF;AACF"}

package/esm/utils/run-context.d.mts

@@ -0,0 +1,94 @@
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+
+//#region ../@warlock.js/ai/src/utils/run-context.d.ts
+/**
+ * The ambient run frame an executable reads when it finishes building
+ * its report. When present, a child execution (an `agent.execute()`,
+ * `workflow.execute()`, `supervisor.execute()` call) auto-attaches its
+ * report to `sink` and inherits the frame's `rootRunId` / `sessionId`
+ * lineage — so reports nest under the enclosing run with NO manual id
+ * threading by the dev.
+ *
+ * Installed by orchestration primitives (supervisor / orchestrator /
+ * team) around the synchronous + async body of an intent's callback,
+ * so any agent the callback invokes directly — `agent.execute(...)`
+ * rather than `ctx.run(...)` — still lands in the trace tree.
+ */
+type RunFrame = {
+  /**
+   * The `children[]` array of the enclosing report node. A child
+   * execution pushes its assembled report here on completion.
+   */
+  sink: BaseReport[];
+  /**
+   * The outermost run-id this subtree belongs to. Propagated onto the
+   * child report's `rootRunId` so flat-row consumers group it with the
+   * enclosing run.
+   */
+  rootRunId: string;
+  /**
+   * Run-id of the enclosing node (the immediate parent of any child
+   * captured through this frame). Stamped onto the child's
+   * `parentRunId`.
+   */
+  parentRunId: string;
+  /**
+   * Session identifier propagated onto the captured child's subtree.
+   * `undefined` when the enclosing run had none.
+   */
+  sessionId?: string;
+};
+/**
+ * Run `fn` with `frame` installed as the ambient {@link RunFrame} for
+ * the entire async subtree it spawns. Restores the previous frame (or
+ * none) when `fn` settles. Returns whatever `fn` returns.
+ *
+ * Nesting is natural: a callback that itself dispatches a nested
+ * supervisor installs a fresh frame for the inner run, and the inner
+ * frame shadows the outer one for the inner subtree only — exactly the
+ * tree shape the report models.
+ */
+declare function withRunFrame<T>(frame: RunFrame, fn: () => T): T;
+/**
+ * Run `fn` with NO ambient {@link RunFrame} installed for its async
+ * subtree, restoring the previous frame when `fn` settles. Used by the
+ * supervisor's EXPLICIT capture paths (`ctx.run(...)` /
+ * `ctx.intents.X.execute()`) — those already push the child report onto
+ * the callback's `children[]` themselves, so the child must NOT also
+ * self-capture via the ambient frame (which would double-count it).
+ */
+declare function withoutRunFrame<T>(fn: () => T): T;
+/**
+ * Read the current ambient {@link RunFrame}, or `undefined` when no
+ * orchestration callback is on the stack. An executable calls this at
+ * report-build time: a present frame means "you were invoked inside a
+ * callback — attach yourself to its tree".
+ */
+declare function currentRunFrame(): RunFrame | undefined;
+/**
+ * Capture a freshly-built child `report` onto the current ambient
+ * {@link RunFrame} when one is installed. Pushes the report onto the
+ * frame's `sink` so it nests under the enclosing node, and rewrites the
+ * report's lineage (`rootRunId`, `parentRunId`, `sessionId`) to the
+ * frame's — mirroring how `step.agent` / `ctx.run` capture child
+ * reports explicitly, but driven ambiently.
+ *
+ * No-op (returns `false`) when no frame is installed — a standalone
+ * `agent.execute()` keeps its self-root untouched. Returns `true` when
+ * the report was captured so the caller can suppress its own terminal
+ * lineage stamp if needed.
+ *
+ * The lineage rewrite is intentionally shallow on the root + deep on
+ * descendants would double-stamp; callers pass the already-lineage-
+ * stamped subtree (self-root), and this relinks only the root's
+ * `rootRunId` / `parentRunId` / `sessionId`. Descendants already carry
+ * the child's own self-root as their `rootRunId`; the enclosing
+ * primitive's terminal `stampReportLineage` pass (run once on the
+ * outer tree) rewrites the whole subtree to the true outer root. This
+ * keeps capture cheap and defers the single authoritative relink to
+ * the outer build.
+ */
+declare function captureChildReport(report: BaseReport): boolean;
+//#endregion
+export { RunFrame, captureChildReport, currentRunFrame, withRunFrame, withoutRunFrame };
+//# sourceMappingURL=run-context.d.mts.map

package/esm/utils/run-context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/run-context.ts"],"mappings":";;;;;AAgBA;;;;;;;;;;AAsBW;KAtBC,QAAA;EAqDgB;;;;EAhD1B,IAAA,EAAM,UAAU;EAgD8C;;;;;EA1C9D,SAAA;EA0C+C;;;AAAe;AAYhE;EAhDE,WAAA;EAgD6B;;;;EA3C7B,SAAA;AAAA;;AA2CgD;AAUlD;;;;AAA2C;AAsC3C;;;iBA5DgB,YAAA,IAAgB,KAAA,EAAO,QAAA,EAAU,EAAA,QAAU,CAAA,GAAI,CAAA;AA4DV;;;;;;;;AAAA,iBAhDrC,eAAA,IAAmB,EAAA,QAAU,CAAA,GAAI,CAAC;;;;;;;iBAUlC,eAAA,IAAmB,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;iBAsC3B,kBAAA,CAAmB,MAAkB,EAAV,UAAU"}

package/esm/utils/run-context.mjs

@@ -0,0 +1,98 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region ../@warlock.js/ai/src/utils/run-context.ts
+/**
+* Process-wide async-local store holding the current {@link RunFrame}.
+* A single shared instance so a frame installed by the supervisor is
+* visible to an agent running several `await`s deep inside a callback,
+* across module boundaries. Empty (returns `undefined`) outside any
+* orchestration callback — standalone `agent.execute()` is unaffected.
+*/
+const runFrameStore = new AsyncLocalStorage();
+/**
+* A second async-local flag set whenever execution is nested inside a
+* parent capture — by BOTH {@link withRunFrame} (ambient capture) and
+* {@link withoutRunFrame} (explicit parent capture, which clears the frame).
+* Lets the `observeAll` gate skip self-routing a nested run regardless of
+* which capture path its parent uses — the parent already captures it.
+*/
+const nestedStore = new AsyncLocalStorage();
+/**
+* Run `fn` with `frame` installed as the ambient {@link RunFrame} for
+* the entire async subtree it spawns. Restores the previous frame (or
+* none) when `fn` settles. Returns whatever `fn` returns.
+*
+* Nesting is natural: a callback that itself dispatches a nested
+* supervisor installs a fresh frame for the inner run, and the inner
+* frame shadows the outer one for the inner subtree only — exactly the
+* tree shape the report models.
+*/
+function withRunFrame(frame, fn) {
+	return nestedStore.run(true, () => runFrameStore.run(frame, fn));
+}
+/**
+* Run `fn` with NO ambient {@link RunFrame} installed for its async
+* subtree, restoring the previous frame when `fn` settles. Used by the
+* supervisor's EXPLICIT capture paths (`ctx.run(...)` /
+* `ctx.intents.X.execute()`) — those already push the child report onto
+* the callback's `children[]` themselves, so the child must NOT also
+* self-capture via the ambient frame (which would double-count it).
+*/
+function withoutRunFrame(fn) {
+	return nestedStore.run(true, () => runFrameStore.run(void 0, fn));
+}
+/**
+* Read the current ambient {@link RunFrame}, or `undefined` when no
+* orchestration callback is on the stack. An executable calls this at
+* report-build time: a present frame means "you were invoked inside a
+* callback — attach yourself to its tree".
+*/
+function currentRunFrame() {
+	return runFrameStore.getStore();
+}
+/**
+* `true` when execution is nested inside a parent capture — set by
+* {@link withRunFrame} (ambient) or {@link withoutRunFrame} (explicit). Read
+* by the observe-all gate so a nested run, which its parent already captures
+* into the trace tree, is not also self-routed as a standalone top-level
+* trace. `false` for a standalone (root) run.
+*/
+function isNestedRun() {
+	return nestedStore.getStore() === true;
+}
+/**
+* Capture a freshly-built child `report` onto the current ambient
+* {@link RunFrame} when one is installed. Pushes the report onto the
+* frame's `sink` so it nests under the enclosing node, and rewrites the
+* report's lineage (`rootRunId`, `parentRunId`, `sessionId`) to the
+* frame's — mirroring how `step.agent` / `ctx.run` capture child
+* reports explicitly, but driven ambiently.
+*
+* No-op (returns `false`) when no frame is installed — a standalone
+* `agent.execute()` keeps its self-root untouched. Returns `true` when
+* the report was captured so the caller can suppress its own terminal
+* lineage stamp if needed.
+*
+* The lineage rewrite is intentionally shallow on the root + deep on
+* descendants would double-stamp; callers pass the already-lineage-
+* stamped subtree (self-root), and this relinks only the root's
+* `rootRunId` / `parentRunId` / `sessionId`. Descendants already carry
+* the child's own self-root as their `rootRunId`; the enclosing
+* primitive's terminal `stampReportLineage` pass (run once on the
+* outer tree) rewrites the whole subtree to the true outer root. This
+* keeps capture cheap and defers the single authoritative relink to
+* the outer build.
+*/
+function captureChildReport(report) {
+	const frame = runFrameStore.getStore();
+	if (!frame) return false;
+	report.parentRunId = frame.parentRunId;
+	report.rootRunId = frame.rootRunId;
+	if (frame.sessionId !== void 0) report.sessionId = frame.sessionId;
+	frame.sink.push(report);
+	return true;
+}
+
+//#endregion
+export { captureChildReport, currentRunFrame, isNestedRun, withRunFrame, withoutRunFrame };
+//# sourceMappingURL=run-context.mjs.map

package/esm/utils/run-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/run-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\n\n/**\n * The ambient run frame an executable reads when it finishes building\n * its report. When present, a child execution (an `agent.execute()`,\n * `workflow.execute()`, `supervisor.execute()` call) auto-attaches its\n * report to `sink` and inherits the frame's `rootRunId` / `sessionId`\n * lineage — so reports nest under the enclosing run with NO manual id\n * threading by the dev.\n *\n * Installed by orchestration primitives (supervisor / orchestrator /\n * team) around the synchronous + async body of an intent's callback,\n * so any agent the callback invokes directly — `agent.execute(...)`\n * rather than `ctx.run(...)` — still lands in the trace tree.\n */\nexport type RunFrame = {\n  /**\n   * The `children[]` array of the enclosing report node. A child\n   * execution pushes its assembled report here on completion.\n   */\n  sink: BaseReport[];\n  /**\n   * The outermost run-id this subtree belongs to. Propagated onto the\n   * child report's `rootRunId` so flat-row consumers group it with the\n   * enclosing run.\n   */\n  rootRunId: string;\n  /**\n   * Run-id of the enclosing node (the immediate parent of any child\n   * captured through this frame). Stamped onto the child's\n   * `parentRunId`.\n   */\n  parentRunId: string;\n  /**\n   * Session identifier propagated onto the captured child's subtree.\n   * `undefined` when the enclosing run had none.\n   */\n  sessionId?: string;\n};\n\n/**\n * Process-wide async-local store holding the current {@link RunFrame}.\n * A single shared instance so a frame installed by the supervisor is\n * visible to an agent running several `await`s deep inside a callback,\n * across module boundaries. Empty (returns `undefined`) outside any\n * orchestration callback — standalone `agent.execute()` is unaffected.\n */\nconst runFrameStore = new AsyncLocalStorage<RunFrame | undefined>();\n\n/**\n * A second async-local flag set whenever execution is nested inside a\n * parent capture — by BOTH {@link withRunFrame} (ambient capture) and\n * {@link withoutRunFrame} (explicit parent capture, which clears the frame).\n * Lets the `observeAll` gate skip self-routing a nested run regardless of\n * which capture path its parent uses — the parent already captures it.\n */\nconst nestedStore = new AsyncLocalStorage<boolean>();\n\n/**\n * Run `fn` with `frame` installed as the ambient {@link RunFrame} for\n * the entire async subtree it spawns. Restores the previous frame (or\n * none) when `fn` settles. Returns whatever `fn` returns.\n *\n * Nesting is natural: a callback that itself dispatches a nested\n * supervisor installs a fresh frame for the inner run, and the inner\n * frame shadows the outer one for the inner subtree only — exactly the\n * tree shape the report models.\n */\nexport function withRunFrame<T>(frame: RunFrame, fn: () => T): T {\n  return nestedStore.run(true, () => runFrameStore.run(frame, fn));\n}\n\n/**\n * Run `fn` with NO ambient {@link RunFrame} installed for its async\n * subtree, restoring the previous frame when `fn` settles. Used by the\n * supervisor's EXPLICIT capture paths (`ctx.run(...)` /\n * `ctx.intents.X.execute()`) — those already push the child report onto\n * the callback's `children[]` themselves, so the child must NOT also\n * self-capture via the ambient frame (which would double-count it).\n */\nexport function withoutRunFrame<T>(fn: () => T): T {\n  return nestedStore.run(true, () => runFrameStore.run(undefined, fn));\n}\n\n/**\n * Read the current ambient {@link RunFrame}, or `undefined` when no\n * orchestration callback is on the stack. An executable calls this at\n * report-build time: a present frame means \"you were invoked inside a\n * callback — attach yourself to its tree\".\n */\nexport function currentRunFrame(): RunFrame | undefined {\n  return runFrameStore.getStore();\n}\n\n/**\n * `true` when execution is nested inside a parent capture — set by\n * {@link withRunFrame} (ambient) or {@link withoutRunFrame} (explicit). Read\n * by the observe-all gate so a nested run, which its parent already captures\n * into the trace tree, is not also self-routed as a standalone top-level\n * trace. `false` for a standalone (root) run.\n */\nexport function isNestedRun(): boolean {\n  return nestedStore.getStore() === true;\n}\n\n/**\n * Capture a freshly-built child `report` onto the current ambient\n * {@link RunFrame} when one is installed. Pushes the report onto the\n * frame's `sink` so it nests under the enclosing node, and rewrites the\n * report's lineage (`rootRunId`, `parentRunId`, `sessionId`) to the\n * frame's — mirroring how `step.agent` / `ctx.run` capture child\n * reports explicitly, but driven ambiently.\n *\n * No-op (returns `false`) when no frame is installed — a standalone\n * `agent.execute()` keeps its self-root untouched. Returns `true` when\n * the report was captured so the caller can suppress its own terminal\n * lineage stamp if needed.\n *\n * The lineage rewrite is intentionally shallow on the root + deep on\n * descendants would double-stamp; callers pass the already-lineage-\n * stamped subtree (self-root), and this relinks only the root's\n * `rootRunId` / `parentRunId` / `sessionId`. Descendants already carry\n * the child's own self-root as their `rootRunId`; the enclosing\n * primitive's terminal `stampReportLineage` pass (run once on the\n * outer tree) rewrites the whole subtree to the true outer root. This\n * keeps capture cheap and defers the single authoritative relink to\n * the outer build.\n */\nexport function captureChildReport(report: BaseReport): boolean {\n  const frame = runFrameStore.getStore();\n\n  if (!frame) {\n    return false;\n  }\n\n  report.parentRunId = frame.parentRunId;\n  report.rootRunId = frame.rootRunId;\n\n  if (frame.sessionId !== undefined) {\n    report.sessionId = frame.sessionId;\n  }\n\n  frame.sink.push(report);\n\n  return true;\n}\n"],"mappings":";;;;;;;;;;AAgDA,MAAM,gBAAgB,IAAI,kBAAwC;;;;;;;;AASlE,MAAM,cAAc,IAAI,kBAA2B;;;;;;;;;;;AAYnD,SAAgB,aAAgB,OAAiB,IAAgB;CAC/D,OAAO,YAAY,IAAI,YAAY,cAAc,IAAI,OAAO,EAAE,CAAC;AACjE;;;;;;;;;AAUA,SAAgB,gBAAmB,IAAgB;CACjD,OAAO,YAAY,IAAI,YAAY,cAAc,IAAI,QAAW,EAAE,CAAC;AACrE;;;;;;;AAQA,SAAgB,kBAAwC;CACtD,OAAO,cAAc,SAAS;AAChC;;;;;;;;AASA,SAAgB,cAAuB;CACrC,OAAO,YAAY,SAAS,MAAM;AACpC;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,mBAAmB,QAA6B;CAC9D,MAAM,QAAQ,cAAc,SAAS;CAErC,IAAI,CAAC,OACH,OAAO;CAGT,OAAO,cAAc,MAAM;CAC3B,OAAO,YAAY,MAAM;CAEzB,IAAI,MAAM,cAAc,QACtB,OAAO,YAAY,MAAM;CAG3B,MAAM,KAAK,KAAK,MAAM;CAEtB,OAAO;AACT"}

package/esm/vcr/cassette-io.mjs

@@ -0,0 +1,57 @@
+//#region ../@warlock.js/ai/src/vcr/cassette-io.ts
+let fsModule;
+/**
+* Resolve `node:fs/promises` once and memoize it.
+*/
+async function loadFs() {
+	if (!fsModule) fsModule = await import("node:fs/promises");
+	return fsModule;
+}
+/**
+* Build a fresh, empty cassette for a model identity. Used when the path
+* does not exist yet (first record run).
+*/
+function emptyCassette(model, provider) {
+	return {
+		version: 1,
+		model,
+		provider,
+		entries: []
+	};
+}
+/**
+* Load a cassette from disk. Returns a fresh empty cassette (not an error)
+* when the file does not exist — the common first-record case. Any other I/O
+* or parse failure rejects so corruption is never silently swallowed.
+*/
+async function loadCassette(path, model, provider) {
+	const fs = await loadFs();
+	let raw;
+	try {
+		raw = await fs.readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return emptyCassette(model, provider);
+		throw error;
+	}
+	const parsed = JSON.parse(raw);
+	return {
+		version: 1,
+		model: parsed.model ?? model,
+		provider: parsed.provider ?? provider,
+		entries: Array.isArray(parsed.entries) ? parsed.entries : []
+	};
+}
+/**
+* Write a cassette to disk as pretty-printed JSON, creating the parent
+* directory if needed so a brand-new `./cassettes/foo.json` path just works.
+*/
+async function saveCassette(path, cassette) {
+	const fs = await loadFs();
+	const dir = (await import("node:path")).dirname(path);
+	if (dir && dir !== "." && dir !== path) await fs.mkdir(dir, { recursive: true });
+	await fs.writeFile(path, JSON.stringify(cassette, void 0, 2), "utf8");
+}
+
+//#endregion
+export { emptyCassette, loadCassette, saveCassette };
+//# sourceMappingURL=cassette-io.mjs.map

package/esm/vcr/cassette-io.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cassette-io.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/cassette-io.ts"],"sourcesContent":["import type { Cassette } from \"./vcr.type\";\n\n/**\n * Lazily-resolved `node:fs/promises` module. VCR cassette I/O only touches\n * disk on construct (load) and on `save()` — keeping the import lazy means\n * importing the `vcr` factory never eagerly pulls `node:fs`, which keeps the\n * surface usable in non-node bundles that never call a disk path.\n */\ntype FsPromises = typeof import(\"node:fs/promises\");\n\nlet fsModule: FsPromises | undefined;\n\n/**\n * Resolve `node:fs/promises` once and memoize it.\n */\nasync function loadFs(): Promise<FsPromises> {\n  if (!fsModule) {\n    fsModule = await import(\"node:fs/promises\");\n  }\n\n  return fsModule;\n}\n\n/**\n * Build a fresh, empty cassette for a model identity. Used when the path\n * does not exist yet (first record run).\n */\nexport function emptyCassette(model: string, provider: string): Cassette {\n  return {\n    version: 1,\n    model,\n    provider,\n    entries: [],\n  };\n}\n\n/**\n * Load a cassette from disk. Returns a fresh empty cassette (not an error)\n * when the file does not exist — the common first-record case. Any other I/O\n * or parse failure rejects so corruption is never silently swallowed.\n */\nexport async function loadCassette(\n  path: string,\n  model: string,\n  provider: string,\n): Promise<Cassette> {\n  const fs = await loadFs();\n\n  let raw: string;\n\n  try {\n    raw = await fs.readFile(path, \"utf8\");\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return emptyCassette(model, provider);\n    }\n\n    throw error;\n  }\n\n  const parsed = JSON.parse(raw) as Cassette;\n\n  return {\n    version: 1,\n    model: parsed.model ?? model,\n    provider: parsed.provider ?? provider,\n    entries: Array.isArray(parsed.entries) ? parsed.entries : [],\n  };\n}\n\n/**\n * Write a cassette to disk as pretty-printed JSON, creating the parent\n * directory if needed so a brand-new `./cassettes/foo.json` path just works.\n */\nexport async function saveCassette(path: string, cassette: Cassette): Promise<void> {\n  const fs = await loadFs();\n  const nodePath = await import(\"node:path\");\n  const dir = nodePath.dirname(path);\n\n  if (dir && dir !== \".\" && dir !== path) {\n    await fs.mkdir(dir, { recursive: true });\n  }\n\n  await fs.writeFile(path, JSON.stringify(cassette, undefined, 2), \"utf8\");\n}\n"],"mappings":";AAUA,IAAI;;;;AAKJ,eAAe,SAA8B;CAC3C,IAAI,CAAC,UACH,WAAW,MAAM,OAAO;CAG1B,OAAO;AACT;;;;;AAMA,SAAgB,cAAc,OAAe,UAA4B;CACvE,OAAO;EACL,SAAS;EACT;EACA;EACA,SAAS,CAAC;CACZ;AACF;;;;;;AAOA,eAAsB,aACpB,MACA,OACA,UACmB;CACnB,MAAM,KAAK,MAAM,OAAO;CAExB,IAAI;CAEJ,IAAI;EACF,MAAM,MAAM,GAAG,SAAS,MAAM,MAAM;CACtC,SAAS,OAAO;EACd,IAAK,MAAgC,SAAS,UAC5C,OAAO,cAAc,OAAO,QAAQ;EAGtC,MAAM;CACR;CAEA,MAAM,SAAS,KAAK,MAAM,GAAG;CAE7B,OAAO;EACL,SAAS;EACT,OAAO,OAAO,SAAS;EACvB,UAAU,OAAO,YAAY;EAC7B,SAAS,MAAM,QAAQ,OAAO,OAAO,IAAI,OAAO,UAAU,CAAC;CAC7D;AACF;;;;;AAMA,eAAsB,aAAa,MAAc,UAAmC;CAClF,MAAM,KAAK,MAAM,OAAO;CAExB,MAAM,OAAM,MADW,OAAO,aACV,CAAC,QAAQ,IAAI;CAEjC,IAAI,OAAO,QAAQ,OAAO,QAAQ,MAChC,MAAM,GAAG,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;CAGzC,MAAM,GAAG,UAAU,MAAM,KAAK,UAAU,UAAU,QAAW,CAAC,GAAG,MAAM;AACzE"}

package/esm/vcr/errors.d.mts

@@ -0,0 +1,42 @@
+import { AIError, AIErrorOptions } from "../errors/ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/errors.d.ts
+/**
+ * Payload for {@link VcrCassetteMissError}. Carries the looked-up request
+ * hash and the cassette path so a failing CI run names exactly which call
+ * was not recorded.
+ */
+type VcrCassetteMissErrorOptions = AIErrorOptions & {
+  /** The normalized request hash that found no matching cassette entry. */requestHash?: string; /** Cassette file path the lookup ran against. */
+  path?: string;
+};
+/**
+ * Thrown when a `vcr(model, { mode: "replay" })` call finds no cassette
+ * entry matching the request hash.
+ *
+ * **The whole point of deterministic tests.** VCR in `replay` mode never
+ * falls back to a live provider call on a miss — that would silently
+ * re-introduce network/non-determinism into a test that asked for the
+ * opposite. Instead it throws this error so the run fails loud, telling
+ * the developer to re-record the cassette (run once in `record`/`auto`).
+ *
+ * Extends {@link AIError} directly (not `ProviderError`) — a cassette miss
+ * is a harness/config failure, not a provider failure.
+ *
+ * @example
+ * try {
+ *   await vcrModel.complete(messages);
+ * } catch (error) {
+ *   if (error instanceof VcrCassetteMissError) {
+ *     console.error("Re-record the cassette:", error.path);
+ *   }
+ * }
+ */
+declare class VcrCassetteMissError extends AIError {
+  readonly requestHash?: string;
+  readonly path?: string;
+  constructor(message: string, options?: VcrCassetteMissErrorOptions);
+}
+//#endregion
+export { VcrCassetteMissError, VcrCassetteMissErrorOptions };
+//# sourceMappingURL=errors.d.mts.map

package/esm/vcr/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/errors.ts"],"mappings":";;;;AAQA;;;;KAAY,2BAAA,GAA8B,cAAc;EAEtD,yEAAA,WAAA,WAEI;EAAJ,IAAA;AAAA;;;;;;;;;;;;AA6ByE;;;;;;;;;;;cAJ9D,oBAAA,SAA6B,OAAO;EAAA,SAC/B,WAAA;EAAA,SACA,IAAA;cAEG,OAAA,UAAiB,OAAA,GAAU,2BAAA;AAAA"}

package/esm/vcr/errors.mjs

@@ -0,0 +1,37 @@
+import { AIError } from "../errors/ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/errors.ts
+/**
+* Thrown when a `vcr(model, { mode: "replay" })` call finds no cassette
+* entry matching the request hash.
+*
+* **The whole point of deterministic tests.** VCR in `replay` mode never
+* falls back to a live provider call on a miss — that would silently
+* re-introduce network/non-determinism into a test that asked for the
+* opposite. Instead it throws this error so the run fails loud, telling
+* the developer to re-record the cassette (run once in `record`/`auto`).
+*
+* Extends {@link AIError} directly (not `ProviderError`) — a cassette miss
+* is a harness/config failure, not a provider failure.
+*
+* @example
+* try {
+*   await vcrModel.complete(messages);
+* } catch (error) {
+*   if (error instanceof VcrCassetteMissError) {
+*     console.error("Re-record the cassette:", error.path);
+*   }
+* }
+*/
+var VcrCassetteMissError = class extends AIError {
+	constructor(message, options) {
+		super("VCR_CASSETTE_MISS", message, options);
+		this.name = "VcrCassetteMissError";
+		this.requestHash = options?.requestHash;
+		this.path = options?.path;
+	}
+};
+
+//#endregion
+export { VcrCassetteMissError };
+//# sourceMappingURL=errors.mjs.map

package/esm/vcr/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/errors.ts"],"sourcesContent":["import { AIError } from \"../errors/ai-error\";\nimport type { AIErrorOptions } from \"../errors/ai-error\";\n\n/**\n * Payload for {@link VcrCassetteMissError}. Carries the looked-up request\n * hash and the cassette path so a failing CI run names exactly which call\n * was not recorded.\n */\nexport type VcrCassetteMissErrorOptions = AIErrorOptions & {\n  /** The normalized request hash that found no matching cassette entry. */\n  requestHash?: string;\n  /** Cassette file path the lookup ran against. */\n  path?: string;\n};\n\n/**\n * Thrown when a `vcr(model, { mode: \"replay\" })` call finds no cassette\n * entry matching the request hash.\n *\n * **The whole point of deterministic tests.** VCR in `replay` mode never\n * falls back to a live provider call on a miss — that would silently\n * re-introduce network/non-determinism into a test that asked for the\n * opposite. Instead it throws this error so the run fails loud, telling\n * the developer to re-record the cassette (run once in `record`/`auto`).\n *\n * Extends {@link AIError} directly (not `ProviderError`) — a cassette miss\n * is a harness/config failure, not a provider failure.\n *\n * @example\n * try {\n *   await vcrModel.complete(messages);\n * } catch (error) {\n *   if (error instanceof VcrCassetteMissError) {\n *     console.error(\"Re-record the cassette:\", error.path);\n *   }\n * }\n */\nexport class VcrCassetteMissError extends AIError {\n  public readonly requestHash?: string;\n  public readonly path?: string;\n\n  public constructor(message: string, options?: VcrCassetteMissErrorOptions) {\n    super(\"VCR_CASSETTE_MISS\", message, options);\n    this.name = \"VcrCassetteMissError\";\n    this.requestHash = options?.requestHash;\n    this.path = options?.path;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,uBAAb,cAA0C,QAAQ;CAIhD,AAAO,YAAY,SAAiB,SAAuC;EACzE,MAAM,qBAAqB,SAAS,OAAO;EAC3C,KAAK,OAAO;EACZ,KAAK,cAAc,SAAS;EAC5B,KAAK,OAAO,SAAS;CACvB;AACF"}

package/esm/vcr/hash-request.d.mts

@@ -0,0 +1,28 @@
+import { Message } from "../contracts/conversation-message.type.mjs";
+import { ModelCallOptions } from "../contracts/model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/hash-request.d.ts
+/**
+ * Default `ModelCallOptions` fields folded into the request hash. These are
+ * the inputs that materially change the model's output; everything else
+ * (notably `signal` and unknown provider keys) is excluded so an otherwise
+ * identical logical call still matches its recording.
+ */
+declare const DEFAULT_HASH_OPTIONS: readonly string[];
+/**
+ * Compute the stable VCR request hash for a model call.
+ *
+ * The hash covers the full `messages` array plus the picked, normalized
+ * `options` subset (see {@link DEFAULT_HASH_OPTIONS}). Inputs are
+ * canonicalized (recursive key sort) before serialization so property order
+ * never affects the result. `signal` and unknown provider keys are excluded.
+ *
+ * @example
+ * const a = hashRequest(messages, { temperature: 0.2 });
+ * const b = hashRequest(messages, { temperature: 0.2, signal });
+ * // a === b — signal is excluded.
+ */
+declare function hashRequest(messages: Message[], options?: ModelCallOptions, hashOptions?: readonly string[]): string;
+//#endregion
+export { DEFAULT_HASH_OPTIONS, hashRequest };
+//# sourceMappingURL=hash-request.d.mts.map

package/esm/vcr/hash-request.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-request.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/hash-request.ts"],"mappings":";;;;;;AAUA;;;;cAAa,oBAAA;AAiJb;;;;;;;;;;AAGuD;;;AAHvD,iBAAgB,WAAA,CACd,QAAA,EAAU,OAAA,IACV,OAAA,GAAU,gBAAgB,EAC1B,WAAA"}

package/esm/vcr/hash-request.mjs

@@ -0,0 +1,118 @@
+//#region ../@warlock.js/ai/src/vcr/hash-request.ts
+/**
+* Default `ModelCallOptions` fields folded into the request hash. These are
+* the inputs that materially change the model's output; everything else
+* (notably `signal` and unknown provider keys) is excluded so an otherwise
+* identical logical call still matches its recording.
+*/
+const DEFAULT_HASH_OPTIONS = [
+	"temperature",
+	"maxTokens",
+	"responseSchema",
+	"tools",
+	"reasoning"
+];
+/**
+* Reduce a tool to the parts the model actually conditions on: its name,
+* description, and the *shape* of its input schema. Two tools that differ
+* only by object identity (a fresh schema instance per import) hash
+* identically; a real contract change (renamed field, new description)
+* invalidates the recording.
+*
+* The input schema is fingerprinted structurally — a Standard Schema is an
+* opaque object, so we serialize its enumerable own keys rather than
+* attempting to read its internals.
+*/
+function fingerprintTool(tool) {
+	return {
+		name: tool.name,
+		description: tool.description,
+		input: tool.input ? schemaShape(tool.input) : void 0
+	};
+}
+/**
+* Produce a stable, JSON-safe fingerprint of an arbitrary schema object.
+* Records only the structural skeleton (own enumerable keys, recursively)
+* so harmless instance differences don't perturb the hash while a genuine
+* structural change does.
+*/
+function schemaShape(value, depth = 0) {
+	if (depth > 6 || value === null || typeof value !== "object") return typeof value;
+	if (Array.isArray(value)) return value.map((item) => schemaShape(item, depth + 1));
+	const out = {};
+	for (const key of Object.keys(value).sort()) out[key] = schemaShape(value[key], depth + 1);
+	return out;
+}
+/**
+* Pick the hashable subset of `options`, normalizing `tools` into their
+* name+description+schema-shape fingerprint. `signal` and any field not in
+* `hashOptions` are dropped.
+*/
+function pickOptions(options, hashOptions) {
+	if (!options) return {};
+	const picked = {};
+	for (const key of hashOptions) {
+		const value = options[key];
+		if (value === void 0) continue;
+		if (key === "tools" && Array.isArray(value)) {
+			picked[key] = value.map(fingerprintTool);
+			continue;
+		}
+		picked[key] = value;
+	}
+	return picked;
+}
+/**
+* Recursively sort object keys so two logically-equal payloads serialize to
+* byte-identical JSON regardless of property insertion order.
+*/
+function canonicalize(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const out = {};
+	for (const key of Object.keys(value).sort()) out[key] = canonicalize(value[key]);
+	return out;
+}
+/**
+* Non-cryptographic 53-bit string hash (FNV-style, cyrb53). Deterministic
+* across runs and platforms; collision-resistant enough for a per-cassette
+* keyspace. Returned as a base-36 string.
+*/
+function hashString(input) {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+	h1 ^= Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507);
+	h2 ^= Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+/**
+* Compute the stable VCR request hash for a model call.
+*
+* The hash covers the full `messages` array plus the picked, normalized
+* `options` subset (see {@link DEFAULT_HASH_OPTIONS}). Inputs are
+* canonicalized (recursive key sort) before serialization so property order
+* never affects the result. `signal` and unknown provider keys are excluded.
+*
+* @example
+* const a = hashRequest(messages, { temperature: 0.2 });
+* const b = hashRequest(messages, { temperature: 0.2, signal });
+* // a === b — signal is excluded.
+*/
+function hashRequest(messages, options, hashOptions = DEFAULT_HASH_OPTIONS) {
+	const payload = canonicalize({
+		messages,
+		options: pickOptions(options, hashOptions)
+	});
+	return hashString(JSON.stringify(payload));
+}
+
+//#endregion
+export { DEFAULT_HASH_OPTIONS, hashRequest };
+//# sourceMappingURL=hash-request.mjs.map

package/esm/vcr/hash-request.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-request.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/hash-request.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type { ModelCallOptions } from \"../contracts/model.contract\";\nimport type { ToolConfig } from \"../contracts/tool.contract\";\n\n/**\n * Default `ModelCallOptions` fields folded into the request hash. These are\n * the inputs that materially change the model's output; everything else\n * (notably `signal` and unknown provider keys) is excluded so an otherwise\n * identical logical call still matches its recording.\n */\nexport const DEFAULT_HASH_OPTIONS: readonly string[] = [\n  \"temperature\",\n  \"maxTokens\",\n  \"responseSchema\",\n  \"tools\",\n  \"reasoning\",\n];\n\n/**\n * Reduce a tool to the parts the model actually conditions on: its name,\n * description, and the *shape* of its input schema. Two tools that differ\n * only by object identity (a fresh schema instance per import) hash\n * identically; a real contract change (renamed field, new description)\n * invalidates the recording.\n *\n * The input schema is fingerprinted structurally — a Standard Schema is an\n * opaque object, so we serialize its enumerable own keys rather than\n * attempting to read its internals.\n */\nfunction fingerprintTool(tool: ToolConfig<unknown, unknown>): unknown {\n  return {\n    name: tool.name,\n    description: tool.description,\n    input: tool.input ? schemaShape(tool.input) : undefined,\n  };\n}\n\n/**\n * Produce a stable, JSON-safe fingerprint of an arbitrary schema object.\n * Records only the structural skeleton (own enumerable keys, recursively)\n * so harmless instance differences don't perturb the hash while a genuine\n * structural change does.\n */\nfunction schemaShape(value: unknown, depth = 0): unknown {\n  if (depth > 6 || value === null || typeof value !== \"object\") {\n    return typeof value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => schemaShape(item, depth + 1));\n  }\n\n  const out: Record<string, unknown> = {};\n\n  for (const key of Object.keys(value as Record<string, unknown>).sort()) {\n    out[key] = schemaShape((value as Record<string, unknown>)[key], depth + 1);\n  }\n\n  return out;\n}\n\n/**\n * Pick the hashable subset of `options`, normalizing `tools` into their\n * name+description+schema-shape fingerprint. `signal` and any field not in\n * `hashOptions` are dropped.\n */\nfunction pickOptions(\n  options: ModelCallOptions | undefined,\n  hashOptions: readonly string[],\n): Record<string, unknown> {\n  if (!options) {\n    return {};\n  }\n\n  const picked: Record<string, unknown> = {};\n\n  for (const key of hashOptions) {\n    const value = options[key];\n\n    if (value === undefined) {\n      continue;\n    }\n\n    if (key === \"tools\" && Array.isArray(value)) {\n      picked[key] = (value as ToolConfig<unknown, unknown>[]).map(fingerprintTool);\n      continue;\n    }\n\n    picked[key] = value;\n  }\n\n  return picked;\n}\n\n/**\n * Recursively sort object keys so two logically-equal payloads serialize to\n * byte-identical JSON regardless of property insertion order.\n */\nfunction canonicalize(value: unknown): unknown {\n  if (value === null || typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(canonicalize);\n  }\n\n  const out: Record<string, unknown> = {};\n\n  for (const key of Object.keys(value as Record<string, unknown>).sort()) {\n    out[key] = canonicalize((value as Record<string, unknown>)[key]);\n  }\n\n  return out;\n}\n\n/**\n * Non-cryptographic 53-bit string hash (FNV-style, cyrb53). Deterministic\n * across runs and platforms; collision-resistant enough for a per-cassette\n * keyspace. Returned as a base-36 string.\n */\nfunction hashString(input: string): string {\n  let h1 = 0xdeadbeef;\n  let h2 = 0x41c6ce57;\n\n  for (let i = 0; i < input.length; i++) {\n    const ch = input.charCodeAt(i);\n\n    h1 = Math.imul(h1 ^ ch, 2654435761);\n    h2 = Math.imul(h2 ^ ch, 1597334677);\n  }\n\n  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);\n  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);\n  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);\n  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);\n\n  const combined = 4294967296 * (2097151 & h2) + (h1 >>> 0);\n\n  return combined.toString(36);\n}\n\n/**\n * Compute the stable VCR request hash for a model call.\n *\n * The hash covers the full `messages` array plus the picked, normalized\n * `options` subset (see {@link DEFAULT_HASH_OPTIONS}). Inputs are\n * canonicalized (recursive key sort) before serialization so property order\n * never affects the result. `signal` and unknown provider keys are excluded.\n *\n * @example\n * const a = hashRequest(messages, { temperature: 0.2 });\n * const b = hashRequest(messages, { temperature: 0.2, signal });\n * // a === b — signal is excluded.\n */\nexport function hashRequest(\n  messages: Message[],\n  options?: ModelCallOptions,\n  hashOptions: readonly string[] = DEFAULT_HASH_OPTIONS,\n): string {\n  const payload = canonicalize({\n    messages,\n    options: pickOptions(options, hashOptions),\n  });\n\n  return hashString(JSON.stringify(payload));\n}\n"],"mappings":";;;;;;;AAUA,MAAa,uBAA0C;CACrD;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;AAaA,SAAS,gBAAgB,MAA6C;CACpE,OAAO;EACL,MAAM,KAAK;EACX,aAAa,KAAK;EAClB,OAAO,KAAK,QAAQ,YAAY,KAAK,KAAK,IAAI;CAChD;AACF;;;;;;;AAQA,SAAS,YAAY,OAAgB,QAAQ,GAAY;CACvD,IAAI,QAAQ,KAAK,UAAU,QAAQ,OAAO,UAAU,UAClD,OAAO,OAAO;CAGhB,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,SAAS,YAAY,MAAM,QAAQ,CAAC,CAAC;CAGzD,MAAM,MAA+B,CAAC;CAEtC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,CAAC,CAAC,KAAK,GACnE,IAAI,OAAO,YAAa,MAAkC,MAAM,QAAQ,CAAC;CAG3E,OAAO;AACT;;;;;;AAOA,SAAS,YACP,SACA,aACyB;CACzB,IAAI,CAAC,SACH,OAAO,CAAC;CAGV,MAAM,SAAkC,CAAC;CAEzC,KAAK,MAAM,OAAO,aAAa;EAC7B,MAAM,QAAQ,QAAQ;EAEtB,IAAI,UAAU,QACZ;EAGF,IAAI,QAAQ,WAAW,MAAM,QAAQ,KAAK,GAAG;GAC3C,OAAO,OAAQ,MAAyC,IAAI,eAAe;GAC3E;EACF;EAEA,OAAO,OAAO;CAChB;CAEA,OAAO;AACT;;;;;AAMA,SAAS,aAAa,OAAyB;CAC7C,IAAI,UAAU,QAAQ,OAAO,UAAU,UACrC,OAAO;CAGT,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,IAAI,YAAY;CAG/B,MAAM,MAA+B,CAAC;CAEtC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,CAAC,CAAC,KAAK,GACnE,IAAI,OAAO,aAAc,MAAkC,IAAI;CAGjE,OAAO;AACT;;;;;;AAOA,SAAS,WAAW,OAAuB;CACzC,IAAI,KAAK;CACT,IAAI,KAAK;CAET,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,KAAK,MAAM,WAAW,CAAC;EAE7B,KAAK,KAAK,KAAK,KAAK,IAAI,UAAU;EAClC,KAAK,KAAK,KAAK,KAAK,IAAI,UAAU;CACpC;CAEA,KAAK,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAC3C,MAAM,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAC5C,KAAK,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAC3C,MAAM,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAI5C,QAFiB,cAAc,UAAU,OAAO,OAAO,GAExC,CAAC,SAAS,EAAE;AAC7B;;;;;;;;;;;;;;AAeA,SAAgB,YACd,UACA,SACA,cAAiC,sBACzB;CACR,MAAM,UAAU,aAAa;EAC3B;EACA,SAAS,YAAY,SAAS,WAAW;CAC3C,CAAC;CAED,OAAO,WAAW,KAAK,UAAU,OAAO,CAAC;AAC3C"}

package/esm/vcr/index.d.mts

@@ -0,0 +1,4 @@
+import { Cassette, CassetteEntry, VcrMode, VcrModel, VcrOptions } from "./vcr.type.mjs";
+import { vcr } from "./vcr.mjs";
+import { VcrCassetteMissError, VcrCassetteMissErrorOptions } from "./errors.mjs";
+import { DEFAULT_HASH_OPTIONS, hashRequest } from "./hash-request.mjs";

package/esm/vcr/index.mjs

@@ -0,0 +1,5 @@
+import { VcrCassetteMissError } from "./errors.mjs";
+import { DEFAULT_HASH_OPTIONS, hashRequest } from "./hash-request.mjs";
+import { vcr } from "./vcr.mjs";
+
+export {  };

package/esm/vcr/vcr.d.mts

@@ -0,0 +1,32 @@
+import { ModelContract } from "../contracts/model.contract.mjs";
+import { VcrModel, VcrOptions } from "./vcr.type.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/vcr.d.ts
+/**
+ * Wrap any `ModelContract` in a record/replay decorator backed by a JSON
+ * cassette on disk.
+ *
+ * **What it does.** Intercepts only `complete()`/`stream()` — the single
+ * seam every agent trip funnels through — and delegates `name`, `provider`,
+ * `capabilities`, and `pricing` to the inner model untouched. On a call it
+ * computes a stable hash over `{ messages, picked options }` and, depending
+ * on `mode`:
+ *
+ * - **`record`** — always calls the inner model and appends a cassette entry.
+ * - **`replay`** — returns the matching entry (or re-yields its chunks /
+ *   re-throws its error); a miss throws `VcrCassetteMissError`, never a live
+ *   call.
+ * - **`auto`** (default) — replays a hit, records a miss.
+ *
+ * Composes *below* `fallbackModel` and works with any adapter because it
+ * depends only on `ModelContract`. Call `save()` to flush new entries.
+ *
+ * @example
+ * const model = vcr(liveModel, { path: "./cassettes/support.json" });
+ * const response = await model.complete(messages);
+ * await model.save(); // first run records; later runs replay deterministically.
+ */
+declare function vcr(model: ModelContract, options: VcrOptions): VcrModel;
+//#endregion
+export { vcr };
+//# sourceMappingURL=vcr.d.mts.map

package/esm/vcr/vcr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/vcr.ts"],"mappings":";;;;;;AA8UA;;;;;;;;;;;;;;AAAwE;;;;;;;;iBAAxD,GAAA,CAAI,KAAA,EAAO,aAAA,EAAe,OAAA,EAAS,UAAA,GAAa,QAAA"}