@warlock.js/core 4.4.0 → 4.6.0

package/esm/ai/src/utils/compute-cost.mjs

@@ -0,0 +1,112 @@
+//#region ../@warlock.js/ai/src/utils/compute-cost.ts
+/**
+* Compute a per-channel USD cost breakdown for a single `Usage` against
+* a model's pricing table. Returns `undefined` when no pricing is
+* configured — the framework treats unpriced runs as "cost unknown,"
+* not "cost zero," so dashboards can distinguish free-tier from
+* un-instrumented.
+*
+* **Shape mirrors `ModelPricing`** — `input`, `output`, optional
+* `cachedInput` / `cachedOutput`. Consumers needing a scalar total
+* sum the populated fields. The breakdown is the value-add: it tells
+* downstream tooling HOW the total was reached (input-vs-output
+* share, cache savings) without re-deriving against pricing tables
+* that may have shifted since the report was written.
+*
+* **Cache-aware.** `usage.cachedTokens` is the subset of `usage.input`
+* served from the provider's prompt cache and bills at
+* `pricing.cachedInput` (falls back to full `pricing.input` when the
+* provider doesn't publish a cache rate). The remaining `input -
+* cachedTokens` bills at full rate and shows up in `cost.input`. The
+* `cachedOutput` channel is reserved for Anthropic-style cache writes;
+* until an adapter populates `usage.cacheWriteTokens`, the framework
+* leaves it undefined.
+*
+* Pricing values are USD-per-million-tokens. The function divides
+* once at the end to avoid floating-point accumulation error on
+* per-token math.
+*
+* @example
+* const usage: Usage = { input: 150_000, output: 30_000, total: 180_000, cachedTokens: 90_000 };
+* const cost = computeCost(usage, { input: 0.15, output: 0.6, cachedInput: 0.075 });
+* // cost = {
+* //   input: (60_000 * 0.15) / 1e6 = 0.009,
+* //   output: (30_000 * 0.6) / 1e6 = 0.018,
+* //   cachedInput: (90_000 * 0.075) / 1e6 = 0.00675,
+* // }
+*/
+function computeCost(usage, pricing) {
+	if (!pricing) return;
+	const cachedInput = usage.cachedTokens ?? 0;
+	const cost = {
+		input: Math.max(0, usage.input - cachedInput) * pricing.input / 1e6,
+		output: usage.output * pricing.output / 1e6
+	};
+	if (cachedInput > 0) cost.cachedInput = cachedInput * (pricing.cachedInput ?? pricing.input) / 1e6;
+	return cost;
+}
+/**
+* Merge a child's cost breakdown into a running parent total. Each
+* channel (`input`, `output`, `cachedInput`, `cachedOutput`) sums
+* independently — an undefined channel on either side is treated as
+* zero contribution rather than dropping the other side's value. A
+* single unpriced child should never erase the cost of its priced
+* siblings.
+*
+* Returns the new parent breakdown, or `undefined` when neither parent
+* nor child carried any cost data (preserves the "no priced
+* contributor has appeared yet" signal that distinguishes "missing
+* pricing" from "genuinely zero").
+*/
+function accumulateCost(parent, child) {
+	if (!child) return parent;
+	if (!parent) return { ...child };
+	const merged = {
+		input: parent.input + child.input,
+		output: parent.output + child.output
+	};
+	const cachedInput = sumOptional(parent.cachedInput, child.cachedInput);
+	if (cachedInput !== void 0) merged.cachedInput = cachedInput;
+	const cachedOutput = sumOptional(parent.cachedOutput, child.cachedOutput);
+	if (cachedOutput !== void 0) merged.cachedOutput = cachedOutput;
+	return merged;
+}
+/**
+* Add two optional numbers, treating either side's `undefined` as
+* zero — but return `undefined` when both are absent. Keeps "this
+* channel was never reported anywhere" distinguishable from "this
+* channel was reported as 0."
+*/
+function sumOptional(parent, child) {
+	if (parent === void 0 && child === void 0) return;
+	return (parent ?? 0) + (child ?? 0);
+}
+/**
+* Accumulate a child {@link Usage} into a running parent total, mutating
+* `target` in place. Scalar token channels (`input` / `output` / `total`)
+* sum directly; the optional sub-channels (`cachedTokens`,
+* `reasoningTokens`, `cacheWriteTokens`) accumulate only when some
+* contributor reported them (preserving the "never reported anywhere"
+* signal); and the cost breakdown merges via {@link accumulateCost} so a
+* single unpriced child can never erase a priced sibling's cost.
+*
+* This is the ONE canonical usage rollup — every aggregator (agent,
+* workflow, supervisor, team, planner, batch) routes through it so cost +
+* cache/reasoning telemetry propagates identically to the top-level
+* `result.usage`. Re-implementing a bare `input/output/total` sum at a
+* call site silently drops those optional channels.
+*/
+function mergeUsage(target, child) {
+	target.input += child.input;
+	target.output += child.output;
+	target.total += child.total;
+	if (child.cachedTokens !== void 0) target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;
+	if (child.reasoningTokens !== void 0) target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;
+	if (child.cacheWriteTokens !== void 0) target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;
+	const mergedCost = accumulateCost(target.cost, child.cost);
+	if (mergedCost !== void 0) target.cost = mergedCost;
+}
+
+//#endregion
+export { accumulateCost, computeCost, mergeUsage };
+//# sourceMappingURL=compute-cost.mjs.map

