@warlock.js/ai 4.1.1

package/esm/tool/tool.mjs

@@ -0,0 +1,184 @@
+import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
+import { ToolExecutionError } from "../errors/tool-execution-error.mjs";
+import "../errors/index.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+
+//#region ../../@warlock.js/ai/src/tool/tool.ts
+/**
+* Degraded `ToolContext` supplied when no caller threads one through
+* (`tool.invoke(input)` standalone, batch scripts, tests). Per
+* decisions §35 — mutations on the empty bag are harmless no-ops;
+* production paths under a supervisor receive a real ctx with the
+* iteration's shared bag.
+*/
+function defaultToolContext() {
+	return { artifacts: {} };
+}
+const EMPTY_USAGE = Object.freeze({
+	input: 0,
+	output: 0,
+	total: 0
+});
+/**
+* Wraps a raw `ToolConfig` and adds a safe `invoke()` method for the agent runtime.
+* The returned object preserves all original contract fields unchanged.
+*
+* Error categorization:
+* - Input schema rejects model args → `SchemaValidationError` (issues preserved).
+* - Schema's `validate()` itself throws → `SchemaValidationError` wrapping the cause.
+* - `execute()` throws → `ToolExecutionError` wrapping the cause.
+*
+* @example
+* const weatherTool = tool({
+*   name: "getWeather",
+*   description: "Fetch current weather for a city",
+*   input: z.object({ city: z.string() }),
+*   execute: async ({ city }) => ({ temp: 72 }),
+* });
+*
+* const result = await weatherTool.invoke({ city: "Cairo" });
+*/
+/**
+* Internal factory for `asTool()` wrappers on composite primitives
+* (agent / workflow / supervisor). Unlike the public `tool()` factory
+* (which synthesizes a leaf `BaseReport` every time), this variant
+* lets the composite's own `ExecuteResult` flow through: the inner
+* primitive's `report` becomes the sole child of the outer tool-call
+* node, and the inner `usage` is surfaced so parents can roll it up.
+*
+* The caller supplies `execute()` returning `{ data, usage, report }`
+* from the composite's own `execute()` method. Validation failures
+* and thrown errors still produce a synthesized failed leaf report —
+* the inner-report propagation is strictly a success-path concern.
+*
+* Not exported from the package barrel — used by `agent.asTool()`,
+* `workflow.asTool()`, `supervisor.asTool()` only.
+*/
+function compositeAsTool(contract) {
+	const publicExecute = async (input) => {
+		const envelope = await contract.execute(input);
+		if (envelope.error) throw envelope.error;
+		return envelope.data;
+	};
+	return {
+		name: contract.name,
+		description: contract.description ?? `Composite tool "${contract.name}".`,
+		meta: contract.meta,
+		input: contract.input,
+		execute: publicExecute,
+		async invoke(rawInput, _ctx) {
+			const startedAtDate = /* @__PURE__ */ new Date();
+			const start = performance.now();
+			const runId = generateRunId("tool");
+			const failLeaf = (error) => {
+				const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+				const duration = performance.now() - start;
+				return {
+					error,
+					usage: EMPTY_USAGE,
+					report: {
+						runId,
+						rootRunId: runId,
+						name: contract.name,
+						version: contract.version,
+						type: "tool",
+						status: "failed",
+						startedAt: startedAtDate.toISOString(),
+						endedAt,
+						duration,
+						usage: EMPTY_USAGE,
+						children: []
+					}
+				};
+			};
+			let validationResult;
+			try {
+				validationResult = await contract.input["~standard"].validate(rawInput);
+			} catch (thrown) {
+				const message = thrown instanceof Error ? thrown.message : String(thrown);
+				return failLeaf(new SchemaValidationError(`Schema validation threw for tool "${contract.name}": ${message}`, {
+					cause: thrown,
+					context: { toolName: contract.name }
+				}));
+			}
+			if (validationResult.issues) return failLeaf(new SchemaValidationError(`Validation failed: ${validationResult.issues.map((issue) => issue.message).join("; ")}`, {
+				issues: validationResult.issues,
+				context: { toolName: contract.name }
+			}));
+			try {
+				const composite = await contract.execute(validationResult.value);
+				return {
+					data: composite.data,
+					error: composite.error,
+					usage: composite.usage,
+					report: composite.report
+				};
+			} catch (thrown) {
+				return failLeaf(new ToolExecutionError(thrown instanceof Error ? thrown.message : String(thrown), {
+					cause: thrown,
+					toolName: contract.name
+				}));
+			}
+		}
+	};
+}
+function tool(contract) {
+	return {
+		...contract,
+		async invoke(rawInput, ctx) {
+			const startedAtDate = /* @__PURE__ */ new Date();
+			const start = performance.now();
+			const runId = generateRunId("tool");
+			const handlerCtx = ctx ?? defaultToolContext();
+			const finish = (partial) => {
+				const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+				const duration = performance.now() - start;
+				const status = partial.error ? "failed" : "completed";
+				const report = {
+					runId,
+					rootRunId: runId,
+					name: contract.name,
+					version: contract.version,
+					type: "tool",
+					status,
+					startedAt: startedAtDate.toISOString(),
+					endedAt,
+					duration,
+					usage: EMPTY_USAGE,
+					children: []
+				};
+				return {
+					...partial,
+					usage: EMPTY_USAGE,
+					report
+				};
+			};
+			let validationResult;
+			try {
+				validationResult = await contract.input["~standard"].validate(rawInput);
+			} catch (thrown) {
+				const message = thrown instanceof Error ? thrown.message : String(thrown);
+				return finish({ error: new SchemaValidationError(`Schema validation threw for tool "${contract.name}": ${message}`, {
+					cause: thrown,
+					context: { toolName: contract.name }
+				}) });
+			}
+			if (validationResult.issues) return finish({ error: new SchemaValidationError(`Validation failed: ${validationResult.issues.map((issue) => issue.message).join("; ")}`, {
+				issues: validationResult.issues,
+				context: { toolName: contract.name }
+			}) });
+			try {
+				return finish({ data: await contract.execute(validationResult.value, handlerCtx) });
+			} catch (thrown) {
+				return finish({ error: new ToolExecutionError(thrown instanceof Error ? thrown.message : String(thrown), {
+					cause: thrown,
+					toolName: contract.name
+				}) });
+			}
+		}
+	};
+}
+
+//#endregion
+export { compositeAsTool, tool };
+//# sourceMappingURL=tool.mjs.map

