@warlock.js/ai 4.1.1

package/esm/utils/json-schema.mjs

@@ -0,0 +1,89 @@
+//#region ../../@warlock.js/ai/src/utils/json-schema.ts
+/**
+* Best-effort JSON Schema extraction from a Standard Schema instance.
+*
+* Different libraries expose their JSON representation through different
+* paths:
+* - **Seal / Standard JSON Schema V1**: `["~standard"].jsonSchema.input({ target })`
+*   — nested under the spec object, takes a target switch. Default target
+*   is `"openai-strict"` since the primary consumer is OpenAI's native
+*   structured-output mechanism; pass `options.target` to override.
+* - **Zod / similar**: top-level `.jsonSchema` property. Zod v4 actually
+*   ships `toJSONSchema` as a module function, not a method, so it does
+*   NOT hit this probe — Zod users pass their converted schema via the
+*   `AgentExecuteOptions.responseSchema` escape hatch.
+*
+* Deliberately does NOT probe `toJSON` — that's a generic JavaScript
+* serialization hook (Seal's schemas have one that dumps internal rule
+* state) and matching it would return garbage disguised as a JSON Schema.
+*
+* Returns `undefined` when no path matches. The caller then either skips
+* native structured-output wiring or falls back to a schema-less
+* instruction.
+*
+* Shared across every SDK adapter package (OpenAI, Anthropic, Bedrock…)
+* so each provider converts schemas identically.
+*
+* @example
+* const schema = extractJsonSchema(mySealSchema);
+* // { type: "object", properties: { ... }, required: [ ... ], additionalProperties: false }
+*
+* @example
+* // Ask for a different target explicitly
+* const draft = extractJsonSchema(mySealSchema, { target: "draft-2020-12" });
+*/
+function extractJsonSchema(schema, options = {}) {
+	if (!schema) return void 0;
+	const sealJsonSchema = extractFromSealPath(schema, options.target ?? "openai-strict");
+	if (sealJsonSchema) return sealJsonSchema;
+	const topLevel = extractFromCandidateKeys(schema);
+	if (topLevel) return topLevel;
+}
+/**
+* Probe the Standard JSON Schema V1 extension path on `schema["~standard"]`.
+* The spec defines `jsonSchema.input({ target, libraryOptions? })` as a
+* function returning a JSON Schema tailored to the requested target. We
+* pass the caller's target (default `"openai-strict"`) so the library
+* produces output ready for OpenAI's native structured-output mode
+* without additional post-processing.
+*
+* Calling `.input()` without a target would throw (or return garbage) per
+* the spec — a failure here returns `undefined` so the fallback probe
+* runs.
+*/
+function extractFromSealPath(schema, target) {
+	const standardSlot = schema["~standard"];
+	if (!standardSlot || typeof standardSlot !== "object") return;
+	const jsonSchemaSlot = standardSlot["jsonSchema"];
+	if (!jsonSchemaSlot || typeof jsonSchemaSlot !== "object") return;
+	const inputFn = jsonSchemaSlot["input"];
+	if (typeof inputFn !== "function") return;
+	try {
+		const result = inputFn.call(jsonSchemaSlot, { target });
+		if (result && typeof result === "object") return result;
+	} catch {}
+}
+/**
+* Probe well-known top-level keys libraries use to expose their JSON
+* Schema. Supports both method form (rare) and property form (common).
+* Deliberately narrow — `toJSON` is NOT probed here because it's a
+* generic serialization hook that returns library-internal state for
+* many validators (Seal included), not a JSON Schema.
+*/
+function extractFromCandidateKeys(schemaRecord) {
+	for (const key of ["jsonSchema", "_jsonSchema"]) {
+		const value = schemaRecord[key];
+		if (typeof value === "function") {
+			try {
+				const result = value.call(schemaRecord);
+				if (result && typeof result === "object") return result;
+			} catch {}
+			continue;
+		}
+		if (value && typeof value === "object") return value;
+	}
+}
+
+//#endregion
+export { extractJsonSchema };
+//# sourceMappingURL=json-schema.mjs.map

