claude-code-cache-fix 3.1.0 → 3.2.0

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/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;

package/templates/cache-fix-proxy-healthcheck.service.template

@@ -0,0 +1,7 @@
+[Unit]
+Description=Claude Code Cache Fix Proxy — health check + auto-restart
+After=network.target
+
+[Service]
+Type=oneshot
+ExecStart=/bin/sh -c 'curl -fs --max-time 3 http://127.0.0.1:{{PORT}}/health > /dev/null || systemctl --user start cache-fix-proxy.service'

package/templates/cache-fix-proxy-healthcheck.timer.template

@@ -0,0 +1,14 @@
+[Unit]
+Description=Claude Code Cache Fix Proxy — health check timer (every 2 min)
+Documentation=https://github.com/cnighswonger/claude-code-cache-fix
+
+[Timer]
+# Run 30s after boot, then every 2 minutes thereafter. Off-round minute
+# so the firing distribution doesn't pile up on :00.
+OnBootSec=30s
+OnUnitActiveSec=2min
+AccuracySec=15s
+Unit=cache-fix-proxy-healthcheck.service
+
+[Install]
+WantedBy=timers.target

package/templates/cache-fix-proxy.service.template

@@ -0,0 +1,17 @@
+[Unit]
+Description=Claude Code Cache Fix Proxy
+After=network.target
+{{REQUIRES_LINE}}
+
+[Service]
+Type=simple
+ExecStart={{NODE}} {{SERVER_PATH}}
+Restart=on-failure
+RestartSec=5
+Environment=CACHE_FIX_PROXY_PORT={{PORT}}
+{{UPSTREAM_LINE}}
+{{DEBUG_LINE}}
+WorkingDirectory={{WORKING_DIR}}
+
+[Install]
+WantedBy=default.target

package/templates/com.cnighswonger.cache-fix-proxy.plist.template

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.cnighswonger.cache-fix-proxy</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{NODE}}</string>
+        <string>{{SERVER_PATH}}</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>CACHE_FIX_PROXY_PORT</key>
+        <string>{{PORT}}</string>
+{{UPSTREAM_PLIST}}
+{{DEBUG_PLIST}}
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>{{WORKING_DIR}}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>{{LOG_DIR}}/cache-fix-proxy.log</string>
+    <key>StandardErrorPath</key>
+    <string>{{LOG_DIR}}/cache-fix-proxy.err</string>
+</dict>
+</plist>