package/esm/tool/tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/tool/tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type { ToolConfig, ToolContext } from \"../contracts/tool.contract\";\nimport { AIError, SchemaValidationError, ToolExecutionError } from \"../errors\";\nimport { generateRunId } from \"../utils/generate-run-id\";\n\n/**\n * Degraded `ToolContext` supplied when no caller threads one through\n * (`tool.invoke(input)` standalone, batch scripts, tests). Per\n * decisions §35 — mutations on the empty bag are harmless no-ops;\n * production paths under a supervisor receive a real ctx with the\n * iteration's shared bag.\n */\nfunction defaultToolContext(): ToolContext {\n  return { artifacts: {} };\n}\n\nconst EMPTY_USAGE: Usage = Object.freeze({ input: 0, output: 0, total: 0 });\n\n/**\n * Result returned by `ToolContract.invoke()`.\n *\n * **Canonical destructure:** `const { data, usage, report, error }` —\n * matches every other executable (`AgentResult`, `WorkflowResult`,\n * `SupervisorResult`) so parent agents can treat every tool dispatch\n * uniformly.\n *\n * **Shape.** `data` / `error` carry the outcome; `usage` and `report`\n * are always present. For leaf tools, `usage` is zero and `report`\n * is a framework-synthesized {@link BaseReport} (`type: \"tool\"`,\n * `children: []`, real timing) so parents never have to nil-check.\n * For composites wrapped via `asTool()`, `usage` and `report` mirror\n * the inner primitive's — the nested tree lives in `report.children`.\n *\n * @example\n * const result = await myTool.invoke({ city: \"Cairo\" });\n * if (result.error) console.error(result.error.message);\n * else console.log(result.data, result.report.duration);\n */\nexport type ToolInvokeResult<TOutput> = {\n  /** Successfully-returned output. Undefined if execution or validation failed. */\n  data?: TOutput;\n  /** Typed AI error produced by validation or execute(), if any. */\n  error?: AIError;\n  /** Rolled-up usage (zero for leaf tools, populated for composites). */\n  usage: Usage;\n  /** Recursive execution report — `report.children` carries nested executables. */\n  report: BaseReport;\n};\n\n/**\n * A `ToolConfig` augmented with a safe `invoke()` entry point for the agent runtime.\n *\n * @example\n * const wrapped: ToolContract<{ city: string }, { temp: number }> = tool(contract);\n * const result = await wrapped.invoke({ city: \"Cairo\" });\n */\nexport interface ToolContract<TInput = unknown, TOutput = unknown> extends ToolConfig<\n  TInput,\n  TOutput\n> {\n  /**\n   * Agent-runtime entry point. Validates raw input against the tool's schema,\n   * calls execute(), catches errors, and reports duration.\n   * Never throws — errors surface in the returned `error` field as\n   * typed `AIError` subclasses.\n   *\n   * The optional second argument is a `ToolContext` (Phase 5 /\n   * decisions §35) — when supplied, threaded into `execute(input, ctx)`\n   * so tools can write system-only side data into `ctx.artifacts`.\n   * Standalone callers may omit it; the framework supplies a\n   * degraded `{ artifacts: {} }` so single-arg legacy handlers keep\n   * working unchanged.\n   *\n   * @example\n   * const result = await myTool.invoke(rawLLMArgs);\n   * if (result.error) handleError(result.error);\n   */\n  invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>>;\n}\n\n/**\n * Wraps a raw `ToolConfig` and adds a safe `invoke()` method for the agent runtime.\n * The returned object preserves all original contract fields unchanged.\n *\n * Error categorization:\n * - Input schema rejects model args → `SchemaValidationError` (issues preserved).\n * - Schema's `validate()` itself throws → `SchemaValidationError` wrapping the cause.\n * - `execute()` throws → `ToolExecutionError` wrapping the cause.\n *\n * @example\n * const weatherTool = tool({\n *   name: \"getWeather\",\n *   description: \"Fetch current weather for a city\",\n *   input: z.object({ city: z.string() }),\n *   execute: async ({ city }) => ({ temp: 72 }),\n * });\n *\n * const result = await weatherTool.invoke({ city: \"Cairo\" });\n */\n/**\n * Internal factory for `asTool()` wrappers on composite primitives\n * (agent / workflow / supervisor). Unlike the public `tool()` factory\n * (which synthesizes a leaf `BaseReport` every time), this variant\n * lets the composite's own `ExecuteResult` flow through: the inner\n * primitive's `report` becomes the sole child of the outer tool-call\n * node, and the inner `usage` is surfaced so parents can roll it up.\n *\n * The caller supplies `execute()` returning `{ data, usage, report }`\n * from the composite's own `execute()` method. Validation failures\n * and thrown errors still produce a synthesized failed leaf report —\n * the inner-report propagation is strictly a success-path concern.\n *\n * Not exported from the package barrel — used by `agent.asTool()`,\n * `workflow.asTool()`, `supervisor.asTool()` only.\n */\nexport function compositeAsTool<TInput, TOutput>(contract: {\n  name: string;\n  description?: string;\n  version?: string;\n  meta?: ToolConfig[\"meta\"];\n  input: StandardSchemaV1<TInput>;\n  /** Runs the underlying composite and returns its full envelope. */\n  execute: (input: TInput) => Promise<{\n    data?: TOutput;\n    error?: AIError;\n    usage: Usage;\n    report: BaseReport;\n  }>;\n}): ToolContract<TInput, TOutput> {\n  // The underlying `ToolConfig<TInput, TOutput>.execute` is typed as\n  // `(input) => Promise<TOutput>`, but composite wrappers return an\n  // envelope object instead. Surface a contract-shaped view that\n  // extracts `.data` on demand for any code that still treats this\n  // like a plain tool.\n  const publicExecute = async (input: TInput): Promise<TOutput> => {\n    const envelope = await contract.execute(input);\n    if (envelope.error) throw envelope.error;\n    return envelope.data as TOutput;\n  };\n\n  return {\n    name: contract.name,\n    description: contract.description ?? `Composite tool \"${contract.name}\".`,\n    meta: contract.meta,\n    input: contract.input,\n    execute: publicExecute,\n\n    async invoke(rawInput: unknown, _ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>> {\n      // Composite tools (asTool-wrapped agent/workflow/supervisor) do\n      // NOT relay the ctx into their inner execution — composites\n      // have their own state/scope; an inner supervisor gets a fresh\n      // artifacts bag. The parameter is accepted for signature parity\n      // with `tool()` so callers can use both interchangeably.\n      const startedAtDate = new Date();\n      const start = performance.now();\n      const runId = generateRunId(\"tool\");\n\n      const failLeaf = (error: AIError): ToolInvokeResult<TOutput> => {\n        const endedAt = new Date().toISOString();\n        const duration = performance.now() - start;\n        return {\n          error,\n          usage: EMPTY_USAGE,\n          report: {\n            runId,\n            rootRunId: runId,\n            name: contract.name,\n            version: contract.version,\n            type: \"tool\",\n            status: \"failed\",\n            startedAt: startedAtDate.toISOString(),\n            endedAt,\n            duration,\n            usage: EMPTY_USAGE,\n            children: [],\n          },\n        };\n      };\n\n      let validationResult: StandardSchemaV1.Result<TInput>;\n      try {\n        const schema = contract.input as StandardSchemaV1<TInput>;\n        validationResult = await schema[\"~standard\"].validate(rawInput);\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n        return failLeaf(\n          new SchemaValidationError(\n            `Schema validation threw for tool \"${contract.name}\": ${message}`,\n            { cause: thrown, context: { toolName: contract.name } },\n          ),\n        );\n      }\n\n      if (validationResult.issues) {\n        const summary = validationResult.issues.map((issue) => issue.message).join(\"; \");\n        return failLeaf(\n          new SchemaValidationError(`Validation failed: ${summary}`, {\n            issues: validationResult.issues,\n            context: { toolName: contract.name },\n          }),\n        );\n      }\n\n      try {\n        const composite = await contract.execute(validationResult.value);\n        // Surface the inner primitive's full envelope. The outer\n        // ToolInvokeResult carries the composite's usage and report\n        // verbatim; the agent runtime nests the report as a child of\n        // the tool-dispatch node it records.\n        return {\n          data: composite.data,\n          error: composite.error,\n          usage: composite.usage,\n          report: composite.report,\n        };\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n        return failLeaf(\n          new ToolExecutionError(message, {\n            cause: thrown,\n            toolName: contract.name,\n          }),\n        );\n      }\n    },\n  };\n}\n\nexport function tool<TInput, TOutput>(\n  contract: ToolConfig<TInput, TOutput>,\n): ToolContract<TInput, TOutput> {\n  return {\n    ...contract,\n\n    async invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>> {\n      const startedAtDate = new Date();\n      const start = performance.now();\n      const runId = generateRunId(\"tool\");\n      const handlerCtx = ctx ?? defaultToolContext();\n\n      const finish = (partial: { data?: TOutput; error?: AIError }): ToolInvokeResult<TOutput> => {\n        const endedAt = new Date().toISOString();\n        const duration = performance.now() - start;\n        const status: BaseReport[\"status\"] = partial.error ? \"failed\" : \"completed\";\n        const report: BaseReport = {\n          runId,\n          rootRunId: runId,\n          name: contract.name,\n          version: contract.version,\n          type: \"tool\",\n          status,\n          startedAt: startedAtDate.toISOString(),\n          endedAt,\n          duration,\n          usage: EMPTY_USAGE,\n          children: [],\n        };\n\n        return {\n          ...partial,\n          usage: EMPTY_USAGE,\n          report,\n        };\n      };\n\n      let validationResult: StandardSchemaV1.Result<TInput>;\n      try {\n        const schema = contract.input as StandardSchemaV1<TInput>;\n        validationResult = await schema[\"~standard\"].validate(rawInput);\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n\n        return finish({\n          error: new SchemaValidationError(\n            `Schema validation threw for tool \"${contract.name}\": ${message}`,\n            { cause: thrown, context: { toolName: contract.name } },\n          ),\n        });\n      }\n\n      if (validationResult.issues) {\n        const summary = validationResult.issues.map((issue) => issue.message).join(\"; \");\n\n        return finish({\n          error: new SchemaValidationError(`Validation failed: ${summary}`, {\n            issues: validationResult.issues,\n            context: { toolName: contract.name },\n          }),\n        });\n      }\n\n      try {\n        const output = await contract.execute(validationResult.value, handlerCtx);\n        return finish({ data: output });\n      } catch (thrown) {\n        const message = thrown instanceof Error ? thrown.message : String(thrown);\n\n        return finish({\n          error: new ToolExecutionError(message, {\n            cause: thrown,\n            toolName: contract.name,\n          }),\n        });\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/esm/utils/compute-cost.d.mts