package/esm/ai/src/utils/compute-cost.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-cost.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/utils/compute-cost.ts"],"sourcesContent":["import type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\n\n/**\n * Compute a per-channel USD cost breakdown for a single `Usage` against\n * a model's pricing table. Returns `undefined` when no pricing is\n * configured — the framework treats unpriced runs as \"cost unknown,\"\n * not \"cost zero,\" so dashboards can distinguish free-tier from\n * un-instrumented.\n *\n * **Shape mirrors `ModelPricing`** — `input`, `output`, optional\n * `cachedInput` / `cachedOutput`. Consumers needing a scalar total\n * sum the populated fields. The breakdown is the value-add: it tells\n * downstream tooling HOW the total was reached (input-vs-output\n * share, cache savings) without re-deriving against pricing tables\n * that may have shifted since the report was written.\n *\n * **Cache-aware.** `usage.cachedTokens` is the subset of `usage.input`\n * served from the provider's prompt cache and bills at\n * `pricing.cachedInput` (falls back to full `pricing.input` when the\n * provider doesn't publish a cache rate). The remaining `input -\n * cachedTokens` bills at full rate and shows up in `cost.input`. The\n * `cachedOutput` channel is reserved for Anthropic-style cache writes;\n * until an adapter populates `usage.cacheWriteTokens`, the framework\n * leaves it undefined.\n *\n * Pricing values are USD-per-million-tokens. The function divides\n * once at the end to avoid floating-point accumulation error on\n * per-token math.\n *\n * @example\n * const usage: Usage = { input: 150_000, output: 30_000, total: 180_000, cachedTokens: 90_000 };\n * const cost = computeCost(usage, { input: 0.15, output: 0.6, cachedInput: 0.075 });\n * // cost = {\n * //   input: (60_000 * 0.15) / 1e6 = 0.009,\n * //   output: (30_000 * 0.6) / 1e6 = 0.018,\n * //   cachedInput: (90_000 * 0.075) / 1e6 = 0.00675,\n * // }\n */\nexport function computeCost(usage: Usage, pricing: ModelPricing | undefined): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  const cachedInput = usage.cachedTokens ?? 0;\n  const uncachedInput = Math.max(0, usage.input - cachedInput);\n\n  const cost: ModelPricing = {\n    input: (uncachedInput * pricing.input) / 1_000_000,\n    output: (usage.output * pricing.output) / 1_000_000,\n  };\n\n  if (cachedInput > 0) {\n    const cachedInputRate = pricing.cachedInput ?? pricing.input;\n    cost.cachedInput = (cachedInput * cachedInputRate) / 1_000_000;\n  }\n\n  return cost;\n}\n\n/**\n * Merge a child's cost breakdown into a running parent total. Each\n * channel (`input`, `output`, `cachedInput`, `cachedOutput`) sums\n * independently — an undefined channel on either side is treated as\n * zero contribution rather than dropping the other side's value. A\n * single unpriced child should never erase the cost of its priced\n * siblings.\n *\n * Returns the new parent breakdown, or `undefined` when neither parent\n * nor child carried any cost data (preserves the \"no priced\n * contributor has appeared yet\" signal that distinguishes \"missing\n * pricing\" from \"genuinely zero\").\n */\nexport function accumulateCost(\n  parent: ModelPricing | undefined,\n  child: ModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!child) {\n    return parent;\n  }\n\n  if (!parent) {\n    return { ...child };\n  }\n\n  const merged: ModelPricing = {\n    input: parent.input + child.input,\n    output: parent.output + child.output,\n  };\n\n  const cachedInput = sumOptional(parent.cachedInput, child.cachedInput);\n  if (cachedInput !== undefined) {\n    merged.cachedInput = cachedInput;\n  }\n\n  const cachedOutput = sumOptional(parent.cachedOutput, child.cachedOutput);\n  if (cachedOutput !== undefined) {\n    merged.cachedOutput = cachedOutput;\n  }\n\n  return merged;\n}\n\n/**\n * Add two optional numbers, treating either side's `undefined` as\n * zero — but return `undefined` when both are absent. Keeps \"this\n * channel was never reported anywhere\" distinguishable from \"this\n * channel was reported as 0.\"\n */\nfunction sumOptional(parent: number | undefined, child: number | undefined): number | undefined {\n  if (parent === undefined && child === undefined) {\n    return undefined;\n  }\n\n  return (parent ?? 0) + (child ?? 0);\n}\n\n/**\n * Accumulate a child {@link Usage} into a running parent total, mutating\n * `target` in place. Scalar token channels (`input` / `output` / `total`)\n * sum directly; the optional sub-channels (`cachedTokens`,\n * `reasoningTokens`, `cacheWriteTokens`) accumulate only when some\n * contributor reported them (preserving the \"never reported anywhere\"\n * signal); and the cost breakdown merges via {@link accumulateCost} so a\n * single unpriced child can never erase a priced sibling's cost.\n *\n * This is the ONE canonical usage rollup — every aggregator (agent,\n * workflow, supervisor, team, planner, batch) routes through it so cost +\n * cache/reasoning telemetry propagates identically to the top-level\n * `result.usage`. Re-implementing a bare `input/output/total` sum at a\n * call site silently drops those optional channels.\n */\nexport function mergeUsage(target: Usage, child: Usage): void {\n  target.input += child.input;\n  target.output += child.output;\n  target.total += child.total;\n\n  if (child.cachedTokens !== undefined) {\n    target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;\n  }\n\n  if (child.reasoningTokens !== undefined) {\n    target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;\n  }\n\n  if (child.cacheWriteTokens !== undefined) {\n    target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;\n  }\n\n  const mergedCost = accumulateCost(target.cost, child.cost);\n  if (mergedCost !== undefined) {\n    target.cost = mergedCost;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,YAAY,OAAc,SAA6D;CACrG,IAAI,CAAC,SACH;CAGF,MAAM,cAAc,MAAM,gBAAgB;CAG1C,MAAM,OAAqB;EACzB,OAHoB,KAAK,IAAI,GAAG,MAAM,QAAQ,WAG1B,IAAI,QAAQ,QAAS;EACzC,QAAS,MAAM,SAAS,QAAQ,SAAU;CAC5C;CAEA,IAAI,cAAc,GAEhB,KAAK,cAAe,eADI,QAAQ,eAAe,QAAQ,SACF;CAGvD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,eACd,QACA,OAC0B;CAC1B,IAAI,CAAC,OACH,OAAO;CAGT,IAAI,CAAC,QACH,OAAO,EAAE,GAAG,MAAM;CAGpB,MAAM,SAAuB;EAC3B,OAAO,OAAO,QAAQ,MAAM;EAC5B,QAAQ,OAAO,SAAS,MAAM;CAChC;CAEA,MAAM,cAAc,YAAY,OAAO,aAAa,MAAM,WAAW;CACrE,IAAI,gBAAgB,QAClB,OAAO,cAAc;CAGvB,MAAM,eAAe,YAAY,OAAO,cAAc,MAAM,YAAY;CACxE,IAAI,iBAAiB,QACnB,OAAO,eAAe;CAGxB,OAAO;AACT;;;;;;;AAQA,SAAS,YAAY,QAA4B,OAA+C;CAC9F,IAAI,WAAW,UAAa,UAAU,QACpC;CAGF,QAAQ,UAAU,MAAM,SAAS;AACnC;;;;;;;;;;;;;;;;AAiBA,SAAgB,WAAW,QAAe,OAAoB;CAC5D,OAAO,SAAS,MAAM;CACtB,OAAO,UAAU,MAAM;CACvB,OAAO,SAAS,MAAM;CAEtB,IAAI,MAAM,iBAAiB,QACzB,OAAO,gBAAgB,OAAO,gBAAgB,KAAK,MAAM;CAG3D,IAAI,MAAM,oBAAoB,QAC5B,OAAO,mBAAmB,OAAO,mBAAmB,KAAK,MAAM;CAGjE,IAAI,MAAM,qBAAqB,QAC7B,OAAO,oBAAoB,OAAO,oBAAoB,KAAK,MAAM;CAGnE,MAAM,aAAa,eAAe,OAAO,MAAM,MAAM,IAAI;CACzD,IAAI,eAAe,QACjB,OAAO,OAAO;AAElB"}

package/esm/ai/src/utils/extract-json-lenient.mjs

@@ -0,0 +1,97 @@
+import { extractJsonPayload } from "./extract-json-payload.mjs";
+
+//#region ../@warlock.js/ai/src/utils/extract-json-lenient.ts
+/**
+* Lenient counterpart to {@link extractJsonPayload}, tuned for the
+* structured-output judges that emit *corrupted* JSON — notably the
+* Amazon Nova family, which routinely wraps its verdict in fenced
+* ` ```json ` blocks, prepends an explanation paragraph, or trails the
+* object with commentary.
+*
+* Where `extractJsonPayload` deliberately refuses the "first `{` … last
+* `}`" heuristic (it would corrupt strict callers when prose contains
+* stray braces), this helper *opts into* that resilience: after fence
+* stripping it scans for the first balanced JSON object (`{…}`) or array
+* (`[…]`) and returns just that slice. Brace/bracket counting is
+* string-aware (it ignores braces inside JSON string literals and honors
+* `\"` escapes), so prose-embedded braces inside the JSON's own strings
+* don't throw off the balance.
+*
+* Returns the fence-stripped, trimmed text unchanged when no balanced
+* structure is found, so the caller's `JSON.parse` still fails loudly on
+* genuine garbage rather than this helper inventing a value.
+*
+* **Trade-off:** resilience over strictness. Use it only where a tolerant
+* parse is wanted (the judge preset) — for normal structured output keep
+* `extractJsonPayload`, which fails fast on malformed responses so real
+* prompt/model defects surface instead of being silently papered over.
+*
+* @example
+* extractJsonLenient('Here is my verdict:\n```json\n{"score":0.9}\n``` — done.');
+* // => '{"score":0.9}'
+*
+* @example
+* extractJsonLenient('The answer is {"verdict":"pass"} for sure.');
+* // => '{"verdict":"pass"}'
+*
+* @example
+* extractJsonLenient('{"valid":true}');
+* // => '{"valid":true}'   (clean JSON passes through)
+*/
+function extractJsonLenient(text) {
+	const stripped = extractJsonPayload(text);
+	return sliceFirstBalanced(stripped) ?? stripped;
+}
+/**
+* Scan for the first balanced JSON object or array and return its raw
+* slice. Returns `undefined` when no opening `{`/`[` is found or the
+* structure never closes (truncated / partial output) — the caller then
+* falls back to the fence-stripped text so the failure stays visible.
+*
+* String-literal aware: braces and brackets appearing *inside* a JSON
+* string are not counted toward the balance, and a backslash escapes the
+* next character so an escaped quote (`\"`) doesn't prematurely end the
+* string scan.
+*/
+function sliceFirstBalanced(text) {
+	const start = firstOpenerIndex(text);
+	if (start === -1) return;
+	const opener = text[start];
+	const closer = opener === "{" ? "}" : "]";
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let index = start; index < text.length; index++) {
+		const char = text[index];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			continue;
+		}
+		if (char === opener) depth++;
+		else if (char === closer) {
+			depth--;
+			if (depth === 0) return text.slice(start, index + 1);
+		}
+	}
+}
+/**
+* Index of the first JSON structure opener (`{` or `[`), whichever
+* appears earliest, or `-1` when neither is present.
+*/
+function firstOpenerIndex(text) {
+	const brace = text.indexOf("{");
+	const bracket = text.indexOf("[");
+	if (brace === -1) return bracket;
+	if (bracket === -1) return brace;
+	return Math.min(brace, bracket);
+}
+
+//#endregion
+export { extractJsonLenient };
+//# sourceMappingURL=extract-json-lenient.mjs.map