package/esm/utils/json-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/json-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Supported JSON Schema output targets per the Standard JSON Schema V1\n * spec. `openai-strict` is the richest for OpenAI structured outputs —\n * every property listed in `required`, optionals expressed as\n * `[\"T\", \"null\"]`, `additionalProperties: false` everywhere. Other\n * targets produce standards-compliant but looser output.\n */\nexport type JsonSchemaTarget = \"draft-2020-12\" | \"draft-07\" | \"openapi-3.0\" | \"openai-strict\";\n\n/**\n * Options for `extractJsonSchema`. `target` is forwarded to libraries that\n * implement the Standard JSON Schema V1 spec (Seal, and any future lib\n * that follows the spec). Libraries using their own top-level `.jsonSchema`\n * / `._jsonSchema` property ignore the target.\n */\nexport type ExtractJsonSchemaOptions = {\n  target?: JsonSchemaTarget | (string & {});\n};\n\n/**\n * Best-effort JSON Schema extraction from a Standard Schema instance.\n *\n * Different libraries expose their JSON representation through different\n * paths:\n * - **Seal / Standard JSON Schema V1**: `[\"~standard\"].jsonSchema.input({ target })`\n *   — nested under the spec object, takes a target switch. Default target\n *   is `\"openai-strict\"` since the primary consumer is OpenAI's native\n *   structured-output mechanism; pass `options.target` to override.\n * - **Zod / similar**: top-level `.jsonSchema` property. Zod v4 actually\n *   ships `toJSONSchema` as a module function, not a method, so it does\n *   NOT hit this probe — Zod users pass their converted schema via the\n *   `AgentExecuteOptions.responseSchema` escape hatch.\n *\n * Deliberately does NOT probe `toJSON` — that's a generic JavaScript\n * serialization hook (Seal's schemas have one that dumps internal rule\n * state) and matching it would return garbage disguised as a JSON Schema.\n *\n * Returns `undefined` when no path matches. The caller then either skips\n * native structured-output wiring or falls back to a schema-less\n * instruction.\n *\n * Shared across every SDK adapter package (OpenAI, Anthropic, Bedrock…)\n * so each provider converts schemas identically.\n *\n * @example\n * const schema = extractJsonSchema(mySealSchema);\n * // { type: \"object\", properties: { ... }, required: [ ... ], additionalProperties: false }\n *\n * @example\n * // Ask for a different target explicitly\n * const draft = extractJsonSchema(mySealSchema, { target: \"draft-2020-12\" });\n */\nexport function extractJsonSchema(\n  schema: StandardSchemaV1<unknown> | undefined,\n  options: ExtractJsonSchemaOptions = {},\n): Record<string, unknown> | undefined {\n  if (!schema) return undefined;\n\n  const target = options.target ?? \"openai-strict\";\n\n  // 1. Seal / Standard JSON Schema V1 pattern: [\"~standard\"].jsonSchema.input({ target })\n  const sealJsonSchema = extractFromSealPath(schema, target);\n\n  if (sealJsonSchema) {\n    return sealJsonSchema;\n  }\n\n  // 2. Top-level jsonSchema / _jsonSchema (Zod-like, property or method form)\n  const topLevel = extractFromCandidateKeys(schema as unknown as Record<string, unknown>);\n\n  if (topLevel) {\n    return topLevel;\n  }\n\n  return undefined;\n}\n\n/**\n * Probe the Standard JSON Schema V1 extension path on `schema[\"~standard\"]`.\n * The spec defines `jsonSchema.input({ target, libraryOptions? })` as a\n * function returning a JSON Schema tailored to the requested target. We\n * pass the caller's target (default `\"openai-strict\"`) so the library\n * produces output ready for OpenAI's native structured-output mode\n * without additional post-processing.\n *\n * Calling `.input()` without a target would throw (or return garbage) per\n * the spec — a failure here returns `undefined` so the fallback probe\n * runs.\n */\nfunction extractFromSealPath(\n  schema: StandardSchemaV1<unknown>,\n  target: string,\n): Record<string, unknown> | undefined {\n  const standardSlot = (schema as unknown as Record<string, unknown>)[\"~standard\"];\n\n  if (!standardSlot || typeof standardSlot !== \"object\") {\n    return undefined;\n  }\n\n  const jsonSchemaSlot = (standardSlot as Record<string, unknown>)[\"jsonSchema\"];\n\n  if (!jsonSchemaSlot || typeof jsonSchemaSlot !== \"object\") {\n    return undefined;\n  }\n\n  const inputFn = (jsonSchemaSlot as Record<string, unknown>)[\"input\"];\n\n  if (typeof inputFn !== \"function\") {\n    return undefined;\n  }\n\n  try {\n    const result = (inputFn as (options: { target: string }) => unknown).call(jsonSchemaSlot, {\n      target,\n    });\n\n    if (result && typeof result === \"object\") {\n      return result as Record<string, unknown>;\n    }\n  } catch {\n    // fall through — library didn't support the target or threw otherwise\n  }\n\n  return undefined;\n}\n\n/**\n * Probe well-known top-level keys libraries use to expose their JSON\n * Schema. Supports both method form (rare) and property form (common).\n * Deliberately narrow — `toJSON` is NOT probed here because it's a\n * generic serialization hook that returns library-internal state for\n * many validators (Seal included), not a JSON Schema.\n */\nfunction extractFromCandidateKeys(\n  schemaRecord: Record<string, unknown>,\n): Record<string, unknown> | undefined {\n  const candidateKeys = [\"jsonSchema\", \"_jsonSchema\"] as const;\n\n  for (const key of candidateKeys) {\n    const value = schemaRecord[key];\n\n    if (typeof value === \"function\") {\n      try {\n        const result = (value as () => unknown).call(schemaRecord);\n\n        if (result && typeof result === \"object\") {\n          return result as Record<string, unknown>;\n        }\n      } catch {\n        // try next candidate\n      }\n\n      continue;\n    }\n\n    if (value && typeof value === \"object\") {\n      return value as Record<string, unknown>;\n    }\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAgB,kBACd,QACA,UAAoC,CAAC,GACA;CACrC,IAAI,CAAC,QAAQ,OAAO;CAKpB,MAAM,iBAAiB,oBAAoB,QAH5B,QAAQ,UAAU,eAGwB;CAEzD,IAAI,gBACF,OAAO;CAIT,MAAM,WAAW,yBAAyB,MAA4C;CAEtF,IAAI,UACF,OAAO;AAIX;;;;;;;;;;;;;AAcA,SAAS,oBACP,QACA,QACqC;CACrC,MAAM,eAAgB,OAA8C;CAEpE,IAAI,CAAC,gBAAgB,OAAO,iBAAiB,UAC3C;CAGF,MAAM,iBAAkB,aAAyC;CAEjE,IAAI,CAAC,kBAAkB,OAAO,mBAAmB,UAC/C;CAGF,MAAM,UAAW,eAA2C;CAE5D,IAAI,OAAO,YAAY,YACrB;CAGF,IAAI;EACF,MAAM,SAAU,QAAqD,KAAK,gBAAgB,EACxF,OACF,CAAC;EAED,IAAI,UAAU,OAAO,WAAW,UAC9B,OAAO;CAEX,QAAQ,CAER;AAGF;;;;;;;;AASA,SAAS,yBACP,cACqC;CAGrC,KAAK,MAAM,OAAO,CAFK,cAAc,aAEP,GAAG;EAC/B,MAAM,QAAQ,aAAa;EAE3B,IAAI,OAAO,UAAU,YAAY;GAC/B,IAAI;IACF,MAAM,SAAU,MAAwB,KAAK,YAAY;IAEzD,IAAI,UAAU,OAAO,WAAW,UAC9B,OAAO;GAEX,QAAQ,CAER;GAEA;EACF;EAEA,IAAI,SAAS,OAAO,UAAU,UAC5B,OAAO;CAEX;AAGF"}