@@ -0,0 +1,58 @@
+import { ModelPricing } from "../contracts/result/model-pricing.type.mjs";
+import { Usage } from "../contracts/result/usage.type.mjs";
+
+//#region ../../@warlock.js/ai/src/utils/compute-cost.d.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,
+ * // }
+ */
+declare function computeCost(usage: Usage, pricing: ModelPricing | undefined): ModelPricing | undefined;
+/**
+ * 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").
+ */
+declare function accumulateCost(parent: ModelPricing | undefined, child: ModelPricing | undefined): ModelPricing | undefined;
+//#endregion
+export { accumulateCost, computeCost };
+//# sourceMappingURL=compute-cost.d.mts.map

package/esm/utils/compute-cost.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-cost.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/compute-cost.ts"],"mappings":";;;;;;AAuCA;;;;;;;;;;;;;;AAA0F;AAkC1F;;;;;;;;;;;;;;AAGe;;;;;iBArCC,WAAA,CAAY,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,YAAA,eAA2B,YAAA;;;;;;;;;;;;;;iBAkC9D,cAAA,CACd,MAAA,EAAQ,YAAA,cACR,KAAA,EAAO,YAAA,eACN,YAAA"}

package/esm/utils/compute-cost.mjs

@@ -0,0 +1,87 @@
+//#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);
+}
+
+//#endregion
+export { accumulateCost, computeCost };
+//# sourceMappingURL=compute-cost.mjs.map

