@warlock.js/core 4.4.0 → 4.6.0

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

@@ -0,0 +1,232 @@
+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 { extname, isAbsolute, relative, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+
+//#region ../@warlock.js/ai/src/utils/prepare-attachment-part.ts
+const IMAGE_EXTENSIONS_TO_MEDIA_TYPE = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".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
+* its own.
+*
+* Kind resolution:
+* - Tagged `{ type: "image", source }` / `{ type: "text", source }`
+*   trusts the caller's intent.
+* - Shorthand (raw string / `StorageFileShape`) infers from the file
+*   extension. Image extensions (`.png`/`.jpg`/`.jpeg`/`.webp`/`.gif`)
+*   map to `"image"`. `.txt` maps to `"text"`. Anything else throws
+*   `InvalidRequestError` — silent inference on ambiguous inputs
+*   causes silent bugs.
+*
+* Local paths are read from disk; images are base64-encoded inline,
+* text files are read as UTF-8 strings and returned as a `text`
+* `ContentPart`. Remote URLs for image attachments are passed through
+* unchanged; remote URLs for text attachments are fetched so the
+* adapter never needs network access.
+*
+* @example
+* await prepareAttachmentPart("./photo.png");
+* // → { type: "image", source: { base64: "...", mediaType: "image/png" } }
+*
+* @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, 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
+* immediately; for shorthand we inspect the extension. Throws if the
+* shorthand doesn't look like anything we recognize.
+*/
+function resolveKind(attachment) {
+	if (isTaggedAttachment(attachment)) return attachment.type;
+	const path = extractPath(attachment);
+	const extension = path ? extname(stripQuery(path)).toLowerCase() : "";
+	if (IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension]) return "image";
+	if (TEXT_EXTENSIONS.has(extension)) return "text";
+	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, policy, bareString) {
+	const inferredMediaType = isTaggedAttachment(attachment) ? void 0 : inferImageMediaType(attachment);
+	const resolved = resolveAttachment(attachment);
+	if (resolved.type === "url") return {
+		type: "image",
+		source: { url: resolved.value }
+	};
+	if (resolved.type === "base64") return {
+		type: "image",
+		source: {
+			base64: resolved.value,
+			mediaType: resolved.mediaType
+		}
+	};
+	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: {
+			base64: (await readFile(resolved.value)).toString("base64"),
+			mediaType
+		}
+	};
+}
+/**
+* Produce a `text` ContentPart. URLs are fetched as UTF-8, paths are
+* read from disk as UTF-8, inline base64 is decoded to UTF-8. The
+* result joins the conversation as an additional text part the model
+* sees before responding.
+*/
+async function prepareTextPart(attachment, policy, bareString) {
+	const resolved = resolveAttachment(attachment);
+	if (resolved.type === "url") {
+		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: result.status
+		} });
+		return {
+			type: "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;
+}
+function inferImageMediaType(input) {
+	const path = extractPath(input);
+	if (!path) return;
+	return IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extname(stripQuery(path)).toLowerCase()];
+}
+function extractPath(input) {
+	if (typeof input === "string") return input;
+	if (typeof input === "object" && input !== null) {
+		const storage = input;
+		return storage.url ?? storage.absolutePath;
+	}
+}
+function stripQuery(path) {
+	const queryIndex = path.indexOf("?");
+	return queryIndex === -1 ? path : path.slice(0, queryIndex);
+}
+
+//#endregion
+export { prepareAttachmentPart };
+//# sourceMappingURL=prepare-attachment-part.mjs.map

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