package/esm/utils/prepare-attachment-part.d.mts

@@ -0,0 +1,36 @@
+import { Attachment } from "../contracts/attachment.type.mjs";
+import { ContentPart } from "../contracts/content-part.type.mjs";
+
+//#region ../../@warlock.js/ai/src/utils/prepare-attachment-part.d.ts
+/**
+ * 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>" }
+ */
+declare function prepareAttachmentPart(attachment: Attachment): Promise<ContentPart>;
+//#endregion
+export { prepareAttachmentPart };
+//# sourceMappingURL=prepare-attachment-part.d.mts.map

package/esm/utils/prepare-attachment-part.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-attachment-part.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/prepare-attachment-part.ts"],"mappings":";;;;;;AA+CA;;;;;;;;;;;;;AAEsB;;;;;;;;;;;;;iBAFA,qBAAA,CACpB,UAAA,EAAY,UAAA,GACX,OAAA,CAAQ,WAAA"}

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

@@ -0,0 +1,140 @@
+import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import "../errors/index.mjs";
+import { resolveAttachment } from "./resolve-attachment.mjs";
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+
+//#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"]);
+/**
+* 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>" }
+*/
+async function prepareAttachmentPart(attachment) {
+	if (resolveKind(attachment) === "text") return prepareTextPart(attachment);
+	return prepareImagePart(attachment);
+}
+/**
+* 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";
+	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)");
+}
+/**
+* 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) {
+	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 } });
+	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) {
+	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: {
+			url: resolved.value,
+			status: response.status
+		} });
+		return {
+			type: "text",
+			text: await response.text()
+		};
+	}
+	if (resolved.type === "base64") return {
+		type: "text",
+		text: Buffer.from(resolved.value, "base64").toString("utf8")
+	};
+	return {
+		type: "text",
+		text: await readFile(resolved.value, "utf8")
+	};
+}
+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/utils/prepare-attachment-part.mjs.map

@@ -0,0 +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,EAAE,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,GAIjB,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,EAAE,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,EAAE,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"}

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

@@ -0,0 +1,33 @@
+import { Attachment, ResolvedAttachment } from "../contracts/attachment.type.mjs";
+
+//#region ../../@warlock.js/ai/src/utils/resolve-attachment.d.ts
+/**
+ * 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? }`) → URL wins over
+ *   absolute path. URL becomes `{ type: "url" }`; absolute path
+ *   becomes `{ type: "path" }`.
+ * - 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" }
+ */
+declare function resolveAttachment(attachment: Attachment): ResolvedAttachment;
+//#endregion
+export { resolveAttachment };
+//# sourceMappingURL=resolve-attachment.d.mts.map

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

