@warlock.js/core 4.4.0 → 4.5.0

package/esm/ai/src/tool/executable-as-tool.mjs

@@ -0,0 +1,81 @@
+import { AgentExecutionError } from "../errors/agent-execution-error.mjs";
+import "../errors/index.mjs";
+import { compositeAsTool } from "./tool.mjs";
+
+//#region ../@warlock.js/ai/src/tool/executable-as-tool.ts
+/**
+* Identity passthrough schema used when an executable is registered as
+* a tool without declaring an `inputSchema`. The model's raw arguments
+* flow straight to `execute()` unchanged — the executable validates
+* internally (workflows via their steps, supervisors/agents via their
+* own input handling).
+*/
+function passthroughSchema() {
+	return { "~standard": {
+		version: 1,
+		vendor: "warlock-ai",
+		validate: (value) => ({ value })
+	} };
+}
+/**
+* Type guard distinguishing a raw executable primitive from a built
+* `ToolContract`. An executable exposes `execute()` and no `invoke()`;
+* a `ToolContract` exposes `invoke()`. The `invoke` check is the
+* load-bearing discriminator — `.asTool()`-wrapped composites keep
+* their own `execute` too, so checking `execute` alone is insufficient.
+*/
+function isExecutableTool(entry) {
+	if (!entry || typeof entry !== "object") return false;
+	const candidate = entry;
+	return typeof candidate.execute === "function" && typeof candidate.invoke !== "function";
+}
+/**
+* Adapt a raw executable primitive (agent / workflow / supervisor) into
+* a `ToolContract` so an agent can dispatch it inside its tool-call
+* loop WITHOUT the caller writing `.asTool()`. Derives the LLM tool
+* manifest from the executable's own `name` + `description` +
+* (optional) `inputSchema`, then dispatches through the executable's
+* `execute()` — the inner report nests under the outer tool-call node
+* exactly like an explicit `.asTool()` wrapper.
+*
+* Throws `AgentExecutionError` at author time when the executable lacks
+* a usable `name` — the agent's tool surface needs a stable id, the
+* same constraint `.asTool()` enforces.
+*/
+function executableToTool(executable) {
+	if (!executable.name || typeof executable.name !== "string") throw new AgentExecutionError("tools[]: an executable (agent/workflow/supervisor) used as a tool must have a `name`", { context: { authoring: true } });
+	return compositeAsTool({
+		name: executable.name,
+		description: executable.description ?? `Invoke "${executable.name}" as a tool.`,
+		input: executable.inputSchema ?? passthroughSchema(),
+		execute: async (input, ctx) => {
+			const result = await executable.execute(input, ctx?.signal ? { signal: ctx.signal } : void 0);
+			if (result.error) throw result.error;
+			return {
+				data: result.data,
+				usage: result.usage,
+				report: result.report
+			};
+		}
+	});
+}
+/**
+* Normalize an agent's `tools: []` array into a uniform
+* `ToolContract[]` for the runtime. Already-built `ToolContract`s
+* (`.asTool()` / `ai.tool()`) pass through untouched; raw executable
+* primitives are auto-adapted via {@link executableToTool}.
+*
+* Returns `undefined` when no tools were supplied so the agent's
+* existing `config.tools ?? []` fallbacks stay byte-identical.
+*/
+function normalizeAgentTools(tools) {
+	if (!tools) return;
+	return tools.map((entry) => {
+		if (isExecutableTool(entry)) return executableToTool(entry);
+		return entry;
+	});
+}
+
+//#endregion
+export { executableToTool, isExecutableTool, normalizeAgentTools };
+//# sourceMappingURL=executable-as-tool.mjs.map

