botholomew 0.18.7 → 0.19.3

package/src/llm/capabilities.ts

@@ -0,0 +1,155 @@
+import type { LlmBlock } from "../config/schemas.ts";
+import { logger } from "../utils/logger.ts";
+import { BotholomewLlmError } from "./types.ts";
+
+const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434";
+
+/** Manually-curated max input tokens per known model. */
+const KNOWN_CONTEXT_WINDOWS: Record<string, number> = {
+  // Anthropic
+  "claude-opus-4-6": 200_000,
+  "claude-opus-4-5": 200_000,
+  "claude-sonnet-4-5": 200_000,
+  "claude-haiku-4-5-20251001": 200_000,
+  // OpenAI
+  "gpt-4o": 128_000,
+  "gpt-4o-mini": 128_000,
+  "gpt-4-turbo": 128_000,
+  // Ollama (defaults — extendable per Modelfile)
+  "llama3.1:8b": 128_000,
+  "llama3.1:70b": 128_000,
+  "qwen2.5:7b": 32_000,
+  "qwen2.5:3b": 32_000,
+  "mistral-nemo": 128_000,
+};
+
+const FALLBACK_BY_PROVIDER: Record<LlmBlock["provider"], number> = {
+  anthropic: 200_000,
+  // Ollama allocates KV cache up front, so a generous default eats RAM on
+  // local machines. 16K covers Botholomew's system prompt + tool schemas +
+  // a reasonable conversation; raise via `llm.max_input_tokens` if needed.
+  ollama: 16_000,
+  "openai-compatible": 32_000,
+};
+
+const tokenCache = new Map<string, number>();
+const toolSupportCache = new Map<string, boolean>();
+
+const TOOL_CAPABLE_HINT = `Try one of these tool-capable models:
+  Anthropic:           claude-opus-4-6, claude-sonnet-4-5, claude-haiku-4-5
+  Ollama (local):      llama3.1:8b, qwen2.5:7b, mistral-nemo, command-r
+  OpenAI-compatible:   gpt-4o, gpt-4o-mini, or any function-calling model
+
+Update \`llm.model\` in your botholomew config. If you believe this model
+*does* support tools but the probe is wrong, set \`llm.supports_tools: true\`
+to override.`;
+
+function cacheKey(cfg: LlmBlock): string {
+  return `${cfg.provider}:${cfg.model}:${cfg.base_url ?? ""}`;
+}
+
+function ollamaBaseUrl(cfg: LlmBlock): string {
+  return (cfg.base_url || DEFAULT_OLLAMA_BASE_URL).replace(/\/+$/, "");
+}
+
+interface OllamaShowResponse {
+  capabilities?: string[];
+  model_info?: Record<string, unknown>;
+}
+
+async function ollamaShow(cfg: LlmBlock): Promise<OllamaShowResponse | null> {
+  try {
+    const response = await fetch(`${ollamaBaseUrl(cfg)}/api/show`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: cfg.model }),
+    });
+    if (!response.ok) return null;
+    return (await response.json()) as OllamaShowResponse;
+  } catch (err) {
+    logger.debug(`Ollama /api/show failed: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * Throws `BotholomewLlmError("no_tool_support", ...)` if the configured model
+ * cannot call tools. Memoized per `provider:model:base_url`.
+ */
+export async function assertToolCapable(cfg: LlmBlock): Promise<void> {
+  const key = cacheKey(cfg);
+  const cached = toolSupportCache.get(key);
+  if (cached === true) return;
+  if (cached === false) {
+    throw makeNoToolError(cfg);
+  }
+
+  let supported = false;
+  switch (cfg.provider) {
+    case "anthropic":
+      supported = true;
+      break;
+    case "openai-compatible":
+      supported = cfg.supports_tools !== false;
+      break;
+    case "ollama": {
+      const show = await ollamaShow(cfg);
+      if (show?.capabilities?.includes("tools")) {
+        supported = true;
+      } else if (show == null) {
+        // Probe failed — fall back to the manual override (default false).
+        supported = cfg.supports_tools === true;
+      } else {
+        supported = false;
+      }
+      break;
+    }
+  }
+
+  toolSupportCache.set(key, supported);
+  if (!supported) throw makeNoToolError(cfg);
+}
+
+function makeNoToolError(cfg: LlmBlock): BotholomewLlmError {
+  return new BotholomewLlmError(
+    "no_tool_support",
+    `Model "${cfg.model}" (${cfg.provider}) does not support tool/function calling, which Botholomew requires.\n\n${TOOL_CAPABLE_HINT}`,
+  );
+}
+
+/**
+ * Resolve max input tokens for the given model. Lookup order:
+ *   1. `cfg.max_input_tokens` override
+ *   2. Ollama `/api/show` `model_info.<arch>.context_length`
+ *   3. Hardcoded KNOWN_CONTEXT_WINDOWS table
+ *   4. Provider-level fallback
+ */
+export async function getMaxInputTokens(cfg: LlmBlock): Promise<number> {
+  if (cfg.max_input_tokens && cfg.max_input_tokens > 0) {
+    return cfg.max_input_tokens;
+  }
+  const key = cacheKey(cfg);
+  const cached = tokenCache.get(key);
+  if (cached !== undefined) return cached;
+
+  let resolved: number | null = null;
+
+  // For Ollama, skip /api/show — it reports the model's *maximum* (often
+  // 128K+), but Ollama allocates KV cache for the full num_ctx up front.
+  // Use the provider fallback so local Macs don't OOM. Users who want more
+  // can set `llm.max_input_tokens` explicitly.
+  if (cfg.provider !== "ollama") {
+    const fromTable = KNOWN_CONTEXT_WINDOWS[cfg.model];
+    if (fromTable && fromTable > 0) resolved = fromTable;
+  }
+
+  if (resolved == null) {
+    resolved = FALLBACK_BY_PROVIDER[cfg.provider];
+    logger.debug(
+      `Falling back to default context window (${resolved}) for ${cfg.provider}:${cfg.model}. Set \`llm.max_input_tokens\` to override.`,
+    );
+  }
+
+  tokenCache.set(key, resolved);
+  return resolved;
+}