@@ -0,0 +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"}

package/esm/utils/resolve-attachment.mjs

@@ -0,0 +1,73 @@
+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? }`) → URL wins over
+*   absolute path. URL becomes `{ type: "url" }`; absolute path
+*   becomes `{ type: "path" }`.
+* - 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/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? }`) → 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"}

package/esm/utils/safe-json-parse.d.mts

@@ -0,0 +1,14 @@
+//#region ../../@warlock.js/ai/src/utils/safe-json-parse.d.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, {});
+ */
+declare function safeJsonParse<TValue>(data: string | null | undefined, defaultValue: TValue): TValue;
+//#endregion
+export { safeJsonParse };
+//# sourceMappingURL=safe-json-parse.d.mts.map

package/esm/utils/safe-json-parse.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-json-parse.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/safe-json-parse.ts"],"mappings":";;AASA;;;;;;;;iBAAgB,aAAA,QAAA,CACd,IAAA,6BACA,YAAA,EAAc,MAAA,GACb,MAAM"}

package/esm/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/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/utils/stamp-report-lineage.d.mts

@@ -0,0 +1,61 @@
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+
+//#region ../../@warlock.js/ai/src/utils/stamp-report-lineage.d.ts
+/**
+ * Options for {@link stampReportLineage}. Every field is optional —
+ * the caller supplies whichever pieces it knows. Missing pieces are
+ * left untouched (existing values on the report survive).
+ */
+type LineageStamp = {
+  /**
+   * The outermost run-id this subtree belongs to. When set, EVERY
+   * node in the subtree gets its `rootRunId` rewritten to this
+   * value — overrides any inner self-roots produced by nested
+   * `buildResult` calls.
+   */
+  rootRunId: string;
+  /**
+   * Run-id of the immediate parent of THIS subtree's top node. Each
+   * descendant's `parentRunId` is then derived from its own walk
+   * position (its parent's `runId`).
+   */
+  parentRunId?: string;
+  /**
+   * Caller-supplied session identifier — propagates to every node in
+   * the subtree. Skipped when undefined.
+   */
+  sessionId?: string;
+};
+/**
+ * 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 };
+ */
+declare function stampReportLineage(root: BaseReport, stamp: LineageStamp): void;
+//#endregion
+export { LineageStamp, stampReportLineage };
+//# sourceMappingURL=stamp-report-lineage.d.mts.map

