@offerpilot/axiomruntime 0.0.3 → 0.0.5

package/dist/core/images/image-generation-service.js

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isProviderCircuitOpen, readCache, recordProviderRuntimeFailure, recordProviderRuntimeSuccess } from "../config/cache-store.js";
+import { readProviders } from "../config/providers-store.js";
+import { writeLog } from "../logs/log-service.js";
+import { startOpenAiUsageProxy } from "../runner/openai-usage-proxy.js";
+import { isRecord } from "../utils/is-record.js";
+const IMAGE_REQUEST_TIMEOUT_MS = 120_000;
+const MAX_IMAGE_RESPONSE_BYTES = 32 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+export async function resolveImageProviderCandidates(selection) {
+    const target = typeof selection === "string" ? selection.trim() : "";
+    let providerName = typeof selection === "string" ? "" : selection.providerName?.trim() ?? "";
+    let requestedModel = typeof selection === "string" ? "" : selection.model?.trim() ?? "";
+    if (!target && !providerName && !requestedModel)
+        throw new Error("Image provider or model is required.");
+    const [providers, cache] = await Promise.all([readProviders(), readCache()]);
+    if (!providers.length) {
+        throw new Error("No providers configured. Run `ai add` first.");
+    }
+    if (target) {
+        const targetProvider = providers.find((provider) => provider.name === target);
+        if (targetProvider)
+            providerName = targetProvider.name;
+        else
+            requestedModel = target;
+    }
+    const preferredProvider = providerName ? providers.find((provider) => provider.name === providerName) : undefined;
+    if (providerName && !preferredProvider) {
+        throw new Error(`Provider not found: ${providerName}`);
+    }
+    const targetModel = requestedModel || preferredProvider?.model.trim() || "";
+    if (!targetModel) {
+        throw new Error(`Provider ${providerName} has no default image model. Configure its model first.`);
+    }
+    const candidates = providers.flatMap((provider) => {
+        const cached = cache.providers[provider.name];
+        if (isProviderCircuitOpen(cached))
+            return [];
+        if (cached?.status === "error" && !cached.circuitOpenUntil)
+            return [];
+        const knownModels = cached?.models ?? [];
+        const offersModel = knownModels.includes(targetModel)
+            || (!knownModels.length && provider.model === targetModel);
+        return offersModel ? [{ provider, model: targetModel }] : [];
+    });
+    if (!preferredProvider)
+        return candidates;
+    return [
+        ...candidates.filter((candidate) => candidate.provider.name === preferredProvider.name),
+        ...candidates.filter((candidate) => candidate.provider.name !== preferredProvider.name)
+    ];
+}
+export async function generateImage(input) {
+    const prompt = input.prompt.trim();
+    if (!prompt)
+        throw new Error("Image prompt is required.");
+    const selection = input.target ?? { providerName: input.provider, model: input.model };
+    const candidates = await resolveImageProviderCandidates(selection);
+    if (!candidates.length) {
+        const selectionName = input.target ?? input.provider ?? input.model ?? "(unknown)";
+        throw new Error(`No usable provider offers image model for ${selectionName}. Run \`ai status\` to refresh model lists.`);
+    }
+    const failures = [];
+    for (const candidate of candidates) {
+        try {
+            const result = await generateWithProvider(candidate, prompt, input.outputDir ?? process.cwd());
+            await recordProviderRuntimeSuccess(candidate.provider.name);
+            return result;
+        }
+        catch (error) {
+            const message = summarizeError(error);
+            failures.push(`${candidate.provider.name}: ${message}`);
+            await recordProviderRuntimeFailure(candidate.provider.name, message);
+            await writeLog({
+                level: "warn",
+                category: "provider",
+                action: "image_generation_provider_failed",
+                message: `Image generation failed for ${candidate.provider.name} / ${candidate.model}: ${message}`,
+                metadata: { provider: candidate.provider.name, model: candidate.model }
+            });
+        }
+    }
+    throw new Error(`Image generation failed. ${failures.join("; ")}`);
+}
+async function generateWithProvider(candidate, prompt, outputDir) {
+    const usageProxy = await startOpenAiUsageProxy({
+        provider: candidate.provider,
+        model: candidate.model,
+        tool: "image",
+        engine: "codex",
+        upstreamHeadersTimeoutMs: IMAGE_REQUEST_TIMEOUT_MS
+    });
+    try {
+        const response = await fetchWithTimeout(`${usageProxy.baseUrl}/images/generations`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${candidate.provider.apiKey}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify({ model: candidate.model, prompt, n: 1 })
+        });
+        const text = await readBoundedResponseText(response, MAX_IMAGE_RESPONSE_BYTES);
+        const payload = parseJsonResponse(text);
+        if (!response.ok) {
+            throw new Error(readProviderError(payload) ?? `Provider returned HTTP ${response.status}.`);
+        }
+        const image = readFirstImage(payload);
+        if (!image)
+            throw new Error("Provider response did not contain an image.");
+        const baseResult = {
+            provider: candidate.provider.name,
+            model: candidate.model,
+            ...(image.revisedPrompt ? { revisedPrompt: image.revisedPrompt } : {})
+        };
+        if (image.base64) {
+            const buffer = decodeImage(image.base64);
+            const extension = detectImageExtension(buffer);
+            const filePath = await writeImageFile(outputDir, buffer, extension);
+            await writeLog({
+                category: "usage",
+                action: "image_generated",
+                message: `Generated image with ${candidate.provider.name} / ${candidate.model}.`,
+                metadata: { provider: candidate.provider.name, model: candidate.model, filePath, bytes: buffer.length }
+            });
+            return { ...baseResult, filePath };
+        }
+        await writeLog({
+            category: "usage",
+            action: "image_generated_url",
+            message: `Generated image URL with ${candidate.provider.name} / ${candidate.model}.`,
+            metadata: { provider: candidate.provider.name, model: candidate.model, urlHost: new URL(image.url).host }
+        });
+        return { ...baseResult, url: image.url };
+    }
+    finally {
+        await usageProxy.close().catch(() => undefined);
+    }
+}
+async function fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), IMAGE_REQUEST_TIMEOUT_MS);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readBoundedResponseText(response, maxBytes) {
+    const contentLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        throw new Error(`Provider image response exceeds ${maxBytes} bytes.`);
+    }
+    if (!response.body)
+        return "";
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of response.body) {
+        const buffer = Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > maxBytes)
+            throw new Error(`Provider image response exceeds ${maxBytes} bytes.`);
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, bytes).toString("utf8");
+}
+function parseJsonResponse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("Provider returned an invalid image response.");
+    }
+}
+function readFirstImage(payload) {
+    if (!isRecord(payload) || !Array.isArray(payload.data) || !isRecord(payload.data[0]))
+        return null;
+    const item = payload.data[0];
+    const base64 = typeof item.b64_json === "string" && item.b64_json.trim() ? item.b64_json.trim() : undefined;
+    const url = typeof item.url === "string" && isSafeImageUrl(item.url) ? item.url : undefined;
+    const revisedPrompt = typeof item.revised_prompt === "string" && item.revised_prompt.trim()
+        ? item.revised_prompt.trim()
+        : undefined;
+    if (!base64 && !url)
+        return null;
+    return { base64, url, revisedPrompt };
+}
+function isSafeImageUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+function decodeImage(value) {
+    const normalized = value.replace(/\s+/g, "");
+    if (!normalized || normalized.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
+        throw new Error("Provider returned invalid base64 image data.");
+    }
+    const buffer = Buffer.from(normalized, "base64");
+    if (!buffer.length)
+        throw new Error("Provider returned an empty image.");
+    if (buffer.length > MAX_IMAGE_BYTES)
+        throw new Error(`Generated image exceeds ${MAX_IMAGE_BYTES} bytes.`);
+    return buffer;
+}
+function detectImageExtension(buffer) {
+    if (buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return "png";
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff)
+        return "jpg";
+    if (buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP")
+        return "webp";
+    if (["GIF87a", "GIF89a"].includes(buffer.subarray(0, 6).toString("ascii")))
+        return "gif";
+    throw new Error("Provider returned an unsupported image format.");
+}
+async function writeImageFile(outputDir, buffer, extension) {
+    const resolvedDir = path.resolve(outputDir);
+    await fs.mkdir(resolvedDir, { recursive: true });
+    const fileName = `axiom-image-${formatTimestamp(new Date())}-${randomUUID().slice(0, 8)}.${extension}`;
+    const filePath = path.join(resolvedDir, fileName);
+    const temporaryPath = path.join(resolvedDir, `.${fileName}.${process.pid}.tmp`);
+    try {
+        await fs.writeFile(temporaryPath, buffer, { mode: 0o600, flag: "wx" });
+        await fs.rename(temporaryPath, filePath);
+        return filePath;
+    }
+    catch (error) {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function formatTimestamp(date) {
+    return date.toISOString().replace(/[-:]/g, "").replace(/\..+$/, "").replace("T", "-");
+}
+function readProviderError(payload) {
+    if (!isRecord(payload))
+        return null;
+    const error = payload.error;
+    if (typeof error === "string" && error.trim())
+        return error.trim().slice(0, 500);
+    if (isRecord(error) && typeof error.message === "string" && error.message.trim()) {
+        return error.message.trim().slice(0, 500);
+    }
+    return typeof payload.message === "string" && payload.message.trim()
+        ? payload.message.trim().slice(0, 500)
+        : null;
+}
+function summarizeError(error) {
+    if (error instanceof Error && error.name === "AbortError")
+        return "Image request timed out.";
+    return (error instanceof Error ? error.message : String(error)).slice(0, 500);
+}

package/dist/core/integrations/codex-provider-config.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import lockfile from "proper-lockfile";
 import { resolveToolCommand } from "../runner/command-resolver.js";
+import { getRunnerEngine } from "../runner/engine-registry.js";
 const LOCK_OPTIONS = {
     realpath: false,
     stale: 10_000,
@@ -128,6 +129,7 @@ export function buildCodexProviderConfig(current, provider, providerId, model =
     if (!provider.apiKey.trim())
         throw new Error(`Provider ${provider.name} has no API key.`);
     const selectedModel = assertCodexGptModel(model);
+    const baseUrl = getRunnerEngine("codex").normalizeBaseUrl(provider.baseUrl);
     const eol = current.includes("\r\n") ? "\r\n" : "\n";
     let next = removeProviderTables(current, providerId);
     next = setTopLevelTomlString(next, "cli_auth_credentials_store", "file");
@@ -136,7 +138,7 @@ export function buildCodexProviderConfig(current, provider, providerId, model =
     const table = [
         `[model_providers.${providerId}]`,
         `name = ${tomlString(provider.name)}`,
-        `base_url = ${tomlString(provider.baseUrl.trim().replace(/\/+$/, ""))}`,
+        `base_url = ${tomlString(baseUrl)}`,
         `env_key = ${tomlString("OPENAI_API_KEY")}`,
         `wire_api = ${tomlString("responses")}`
     ].join(eol);
@@ -253,7 +255,11 @@ export async function scheduleCodexAppRestart(options = {}) {
         "  setTimeout(() => spawnSync('/usr/bin/open', [appPath], { stdio: 'ignore' }), 1000);",
         "}, 750);"
     ].join("\n");
-    (options.spawnDetached ?? defaultSpawnDetached)(process.execPath, ["-e", helper]);
+    const restartEnvironment = { ...process.env };
+    delete restartEnvironment.OPENAI_API_KEY;
+    (options.spawnDetached ?? defaultSpawnDetached)(process.execPath, ["-e", helper], {
+        env: restartEnvironment
+    });
     return { scheduled: true, appPath };
 }
 async function configureChatGpt(configPath, authPath, codexHome, runner) {
@@ -515,8 +521,8 @@ async function fileExists(filePath) {
         return false;
     }
 }
-function defaultSpawnDetached(command, args) {
-    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+function defaultSpawnDetached(command, args, options = {}) {
+    const child = spawn(command, args, { detached: true, stdio: "ignore", ...options });
     child.unref();
 }
 function runProcess(command, args) {

package/dist/core/runner/openai-usage-http.js

@@ -14,20 +14,22 @@ const RESPONSE_HEADERS_TO_DROP = new Set([
     "content-encoding",
     "content-length"
 ]);
-export function buildUpstreamUrl(upstreamBaseUrl, incomingUrl) {
+export function buildUpstreamUrl(upstreamBaseUrl, incomingUrl, options = {}) {
     const local = new URL(incomingUrl, "http://127.0.0.1");
     let suffix = local.pathname;
-    if (suffix === "/v1") {
-        suffix = "";
-    }
-    else if (suffix.startsWith("/v1/")) {
-        suffix = suffix.slice(3);
+    if (options.stripV1Prefix !== false) {
+        if (suffix === "/v1") {
+            suffix = "";
+        }
+        else if (suffix.startsWith("/v1/")) {
+            suffix = suffix.slice(3);
+        }
     }
     const upstream = new URL(`${upstreamBaseUrl.replace(/\/+$/, "")}${suffix}`);
     upstream.search = local.search;
     return upstream.toString();
 }
-export function buildUpstreamHeaders(headers, apiKey) {
+export function buildUpstreamHeaders(headers, apiKey, options = {}) {
     const next = {};
     for (const [key, value] of Object.entries(headers)) {
         const normalized = key.toLowerCase();
@@ -40,7 +42,12 @@ export function buildUpstreamHeaders(headers, apiKey) {
             next[key] = value;
         }
     }
-    next.authorization = `Bearer ${apiKey}`;
+    if (options.includeAuthorization !== false) {
+        next.authorization = `Bearer ${apiKey}`;
+    }
+    if (options.includeAnthropicApiKey) {
+        next["x-api-key"] = apiKey;
+    }
     next["accept-encoding"] = "identity";
     return next;
 }
@@ -53,21 +60,57 @@ export function writeResponseHead(res, response) {
         }
     }
 }
-export async function streamResponse(response, res) {
+export async function streamResponse(response, res, options = {}) {
+    const maxCaptureBytes = normalizeCaptureLimit(options.maxCaptureBytes);
     const chunks = [];
     let capturedBytes = 0;
+    const tailChunks = [];
+    let tailBytes = 0;
+    let responseBytes = 0;
+    const tailLimit = Math.floor(maxCaptureBytes / 2);
     if (!response.body)
         return Buffer.alloc(0);
     for await (const chunk of response.body) {
         const buffer = Buffer.from(chunk);
-        if (capturedBytes < MAX_USAGE_CAPTURE_BYTES) {
-            const remaining = MAX_USAGE_CAPTURE_BYTES - capturedBytes;
+        responseBytes += buffer.length;
+        if (capturedBytes < maxCaptureBytes) {
+            const remaining = maxCaptureBytes - capturedBytes;
             chunks.push(buffer.length > remaining ? buffer.subarray(0, remaining) : buffer);
             capturedBytes += Math.min(buffer.length, remaining);
         }
+        tailBytes = appendTailChunk(tailChunks, buffer, tailLimit, tailBytes);
         res.write(buffer);
     }
-    return Buffer.concat(chunks);
+    const captured = Buffer.concat(chunks, capturedBytes);
+    if (responseBytes <= maxCaptureBytes)
+        return captured;
+    return Buffer.concat([
+        captured.subarray(0, tailLimit),
+        Buffer.from("\n"),
+        Buffer.concat(tailChunks, tailBytes)
+    ]);
+}
+function normalizeCaptureLimit(value) {
+    if (!Number.isFinite(value) || value === undefined || value <= 0)
+        return MAX_USAGE_CAPTURE_BYTES;
+    return Math.max(1024, Math.floor(value));
+}
+function appendTailChunk(chunks, buffer, limit, currentBytes) {
+    if (buffer.length >= limit) {
+        chunks.splice(0, chunks.length, buffer.subarray(buffer.length - limit));
+        return limit;
+    }
+    chunks.push(buffer);
+    let bytes = currentBytes + buffer.length;
+    while (chunks.length && bytes - chunks[0].length >= limit) {
+        bytes -= chunks.shift().length;
+    }
+    if (bytes > limit && chunks.length) {
+        const excess = bytes - limit;
+        chunks[0] = chunks[0].subarray(excess);
+        bytes = limit;
+    }
+    return bytes;
 }
 export async function readRequestBody(req) {
     const chunks = [];

package/dist/core/runner/openai-usage-proxy.js

@@ -1 +1,2 @@
 export { startOpenAiUsageProxy } from "./openai-usage-server.js";
+export { sumKnownProxyCosts, sumProxyUsage } from "./openai-usage-summary.js";

package/dist/core/runner/openai-usage-recording.js

@@ -59,15 +59,47 @@ export async function recordUsageFromResponse(input) {
 }
 function extractBestUsageCandidate(text, contentType, fallbackModel) {
     const values = contentType.includes("text/event-stream") ? parseSseValues(text) : parseJsonValues(text);
-    let best = null;
+    const candidates = [];
     for (const value of values) {
-        for (const candidate of collectUsageCandidates(value, fallbackModel)) {
-            if (!best || candidate.usage.totalTokens >= best.usage.totalTokens) {
-                best = candidate;
-            }
+        candidates.push(...collectUsageCandidates(value, fallbackModel));
+    }
+    return mergeUsageCandidates(candidates, fallbackModel);
+}
+function mergeUsageCandidates(candidates, fallbackModel) {
+    if (!candidates.length)
+        return null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let totalTokens = 0;
+    let cacheReadInputTokens;
+    let model = fallbackModel;
+    let modelCandidateTokens = -1;
+    let costUsd;
+    for (const candidate of candidates) {
+        inputTokens = Math.max(inputTokens, candidate.usage.inputTokens);
+        outputTokens = Math.max(outputTokens, candidate.usage.outputTokens);
+        totalTokens = Math.max(totalTokens, candidate.usage.totalTokens);
+        if (candidate.usage.cacheReadInputTokens !== undefined) {
+            cacheReadInputTokens = Math.max(cacheReadInputTokens ?? 0, candidate.usage.cacheReadInputTokens);
+        }
+        if (candidate.usage.totalTokens >= modelCandidateTokens) {
+            model = candidate.model;
+            modelCandidateTokens = candidate.usage.totalTokens;
+        }
+        if (candidate.costUsd !== undefined) {
+            costUsd = Math.max(costUsd ?? 0, candidate.costUsd);
         }
     }
-    return best;
+    return {
+        model,
+        usage: {
+            inputTokens,
+            outputTokens,
+            totalTokens: Math.max(totalTokens, inputTokens + outputTokens),
+            ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {})
+        },
+        ...(costUsd !== undefined ? { costUsd } : {})
+    };
 }
 function parseJsonValues(text) {
     const trimmed = text.trim();

package/dist/core/runner/openai-usage-server.js

@@ -8,7 +8,8 @@ import { getToolBaseUrl } from "./tool-runner.js";
 const DEFAULT_UPSTREAM_HEADERS_TIMEOUT_MS = 45_000;
 const MAX_CONSECUTIVE_HEADERS_TIMEOUTS = 2;
 export async function startOpenAiUsageProxy(input) {
-    const upstreamBaseUrl = getToolBaseUrl("codex", input.provider);
+    const engine = input.engine ?? (input.tool === "claude" ? "claude" : "codex");
+    const upstreamBaseUrl = getToolBaseUrl(engine, input.provider);
     const upstreamHeadersTimeoutMs = normalizePositiveTimeout(input.upstreamHeadersTimeoutMs, DEFAULT_UPSTREAM_HEADERS_TIMEOUT_MS);
     // Codex already retries failed Responses requests. Give those retries fresh
     // upstream connections so a stale gateway keep-alive socket cannot poison an
@@ -50,7 +51,7 @@ export async function startOpenAiUsageProxy(input) {
             requestModel = extractRequestModel(requestBody) ?? input.model;
             requestBytes = requestBody.length;
             requestShape = summarizeRequestShape(requestBody);
-            const responsesStream = isResponsesStreamRequest(req.url ?? "/", requestBody);
+            const responsesStream = engine === "codex" && isResponsesStreamRequest(req.url ?? "/", requestBody);
             void writeLog({
                 category: "usage",
                 action: "openai_usage_proxy_request",
@@ -62,7 +63,9 @@ export async function startOpenAiUsageProxy(input) {
                     path: new URL(req.url ?? "/", "http://127.0.0.1").pathname
                 }
             });
-            const upstreamUrl = buildUpstreamUrl(upstreamBaseUrl, req.url ?? "/");
+            const upstreamUrl = buildUpstreamUrl(upstreamBaseUrl, req.url ?? "/", {
+                stripV1Prefix: engine === "codex"
+            });
             upstreamPath = new URL(upstreamUrl).pathname;
             if (consecutiveHeadersTimeouts >= MAX_CONSECUTIVE_HEADERS_TIMEOUTS) {
                 await writeLog({
@@ -87,7 +90,10 @@ export async function startOpenAiUsageProxy(input) {
             }
             const upstreamResponse = await fetch(upstreamUrl, {
                 method: req.method,
-                headers: buildUpstreamHeaders(req.headers, input.provider.apiKey),
+                headers: buildUpstreamHeaders(req.headers, input.provider.apiKey, {
+                    includeAnthropicApiKey: engine === "claude",
+                    includeAuthorization: engine !== "claude"
+                }),
                 body: requestBody.length && methodMayHaveBody(req.method) ? requestBody : undefined,
                 dispatcher: upstreamDispatcher
             });
@@ -150,7 +156,9 @@ export async function startOpenAiUsageProxy(input) {
                 return;
             }
             writeResponseHead(res, upstreamResponse);
-            const captured = await streamResponse(upstreamResponse, res);
+            const captured = await streamResponse(upstreamResponse, res, {
+                maxCaptureBytes: input.tool === "image" ? 32 * 1024 * 1024 : undefined
+            });
             const recordedUsage = await recordUsageFromResponse({
                 text: captured.toString("utf8"),
                 contentType: upstreamResponse.headers.get("content-type") ?? "",
@@ -208,7 +216,7 @@ export async function startOpenAiUsageProxy(input) {
         throw new Error("Failed to start AI Gateway OpenAI proxy.");
     }
     return {
-        baseUrl: `http://127.0.0.1:${address.port}/v1`,
+        baseUrl: `http://127.0.0.1:${address.port}${engine === "codex" ? "/v1" : ""}`,
         async close() {
             const closeServer = server.listening
                 ? new Promise((resolve, reject) => {

package/dist/core/runner/openai-usage-summary.js

@@ -0,0 +1,18 @@
+export function sumKnownProxyCosts(records) {
+    const knownCosts = records
+        .map((record) => record.costUsd)
+        .filter((cost) => typeof cost === "number" && Number.isFinite(cost) && cost >= 0);
+    if (!knownCosts.length)
+        return undefined;
+    return Number(knownCosts.reduce((sum, cost) => sum + cost, 0).toFixed(8));
+}
+export function sumProxyUsage(records) {
+    if (!records.length)
+        return undefined;
+    return records.reduce((sum, record) => ({
+        inputTokens: sum.inputTokens + record.usage.inputTokens,
+        outputTokens: sum.outputTokens + record.usage.outputTokens,
+        totalTokens: sum.totalTokens + record.usage.totalTokens,
+        cacheReadInputTokens: (sum.cacheReadInputTokens ?? 0) + (record.usage.cacheReadInputTokens ?? 0)
+    }), { inputTokens: 0, outputTokens: 0, totalTokens: 0, cacheReadInputTokens: 0 });
+}