claude-code-cache-fix 2.0.6 → 3.0.1

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 };
+          }
+        }
+      }
+    }
+  },
+};

package/proxy/extensions/request-log.mjs

@@ -0,0 +1,35 @@
+import { appendFile } from "node:fs/promises";
+
+const LOG_PATH = process.env.CACHE_FIX_REQUEST_LOG || "";
+
+export default {
+  name: "request-log",
+  description: "Optional NDJSON request timing log",
+  enabled: false,
+  order: 700,
+
+  async onRequest(ctx) {
+    ctx.meta._requestStart = Date.now();
+    ctx.meta._requestModel = ctx.body.model || null;
+  },
+
+  async onResponseStart(ctx) {
+    ctx.meta._responseStart = Date.now();
+  },
+
+  async onStreamEvent(ctx) {
+    if (ctx.event?.type === "message_delta" && ctx.meta._requestStart && LOG_PATH) {
+      const entry = {
+        ts: new Date().toISOString(),
+        model: ctx.meta._requestModel,
+        latencyMs: (ctx.meta._responseStart || Date.now()) - ctx.meta._requestStart,
+        outputTokens: ctx.event.usage?.output_tokens || 0,
+        cacheRead: ctx.meta.cacheStats?.cacheRead || 0,
+        cacheCreation: ctx.meta.cacheStats?.cacheCreation || 0,
+      };
+      try {
+        await appendFile(LOG_PATH, JSON.stringify(entry) + "\n");
+      } catch {}
+    }
+  },
+};

package/proxy/extensions/sort-stabilization.mjs

@@ -0,0 +1,62 @@
+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 isSkillsBlock(text) {
+  return typeof text === "string" && text.includes("User-invocable skills");
+}
+
+function isDeferredToolsBlock(text) {
+  return typeof text === "string" && text.includes("deferred tools are now available");
+}
+
+export default {
+  name: "sort-stabilization",
+  description: "Deterministic ordering of skills, deferred tools, and tool definitions",
+  order: 200,
+
+  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;
+
+        if (isSkillsBlock(block.text)) {
+          const sorted = sortSkillsBlock(block.text);
+          if (sorted !== block.text) {
+            body.system[i] = { ...block, text: sorted };
+          }
+        } else if (isDeferredToolsBlock(block.text)) {
+          const sorted = sortDeferredToolsBlock(block.text);
+          if (sorted !== block.text) {
+            body.system[i] = { ...block, text: sorted };
+          }
+        }
+      }
+    }
+
+    if (Array.isArray(body.tools)) {
+      body.tools.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
+    }
+  },
+};

package/proxy/extensions/ttl-management.mjs

@@ -0,0 +1,49 @@
+const TTL_MAIN = (process.env.CACHE_FIX_TTL_MAIN || "1h").toLowerCase();
+const TTL_SUBAGENT = (process.env.CACHE_FIX_TTL_SUBAGENT || "1h").toLowerCase();
+const AGENT_SDK_PREFIX = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
+
+function detectRequestType(system) {
+  if (!Array.isArray(system)) return "main";
+  const isSubagent = system.some(
+    (b) => b?.type === "text" && typeof b.text === "string" && b.text.startsWith(AGENT_SDK_PREFIX)
+  );
+  return isSubagent ? "subagent" : "main";
+}
+
+function injectTtl(block, ttlParam) {
+  if (block.cache_control?.type === "ephemeral" && !block.cache_control.ttl) {
+    return { ...block, cache_control: { ...block.cache_control, ttl: ttlParam } };
+  }
+  return block;
+}
+
+export default {
+  name: "ttl-management",
+  description: "Inject correct TTL on cache_control markers based on detected tier",
+  order: 500,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+    if (!body.system) return;
+
+    const requestType = detectRequestType(body.system);
+    const ttlValue = requestType === "subagent" ? TTL_SUBAGENT : TTL_MAIN;
+
+    if (ttlValue === "none") return;
+
+    const ttlParam = ttlValue === "5m" ? "5m" : "1h";
+
+    if (Array.isArray(body.system)) {
+      body.system = body.system.map((block) => injectTtl(block, ttlParam));
+    }
+
+    if (Array.isArray(body.messages)) {
+      for (const msg of body.messages) {
+        if (!Array.isArray(msg.content)) continue;
+        for (let i = 0; i < msg.content.length; i++) {
+          msg.content[i] = injectTtl(msg.content[i], ttlParam);
+        }
+      }
+    }
+  },
+};

