claude-code-cache-fix 3.1.1 → 3.2.1

package/proxy/extensions/usage-log.mjs

@@ -1,46 +1,275 @@
+// usage-log — append per-call usage record to ~/.claude/usage.jsonl.
+//
+// The emitted record matches `MeterRowSchema` v:1 from
+// `claude-code-meter/src/log/schema.mjs` exactly. claude-meter validates each
+// row through that schema; the wire format is the cross-repo contract.
+//
+// Schema (every row):
+//   v: 1
+//   ts: ISO datetime
+//   sid: 8-char lowercase hex (proxy session, sticky for proxy lifetime)
+//   model: string ≤64, /^[a-z0-9._-]+$/
+//   requested_model?: string ≤64, /^[a-z0-9._-]*$/  (optional)
+//   model_mismatch?: bool                            (optional)
+//   speed: "standard" | "fast" | ""
+//   service_tier: string ≤32, /^[a-z0-9_-]*$/
+//   input_tokens, output_tokens, cache_creation_input_tokens,
+//   cache_read_input_tokens, ephemeral_1h_input_tokens,
+//   ephemeral_5m_input_tokens, web_search_requests: int ≥ 0
+//   q5h, q7d: float 0–2
+//   q5h_reset, q7d_reset: int (unix sec)
+//   qstatus, qoverage, qclaim: string lowercase enums
+//   qfallback_pct: float 0–1
+//   qoverage_util?: float ≥ 0                        (optional)
+//   qrepresentative_claim?: string ≤16               (optional)
+//   org_id?: 16-char hex (sha256(raw header).digest("hex").slice(0,16))
+//   overage_disabled_reason?: string ≤64             (optional)
+//   cache_hit_rate: float 0–1
+//   q5h_delta, q7d_delta: float (0 on first call after restart)
+//
+// `peak_hour` is NOT in the wire format. It can be derived from `ts` if any
+// consumer needs it.
+//
+// Activation: enabled:false in the export default (existing usage-log
+// pattern). Users opt in by adding an entry to proxy/extensions.json:
+//   "usage-log": { "enabled": true, "order": 650 }
+// CACHE_FIX_USAGE_LOG=<path> overrides the destination path only — it is NOT
+// an enable flag and never has been.
+//
+// See `docs/directives/proxy-claude-meter-compat.md` for full design.
+
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 
 const LOG_PATH = process.env.CACHE_FIX_USAGE_LOG || join(homedir(), ".claude", "usage.jsonl");
 
