@warlock.js/core 4.7.0 → 4.8.1

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

@@ -1,185 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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/transcribe/audio-input.mjs

@@ -1,84 +0,0 @@
-import { basename, extname } from "node:path";
-import { readFile } from "node:fs/promises";
-
-//#region ../@warlock.js/ai/src/transcribe/audio-input.ts
-/**
-* File-extension → IANA audio media type map covering the formats the
-* common STT providers accept — including the **WhatsApp voice-note**
-* formats (`.ogg` / `.opus`, Opus-in-Ogg on Android; `.m4a` on iOS).
-*/
-const AUDIO_MEDIA_TYPES = {
-	".mp3": "audio/mpeg",
-	".mpeg": "audio/mpeg",
-	".mpga": "audio/mpeg",
-	".m4a": "audio/mp4",
-	".mp4": "audio/mp4",
-	".wav": "audio/wav",
-	".webm": "audio/webm",
-	".weba": "audio/webm",
-	".ogg": "audio/ogg",
-	".oga": "audio/ogg",
-	".opus": "audio/ogg",
-	".flac": "audio/flac",
-	".aac": "audio/aac"
-};
-/**
-* Resolve the audio media type from a filename's extension, or
-* `undefined` when the extension is unknown. Case-insensitive.
-*
-* @example
-* audioMediaTypeForFilename("voice-note.opus"); // "audio/ogg"
-*/
-function audioMediaTypeForFilename(filename) {
-	return AUDIO_MEDIA_TYPES[extname(filename).toLowerCase()];
-}
-/**
-* Package raw audio bytes as an {@link AudioInput} for `ai.transcribe()`.
-* Pure plumbing — no AI, no I/O. Use when you already hold the bytes
-* (an upload buffer, a downloaded blob).
-*
-* @example
-* const audio = audioFromBuffer(uploadBuffer, "audio/ogg", "note.ogg");
-* const { data } = await ai.transcribe({ model: openai.transcribe({ name: "whisper-1" }), audio });
-*/
-function audioFromBuffer(data, mediaType, filename) {
-	return {
-		base64: Buffer.from(data).toString("base64"),
-		mediaType,
-		...filename ? { filename } : {}
-	};
-}
-/**
-* Read an audio file from disk and package it as an {@link AudioInput}
-* for `ai.transcribe()` — the one-line bridge from a file on disk
-* (WhatsApp `.ogg`/`.opus`, a meeting `.m4a`, a `.wav`) to the
-* transcription verb. **Pure utility — no AI here**; the actual text
-* extraction is the AI step (`ai.transcribe`).
-*
-* The media type is inferred from the file extension (override via
-* `options.mediaType` for extensionless or mislabeled files).
-*
-* @example
-* // WhatsApp voice note → text, end to end:
-* const audio = await audioFromFile("./voice-note.ogg");
-* const { data, error } = await ai.transcribe({
-*   model: openai.transcribe({ name: "whisper-1" }),
-*   audio,
-*   language: "en",
-* });
-* if (!error) console.log(data.text);
-*/
-async function audioFromFile(filePath, options) {
-	const buffer = await readFile(filePath);
-	const filename = basename(filePath);
-	const mediaType = options?.mediaType ?? audioMediaTypeForFilename(filename) ?? "audio/mpeg";
-	return {
-		base64: buffer.toString("base64"),
-		mediaType,
-		filename
-	};
-}
-
-//#endregion
-export { audioFromBuffer, audioFromFile, audioMediaTypeForFilename };
-//# sourceMappingURL=audio-input.mjs.map

