lazyclaw 3.88.0

package/providers/gemini.mjs

@@ -0,0 +1,187 @@
+// Google Gemini (Generative Language API) streaming provider.
+//
+// Wire format:
+//   POST https://generativelanguage.googleapis.com/v1/models/{model}:streamGenerateContent?alt=sse&key={apiKey}
+//   { "contents": [...], "systemInstruction"?: {...} }
+//
+// Auth quirk: Gemini takes `?key=...` in the query string rather than a
+// header. We still accept opts.apiKey via the same shape as the other
+// providers and append it to the URL ourselves so callers don't have to
+// remember the difference.
+//
+// Streaming format with `alt=sse`: standard SSE — `data: <json>\n\n` per
+// chunk. Each JSON payload contains
+// `candidates[0].content.parts[0].text` for text deltas. There's no
+// terminator like `[DONE]`; the stream simply ends.
+//
+// Test seam: opts.fetch overrides globalThis.fetch.
+
+const DEFAULT_BASE = 'https://generativelanguage.googleapis.com/v1';
+
+class InvalidApiKeyError extends Error {
+  constructor(message = 'invalid api key') {
+    super(message);
+    this.name = 'InvalidApiKeyError';
+    this.code = 'INVALID_KEY';
+  }
+}
+class AbortError extends Error {
+  constructor(message = 'aborted') {
+    super(message);
+    this.name = 'AbortError';
+    this.code = 'ABORT';
+  }
+}
+class RateLimitError extends Error {
+  constructor(retryAfterMs, body = '') {
+    super(`gemini api 429: rate limited (retry-after ${retryAfterMs}ms)`);
+    this.name = 'RateLimitError';
+    this.code = 'RATE_LIMIT';
+    this.status = 429;
+    this.retryAfterMs = retryAfterMs;
+    this.body = body;
+  }
+}
+class ApiError extends Error {
+  constructor(status, body) {
+    super(`gemini api ${status}: ${String(body).slice(0, 200)}`);
+    this.name = 'GeminiApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function parseRetryAfterMs(headers) {
+  let raw = null;
+  if (headers && typeof headers.get === 'function') raw = headers.get('retry-after') || headers.get('Retry-After');
+  else if (headers) raw = headers['retry-after'] || headers['Retry-After'];
+  if (!raw) return 1000;
+  const asInt = parseInt(String(raw), 10);
+  if (!Number.isNaN(asInt)) return Math.max(0, asInt * 1000);
+  const date = Date.parse(String(raw));
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return 1000;
+}
+
+async function* iterateBody(body) {
+  if (body && typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) yield value;
+    }
+    return;
+  }
+  if (body && typeof body[Symbol.asyncIterator] === 'function') {
+    for await (const chunk of body) yield chunk;
+    return;
+  }
+  if (typeof body === 'string') { yield new TextEncoder().encode(body); return; }
+  if (body instanceof Uint8Array) { yield body; return; }
+  throw new Error('gemini: response body is not iterable');
+}
+
+function* parseSseFrames(buffer) {
+  let cursor = 0;
+  while (true) {
+    const sep = buffer.indexOf('\n\n', cursor);
+    if (sep < 0) break;
+    const frame = buffer.slice(cursor, sep);
+    cursor = sep + 2;
+    const dataLines = [];
+    for (const line of frame.split('\n')) {
+      if (line.startsWith('data:')) dataLines.push(line.slice(5).trim());
+    }
+    yield { data: dataLines.join('\n'), nextCursor: cursor };
+  }
+}
+
+// Translate the canonical {role:user|assistant|system, content:string}
+// message shape to Gemini's contents+systemInstruction shape.
+//   - assistant → "model" (Gemini's name for it)
+//   - system → bubbled up to systemInstruction (most recent wins on conflict)
+function toGeminiBody(messages, opts) {
+  const contents = [];
+  let systemText = opts.system || null;
+  for (const m of messages) {
+    if (m.role === 'system') {
+      systemText = String(m.content ?? '');
+      continue;
+    }
+    if (m.role !== 'user' && m.role !== 'assistant') continue;
+    contents.push({
+      role: m.role === 'assistant' ? 'model' : 'user',
+      parts: [{ text: String(m.content ?? '') }],
+    });
+  }
+  const body = { contents };
+  if (systemText) body.systemInstruction = { parts: [{ text: systemText }] };
+  return body;
+}
+
+export const geminiProvider = {
+  name: 'gemini',
+  /**
+   * @param {Array<{role:string,content:string}>} messages
+   * @param {{ apiKey?:string, model?:string, baseUrl?:string, fetch?:typeof fetch, signal?:AbortSignal, system?:string }} opts
+   */
+  async *sendMessage(messages, opts = {}) {
+    if (!opts.apiKey) throw new InvalidApiKeyError('missing api key');
+    const fetchFn = opts.fetch || globalThis.fetch;
+    if (!fetchFn) throw new Error('gemini: no fetch implementation available');
+    const baseUrl = (opts.baseUrl || DEFAULT_BASE).replace(/\/$/, '');
+    const model = opts.model || 'gemini-1.5-pro';
+
+    if (opts.signal?.aborted) throw new AbortError('aborted before request');
+
+    const url = `${baseUrl}/models/${encodeURIComponent(model)}:streamGenerateContent?alt=sse&key=${encodeURIComponent(opts.apiKey)}`;
+    const res = await fetchFn(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(toGeminiBody(messages, opts)),
+      signal: opts.signal,
+    });
+
+    if (!res.ok) {
+      const text = typeof res.text === 'function' ? await res.text() : '';
+      if (res.status === 401 || res.status === 403) throw new InvalidApiKeyError(text || 'unauthorized');
+      if (res.status === 429) throw new RateLimitError(parseRetryAfterMs(res.headers), text || '');
+      throw new ApiError(res.status, text || '');
+    }
+
+    const decoder = new TextDecoder('utf-8', { fatal: false });
+    let buffer = '';
+    for await (const chunk of iterateBody(res.body)) {
+      if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
+      buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+      let consumed = 0;
+      for (const frame of parseSseFrames(buffer)) {
+        consumed = frame.nextCursor;
+        if (!frame.data) continue;
+        try {
+          const obj = JSON.parse(frame.data);
+          // Gemini may stream multiple parts; concatenate any text fields
+          // we recognize. The path is candidates[0].content.parts[*].text.
+          const parts = obj?.candidates?.[0]?.content?.parts;
+          if (Array.isArray(parts)) {
+            for (const p of parts) {
+              if (typeof p?.text === 'string' && p.text) yield p.text;
+            }
+          }
+          // Some error responses surface mid-stream as {error: {...}}.
+          if (obj?.error) {
+            const message = obj.error.message || JSON.stringify(obj.error);
+            throw new ApiError(obj.error.code || 500, message);
+          }
+        } catch (err) {
+          if (err instanceof ApiError) throw err;
+          // malformed frame — skip and keep streaming
+        }
+      }
+      if (consumed > 0) buffer = buffer.slice(consumed);
+    }
+  },
+};
+
+export { InvalidApiKeyError, ApiError, AbortError, RateLimitError };

