claude-code-cache-fix 3.0.5 → 3.1.1

package/proxy/extensions/prefix-diff.mjs

@@ -0,0 +1,277 @@
+// prefix-diff — diagnostic extension for hunting cache-bust sources.
+//
+// On every request, snapshots a small projection of the prefix (system
+// prompt + tools + first 5 messages) and writes it to
+// `~/.claude/cache-fix-snapshots/<key>-last.json`. If a prior snapshot
+// exists and differs, also writes a `<key>-diff.json` and emits a
+// one-line stderr summary.
+//
+// No request mutation. The diagnostic is fail-open: any I/O error is
+// swallowed silently in production. Set CACHE_FIX_DEBUG=1 to also log
+// swallowed errors so silent failures stay observable.
+//
+// Adaptation from preload's `snapshotPrefix(payload)` (preload.mjs ~1656):
+// preload fired the diff once per process restart. The proxy is long-lived
+// and supports hot-reload, so we drop the "first call" gate and run the
+// diff per call. Trade-off: more disk writes, but each is tiny and the
+// diagnostic value is higher (drift visible across every turn, not just
+// at startup).
+
+import {
+  mkdir as _mkdir,
+  readFile as _readFile,
+  writeFile as _writeFile,
+  rename as _rename,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+const ENABLED = process.env.CACHE_FIX_PREFIXDIFF === "1";
+const DEBUG = process.env.CACHE_FIX_DEBUG === "1";
+
+const DEFAULT_FS = {
+  mkdir: _mkdir,
+  readFile: _readFile,
+  writeFile: _writeFile,
+  rename: _rename,
+};
+
+function getSnapshotDir() {
+  return join(homedir(), ".claude", "cache-fix-snapshots");
+}
+
+function debug(msg) {
+  if (DEBUG) process.stderr.write(`[prefix-diff] ${msg}\n`);
+}
+
+function computeSessionKey(system) {
+  return createHash("sha256")
+    .update(JSON.stringify(system).slice(0, 2000))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+function computeToolsHash(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return "none";
+  // Match preload behavior: hash unsorted tool names so order changes
+  // surface as hash mismatches (a real cache-bust signal).
+  return createHash("sha256")
+    .update(JSON.stringify(tools.map((t) => t?.name ?? "")))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+function computeSystemHash(system) {
+  if (!system) return "none";
+  return createHash("sha256")
+    .update(JSON.stringify(system))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+// Project the first 5 user/assistant messages: strip cache_control,
+// truncate text >500 chars with `...[N chars]` marker. Pure: returns
+// new objects, never mutates input.
+function truncatePrefixMessages(messages) {
+  if (!Array.isArray(messages)) return [];
+  return messages.slice(0, 5).map((msg) => {
+    if (!msg || !Array.isArray(msg.content)) {
+      return { role: msg?.role, content: msg?.content };
+    }
+    const cleanedContent = msg.content.map((block) => {
+      if (!block || typeof block !== "object") return block;
+      const { cache_control, ...rest } = block;
+      if (typeof rest.text === "string" && rest.text.length > 500) {
+        return {
+          ...rest,
+          text: rest.text.slice(0, 500) + `...[${rest.text.length} chars]`,
+        };
+      }
+      return rest;
+    });
+    return { role: msg.role, content: cleanedContent };
+  });
+}
+
+function buildSnapshot(payload) {
+  if (!payload || !payload.system) return null;
+  return {
+    timestamp: new Date().toISOString(),
+    messageCount: Array.isArray(payload.messages) ? payload.messages.length : 0,
+    toolsHash: computeToolsHash(payload.tools),
+    systemHash: computeSystemHash(payload.system),
+    prefixMessages: truncatePrefixMessages(payload.messages),
+  };
+}
+
+function computeDiff(prev, current) {
+  const diff = {
+    timestamp: current.timestamp,
+    prevTimestamp: prev.timestamp,
+    toolsMatch: prev.toolsHash === current.toolsHash,
+    systemMatch: prev.systemHash === current.systemHash,
+    messageCountPrev: prev.messageCount,
+    messageCountNow: current.messageCount,
+    prefixDiffs: [],
+  };
+  const prevMsgs = Array.isArray(prev.prefixMessages) ? prev.prefixMessages : [];
+  const nowMsgs = Array.isArray(current.prefixMessages) ? current.prefixMessages : [];
+  const maxIdx = Math.max(prevMsgs.length, nowMsgs.length);
+  for (let i = 0; i < maxIdx; i++) {
+    const prevSer = JSON.stringify(prevMsgs[i] ?? null);
+    const nowSer = JSON.stringify(nowMsgs[i] ?? null);
+    if (prevSer !== nowSer) {
+      diff.prefixDiffs.push({
+        index: i,
+        prev: prevMsgs[i] ?? null,
+        now: nowMsgs[i] ?? null,
+      });
+    }
+  }
+  return diff;
+}
+
+function diffHasChanges(diff) {
+  return (
+    diff.prefixDiffs.length > 0 ||
+    !diff.toolsMatch ||
+    !diff.systemMatch ||
+    diff.messageCountPrev !== diff.messageCountNow
+  );
+}
+
+// Atomic write: stage to a unique-per-invocation .tmp, then rename to
+// final path. The unique suffix is essential under concurrency — two
+// parallel callers writing to the same finalPath would otherwise share
+// a single .tmp and corrupt each other's content.
+//
+// On rename failure the prior final-path file (if any) remains intact.
+// The orphan .tmp persists on disk — because each invocation uses a
+// unique temp name, later calls do NOT implicitly overwrite it. This is
+// a small leak (accepted: failures are rare, files are tiny) rather than
+// a correctness issue. A follow-up could add best-effort cleanup.
+async function atomicWriteJson(finalPath, obj, fs) {
+  const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.${Math.random()
+    .toString(36)
+    .slice(2, 10)}.tmp`;
+  await fs.writeFile(tmpPath, JSON.stringify(obj, null, 2));
+  await fs.rename(tmpPath, finalPath);
+}
+
+/**
+ * Snapshot the prefix of `payload` and diff against the prior snapshot.
+ *
+ * Pure-ish: never throws, never mutates `payload`. All I/O is gated by
+ * try/catch; failures are debug-logged when CACHE_FIX_DEBUG=1.
+ *
+ * @param {object} payload  The request body (system, tools, messages).
+ * @param {object} options
+ * @param {string} [options.dir] Snapshot directory. Defaults to ~/.claude/cache-fix-snapshots.
+ * @param {object} [options.fs]  fs/promises overrides for tests:
+ *                               { mkdir, readFile, writeFile, rename }.
+ *                               Any subset replaces the corresponding default.
+ * @returns {Promise<{ key, wroteSnapshot, wroteDiff } | null>} Result for tests; null if no system.
+ */
+async function snapshotPrefix(payload, options = {}) {
+  const current = buildSnapshot(payload);
+  if (!current) return null;
+
+  const dir = options.dir || getSnapshotDir();
+  const fs = { ...DEFAULT_FS, ...(options.fs || {}) };
+
+  const sessionKey = computeSessionKey(payload.system);
+  const lastPath = join(dir, `${sessionKey}-last.json`);
+  const diffPath = join(dir, `${sessionKey}-diff.json`);
+
+  // Ensure directory exists. mkdir failure aborts — without dir, nothing
+  // else can succeed.
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch (err) {
+    debug(`mkdir failed for ${dir}: ${err?.message ?? err}`);
+    return { key: sessionKey, wroteSnapshot: false, wroteDiff: false };
+  }
+
+  // Read prior snapshot if it exists. Missing file is normal; corrupt
+  // file is treated as no prior (skip diff, proceed to overwrite).
+  let prev = null;
+  try {
+    const txt = await fs.readFile(lastPath, "utf-8");
+    prev = JSON.parse(txt);
+  } catch (err) {
+    if (err && err.code !== "ENOENT") {
+      debug(`prior snapshot unreadable at ${lastPath}: ${err?.message ?? err}`);
+    }
+  }
+
+  // Compute and write diff if anything changed.
+  let wroteDiff = false;
+  if (prev) {
+    const diff = computeDiff(prev, current);
+    if (diffHasChanges(diff)) {
+      try {
+        await atomicWriteJson(diffPath, diff, fs);
+        wroteDiff = true;
+        // Always log the summary line when a diff fires (not just under
+        // CACHE_FIX_DEBUG) — this is the diagnostic's whole purpose.
+        process.stderr.write(
+          `[prefix-diff] ${sessionKey}: ${diff.prefixDiffs.length} differences, ` +
+            `tools=${diff.toolsMatch ? "match" : "DIFFER"}, ` +
+            `system=${diff.systemMatch ? "match" : "DIFFER"}, ` +
+            `messages=${diff.messageCountPrev}→${diff.messageCountNow}\n`,
+        );
+      } catch (err) {
+        debug(`diff write failed at ${diffPath}: ${err?.message ?? err}`);
+      }
+    }
+  }
+
+  // Always write the new snapshot atomically so the next call has a
+  // fresh baseline. On failure, prior snapshot is intact.
+  let wroteSnapshot = false;
+  try {
+    await atomicWriteJson(lastPath, current, fs);
+    wroteSnapshot = true;
+  } catch (err) {
+    debug(`snapshot write failed at ${lastPath}: ${err?.message ?? err}`);
+  }
+
+  return { key: sessionKey, wroteSnapshot, wroteDiff };
+}
+
+// The named exports below are internal test seams, not part of the
+// proxy extension contract. Pipeline loading consumes only `default`.
+// They're exposed so tests can call the helpers directly with their own
+// options (tmpdir, failing fs mocks) instead of mutating process env or
+// monkey-patching node:fs/promises at module scope.
+export {
+  snapshotPrefix,
+  buildSnapshot,
+  computeDiff,
+  computeSessionKey,
+  truncatePrefixMessages,
+  diffHasChanges,
+};
+
+export default {
+  name: "prefix-diff",
+  description:
+    "Snapshot prefix (first 5 msgs + system + tools) and diff against previous run for cache-bust hunting",
+  // Always loaded; gated at runtime by CACHE_FIX_PREFIXDIFF=1 inside onRequest.
+  // This matches the acceptance criteria (env var alone activates) — the
+  // extension is cheap to load (one no-op check per request when disabled).
+  enabled: true,
+  order: 680,
+
+  async onRequest(ctx) {
+    if (!ENABLED) return;
+    if (!ctx || !ctx.body) return;
+    // snapshotPrefix never throws; double-belt try/catch is defense in depth.
+    try {
+      await snapshotPrefix(ctx.body);
+    } catch (err) {
+      debug(`onRequest unexpected: ${err?.message ?? err}`);
+    }
+  },
+};

package/proxy/extensions/smoosh-split.mjs

@@ -0,0 +1,68 @@
+const TRAILING_SMOOSH = /\n\n(<system-reminder>\n(?:(?!<\/system-reminder>)[\s\S])*?\n<\/system-reminder>)\s*$/;
+
+function splitSmooshedReminders(messages) {
+  if (!Array.isArray(messages)) return { messages, stats: null };
+
+  let totalPeeled = 0;
+
+  const result = messages.map((msg) => {
+    if (msg.role !== "user" || !Array.isArray(msg.content)) return msg;
+
+    const out = [];
+    const peeledReminders = [];
+    let mutated = false;
+
+    for (const block of msg.content) {
+      if (block?.type === "tool_result" && typeof block.content === "string") {
+        const reminders = [];
+        let s = block.content;
+        while (true) {
+          const m = s.match(TRAILING_SMOOSH);
+          if (!m) break;
+          reminders.unshift(m[1]);
+          s = s.slice(0, m.index);
+        }
+        if (reminders.length > 0) {
+          out.push({ ...block, content: s });
+          for (const r of reminders) peeledReminders.push({ type: "text", text: r });
+          totalPeeled += reminders.length;
+          mutated = true;
+          continue;
+        }
+      }
+      out.push(block);
+    }
+
+    if (mutated) {
+      return { ...msg, content: [...out, ...peeledReminders] };
+    }
+    return msg;
+  });
+
+  return {
+    messages: totalPeeled > 0 ? result : messages,
+    stats: totalPeeled > 0 ? { peeled: totalPeeled } : null,
+  };
+}
+
+export { splitSmooshedReminders, TRAILING_SMOOSH };
+
+export default {
+  name: "smoosh-split",
+  description: "Peel smooshed system-reminders from tool_result content into standalone blocks",
+  enabled: false,
+  order: 320,
+
+  async onRequest(ctx) {
+    if (!ctx.body.messages) return;
+
+    const { messages, stats } = splitSmooshedReminders(ctx.body.messages);
+    if (stats) {
+      ctx.body.messages = messages;
+      ctx.meta.smooshSplitStats = stats;
+      process.stderr.write(
+        `[smoosh-split] peeled ${stats.peeled} reminder(s) from tool_result.content\n`
+      );
+    }
+  },
+};

package/proxy/extensions/sort-stabilization.mjs

@@ -28,6 +28,8 @@ function isDeferredToolsBlock(text) {
   return typeof text === "string" && text.includes("deferred tools are now available");
 }
 
+export { sortSkillsBlock, sortDeferredToolsBlock, isSkillsBlock, isDeferredToolsBlock };
+
 export default {
   name: "sort-stabilization",
   description: "Deterministic ordering of skills, deferred tools, and tool definitions",

package/proxy/extensions/tool-input-normalize.mjs

@@ -0,0 +1,73 @@
+function normalizeToolUseInputs(body) {
+  if (!body || typeof body !== "object") return 0;
+  if (!Array.isArray(body.messages) || !Array.isArray(body.tools)) return 0;
+
+  const toolSchemas = Object.create(null);
+  for (const tool of body.tools) {
+    if (!tool || typeof tool !== "object") continue;
+    const name = tool.name;
+    if (typeof name !== "string") continue;
+    const props = tool.input_schema?.properties;
+    if (!props || typeof props !== "object") continue;
+    toolSchemas[name] = Object.keys(props);
+  }
+
+  let modified = 0;
+  for (const msg of body.messages) {
+    if (!msg || msg.role !== "assistant") continue;
+    if (!Array.isArray(msg.content)) continue;
+    for (let i = 0; i < msg.content.length; i++) {
+      const block = msg.content[i];
+      if (!block || block.type !== "tool_use") continue;
+      if (!block.input || typeof block.input !== "object" || Array.isArray(block.input)) continue;
+      const schemaKeys = toolSchemas[block.name];
+      if (!schemaKeys) continue;
+
+      const currentKeys = Object.keys(block.input);
+      const schemaKeySet = new Set(schemaKeys);
+      const hasExtras = currentKeys.some((k) => !schemaKeySet.has(k));
+
+      const presentSchemaKeys = schemaKeys.filter((k) =>
+        Object.prototype.hasOwnProperty.call(block.input, k)
+      );
+      const currentInSchema = currentKeys.filter((k) => schemaKeySet.has(k));
+
+      let orderDiffers = presentSchemaKeys.length !== currentInSchema.length;
+      if (!orderDiffers) {
+        for (let j = 0; j < presentSchemaKeys.length; j++) {
+          if (presentSchemaKeys[j] !== currentInSchema[j]) {
+            orderDiffers = true;
+            break;
+          }
+        }
+      }
+
+      if (!hasExtras && !orderDiffers) continue;
+
+      const newInput = {};
+      for (const k of presentSchemaKeys) {
+        newInput[k] = block.input[k];
+      }
+      msg.content[i] = { ...block, input: newInput };
+      modified++;
+    }
+  }
+  return modified;
+}
+
+export { normalizeToolUseInputs };
+
+export default {
+  name: "tool-input-normalize",
+  description: "Normalize tool_use input field ordering to match schema for cache stability",
+  enabled: false,
+  order: 280,
+
+  async onRequest(ctx) {
+    if (!ctx.body.messages || !ctx.body.tools) return;
+    const count = normalizeToolUseInputs(ctx.body);
+    if (count > 0) {
+      ctx.meta.toolInputNormalizeCount = count;
+    }
+  },
+};

package/proxy/extensions/ttl-management.mjs

@@ -17,6 +17,8 @@ function injectTtl(block, ttlParam) {
   return block;
 }
 
+export { detectRequestType, injectTtl };
+
 export default {
   name: "ttl-management",
   description: "Inject correct TTL on cache_control markers based on detected tier",

package/proxy/extensions/usage-log.mjs

@@ -0,0 +1,46 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+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();
+
+  const stats = meta.cacheStats || {};
+  const quota = meta._quotaData || {};
+
+  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,
+  };
+}
+
+export { buildRecord, LOG_PATH };
+
+export default {
+  name: "usage-log",
+  description: "Append per-call usage record to ~/.claude/usage.jsonl",
+  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);
+
+    try {
+      await mkdir(join(homedir(), ".claude"), { recursive: true });
+      await appendFile(LOG_PATH, JSON.stringify(record) + "\n");
+    } catch {}
+  },
+};

package/proxy/extensions.json

@@ -3,6 +3,9 @@
   "sort-stabilization": { "enabled": true, "order": 200 },
   "fresh-session-sort": { "enabled": true, "order": 250 },
   "identity-normalization": { "enabled": true, "order": 300 },
+  "smoosh-split": { "enabled": true, "order": 320 },
+  "content-strip": { "enabled": true, "order": 330 },
+  "tool-input-normalize": { "enabled": true, "order": 340 },
   "cache-control-normalize": { "enabled": true, "order": 400 },
   "ttl-management": { "enabled": true, "order": 500 },
   "cache-telemetry": { "enabled": true, "order": 600 },

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>