package/esm/ai/src/utils/extract-json-lenient.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json-lenient.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/utils/extract-json-lenient.ts"],"sourcesContent":["import { extractJsonPayload } from \"./extract-json-payload\";\n\n/**\n * Lenient counterpart to {@link extractJsonPayload}, tuned for the\n * structured-output judges that emit *corrupted* JSON — notably the\n * Amazon Nova family, which routinely wraps its verdict in fenced\n * ` ```json ` blocks, prepends an explanation paragraph, or trails the\n * object with commentary.\n *\n * Where `extractJsonPayload` deliberately refuses the \"first `{` … last\n * `}`\" heuristic (it would corrupt strict callers when prose contains\n * stray braces), this helper *opts into* that resilience: after fence\n * stripping it scans for the first balanced JSON object (`{…}`) or array\n * (`[…]`) and returns just that slice. Brace/bracket counting is\n * string-aware (it ignores braces inside JSON string literals and honors\n * `\\\"` escapes), so prose-embedded braces inside the JSON's own strings\n * don't throw off the balance.\n *\n * Returns the fence-stripped, trimmed text unchanged when no balanced\n * structure is found, so the caller's `JSON.parse` still fails loudly on\n * genuine garbage rather than this helper inventing a value.\n *\n * **Trade-off:** resilience over strictness. Use it only where a tolerant\n * parse is wanted (the judge preset) — for normal structured output keep\n * `extractJsonPayload`, which fails fast on malformed responses so real\n * prompt/model defects surface instead of being silently papered over.\n *\n * @example\n * extractJsonLenient('Here is my verdict:\\n```json\\n{\"score\":0.9}\\n``` — done.');\n * // => '{\"score\":0.9}'\n *\n * @example\n * extractJsonLenient('The answer is {\"verdict\":\"pass\"} for sure.');\n * // => '{\"verdict\":\"pass\"}'\n *\n * @example\n * extractJsonLenient('{\"valid\":true}');\n * // => '{\"valid\":true}'   (clean JSON passes through)\n */\nexport function extractJsonLenient(text: string): string {\n  // First reuse the strict fence stripper. When the model produced a\n  // clean fenced block this already yields the exact payload, so the\n  // balanced scan below becomes a no-op pass-through.\n  const stripped = extractJsonPayload(text);\n\n  const sliced = sliceFirstBalanced(stripped);\n\n  return sliced ?? stripped;\n}\n\n/**\n * Scan for the first balanced JSON object or array and return its raw\n * slice. Returns `undefined` when no opening `{`/`[` is found or the\n * structure never closes (truncated / partial output) — the caller then\n * falls back to the fence-stripped text so the failure stays visible.\n *\n * String-literal aware: braces and brackets appearing *inside* a JSON\n * string are not counted toward the balance, and a backslash escapes the\n * next character so an escaped quote (`\\\"`) doesn't prematurely end the\n * string scan.\n */\nfunction sliceFirstBalanced(text: string): string | undefined {\n  const start = firstOpenerIndex(text);\n\n  if (start === -1) {\n    return undefined;\n  }\n\n  const opener = text[start];\n  const closer = opener === \"{\" ? \"}\" : \"]\";\n\n  let depth = 0;\n  let inString = false;\n  let escaped = false;\n\n  for (let index = start; index < text.length; index++) {\n    const char = text[index];\n\n    if (inString) {\n      if (escaped) {\n        escaped = false;\n      } else if (char === \"\\\\\") {\n        escaped = true;\n      } else if (char === '\"') {\n        inString = false;\n      }\n\n      continue;\n    }\n\n    if (char === '\"') {\n      inString = true;\n      continue;\n    }\n\n    if (char === opener) {\n      depth++;\n    } else if (char === closer) {\n      depth--;\n\n      if (depth === 0) {\n        return text.slice(start, index + 1);\n      }\n    }\n  }\n\n  // Opener with no matching close — truncated / partial output. Leave it\n  // to the caller's fallback (and its loud parse failure).\n  return undefined;\n}\n\n/**\n * Index of the first JSON structure opener (`{` or `[`), whichever\n * appears earliest, or `-1` when neither is present.\n */\nfunction firstOpenerIndex(text: string): number {\n  const brace = text.indexOf(\"{\");\n  const bracket = text.indexOf(\"[\");\n\n  if (brace === -1) {\n    return bracket;\n  }\n\n  if (bracket === -1) {\n    return brace;\n  }\n\n  return Math.min(brace, bracket);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,mBAAmB,MAAsB;CAIvD,MAAM,WAAW,mBAAmB,IAAI;CAIxC,OAFe,mBAAmB,QAEtB,KAAK;AACnB;;;;;;;;;;;;AAaA,SAAS,mBAAmB,MAAkC;CAC5D,MAAM,QAAQ,iBAAiB,IAAI;CAEnC,IAAI,UAAU,IACZ;CAGF,MAAM,SAAS,KAAK;CACpB,MAAM,SAAS,WAAW,MAAM,MAAM;CAEtC,IAAI,QAAQ;CACZ,IAAI,WAAW;CACf,IAAI,UAAU;CAEd,KAAK,IAAI,QAAQ,OAAO,QAAQ,KAAK,QAAQ,SAAS;EACpD,MAAM,OAAO,KAAK;EAElB,IAAI,UAAU;GACZ,IAAI,SACF,UAAU;QACL,IAAI,SAAS,MAClB,UAAU;QACL,IAAI,SAAS,MAClB,WAAW;GAGb;EACF;EAEA,IAAI,SAAS,MAAK;GAChB,WAAW;GACX;EACF;EAEA,IAAI,SAAS,QACX;OACK,IAAI,SAAS,QAAQ;GAC1B;GAEA,IAAI,UAAU,GACZ,OAAO,KAAK,MAAM,OAAO,QAAQ,CAAC;EAEtC;CACF;AAKF;;;;;AAMA,SAAS,iBAAiB,MAAsB;CAC9C,MAAM,QAAQ,KAAK,QAAQ,GAAG;CAC9B,MAAM,UAAU,KAAK,QAAQ,GAAG;CAEhC,IAAI,UAAU,IACZ,OAAO;CAGT,IAAI,YAAY,IACd,OAAO;CAGT,OAAO,KAAK,IAAI,OAAO,OAAO;AAChC"}