package/esm/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"],"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"}

package/esm/utils/extract-json-payload.d.mts

@@ -0,0 +1,33 @@
+//#region ../../@warlock.js/ai/src/utils/extract-json-payload.d.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)
+ */
+declare function extractJsonPayload(text: string): string;
+//#endregion
+export { extractJsonPayload };
+//# sourceMappingURL=extract-json-payload.d.mts.map

package/esm/utils/extract-json-payload.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json-payload.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/extract-json-payload.ts"],"mappings":";;AA4BA;;;;AAA+C;;;;;;;;;;;;;;;;;;;;;;;iBAA/B,kBAAA,CAAmB,IAAY"}

package/esm/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/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,GAAG,KAAK;CAG5B,OAAO;AACT"}

package/esm/utils/generate-run-id.d.mts

@@ -0,0 +1,20 @@
+//#region ../../@warlock.js/ai/src/utils/generate-run-id.d.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"
+ */
+declare function generateRunId(prefix: string): string;
+//#endregion
+export { generateRunId };
+//# sourceMappingURL=generate-run-id.d.mts.map

package/esm/utils/generate-run-id.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-run-id.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/generate-run-id.ts"],"mappings":";;AAeA;;;;AAA4C;;;;;;;;;;iBAA5B,aAAA,CAAc,MAAc"}

