@warlock.js/core 4.4.0 → 4.5.0

package/esm/ai/src/utils/stamp-report-lineage.mjs

@@ -0,0 +1,45 @@
+//#region ../@warlock.js/ai/src/utils/stamp-report-lineage.ts
+/**
+* Walk a freshly-built report tree and stamp lineage fields onto
+* every node:
+*
+* - `rootRunId` — rewritten to `stamp.rootRunId` everywhere. Composite
+*   children built by inner primitives carry their own self-root; this
+*   walk overrides it so the outer root wins (single coherent run id
+*   across the whole tree).
+* - `parentRunId` — root node gets `stamp.parentRunId`; descendants
+*   derive theirs from each parent's own `runId`.
+* - `sessionId` — propagated when provided.
+* - `reportSchemaVersion` — stamped only on the root (the value is the
+*   same for the whole tree; storing it on every node would waste
+*   space).
+*
+* Designed to run ONCE per top-level `buildResult` call. Each
+* primitive's executor invokes this on the assembled root report just
+* before returning; nested primitives produced their own subtree with
+* a self-root, and this pass relinks everything to the outer caller's
+* lineage.
+*
+* Mutates the report in place — internal use only, before the report
+* is exposed via `result.report`.
+*
+* @example
+* const root = this.buildBareReport();
+* stampReportLineage(root, { rootRunId: this.runId, sessionId: this.options?.sessionId });
+* return { ..., report: root };
+*/
+function stampReportLineage(root, stamp) {
+	root.reportSchemaVersion = 1;
+	walk(root, stamp.rootRunId, stamp.parentRunId, stamp.sessionId);
+}
+function walk(node, rootRunId, parentRunId, sessionId) {
+	node.rootRunId = rootRunId;
+	if (parentRunId !== void 0) node.parentRunId = parentRunId;
+	else delete node.parentRunId;
+	if (sessionId !== void 0) node.sessionId = sessionId;
+	for (const child of node.children) walk(child, rootRunId, node.runId, sessionId);
+}
+
+//#endregion
+export { stampReportLineage };
+//# sourceMappingURL=stamp-report-lineage.mjs.map

