cachegate 1.3.0 → 1.4.0

package/metrics.js

@@ -105,6 +105,11 @@ async function ensureSchema() {
         error_type TEXT
       );
       ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS scope TEXT;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS coalesced BOOLEAN;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS quality_score REAL;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS cascaded BOOLEAN;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS trace_id TEXT;
+      ALTER TABLE router_metrics ADD COLUMN IF NOT EXISTS joined_trace_id TEXT;
       CREATE INDEX IF NOT EXISTS router_metrics_ts_idx ON router_metrics (ts DESC);
       CREATE INDEX IF NOT EXISTS router_metrics_provider_ts_idx ON router_metrics (provider, ts DESC);
       CREATE INDEX IF NOT EXISTS router_metrics_scope_ts_idx ON router_metrics (scope, ts DESC);
@@ -127,6 +132,11 @@ function rowFromPg(dbRow) {
     model: dbRow.model || undefined,
     requested_model: dbRow.requested_model || undefined,
     cache_hit: dbRow.cache_hit === null ? undefined : dbRow.cache_hit,
+    coalesced: dbRow.coalesced === null ? undefined : dbRow.coalesced,
+    cascaded: dbRow.cascaded === null ? undefined : dbRow.cascaded,
+    quality_score: dbRow.quality_score === null ? undefined : dbRow.quality_score,
+    trace_id: dbRow.trace_id || undefined,
+    joined_trace_id: dbRow.joined_trace_id || undefined,
     cache_type: dbRow.cache_type || undefined,
     latency_ms: dbRow.latency_ms === null ? undefined : dbRow.latency_ms,
     cost_usd: dbRow.cost_usd === null ? undefined : dbRow.cost_usd,
@@ -140,19 +150,24 @@ async function recordToPostgres(scope, entry) {
     await ensureSchema();
     await getPool().query(
       `INSERT INTO router_metrics
-         (scope, provider, model, requested_model, cache_hit, cache_type, latency_ms, cost_usd, error, error_type)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
+         (scope, provider, model, requested_model, cache_hit, coalesced, cascaded, quality_score, cache_type, latency_ms, cost_usd, error, error_type, trace_id, joined_trace_id)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)`,
       [
         scope != null ? String(scope) : null,
         entry.provider ?? null,
         entry.model ?? null,
         entry.requested_model ?? null,
         entry.cache_hit ?? null,
+        entry.coalesced ?? null,
+        entry.cascaded ?? null,
+        entry.quality_score ?? null,
         entry.cache_type ?? null,
         entry.latency_ms ?? null,
         entry.cost_usd ?? null,
         entry.error ?? null,
-        entry.error_type ?? null
+        entry.error_type ?? null,
+        entry.trace_id ?? null,
+        entry.joined_trace_id ?? null
       ]
     );
   } catch (err) {
@@ -358,8 +373,10 @@ function ensureWriteStream() {
  */
 function record(scope, entry) {
   if (usingPostgres()) {
-    recordToPostgres(scope, entry); // fire-and-forget - see its own comment
-    return;
+    // Returns the INSERT promise so tests/scripts can await it; request
+    // paths ignore it, so it stays fire-and-forget for them (a metrics
+    // write must never be the reason a real request fails or slows down).
+    return recordToPostgres(scope, entry);
   }
   try {
     const line = JSON.stringify({
@@ -425,6 +442,13 @@ async function providerStats(scope, windowSize = 50) {
     const avgLatencyMs = latencies.length
       ? latencies.reduce((sum, e) => sum + e.latency_ms, 0) / latencies.length
       : null;
+    // Mean quality across entries that actually HAVE a quality_score
+    // (cache hits, coalesced joiners, and pre-this-change rows don't set
+    // one) - same null-tolerant pattern avgLatencyMs uses for latency.
+    const qualityScores = recent.filter((e) => typeof e.quality_score === 'number');
+    const avgQualityScore = qualityScores.length
+      ? qualityScores.reduce((sum, e) => sum + e.quality_score, 0) / qualityScores.length
+      : null;
     // The MOST RECENT error only, not a tally of every type seen in the
     // window - an alert should reflect "what's wrong right now," not a
     // mix that might include something already fixed earlier in the
@@ -437,6 +461,7 @@ async function providerStats(scope, windowSize = 50) {
       sampleSize: recent.length,
       errorRate: recent.length ? errorEntries.length / recent.length : 0,
       avgLatencyMs,
+      avgQualityScore,
       lastErrorType: lastError ? lastError.error_type || classifyErrorType(lastError.error) : null,
       lastErrorAt: lastError ? lastError.timestamp : null
     };
@@ -470,6 +495,61 @@ async function providerStats(scope, windowSize = 50) {
  * underlying log, two different questions - not accidentally
  * duplicated logic.
  */
+
+// Shared "$ saved" formula (mirrors cachegate-cloud's usage.mjs
+// estimatedSavings / estimatedSavingsGlobal, 2026-09-05 Phase 2 step 20):
+// for each model, the average cost of a cache-MISS (cache_hit === false,
+// no error) times that model's cache-HIT count, summed across models. A
+// model with hits but no recorded miss yet contributes 0 - never a
+// cross-model average (usage.mjs's own documented honesty floor). Rows
+// with no model are skipped. Pure (takes rows, returns { total, perDay })
+// so it's directly unit-testable and shared by rangeSummary() and
+// server.js's GET /stats without duplicating the formula.
+function computeSavings(rows) {
+  const all = new Map(); // model -> accumulator
+  const perDay = new Map(); // YYYY-MM-DD -> Map(model -> accumulator)
+  const accFor = (map, key) => {
+    let acc = map.get(key);
+    if (!acc) {
+      acc = { missCostSum: 0, missCount: 0, hits: 0 };
+      map.set(key, acc);
+    }
+    return acc;
+  };
+  for (const row of rows) {
+    if (!row.model) continue;
+    const acc = accFor(all, row.model);
+    const date = row.timestamp.slice(0, 10);
+    let dayMap = perDay.get(date);
+    if (!dayMap) {
+      dayMap = new Map();
+      perDay.set(date, dayMap);
+    }
+    const dayAcc = accFor(dayMap, row.model);
+    if (row.cache_hit === true) {
+      acc.hits += 1;
+      dayAcc.hits += 1;
+    } else if (row.cache_hit === false && !row.error) {
+      acc.missCostSum += row.cost_usd || 0;
+      acc.missCount += 1;
+      dayAcc.missCostSum += row.cost_usd || 0;
+      dayAcc.missCount += 1;
+    }
+  }
+  const sum = (map) => {
+    let total = 0;
+    for (const acc of map.values()) {
+      if (acc.hits > 0 && acc.missCount > 0) {
+        total += (acc.missCostSum / acc.missCount) * acc.hits;
+      }
+    }
+    return total;
+  };
+  const out = new Map();
+  for (const [date, map] of perDay) out.set(date, sum(map));
+  return { total: sum(all), perDay: out };
+}
+
 async function rangeSummary(scope, days = 14) {
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
 
@@ -506,7 +586,7 @@ async function rangeSummary(scope, days = 14) {
   for (const row of inRange) {
     const date = row.timestamp.slice(0, 10); // YYYY-MM-DD (UTC, from toISOString())
     if (!dailyByDate.has(date)) {
-      dailyByDate.set(date, { date, requests: 0, cost_usd: 0, exact_hits: 0, semantic_hits: 0, misses: 0, errors: 0 });
+      dailyByDate.set(date, { date, requests: 0, cost_usd: 0, saved_usd: 0, exact_hits: 0, semantic_hits: 0, misses: 0, errors: 0 });
     }
     const bucket = dailyByDate.get(date);
     bucket.requests += 1;
@@ -539,6 +619,8 @@ async function rangeSummary(scope, days = 14) {
     }
   }
 
+  const savings = computeSavings(inRange);
+
   const providerSummary = {};
   for (const [name, p] of Object.entries(byProvider)) {
     providerSummary[name] = {
@@ -553,6 +635,7 @@ async function rangeSummary(scope, days = 14) {
     days,
     sample_size: inRange.length,
     total_cost_usd: totalCostUsd,
+    saved_usd: savings.total,
     cache_hit_rate: {
       exact: inRange.length ? exactHits / inRange.length : 0,
       semantic: inRange.length ? semanticHits / inRange.length : 0,
@@ -560,7 +643,9 @@ async function rangeSummary(scope, days = 14) {
     },
     error_rate: inRange.length ? errors / inRange.length : 0,
     by_provider: providerSummary,
-    daily: [...dailyByDate.values()].sort((a, b) => a.date.localeCompare(b.date))
+    daily: [...dailyByDate.values()]
+      .sort((a, b) => a.date.localeCompare(b.date))
+      .map((d) => ({ ...d, saved_usd: savings.perDay.get(d.date) || 0 }))
   };
 }
 
@@ -645,6 +730,7 @@ module.exports = {
   readRecent,
   providerStats,
   rangeSummary,
+  computeSavings,
   pruneOlderThan,
   pruneScopedOlderThan,
   currentLogPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cachegate",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Self-hostable, OpenAI-compatible LLM proxy: routes to the cheapest healthy provider, caches responses exactly and semantically, tracks cost and latency per call.",
   "license": "MIT",
   "main": "server.js",
@@ -10,13 +10,18 @@
   "files": [
     "server.js",
     "cache.js",
+    "cascade.js",
+    "coalescing.js",
     "embeddings.js",
     "failover.js",
+    "guardrails.js",
     "metrics.js",
+    "pii.js",
     "redisClient.js",
     "router.js",
     "semanticCache.js",
     "streaming.js",
+    "tracing.js",
     "providers/",
     "public/",
     ".env.example"
@@ -26,10 +31,15 @@
   },
   "scripts": {
     "start": "node server.js",
-    "test": "node --test"
+    "test": "node --test",
+    "eval:semantic-cache": "node eval/semantic-cache-eval.js"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.115.0",
+    "@huggingface/transformers": "^3.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/sdk-node": "^0.222.0",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
     "express-rate-limit": "^8.6.2",

package/pii.js

@@ -0,0 +1,128 @@
+// model-router/pii.js
+//
+// Pattern-based PII detection + redaction (roadmap step 25, PII track).
+// Gated behind GUARDRAILS_PII_REDACTION (default OFF, same off-by-default
+// convention as step 22's local embeddings) - ships fully inert until a
+// deployment opts in. Standalone for now: NOT wired into server.js yet
+// (see the step 25 kickoff directive) - this module only exposes the
+// detection/redaction primitive; the pre-dispatch request-path wiring
+// (and the coordination with the injection/policy track it needs to
+// share a hook shape with) is a separate, joint follow-up change.
+//
+// Deliberately pattern/regex based, not a model call: PII redaction has
+// to be synchronous, fast (it would run on every request, not just
+// cache misses), and free of its own network dependency - a step whose
+// whole job is stripping sensitive content out of a request shouldn't
+// itself be a network hop that could leak that content to a third party.
+//
+// Redaction never surfaces the actual matched value anywhere, even in
+// its own return value - only { type, count } counters. A false
+// positive costs an unnecessary redaction (annoying); a leaked value in
+// a log or a metrics row costs an actual PII exposure. This module is
+// built to make the cheaper mistake.
+
+// Order matters: more specific/longer patterns run first, so a token
+// that could satisfy two shapes (e.g. a 16-digit run also containing a
+// phone-shaped substring) is claimed by the more specific match before
+// a looser pattern gets a chance to partially match what's left of it.
+const PATTERNS = [
+  {
+    type: 'email',
+    regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
+  },
+  {
+    type: 'credit_card',
+    // 13-19 digits, optionally grouped by single spaces or dashes
+    // between digits (covers both "4111111111111111" and
+    // "4111 1111 1111 1111"/"4111-1111-1111-1111"). Matched by shape
+    // first, then narrowed by a Luhn checksum below - shape alone would
+    // false-positive on any long unrelated digit run (an order id, a
+    // padded invoice number).
+    regex: /\b(?:\d[ -]?){12,18}\d\b/g,
+    validate: (match) => luhnValid(match.replace(/[ -]/g, ''))
+  },
+  {
+    type: 'ssn',
+    // US SSN: NNN-NN-NNNN. Dashes required - a bare 9-digit run is too
+    // easy to confuse with an account/phone number to redact safely
+    // without a much higher false-positive rate.
+    regex: /\b\d{3}-\d{2}-\d{4}\b/g
+  },
+  {
+    type: 'phone',
+    // NA-style, requiring at least one separator (space/dash/dot/
+    // parens) - a bare 10-digit run is left to the credit-card pattern
+    // above (which needs 13+ digits, so no real overlap) rather than
+    // guessed at here. Uses digit lookaround, not \b, at both ends: a
+    // leading "(" is itself a non-word character, so a \b right before
+    // it never matches (word-boundary needs one word char and one
+    // non-word char either side) - \b would let the engine skip past a
+    // real "(555)" opening paren and leave it un-redacted outside the
+    // match. (?<!\d)/(?!\d) only cares that the run isn't glued to more
+    // digits, which is what actually needs guarding against here.
+    regex: /(?<!\d)(?:\+?1[ .-]?)?\(?\d{3}\)?[ .-]\d{3}[ .-]\d{4}(?!\d)/g
+  },
+  {
+    type: 'api_key',
+    // Common vendor secret shapes (OpenAI classic "sk-...", OpenAI
+    // project-scoped "sk-proj-...", Anthropic "sk-ant-...", AWS,
+    // GitHub, Slack, Google) - opaque tokens like these are exactly the
+    // kind of thing that ends up pasted into a prompt by accident. The
+    // "sk-" body allows dashes/underscores, not just alphanumerics, so
+    // it covers the dash-separated "-proj-"/"-ant-" variants too rather
+    // than needing one alternative per vendor prefix.
+    regex: /\b(?:sk-[a-zA-Z0-9_-]{20,}|AKIA[0-9A-Z]{16}|gh[pousr]_[a-zA-Z0-9]{20,}|xox[baprs]-[a-zA-Z0-9-]{10,}|AIza[0-9A-Za-z_-]{35})\b/g
+  }
+];
+
+function luhnValid(digits) {
+  let sum = 0;
+  let alternate = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = Number(digits[i]);
+    if (alternate) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alternate = !alternate;
+  }
+  return sum % 10 === 0;
+}
+
+function isEnabled() {
+  return process.env.GUARDRAILS_PII_REDACTION === 'true';
+}
+
+// redact(text) -> { text, redactions: [{ type, count }] }.
+// Side-effect free and safe to call unconditionally - when the flag is
+// off, returns the text UNCHANGED (not an error, not a throw), same
+// "always callable, flag decides" shape as embeddings.js's isEnabled().
+function redact(text) {
+  if (!isEnabled() || typeof text !== 'string' || text.length === 0) {
+    return { text, redactions: [] };
+  }
+
+  let result = text;
+  const counts = new Map();
+
+  for (const { type, regex, validate } of PATTERNS) {
+    // A fresh RegExp per pattern per call: the source patterns are
+    // global (/g), and a shared stateful regex's lastIndex would
+    // corrupt matching across concurrent/repeated calls in a
+    // long-running process handling many requests.
+    const re = new RegExp(regex.source, regex.flags);
+    result = result.replace(re, (match) => {
+      if (validate && !validate(match)) return match; // shape matched but failed validation - leave as-is
+      counts.set(type, (counts.get(type) || 0) + 1);
+      return `[REDACTED_${type.toUpperCase()}]`;
+    });
+  }
+
+  return {
+    text: result,
+    redactions: Array.from(counts.entries()).map(([type, count]) => ({ type, count }))
+  };
+}
+
+module.exports = { isEnabled, redact };

package/providers/anthropic.js

@@ -1,122 +1,122 @@
-// model-router/providers/anthropic.js
-const { Anthropic } = require('@anthropic-ai/sdk');
-
-function buildClient(apiKey) {
-  return new Anthropic({ apiKey });
-}
-
-function estimateCost(model, inputTokens, outputTokens) {
-  // Approximate pricing per 1M tokens — update as Anthropic changes rates
-  const rates = {
-    'claude-sonnet-4-5-20250929': { input: 3.0, output: 15.0 },
-    'claude-haiku-4-5-20251001': { input: 0.8, output: 4.0 },
-    'claude-3-5-sonnet-20241022': { input: 3.0, output: 15.0 },
-    'claude-3-5-sonnet-20240620': { input: 3.0, output: 15.0 }
-  };
-  const rate = rates[model] || { input: 3.0, output: 15.0 };
-  return ((inputTokens * rate.input) + (outputTokens * rate.output)) / 1_000_000;
-}
-
-async function chat(client, payload) {
-  const systemMessage = payload.messages.find(m => m.role === 'system');
-  const userMessages = payload.messages.filter(m => m.role !== 'system');
-
-  const request = {
-    model: payload.model,
-    max_tokens: payload.max_tokens || 1024,
-    temperature: typeof payload.temperature === 'number' ? payload.temperature : 0.0,
-    messages: userMessages,
-    ...(systemMessage && { system: systemMessage.content }),
-    ...(payload.tools && { tools: payload.tools }),
-    ...(payload.tool_choice && { tool_choice: payload.tool_choice })
-  };
-
-  const start = Date.now();
-  const response = await client.messages.create(request);
-  const latencyMs = Date.now() - start;
-
-  const inputTokens = response.usage.input_tokens;
-  const outputTokens = response.usage.output_tokens;
-  const costUsd = estimateCost(payload.model, inputTokens, outputTokens);
-
-  const toolCall = response.content.find(c => c.type === 'tool_use');
-  const textContent = response.content
-    .filter(c => c.type === 'text')
-    .map(c => c.text)
-    .join('');
-
-  return {
-    provider: 'anthropic',
-    model: payload.model,
-    latency_ms: latencyMs,
-    usage: { input_tokens: inputTokens, output_tokens: outputTokens },
-    cost_usd: costUsd,
-    content: textContent,
-    tool_calls: toolCall ? [toolCall] : undefined,
-    raw: response
-  };
-}
-
-/**
- * Pure state-accumulation for one Anthropic streaming event - factored
- * out from chatStream() so the trickiest part (pulling usage/cost data
- * out of a stream instead of one final response object) is directly
- * unit-testable with canned events, no live API needed. Mutates
- * `state` ({content, inputTokens, outputTokens}) and calls onDelta()
- * with each new piece of assistant text.
- */
-function applyStreamEvent(state, event, onDelta) {
-  if (event.type === 'message_start') {
-    state.inputTokens = event.message.usage.input_tokens;
-    state.outputTokens = event.message.usage.output_tokens || 0;
-  } else if (event.type === 'content_block_delta' && event.delta && event.delta.type === 'text_delta') {
-    state.content += event.delta.text;
-    onDelta(event.delta.text);
-  } else if (event.type === 'message_delta' && event.usage) {
-    // Anthropic reports output_tokens progressively here; the last one
-    // received before message_stop is the final total.
-    state.outputTokens = event.usage.output_tokens;
-  }
-}
-
-/**
- * Streaming counterpart to chat(). Scope: plain text content only - no
- * tools/tool_choice forwarded (server.js rejects stream:true + tools
- * before this is ever called; see streaming.js for why).
- */
-async function chatStream(client, payload, { onDelta, signal } = {}) {
-  const systemMessage = payload.messages.find(m => m.role === 'system');
-  const userMessages = payload.messages.filter(m => m.role !== 'system');
-
-  const request = {
-    model: payload.model,
-    max_tokens: payload.max_tokens || 1024,
-    temperature: typeof payload.temperature === 'number' ? payload.temperature : 0.0,
-    messages: userMessages,
-    ...(systemMessage && { system: systemMessage.content }),
-    stream: true
-  };
-
-  const start = Date.now();
-  const stream = await client.messages.create(request, signal ? { signal } : undefined);
-
-  const state = { content: '', inputTokens: 0, outputTokens: 0 };
-  for await (const event of stream) {
-    applyStreamEvent(state, event, onDelta || (() => {}));
-  }
-
-  const latencyMs = Date.now() - start;
-  const costUsd = estimateCost(payload.model, state.inputTokens, state.outputTokens);
-
-  return {
-    provider: 'anthropic',
-    model: payload.model,
-    latency_ms: latencyMs,
-    usage: { input_tokens: state.inputTokens, output_tokens: state.outputTokens },
-    cost_usd: costUsd,
-    content: state.content,
-    tool_calls: undefined
-  };
-}
-
-module.exports = { buildClient, chat, chatStream, applyStreamEvent, estimateCost };
+// model-router/providers/anthropic.js
+const { Anthropic } = require('@anthropic-ai/sdk');
+
+function buildClient(apiKey) {
+  return new Anthropic({ apiKey });
+}
+
+function estimateCost(model, inputTokens, outputTokens) {
+  // Approximate pricing per 1M tokens — update as Anthropic changes rates
+  const rates = {
+    'claude-sonnet-4-5-20250929': { input: 3.0, output: 15.0 },
+    'claude-haiku-4-5-20251001': { input: 0.8, output: 4.0 },
+    'claude-3-5-sonnet-20241022': { input: 3.0, output: 15.0 },
+    'claude-3-5-sonnet-20240620': { input: 3.0, output: 15.0 }
+  };
+  const rate = rates[model] || { input: 3.0, output: 15.0 };
+  return ((inputTokens * rate.input) + (outputTokens * rate.output)) / 1_000_000;
+}
+
+async function chat(client, payload) {
+  const systemMessage = payload.messages.find(m => m.role === 'system');
+  const userMessages = payload.messages.filter(m => m.role !== 'system');
+
+  const request = {
+    model: payload.model,
+    max_tokens: payload.max_tokens || 1024,
+    temperature: typeof payload.temperature === 'number' ? payload.temperature : 0.0,
+    messages: userMessages,
+    ...(systemMessage && { system: systemMessage.content }),
+    ...(payload.tools && { tools: payload.tools }),
+    ...(payload.tool_choice && { tool_choice: payload.tool_choice })
+  };
+
+  const start = Date.now();
+  const response = await client.messages.create(request);
+  const latencyMs = Date.now() - start;
+
+  const inputTokens = response.usage.input_tokens;
+  const outputTokens = response.usage.output_tokens;
+  const costUsd = estimateCost(payload.model, inputTokens, outputTokens);
+
+  const toolCall = response.content.find(c => c.type === 'tool_use');
+  const textContent = response.content
+    .filter(c => c.type === 'text')
+    .map(c => c.text)
+    .join('');
+
+  return {
+    provider: 'anthropic',
+    model: payload.model,
+    latency_ms: latencyMs,
+    usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+    cost_usd: costUsd,
+    content: textContent,
+    tool_calls: toolCall ? [toolCall] : undefined,
+    raw: response
+  };
+}
+
+/**
+ * Pure state-accumulation for one Anthropic streaming event - factored
+ * out from chatStream() so the trickiest part (pulling usage/cost data
+ * out of a stream instead of one final response object) is directly
+ * unit-testable with canned events, no live API needed. Mutates
+ * `state` ({content, inputTokens, outputTokens}) and calls onDelta()
+ * with each new piece of assistant text.
+ */
+function applyStreamEvent(state, event, onDelta) {
+  if (event.type === 'message_start') {
+    state.inputTokens = event.message.usage.input_tokens;
+    state.outputTokens = event.message.usage.output_tokens || 0;
+  } else if (event.type === 'content_block_delta' && event.delta && event.delta.type === 'text_delta') {
+    state.content += event.delta.text;
+    onDelta(event.delta.text);
+  } else if (event.type === 'message_delta' && event.usage) {
+    // Anthropic reports output_tokens progressively here; the last one
+    // received before message_stop is the final total.
+    state.outputTokens = event.usage.output_tokens;
+  }
+}
+
+/**
+ * Streaming counterpart to chat(). Scope: plain text content only - no
+ * tools/tool_choice forwarded (server.js rejects stream:true + tools
+ * before this is ever called; see streaming.js for why).
+ */
+async function chatStream(client, payload, { onDelta, signal } = {}) {
+  const systemMessage = payload.messages.find(m => m.role === 'system');
+  const userMessages = payload.messages.filter(m => m.role !== 'system');
+
+  const request = {
+    model: payload.model,
+    max_tokens: payload.max_tokens || 1024,
+    temperature: typeof payload.temperature === 'number' ? payload.temperature : 0.0,
+    messages: userMessages,
+    ...(systemMessage && { system: systemMessage.content }),
+    stream: true
+  };
+
+  const start = Date.now();
+  const stream = await client.messages.create(request, signal ? { signal } : undefined);
+
+  const state = { content: '', inputTokens: 0, outputTokens: 0 };
+  for await (const event of stream) {
+    applyStreamEvent(state, event, onDelta || (() => {}));
+  }
+
+  const latencyMs = Date.now() - start;
+  const costUsd = estimateCost(payload.model, state.inputTokens, state.outputTokens);
+
+  return {
+    provider: 'anthropic',
+    model: payload.model,
+    latency_ms: latencyMs,
+    usage: { input_tokens: state.inputTokens, output_tokens: state.outputTokens },
+    cost_usd: costUsd,
+    content: state.content,
+    tool_calls: undefined
+  };
+}
+
+module.exports = { buildClient, chat, chatStream, applyStreamEvent, estimateCost };