package/proxy/extensions.json

@@ -0,0 +1,10 @@
+{
+  "fingerprint-strip": { "enabled": true, "order": 100 },
+  "sort-stabilization": { "enabled": true, "order": 200 },
+  "fresh-session-sort": { "enabled": true, "order": 250 },
+  "identity-normalization": { "enabled": true, "order": 300 },
+  "cache-control-normalize": { "enabled": true, "order": 400 },
+  "ttl-management": { "enabled": true, "order": 500 },
+  "cache-telemetry": { "enabled": true, "order": 600 },
+  "request-log": { "enabled": false, "order": 700 }
+}

package/proxy/pipeline.mjs

@@ -0,0 +1,96 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+let registry = [];
+
+export async function loadExtensions(dir, configPath) {
+  let config = {};
+  try {
+    const raw = await readFile(configPath, "utf8");
+    config = JSON.parse(raw);
+  } catch {}
+
+  const files = await readdir(dir);
+  const mjsFiles = files.filter((f) => f.endsWith(".mjs")).sort();
+
+  const extensions = [];
+  for (const file of mjsFiles) {
+    try {
+      const mod = await import(join(dir, file) + "?t=" + Date.now());
+      const ext = mod.default;
+      if (!ext || !ext.name) continue;
+
+      const cfg = config[ext.name];
+      const enabled = cfg?.enabled ?? ext.enabled ?? true;
+      const order = cfg?.order ?? ext.order ?? 1000;
+
+      if (enabled) {
+        extensions.push({ ...ext, order, _file: file });
+      }
+    } catch (err) {
+      process.stderr.write(`[pipeline] failed to load ${file}: ${err.message}\n`);
+    }
+  }
+
+  extensions.sort((a, b) => a.order - b.order);
+  registry = extensions;
+  return extensions;
+}
+
+export function getRegistry() {
+  return registry;
+}
+
+export function snapshotRegistry() {
+  return [...registry];
+}
+
+export async function runOnRequest(ctx, snapshot) {
+  const exts = snapshot || registry;
+  for (const ext of exts) {
+    if (!ext.onRequest) continue;
+    try {
+      const result = await ext.onRequest(ctx);
+      if (result && result.skip) return result;
+    } catch (err) {
+      process.stderr.write(`[pipeline] ${ext.name}.onRequest error: ${err.message}\n`);
+    }
+  }
+  return undefined;
+}
+
+export async function runOnResponseStart(ctx, snapshot) {
+  const exts = snapshot || registry;
+  for (const ext of exts) {
+    if (!ext.onResponseStart) continue;
+    try {
+      await ext.onResponseStart(ctx);
+    } catch (err) {
+      process.stderr.write(`[pipeline] ${ext.name}.onResponseStart error: ${err.message}\n`);
+    }
+  }
+}
+
+export async function runOnStreamEvent(ctx, snapshot) {
+  const exts = snapshot || registry;
+  for (const ext of exts) {
+    if (!ext.onStreamEvent) continue;
+    try {
+      await ext.onStreamEvent(ctx);
+    } catch (err) {
+      process.stderr.write(`[pipeline] ${ext.name}.onStreamEvent error: ${err.message}\n`);
+    }
+  }
+}
+
+export async function runOnResponse(ctx, snapshot) {
+  const exts = snapshot || registry;
+  for (const ext of exts) {
+    if (!ext.onResponse) continue;
+    try {
+      await ext.onResponse(ctx);
+    } catch (err) {
+      process.stderr.write(`[pipeline] ${ext.name}.onResponse error: ${err.message}\n`);
+    }
+  }
+}

package/proxy/server.mjs