package/esm/ai/src/utils/stamp-report-lineage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp-report-lineage.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/utils/stamp-report-lineage.ts"],"sourcesContent":["import type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\n\n/**\n * Options for {@link stampReportLineage}. Every field is optional —\n * the caller supplies whichever pieces it knows. Missing pieces are\n * left untouched (existing values on the report survive).\n */\nexport type LineageStamp = {\n  /**\n   * The outermost run-id this subtree belongs to. When set, EVERY\n   * node in the subtree gets its `rootRunId` rewritten to this\n   * value — overrides any inner self-roots produced by nested\n   * `buildResult` calls.\n   */\n  rootRunId: string;\n  /**\n   * Run-id of the immediate parent of THIS subtree's top node. Each\n   * descendant's `parentRunId` is then derived from its own walk\n   * position (its parent's `runId`).\n   */\n  parentRunId?: string;\n  /**\n   * Caller-supplied session identifier — propagates to every node in\n   * the subtree. Skipped when undefined.\n   */\n  sessionId?: string;\n};\n\n/**\n * Walk a freshly-built report tree and stamp lineage fields onto\n * every node:\n *\n * - `rootRunId` — rewritten to `stamp.rootRunId` everywhere. Composite\n *   children built by inner primitives carry their own self-root; this\n *   walk overrides it so the outer root wins (single coherent run id\n *   across the whole tree).\n * - `parentRunId` — root node gets `stamp.parentRunId`; descendants\n *   derive theirs from each parent's own `runId`.\n * - `sessionId` — propagated when provided.\n * - `reportSchemaVersion` — stamped only on the root (the value is the\n *   same for the whole tree; storing it on every node would waste\n *   space).\n *\n * Designed to run ONCE per top-level `buildResult` call. Each\n * primitive's executor invokes this on the assembled root report just\n * before returning; nested primitives produced their own subtree with\n * a self-root, and this pass relinks everything to the outer caller's\n * lineage.\n *\n * Mutates the report in place — internal use only, before the report\n * is exposed via `result.report`.\n *\n * @example\n * const root = this.buildBareReport();\n * stampReportLineage(root, { rootRunId: this.runId, sessionId: this.options?.sessionId });\n * return { ..., report: root };\n */\nexport function stampReportLineage(root: BaseReport, stamp: LineageStamp): void {\n  root.reportSchemaVersion = REPORT_SCHEMA_VERSION;\n\n  walk(root, stamp.rootRunId, stamp.parentRunId, stamp.sessionId);\n}\n\nfunction walk(node: BaseReport, rootRunId: string, parentRunId?: string, sessionId?: string): void {\n  node.rootRunId = rootRunId;\n\n  if (parentRunId !== undefined) {\n    node.parentRunId = parentRunId;\n  } else {\n    delete node.parentRunId;\n  }\n\n  if (sessionId !== undefined) {\n    node.sessionId = sessionId;\n  }\n\n  for (const child of node.children) {\n    walk(child, rootRunId, node.runId, sessionId);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,SAAgB,mBAAmB,MAAkB,OAA2B;CAC9E,KAAK;CAEL,KAAK,MAAM,MAAM,WAAW,MAAM,aAAa,MAAM,SAAS;AAChE;AAEA,SAAS,KAAK,MAAkB,WAAmB,aAAsB,WAA0B;CACjG,KAAK,YAAY;CAEjB,IAAI,gBAAgB,QAClB,KAAK,cAAc;MAEnB,OAAO,KAAK;CAGd,IAAI,cAAc,QAChB,KAAK,YAAY;CAGnB,KAAK,MAAM,SAAS,KAAK,UACvB,KAAK,OAAO,WAAW,KAAK,OAAO,SAAS;AAEhD"}

package/esm/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/vcr/vcr.mjs

@@ -0,0 +1,248 @@
+import { redact } from "../security/redact.mjs";
+import { emptyCassette, loadCassette, saveCassette } from "./cassette-io.mjs";
+import { VcrCassetteMissError } from "./errors.mjs";
+import { DEFAULT_HASH_OPTIONS, hashRequest } from "./hash-request.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/vcr.ts
+/**
+* Internal decorator that wraps an inner `ModelContract`, intercepting only
+* `complete()`/`stream()` and delegating every identity getter to the inner
+* model. Drives the record/replay state machine over a single in-memory
+* {@link Cassette}.
+*
+* **Why a class.** It holds mutable per-instance state (the loaded cassette,
+* the dirty flag, the load promise) behind a stable `ModelContract` surface;
+* the public API is the `vcr()` factory, never `new`.
+*/
+var Vcr = class {
+	constructor(inner, options) {
+		this.inner = inner;
+		this.dirty = false;
+		this.warnedVerbatim = false;
+		this.path = options.path;
+		this.mode = options.mode ?? "auto";
+		this.hashOptions = options.hashOptions ?? DEFAULT_HASH_OPTIONS;
+		this.recordRequest = options.recordRequest ?? "verbatim";
+		this.redactRequestHook = options.redactRequest;
+		this.redactResponseHook = options.redactResponse;
+		this.redactErrorHook = options.redactError;
+		this.loadedCassette = emptyCassette(inner.name, inner.provider);
+	}
+	/** Inner model identifier — delegated verbatim. */
+	get name() {
+		return this.inner.name;
+	}
+	/** Inner provider — delegated verbatim. */
+	get provider() {
+		return this.inner.provider;
+	}
+	/** Inner capability flags — delegated verbatim. */
+	get capabilities() {
+		return this.inner.capabilities;
+	}
+	/** Inner pricing — delegated verbatim so cost accounting is unchanged. */
+	get pricing() {
+		return this.inner.pricing;
+	}
+	/** Loaded/recorded cassette, exposed for assertions. */
+	get cassette() {
+		return this.loadedCassette;
+	}
+	/**
+	* Load the on-disk cassette exactly once. Pure `record` mode skips the
+	* read — it always writes fresh — but the in-memory cassette still starts
+	* empty so a record run never accidentally replays a stale entry.
+	*/
+	async ensureLoaded() {
+		if (this.loadPromise) return this.loadPromise;
+		this.loadPromise = this.mode === "record" ? Promise.resolve() : (async () => {
+			this.loadedCassette = await loadCassette(this.path, this.inner.name, this.inner.provider);
+		})();
+		return this.loadPromise;
+	}
+	/** Find a recorded entry whose hash matches the current request. */
+	findEntry(hash) {
+		return this.loadedCassette.entries.find((entry) => entry.requestHash === hash);
+	}
+	/** Re-throw a recorded error by reconstructing a plain `Error`. */
+	throwRecordedError(entry) {
+		const error = new Error(entry.error?.message ?? "Recorded error");
+		error.name = entry.error?.name ?? "Error";
+		throw error;
+	}
+	/**
+	* Non-streaming call. In `replay` a miss throws; in `auto`/`record` a miss
+	* calls the inner model and records the outcome (response or error).
+	*/
+	async complete(messages, options) {
+		await this.ensureLoaded();
+		const hash = hashRequest(messages, options, this.hashOptions);
+		if (this.mode !== "record") {
+			const entry = this.findEntry(hash);
+			if (entry) {
+				if (entry.error) this.throwRecordedError(entry);
+				if (entry.response) return entry.response;
+			}
+			if (this.mode === "replay") throw new VcrCassetteMissError(`No cassette entry for this request (model "${this.inner.name}", hash ${hash}).`, {
+				requestHash: hash,
+				path: this.path
+			});
+		}
+		try {
+			const response = await this.inner.complete(messages, options);
+			this.record({
+				requestHash: hash,
+				request: {
+					messages,
+					options
+				},
+				response
+			});
+			return response;
+		} catch (error) {
+			this.record({
+				requestHash: hash,
+				request: {
+					messages,
+					options
+				},
+				error: {
+					name: error.name,
+					message: error.message
+				}
+			});
+			throw error;
+		}
+	}
+	/**
+	* Streaming call. On replay the stored `chunks` are re-yielded in order
+	* (reproducing the `delta`/`tool-call`/`done` sequence) or the stored
+	* error is re-thrown. On record the inner stream is buffered into
+	* `chunks[]` while being re-emitted, then recorded once exhausted.
+	*/
+	async *stream(messages, options) {
+		await this.ensureLoaded();
+		const hash = hashRequest(messages, options, this.hashOptions);
+		if (this.mode !== "record") {
+			const entry = this.findEntry(hash);
+			if (entry) {
+				if (entry.error) this.throwRecordedError(entry);
+				if (entry.chunks) {
+					for (const chunk of entry.chunks) yield chunk;
+					return;
+				}
+			}
+			if (this.mode === "replay") throw new VcrCassetteMissError(`No cassette entry for this request (model "${this.inner.name}", hash ${hash}).`, {
+				requestHash: hash,
+				path: this.path
+			});
+		}
+		const chunks = [];
+		try {
+			for await (const chunk of this.inner.stream(messages, options)) {
+				chunks.push(chunk);
+				yield chunk;
+			}
+		} catch (error) {
+			this.record({
+				requestHash: hash,
+				request: {
+					messages,
+					options
+				},
+				error: {
+					name: error.name,
+					message: error.message
+				}
+			});
+			throw error;
+		}
+		this.record({
+			requestHash: hash,
+			request: {
+				messages,
+				options
+			},
+			chunks
+		});
+	}
+	/**
+	* Append an entry to the in-memory cassette and mark it dirty, applying
+	* the configured request/response/error redaction first (S2). Pure
+	* `replay` never reaches this path, so no replay run is ever dirtied.
+	*/
+	record(entry) {
+		this.loadedCassette.entries.push(this.applyRedaction(entry));
+		this.dirty = true;
+		this.maybeWarnVerbatim();
+	}
+	/**
+	* Apply the persisted-body privacy controls to an entry before it is
+	* stored. The request body follows `recordRequest`; response/error
+	* redactors are applied only when supplied. Replay matching is by the
+	* recomputed hash (kept verbatim), so none of this affects replay.
+	*/
+	applyRedaction(entry) {
+		const out = {
+			requestHash: entry.requestHash,
+			request: entry.request
+		};
+		if (this.recordRequest === "hash-only") out.request = { messages: [] };
+		else if (this.recordRequest === "redacted") out.request = this.redactRequestHook ? this.redactRequestHook(entry.request) : redact(entry.request);
+		if (entry.response) out.response = this.redactResponseHook ? this.redactResponseHook(entry.response) : entry.response;
+		if (entry.chunks) out.chunks = entry.chunks;
+		if (entry.error) out.error = this.redactErrorHook ? this.redactErrorHook(entry.error) : entry.error;
+		return out;
+	}
+	/**
+	* Warn once (outside tests) when the cassette is recording verbatim
+	* request bodies — they may carry prompts, tool args, and PII, so the
+	* file is not safe to commit until sanitized.
+	*/
+	maybeWarnVerbatim() {
+		if (this.warnedVerbatim || this.recordRequest !== "verbatim") return;
+		if (process.env.VITEST || process.env.NODE_ENV === "test") return;
+		this.warnedVerbatim = true;
+		console.warn(`[warlock-ai] VCR is recording verbatim request bodies to "${this.path}" — prompts, tool args, and any PII are stored unredacted. Sanitize before committing, or set recordRequest: "redacted" | "hash-only".`);
+	}
+	/**
+	* Flush newly recorded entries to `path`. No-op when nothing was recorded
+	* (pure replay, or a record/auto run that only ever hit cached entries).
+	*/
+	async save() {
+		if (!this.dirty) return;
+		await saveCassette(this.path, this.loadedCassette);
+		this.dirty = false;
+	}
+};
+/**
+* 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.
+*/
+function vcr(model, options) {
+	return new Vcr(model, options);
+}
+
+//#endregion
+export { vcr };
+//# sourceMappingURL=vcr.mjs.map

package/esm/ai/src/vcr/vcr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/vcr/vcr.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type {\n  ModelCallOptions,\n  ModelCapabilities,\n  ModelContract,\n  ModelResponse,\n  ModelStreamChunk,\n} from \"../contracts/model.contract\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport { redact } from \"../security/redact\";\nimport { emptyCassette, loadCassette, saveCassette } from \"./cassette-io\";\nimport { VcrCassetteMissError } from \"./errors\";\nimport { DEFAULT_HASH_OPTIONS, hashRequest } from \"./hash-request\";\nimport type { Cassette, CassetteEntry, VcrMode, VcrModel, VcrOptions } from \"./vcr.type\";\n\n/**\n * Internal decorator that wraps an inner `ModelContract`, intercepting only\n * `complete()`/`stream()` and delegating every identity getter to the inner\n * model. Drives the record/replay state machine over a single in-memory\n * {@link Cassette}.\n *\n * **Why a class.** It holds mutable per-instance state (the loaded cassette,\n * the dirty flag, the load promise) behind a stable `ModelContract` surface;\n * the public API is the `vcr()` factory, never `new`.\n */\nclass Vcr implements VcrModel {\n  private readonly mode: VcrMode;\n  private readonly path: string;\n  private readonly hashOptions: readonly string[];\n\n  /** Loaded + newly recorded entries. Mutated in place as we record. */\n  private loadedCassette: Cassette;\n\n  /** Set when an entry is recorded so `save()` knows there's work to flush. */\n  private dirty = false;\n\n  /** One-shot lazy load of the on-disk cassette, shared across calls. */\n  private loadPromise: Promise<void> | undefined;\n\n  /** Persisted-body privacy controls (S2). */\n  private readonly recordRequest: NonNullable<VcrOptions[\"recordRequest\"]>;\n  private readonly redactRequestHook: VcrOptions[\"redactRequest\"];\n  private readonly redactResponseHook: VcrOptions[\"redactResponse\"];\n  private readonly redactErrorHook: VcrOptions[\"redactError\"];\n\n  /** Verbatim-recording warning fires at most once per instance. */\n  private warnedVerbatim = false;\n\n  public constructor(\n    private readonly inner: ModelContract,\n    options: VcrOptions,\n  ) {\n    this.path = options.path;\n    this.mode = options.mode ?? \"auto\";\n    this.hashOptions = options.hashOptions ?? DEFAULT_HASH_OPTIONS;\n    this.recordRequest = options.recordRequest ?? \"verbatim\";\n    this.redactRequestHook = options.redactRequest;\n    this.redactResponseHook = options.redactResponse;\n    this.redactErrorHook = options.redactError;\n    this.loadedCassette = emptyCassette(inner.name, inner.provider);\n  }\n\n  /** Inner model identifier — delegated verbatim. */\n  public get name(): string {\n    return this.inner.name;\n  }\n\n  /** Inner provider — delegated verbatim. */\n  public get provider(): string {\n    return this.inner.provider;\n  }\n\n  /** Inner capability flags — delegated verbatim. */\n  public get capabilities(): ModelCapabilities | undefined {\n    return this.inner.capabilities;\n  }\n\n  /** Inner pricing — delegated verbatim so cost accounting is unchanged. */\n  public get pricing(): ModelPricing | undefined {\n    return this.inner.pricing;\n  }\n\n  /** Loaded/recorded cassette, exposed for assertions. */\n  public get cassette(): Cassette {\n    return this.loadedCassette;\n  }\n\n  /**\n   * Load the on-disk cassette exactly once. Pure `record` mode skips the\n   * read — it always writes fresh — but the in-memory cassette still starts\n   * empty so a record run never accidentally replays a stale entry.\n   */\n  private async ensureLoaded(): Promise<void> {\n    if (this.loadPromise) {\n      return this.loadPromise;\n    }\n\n    this.loadPromise =\n      this.mode === \"record\"\n        ? Promise.resolve()\n        : (async () => {\n            this.loadedCassette = await loadCassette(\n              this.path,\n              this.inner.name,\n              this.inner.provider,\n            );\n          })();\n\n    return this.loadPromise;\n  }\n\n  /** Find a recorded entry whose hash matches the current request. */\n  private findEntry(hash: string): CassetteEntry | undefined {\n    return this.loadedCassette.entries.find((entry) => entry.requestHash === hash);\n  }\n\n  /** Re-throw a recorded error by reconstructing a plain `Error`. */\n  private throwRecordedError(entry: CassetteEntry): never {\n    const error = new Error(entry.error?.message ?? \"Recorded error\");\n\n    error.name = entry.error?.name ?? \"Error\";\n\n    throw error;\n  }\n\n  /**\n   * Non-streaming call. In `replay` a miss throws; in `auto`/`record` a miss\n   * calls the inner model and records the outcome (response or error).\n   */\n  public async complete(messages: Message[], options?: ModelCallOptions): Promise<ModelResponse> {\n    await this.ensureLoaded();\n\n    const hash = hashRequest(messages, options, this.hashOptions);\n\n    if (this.mode !== \"record\") {\n      const entry = this.findEntry(hash);\n\n      if (entry) {\n        if (entry.error) {\n          this.throwRecordedError(entry);\n        }\n\n        if (entry.response) {\n          return entry.response;\n        }\n      }\n\n      if (this.mode === \"replay\") {\n        throw new VcrCassetteMissError(\n          `No cassette entry for this request (model \"${this.inner.name}\", hash ${hash}).`,\n          { requestHash: hash, path: this.path },\n        );\n      }\n    }\n\n    try {\n      const response = await this.inner.complete(messages, options);\n\n      this.record({ requestHash: hash, request: { messages, options }, response });\n\n      return response;\n    } catch (error) {\n      this.record({\n        requestHash: hash,\n        request: { messages, options },\n        error: { name: (error as Error).name, message: (error as Error).message },\n      });\n\n      throw error;\n    }\n  }\n\n  /**\n   * Streaming call. On replay the stored `chunks` are re-yielded in order\n   * (reproducing the `delta`/`tool-call`/`done` sequence) or the stored\n   * error is re-thrown. On record the inner stream is buffered into\n   * `chunks[]` while being re-emitted, then recorded once exhausted.\n   */\n  public async *stream(\n    messages: Message[],\n    options?: ModelCallOptions,\n  ): AsyncIterable<ModelStreamChunk> {\n    await this.ensureLoaded();\n\n    const hash = hashRequest(messages, options, this.hashOptions);\n\n    if (this.mode !== \"record\") {\n      const entry = this.findEntry(hash);\n\n      if (entry) {\n        if (entry.error) {\n          this.throwRecordedError(entry);\n        }\n\n        if (entry.chunks) {\n          for (const chunk of entry.chunks) {\n            yield chunk;\n          }\n\n          return;\n        }\n      }\n\n      if (this.mode === \"replay\") {\n        throw new VcrCassetteMissError(\n          `No cassette entry for this request (model \"${this.inner.name}\", hash ${hash}).`,\n          { requestHash: hash, path: this.path },\n        );\n      }\n    }\n\n    const chunks: ModelStreamChunk[] = [];\n\n    try {\n      for await (const chunk of this.inner.stream(messages, options)) {\n        chunks.push(chunk);\n\n        yield chunk;\n      }\n    } catch (error) {\n      this.record({\n        requestHash: hash,\n        request: { messages, options },\n        error: { name: (error as Error).name, message: (error as Error).message },\n      });\n\n      throw error;\n    }\n\n    this.record({ requestHash: hash, request: { messages, options }, chunks });\n  }\n\n  /**\n   * Append an entry to the in-memory cassette and mark it dirty, applying\n   * the configured request/response/error redaction first (S2). Pure\n   * `replay` never reaches this path, so no replay run is ever dirtied.\n   */\n  private record(entry: CassetteEntry): void {\n    this.loadedCassette.entries.push(this.applyRedaction(entry));\n    this.dirty = true;\n    this.maybeWarnVerbatim();\n  }\n\n  /**\n   * Apply the persisted-body privacy controls to an entry before it is\n   * stored. The request body follows `recordRequest`; response/error\n   * redactors are applied only when supplied. Replay matching is by the\n   * recomputed hash (kept verbatim), so none of this affects replay.\n   */\n  private applyRedaction(entry: CassetteEntry): CassetteEntry {\n    const out: CassetteEntry = {\n      requestHash: entry.requestHash,\n      request: entry.request,\n    };\n\n    if (this.recordRequest === \"hash-only\") {\n      out.request = { messages: [] };\n    } else if (this.recordRequest === \"redacted\") {\n      out.request = this.redactRequestHook\n        ? this.redactRequestHook(entry.request)\n        : redact(entry.request);\n    }\n\n    if (entry.response) {\n      out.response = this.redactResponseHook\n        ? this.redactResponseHook(entry.response)\n        : entry.response;\n    }\n    if (entry.chunks) {\n      out.chunks = entry.chunks;\n    }\n    if (entry.error) {\n      out.error = this.redactErrorHook\n        ? this.redactErrorHook(entry.error)\n        : entry.error;\n    }\n\n    return out;\n  }\n\n  /**\n   * Warn once (outside tests) when the cassette is recording verbatim\n   * request bodies — they may carry prompts, tool args, and PII, so the\n   * file is not safe to commit until sanitized.\n   */\n  private maybeWarnVerbatim(): void {\n    if (this.warnedVerbatim || this.recordRequest !== \"verbatim\") return;\n    if (process.env.VITEST || process.env.NODE_ENV === \"test\") return;\n\n    this.warnedVerbatim = true;\n    console.warn(\n      `[warlock-ai] VCR is recording verbatim request bodies to \"${this.path}\" — prompts, tool args, and any PII are stored unredacted. ` +\n        'Sanitize before committing, or set recordRequest: \"redacted\" | \"hash-only\".',\n    );\n  }\n\n  /**\n   * Flush newly recorded entries to `path`. No-op when nothing was recorded\n   * (pure replay, or a record/auto run that only ever hit cached entries).\n   */\n  public async save(): Promise<void> {\n    if (!this.dirty) {\n      return;\n    }\n\n    await saveCassette(this.path, this.loadedCassette);\n    this.dirty = false;\n  }\n}\n\n/**\n * Wrap any `ModelContract` in a record/replay decorator backed by a JSON\n * cassette on disk.\n *\n * **What it does.** Intercepts only `complete()`/`stream()` — the single\n * seam every agent trip funnels through — and delegates `name`, `provider`,\n * `capabilities`, and `pricing` to the inner model untouched. On a call it\n * computes a stable hash over `{ messages, picked options }` and, depending\n * on `mode`:\n *\n * - **`record`** — always calls the inner model and appends a cassette entry.\n * - **`replay`** — returns the matching entry (or re-yields its chunks /\n *   re-throws its error); a miss throws `VcrCassetteMissError`, never a live\n *   call.\n * - **`auto`** (default) — replays a hit, records a miss.\n *\n * Composes *below* `fallbackModel` and works with any adapter because it\n * depends only on `ModelContract`. Call `save()` to flush new entries.\n *\n * @example\n * const model = vcr(liveModel, { path: \"./cassettes/support.json\" });\n * const response = await model.complete(messages);\n * await model.save(); // first run records; later runs replay deterministically.\n */\nexport function vcr(model: ModelContract, options: VcrOptions): VcrModel {\n  return new Vcr(model, options);\n}\n"],"mappings":"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"}