package/esm/ai/src/transcribe/audio-input.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"audio-input.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/transcribe/audio-input.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { basename, extname } from \"node:path\";\nimport type { AudioInput } from \"../contracts/transcription-model.contract\";\n\n/**\n * File-extension → IANA audio media type map covering the formats the\n * common STT providers accept — including the **WhatsApp voice-note**\n * formats (`.ogg` / `.opus`, Opus-in-Ogg on Android; `.m4a` on iOS).\n */\nconst AUDIO_MEDIA_TYPES: Record<string, string> = {\n  \".mp3\": \"audio/mpeg\",\n  \".mpeg\": \"audio/mpeg\",\n  \".mpga\": \"audio/mpeg\",\n  \".m4a\": \"audio/mp4\",\n  \".mp4\": \"audio/mp4\",\n  \".wav\": \"audio/wav\",\n  \".webm\": \"audio/webm\",\n  \".weba\": \"audio/webm\",\n  \".ogg\": \"audio/ogg\",\n  \".oga\": \"audio/ogg\",\n  \".opus\": \"audio/ogg\",\n  \".flac\": \"audio/flac\",\n  \".aac\": \"audio/aac\",\n};\n\n/**\n * Resolve the audio media type from a filename's extension, or\n * `undefined` when the extension is unknown. Case-insensitive.\n *\n * @example\n * audioMediaTypeForFilename(\"voice-note.opus\"); // \"audio/ogg\"\n */\nexport function audioMediaTypeForFilename(filename: string): string | undefined {\n  return AUDIO_MEDIA_TYPES[extname(filename).toLowerCase()];\n}\n\n/**\n * Package raw audio bytes as an {@link AudioInput} for `ai.transcribe()`.\n * Pure plumbing — no AI, no I/O. Use when you already hold the bytes\n * (an upload buffer, a downloaded blob).\n *\n * @example\n * const audio = audioFromBuffer(uploadBuffer, \"audio/ogg\", \"note.ogg\");\n * const { data } = await ai.transcribe({ model: openai.transcribe({ name: \"whisper-1\" }), audio });\n */\nexport function audioFromBuffer(\n  data: Uint8Array,\n  mediaType: string,\n  filename?: string,\n): AudioInput {\n  return {\n    base64: Buffer.from(data).toString(\"base64\"),\n    mediaType,\n    ...(filename ? { filename } : {}),\n  };\n}\n\n/**\n * Read an audio file from disk and package it as an {@link AudioInput}\n * for `ai.transcribe()` — the one-line bridge from a file on disk\n * (WhatsApp `.ogg`/`.opus`, a meeting `.m4a`, a `.wav`) to the\n * transcription verb. **Pure utility — no AI here**; the actual text\n * extraction is the AI step (`ai.transcribe`).\n *\n * The media type is inferred from the file extension (override via\n * `options.mediaType` for extensionless or mislabeled files).\n *\n * @example\n * // WhatsApp voice note → text, end to end:\n * const audio = await audioFromFile(\"./voice-note.ogg\");\n * const { data, error } = await ai.transcribe({\n *   model: openai.transcribe({ name: \"whisper-1\" }),\n *   audio,\n *   language: \"en\",\n * });\n * if (!error) console.log(data.text);\n */\nexport async function audioFromFile(\n  filePath: string,\n  options?: { mediaType?: string },\n): Promise<AudioInput> {\n  const buffer = await readFile(filePath);\n  const filename = basename(filePath);\n  const mediaType = options?.mediaType ?? audioMediaTypeForFilename(filename) ?? \"audio/mpeg\";\n\n  return { base64: buffer.toString(\"base64\"), mediaType, filename };\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,oBAA4C;CAChD,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;CACR,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;AACV;;;;;;;;AASA,SAAgB,0BAA0B,UAAsC;CAC9E,OAAO,kBAAkB,QAAQ,QAAQ,CAAC,CAAC,YAAY;AACzD;;;;;;;;;;AAWA,SAAgB,gBACd,MACA,WACA,UACY;CACZ,OAAO;EACL,QAAQ,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,QAAQ;EAC3C;EACA,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;CACjC;AACF;;;;;;;;;;;;;;;;;;;;;AAsBA,eAAsB,cACpB,UACA,SACqB;CACrB,MAAM,SAAS,MAAM,SAAS,QAAQ;CACtC,MAAM,WAAW,SAAS,QAAQ;CAClC,MAAM,YAAY,SAAS,aAAa,0BAA0B,QAAQ,KAAK;CAE/E,OAAO;EAAE,QAAQ,OAAO,SAAS,QAAQ;EAAG;EAAW;CAAS;AAClE"}

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

@@ -1,4 +0,0 @@
-import { audioFromBuffer, audioFromFile, audioMediaTypeForFilename } from "./audio-input.mjs";
-import { transcribe } from "./transcribe.mjs";
-
-export {  };

package/esm/ai/src/transcribe/transcribe.mjs