@@ -0,0 +1,168 @@
+import http from "node:http";
+import config from "./config.mjs";
+import { forwardRequest } from "./upstream.mjs";
+import { streamResponse, createTelemetryRecord } from "./stream.mjs";
+import { loadExtensions, snapshotRegistry, runOnRequest, runOnResponseStart, runOnResponse } from "./pipeline.mjs";
+import { startWatcher } from "./watcher.mjs";
+
+function collectBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+async function handleMessages(clientReq, clientRes) {
+  const abortController = new AbortController();
+  const extSnapshot = snapshotRegistry();
+
+  clientReq.on("close", () => {
+    if (!clientRes.writableEnded) {
+      abortController.abort();
+    }
+  });
+
+  const rawBody = await collectBody(clientReq);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    parsed = null;
+  }
+
+  let forwardBody = rawBody;
+  const meta = {};
+
+  if (parsed && extSnapshot.length > 0) {
+    const reqCtx = { body: parsed, headers: { ...clientReq.headers }, meta };
+    const skipResult = await runOnRequest(reqCtx, extSnapshot);
+
+    if (skipResult && skipResult.skip) {
+      const status = skipResult.status || 400;
+      const body = skipResult.body || { error: "blocked_by_extension" };
+      clientRes.writeHead(status, { "content-type": "application/json" });
+      clientRes.end(JSON.stringify(body));
+      return;
+    }
+
+    forwardBody = Buffer.from(JSON.stringify(reqCtx.body));
+  }
+
+  const requestedModel = parsed?.model || null;
+
+  let upstreamRes, responseHeaders, statusCode;
+
+  try {
+    ({ upstreamRes, responseHeaders, statusCode } = await forwardRequest(
+      clientReq,
+      forwardBody,
+      abortController.signal
+    ));
+  } catch (err) {
+    if (abortController.signal.aborted) return;
+    clientRes.writeHead(502, { "content-type": "application/json" });
+    clientRes.end(JSON.stringify({ error: "upstream_error", message: err.message }));
+    return;
+  }
+
+  if (extSnapshot.length > 0) {
+    const resCtx = { status: statusCode, headers: responseHeaders, meta };
+    await runOnResponseStart(resCtx, extSnapshot);
+  }
+
+  const isStreaming = (responseHeaders["content-type"] || "").includes("text/event-stream");
+
+  if (!isStreaming) {
+    const chunks = [];
+    for await (const chunk of upstreamRes) chunks.push(chunk);
+    const rawResponse = Buffer.concat(chunks);
+
+    if (extSnapshot.length > 0) {
+      let responseBody;
+      try {
+        responseBody = JSON.parse(rawResponse.toString());
+      } catch {
+        responseBody = null;
+      }
+      if (responseBody) {
+        const resCtx = { status: statusCode, headers: responseHeaders, body: responseBody, meta };
+        await runOnResponse(resCtx, extSnapshot);
+        clientRes.writeHead(statusCode, resCtx.headers);
+        clientRes.end(JSON.stringify(resCtx.body));
+      } else {
+        clientRes.writeHead(statusCode, responseHeaders);
+        clientRes.end(rawResponse);
+      }
+    } else {
+      clientRes.writeHead(statusCode, responseHeaders);
+      clientRes.end(rawResponse);
+    }
+    return;
+  }
+
+  clientRes.writeHead(statusCode, responseHeaders);
+
+  const telemetry = createTelemetryRecord();
+  telemetry.requestedModel = requestedModel;
+
+  upstreamRes.on("error", (err) => {
+    if (!clientRes.writableEnded) {
+      clientRes.destroy(err);
+    }
+  });
+
+  try {
+    await streamResponse(upstreamRes, clientRes, telemetry, extSnapshot, meta, responseHeaders);
+  } catch (err) {
+    if (!clientRes.writableEnded) {
+      clientRes.destroy(err);
+    }
+  }
+}
+
+function handleHealth(_req, res) {
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify({ status: "ok" }));
+}
+
+function handleNotFound(_req, res) {
+  res.writeHead(404, { "content-type": "application/json" });
+  res.end(JSON.stringify({ error: "not_found" }));
+}
+
+const server = http.createServer((req, res) => {
+  if (req.method === "GET" && req.url === "/health") {
+    return handleHealth(req, res);
+  }
+  if (req.method === "POST" && req.url?.startsWith("/v1/messages")) {
+    return handleMessages(req, res);
+  }
+  handleNotFound(req, res);
+});
+
+function shutdown() {
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(1), 5000);
+}
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
+async function initPipeline() {
+  try {
+    await loadExtensions(config.extensionsDir, config.extensionsConfig);
+    startWatcher(config.extensionsDir, config.extensionsConfig);
+  } catch {}
+}
+
+initPipeline().then(() => {
+  server.listen(config.port, config.bind, () => {
+    const addr = server.address();
+    process.stdout.write(`proxy listening on ${addr.address}:${addr.port}\n`);
+  });
+});
+
+export { server };