package/esm/utils/stamp-report-lineage.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp-report-lineage.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/stamp-report-lineage.ts"],"mappings":";;;;;AAQA;;;KAAY,YAAA;EAOV;;;;AAWS;AAgCX;EA3CE,SAAA;;;;;;EAMA,WAAA;EAqCsE;AAAA;;;EAhCtE,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCc,kBAAA,CAAmB,IAAA,EAAM,UAAA,EAAY,KAAA,EAAO,YAAY"}

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

@@ -0,0 +1,47 @@
+import { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
+
+//#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/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/utils/token-count.d.mts

@@ -0,0 +1,15 @@
+//#region ../../@warlock.js/ai/src/utils/token-count.d.ts
+/**
+ * Approximate the number of tokens in a string.
+ *
+ * Uses the ~4-characters-per-token heuristic, which is accurate enough for
+ * GPT-4 family models and most English text. Use this when a real tokenizer
+ * (tiktoken, etc.) isn't available or would add native dependencies.
+ *
+ * @example
+ * const tokens = approximateTokenCount("Hello, world!"); // 4
+ */
+declare function approximateTokenCount(text: string): number;
+//#endregion
+export { approximateTokenCount };
+//# sourceMappingURL=token-count.d.mts.map

package/esm/utils/token-count.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-count.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/token-count.ts"],"mappings":";;AAUA;;;;AAAkD;;;;;iBAAlC,qBAAA,CAAsB,IAAY"}

package/esm/utils/token-count.mjs

@@ -0,0 +1,18 @@
+//#region ../../@warlock.js/ai/src/utils/token-count.ts
+/**
+* Approximate the number of tokens in a string.
+*
+* Uses the ~4-characters-per-token heuristic, which is accurate enough for
+* GPT-4 family models and most English text. Use this when a real tokenizer
+* (tiktoken, etc.) isn't available or would add native dependencies.
+*
+* @example
+* const tokens = approximateTokenCount("Hello, world!"); // 4
+*/
+function approximateTokenCount(text) {
+	return Math.ceil(text.length / 4);
+}
+
+//#endregion
+export { approximateTokenCount };
+//# sourceMappingURL=token-count.mjs.map

package/esm/utils/token-count.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-count.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/token-count.ts"],"sourcesContent":["/**\n * Approximate the number of tokens in a string.\n *\n * Uses the ~4-characters-per-token heuristic, which is accurate enough for\n * GPT-4 family models and most English text. Use this when a real tokenizer\n * (tiktoken, etc.) isn't available or would add native dependencies.\n *\n * @example\n * const tokens = approximateTokenCount(\"Hello, world!\"); // 4\n */\nexport function approximateTokenCount(text: string): number {\n  return Math.ceil(text.length / 4);\n}\n"],"mappings":";;;;;;;;;;;AAUA,SAAgB,sBAAsB,MAAsB;CAC1D,OAAO,KAAK,KAAK,KAAK,SAAS,CAAC;AAClC"}