package/providers/ollama.mjs

@@ -0,0 +1,148 @@
+// Ollama local-model streaming provider.
+//
+// Endpoint: POST {baseUrl}/api/chat (default baseUrl http://127.0.0.1:11434)
+// Body: { model, messages: [{role, content}], stream: true }
+// Response: newline-delimited JSON, one object per chunk:
+//   {"message":{"role":"assistant","content":"hi"},"done":false}
+//   {"done":true,"prompt_eval_count":N,"eval_count":N,...}
+//
+// Differences from anthropic/openai:
+//   - No auth; opts.apiKey is ignored. We still accept it so the registry
+//     `providers list` shape stays uniform.
+//   - opts.baseUrl overrides the default endpoint (env OLLAMA_HOST also
+//     respected so a single env var aligns this with the dashboard).
+//   - opts.fetch test seam mirrors the other providers.
+//
+// Tools / thinking are not part of Ollama's chat API; we silently drop
+// those opts rather than 400-ing so callers can swap providers without
+// changing surrounding code.
+
+const DEFAULT_BASE = 'http://127.0.0.1:11434';
+
+class AbortError extends Error {
+  constructor(message = 'aborted') {
+    super(message);
+    this.name = 'AbortError';
+    this.code = 'ABORT';
+  }
+}
+
+class ApiError extends Error {
+  constructor(status, body) {
+    super(`ollama api ${status}: ${String(body).slice(0, 200)}`);
+    this.name = 'OllamaApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class ConnectionError extends Error {
+  constructor(baseUrl, cause) {
+    super(`ollama: cannot reach ${baseUrl} (is the daemon running?)`);
+    this.name = 'OllamaConnectionError';
+    this.code = 'CONNECTION_REFUSED';
+    this.cause = cause;
+  }
+}
+
+async function* iterateBody(body) {
+  if (body && typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) yield value;
+    }
+    return;
+  }
+  if (body && typeof body[Symbol.asyncIterator] === 'function') {
+    for await (const chunk of body) yield chunk;
+    return;
+  }
+  if (typeof body === 'string') { yield new TextEncoder().encode(body); return; }
+  if (body instanceof Uint8Array) { yield body; return; }
+  throw new Error('ollama: response body is not iterable');
+}
+
+export const ollamaProvider = {
+  name: 'ollama',
+  /**
+   * @param {Array<{role:string,content:string}>} messages
+   * @param {{ model?:string, baseUrl?:string, fetch?:typeof fetch, signal?:AbortSignal, system?:string }} opts
+   */
+  async *sendMessage(messages, opts = {}) {
+    const fetchFn = opts.fetch || globalThis.fetch;
+    if (!fetchFn) throw new Error('ollama: no fetch implementation available');
+    const baseUrl = (opts.baseUrl || process.env.OLLAMA_HOST || DEFAULT_BASE).replace(/\/$/, '');
+    const model = opts.model || 'llama3.1';
+
+    const apiMessages = [];
+    const sys = opts.system || messages.find(m => m.role === 'system')?.content;
+    if (sys) apiMessages.push({ role: 'system', content: String(sys) });
+    for (const m of messages) {
+      if (m.role === 'user' || m.role === 'assistant') {
+        apiMessages.push({ role: m.role, content: String(m.content ?? '') });
+      }
+    }
+
+    if (opts.signal?.aborted) throw new AbortError('aborted before request');
+
+    let res;
+    try {
+      res = await fetchFn(`${baseUrl}/api/chat`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model, messages: apiMessages, stream: true }),
+        signal: opts.signal,
+      });
+    } catch (err) {
+      // Distinguish "ollama isn't running" from generic network errors so
+      // callers can show a useful prompt ("brew services start ollama")
+      // instead of a confusing fetch trace.
+      if (err && (err.cause?.code === 'ECONNREFUSED' || err.code === 'ECONNREFUSED' || /ECONNREFUSED|fetch failed/i.test(String(err.message)))) {
+        throw new ConnectionError(baseUrl, err);
+      }
+      throw err;
+    }
+
+    if (!res.ok) {
+      const text = typeof res.text === 'function' ? await res.text() : '';
+      throw new ApiError(res.status, text || '');
+    }
+
+    const decoder = new TextDecoder('utf-8', { fatal: false });
+    let buffer = '';
+    for await (const chunk of iterateBody(res.body)) {
+      if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
+      buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+      // Ollama is newline-delimited JSON, not SSE — split on '\n', parse
+      // each non-empty line, leave trailing partial behind for the next read.
+      let nl;
+      while ((nl = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        if (!line.trim()) continue;
+        try {
+          const obj = JSON.parse(line);
+          if (obj?.message?.content) yield obj.message.content;
+          if (obj?.done) return;
+          if (obj?.error) throw new ApiError(500, obj.error);
+        } catch (err) {
+          if (err instanceof ApiError) throw err;
+          // malformed line — skip and keep streaming
+        }
+      }
+    }
+    // Any trailing bytes the decoder still holds onto get flushed and
+    // parsed once. Empty after a clean stream.
+    const tail = decoder.decode();
+    if (tail.trim()) {
+      try {
+        const obj = JSON.parse(tail);
+        if (obj?.message?.content) yield obj.message.content;
+      } catch { /* malformed tail — drop */ }
+    }
+  },
+};
+
+export { ApiError, AbortError, ConnectionError };