-function buildRecord(meta, telemetry, responseHeaders) {
-  const now = new Date();
-  const utcHour = now.getUTCHours();
-  const utcDay = now.getUTCDay();
+// --- Module-scope state ---
+
+const _sid = generateSid();
+let _lastQ5h = null;
+let _lastQ7d = null;
+
+// --- Pure helpers (test seam) ---
 
-  const stats = meta.cacheStats || {};
-  const quota = meta._quotaData || {};
+export function generateSid() {
+  return createHash("sha256")
+    .update(`${process.pid}-${Date.now()}-${Math.random()}`)
+    .digest("hex")
+    .slice(0, 8);
+}
+
+export function hashOrgId(rawOrgId) {
+  if (!rawOrgId || typeof rawOrgId !== "string") return undefined;
+  return createHash("sha256").update(rawOrgId).digest("hex").slice(0, 16);
+}
 
+export function extractMessageStartFields(event) {
+  if (!event || event.type !== "message_start") return null;
+  const msg = event.message;
+  if (!msg || !msg.usage) return null;
+  const usage = msg.usage;
+  const cc = usage.cache_creation || {};
+  const sti = usage.server_tool_use || {};
   return {
-    timestamp: now.toISOString(),
-    model: telemetry.model || "unknown",
-    input_tokens: stats.inputTokens || 0,
-    output_tokens: stats.outputTokens || 0,
-    cache_read_input_tokens: stats.cacheRead || 0,
-    cache_creation_input_tokens: stats.cacheCreation || 0,
-    q5h_pct: quota.five_hour ? quota.five_hour.pct : null,
-    q7d_pct: quota.seven_day ? quota.seven_day.pct : null,
-    peak_hour: utcDay >= 1 && utcDay <= 5 && utcHour >= 13 && utcHour < 19,
+    model: typeof msg.model === "string" ? msg.model : "",
+    speed: usage.speed || "",
+    service_tier: usage.service_tier || "",
+    input_tokens: usage.input_tokens || 0,
+    cache_creation_input_tokens: usage.cache_creation_input_tokens || 0,
+    cache_read_input_tokens: usage.cache_read_input_tokens || 0,
+    ephemeral_1h_input_tokens: cc.ephemeral_1h_input_tokens || 0,
+    ephemeral_5m_input_tokens: cc.ephemeral_5m_input_tokens || 0,
+    web_search_requests: sti.web_search_requests || 0,
+  };
+}
+
+export function extractMessageDeltaFields(event) {
+  if (!event || event.type !== "message_delta") return null;
+  if (!event.usage) return null;
+  return { output_tokens: event.usage.output_tokens || 0 };
+}
+
+function num(headers, key) {
+  const v = headers?.[key];
+  if (v === undefined || v === null || v === "") return null;
+  const n = parseFloat(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function intOf(headers, key) {
+  const v = headers?.[key];
+  if (v === undefined || v === null || v === "") return 0;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function strOf(headers, key) {
+  const v = headers?.[key];
+  return typeof v === "string" ? v : "";
+}
+
+export function parseQuotaHeaders(headers) {
+  const h = headers || {};
+  return {
+    q5h: num(h, "anthropic-ratelimit-unified-5h-utilization") ?? 0,
+    q7d: num(h, "anthropic-ratelimit-unified-7d-utilization") ?? 0,
+    q5h_reset: intOf(h, "anthropic-ratelimit-unified-5h-reset"),
+    q7d_reset: intOf(h, "anthropic-ratelimit-unified-7d-reset"),
+    qstatus: strOf(h, "anthropic-ratelimit-unified-status"),
+    qoverage: strOf(h, "anthropic-ratelimit-unified-overage-status"),
+    qclaim: strOf(h, "anthropic-ratelimit-unified-claim"),
+    qfallback_pct: num(h, "anthropic-ratelimit-unified-fallback-percentage") ?? 0,
+    qoverage_util: num(h, "anthropic-ratelimit-unified-overage-utilization"),
+    qrepresentative_claim: strOf(h, "anthropic-ratelimit-unified-representative-claim") || undefined,
+    org_id_raw: strOf(h, "anthropic-organization-id") || undefined,
+    overage_disabled_reason: strOf(h, "anthropic-ratelimit-unified-overage-disabled-reason") || undefined,
+  };
+}
+
+export function computeDelta(current, previous) {
+  if (previous === null || previous === undefined) return 0;
+  if (typeof current !== "number" || typeof previous !== "number") return 0;
+  return current - previous;
+}
+
+export function assembleRecord({ start, delta, quota, requestedModel, sid, prevQ5h, prevQ7d, now = new Date() }) {
+  const s = start || {};
+  const d = delta || {};
+  const q = quota || {};
+
+  const inputTokens = s.input_tokens || 0;
+  const outputTokens = d.output_tokens || 0;
+  const cacheRead = s.cache_read_input_tokens || 0;
+  const cacheCreation = s.cache_creation_input_tokens || 0;
+  const totalIn = inputTokens + cacheCreation + cacheRead;
+  const cacheHitRate = totalIn > 0 ? cacheRead / totalIn : 0;
+
+  const record = {
+    v: 1,
+    ts: now.toISOString(),
+    sid,
+    model: s.model || "",
+    speed: s.speed || "",
+    service_tier: s.service_tier || "",
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cache_creation_input_tokens: cacheCreation,
+    cache_read_input_tokens: cacheRead,
+    ephemeral_1h_input_tokens: s.ephemeral_1h_input_tokens || 0,
+    ephemeral_5m_input_tokens: s.ephemeral_5m_input_tokens || 0,
+    web_search_requests: s.web_search_requests || 0,
+    q5h: q.q5h ?? 0,
+    q7d: q.q7d ?? 0,
+    q5h_reset: q.q5h_reset || 0,
+    q7d_reset: q.q7d_reset || 0,
+    qstatus: q.qstatus || "",
+    qoverage: q.qoverage || "",
+    qclaim: q.qclaim || "",
+    qfallback_pct: q.qfallback_pct ?? 0,
+    cache_hit_rate: cacheHitRate,
+    q5h_delta: computeDelta(q.q5h, prevQ5h),
+    q7d_delta: computeDelta(q.q7d, prevQ7d),
   };
+
+  // Optional fields are OMITTED (not present as undefined) when source absent.
+  if (requestedModel) {
+    record.requested_model = requestedModel;
+    if (record.model && requestedModel !== record.model) {
+      record.model_mismatch = true;
+    }
+  }
+  if (q.qoverage_util !== null && q.qoverage_util !== undefined) {
+    record.qoverage_util = q.qoverage_util;
+  }
+  if (q.qrepresentative_claim) {
+    record.qrepresentative_claim = q.qrepresentative_claim;
+  }
+  const orgIdHashed = hashOrgId(q.org_id_raw);
+  if (orgIdHashed) {
+    record.org_id = orgIdHashed;
+  }
+  if (q.overage_disabled_reason) {
+    record.overage_disabled_reason = q.overage_disabled_reason;
+  }
+
+  return record;
 }
 
-export { buildRecord, LOG_PATH };
+// --- I/O ---
+
+async function appendJsonl(record, path = LOG_PATH) {
+  await mkdir(join(homedir(), ".claude"), { recursive: true });
+  await appendFile(path, JSON.stringify(record) + "\n");
+}
+
+// Test helper: write a record to a caller-supplied path. Bypasses env-var
+// lookup so tests don't race on a shared env.
+export async function writeRecord(record, path) {
+  await mkdir(path.substring(0, path.lastIndexOf("/")), { recursive: true });
+  await appendFile(path, JSON.stringify(record) + "\n");
+}
+
+// Test helper: reset module-scope delta state.
+export function _resetDeltaStateForTest() {
+  _lastQ5h = null;
+  _lastQ7d = null;
+}
+
+export { LOG_PATH };
+
+// --- Extension contract ---
 
 export default {
   name: "usage-log",
-  description: "Append per-call usage record to ~/.claude/usage.jsonl",
+  description: "Append per-call usage record to ~/.claude/usage.jsonl (MeterRowSchema v:1)",
   enabled: false,
   order: 650,
 
   async onStreamEvent(ctx) {
-    if (!ctx.event || ctx.event.type !== "message_delta" || !ctx.event.usage) return;
-
-    const record = buildRecord(ctx.meta, ctx.telemetry || {}, ctx.responseHeaders);
+    if (!ctx || !ctx.event) return;
 
     try {
-      await mkdir(join(homedir(), ".claude"), { recursive: true });
-      await appendFile(LOG_PATH, JSON.stringify(record) + "\n");
-    } catch {}
+      // message_start: capture per-response state into ctx.meta._usageLog.
+      if (ctx.event.type === "message_start") {
+        const start = extractMessageStartFields(ctx.event);
+        if (start) {
+          ctx.meta = ctx.meta || {};
+          ctx.meta._usageLog = { start };
+        }
+        return;
+      }
+
+      // message_delta: assemble and emit the final record.
+      if (ctx.event.type !== "message_delta" || !ctx.event.usage) return;
+
+      const start = ctx.meta?._usageLog?.start;
+      if (!start) return; // no message_start was observed for this response
+
+      const delta = extractMessageDeltaFields(ctx.event);
+      const quota = parseQuotaHeaders(ctx.responseHeaders || {});
+      const requestedModel = ctx.telemetry?.requestedModel || undefined;
+
+      const record = assembleRecord({
+        start,
+        delta,
+        quota,
+        requestedModel,
+        sid: _sid,
+        prevQ5h: _lastQ5h,
+        prevQ7d: _lastQ7d,
+        now: new Date(),
+      });
+
+      // Update delta tracking AFTER assembly so the first call's delta is 0
+      // (per the directive contract: first call after restart → deltas zero).
+      _lastQ5h = quota.q5h;
+      _lastQ7d = quota.q7d;
+
+      await appendJsonl(record, process.env.CACHE_FIX_USAGE_LOG || LOG_PATH);
+    } catch {
+      // Fail-open: never throw to the pipeline.
+    }
   },
 };

package/proxy/extensions.json

@@ -9,5 +9,6 @@
   "cache-control-normalize": { "enabled": true, "order": 400 },
   "ttl-management": { "enabled": true, "order": 500 },
   "cache-telemetry": { "enabled": true, "order": 600 },
+  "overage-warning": { "enabled": true, "order": 610 },
   "request-log": { "enabled": false, "order": 700 }
 }

package/proxy/image-dimensions.mjs

@@ -0,0 +1,120 @@
+// Pure-JS image header dimension parsing for PNG and JPEG.
+//
+// Used by the image-strip extension to detect images exceeding a configurable
+// max dimension. Stays in a separate module so it can be unit-tested without
+// the rest of the proxy machinery.
+//
+// No native deps. Decode-only — never modifies the image data.
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// PNG: after the 8-byte magic, the IHDR chunk begins. IHDR layout:
+//   [4 bytes length][4 bytes "IHDR"][4 bytes width BE][4 bytes height BE]...
+// Width starts at byte 16, height at byte 20, both 32-bit big-endian.
+export function parsePngDimensions(buffer) {
+  if (!buffer || buffer.length < 24) return null;
+  for (let i = 0; i < PNG_MAGIC.length; i++) {
+    if (buffer[i] !== PNG_MAGIC[i]) return null;
+  }
+  // Verify the IHDR chunk type (offset 12-15 should be ASCII "IHDR")
+  if (
+    buffer[12] !== 0x49 || buffer[13] !== 0x48 ||
+    buffer[14] !== 0x44 || buffer[15] !== 0x52
+  ) {
+    return null;
+  }
+  const width = buffer.readUInt32BE(16);
+  const height = buffer.readUInt32BE(20);
+  if (width <= 0 || height <= 0) return null;
+  return { width, height };
+}
+
+// JPEG SOF (Start Of Frame) markers we care about. We don't differentiate
+// between SOF0 (baseline), SOF1 (extended sequential), SOF2 (progressive),
+// SOF3 (lossless) etc — all carry dimensions in the same layout.
+const JPEG_SOF_MARKERS = new Set([
+  0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+]);
+
+// JPEG: starts with FF D8 (SOI). Each segment after is FF <marker> [length BE]
+// [data...]. We scan for an SOF marker and read width/height from its segment.
+// SOF segment layout after the marker: [length 2B][precision 1B][height 2B][width 2B]...
+export function parseJpegDimensions(buffer) {
+  if (!buffer || buffer.length < 4) return null;
+  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) return null;
+
+  let i = 2;
+  const max = buffer.length;
+  // Bound iterations to keep malformed inputs from looping. JPEG headers we
+  // care about are well under 1KB; cap at the buffer size we got.
+  let iterations = 0;
+  while (i < max - 8 && iterations++ < 1000) {
+    // Each marker segment starts with 0xFF followed by the marker byte.
+    if (buffer[i] !== 0xff) {
+      // Skip over fill bytes / pad bytes (not valid in standard JPEG but tolerated)
+      i++;
+      continue;
+    }
+    // Skip multiple 0xFF prefixes (pad fill — valid per spec)
+    while (i < max - 1 && buffer[i] === 0xff) i++;
+    const marker = buffer[i];
+    i++;
+
+    // Markers without a length-prefixed segment: SOI (D8), EOI (D9), RST0-7 (D0-D7).
+    if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) {
+      continue;
+    }
+
+    if (i + 1 >= max) return null;
+    const segLen = (buffer[i] << 8) | buffer[i + 1];
+    if (segLen < 2 || i + segLen > max) return null;
+
+    if (JPEG_SOF_MARKERS.has(marker)) {
+      // Layout: [length 2B][precision 1B][height 2B][width 2B]
+      // i currently points at the length field's first byte.
+      if (i + 6 >= max) return null;
+      const height = (buffer[i + 3] << 8) | buffer[i + 4];
+      const width = (buffer[i + 5] << 8) | buffer[i + 6];
+      if (width <= 0 || height <= 0) return null;
+      return { width, height };
+    }
+
+    // Skip this segment to its end and continue scanning.
+    i += segLen;
+  }
+  return null;
+}
+
+// Decode a small prefix of base64 data and dispatch to the right parser based
+// on media_type. Returns { width, height } or null.
+//
+// We decode only the first ~512 bytes — enough for PNG IHDR (always near the
+// start) and the typical JPEG SOF location (most image encoders place the SOF
+// within the first few hundred bytes).
+const HEADER_PROBE_BYTES = 1024;
+
+export function parseImageDimensions(mediaType, base64Data) {
+  if (!mediaType || !base64Data || typeof base64Data !== "string") return null;
+  // Base64 expands by ~4/3, so to get HEADER_PROBE_BYTES decoded bytes we need
+  // ~HEADER_PROBE_BYTES * 4 / 3 base64 chars. Round up generously.
+  const probeChars = Math.min(base64Data.length, HEADER_PROBE_BYTES * 2);
+  let buffer;
+  try {
+    buffer = Buffer.from(base64Data.slice(0, probeChars), "base64");
+  } catch {
+    return null;
+  }
+  if (!buffer || buffer.length === 0) return null;
+
+  switch (mediaType.toLowerCase()) {
+    case "image/png":
+      return parsePngDimensions(buffer);
+    case "image/jpeg":
+    case "image/jpg":
+      return parseJpegDimensions(buffer);
+    default:
+      // Unsupported format — fail-open. Caller treats null as "can't measure"
+      // and keeps the image rather than stripping what it can't verify.
+      return null;
+  }
+}

package/proxy/rates.mjs

@@ -0,0 +1,16 @@
+// Shared rate constants for cost projections.
+//
+// This is a deliberate over-simplification for v3.2.0. Anthropic's
+// per-token rates vary by model, by cache tier (input vs cache_read vs
+// cache_creation_5m vs cache_creation_1h), and by overage classification.
+// Encoding all of that correctly is its own subproject — see the v3.3.0
+// follow-up for a precise per-tier engine.
+//
+// For v3.2.0 we ship a single weighted blend constant suitable for
+// a coarse "burn rate at API rates" indicator. Consumers MUST label the
+// resulting number as `coarse` so users do not mistake it for a precise
+// quote.
+
+// Heuristic blend covering input + cache_read + cache_creation + output
+// at a typical Opus 4.7 mix. Order of magnitude is right; precise it is not.
+export const WEIGHTED_TOKEN_COST_USD_COARSE = 0.000005;