package/esm/ai/src/tool/executable-as-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable-as-tool.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/tool/executable-as-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AgentExecutionError, type AIError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"./tool\";\n\n/**\n * Envelope every executable's `execute()` resolves to. Agent, workflow,\n * and supervisor results all satisfy this shape — `data` / `error`\n * carry the outcome while `usage` and `report` are always present —\n * which is exactly what {@link compositeAsTool} needs to nest the inner\n * run under the outer tool-call node.\n */\ntype ExecutableEnvelope<TOutput> = BaseResult & {\n  data?: TOutput;\n  error?: AIError;\n  report: BaseReport;\n};\n\n/**\n * Structural view of an executable primitive (agent / workflow /\n * supervisor) when it is dropped straight into an agent's `tools: []`\n * array WITHOUT being wrapped via `.asTool()` first.\n *\n * Only the fields the auto-adapt path reads are declared:\n * - `name` — becomes the LLM tool name (required; anonymous executables\n *   are rejected at author time, mirroring `.asTool()`).\n * - `description` — the \"when would the model pick this?\" line.\n * - `inputSchema` — opt-in Standard Schema typing the tool's arguments.\n *   Surfaced on `WorkflowInstance` / `SupervisorContract` from the new\n *   optional `inputSchema` config field. Absent for agents (which take\n *   a plain string prompt).\n * - `execute` — the dispatch entry every `ExecutableContract` exposes.\n *\n * `invoke` is declared `never` so a `ToolContract` (which HAS `invoke`)\n * can never be mistaken for an executable by the {@link isExecutableTool}\n * guard.\n */\nexport type ExecutableTool<TInput = unknown, TOutput = unknown> = {\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: StandardSchemaV1<TInput>;\n  execute(input: TInput, options?: unknown): Promise<ExecutableEnvelope<TOutput>>;\n  invoke?: never;\n};\n\n/**\n * Entry accepted in an agent's `tools: []` array — either an already-\n * built `ToolContract` (the `.asTool()` / `ai.tool()` path) or a raw\n * executable primitive the framework auto-adapts on the caller's\n * behalf.\n */\nexport type AgentToolEntry<TInput = unknown, TOutput = unknown> =\n  | ToolContract<TInput, TOutput>\n  | ExecutableTool<TInput, TOutput>;\n\n/**\n * Identity passthrough schema used when an executable is registered as\n * a tool without declaring an `inputSchema`. The model's raw arguments\n * flow straight to `execute()` unchanged — the executable validates\n * internally (workflows via their steps, supervisors/agents via their\n * own input handling).\n */\nfunction passthroughSchema<TInput>(): StandardSchemaV1<TInput> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-ai\",\n      validate: (value: unknown) => ({ value: value as TInput }),\n    },\n  };\n}\n\n/**\n * Type guard distinguishing a raw executable primitive from a built\n * `ToolContract`. An executable exposes `execute()` and no `invoke()`;\n * a `ToolContract` exposes `invoke()`. The `invoke` check is the\n * load-bearing discriminator — `.asTool()`-wrapped composites keep\n * their own `execute` too, so checking `execute` alone is insufficient.\n */\nexport function isExecutableTool(entry: unknown): entry is ExecutableTool {\n  if (!entry || typeof entry !== \"object\") {\n    return false;\n  }\n\n  const candidate = entry as { execute?: unknown; invoke?: unknown };\n\n  return typeof candidate.execute === \"function\" && typeof candidate.invoke !== \"function\";\n}\n\n/**\n * Adapt a raw executable primitive (agent / workflow / supervisor) into\n * a `ToolContract` so an agent can dispatch it inside its tool-call\n * loop WITHOUT the caller writing `.asTool()`. Derives the LLM tool\n * manifest from the executable's own `name` + `description` +\n * (optional) `inputSchema`, then dispatches through the executable's\n * `execute()` — the inner report nests under the outer tool-call node\n * exactly like an explicit `.asTool()` wrapper.\n *\n * Throws `AgentExecutionError` at author time when the executable lacks\n * a usable `name` — the agent's tool surface needs a stable id, the\n * same constraint `.asTool()` enforces.\n */\nexport function executableToTool<TInput, TOutput>(\n  executable: ExecutableTool<TInput, TOutput>,\n): ToolContract<TInput, TOutput> {\n  if (!executable.name || typeof executable.name !== \"string\") {\n    throw new AgentExecutionError(\n      \"tools[]: an executable (agent/workflow/supervisor) used as a tool must have a `name`\",\n      { context: { authoring: true } },\n    );\n  }\n\n  return compositeAsTool<TInput, TOutput>({\n    name: executable.name,\n    description: executable.description ?? `Invoke \"${executable.name}\" as a tool.`,\n    input: executable.inputSchema ?? passthroughSchema<TInput>(),\n    execute: async (input, ctx) => {\n      // Relay the outer run's cancellation signal so a cancelled parent\n      // aborts this nested agent/workflow/supervisor (C2). Omit the\n      // options object entirely when there's no signal so primitives that\n      // treat any second arg as meaningful stay byte-identical.\n      const result = await executable.execute(\n        input,\n        ctx?.signal ? { signal: ctx.signal } : undefined,\n      );\n\n      if (result.error) {\n        // Surface the inner typed error so the surrounding\n        // `compositeAsTool` wrapper produces a `ToolExecutionError`\n        // with `cause` pointing back at the original subclass — the\n        // agent's tool-call loop sees one uniform error class\n        // regardless of which primitive failed.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage as Usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Normalize an agent's `tools: []` array into a uniform\n * `ToolContract[]` for the runtime. Already-built `ToolContract`s\n * (`.asTool()` / `ai.tool()`) pass through untouched; raw executable\n * primitives are auto-adapted via {@link executableToTool}.\n *\n * Returns `undefined` when no tools were supplied so the agent's\n * existing `config.tools ?? []` fallbacks stay byte-identical.\n */\nexport function normalizeAgentTools(\n  tools: ReadonlyArray<AgentToolEntry> | undefined,\n): ToolContract<unknown, unknown>[] | undefined {\n  if (!tools) {\n    return undefined;\n  }\n\n  return tools.map((entry) => {\n    if (isExecutableTool(entry)) {\n      return executableToTool(entry) as ToolContract<unknown, unknown>;\n    }\n\n    return entry as ToolContract<unknown, unknown>;\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAgEA,SAAS,oBAAsD;CAC7D,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;CAC1D,EACF;AACF;;;;;;;;AASA,SAAgB,iBAAiB,OAAyC;CACxE,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,OAAO,UAAU,YAAY,cAAc,OAAO,UAAU,WAAW;AAChF;;;;;;;;;;;;;;AAeA,SAAgB,iBACd,YAC+B;CAC/B,IAAI,CAAC,WAAW,QAAQ,OAAO,WAAW,SAAS,UACjD,MAAM,IAAI,oBACR,wFACA,EAAE,SAAS,EAAE,WAAW,KAAK,EAAE,CACjC;CAGF,OAAO,gBAAiC;EACtC,MAAM,WAAW;EACjB,aAAa,WAAW,eAAe,WAAW,WAAW,KAAK;EAClE,OAAO,WAAW,eAAe,kBAA0B;EAC3D,SAAS,OAAO,OAAO,QAAQ;GAK7B,MAAM,SAAS,MAAM,WAAW,QAC9B,OACA,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MACzC;GAEA,IAAI,OAAO,OAMT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;;;;;;AAWA,SAAgB,oBACd,OAC8C;CAC9C,IAAI,CAAC,OACH;CAGF,OAAO,MAAM,KAAK,UAAU;EAC1B,IAAI,iBAAiB,KAAK,GACxB,OAAO,iBAAiB,KAAK;EAG/B,OAAO;CACT,CAAC;AACH"}

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