package/providers/openai.mjs

@@ -0,0 +1,243 @@
+// OpenAI Chat Completions API streaming provider.
+//
+// Format reference (matches OpenClaw and the OpenAI SDK shape):
+//   POST https://api.openai.com/v1/chat/completions
+//   Authorization: Bearer <key>
+//   {"model": "...", "stream": true, "messages": [...]}
+//
+// SSE body: each frame is `data: <json>\n\n`. Terminator is the literal
+// `data: [DONE]\n\n`. Token text lives at `choices[0].delta.content`.
+//
+// Test seam mirrors the Anthropic provider: opts.fetch overrides
+// globalThis.fetch, opts.maxTokens caps `max_tokens`, opts.system seeds
+// a system message.
+
+const DEFAULT_MAX_TOKENS = 4096;
+
+class InvalidApiKeyError extends Error {
+  constructor(message = 'invalid OpenAI api key') {
+    super(message);
+    this.name = 'InvalidApiKeyError';
+    this.code = 'INVALID_KEY';
+  }
+}
+
+class AbortError extends Error {
+  constructor(message = 'aborted') {
+    super(message);
+    this.name = 'AbortError';
+    this.code = 'ABORT';
+  }
+}
+
+class RateLimitError extends Error {
+  constructor(retryAfterMs, body = '') {
+    super(`openai api 429: rate limited (retry-after ${retryAfterMs}ms)`);
+    this.name = 'RateLimitError';
+    this.code = 'RATE_LIMIT';
+    this.status = 429;
+    this.retryAfterMs = retryAfterMs;
+    this.body = body;
+  }
+}
+
+class ApiError extends Error {
+  constructor(status, body) {
+    super(`openai api ${status}: ${String(body).slice(0, 200)}`);
+    this.name = 'OpenAiApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function parseRetryAfterMs(headers) {
+  let raw = null;
+  if (headers && typeof headers.get === 'function') raw = headers.get('retry-after') || headers.get('Retry-After');
+  else if (headers) raw = headers['retry-after'] || headers['Retry-After'];
+  if (!raw) return 1000;
+  const asInt = parseInt(String(raw), 10);
+  if (!Number.isNaN(asInt)) return Math.max(0, asInt * 1000);
+  const date = Date.parse(String(raw));
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return 1000;
+}
+
+async function* iterateBody(body) {
+  if (body && typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) yield value;
+    }
+    return;
+  }
+  if (body && typeof body[Symbol.asyncIterator] === 'function') {
+    for await (const chunk of body) yield chunk;
+    return;
+  }
+  if (typeof body === 'string') { yield new TextEncoder().encode(body); return; }
+  if (body instanceof Uint8Array) { yield body; return; }
+  throw new Error('openai: response body is not iterable');
+}
+
+function* parseSseFrames(buffer) {
+  let cursor = 0;
+  while (true) {
+    const sep = buffer.indexOf('\n\n', cursor);
+    if (sep < 0) break;
+    const frame = buffer.slice(cursor, sep);
+    cursor = sep + 2;
+    const dataLines = [];
+    for (const line of frame.split('\n')) {
+      if (line.startsWith('data:')) dataLines.push(line.slice(5).trim());
+    }
+    if (dataLines.length > 0) yield { data: dataLines.join('\n'), nextCursor: cursor };
+    else yield { data: '', nextCursor: cursor };
+  }
+}
+
+export const openaiProvider = {
+  name: 'openai',
+  /**
+   * @param {Array<{role:string,content:string}>} messages
+   * @param {{apiKey?:string, model?:string, fetch?:typeof fetch, maxTokens?:number, system?:string}} opts
+   */
+  async *sendMessage(messages, opts = {}) {
+    if (!opts.apiKey) throw new InvalidApiKeyError('missing api key');
+    const fetchFn = opts.fetch || globalThis.fetch;
+    if (!fetchFn) throw new Error('openai: no fetch implementation available');
+
+    const model = opts.model || 'gpt-4.1';
+    const apiMessages = [];
+    const sys = opts.system || messages.find(m => m.role === 'system')?.content;
+    if (sys) apiMessages.push({ role: 'system', content: String(sys) });
+    for (const m of messages) {
+      if (m.role === 'user' || m.role === 'assistant') {
+        apiMessages.push({ role: m.role, content: String(m.content ?? '') });
+      }
+    }
+
+    const body = {
+      model,
+      max_tokens: opts.maxTokens || DEFAULT_MAX_TOKENS,
+      stream: true,
+      messages: apiMessages,
+    };
+    // Tool-use passthrough mirrors the anthropic provider: opts.tools is an
+    // array of OpenAI-shaped tools. opts.toolChoice maps to tool_choice.
+    if (Array.isArray(opts.tools) && opts.tools.length > 0) {
+      body.tools = opts.tools;
+      if (opts.toolChoice) body.tool_choice = opts.toolChoice;
+    }
+    // Usage capture is opt-in via stream_options. We only request it when
+    // the caller provided an onUsage callback — otherwise we'd be paying
+    // for an extra response field we'd just throw away. The shape comes
+    // back as a top-level `usage` field on a final chunk that has empty
+    // choices, right before `[DONE]`.
+    if (typeof opts.onUsage === 'function') {
+      body.stream_options = { include_usage: true };
+    }
+
+    if (opts.signal?.aborted) throw new AbortError('aborted before request');
+    const res = await fetchFn('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'authorization': `Bearer ${opts.apiKey}`,
+      },
+      body: JSON.stringify(body),
+      signal: opts.signal,
+    });
+
+    if (!res.ok) {
+      const text = typeof res.text === 'function' ? await res.text() : '';
+      if (res.status === 401 || res.status === 403) throw new InvalidApiKeyError(text || 'unauthorized');
+      if (res.status === 429) throw new RateLimitError(parseRetryAfterMs(res.headers), text || '');
+      throw new ApiError(res.status, text || '');
+    }
+
+    const decoder = new TextDecoder('utf-8', { fatal: false });
+    let buffer = '';
+    // Usage accumulator. With stream_options.include_usage, the final
+    // pre-[DONE] chunk carries `usage` at top level: {prompt_tokens,
+    // completion_tokens, total_tokens}. We collect into a normalized
+    // shape that mirrors the anthropic provider's onUsage payload so
+    // callers don't have to special-case per provider.
+    let usage = null;
+    // OpenAI streams tool_calls as deltas with an `index` we use as the
+    // accumulation key. Each delta may carry a partial id, name, and/or
+    // arguments string. We assemble until the stream signals
+    // finish_reason: tool_calls (the final tool_call delta in that choice).
+    const toolCallsByIndex = new Map();
+    const flushToolCall = (idx) => {
+      const tc = toolCallsByIndex.get(idx);
+      if (!tc || !tc.function?.name) return;
+      toolCallsByIndex.delete(idx);
+      if (typeof opts.onToolUse !== 'function') return;
+      let input = {};
+      try { input = tc.function.arguments ? JSON.parse(tc.function.arguments) : {}; }
+      catch { /* malformed → empty + raw */ }
+      try {
+        opts.onToolUse({
+          id: tc.id || null,
+          name: tc.function.name,
+          input,
+          raw: tc.function.arguments || '',
+        });
+      } catch { /* never let a callback abort the stream */ }
+    };
+    for await (const chunk of iterateBody(res.body)) {
+      if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
+      buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+      let consumed = 0;
+      for (const frame of parseSseFrames(buffer)) {
+        consumed = frame.nextCursor;
+        if (!frame.data) continue;
+        if (frame.data === '[DONE]') {
+          // Drain any tool calls that haven't been flushed by finish_reason.
+          for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
+          if (usage && typeof opts.onUsage === 'function') {
+            try { opts.onUsage(usage); } catch { /* never let a callback abort */ }
+          }
+          return;
+        }
+        try {
+          const obj = JSON.parse(frame.data);
+          // Usage frame: top-level `usage` (no choices content). Capture
+          // and continue — the final stream terminator [DONE] still emits.
+          if (obj?.usage && typeof obj.usage === 'object') {
+            usage = {
+              inputTokens: obj.usage.prompt_tokens ?? null,
+              outputTokens: obj.usage.completion_tokens ?? null,
+              totalTokens: obj.usage.total_tokens ?? null,
+            };
+          }
+          const choice = obj?.choices?.[0];
+          const delta = choice?.delta || {};
+          if (delta.content) yield delta.content;
+          if (Array.isArray(delta.tool_calls)) {
+            for (const td of delta.tool_calls) {
+              const idx = td.index ?? 0;
+              const cur = toolCallsByIndex.get(idx) || { id: null, function: { name: '', arguments: '' } };
+              if (td.id) cur.id = td.id;
+              if (td.function?.name) cur.function.name = td.function.name;
+              if (typeof td.function?.arguments === 'string') cur.function.arguments += td.function.arguments;
+              toolCallsByIndex.set(idx, cur);
+            }
+          }
+          if (choice?.finish_reason === 'tool_calls') {
+            for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
+          }
+        } catch {
+          // Ignore malformed frames; keep scanning the rest of the buffer.
+        }
+      }
+      if (consumed > 0) buffer = buffer.slice(consumed);
+    }
+    const tail = decoder.decode();
+    if (tail) buffer += tail;
+  },
+};
+
+export { InvalidApiKeyError, ApiError, AbortError, RateLimitError };