@@ -1,127 +0,0 @@
-import { AIError } from "../errors/ai-error.mjs";
-import { ProviderError } from "../errors/provider-error.mjs";
-import { computeCost } from "../utils/compute-cost.mjs";
-import { generateRunId } from "../utils/generate-run-id.mjs";
-import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
-import { notifyObservers } from "../observe/resolve-observers.mjs";
-
-//#region ../@warlock.js/ai/src/transcribe/transcribe.ts
-/**
-* Transcribe audio to text — the speech-to-text verb of the
-* output-modality track (Theme I), inverse of `ai.speech()`. Wraps a
-* {@link TranscriptionModelContract} (from `openai.transcribe(...)`) in
-* the uniform result contract:
-*
-* - **Never throws.** Provider failures surface as a typed `AIError` on
-*   `result.error`.
-* - **Cost-truth.** `result.usage.cost` is filled per-minute
-*   (`whisper-1`) or per-token (`gpt-4o-transcribe`).
-* - **Observable.** The completed {@link TranscriptionReport} routes to
-*   any registered `Observer` via the `observe` seam.
-*
-* @example
-* const openai = new OpenAISDK({ apiKey });
-* const { data, error } = await ai.transcribe({
-*   model: openai.transcribe({ name: "whisper-1" }),
-*   audio: { base64, mediaType: "audio/mpeg", filename: "voicemail.mp3" },
-*   language: "en",
-* });
-* if (!error) console.log(data.text);
-*/
-async function transcribe(params) {
-	const { model, audio } = params;
-	const runId = generateRunId("transcription");
-	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-	const startPerf = performance.now();
-	const usage = {
-		input: 0,
-		output: 0,
-		total: 0
-	};
-	let data;
-	let error;
-	let status = "completed";
-	let durationSeconds;
-	try {
-		const response = await model.transcribe(audio, {
-			language: params.language,
-			prompt: params.prompt,
-			format: params.format,
-			signal: params.signal,
-			...params.options
-		});
-		Object.assign(usage, response.usage);
-		durationSeconds = response.durationSeconds;
-		if (usage.cost === void 0) {
-			const cost = computeTranscriptionCost(usage, durationSeconds, model.pricing);
-			if (cost !== void 0) usage.cost = cost;
-		}
-		data = {
-			text: response.text,
-			...response.segments ? { segments: response.segments } : {}
-		};
-	} catch (thrown) {
-		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
-		status = params.signal?.aborted ? "cancelled" : "failed";
-	}
-	const report = {
-		runId,
-		rootRunId: runId,
-		name: params.name ?? "transcription",
-		type: "transcription",
-		status,
-		error,
-		startedAt,
-		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		duration: performance.now() - startPerf,
-		usage,
-		children: [],
-		model: {
-			name: model.name,
-			provider: model.provider
-		},
-		...durationSeconds !== void 0 ? { durationSeconds } : {},
-		reportSchemaVersion: 1
-	};
-	stampReportLineage(report, {
-		rootRunId: runId,
-		sessionId: params.sessionId
-	});
-	await notifyObservers(params.observe, report);
-	return {
-		type: "transcription",
-		data,
-		error,
-		usage,
-		report
-	};
-}
-/**
-* Price an STT run: `perMinute × (durationSeconds / 60)` (per-minute
-* metering, attributed to `cost.input`) wins when configured, otherwise
-* the standard token math. Returns `undefined` when no usable pricing
-* is present (e.g. per-minute pricing but the provider didn't report a
-* duration).
-*/
-function computeTranscriptionCost(usage, durationSeconds, pricing) {
-	if (!pricing) return;
-	if (pricing.perMinute !== void 0) {
-		if (durationSeconds === void 0) return;
-		return {
-			input: durationSeconds / 60 * pricing.perMinute,
-			output: 0
-		};
-	}
-	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
-		input: pricing.input,
-		output: pricing.output
-	});
-}
-/** Best-effort message for a non-`AIError` thrown value. */
-function toMessage(thrown) {
-	return thrown instanceof Error ? thrown.message : String(thrown);
-}
-
-//#endregion
-export { transcribe };
-//# sourceMappingURL=transcribe.mjs.map