@@ -0,0 +1,4 @@
+import { tool } from "./tool.mjs";
+import { executableToTool, isExecutableTool, normalizeAgentTools } from "./executable-as-tool.mjs";
+
+export {  };

package/esm/ai/src/tool/tool.mjs

@@ -0,0 +1,185 @@
+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, ctx);
+				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;
+			if (contract.input) 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 }
+				}) });
+			}
+			else validationResult = { value: rawInput };
+			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/ai/src/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  /**\n   * Runs the underlying composite and returns its full envelope. The\n   * optional `ctx` relays the outer run's cancellation `signal` so a\n   * cancelled parent aborts the nested primitive instead of letting it\n   * outlive the cancellation (C2).\n   */\n  execute: (input: TInput, ctx?: ToolContext) => 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) run in\n      // their own state/scope — the ctx's `artifacts` bag is NOT shared\n      // into the inner primitive (an inner supervisor gets a fresh bag).\n      // The cancellation `signal`, however, IS relayed (below, into\n      // `contract.execute`) so a cancelled outer run aborts the nested\n      // primitive instead of letting it outlive the cancellation (C2).\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, ctx);\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      if (contract.input) {\n        try {\n          validationResult = await contract.input[\"~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      } else {\n        // `input` is optional on ToolConfig — this is a no-argument tool\n        // (e.g. view_cart, checkout). With no schema there is nothing to\n        // validate, so pass the raw model args straight to execute()\n        // instead of dereferencing a missing schema's `~standard`.\n        validationResult = { value: rawInput as TInput };\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/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"}