package/esm/ai/src/utils/extract-json-payload.mjs

@@ -0,0 +1,39 @@
+//#region ../@warlock.js/ai/src/utils/extract-json-payload.ts
+/**
+* Strip markdown code fences from an LLM response before JSON parsing.
+*
+* Models — especially Claude, smaller models, and local models — routinely
+* wrap JSON output in fenced code blocks (` ```json\n{...}\n``` `) even when
+* instructed otherwise. Sometimes they also precede the fence with prose
+* ("Here you go:\n```json\n...\n```"). This helper finds the first fenced
+* block regardless of language tag and returns its trimmed contents.
+*
+* Returns the trimmed original text unchanged when no fence is present, so
+* clean JSON passes through as a no-op.
+*
+* Deliberately does NOT fall back to "find first `{` and last `}` and slice
+* between them" — that heuristic silently corrupts data when prose contains
+* stray braces. Failing loudly at `JSON.parse` is safer.
+*
+* @example
+* extractJsonPayload('```json\n{"a":1}\n```');
+* // => '{"a":1}'
+*
+* @example
+* extractJsonPayload('Here you go:\n```\n{"a":1}\n```\nHope this helps.');
+* // => '{"a":1}'
+*
+* @example
+* extractJsonPayload('{"a":1}');
+* // => '{"a":1}'   (no fence → unchanged)
+*/
+function extractJsonPayload(text) {
+	const trimmed = text.trim();
+	const fenceMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+	if (fenceMatch) return fenceMatch[1].trim();
+	return trimmed;
+}
+
+//#endregion
+export { extractJsonPayload };
+//# sourceMappingURL=extract-json-payload.mjs.map