package/esm/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/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,EAAE,SAAS,EAAE,EAAE,GAAG,KAAK,OAAO,EACxD,SAAS,EAAE,EACX,MAAM,GAAG,EAAE;AAChB"}

package/esm/utils/index.d.mts

@@ -0,0 +1,9 @@
+import { accumulateCost, computeCost } from "./compute-cost.mjs";
+import { extractJsonPayload } from "./extract-json-payload.mjs";
+import { generateRunId } from "./generate-run-id.mjs";
+import { extractJsonSchema } from "./json-schema.mjs";
+import { prepareAttachmentPart } from "./prepare-attachment-part.mjs";
+import { resolveAttachment } from "./resolve-attachment.mjs";
+import { safeJsonParse } from "./safe-json-parse.mjs";
+import { LineageStamp, stampReportLineage } from "./stamp-report-lineage.mjs";
+import { approximateTokenCount } from "./token-count.mjs";

package/esm/utils/index.mjs

@@ -0,0 +1,11 @@
+import { accumulateCost, computeCost } from "./compute-cost.mjs";
+import { extractJsonPayload } from "./extract-json-payload.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 { safeJsonParse } from "./safe-json-parse.mjs";
+import { stampReportLineage } from "./stamp-report-lineage.mjs";
+import { approximateTokenCount } from "./token-count.mjs";
+
+export {  };