package/providers/rates.mjs

@@ -0,0 +1,85 @@
+// Token → currency conversion helper.
+//
+// Why no shipped rate card:
+//   - Provider prices change. Hardcoding them sets up the library to
+//     silently lie about cost the moment a price moves.
+//   - Different teams negotiate different deals (volume contracts,
+//     regional pricing, provider-managed proxies). A single global
+//     default would be wrong for most users.
+//
+// Shape:
+//   const rates = {
+//     'anthropic/claude-opus-4-7': {
+//       inputPer1M: 15.00,
+//       outputPer1M: 75.00,
+//       cacheReadPer1M: 1.50,
+//       cacheCreatePer1M: 18.75,
+//       currency: 'USD',
+//     },
+//     'openai/gpt-4.1': { inputPer1M: 2.00, outputPer1M: 8.00, currency: 'USD' },
+//   };
+//
+// `costFromUsage({provider, model, usage}, rates)` returns
+//   { cost, currency, breakdown }
+// where breakdown shows the per-bucket charge so callers can audit.
+//
+// Rates are per *million* tokens because that's how every provider
+// publishes them — multiplying tokens/1_000_000 keeps the arithmetic
+// readable in tests.
+
+/**
+ * @param {{ provider: string, model: string, usage: object }} call
+ * @param {Record<string, { inputPer1M: number, outputPer1M: number,
+ *   cacheReadPer1M?: number, cacheCreatePer1M?: number,
+ *   currency?: string }>} rates
+ * @returns {{ cost: number, currency: string, breakdown: object } | null}
+ */
+export function costFromUsage(call, rates) {
+  if (!call || !rates) return null;
+  const key = `${call.provider}/${call.model}`;
+  const r = rates[key];
+  if (!r) return null;
+  const u = call.usage || {};
+  const million = 1_000_000;
+  const inputCost = ((Number(u.inputTokens) || 0) / million) * (Number(r.inputPer1M) || 0);
+  const outputCost = ((Number(u.outputTokens) || 0) / million) * (Number(r.outputPer1M) || 0);
+  // Cache fields only contribute when both rate and usage are present.
+  const cacheReadCost = (Number(u.cacheReadInputTokens) > 0 && Number(r.cacheReadPer1M) > 0)
+    ? (u.cacheReadInputTokens / million) * r.cacheReadPer1M : 0;
+  const cacheCreateCost = (Number(u.cacheCreationInputTokens) > 0 && Number(r.cacheCreatePer1M) > 0)
+    ? (u.cacheCreationInputTokens / million) * r.cacheCreatePer1M : 0;
+  return {
+    cost: round6(inputCost + outputCost + cacheReadCost + cacheCreateCost),
+    currency: r.currency || 'USD',
+    breakdown: {
+      input: round6(inputCost),
+      output: round6(outputCost),
+      cacheRead: round6(cacheReadCost),
+      cacheCreate: round6(cacheCreateCost),
+    },
+  };
+}
+
+function round6(n) {
+  // Six decimals → fractions of a cent at sub-USD prices, while still
+  // rounding away IEEE-754 noise from the 1/1_000_000 division.
+  return Math.round(n * 1_000_000) / 1_000_000;
+}
+
+/**
+ * Reference shape so callers can copy-paste a starting point and edit
+ * with their own current rates. The numbers here are deliberately
+ * placeholders (zeros) — see this module's header for why we don't
+ * ship real prices.
+ */
+export const RATE_CARD_SHAPE = {
+  'anthropic/claude-opus-4-7': {
+    inputPer1M: 0, outputPer1M: 0,
+    cacheReadPer1M: 0, cacheCreatePer1M: 0,
+    currency: 'USD',
+  },
+  'openai/gpt-4.1': {
+    inputPer1M: 0, outputPer1M: 0,
+    currency: 'USD',
+  },
+};