claude-code-cache-fix 2.0.5 → 3.0.0

package/bin/claude-via-proxy.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { fork, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import http from "node:http";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SERVER_PATH = resolve(__dirname, "../proxy/server.mjs");
+
+const args = process.argv.slice(2);
+let proxyPort = 9801;
+let proxyUpstream = undefined;
+const claudeArgs = [];
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--proxy-port" && args[i + 1]) {
+    proxyPort = parseInt(args[++i], 10);
+  } else if (args[i] === "--proxy-upstream" && args[i + 1]) {
+    proxyUpstream = args[++i];
+  } else {
+    claudeArgs.push(args[i]);
+  }
+}
+
+const proxyEnv = { ...process.env, CACHE_FIX_PROXY_PORT: String(proxyPort) };
+if (proxyUpstream) proxyEnv.CACHE_FIX_PROXY_UPSTREAM = proxyUpstream;
+
+const proxyProc = fork(SERVER_PATH, [], {
+  stdio: ["ignore", "pipe", "pipe", "ipc"],
+  env: proxyEnv,
+});
+
+let claudeProc = null;
+let exiting = false;
+
+function cleanup() {
+  if (exiting) return;
+  exiting = true;
+  if (claudeProc && !claudeProc.killed) claudeProc.kill("SIGTERM");
+  if (proxyProc && !proxyProc.killed) proxyProc.kill("SIGTERM");
+}
+
+proxyProc.on("exit", (code) => {
+  if (!exiting) {
+    process.stderr.write(`proxy exited unexpectedly (code ${code})\n`);
+    cleanup();
+    process.exit(1);
+  }
+});
+
+proxyProc.stderr.on("data", (chunk) => {
+  process.stderr.write(chunk);
+});
+
+function waitForReady() {
+  return new Promise((resolve, reject) => {
+    let output = "";
+    proxyProc.stdout.on("data", (chunk) => {
+      output += chunk.toString();
+      const match = output.match(/listening on ([\d.]+):(\d+)/);
+      if (match) resolve(parseInt(match[2], 10));
+    });
+    proxyProc.on("exit", (code) => {
+      reject(new Error(`Proxy exited (code ${code}) before ready`));
+    });
+    setTimeout(() => reject(new Error("Proxy failed to start within 10s")), 10000);
+  });
+}
+
+let actualPort;
+try {
+  actualPort = await waitForReady();
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  cleanup();
+  process.exit(1);
+}
+
+const claudeEnv = {
+  ...process.env,
+  ANTHROPIC_BASE_URL: `http://127.0.0.1:${actualPort}`,
+};
+
+const spawnOpts = { stdio: ["inherit", "pipe", "pipe"], env: claudeEnv };
+if (process.env.CACHE_FIX_CLAUDE_CMD) {
+  const parts = process.env.CACHE_FIX_CLAUDE_CMD.split(" ");
+  claudeProc = spawn(parts[0], [...parts.slice(1), ...claudeArgs], spawnOpts);
+} else {
+  claudeProc = spawn("claude", claudeArgs, spawnOpts);
+}
+
+claudeProc.stdout.on("data", (chunk) => process.stdout.write(chunk));
+claudeProc.stderr.on("data", (chunk) => process.stderr.write(chunk));
+
+claudeProc.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    process.stderr.write("Error: 'claude' command not found. Is Claude Code installed?\n");
+  } else {
+    process.stderr.write(`Failed to start claude: ${err.message}\n`);
+  }
+  cleanup();
+  process.exit(1);
+});
+
+claudeProc.on("close", (code) => {
+  const exitCode = code ?? 0;
+  cleanup();
+  process.exit(exitCode);
+});
+
+process.on("SIGINT", () => { cleanup(); process.exit(130); });
+process.on("SIGTERM", () => { cleanup(); process.exit(143); });

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "2.0.5",
-  "description": "Fixes prompt cache regression in Claude Code that causes up to 20x cost increase on resumed sessions",
+  "version": "3.0.0",
+  "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",
   "main": "./preload.mjs",