package/esm/utils/json-schema.d.mts

@@ -0,0 +1,57 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/utils/json-schema.d.ts
+/**
+ * Supported JSON Schema output targets per the Standard JSON Schema V1
+ * spec. `openai-strict` is the richest for OpenAI structured outputs —
+ * every property listed in `required`, optionals expressed as
+ * `["T", "null"]`, `additionalProperties: false` everywhere. Other
+ * targets produce standards-compliant but looser output.
+ */
+type JsonSchemaTarget = "draft-2020-12" | "draft-07" | "openapi-3.0" | "openai-strict";
+/**
+ * Options for `extractJsonSchema`. `target` is forwarded to libraries that
+ * implement the Standard JSON Schema V1 spec (Seal, and any future lib
+ * that follows the spec). Libraries using their own top-level `.jsonSchema`
+ * / `._jsonSchema` property ignore the target.
+ */
+type ExtractJsonSchemaOptions = {
+  target?: JsonSchemaTarget | (string & {});
+};
+/**
+ * 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" });
+ */
+declare function extractJsonSchema(schema: StandardSchemaV1<unknown> | undefined, options?: ExtractJsonSchemaOptions): Record<string, unknown> | undefined;
+//#endregion
+export { extractJsonSchema };
+//# sourceMappingURL=json-schema.d.mts.map

package/esm/utils/json-schema.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/utils/json-schema.ts"],"mappings":";;;;;AASA;;;;AAA4B;KAAhB,gBAAA;;;;AASe;AAoC3B;;KArCY,wBAAA;EACV,MAAA,GAAS,gBAAgB;AAAA;;;;;;;;;;AAuClB;;;;;;;;;;;;;;;;;;;;;;;;iBAHO,iBAAA,CACd,MAAA,EAAQ,gBAAA,uBACR,OAAA,GAAS,wBAAA,GACR,MAAA"}