claude-code-cache-fix 2.0.6 → 3.0.0

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

package/proxy/upstream.mjs

@@ -0,0 +1,93 @@
+import https from "node:https";
+import http from "node:http";
+import { URL } from "node:url";
+import config from "./config.mjs";
+
+const STRIP_REQUEST_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "transfer-encoding",
+  "te",
+  "upgrade",
+]);
+
+const STRIP_RESPONSE_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "transfer-encoding",
+]);
+
+function shouldStripRequestHeader(name) {
+  const lower = name.toLowerCase();
+  return STRIP_REQUEST_HEADERS.has(lower) || lower.startsWith("proxy-");
+}
+
+function shouldStripResponseHeader(name) {
+  return STRIP_RESPONSE_HEADERS.has(name.toLowerCase());
+}
+
+function buildUpstreamHeaders(incomingHeaders, upstreamHostname) {
+  const headers = {};
+  for (const [key, value] of Object.entries(incomingHeaders)) {
+    if (shouldStripRequestHeader(key)) continue;
+    headers[key] = value;
+  }
+  headers["host"] = upstreamHostname;
+  headers["accept-encoding"] = "identity";
+  return headers;
+}
+
+function filterResponseHeaders(rawHeaders) {
+  const headers = {};
+  for (const [key, value] of Object.entries(rawHeaders)) {
+    if (shouldStripResponseHeader(key)) continue;
+    headers[key] = value;
+  }
+  return headers;
+}
+
+export function forwardRequest(clientReq, body, signal) {
+  return new Promise((resolve, reject) => {
+    const upstreamUrl = new URL(clientReq.url, config.upstream);
+
+    const headers = buildUpstreamHeaders(clientReq.headers, upstreamUrl.hostname);
+    if (body) {
+      headers["content-length"] = Buffer.byteLength(body).toString();
+    }
+
+    const isHTTPS = upstreamUrl.protocol === "https:";
+    const transport = isHTTPS ? https : http;
+    const defaultPort = isHTTPS ? 443 : 80;
+
+    const options = {
+      hostname: upstreamUrl.hostname,
+      port: upstreamUrl.port || defaultPort,
+      path: upstreamUrl.pathname + upstreamUrl.search,
+      method: clientReq.method,
+      headers,
+      timeout: config.timeout,
+    };
+
+    const upstreamReq = transport.request(options, (upstreamRes) => {
+      const responseHeaders = filterResponseHeaders(upstreamRes.headers);
+      resolve({ upstreamRes, responseHeaders, statusCode: upstreamRes.statusCode });
+    });
+
+    upstreamReq.on("error", reject);
+    upstreamReq.on("timeout", () => {
+      upstreamReq.destroy(new Error("Upstream timeout"));
+    });
+
+    if (signal) {
+      signal.addEventListener("abort", () => {
+        upstreamReq.destroy(new Error("Request aborted"));
+      }, { once: true });
+    }
+
+    if (body) {
+      upstreamReq.end(body);
+    } else {
+      upstreamReq.end();
+    }
+  });
+}

package/proxy/watcher.mjs

@@ -0,0 +1,42 @@
+import { watch } from "node:fs";
+import { loadExtensions } from "./pipeline.mjs";
+
+let debounceTimer = null;
+
+export function startWatcher(extensionsDir, configPath, opts = {}) {
+  const debounceMs = opts.debounceMs ?? 100;
+  const onReload = opts.onReload;
+
+  function scheduleReload() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(async () => {
+      try {
+        const exts = await loadExtensions(extensionsDir, configPath);
+        if (onReload) onReload(exts);
+      } catch (err) {
+        process.stderr.write(`[watcher] reload failed: ${err.message}\n`);
+      }
+    }, debounceMs);
+  }
+
+  const dirWatcher = watch(extensionsDir, { persistent: false }, (eventType, filename) => {
+    if (filename && filename.endsWith(".mjs")) {
+      scheduleReload();
+    }
+  });
+
+  let configWatcher = null;
+  try {
+    configWatcher = watch(configPath, { persistent: false }, () => {
+      scheduleReload();
+    });
+  } catch {}
+
+  return {
+    close() {
+      dirWatcher.close();
+      if (configWatcher) configWatcher.close();
+      if (debounceTimer) clearTimeout(debounceTimer);
+    },
+  };
+}