package/src/llm/error-format.ts

@@ -0,0 +1,95 @@
+import { APICallError } from "@ai-sdk/provider";
+import type { LlmBlock } from "../config/schemas.ts";
+
+/**
+ * Turn an unknown error from the AI SDK / fetch / provider into a short,
+ * user-friendly string. Used by every LLM call site (chat, worker, title
+ * generator, schedule evaluator, capability summarizer) so the TUI / logs
+ * never have to render the AI SDK's raw `APICallError` (which dumps the
+ * full request body, headers, and tool schemas on toString).
+ */
+export function formatLlmError(err: unknown, cfg?: LlmBlock): string {
+  if (APICallError.isInstance(err)) {
+    return formatApiCallError(err, cfg);
+  }
+  if (err instanceof Error) {
+    const msg = err.message ?? String(err);
+    if (/ENOTFOUND|ECONNREFUSED|EHOSTUNREACH|fetch failed/i.test(msg)) {
+      if (cfg?.provider === "ollama") {
+        const url = cfg.base_url || "http://localhost:11434";
+        return `Can't reach Ollama at ${url}. Is the server running?`;
+      }
+      return `Network error: ${msg}`;
+    }
+    return msg;
+  }
+  return String(err);
+}
+
+function formatApiCallError(err: APICallError, cfg?: LlmBlock): string {
+  const status = err.statusCode;
+  const provider = cfg?.provider;
+
+  if (status === 401 || status === 403) {
+    if (provider === "anthropic") {
+      return "Unauthorized — check `llm.api_key` (or `ANTHROPIC_API_KEY` env var).";
+    }
+    if (provider === "ollama") {
+      const where = cfg?.base_url ?? "";
+      if (where.includes("ollama.com")) {
+        return "Unauthorized — Ollama Cloud requires a bearer token. Get one from https://ollama.com (account → API keys) and put it in `llm.api_key`.";
+      }
+      return "Unauthorized — your Ollama endpoint rejected the request.";
+    }
+    if (provider === "openai-compatible") {
+      return "Unauthorized — check `llm.api_key` for your OpenAI-compatible endpoint.";
+    }
+    return "Unauthorized — check your API credentials.";
+  }
+
+  if (status === 404) {
+    if (cfg) {
+      return `Model not found: \`${cfg.model}\` on ${cfg.provider}. Check the model id (and \`base_url\` if remote).`;
+    }
+    return "Model not found. Check the model id and base_url.";
+  }
+
+  if (status === 429) {
+    return "Rate limited by the provider. Wait and retry.";
+  }
+
+  if (status && status >= 500) {
+    return `Provider error (${status}). Try again in a moment.`;
+  }
+
+  // Generic fallback — keep it short. Do NOT include `err.requestBodyValues`
+  // (it contains the full prompt + tool schemas) or `err.responseHeaders`.
+  return err.message || `Provider call failed${status ? ` (${status})` : ""}.`;
+}
+
+/**
+ * Drain promises returned by `streamText` that we don't await on the error
+ * path. The AI SDK exposes `usage`, `providerMetadata`, `text`, etc. as
+ * eagerly-created promises tied to the underlying request; when the stream
+ * errors out, these reject too. If we throw out of the for-await loop
+ * before awaiting them, Node logs them as unhandled rejections — which is
+ * what produced the giant request-body dump in the TUI.
+ */
+export function drainStreamPromises(result: {
+  usage?: PromiseLike<unknown>;
+  providerMetadata?: PromiseLike<unknown>;
+}): void {
+  const swallow = () => {};
+  if (
+    result.usage &&
+    typeof (result.usage as Promise<unknown>).catch === "function"
+  ) {
+    void (result.usage as Promise<unknown>).catch(swallow);
+  }
+  if (
+    result.providerMetadata &&
+    typeof (result.providerMetadata as Promise<unknown>).catch === "function"
+  ) {
+    void (result.providerMetadata as Promise<unknown>).catch(swallow);
+  }
+}