package/esm/ai/src/workflow/as-tool.mjs

@@ -0,0 +1,49 @@
+import { WorkflowError } from "../errors/workflow-error.mjs";
+import "../errors/index.mjs";
+import { compositeAsTool } from "../tool/tool.mjs";
+
+//#region ../@warlock.js/ai/src/workflow/as-tool.ts
+/**
+* Wrap a `WorkflowInstance` as a `ToolContract` so an agent can invoke
+* it inside its tool-call loop. Closes the agent-calls-workflow
+* composition gap.
+*
+* Behavior:
+* - Tool `name` mirrors `workflow.name` — workflows without a name throw
+*   `WorkflowError` at wrap time (the agent surface needs a stable id).
+* - Tool `input` is the supplied `inputSchema`; the validated value is
+*   forwarded straight to `workflow.execute(input)`.
+* - On `result.error`, the workflow error is wrapped in
+*   `ToolExecutionError` with `cause` set to the original
+*   `WorkflowError` subclass — the agent's tool-call loop sees a
+*   uniform error class regardless of which primitive failed.
+*
+* @example
+* const wf = workflow({ name: "triage", steps: [...] });
+* const triageTool = asTool(wf, {
+*   description: "Run the support-ticket triage flow",
+*   inputSchema: ticketSchema,
+* });
+* const a = ai.agent({ model, tools: [triageTool] });
+*/
+function asTool(workflowInstance, options) {
+	if (!workflowInstance.name || typeof workflowInstance.name !== "string") throw new WorkflowError("workflow.asTool(): workflow must have a `name` to be wrapped as a tool");
+	return compositeAsTool({
+		name: workflowInstance.name,
+		description: options.description ?? `Invoke workflow "${workflowInstance.name}" as a tool.`,
+		input: options.inputSchema,
+		execute: async (input, ctx) => {
+			const result = await workflowInstance.execute(input, ctx?.signal ? { signal: ctx.signal } : void 0);
+			if (result.error) throw result.error;
+			return {
+				data: result.data,
+				usage: result.usage,
+				report: result.report
+			};
+		}
+	});
+}
+
+//#endregion
+export { asTool };
+//# sourceMappingURL=as-tool.mjs.map