package/esm/ai/src/transcribe/transcribe.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"transcribe.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/transcribe/transcribe.ts"],"sourcesContent":["import type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type {\n  AudioInput,\n  TranscriptionModelContract,\n  TranscriptionModelPricing,\n  TranscriptionSegment,\n} from \"../contracts/transcription-model.contract\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { computeCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\n\n/** Parameters for {@link transcribe}. `model` comes from `sdk.transcribe({ name })`. */\nexport type TranscribeParams = {\n  /** The STT model to transcribe with. */\n  model: TranscriptionModelContract;\n  /** The audio to transcribe (inlined base64 bytes + media type). */\n  audio: AudioInput;\n  /** BCP-47 language hint. */\n  language?: string;\n  /** Optional priming prompt (spelling/style hints). */\n  prompt?: string;\n  /** Provider response-format override (e.g. `\"verbose_json\"`). */\n  format?: string;\n  /** Cancellation handle. */\n  signal?: AbortSignal;\n  /** Observability routing — same `observe` seam as agents. */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"transcription\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of a {@link transcribe} run. */\nexport type TranscriptionData = {\n  /** The full transcript text. */\n  text: string;\n  /** Timestamped segments when the provider returned them. */\n  segments?: TranscriptionSegment[];\n};\n\n/** The report node a {@link transcribe} run produces (`type: \"transcription\"`). */\nexport type TranscriptionReport = BaseReport & {\n  type: \"transcription\";\n  /** Identity of the STT model this run used. */\n  model: { name: string; provider: string };\n  /** Input audio duration in seconds, when the provider reported it. */\n  durationSeconds?: number;\n};\n\n/** Result envelope of {@link transcribe} — the uniform `{ data, error, usage, report }`. */\nexport type TranscriptionResult = ExecuteResult<TranscriptionData> & {\n  type: \"transcription\";\n  report: TranscriptionReport;\n};\n\n/**\n * Transcribe audio to text — the speech-to-text verb of the\n * output-modality track (Theme I), inverse of `ai.speech()`. Wraps a\n * {@link TranscriptionModelContract} (from `openai.transcribe(...)`) in\n * the uniform result contract:\n *\n * - **Never throws.** Provider failures surface as a typed `AIError` on\n *   `result.error`.\n * - **Cost-truth.** `result.usage.cost` is filled per-minute\n *   (`whisper-1`) or per-token (`gpt-4o-transcribe`).\n * - **Observable.** The completed {@link TranscriptionReport} routes to\n *   any registered `Observer` via the `observe` seam.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error } = await ai.transcribe({\n *   model: openai.transcribe({ name: \"whisper-1\" }),\n *   audio: { base64, mediaType: \"audio/mpeg\", filename: \"voicemail.mp3\" },\n *   language: \"en\",\n * });\n * if (!error) console.log(data.text);\n */\nexport async function transcribe(params: TranscribeParams): Promise<TranscriptionResult> {\n  const { model, audio } = params;\n\n  const runId = generateRunId(\"transcription\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: TranscriptionData | undefined;\n  let error: AIError | undefined;\n  let status: TranscriptionReport[\"status\"] = \"completed\";\n  let durationSeconds: number | undefined;\n\n  try {\n    const response = await model.transcribe(audio, {\n      language: params.language,\n      prompt: params.prompt,\n      format: params.format,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    Object.assign(usage, response.usage);\n    durationSeconds = response.durationSeconds;\n\n    if (usage.cost === undefined) {\n      const cost = computeTranscriptionCost(usage, durationSeconds, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { text: response.text, ...(response.segments ? { segments: response.segments } : {}) };\n  } catch (thrown) {\n    error =\n      thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: TranscriptionReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"transcription\",\n    type: \"transcription\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    ...(durationSeconds !== undefined ? { durationSeconds } : {}),\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"transcription\", data, error, usage, report };\n}\n\n/**\n * Price an STT run: `perMinute × (durationSeconds / 60)` (per-minute\n * metering, attributed to `cost.input`) wins when configured, otherwise\n * the standard token math. Returns `undefined` when no usable pricing\n * is present (e.g. per-minute pricing but the provider didn't report a\n * duration).\n */\nfunction computeTranscriptionCost(\n  usage: Usage,\n  durationSeconds: number | undefined,\n  pricing: TranscriptionModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  if (pricing.perMinute !== undefined) {\n    if (durationSeconds === undefined) {\n      return undefined;\n    }\n    return { input: (durationSeconds / 60) * pricing.perMinute, output: 0 };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,eAAsB,WAAW,QAAwD;CACvF,MAAM,EAAE,OAAO,UAAU;CAEzB,MAAM,QAAQ,cAAc,eAAe;CAC3C,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAwC;CAC5C,IAAI;CAEJ,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,WAAW,OAAO;GAC7C,UAAU,OAAO;GACjB,QAAQ,OAAO;GACf,QAAQ,OAAO;GACf,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,KAAK;EACnC,kBAAkB,SAAS;EAE3B,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,yBAAyB,OAAO,iBAAiB,MAAM,OAAO;GAC3E,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO;GAAE,MAAM,SAAS;GAAM,GAAI,SAAS,WAAW,EAAE,UAAU,SAAS,SAAS,IAAI,CAAC;EAAG;CAC9F,SAAS,QAAQ;EACf,QACE,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAC7F,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAA8B;EAClC;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD,GAAI,oBAAoB,SAAY,EAAE,gBAAgB,IAAI,CAAC;EAC3D;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAiB;EAAM;EAAO;EAAO;CAAO;AAC7D;;;;;;;;AASA,SAAS,yBACP,OACA,iBACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAGF,IAAI,QAAQ,cAAc,QAAW;EACnC,IAAI,oBAAoB,QACtB;EAEF,OAAO;GAAE,OAAQ,kBAAkB,KAAM,QAAQ;GAAW,QAAQ;EAAE;CACxE;CAEA,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}

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

@@ -1,112 +0,0 @@
-//#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

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