@warlock.js/ai 4.4.0 → 4.5.0

package/esm/utils/prepare-attachment-part.mjs

@@ -1,8 +1,10 @@
 import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import { OutboundPolicyError } from "../errors/outbound-policy-error.mjs";
 import "../errors/index.mjs";
+import { fetchTextWithPolicy } from "../security/outbound-policy.mjs";
 import { resolveAttachment } from "./resolve-attachment.mjs";
 import { readFile } from "node:fs/promises";
-import { extname } from "node:path";
+import { extname, isAbsolute, relative, resolve } from "node:path";
 
 //#region ../@warlock.js/ai/src/utils/prepare-attachment-part.ts
 const IMAGE_EXTENSIONS_TO_MEDIA_TYPE = {
@@ -13,6 +15,14 @@ const IMAGE_EXTENSIONS_TO_MEDIA_TYPE = {
 	".gif": "image/gif"
 };
 const TEXT_EXTENSIONS = new Set([".txt"]);
+const AUDIO_EXTENSIONS_TO_MEDIA_TYPE = {
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".m4a": "audio/mp4",
+	".ogg": "audio/ogg",
+	".weba": "audio/webm"
+};
+const PDF_EXTENSIONS = new Set([".pdf"]);
 /**
 * Convert a user-supplied `Attachment` into a provider-ready
 * `ContentPart` the model adapter can consume without doing any I/O of
@@ -40,10 +50,21 @@ const TEXT_EXTENSIONS = new Set([".txt"]);
 * @example
 * await prepareAttachmentPart({ type: "text", source: "./notes.txt" });
 * // → { type: "text", text: "<file contents>" }
+*
+* **Trust boundary (S1).** Attachment references are often user-controlled,
+* so server-side I/O is policy-gated by `policy` ({@link AttachmentPolicy}):
+* remote text fetches are default-deny and, when enabled, run through the
+* shared `OutboundPolicy` (scheme/host/private-IP/max-bytes/timeout); local
+* reads honor an `allowedRoots` sandbox; bare-string local paths warn
+* (staged deprecation). URL *image* attachments are passed to the provider
+* untouched (never fetched here).
 */
-async function prepareAttachmentPart(attachment) {
-	if (resolveKind(attachment) === "text") return prepareTextPart(attachment);
-	return prepareImagePart(attachment);
+async function prepareAttachmentPart(attachment, policy) {
+	const kind = resolveKind(attachment);
+	const bareString = typeof attachment === "string";
+	if (kind === "text") return prepareTextPart(attachment, policy, bareString);
+	if (kind === "image") return prepareImagePart(attachment, policy, bareString);
+	return prepareBinaryPart(attachment, kind, policy, bareString);
 }
 /**
 * Decide whether the attachment is text or image. Tagged forms win
@@ -56,14 +77,50 @@ function resolveKind(attachment) {
 	const extension = path ? extname(stripQuery(path)).toLowerCase() : "";
 	if (IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension]) return "image";
 	if (TEXT_EXTENSIONS.has(extension)) return "text";
-	throw new InvalidRequestError("Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt)");
+	if (PDF_EXTENSIONS.has(extension)) return "pdf";
+	if (AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extension]) return "audio";
+	throw new InvalidRequestError("Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text' | 'pdf' | 'audio', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt, .pdf, .mp3, .wav, .m4a, .ogg, .weba)");
+}
+/**
+* Produce a `pdf` / `audio` ContentPart (A2). URLs pass through; local
+* paths are read and base64-encoded with a media type inferred from the
+* kind (`application/pdf`) or extension (audio); inline base64 passes
+* through. Same `AttachmentPolicy` gating as image/text reads.
+*/
+async function prepareBinaryPart(attachment, kind, policy, bareString) {
+	const resolved = resolveAttachment(attachment);
+	if (resolved.type === "url") return {
+		type: kind,
+		source: { url: resolved.value }
+	};
+	if (resolved.type === "base64") return {
+		type: kind,
+		source: {
+			base64: resolved.value,
+			mediaType: resolved.mediaType
+		}
+	};
+	const mediaType = kind === "pdf" ? "application/pdf" : inferAudioMediaType(resolved.value);
+	if (!mediaType) throw new InvalidRequestError(`Cannot infer media type for ${kind} path "${resolved.value}" — use a recognized extension or pass \`{ type: '${kind}', source: { base64, mediaType } }\``, { context: { path: resolved.value } });
+	enforceLocalPathPolicy(resolved.value, bareString, policy);
+	return {
+		type: kind,
+		source: {
+			base64: (await readFile(resolved.value)).toString("base64"),
+			mediaType
+		}
+	};
+}
+/** Infer an audio media type from a path's extension. */
+function inferAudioMediaType(path) {
+	return AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extname(stripQuery(path)).toLowerCase()];
 }
 /**
 * Produce an `image` ContentPart. URLs pass through; paths are
 * read from disk and base64-encoded with an inferred media type.
 * Inline base64 attachments pass through unchanged.
 */
-async function prepareImagePart(attachment) {
+async function prepareImagePart(attachment, policy, bareString) {
 	const inferredMediaType = isTaggedAttachment(attachment) ? void 0 : inferImageMediaType(attachment);
 	const resolved = resolveAttachment(attachment);
 	if (resolved.type === "url") return {
@@ -79,6 +136,7 @@ async function prepareImagePart(attachment) {
 	};
 	const mediaType = inferredMediaType ?? inferImageMediaType(resolved.value);
 	if (!mediaType) throw new InvalidRequestError(`Cannot infer media type for path "${resolved.value}" — use a recognized image extension or pass \`{ type: 'image', source: { base64, mediaType } }\``, { context: { path: resolved.value } });
+	enforceLocalPathPolicy(resolved.value, bareString, policy);
 	return {
 		type: "image",
 		source: {
@@ -93,28 +151,62 @@ async function prepareImagePart(attachment) {
 * result joins the conversation as an additional text part the model
 * sees before responding.
 */
-async function prepareTextPart(attachment) {
+async function prepareTextPart(attachment, policy, bareString) {
 	const resolved = resolveAttachment(attachment);
 	if (resolved.type === "url") {
-		const response = await fetch(resolved.value);
-		if (!response.ok) throw new InvalidRequestError(`Failed to fetch text attachment "${resolved.value}" — status ${response.status}`, { context: {
+		if (!policy?.allowRemoteFetch) throw new OutboundPolicyError(`remote text attachment fetch is disabled by default — set \`attachmentPolicy.allowRemoteFetch: true\` (with an \`outbound\` policy) to fetch "${resolved.value}"`, { context: { url: resolved.value } });
+		const result = await fetchTextWithPolicy(resolved.value, policy.outbound ?? {});
+		if (!result.ok) throw new InvalidRequestError(`Failed to fetch text attachment "${resolved.value}" — status ${result.status}`, { context: {
 			url: resolved.value,
-			status: response.status
+			status: result.status
 		} });
 		return {
 			type: "text",
-			text: await response.text()
+			text: result.text
 		};
 	}
 	if (resolved.type === "base64") return {
 		type: "text",
 		text: Buffer.from(resolved.value, "base64").toString("utf8")
 	};
+	enforceLocalPathPolicy(resolved.value, bareString, policy);
 	return {
 		type: "text",
 		text: await readFile(resolved.value, "utf8")
 	};
 }
+/** Process-lifetime flag so the bare-string deprecation warns at most once. */
+let warnedBareLocalPath = false;
+/**
+* Enforce the local-file half of {@link AttachmentPolicy} (S1):
+*
+* - **Bare-string local paths** are staged for deprecation. With
+*   `allowBareLocalPaths: false` they hard-deny now; otherwise they warn
+*   once (outside tests) — the typed `StorageFile.absolutePath` route is
+*   the supported way to read a local file.
+* - **`allowedRoots` sandbox** — when set, the resolved path must live
+*   inside one of the roots, else the read is refused.
+*/
+function enforceLocalPathPolicy(path, bareString, policy) {
+	if (bareString) {
+		if (policy?.allowBareLocalPaths === false) throw new OutboundPolicyError(`local file attachment via a bare string path ("${path}") is disabled — pass a typed \`{ type, source: { absolutePath } }\` StorageFile, or set \`attachmentPolicy.allowBareLocalPaths: true\``, { context: { path } });
+		if (!warnedBareLocalPath && !process.env.VITEST && process.env.NODE_ENV !== "test") {
+			warnedBareLocalPath = true;
+			console.warn("[warlock-ai] reading a local file attachment from a bare string path is deprecated and will be denied by default in a future minor. Pass a typed `{ type, source: { absolutePath } }` StorageFile and confine reads with `attachmentPolicy.allowedRoots`.");
+		}
+	}
+	const roots = policy?.allowedRoots;
+	if (roots && roots.length > 0) {
+		const target = resolve(path);
+		if (!roots.some((root) => {
+			const rel = relative(resolve(root), target);
+			return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+		})) throw new OutboundPolicyError(`local file attachment "${path}" is outside the allowed roots`, { context: {
+			path,
+			allowedRoots: roots
+		} });
+	}
+}
 function isTaggedAttachment(attachment) {
 	return typeof attachment === "object" && attachment !== null && "type" in attachment;
 }

package/esm/utils/prepare-attachment-part.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"prepare-attachment-part.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/prepare-attachment-part.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { extname } from \"node:path\";\nimport type { Attachment } from \"../contracts/attachment.type\";\nimport type { ContentPart } from \"../contracts/content-part.type\";\nimport { InvalidRequestError } from \"../errors\";\nimport { resolveAttachment } from \"./resolve-attachment\";\n\nconst IMAGE_EXTENSIONS_TO_MEDIA_TYPE: Record<string, string> = {\n  \".png\": \"image/png\",\n  \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\",\n  \".webp\": \"image/webp\",\n  \".gif\": \"image/gif\",\n};\n\nconst TEXT_EXTENSIONS = new Set([\".txt\"]);\n\ntype AttachmentKind = \"image\" | \"text\";\n\n/**\n * Convert a user-supplied `Attachment` into a provider-ready\n * `ContentPart` the model adapter can consume without doing any I/O of\n * its own.\n *\n * Kind resolution:\n * - Tagged `{ type: \"image\", source }` / `{ type: \"text\", source }`\n *   trusts the caller's intent.\n * - Shorthand (raw string / `StorageFileShape`) infers from the file\n *   extension. Image extensions (`.png`/`.jpg`/`.jpeg`/`.webp`/`.gif`)\n *   map to `\"image\"`. `.txt` maps to `\"text\"`. Anything else throws\n *   `InvalidRequestError` — silent inference on ambiguous inputs\n *   causes silent bugs.\n *\n * Local paths are read from disk; images are base64-encoded inline,\n * text files are read as UTF-8 strings and returned as a `text`\n * `ContentPart`. Remote URLs for image attachments are passed through\n * unchanged; remote URLs for text attachments are fetched so the\n * adapter never needs network access.\n *\n * @example\n * await prepareAttachmentPart(\"./photo.png\");\n * // → { type: \"image\", source: { base64: \"...\", mediaType: \"image/png\" } }\n *\n * @example\n * await prepareAttachmentPart({ type: \"text\", source: \"./notes.txt\" });\n * // → { type: \"text\", text: \"<file contents>\" }\n */\nexport async function prepareAttachmentPart(\n  attachment: Attachment,\n): Promise<ContentPart> {\n  const kind = resolveKind(attachment);\n\n  if (kind === \"text\") {\n    return prepareTextPart(attachment);\n  }\n\n  return prepareImagePart(attachment);\n}\n\n/**\n * Decide whether the attachment is text or image. Tagged forms win\n * immediately; for shorthand we inspect the extension. Throws if the\n * shorthand doesn't look like anything we recognize.\n */\nfunction resolveKind(attachment: Attachment): AttachmentKind {\n  if (isTaggedAttachment(attachment)) {\n    return attachment.type;\n  }\n\n  const path = extractPath(attachment);\n  const extension = path ? extname(stripQuery(path)).toLowerCase() : \"\";\n\n  if (IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension]) {\n    return \"image\";\n  }\n\n  if (TEXT_EXTENSIONS.has(extension)) {\n    return \"text\";\n  }\n\n  throw new InvalidRequestError(\n    \"Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt)\",\n  );\n}\n\n/**\n * Produce an `image` ContentPart. URLs pass through; paths are\n * read from disk and base64-encoded with an inferred media type.\n * Inline base64 attachments pass through unchanged.\n */\nasync function prepareImagePart(attachment: Attachment): Promise<ContentPart> {\n  const inferredMediaType = isTaggedAttachment(attachment)\n    ? undefined\n    : inferImageMediaType(attachment);\n\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    return { type: \"image\", source: { url: resolved.value } };\n  }\n\n  if (resolved.type === \"base64\") {\n    return {\n      type: \"image\",\n      source: { base64: resolved.value, mediaType: resolved.mediaType },\n    };\n  }\n\n  const mediaType = inferredMediaType ?? inferImageMediaType(resolved.value);\n\n  if (!mediaType) {\n    throw new InvalidRequestError(\n      `Cannot infer media type for path \"${resolved.value}\" — use a recognized image extension or pass ` +\n        \"`{ type: 'image', source: { base64, mediaType } }`\",\n      { context: { path: resolved.value } },\n    );\n  }\n\n  const bytes = await readFile(resolved.value);\n\n  return {\n    type: \"image\",\n    source: { base64: bytes.toString(\"base64\"), mediaType },\n  };\n}\n\n/**\n * Produce a `text` ContentPart. URLs are fetched as UTF-8, paths are\n * read from disk as UTF-8, inline base64 is decoded to UTF-8. The\n * result joins the conversation as an additional text part the model\n * sees before responding.\n */\nasync function prepareTextPart(attachment: Attachment): Promise<ContentPart> {\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    const response = await fetch(resolved.value);\n\n    if (!response.ok) {\n      throw new InvalidRequestError(\n        `Failed to fetch text attachment \"${resolved.value}\" — status ${response.status}`,\n        { context: { url: resolved.value, status: response.status } },\n      );\n    }\n\n    return { type: \"text\", text: await response.text() };\n  }\n\n  if (resolved.type === \"base64\") {\n    const decoded = Buffer.from(resolved.value, \"base64\").toString(\"utf8\");\n\n    return { type: \"text\", text: decoded };\n  }\n\n  const bytes = await readFile(resolved.value, \"utf8\");\n\n  return { type: \"text\", text: bytes };\n}\n\nfunction isTaggedAttachment(\n  attachment: Attachment,\n): attachment is Extract<Attachment, { type: string }> {\n  return (\n    typeof attachment === \"object\" &&\n    attachment !== null &&\n    \"type\" in attachment\n  );\n}\n\nfunction inferImageMediaType(input: unknown): string | undefined {\n  const path = extractPath(input);\n\n  if (!path) {\n    return undefined;\n  }\n\n  const extension = extname(stripQuery(path)).toLowerCase();\n\n  return IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension];\n}\n\nfunction extractPath(input: unknown): string | undefined {\n  if (typeof input === \"string\") {\n    return input;\n  }\n\n  if (typeof input === \"object\" && input !== null) {\n    const storage = input as { url?: string; absolutePath?: string };\n    return storage.url ?? storage.absolutePath;\n  }\n\n  return undefined;\n}\n\nfunction stripQuery(path: string): string {\n  const queryIndex = path.indexOf(\"?\");\n\n  return queryIndex === -1 ? path : path.slice(0, queryIndex);\n}\n"],"mappings":";;;;;;;AAOA,MAAM,iCAAyD;CAC7D,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;AACV;AAEA,MAAM,kBAAkB,IAAI,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCxC,eAAsB,sBACpB,YACsB;CAGtB,IAFa,YAAY,UAElB,MAAM,QACX,OAAO,gBAAgB,UAAU;CAGnC,OAAO,iBAAiB,UAAU;AACpC;;;;;;AAOA,SAAS,YAAY,YAAwC;CAC3D,IAAI,mBAAmB,UAAU,GAC/B,OAAO,WAAW;CAGpB,MAAM,OAAO,YAAY,UAAU;CACnC,MAAM,YAAY,OAAO,QAAQ,WAAW,IAAI,CAAC,CAAC,CAAC,YAAY,IAAI;CAEnE,IAAI,+BAA+B,YACjC,OAAO;CAGT,IAAI,gBAAgB,IAAI,SAAS,GAC/B,OAAO;CAGT,MAAM,IAAI,oBACR,2KACF;AACF;;;;;;AAOA,eAAe,iBAAiB,YAA8C;CAC5E,MAAM,oBAAoB,mBAAmB,UAAU,IACnD,SACA,oBAAoB,UAAU;CAElC,MAAM,WAAW,kBAAkB,UAAU;CAE7C,IAAI,SAAS,SAAS,OACpB,OAAO;EAAE,MAAM;EAAS,QAAQ,EAAE,KAAK,SAAS,MAAM;CAAE;CAG1D,IAAI,SAAS,SAAS,UACpB,OAAO;EACL,MAAM;EACN,QAAQ;GAAE,QAAQ,SAAS;GAAO,WAAW,SAAS;EAAU;CAClE;CAGF,MAAM,YAAY,qBAAqB,oBAAoB,SAAS,KAAK;CAEzE,IAAI,CAAC,WACH,MAAM,IAAI,oBACR,qCAAqC,SAAS,MAAM,oGAEpD,EAAE,SAAS,EAAE,MAAM,SAAS,MAAM,EAAE,CACtC;CAKF,OAAO;EACL,MAAM;EACN,QAAQ;GAAE,SAAQ,MAJA,SAAS,SAAS,KAAK,EAIlB,CAAC,SAAS,QAAQ;GAAG;EAAU;CACxD;AACF;;;;;;;AAQA,eAAe,gBAAgB,YAA8C;CAC3E,MAAM,WAAW,kBAAkB,UAAU;CAE7C,IAAI,SAAS,SAAS,OAAO;EAC3B,MAAM,WAAW,MAAM,MAAM,SAAS,KAAK;EAE3C,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,oBACR,oCAAoC,SAAS,MAAM,aAAa,SAAS,UACzE,EAAE,SAAS;GAAE,KAAK,SAAS;GAAO,QAAQ,SAAS;EAAO,EAAE,CAC9D;EAGF,OAAO;GAAE,MAAM;GAAQ,MAAM,MAAM,SAAS,KAAK;EAAE;CACrD;CAEA,IAAI,SAAS,SAAS,UAGpB,OAAO;EAAE,MAAM;EAAQ,MAFP,OAAO,KAAK,SAAS,OAAO,QAAQ,CAAC,CAAC,SAAS,MAE5B;CAAE;CAKvC,OAAO;EAAE,MAAM;EAAQ,MAAM,MAFT,SAAS,SAAS,OAAO,MAAM;CAEhB;AACrC;AAEA,SAAS,mBACP,YACqD;CACrD,OACE,OAAO,eAAe,YACtB,eAAe,QACf,UAAU;AAEd;AAEA,SAAS,oBAAoB,OAAoC;CAC/D,MAAM,OAAO,YAAY,KAAK;CAE9B,IAAI,CAAC,MACH;CAKF,OAAO,+BAFW,QAAQ,WAAW,IAAI,CAAC,CAAC,CAAC,YAEE;AAChD;AAEA,SAAS,YAAY,OAAoC;CACvD,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM;EAC/C,MAAM,UAAU;EAChB,OAAO,QAAQ,OAAO,QAAQ;CAChC;AAGF;AAEA,SAAS,WAAW,MAAsB;CACxC,MAAM,aAAa,KAAK,QAAQ,GAAG;CAEnC,OAAO,eAAe,KAAK,OAAO,KAAK,MAAM,GAAG,UAAU;AAC5D"}
+{"version":3,"file":"prepare-attachment-part.mjs","names":["resolvePath"],"sources":["../../../../../../../@warlock.js/ai/src/utils/prepare-attachment-part.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { extname, isAbsolute, relative, resolve as resolvePath } from \"node:path\";\nimport type { AttachmentPolicy } from \"../contracts/attachment-policy.type\";\nimport type { Attachment } from \"../contracts/attachment.type\";\nimport type { ContentPart } from \"../contracts/content-part.type\";\nimport { InvalidRequestError, OutboundPolicyError } from \"../errors\";\nimport { fetchTextWithPolicy } from \"../security/outbound-policy\";\nimport { resolveAttachment } from \"./resolve-attachment\";\n\nconst IMAGE_EXTENSIONS_TO_MEDIA_TYPE: Record<string, string> = {\n  \".png\": \"image/png\",\n  \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\",\n  \".webp\": \"image/webp\",\n  \".gif\": \"image/gif\",\n};\n\nconst TEXT_EXTENSIONS = new Set([\".txt\"]);\n\nconst AUDIO_EXTENSIONS_TO_MEDIA_TYPE: Record<string, string> = {\n  \".mp3\": \"audio/mpeg\",\n  \".wav\": \"audio/wav\",\n  \".m4a\": \"audio/mp4\",\n  \".ogg\": \"audio/ogg\",\n  \".weba\": \"audio/webm\",\n};\n\nconst PDF_EXTENSIONS = new Set([\".pdf\"]);\n\ntype AttachmentKind = \"image\" | \"text\" | \"pdf\" | \"audio\";\n\n/**\n * Convert a user-supplied `Attachment` into a provider-ready\n * `ContentPart` the model adapter can consume without doing any I/O of\n * its own.\n *\n * Kind resolution:\n * - Tagged `{ type: \"image\", source }` / `{ type: \"text\", source }`\n *   trusts the caller's intent.\n * - Shorthand (raw string / `StorageFileShape`) infers from the file\n *   extension. Image extensions (`.png`/`.jpg`/`.jpeg`/`.webp`/`.gif`)\n *   map to `\"image\"`. `.txt` maps to `\"text\"`. Anything else throws\n *   `InvalidRequestError` — silent inference on ambiguous inputs\n *   causes silent bugs.\n *\n * Local paths are read from disk; images are base64-encoded inline,\n * text files are read as UTF-8 strings and returned as a `text`\n * `ContentPart`. Remote URLs for image attachments are passed through\n * unchanged; remote URLs for text attachments are fetched so the\n * adapter never needs network access.\n *\n * @example\n * await prepareAttachmentPart(\"./photo.png\");\n * // → { type: \"image\", source: { base64: \"...\", mediaType: \"image/png\" } }\n *\n * @example\n * await prepareAttachmentPart({ type: \"text\", source: \"./notes.txt\" });\n * // → { type: \"text\", text: \"<file contents>\" }\n *\n * **Trust boundary (S1).** Attachment references are often user-controlled,\n * so server-side I/O is policy-gated by `policy` ({@link AttachmentPolicy}):\n * remote text fetches are default-deny and, when enabled, run through the\n * shared `OutboundPolicy` (scheme/host/private-IP/max-bytes/timeout); local\n * reads honor an `allowedRoots` sandbox; bare-string local paths warn\n * (staged deprecation). URL *image* attachments are passed to the provider\n * untouched (never fetched here).\n */\nexport async function prepareAttachmentPart(\n  attachment: Attachment,\n  policy?: AttachmentPolicy,\n): Promise<ContentPart> {\n  const kind = resolveKind(attachment);\n  const bareString = typeof attachment === \"string\";\n\n  if (kind === \"text\") {\n    return prepareTextPart(attachment, policy, bareString);\n  }\n\n  if (kind === \"image\") {\n    return prepareImagePart(attachment, policy, bareString);\n  }\n\n  return prepareBinaryPart(attachment, kind, policy, bareString);\n}\n\n/**\n * Decide whether the attachment is text or image. Tagged forms win\n * immediately; for shorthand we inspect the extension. Throws if the\n * shorthand doesn't look like anything we recognize.\n */\nfunction resolveKind(attachment: Attachment): AttachmentKind {\n  if (isTaggedAttachment(attachment)) {\n    return attachment.type;\n  }\n\n  const path = extractPath(attachment);\n  const extension = path ? extname(stripQuery(path)).toLowerCase() : \"\";\n\n  if (IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension]) {\n    return \"image\";\n  }\n\n  if (TEXT_EXTENSIONS.has(extension)) {\n    return \"text\";\n  }\n\n  if (PDF_EXTENSIONS.has(extension)) {\n    return \"pdf\";\n  }\n\n  if (AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extension]) {\n    return \"audio\";\n  }\n\n  throw new InvalidRequestError(\n    \"Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text' | 'pdf' | 'audio', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt, .pdf, .mp3, .wav, .m4a, .ogg, .weba)\",\n  );\n}\n\n/**\n * Produce a `pdf` / `audio` ContentPart (A2). URLs pass through; local\n * paths are read and base64-encoded with a media type inferred from the\n * kind (`application/pdf`) or extension (audio); inline base64 passes\n * through. Same `AttachmentPolicy` gating as image/text reads.\n */\nasync function prepareBinaryPart(\n  attachment: Attachment,\n  kind: \"pdf\" | \"audio\",\n  policy: AttachmentPolicy | undefined,\n  bareString: boolean,\n): Promise<ContentPart> {\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    return { type: kind, source: { url: resolved.value } };\n  }\n\n  if (resolved.type === \"base64\") {\n    return { type: kind, source: { base64: resolved.value, mediaType: resolved.mediaType } };\n  }\n\n  const mediaType =\n    kind === \"pdf\" ? \"application/pdf\" : inferAudioMediaType(resolved.value);\n\n  if (!mediaType) {\n    throw new InvalidRequestError(\n      `Cannot infer media type for ${kind} path \"${resolved.value}\" — use a recognized extension or pass ` +\n        `\\`{ type: '${kind}', source: { base64, mediaType } }\\``,\n      { context: { path: resolved.value } },\n    );\n  }\n\n  enforceLocalPathPolicy(resolved.value, bareString, policy);\n  const bytes = await readFile(resolved.value);\n\n  return { type: kind, source: { base64: bytes.toString(\"base64\"), mediaType } };\n}\n\n/** Infer an audio media type from a path's extension. */\nfunction inferAudioMediaType(path: string): string | undefined {\n  return AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extname(stripQuery(path)).toLowerCase()];\n}\n\n/**\n * Produce an `image` ContentPart. URLs pass through; paths are\n * read from disk and base64-encoded with an inferred media type.\n * Inline base64 attachments pass through unchanged.\n */\nasync function prepareImagePart(\n  attachment: Attachment,\n  policy: AttachmentPolicy | undefined,\n  bareString: boolean,\n): Promise<ContentPart> {\n  const inferredMediaType = isTaggedAttachment(attachment)\n    ? undefined\n    : inferImageMediaType(attachment);\n\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    // URL images are handed to the provider as a URL — the provider\n    // fetches them, not us — so there's no server-side SSRF surface here.\n    return { type: \"image\", source: { url: resolved.value } };\n  }\n\n  if (resolved.type === \"base64\") {\n    return {\n      type: \"image\",\n      source: { base64: resolved.value, mediaType: resolved.mediaType },\n    };\n  }\n\n  const mediaType = inferredMediaType ?? inferImageMediaType(resolved.value);\n\n  if (!mediaType) {\n    throw new InvalidRequestError(\n      `Cannot infer media type for path \"${resolved.value}\" — use a recognized image extension or pass ` +\n        \"`{ type: 'image', source: { base64, mediaType } }`\",\n      { context: { path: resolved.value } },\n    );\n  }\n\n  enforceLocalPathPolicy(resolved.value, bareString, policy);\n  const bytes = await readFile(resolved.value);\n\n  return {\n    type: \"image\",\n    source: { base64: bytes.toString(\"base64\"), mediaType },\n  };\n}\n\n/**\n * Produce a `text` ContentPart. URLs are fetched as UTF-8, paths are\n * read from disk as UTF-8, inline base64 is decoded to UTF-8. The\n * result joins the conversation as an additional text part the model\n * sees before responding.\n */\nasync function prepareTextPart(\n  attachment: Attachment,\n  policy: AttachmentPolicy | undefined,\n  bareString: boolean,\n): Promise<ContentPart> {\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    // Default-deny: a remote text attachment is a server-side fetch of\n    // user-controlled input — refuse unless the app explicitly opted in,\n    // then run it through the shared OutboundPolicy (scheme/host/private-\n    // IP/max-bytes/timeout).\n    if (!policy?.allowRemoteFetch) {\n      throw new OutboundPolicyError(\n        `remote text attachment fetch is disabled by default — set \\`attachmentPolicy.allowRemoteFetch: true\\` (with an \\`outbound\\` policy) to fetch \"${resolved.value}\"`,\n        { context: { url: resolved.value } },\n      );\n    }\n\n    const result = await fetchTextWithPolicy(resolved.value, policy.outbound ?? {});\n\n    if (!result.ok) {\n      throw new InvalidRequestError(\n        `Failed to fetch text attachment \"${resolved.value}\" — status ${result.status}`,\n        { context: { url: resolved.value, status: result.status } },\n      );\n    }\n\n    return { type: \"text\", text: result.text };\n  }\n\n  if (resolved.type === \"base64\") {\n    const decoded = Buffer.from(resolved.value, \"base64\").toString(\"utf8\");\n\n    return { type: \"text\", text: decoded };\n  }\n\n  enforceLocalPathPolicy(resolved.value, bareString, policy);\n  const bytes = await readFile(resolved.value, \"utf8\");\n\n  return { type: \"text\", text: bytes };\n}\n\n/** Process-lifetime flag so the bare-string deprecation warns at most once. */\nlet warnedBareLocalPath = false;\n\n/**\n * Enforce the local-file half of {@link AttachmentPolicy} (S1):\n *\n * - **Bare-string local paths** are staged for deprecation. With\n *   `allowBareLocalPaths: false` they hard-deny now; otherwise they warn\n *   once (outside tests) — the typed `StorageFile.absolutePath` route is\n *   the supported way to read a local file.\n * - **`allowedRoots` sandbox** — when set, the resolved path must live\n *   inside one of the roots, else the read is refused.\n */\nfunction enforceLocalPathPolicy(\n  path: string,\n  bareString: boolean,\n  policy: AttachmentPolicy | undefined,\n): void {\n  if (bareString) {\n    if (policy?.allowBareLocalPaths === false) {\n      throw new OutboundPolicyError(\n        `local file attachment via a bare string path (\"${path}\") is disabled — pass a typed \\`{ type, source: { absolutePath } }\\` StorageFile, or set \\`attachmentPolicy.allowBareLocalPaths: true\\``,\n        { context: { path } },\n      );\n    }\n\n    if (!warnedBareLocalPath && !process.env.VITEST && process.env.NODE_ENV !== \"test\") {\n      warnedBareLocalPath = true;\n      console.warn(\n        \"[warlock-ai] reading a local file attachment from a bare string path is deprecated and will be denied by default in a future minor. \" +\n          \"Pass a typed `{ type, source: { absolutePath } }` StorageFile and confine reads with `attachmentPolicy.allowedRoots`.\",\n      );\n    }\n  }\n\n  const roots = policy?.allowedRoots;\n  if (roots && roots.length > 0) {\n    const target = resolvePath(path);\n    const inside = roots.some(root => {\n      const rel = relative(resolvePath(root), target);\n      return rel === \"\" || (!rel.startsWith(\"..\") && !isAbsolute(rel));\n    });\n\n    if (!inside) {\n      throw new OutboundPolicyError(\n        `local file attachment \"${path}\" is outside the allowed roots`,\n        { context: { path, allowedRoots: roots } },\n      );\n    }\n  }\n}\n\nfunction isTaggedAttachment(\n  attachment: Attachment,\n): attachment is Extract<Attachment, { type: string }> {\n  return (\n    typeof attachment === \"object\" &&\n    attachment !== null &&\n    \"type\" in attachment\n  );\n}\n\nfunction inferImageMediaType(input: unknown): string | undefined {\n  const path = extractPath(input);\n\n  if (!path) {\n    return undefined;\n  }\n\n  const extension = extname(stripQuery(path)).toLowerCase();\n\n  return IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension];\n}\n\nfunction extractPath(input: unknown): string | undefined {\n  if (typeof input === \"string\") {\n    return input;\n  }\n\n  if (typeof input === \"object\" && input !== null) {\n    const storage = input as { url?: string; absolutePath?: string };\n    return storage.url ?? storage.absolutePath;\n  }\n\n  return undefined;\n}\n\nfunction stripQuery(path: string): string {\n  const queryIndex = path.indexOf(\"?\");\n\n  return queryIndex === -1 ? path : path.slice(0, queryIndex);\n}\n"],"mappings":"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"}

package/esm/utils/resolve-attachment.d.mts

@@ -8,9 +8,10 @@ import { Attachment, ResolvedAttachment } from "../contracts/attachment.type.mjs
  *
  * Resolution rules:
  * - `{ base64, mediaType }` → `{ type: "base64", value, mediaType }`.
- * - `StorageFileShape` (`{ url?, absolutePath? }`) → URL wins over
- *   absolute path. URL becomes `{ type: "url" }`; absolute path
- *   becomes `{ type: "path" }`.
+ * - `StorageFileShape` (`{ url?, absolutePath? }`) → `absolutePath` wins
+ *   over `url` when both are present (prefer the local file over an extra
+ *   remote hop). Absolute path becomes `{ type: "path" }`; url becomes
+ *   `{ type: "url" }`.
  * - String starting with `http://` / `https://` → `{ type: "url" }`.
  * - Any other string → `{ type: "path" }`.
  * - Tagged `{ type: "image" | "text", source }` → recurses into `source`.

package/esm/utils/resolve-attachment.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-attachment.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/resolve-attachment.ts"],"mappings":";;;;;AAmCA;;;;;;;;AAA6E;;;;;;;;;;;;;;;;iBAA7D,iBAAA,CAAkB,UAAA,EAAY,UAAA,GAAa,kBAAkB"}
+{"version":3,"file":"resolve-attachment.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/resolve-attachment.ts"],"mappings":";;;;;AAoCA;;;;;;;;AAA6E;;;;;;;;;;;;;;;;;iBAA7D,iBAAA,CAAkB,UAAA,EAAY,UAAA,GAAa,kBAAkB"}

package/esm/utils/resolve-attachment.mjs

@@ -10,9 +10,10 @@ const REMOTE_URL_PATTERN = /^https?:\/\//i;
 *
 * Resolution rules:
 * - `{ base64, mediaType }` → `{ type: "base64", value, mediaType }`.
-* - `StorageFileShape` (`{ url?, absolutePath? }`) → URL wins over
-*   absolute path. URL becomes `{ type: "url" }`; absolute path
-*   becomes `{ type: "path" }`.
+* - `StorageFileShape` (`{ url?, absolutePath? }`) → `absolutePath` wins
+*   over `url` when both are present (prefer the local file over an extra
+*   remote hop). Absolute path becomes `{ type: "path" }`; url becomes
+*   `{ type: "url" }`.
 * - String starting with `http://` / `https://` → `{ type: "url" }`.
 * - Any other string → `{ type: "path" }`.
 * - Tagged `{ type: "image" | "text", source }` → recurses into `source`.

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"}