package/esm/ai/src/workflow/as-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/workflow/as-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { WorkflowInstance } from \"../contracts/workflow/workflow.contract\";\nimport { WorkflowError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"../tool/tool\";\n\n/**\n * Wrap a `WorkflowInstance` as a `ToolContract` so an agent can invoke\n * it inside its tool-call loop. Closes the agent-calls-workflow\n * composition gap.\n *\n * Behavior:\n * - Tool `name` mirrors `workflow.name` — workflows without a name throw\n *   `WorkflowError` at wrap time (the agent surface needs a stable id).\n * - Tool `input` is the supplied `inputSchema`; the validated value is\n *   forwarded straight to `workflow.execute(input)`.\n * - On `result.error`, the workflow error is wrapped in\n *   `ToolExecutionError` with `cause` set to the original\n *   `WorkflowError` subclass — the agent's tool-call loop sees a\n *   uniform error class regardless of which primitive failed.\n *\n * @example\n * const wf = workflow({ name: \"triage\", steps: [...] });\n * const triageTool = asTool(wf, {\n *   description: \"Run the support-ticket triage flow\",\n *   inputSchema: ticketSchema,\n * });\n * const a = ai.agent({ model, tools: [triageTool] });\n */\nexport function asTool<TInput, TOutput, TToolInput = TInput>(\n  workflowInstance: WorkflowInstance<TInput, TOutput>,\n  options: {\n    description?: string;\n    inputSchema: StandardSchemaV1<TToolInput>;\n  },\n): ToolContract<TToolInput, TOutput> {\n  if (!workflowInstance.name || typeof workflowInstance.name !== \"string\") {\n    throw new WorkflowError(\n      \"workflow.asTool(): workflow must have a `name` to be wrapped as a tool\",\n    );\n  }\n\n  return compositeAsTool<TToolInput, TOutput>({\n    name: workflowInstance.name,\n    description: options.description ?? `Invoke workflow \"${workflowInstance.name}\" as a tool.`,\n    input: options.inputSchema,\n    execute: async (input, ctx) => {\n      // Relay the outer agent's cancellation signal so cancelling the\n      // parent aborts this nested workflow run (C2).\n      const result = await workflowInstance.execute(\n        input as unknown as TInput,\n        ctx?.signal ? { signal: ctx.signal } : undefined,\n      );\n\n      if (result.error) {\n        // Throw the workflow error so the surrounding wrapper catches\n        // it and produces a `ToolExecutionError` with `cause` pointing\n        // back at the original `WorkflowError` subclass — keeps the\n        // agent's tool-call loop seeing one uniform error class\n        // regardless of which primitive failed.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage,\n        report: result.report,\n      };\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,OACd,kBACA,SAImC;CACnC,IAAI,CAAC,iBAAiB,QAAQ,OAAO,iBAAiB,SAAS,UAC7D,MAAM,IAAI,cACR,wEACF;CAGF,OAAO,gBAAqC;EAC1C,MAAM,iBAAiB;EACvB,aAAa,QAAQ,eAAe,oBAAoB,iBAAiB,KAAK;EAC9E,OAAO,QAAQ;EACf,SAAS,OAAO,OAAO,QAAQ;GAG7B,MAAM,SAAS,MAAM,iBAAiB,QACpC,OACA,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MACzC;GAEA,IAAI,OAAO,OAMT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH"}