package/src/llm/fake.ts

@@ -0,0 +1,226 @@
+import { existsSync, readFileSync } from "node:fs";
+import { MockLanguageModelV3, simulateReadableStream } from "ai/test";
+
+export interface FakeTurn {
+  /** Optional regex matched against the most recent user-authored text. */
+  match?: string;
+  /** Full reply text; auto-chunked if `chunks` is absent. */
+  text?: string;
+  /** Explicit text chunks; overrides auto-chunking. */
+  chunks?: string[];
+  /** Characters per auto-chunk when `chunks` is absent. */
+  chunkSize?: number;
+  /** Delay between chunks in milliseconds. */
+  delayMs?: number;
+  /** Initial wait before the first chunk emits, in milliseconds. */
+  preDelayMs?: number;
+  /** Optional tool calls to emit after text. */
+  toolCalls?: Array<{
+    id?: string;
+    name: string;
+    input: Record<string, unknown>;
+  }>;
+  /** Optional usage/cache reporting. */
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+  };
+  providerMetadata?: Record<string, Record<string, unknown>>;
+}
+
+export interface FakeFixture {
+  turns: FakeTurn[];
+}
+
+let loadedFixture: FakeFixture | null = null;
+let loadedFixturePath: string | undefined;
+let sequentialIndex = 0;
+
+function loadFixture(): FakeFixture {
+  const fixturePath = process.env.BOTHOLOMEW_FAKE_LLM_FIXTURE;
+  if (loadedFixture && loadedFixturePath === fixturePath) {
+    return loadedFixture;
+  }
+  loadedFixturePath = fixturePath;
+  sequentialIndex = 0;
+  if (!fixturePath) {
+    loadedFixture = { turns: [] };
+    return loadedFixture;
+  }
+  if (!existsSync(fixturePath)) {
+    throw new Error(
+      `BOTHOLOMEW_FAKE_LLM_FIXTURE points to missing file: ${fixturePath}`,
+    );
+  }
+  loadedFixture = JSON.parse(readFileSync(fixturePath, "utf8")) as FakeFixture;
+  return loadedFixture;
+}
+
+function selectTurn(lastUserText: string): FakeTurn {
+  const fixture = loadFixture();
+  if (fixture.turns.length === 0) {
+    return { text: "(fake LLM: no fixture turns configured)" };
+  }
+  for (let i = sequentialIndex; i < fixture.turns.length; i++) {
+    const t = fixture.turns[i];
+    if (t?.match && new RegExp(t.match, "i").test(lastUserText)) {
+      sequentialIndex = i + 1;
+      return t;
+    }
+  }
+  if (sequentialIndex < fixture.turns.length) {
+    const t = fixture.turns[sequentialIndex];
+    sequentialIndex++;
+    if (t) return t;
+  }
+  return fixture.turns[fixture.turns.length - 1] ?? { text: "" };
+}
+
+function chunkText(text: string, size: number): string[] {
+  if (size <= 0 || text.length === 0) return text ? [text] : [];
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += size) out.push(text.slice(i, i + size));
+  return out;
+}
+
+function extractLastUserText(prompt: unknown): string {
+  if (!Array.isArray(prompt)) return "";
+  for (let i = prompt.length - 1; i >= 0; i--) {
+    const m = prompt[i] as { role?: string; content?: unknown };
+    if (m.role !== "user") continue;
+    if (typeof m.content === "string") return m.content;
+    if (Array.isArray(m.content)) {
+      for (const part of m.content) {
+        const p = part as { type?: string; text?: unknown };
+        if (p.type === "text" && typeof p.text === "string") return p.text;
+      }
+    }
+  }
+  return "";
+}
+
+function isTitleGeneratorCall(prompt: unknown): boolean {
+  if (!Array.isArray(prompt)) return false;
+  for (const m of prompt) {
+    const msg = m as { role?: string; content?: unknown };
+    if (msg.role === "system" && typeof msg.content === "string") {
+      return /title generator/i.test(msg.content);
+    }
+  }
+  return false;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: V3StreamPart union too wide to enumerate
+type StreamPart = any;
+
+function buildStreamParts(turn: FakeTurn): StreamPart[] {
+  const parts: StreamPart[] = [{ type: "stream-start", warnings: [] }];
+  const text = turn.text ?? turn.chunks?.join("") ?? "";
+  const chunks = turn.chunks ?? chunkText(text, turn.chunkSize ?? 6);
+
+  const textId = "txt_0";
+  if (text) {
+    parts.push({ type: "text-start", id: textId });
+    for (const chunk of chunks) {
+      parts.push({ type: "text-delta", id: textId, delta: chunk });
+    }
+    parts.push({ type: "text-end", id: textId });
+  }
+
+  if (turn.toolCalls) {
+    for (const tc of turn.toolCalls) {
+      const id = tc.id ?? `toolu_${Math.random().toString(36).slice(2, 14)}`;
+      parts.push({ type: "tool-input-start", id, toolName: tc.name });
+      parts.push({
+        type: "tool-call",
+        toolCallId: id,
+        toolName: tc.name,
+        input: JSON.stringify(tc.input),
+      });
+    }
+  }
+
+  const unified = turn.toolCalls?.length ? "tool-calls" : "stop";
+  const inTok = turn.usage?.inputTokens ?? 100;
+  const outTok =
+    turn.usage?.outputTokens ?? Math.max(1, Math.floor(text.length / 4));
+  parts.push({
+    type: "finish",
+    finishReason: { unified, raw: unified },
+    usage: {
+      inputTokens: {
+        total: inTok,
+        noCache: inTok,
+        cacheRead: 0,
+        cacheWrite: 0,
+      },
+      outputTokens: { total: outTok, text: outTok, reasoning: 0 },
+      totalTokens: inTok + outTok,
+    },
+    providerMetadata: turn.providerMetadata,
+  });
+
+  return parts;
+}
+
+export function createFakeLanguageModel(): MockLanguageModelV3 {
+  return new MockLanguageModelV3({
+    provider: "fake",
+    modelId: "botholomew-fake-llm",
+    doStream: async (options) => {
+      const titleCall = isTitleGeneratorCall(options.prompt);
+      const turn: FakeTurn = titleCall
+        ? { text: "Chat session", delayMs: 0 }
+        : selectTurn(extractLastUserText(options.prompt));
+
+      const parts = buildStreamParts(turn);
+      return {
+        stream: simulateReadableStream({
+          chunks: parts,
+          initialDelayInMs: turn.preDelayMs ?? null,
+          chunkDelayInMs: turn.delayMs ?? null,
+        }),
+      };
+    },
+    doGenerate: async (options) => {
+      const titleCall = isTitleGeneratorCall(options.prompt);
+      const turn: FakeTurn = titleCall
+        ? { text: "Chat session" }
+        : selectTurn(extractLastUserText(options.prompt));
+      const text = turn.text ?? turn.chunks?.join("") ?? "";
+      const content: Array<Record<string, unknown>> = [];
+      if (text) content.push({ type: "text", text });
+      if (turn.toolCalls) {
+        for (const tc of turn.toolCalls) {
+          const id =
+            tc.id ?? `toolu_${Math.random().toString(36).slice(2, 14)}`;
+          content.push({
+            type: "tool-call",
+            toolCallId: id,
+            toolName: tc.name,
+            input: JSON.stringify(tc.input),
+          });
+        }
+      }
+      const unified = turn.toolCalls?.length ? "tool-calls" : "stop";
+      const inTok = turn.usage?.inputTokens ?? 100;
+      const outTok =
+        turn.usage?.outputTokens ?? Math.max(1, Math.floor(text.length / 4));
+      return {
+        content: content as never,
+        finishReason: { unified, raw: unified },
+        usage: {
+          inputTokens: {
+            total: inTok,
+            noCache: inTok,
+            cacheRead: 0,
+            cacheWrite: 0,
+          },
+          outputTokens: { total: outTok, text: outTok, reasoning: 0 },
+          totalTokens: inTok + outTok,
+        },
+        warnings: [],
+      };
+    },
+  });
+}

package/src/llm/index.ts

@@ -0,0 +1,19 @@
+export { type AbortHandle, createAbortHandle } from "./abort.ts";
+export { withAnthropicCacheBreakpoints } from "./cache-control.ts";
+export { assertToolCapable, getMaxInputTokens } from "./capabilities.ts";
+export { drainStreamPromises, formatLlmError } from "./error-format.ts";
+export {
+  createFakeLanguageModel,
+  type FakeFixture,
+  type FakeTurn,
+} from "./fake.ts";
+export { describeModel, getLanguageModel } from "./provider.ts";
+export { buildProviderOptions } from "./provider-options.ts";
+export { toAiSdkTool, toAiSdkTools } from "./tools.ts";
+export {
+  BotholomewLlmError,
+  type CacheTokens,
+  type LlmBlock,
+  type LlmProvider,
+} from "./types.ts";
+export { extractCacheTokens } from "./usage.ts";

package/src/llm/provider-options.ts

@@ -0,0 +1,29 @@
+import type { SharedV3ProviderOptions } from "@ai-sdk/provider";
+import type { LlmBlock } from "../config/schemas.ts";
+
+type ProviderOptions = SharedV3ProviderOptions;
+
+/**
+ * Build the `providerOptions` payload passed to `streamText` / `generateText`
+ * / `generateObject` for the current provider.
+ *
+ * For Ollama, this is critical: without `num_ctx` set per-request the server
+ * defaults to whatever the model's Modelfile says (usually 4096), and any
+ * prompt larger than that silently gets truncated — which mangles the
+ * system prompt and tool schemas.
+ *
+ * Returns `undefined` for providers that don't need per-call options.
+ */
+export function buildProviderOptions(
+  cfg: LlmBlock,
+  numCtx: number,
+): ProviderOptions | undefined {
+  if (cfg.provider === "ollama") {
+    return {
+      ollama: {
+        options: { num_ctx: numCtx },
+      },
+    };
+  }
+  return undefined;
+}

package/src/llm/provider.ts

@@ -0,0 +1,65 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import type { LanguageModel } from "ai";
+import { createOllama } from "ollama-ai-provider-v2";
+import type { LlmBlock } from "../config/schemas.ts";
+import { createFakeLanguageModel } from "./fake.ts";
+import { BotholomewLlmError } from "./types.ts";
+
+const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434";
+
+/**
+ * Return an AI SDK `LanguageModel` for the given config block. When
+ * `BOTHOLOMEW_FAKE_LLM=1` is set, always returns a `MockLanguageModelV3`
+ * regardless of provider — the fixture path is read inside the fake.
+ */
+export function getLanguageModel(cfg: LlmBlock): LanguageModel {
+  if (process.env.BOTHOLOMEW_FAKE_LLM === "1") {
+    return createFakeLanguageModel();
+  }
+  switch (cfg.provider) {
+    case "anthropic": {
+      if (!cfg.api_key) {
+        throw new BotholomewLlmError(
+          "no_credentials",
+          "Anthropic provider requires `llm.api_key` (or ANTHROPIC_API_KEY env var).",
+        );
+      }
+      const anthropic = createAnthropic({ apiKey: cfg.api_key });
+      return anthropic(cfg.model);
+    }
+    case "ollama": {
+      const baseURL = `${(cfg.base_url || DEFAULT_OLLAMA_BASE_URL).replace(/\/+$/, "")}/api`;
+      // When `api_key` is set, send it as a bearer token. Local Ollama
+      // ignores auth headers; Ollama Cloud (https://ollama.com) requires
+      // them. Same code path covers both.
+      const headers = cfg.api_key
+        ? { Authorization: `Bearer ${cfg.api_key}` }
+        : undefined;
+      const ollama = createOllama({ baseURL, headers });
+      return ollama(cfg.model);
+    }
+    case "openai-compatible": {
+      if (!cfg.base_url) {
+        throw new BotholomewLlmError(
+          "no_credentials",
+          "OpenAI-compatible provider requires `llm.base_url`.",
+        );
+      }
+      const provider = createOpenAICompatible({
+        name: "openai-compatible",
+        baseURL: cfg.base_url.replace(/\/+$/, ""),
+        apiKey: cfg.api_key || undefined,
+      });
+      return provider(cfg.model);
+    }
+    default: {
+      const exhaustive: never = cfg.provider;
+      throw new Error(`Unsupported LLM provider: ${String(exhaustive)}`);
+    }
+  }
+}
+
+export function describeModel(cfg: LlmBlock): string {
+  return `${cfg.provider}:${cfg.model}`;
+}

package/src/llm/tools.ts

@@ -0,0 +1,24 @@
+import { type Tool, type ToolSet, tool } from "ai";
+import type { z } from "zod";
+import type { AnyToolDefinition } from "../tools/tool.ts";
+
+/**
+ * Convert a Botholomew `ToolDefinition` into an AI-SDK `Tool`. We deliberately
+ * do NOT wire the `execute` function: our turn loop runs tools itself so we can
+ * keep max_turns, parallel execution, queued user injections, terminal worker
+ * tools, and the soft-error (`is_error`) convention working consistently.
+ */
+export function toAiSdkTool(def: AnyToolDefinition): Tool {
+  return tool({
+    description: def.description,
+    inputSchema: def.inputSchema as z.ZodType,
+  });
+}
+
+export function toAiSdkTools(defs: AnyToolDefinition[]): ToolSet {
+  const out: Record<string, Tool> = {};
+  for (const def of defs) {
+    out[def.name] = toAiSdkTool(def);
+  }
+  return out as ToolSet;
+}

package/src/llm/types.ts

@@ -0,0 +1,20 @@
+export type { LlmBlock, LlmProvider } from "../config/schemas.ts";
+
+export interface CacheTokens {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheCreation: number;
+}
+
+export class BotholomewLlmError extends Error {
+  code: "no_tool_support" | "no_credentials" | "model_unreachable";
+  constructor(
+    code: "no_tool_support" | "no_credentials" | "model_unreachable",
+    message: string,
+  ) {
+    super(message);
+    this.code = code;
+    this.name = "BotholomewLlmError";
+  }
+}

package/src/llm/usage.ts

@@ -0,0 +1,33 @@
+import type { LanguageModelUsage, ProviderMetadata } from "ai";
+import type { CacheTokens } from "./types.ts";
+
+interface AnthropicCacheMeta {
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+}
+
+/**
+ * Normalize cache-token accounting across providers. Anthropic surfaces cache
+ * read/creation via `providerMetadata.anthropic`; AI SDK also bubbles cache
+ * reads into `usage.inputTokenDetails.cacheReadTokens` for some providers.
+ * Non-caching providers (Ollama, OpenAI-compatible) yield zeros.
+ */
+export function extractCacheTokens(
+  usage: LanguageModelUsage | undefined,
+  meta?: ProviderMetadata,
+): CacheTokens {
+  const anthropicMeta = (meta?.anthropic ?? {}) as AnthropicCacheMeta;
+  return {
+    input: usage?.inputTokens ?? 0,
+    output: usage?.outputTokens ?? 0,
+    cacheRead:
+      anthropicMeta.cacheReadInputTokens ??
+      usage?.inputTokenDetails?.cacheReadTokens ??
+      usage?.cachedInputTokens ??
+      0,
+    cacheCreation:
+      anthropicMeta.cacheCreationInputTokens ??
+      usage?.inputTokenDetails?.cacheWriteTokens ??
+      0,
+  };
+}