@warlock.js/core 4.3.0 → 4.5.0

package/esm/ai/src/utils/index.mjs

@@ -0,0 +1,12 @@
+import { accumulateCost, computeCost, mergeUsage } from "./compute-cost.mjs";
+import { extractJsonPayload } from "./extract-json-payload.mjs";
+import { extractJsonLenient } from "./extract-json-lenient.mjs";
+import { generateRunId } from "./generate-run-id.mjs";
+import { extractJsonSchema } from "./json-schema.mjs";
+import { resolveAttachment } from "./resolve-attachment.mjs";
+import { prepareAttachmentPart } from "./prepare-attachment-part.mjs";
+import { captureChildReport, withRunFrame, withoutRunFrame } from "./run-context.mjs";
+import { safeJsonParse } from "./safe-json-parse.mjs";
+import { stampReportLineage } from "./stamp-report-lineage.mjs";
+
+export {  };

package/esm/ai/src/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/ai/src/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/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"}