@@ -0,0 +1 @@
+{"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/ai/src/utils/resolve-attachment.mjs

@@ -0,0 +1,74 @@
+import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import "../errors/index.mjs";
+
+//#region ../@warlock.js/ai/src/utils/resolve-attachment.ts
+const REMOTE_URL_PATTERN = /^https?:\/\//i;
+/**
+* Normalize a user-supplied `Attachment` (or bare `AttachmentSource`)
+* into a `ResolvedAttachment` the agent can hand to file-reading code
+* without re-discriminating the input variant.
+*
+* Resolution rules:
+* - `{ base64, mediaType }` → `{ type: "base64", value, mediaType }`.
+* - `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`.
+*
+* Throws `InvalidRequestError` on obviously invalid input (empty
+* string, storage object with neither url nor absolutePath, missing
+* source field).
+*
+* @example
+* resolveAttachment("https://cdn.example.com/doc.pdf");
+* // → { type: "url", value: "https://cdn.example.com/doc.pdf" }
+*
+* @example
+* resolveAttachment({ type: "image", source: "/tmp/x.png" });
+* // → { type: "path", value: "/tmp/x.png" }
+*/
+function resolveAttachment(attachment) {
+	if (typeof attachment === "object" && attachment !== null && "type" in attachment) return resolveSource(attachment.source);
+	return resolveSource(attachment);
+}
+function resolveSource(source) {
+	if (typeof source === "string") {
+		if (!source) throw new InvalidRequestError("Cannot resolve empty attachment string");
+		if (REMOTE_URL_PATTERN.test(source)) return {
+			type: "url",
+			value: source
+		};
+		return {
+			type: "path",
+			value: source
+		};
+	}
+	if ("url" in source || "absolutePath" in source) {
+		const storage = source;
+		if (storage.absolutePath) return {
+			type: "path",
+			value: storage.absolutePath
+		};
+		if (storage.url) return {
+			type: "url",
+			value: storage.url
+		};
+		throw new InvalidRequestError("Storage attachment has neither url nor absolutePath");
+	}
+	if ("base64" in source) {
+		if (!source.base64 || !source.mediaType) throw new InvalidRequestError("Inline attachment requires both `base64` and `mediaType`");
+		return {
+			type: "base64",
+			value: source.base64,
+			mediaType: source.mediaType
+		};
+	}
+	throw new InvalidRequestError("Unrecognized attachment source — expected a string path/URL, a StorageFile, or `{ base64, mediaType }`");
+}
+
+//#endregion
+export { resolveAttachment };
+//# sourceMappingURL=resolve-attachment.mjs.map

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

@@ -0,0 +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? }`) → `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/ai/src/utils/run-context.mjs

@@ -0,0 +1,89 @@
+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));
+}
+/**
+* `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, isNestedRun, withRunFrame, withoutRunFrame };
+//# sourceMappingURL=run-context.mjs.map

package/esm/ai/src/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;;;;;;;;AAmBA,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/ai/src/utils/safe-json-parse.mjs

@@ -0,0 +1,22 @@
+//#region ../@warlock.js/ai/src/utils/safe-json-parse.ts
+/**
+* Parse a JSON string, returning a caller-supplied fallback when the input
+* is empty or malformed instead of throwing. Useful at provider boundaries
+* where tool-call arguments may arrive as `null`, `""`, or partial JSON
+* during streaming — callers want a safe default, not an exception.
+*
+* @example
+* const args = safeJsonParse<Record<string, unknown>>(toolCall.function.arguments, {});
+*/
+function safeJsonParse(data, defaultValue) {
+	if (!data) return defaultValue;
+	try {
+		return JSON.parse(data);
+	} catch {
+		return defaultValue;
+	}
+}
+
+//#endregion
+export { safeJsonParse };
+//# sourceMappingURL=safe-json-parse.mjs.map

package/esm/ai/src/utils/safe-json-parse.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-json-parse.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/utils/safe-json-parse.ts"],"sourcesContent":["/**\n * Parse a JSON string, returning a caller-supplied fallback when the input\n * is empty or malformed instead of throwing. Useful at provider boundaries\n * where tool-call arguments may arrive as `null`, `\"\"`, or partial JSON\n * during streaming — callers want a safe default, not an exception.\n *\n * @example\n * const args = safeJsonParse<Record<string, unknown>>(toolCall.function.arguments, {});\n */\nexport function safeJsonParse<TValue>(\n  data: string | null | undefined,\n  defaultValue: TValue,\n): TValue {\n  if (!data) {\n    return defaultValue;\n  }\n\n  try {\n    return JSON.parse(data) as TValue;\n  } catch {\n    return defaultValue;\n  }\n}\n"],"mappings":";;;;;;;;;;AASA,SAAgB,cACd,MACA,cACQ;CACR,IAAI,CAAC,MACH,OAAO;CAGT,IAAI;EACF,OAAO,KAAK,MAAM,IAAI;CACxB,QAAQ;EACN,OAAO;CACT;AACF"}

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