package/esm/ai/src/utils/extract-json-payload.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json-payload.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/utils/extract-json-payload.ts"],"sourcesContent":["/**\n * Strip markdown code fences from an LLM response before JSON parsing.\n *\n * Models — especially Claude, smaller models, and local models — routinely\n * wrap JSON output in fenced code blocks (` ```json\\n{...}\\n``` `) even when\n * instructed otherwise. Sometimes they also precede the fence with prose\n * (\"Here you go:\\n```json\\n...\\n```\"). This helper finds the first fenced\n * block regardless of language tag and returns its trimmed contents.\n *\n * Returns the trimmed original text unchanged when no fence is present, so\n * clean JSON passes through as a no-op.\n *\n * Deliberately does NOT fall back to \"find first `{` and last `}` and slice\n * between them\" — that heuristic silently corrupts data when prose contains\n * stray braces. Failing loudly at `JSON.parse` is safer.\n *\n * @example\n * extractJsonPayload('```json\\n{\"a\":1}\\n```');\n * // => '{\"a\":1}'\n *\n * @example\n * extractJsonPayload('Here you go:\\n```\\n{\"a\":1}\\n```\\nHope this helps.');\n * // => '{\"a\":1}'\n *\n * @example\n * extractJsonPayload('{\"a\":1}');\n * // => '{\"a\":1}'   (no fence → unchanged)\n */\nexport function extractJsonPayload(text: string): string {\n  const trimmed = text.trim();\n\n  const fenceMatch = trimmed.match(/```(?:json)?\\s*\\n?([\\s\\S]*?)\\n?```/);\n\n  if (fenceMatch) {\n    return fenceMatch[1].trim();\n  }\n\n  return trimmed;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,mBAAmB,MAAsB;CACvD,MAAM,UAAU,KAAK,KAAK;CAE1B,MAAM,aAAa,QAAQ,MAAM,oCAAoC;CAErE,IAAI,YACF,OAAO,WAAW,EAAE,CAAC,KAAK;CAG5B,OAAO;AACT"}

package/esm/ai/src/utils/generate-run-id.mjs

@@ -0,0 +1,23 @@
+//#region ../@warlock.js/ai/src/utils/generate-run-id.ts
+/**
+* Generates a stable, human-readable run id for any execution node
+* (tool invocation, agent run, workflow run, supervisor run). Format:
+* `${prefix}_${timestamp36}_${random36}` — compact, sortable by
+* prefix, collision-resistant within a run.
+*
+* Shared helper so every primitive emits the same id shape. The
+* prefix is conventionally the primitive kind (`"tool"`, `"agent"`,
+* `"workflow"`, `"sup"`) but callers can pass anything; the id is
+* purely for correlation, never parsed.
+*
+* @example
+* const runId = generateRunId("tool");
+* // → "tool_ld8x3m_7fq2j1kp"
+*/
+function generateRunId(prefix) {
+	return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+//#endregion
+export { generateRunId };
+//# sourceMappingURL=generate-run-id.mjs.map

package/esm/ai/src/utils/generate-run-id.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-run-id.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/utils/generate-run-id.ts"],"sourcesContent":["/**\n * Generates a stable, human-readable run id for any execution node\n * (tool invocation, agent run, workflow run, supervisor run). Format:\n * `${prefix}_${timestamp36}_${random36}` — compact, sortable by\n * prefix, collision-resistant within a run.\n *\n * Shared helper so every primitive emits the same id shape. The\n * prefix is conventionally the primitive kind (`\"tool\"`, `\"agent\"`,\n * `\"workflow\"`, `\"sup\"`) but callers can pass anything; the id is\n * purely for correlation, never parsed.\n *\n * @example\n * const runId = generateRunId(\"tool\");\n * // → \"tool_ld8x3m_7fq2j1kp\"\n */\nexport function generateRunId(prefix: string): string {\n  return `${prefix}_${Date.now().toString(36)}_${Math.random()\n    .toString(36)\n    .slice(2, 10)}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,SAAgB,cAAc,QAAwB;CACpD,OAAO,GAAG,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,GAAG,KAAK,OAAO,CAAC,CACzD,SAAS,EAAE,CAAC,CACZ,MAAM,GAAG,EAAE;AAChB"}

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