+  "bin": {
+    "claude-via-proxy": "./bin/claude-via-proxy.mjs"
+  },
   "files": [
     "preload.mjs",
     "postinstall.js",
     "tools/",
-    "claude-fixed.bat"
+    "claude-fixed.bat",
+    "proxy/",
+    "bin/"
   ],
   "engines": {
     "node": ">=18"

package/proxy/config.mjs

@@ -0,0 +1,23 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  const parsed = parseInt(raw, 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const config = {
+  port: envInt("CACHE_FIX_PROXY_PORT", 9801),
+  bind: process.env.CACHE_FIX_PROXY_BIND || "127.0.0.1",
+  upstream: process.env.CACHE_FIX_PROXY_UPSTREAM || "https://api.anthropic.com",
+  timeout: envInt("CACHE_FIX_PROXY_TIMEOUT", 600_000),
+  extensionsDir: process.env.CACHE_FIX_EXTENSIONS_DIR || join(__dirname, "extensions"),
+  extensionsConfig: process.env.CACHE_FIX_EXTENSIONS_CONFIG || join(__dirname, "extensions.json"),
+  debug: process.env.CACHE_FIX_DEBUG === "1",
+};
+
+export default config;

package/proxy/extensions/cache-control-normalize.mjs

@@ -0,0 +1,59 @@
+function stripCacheControlMarkers(msg) {
+  if (!msg || msg.role !== "user" || !Array.isArray(msg.content)) return 0;
+  let n = 0;
+  for (let i = 0; i < msg.content.length; i++) {
+    const block = msg.content[i];
+    if (block && typeof block === "object" && block.cache_control) {
+      const { cache_control, ...rest } = block;
+      msg.content[i] = rest;
+      n++;
+    }
+  }
+  return n;
+}
+
+function countUserCacheControlMarkers(body) {
+  if (!body || !Array.isArray(body.messages)) return 0;
+  let n = 0;
+  for (const msg of body.messages) {
+    if (msg?.role !== "user" || !Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (block && typeof block === "object" && block.cache_control) n++;
+    }
+  }
+  return n;
+}
+
+export default {
+  name: "cache-control-normalize",
+  description: "Strip scattered cache_control markers from user messages and apply canonical placement",
+  order: 400,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+    if (!Array.isArray(body.messages)) return;
+
+    const markerCount = countUserCacheControlMarkers(body);
+    if (markerCount === 0) return;
+
+    for (const msg of body.messages) {
+      if (msg.role === "user") {
+        stripCacheControlMarkers(msg);
+      }
+    }
+
+    // Apply canonical cache_control at the last block of the last user message
+    for (let i = body.messages.length - 1; i >= 0; i--) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content) || msg.content.length === 0) continue;
+      const lastBlock = msg.content[msg.content.length - 1];
+      if (lastBlock && typeof lastBlock === "object") {
+        msg.content[msg.content.length - 1] = {
+          ...lastBlock,
+          cache_control: { type: "ephemeral" },
+        };
+      }
+      break;
+    }
+  },
+};

package/proxy/extensions/cache-telemetry.mjs

@@ -0,0 +1,24 @@
+export default {
+  name: "cache-telemetry",
+  description: "Extract cache hit/miss stats from response stream for monitoring",
+  order: 600,
+
+  async onStreamEvent(ctx) {
+    const { event, telemetry } = ctx;
+    if (!event || !telemetry) return;
+
+    if (event.type === "message_start" && event.message?.usage) {
+      const usage = event.message.usage;
+      ctx.meta.cacheStats = {
+        cacheRead: usage.cache_read_input_tokens || 0,
+        cacheCreation: usage.cache_creation_input_tokens || 0,
+        inputTokens: usage.input_tokens || 0,
+      };
+    }
+
+    if (event.type === "message_delta" && event.usage) {
+      if (!ctx.meta.cacheStats) ctx.meta.cacheStats = {};
+      ctx.meta.cacheStats.outputTokens = event.usage.output_tokens || 0;
+    }
+  },
+};