package/proxy/stream.mjs

@@ -0,0 +1,110 @@
+import { runOnStreamEvent } from "./pipeline.mjs";
+
+export function createTelemetryRecord() {
+  return {
+    model: null,
+    requestedModel: null,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheRead: 0,
+    cacheCreation: 0,
+    stopReason: null,
+  };
+}
+
+function extractTelemetry(event, telemetry) {
+  if (event.type === "message_start" && event.message) {
+    const msg = event.message;
+    telemetry.model = msg.model || null;
+    if (msg.usage) {
+      telemetry.inputTokens = msg.usage.input_tokens || 0;
+      telemetry.cacheRead = msg.usage.cache_read_input_tokens || 0;
+      telemetry.cacheCreation = msg.usage.cache_creation_input_tokens || 0;
+    }
+  } else if (event.type === "message_delta") {
+    if (event.usage) {
+      telemetry.outputTokens = event.usage.output_tokens || 0;
+    }
+    telemetry.stopReason = event.delta?.stop_reason || null;
+  }
+}
+
+async function processLine(line, clientRes, telemetry, extSnapshot, meta, responseHeaders) {
+  if (!line.startsWith("data: ")) {
+    const ok = clientRes.write(line + "\n");
+    if (!ok) await new Promise((r) => clientRes.once("drain", r));
+    return;
+  }
+
+  const jsonStr = line.slice(6);
+  if (jsonStr === "[DONE]") {
+    const ok = clientRes.write(line + "\n");
+    if (!ok) await new Promise((r) => clientRes.once("drain", r));
+    return;
+  }
+
+  let event;
+  try {
+    event = JSON.parse(jsonStr);
+  } catch {
+    const ok = clientRes.write(line + "\n");
+    if (!ok) await new Promise((r) => clientRes.once("drain", r));
+    return;
+  }
+
+  extractTelemetry(event, telemetry);
+
+  if (!extSnapshot || extSnapshot.length === 0) {
+    const ok = clientRes.write(line + "\n");
+    if (!ok) await new Promise((r) => clientRes.once("drain", r));
+    return;
+  }
+
+  const ctx = { event, meta, telemetry, responseHeaders: responseHeaders || null, drop: false };
+  const originalRef = event;
+  await runOnStreamEvent(ctx, extSnapshot);
+
+  if (ctx.drop) return;
+
+  let output;
+  if (ctx.event === originalRef) {
+    output = line + "\n";
+  } else {
+    try {
+      output = "data: " + JSON.stringify(ctx.event) + "\n";
+    } catch {
+      output = line + "\n";
+    }
+  }
+
+  const ok = clientRes.write(output);
+  if (!ok) await new Promise((r) => clientRes.once("drain", r));
+}
+
+export async function streamResponse(upstreamRes, clientRes, telemetry, extSnapshot, meta, responseHeaders) {
+  let buffer = "";
+
+  for await (const chunk of upstreamRes) {
+    const text = chunk.toString();
+    buffer += text;
+
+    const lines = buffer.split("\n");
+    buffer = lines.pop();
+
+    for (const line of lines) {
+      if (line === "") {
+        const ok = clientRes.write("\n");
+        if (!ok) await new Promise((r) => clientRes.once("drain", r));
+      } else {
+        await processLine(line, clientRes, telemetry, extSnapshot, meta, responseHeaders);
+      }
+    }
+  }
+
+  if (buffer.length > 0) {
+    await processLine(buffer, clientRes, telemetry, extSnapshot, meta, responseHeaders);
+  }
+
+  clientRes.end();
+  return telemetry;
+}