package/proxy/extensions/fingerprint-strip.mjs

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+
+const FINGERPRINT_SALT = "59cf53e54c78";
+const FINGERPRINT_INDICES = [4, 7, 20];
+
+function computeFingerprint(messageText, version) {
+  const chars = FINGERPRINT_INDICES.map((i) => messageText[i] || "0").join("");
+  const input = `${FINGERPRINT_SALT}${chars}${version}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 3);
+}
+
+function extractRealUserMessageText(messages) {
+  for (const msg of messages) {
+    if (msg.role !== "user") continue;
+    const content = msg.content;
+    if (!Array.isArray(content)) {
+      if (typeof content === "string" && !content.startsWith("<system-reminder>")) {
+        return content;
+      }
+      continue;
+    }
+    for (const block of content) {
+      if (block.type === "text" && typeof block.text === "string" && !block.text.startsWith("<system-reminder>")) {
+        return block.text;
+      }
+    }
+  }
+  return "";
+}
+
+function extractFirstMessageText(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return "";
+  const first = messages[0];
+  if (!first || first.role !== "user") return "";
+  const content = first.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  for (const block of content) {
+    if (block.type === "text" && typeof block.text === "string") {
+      return block.text;
+    }
+  }
+  return "";
+}
+
+function stabilizeFingerprint(system, messages) {
+  if (!Array.isArray(system)) return null;
+
+  const attrIdx = system.findIndex(
+    (b) => b.type === "text" && typeof b.text === "string" && b.text.includes("x-anthropic-billing-header:")
+  );
+  if (attrIdx === -1) return null;
+
+  const attrBlock = system[attrIdx];
+  const versionMatch = attrBlock.text.match(/cc_version=([^;]+)/);
+  if (!versionMatch) return null;
+
+  const fullVersion = versionMatch[1];
+  const dotParts = fullVersion.split(".");
+  if (dotParts.length < 4) return null;
+
+  const baseVersion = dotParts.slice(0, 3).join(".");
+  const oldFingerprint = dotParts[3];
+
+  const realText = extractRealUserMessageText(messages);
+  const realVerification = computeFingerprint(realText, baseVersion);
+  const legacyText = extractFirstMessageText(messages);
+  const legacyVerification = computeFingerprint(legacyText, baseVersion);
+
+  let verificationPassed = false;
+  if (realVerification === oldFingerprint) {
+    verificationPassed = true;
+  } else if (legacyVerification === oldFingerprint) {
+    verificationPassed = true;
+  }
+
+  if (!verificationPassed) return null;
+
+  const stableFingerprint = computeFingerprint(realText, baseVersion);
+  if (stableFingerprint === oldFingerprint) return null;
+
+  const newVersion = `${baseVersion}.${stableFingerprint}`;
+  const newText = attrBlock.text.replace(
+    `cc_version=${fullVersion}`,
+    `cc_version=${newVersion}`
+  );
+
+  return { attrIdx, newText, oldFingerprint, stableFingerprint };
+}
+
+export default {
+  name: "fingerprint-strip",
+  description: "Stabilize cc_version fingerprint in system prompt for cache prefix consistency",
+  order: 100,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+    if (!body.system || !body.messages) return;
+
+    const result = stabilizeFingerprint(body.system, body.messages);
+    if (result) {
+      body.system[result.attrIdx] = { ...body.system[result.attrIdx], text: result.newText };
+    }
+  },
+};

package/proxy/extensions/fresh-session-sort.mjs

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+
+const SR = "<system-reminder>\n";
+
+function isSystemReminder(text) {
+  return typeof text === "string" && text.startsWith("<system-reminder>");
+}
+
+function isHooksBlock(text) {
+  return isSystemReminder(text) && text.substring(0, 200).includes("hook success");
+}
+
+function isSkillsBlock(text) {
+  return typeof text === "string" && text.startsWith(SR + "The following skills are available");
+}
+
+function isDeferredToolsBlock(text) {
+  return typeof text === "string" && text.startsWith(SR + "The following deferred tools are now available");
+}
+
+function isMcpBlock(text) {
+  return typeof text === "string" && text.startsWith(SR + "# MCP Server Instructions");
+}
+
+function isRelocatableBlock(text) {
+  return isHooksBlock(text) || isSkillsBlock(text) || isDeferredToolsBlock(text) || isMcpBlock(text);
+}
+
+function isClearArtifact(text) {
+  if (typeof text !== "string") return false;
+  return (
+    text.startsWith("<local-command-caveat>") ||
+    text.startsWith("<command-name>") ||
+    text.startsWith("<local-command-stdout>")
+  );
+}
+
+function sortSkillsBlock(text) {
+  const match = text.match(/^([\s\S]*?\n\n)(- [\s\S]+?)(\n<\/system-reminder>\s*)$/);
+  if (!match) return text;
+  const [, header, entriesText, footer] = match;
+  const entries = entriesText.split(/\n(?=- )/);
+  entries.sort();
+  return header + entries.join("\n") + footer;
+}
+
+function sortDeferredToolsBlock(text) {
+  const match = text.match(
+    /^(<system-reminder>\nThe following deferred tools are now available[^\n]*\n)([\s\S]+?)(\n<\/system-reminder>\s*)$/
+  );
+  if (!match) return text;
+  const [, header, toolsList, footer] = match;
+  const tools = toolsList.split("\n").map((t) => t.trim()).filter(Boolean);
+  tools.sort();
+  return header + tools.join("\n") + footer;
+}
+
+function stripSessionKnowledge(text) {
+  return text.replace(/\n<session_knowledge[^>]*>[\s\S]*?<\/session_knowledge>/g, "");
+}
+
+const _pinnedBlocks = new Map();
+
+function pinBlockContent(blockType, text) {
+  const normalized = text.replace(/\s+(<\/system-reminder>)\s*$/, "\n$1");
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  const pinned = _pinnedBlocks.get(blockType);
+  if (pinned && pinned.hash === hash) return pinned.text;
+  _pinnedBlocks.set(blockType, { hash, text: normalized });
+  return normalized;
+}
+
+function getBlockType(text) {
+  if (isSkillsBlock(text)) return "skills";
+  if (isDeferredToolsBlock(text)) return "deferred";
+  if (isMcpBlock(text)) return "mcp";
+  if (isHooksBlock(text)) return "hooks";
+  return null;
+}
+
+function fixBlockText(blockType, text) {
+  let fixed = text;
+  if (blockType === "skills") fixed = sortSkillsBlock(fixed);
+  else if (blockType === "deferred") fixed = sortDeferredToolsBlock(fixed);
+  else if (blockType === "hooks") fixed = stripSessionKnowledge(fixed);
+  return pinBlockContent(blockType, fixed);
+}
+
+export default {
+  name: "fresh-session-sort",
+  description: "Relocate scattered blocks to messages[0] in deterministic fresh-session order",
+  order: 250,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+    if (!Array.isArray(body.messages)) return;
+
+    let firstUserIdx = -1;
+    for (let i = 0; i < body.messages.length; i++) {
+      if (body.messages[i].role === "user") {
+        firstUserIdx = i;
+        break;
+      }
+    }
+    if (firstUserIdx === -1) return;
+
+    const firstMsg = body.messages[firstUserIdx];
+    if (!Array.isArray(firstMsg?.content)) return;
+
+    // Strip /clear artifacts from first user message
+    const beforeLen = firstMsg.content.length;
+    firstMsg.content = firstMsg.content.filter((b) => !isClearArtifact(b.text || ""));
+
+    // Check for scattered relocatable blocks outside first user message
+    let hasScatteredBlocks = false;
+    for (let i = firstUserIdx + 1; i < body.messages.length && !hasScatteredBlocks; i++) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+      for (const block of msg.content) {
+        if (isRelocatableBlock(block.text || "")) {
+          hasScatteredBlocks = true;
+          break;
+        }
+      }
+    }
+
+    if (!hasScatteredBlocks) {
+      // Still sort and pin blocks in-place for deterministic first-call baseline
+      let modified = false;
+      const newContent = firstMsg.content.map((block) => {
+        const text = block.text || "";
+        const blockType = getBlockType(text);
+        if (!blockType) return block;
+
+        const fixedText = fixBlockText(blockType, text);
+        if (fixedText !== text) {
+          modified = true;
+          const { cache_control, ...rest } = block;
+          return { ...rest, text: fixedText };
+        }
+        return block;
+      });
+
+      if (modified || firstMsg.content.length !== beforeLen) {
+        body.messages[firstUserIdx] = { ...firstMsg, content: newContent };
+      }
+      return;
+    }
+
+    // Scan backwards to find latest instance of each relocatable block type
+    const found = new Map();
+    for (let i = body.messages.length - 1; i >= firstUserIdx; i--) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+      for (let j = msg.content.length - 1; j >= 0; j--) {
+        const block = msg.content[j];
+        const text = block.text || "";
+        const blockType = getBlockType(text);
+        if (!blockType || found.has(blockType)) continue;
+
+        const fixedText = fixBlockText(blockType, text);
+        const { cache_control, ...rest } = block;
+        found.set(blockType, { ...rest, text: fixedText });
+      }
+    }
+
+    if (found.size === 0) return;
+
+    // Remove all relocatable blocks from all user messages
+    for (let i = 0; i < body.messages.length; i++) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+      const filtered = msg.content.filter((b) => !isRelocatableBlock(b.text || ""));
+      if (filtered.length !== msg.content.length) {
+        body.messages[i] = { ...msg, content: filtered };
+      }
+    }
+
+    // Prepend in deterministic order: deferred → mcp → skills → hooks
+    const ORDER = ["deferred", "mcp", "skills", "hooks"];
+    const toRelocate = ORDER.filter((t) => found.has(t)).map((t) => found.get(t));
+
+    body.messages[firstUserIdx] = {
+      ...body.messages[firstUserIdx],
+      content: [...toRelocate, ...body.messages[firstUserIdx].content],
+    };
+  },
+};

package/proxy/extensions/identity-normalization.mjs

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+
+const _pinnedBlocks = new Map();
+
+const SESSION_START_RESUME_MARKER = /SessionStart:startup hook success:/g;
+const SESSION_START_ID_TAG = /\n?<session-id>[^<]*<\/session-id>/g;
+const SESSION_START_LAST_ACTIVE_LINE = /\nLast active:[^\n]*/g;
+const CONTINUE_TRAILER_TEXT = "Continue from where you left off.";
+
+const REMINDER_WRAP_REGEX = /^<system-reminder>\n([\s\S]*?)\n<\/system-reminder>\s*$/;
+const BOOKKEEPING_REMINDER_PATTERNS = [
+  /^Token usage: \d+\/\d+; \d+ remaining\s*$/,
+  /^Output tokens \u2014 turn: [^\n]+ \u00b7 session: [^\n]+\s*$/,
+  /^USD budget: \$[\d.]+\/\$[\d.]+; \$[\d.]+ remaining\s*$/,
+];
+
+function pinBlockContent(blockType, text) {
+  const normalized = text.replace(/\s+(<\/system-reminder>)\s*$/, "\n$1");
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  const pinned = _pinnedBlocks.get(blockType);
+
+  if (pinned && pinned.hash === hash) {
+    return pinned.text;
+  }
+
+  _pinnedBlocks.set(blockType, { hash, text: normalized });
+  return normalized;
+}
+
+function stripSessionKnowledge(text) {
+  return text.replace(
+    /\n<session_knowledge[^>]*>[\s\S]*?<\/session_knowledge>/g,
+    ""
+  );
+}
+
+function normalizeSessionStartText(text) {
+  if (typeof text !== "string" || !text.includes("SessionStart:")) return [text, 0];
+  let count = 0;
+  let out = text;
+  if (SESSION_START_RESUME_MARKER.test(out)) {
+    SESSION_START_RESUME_MARKER.lastIndex = 0;
+    out = out.replace(SESSION_START_RESUME_MARKER, "SessionStart:startup hook success:");
+    count++;
+  }
+  if (SESSION_START_ID_TAG.test(out)) {
+    SESSION_START_ID_TAG.lastIndex = 0;
+    out = out.replace(SESSION_START_ID_TAG, "");
+    count++;
+  }
+  if (SESSION_START_LAST_ACTIVE_LINE.test(out)) {
+    SESSION_START_LAST_ACTIVE_LINE.lastIndex = 0;
+    out = out.replace(SESSION_START_LAST_ACTIVE_LINE, "");
+    count++;
+  }
+  return [out, count];
+}
+
+function isContinueTrailerBlock(block) {
+  return (
+    !!block &&
+    typeof block === "object" &&
+    block.type === "text" &&
+    block.text === CONTINUE_TRAILER_TEXT
+  );
+}
+
+function isBookkeepingReminder(text) {
+  if (typeof text !== "string") return false;
+  const m = text.match(REMINDER_WRAP_REGEX);
+  if (!m) return false;
+  const inner = m[1];
+  for (const rx of BOOKKEEPING_REMINDER_PATTERNS) {
+    if (rx.test(inner)) return true;
+  }
+  return false;
+}
+
+export default {
+  name: "identity-normalization",
+  description: "Normalize volatile identity fields (SessionStart, Continue trailers, bookkeeping) for cache stability",
+  order: 300,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+
+    if (Array.isArray(body.system)) {
+      for (let i = 0; i < body.system.length; i++) {
+        const block = body.system[i];
+        if (block.type !== "text" || typeof block.text !== "string") continue;
+
+        let text = block.text;
+        if (text.includes("session_knowledge")) {
+          text = stripSessionKnowledge(text);
+        }
+        if (text.includes("<system-reminder>")) {
+          text = pinBlockContent(`system_${i}`, text);
+        }
+        if (text !== block.text) {
+          body.system[i] = { ...block, text };
+        }
+      }
+    }
+
+    if (Array.isArray(body.messages)) {
+      for (const msg of body.messages) {
+        if (!Array.isArray(msg.content)) continue;
+
+        for (let i = msg.content.length - 1; i >= 0; i--) {
+          const block = msg.content[i];
+          if (block.type !== "text" || typeof block.text !== "string") continue;
+
+          if (isContinueTrailerBlock(block) && i === msg.content.length - 1 && msg.role === "user") {
+            continue;
+          }
+
+          if (isBookkeepingReminder(block.text)) {
+            continue;
+          }
+
+          const [normalized] = normalizeSessionStartText(block.text);
+          if (normalized !== block.text) {
+            msg.content[i] = { ...block, text: normalized };
+          }
+        }
+      }
+    }
+  },
+};