lynkr 9.9.1 → 9.11.0

package/src/clients/databricks.js

@@ -299,8 +299,16 @@ async function invokeAzureAnthropic(body, incomingHeaders = {}) {
   }
 
   // OAuth passthrough: prefer incoming Bearer token (Claude Pro/Max subscription)
-  // over a configured API key.
-  const incomingAuth = incomingHeaders?.authorization || incomingHeaders?.Authorization;
+  // over a configured API key — but ONLY when it is actually an Anthropic
+  // token (sk-ant-*). OpenAI-shape clients (Codex, goose) send their own
+  // provider's Bearer, and forwarding that to api.anthropic.com earns a
+  // guaranteed 401 "Invalid bearer token" (live incident 2026-07-21, Codex
+  // via tier fallback).
+  let incomingAuth = incomingHeaders?.authorization || incomingHeaders?.Authorization;
+  if (incomingAuth && incomingAuth.startsWith("Bearer ") && !incomingAuth.slice("Bearer ".length).startsWith("sk-ant-")) {
+    logger.debug({ tokenShape: incomingAuth.slice(7, 15) + "…" }, "Azure Anthropic: ignoring non-Anthropic bearer token from client");
+    incomingAuth = null;
+  }
 
   // Headers Anthropic uses to verify client identity for subscription OAuth tokens.
   // If we strip these, Anthropic returns 429 rate_limit_error with no rate-limit
@@ -552,9 +560,20 @@ async function invokeOllama(body, incomingHeaders = {}) {
     if (body.tool_choice) ollamaBody.tool_choice = body.tool_choice;
     if (body.metadata) ollamaBody.metadata = body.metadata;
 
-    // Tools (already Anthropic format — no conversion needed)
+    // Tools: normalize to Anthropic shape. Callers that stayed OpenAI-format
+    // upstream (OpenWorker, aisuite, any client hitting /v1/chat/completions)
+    // otherwise ship {type:"function", function:{...}} which Ollama's
+    // /v1/messages endpoint rejects with 400 "can't find closing '}' symbol".
     if (supportsTools && Array.isArray(toolsToSend) && toolsToSend.length > 0) {
-      ollamaBody.tools = toolsToSend;
+      ollamaBody.tools = toolsToSend.map(tool =>
+        tool?.type === "function" && tool.function
+          ? {
+              name: tool.function.name,
+              description: tool.function.description || "",
+              input_schema: tool.function.parameters || { type: "object", properties: {} },
+            }
+          : tool
+      );
     }
 
     if (config.ollama.keepAlive !== undefined) {
@@ -1374,13 +1393,37 @@ async function invokeLlamaCpp(body, incomingHeaders = {}) {
     headers["Authorization"] = `Bearer ${config.llamacpp.apiKey}`;
   }
 
-  const messages = convertAnthropicMessagesToOpenRouter(body.messages || []);
+  let messages = convertAnthropicMessagesToOpenRouter(body.messages || []);
 
   if (body.system) {
     messages.unshift({ role: "system", content: body.system });
   }
 
-  // FIX: Deduplicate consecutive messages with same role (llama.cpp rejects this)
+  // Fold EVERY system-role message into one leading system message. Claude
+  // Code 2.1.216+ sends system-role entries inside `messages` (a leading one
+  // plus a trailing billing-header-tagged one), and strict Jinja chat
+  // templates (Qwen-family, e.g. Ornith) raise "System message must be at
+  // the beginning" for any non-leading system message. Folding preserves
+  // the content the old consecutive-dedup used to silently DROP.
+  const systemParts = [];
+  const nonSystem = [];
+  for (const msg of messages) {
+    if (msg.role === "system") {
+      const text = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+      if (text && text.trim()) systemParts.push(text);
+    } else {
+      nonSystem.push(msg);
+    }
+  }
+  if (systemParts.length > 0) {
+    nonSystem.unshift({ role: "system", content: systemParts.join("\n\n") });
+    if (systemParts.length > 1) {
+      logger.debug({ folded: systemParts.length }, "llama.cpp: folded system messages into one leading system message");
+    }
+  }
+  messages = nonSystem;
+
+  // Deduplicate consecutive messages with same role (llama.cpp rejects this)
   const deduplicated = [];
   let lastRole = null;
   for (const msg of messages) {
@@ -1460,7 +1503,20 @@ async function invokeLlamaCpp(body, incomingHeaders = {}) {
     }))
   }, "=== LLAMA.CPP REQUEST ===");
 
-  return performJsonRequest(endpoint, { headers, body: llamacppBody }, "llama.cpp");
+  const result = await performJsonRequest(endpoint, { headers, body: llamacppBody }, "llama.cpp");
+
+  // Context overflow is a CAPACITY error, not a request error: the local
+  // model's slot is simply too small for this conversation (llama-server
+  // splits -c across --parallel slots). Returning the 400 as-is fails the
+  // request AND records a provider "success" (nothing threw), so the
+  // tier-fallback ladder never rescues it. Throw instead — same pattern as
+  // _throwIfOllamaError — so invokeModel escalates to a bigger-context tier.
+  const _llamaErrMsg = result?.json?.error?.message || "";
+  if (!result?.ok && /exceeds the available context size/i.test(_llamaErrMsg)) {
+    throw new Error(`llama.cpp context overflow: ${_llamaErrMsg}`);
+  }
+
+  return result;
 }
 
 async function invokeLMStudio(body, incomingHeaders = {}) {
@@ -1889,6 +1945,21 @@ async function invokeZai(body, incomingHeaders = {}) {
       }, "=== INJECTING STANDARD TOOLS (Z.AI Anthropic) ===");
     }
 
+    // Normalize to Anthropic tool shape — the /anthropic/v1/messages endpoint
+    // rejects OpenAI-nested tools ({type:"function", function:{name,...}}) with
+    // 422 missing body.tools[0].name. Callers that stayed OpenAI-format upstream
+    // (OpenWorker, aisuite, any client hitting /v1/chat/completions with an
+    // unusual tool shape) get unwrapped here.
+    zaiBody.tools = zaiBody.tools.map(tool =>
+      tool?.type === "function" && tool.function
+        ? {
+            name: tool.function.name,
+            description: tool.function.description || "",
+            input_schema: tool.function.parameters || { type: "object", properties: {} },
+          }
+        : tool
+    );
+
     headers = {
       "Content-Type": "application/json",
       "x-api-key": config.zai.apiKey,
@@ -1974,13 +2045,17 @@ async function invokeMoonshot(body, incomingHeaders = {}) {
 
   // Model mapping: Anthropic names → Moonshot/Kimi names
   const modelMap = {
-    "claude-sonnet-4-5-20250929": "kimi-k2-turbo-preview",
-    "claude-sonnet-4-5": "kimi-k2-turbo-preview",
-    "claude-sonnet-4.5": "kimi-k2-turbo-preview",
-    "claude-3-5-sonnet": "kimi-k2-turbo-preview",
-    "claude-haiku-4-5-20251001": "kimi-k2-turbo-preview",
-    "claude-haiku-4-5": "kimi-k2-turbo-preview",
-    "claude-3-haiku": "kimi-k2-turbo-preview",
+    "claude-sonnet-4-5-20250929": "kimi-k2.6",
+    "claude-sonnet-4-5": "kimi-k2.6",
+    "claude-sonnet-4.5": "kimi-k2.6",
+    "claude-3-5-sonnet": "kimi-k2.6",
+    "claude-haiku-4-5-20251001": "kimi-k2.6",
+    "claude-haiku-4-5": "kimi-k2.6",
+    "claude-3-haiku": "kimi-k2.6",
+    // Retired ids (gone from /v1/models as of 2026-07: "Not found the model")
+    // that older tier configs may still reference.
+    "kimi-k2-turbo-preview": "kimi-k2.6",
+    "kimi-k2-thinking": "kimi-k3",
     // moonshot-v1-auto 400s with "tokenization failed" (its server-side auto
     // context-size pass fails on large tool-bearing payloads). Remap to a
     // fixed model that's broadly available on api.moonshot.ai.
@@ -1988,7 +2063,12 @@ async function invokeMoonshot(body, incomingHeaders = {}) {
   };
 
   const requestedModel = body._tierModel || body.model || config.moonshot.model;
-  let mappedModel = modelMap[requestedModel] || config.moonshot.model || "kimi-k2-turbo-preview";
+  // Honor tier-selected Moonshot ids (e.g. TIER_REASONING=moonshot:kimi-k2.6)
+  // instead of silently swapping in the .env default model.
+  let mappedModel = modelMap[requestedModel]
+    || (/^(kimi-|moonshot-v1)/i.test(requestedModel || "") ? requestedModel : null)
+    || config.moonshot.model
+    || "kimi-k3";
   // Guard against the deprecated auto model arriving via config too.
   if (mappedModel === "moonshot-v1-auto") mappedModel = "moonshot-v1-128k";
 
@@ -2002,18 +2082,18 @@ async function invokeMoonshot(body, incomingHeaders = {}) {
     messages.unshift({ role: "system", content: systemContent });
   }
 
-  // kimi-k2.x (k2.5 / k2.6 …) are thinking models that only accept
-  // temperature: 1 — any other value 400s with "invalid temperature".
-  const isKimiThinking = /^kimi-k2/i.test(mappedModel);
+  // Every current kimi-k* model (k2.5, k2.6, k2.7-code, k3, …) pins sampling
+  // params: temperature must be 1 — any other value 400s with "invalid
+  // temperature: only 1 is allowed for this model" (probed live 2026-07-23).
+  // Only the moonshot-v1-* models accept caller-supplied values.
+  const isKimiPinned = /^kimi-k/i.test(mappedModel);
 
   const moonshotBody = {
     model: mappedModel,
     messages,
     max_tokens: body.max_tokens || 16384,
-    // kimi-k2.x thinking models pin sampling params: temperature must be 1
-    // and top_p must be 0.95 — any other value 400s.
-    temperature: isKimiThinking ? 1 : (body.temperature ?? 0.7),
-    top_p: isKimiThinking ? 0.95 : (body.top_p ?? 1.0),
+    temperature: isKimiPinned ? 1 : (body.temperature ?? 0.7),
+    top_p: isKimiPinned ? 0.95 : (body.top_p ?? 1.0),
     stream: false,  // Force non-streaming - OpenAI SSE to Anthropic SSE conversion not implemented
   };
 
@@ -2633,6 +2713,43 @@ function stripLynkrBadges(messages) {
   return mutated ? out : messages;
 }
 
+// Single source of truth for provider dispatch. Both the initial call and the
+// fallback ladder MUST route through invokeProvider — the previous duplicated
+// if/else chains drifted (the fallback chain was missing ollama, bedrock,
+// lmstudio and codex), and unknown providers silently dialed databricks,
+// which under tier routing is a deliberate dead number (see .env note about
+// the 2026-07-07 self-loop incident). Add new providers HERE, nowhere else;
+// the registry-coverage unit test fails if this map and
+// SUPPORTED_MODEL_PROVIDERS fall out of sync.
+const PROVIDER_INVOKERS = {
+  "azure-openai": invokeAzureOpenAI,
+  "azure-anthropic": invokeAzureAnthropic,
+  ollama: invokeOllama,
+  openrouter: invokeOpenRouter,
+  edenai: invokeEdenAI,
+  openai: invokeOpenAI,
+  llamacpp: invokeLlamaCpp,
+  lmstudio: invokeLMStudio,
+  bedrock: invokeBedrock,
+  zai: invokeZai,
+  vertex: invokeVertex,
+  moonshot: invokeMoonshot,
+  codex: invokeCodex,
+};
+
+function invokeProvider(provider, body, incomingHeaders) {
+  const invoke = PROVIDER_INVOKERS[provider];
+  if (!invoke) {
+    // databricks itself, or an unknown name. Loud, not silent: under tier
+    // routing this path used to swallow misconfigured providers.
+    if (provider !== "databricks") {
+      logger.warn({ provider }, "No invoker registered for provider — defaulting to databricks");
+    }
+    return invokeDatabricks(body, incomingHeaders);
+  }
+  return invoke(body, incomingHeaders);
+}
+
 async function invokeModel(body, options = {}) {
   const { determineProviderSmart, isFallbackEnabled, getFallbackProvider } = require("./routing");
   const metricsCollector = getMetricsCollector();
@@ -2681,7 +2798,13 @@ async function invokeModel(body, options = {}) {
         _queryText: body._queryText ?? null,
       }
     : await determineProviderSmart(body, { workspace, tenantPolicy });
-  const initialProvider = routingResult.provider;
+  // Canonicalize the provider name ONCE. Tier configs write z.ai as "z-ai";
+  // every dispatch case, breaker, and health key below uses "zai". Without
+  // this the dispatch chain falls through to the Databricks default — whose
+  // base is a deliberate fail-fast dummy port in tier-routing setups — so
+  // every "z-ai" tier request died with fetch's bad-port blocklist while
+  // z.ai itself was perfectly healthy (live incident 2026-07-21/22).
+  const initialProvider = routingResult.provider === "z-ai" ? "zai" : routingResult.provider;
   const tierSelectedModel = routingResult.model;
 
   // Inject tier-selected model into body so provider functions can use it
@@ -2783,34 +2906,7 @@ async function invokeModel(body, options = {}) {
 
   try {
     const result = await breaker.execute(async () => {
-      if (initialProvider === "azure-openai") {
-        return await invokeAzureOpenAI(body, incomingHeaders);
-      } else if (initialProvider === "azure-anthropic") {
-        return await invokeAzureAnthropic(body, incomingHeaders);
-      } else if (initialProvider === "ollama") {
-        return await invokeOllama(body, incomingHeaders);
-      } else if (initialProvider === "openrouter") {
-        return await invokeOpenRouter(body, incomingHeaders);
-      } else if (initialProvider === "edenai") {
-        return await invokeEdenAI(body, incomingHeaders);
-      } else if (initialProvider === "openai") {
-        return await invokeOpenAI(body, incomingHeaders);
-      } else if (initialProvider === "llamacpp") {
-        return await invokeLlamaCpp(body, incomingHeaders);
-      } else if (initialProvider === "lmstudio") {
-        return await invokeLMStudio(body, incomingHeaders);
-      } else if (initialProvider === "bedrock") {
-        return await invokeBedrock(body, incomingHeaders);
-      } else if (initialProvider === "zai") {
-        return await invokeZai(body, incomingHeaders);
-      } else if (initialProvider === "vertex") {
-        return await invokeVertex(body, incomingHeaders);
-      } else if (initialProvider === "moonshot") {
-        return await invokeMoonshot(body, incomingHeaders);
-      } else if (initialProvider === "codex") {
-        return await invokeCodex(body, incomingHeaders);
-      }
-      return await invokeDatabricks(body, incomingHeaders);
+      return await invokeProvider(initialProvider, body, incomingHeaders);
     });
 
     const latency = Date.now() - startTime;
@@ -2903,6 +2999,7 @@ async function invokeModel(body, options = {}) {
       candidates: routingResult.candidates ?? null,
       pinned: routingResult.pinned ? 1 : 0,
       switch_reason: routingResult.switch_reason ?? null,
+      cache_decision: routingResult._cacheDecision ?? null,
     });
 
     // WS5.4 — feedback loop (success path).
@@ -2984,6 +3081,29 @@ async function invokeModel(body, options = {}) {
     healthTracker.recordFailure(initialProvider, err, err.status);
     getLatencyTracker().record(initialProvider, routingDecision?.model, failLatency);
 
+    // Accumulate every provider failure for this request so the terminal
+    // error can tell the client WHY nothing answered (quota exhausted vs
+    // context overflow vs dead config) instead of only the last rung's
+    // error. Rendered by the SSE writer when the whole chain fails.
+    const failureTrail = [
+      `${initialProvider}${routingDecision?.model ? ` (${routingDecision.model})` : ""}: ${err.status ? `HTTP ${err.status} — ` : ""}${err.message}`,
+    ];
+
+    // undici wraps every network failure as "TypeError: fetch failed" — the
+    // actionable detail (ENOTFOUND vs ECONNRESET vs ETIMEDOUT vs TLS) lives
+    // in err.cause. Without this line the z-ai breaker trips on repeated
+    // "fetch failed" with nothing to diagnose (live incidents 2026-07-21/22:
+    // ~5ms failures from a long-lived process while fresh processes succeed).
+    logger.warn({
+      provider: initialProvider,
+      model: routingDecision?.model ?? null,
+      error: err.message,
+      causeCode: err.cause?.code ?? null,
+      causeMessage: err.cause?.message ?? null,
+      causeErrors: Array.isArray(err.cause?.errors) ? err.cause.errors.map((e) => e.code || e.message).slice(0, 4) : null,
+      failLatencyMs: failLatency,
+    }, "Provider invocation failed");
+
     // Tier-aware escalate-then-demote fallback (TIER_FALLBACK_ENABLED).
     // On failure, try a MORE capable tier first (climb toward REASONING); only
     // if every higher tier is unavailable do we fall downward to SIMPLE/local.
@@ -3011,9 +3131,30 @@ async function invokeModel(body, options = {}) {
               _cascadeInner: true,
               workspace,
               tenantPolicy,
+              // Forward the client's headers: azure-anthropic in wrap mode
+              // authenticates with the incoming OAuth Bearer token, so a
+              // fallback attempt without headers is guaranteed to fail with
+              // "requires authentication".
+              headers: incomingHeaders,
             }
           );
 
+          // A candidate that answers with an error is a FAILED candidate,
+          // not a serve. Provider clients return {ok:false} on 4xx instead
+          // of throwing, and serving that here hands the client a 401/403
+          // while healthier rungs below never get tried (live incident
+          // 2026-07-21: Codex request served azure-anthropic's 401 while
+          // llamacpp sat idle one rung down).
+          if (attempt?.ok === false) {
+            logger.warn({
+              toProvider: cand.provider,
+              status: attempt.status,
+              error: attempt.json?.error?.message || attempt.text?.slice(0, 120) || null,
+            }, "[TierFallback] Candidate answered with an error response, trying next");
+            failureTrail.push(`${cand.provider} (${cand.model}): HTTP ${attempt.status} — ${attempt.json?.error?.message || attempt.text?.slice(0, 120) || "error response"}`);
+            continue;
+          }
+
           metricsCollector.recordFallbackAttempt(initialProvider, cand.provider, "tier_fallback");
           logger.warn({
             servedTier: cand.tier,
@@ -3041,6 +3182,7 @@ async function invokeModel(body, options = {}) {
             { toProvider: cand.provider, error: innerErr.message },
             "[TierFallback] Candidate failed, trying next"
           );
+          failureTrail.push(`${cand.provider} (${cand.model}): ${innerErr.message}`);
         }
       }
       logger.warn(
@@ -3089,6 +3231,7 @@ async function invokeModel(body, options = {}) {
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
+      cache_decision: routingResult._cacheDecision ?? null,
       });
 
       // WS5.4 — feedback loop (primary-failed, no fallback). Low quality
@@ -3108,6 +3251,7 @@ async function invokeModel(body, options = {}) {
         },
       });
 
+      err.lynkrFailureTrail = failureTrail;
       throw err;
     }
 
@@ -3135,26 +3279,7 @@ async function invokeModel(body, options = {}) {
       const fallbackStart = Date.now();
 
       const fallbackResult = await fallbackBreaker.execute(async () => {
-        if (fallbackProvider === "azure-openai") {
-          return await invokeAzureOpenAI(body, incomingHeaders);
-        } else if (fallbackProvider === "azure-anthropic") {
-          return await invokeAzureAnthropic(body, incomingHeaders);
-        } else if (fallbackProvider === "openrouter") {
-          return await invokeOpenRouter(body, incomingHeaders);
-        } else if (fallbackProvider === "edenai") {
-          return await invokeEdenAI(body, incomingHeaders);
-        } else if (fallbackProvider === "openai") {
-          return await invokeOpenAI(body, incomingHeaders);
-        } else if (fallbackProvider === "llamacpp") {
-          return await invokeLlamaCpp(body, incomingHeaders);
-        } else if (fallbackProvider === "zai") {
-          return await invokeZai(body, incomingHeaders);
-        } else if (fallbackProvider === "vertex") {
-          return await invokeVertex(body, incomingHeaders);
-        } else if (fallbackProvider === "moonshot") {
-          return await invokeMoonshot(body, incomingHeaders);
-        }
-        return await invokeDatabricks(body, incomingHeaders);
+        return await invokeProvider(fallbackProvider, body, incomingHeaders);
       });
 
       const fallbackLatency = Date.now() - fallbackStart;
@@ -3225,6 +3350,7 @@ async function invokeModel(body, options = {}) {
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
+      cache_decision: routingResult._cacheDecision ?? null,
       });
 
       // WS5.4 — feedback loop (fallback success). The served provider
@@ -3244,6 +3370,16 @@ async function invokeModel(body, options = {}) {
         },
       });
 
+      // The last rung also answered with an error — thread the whole trail
+      // into the error payload so the client sees every failure, not just
+      // this one (e.g. "moonshot: quota" matters more than "azure: 404").
+      if (fallbackResult?.ok === false) {
+        failureTrail.push(`${fallbackProvider}: HTTP ${fallbackResult.status} — ${fallbackResult.json?.error?.message || String(fallbackResult.text || "").slice(0, 120) || "error response"}`);
+        if (fallbackResult.json && typeof fallbackResult.json === "object") {
+          fallbackResult.json._lynkr_failure_trail = failureTrail;
+        }
+      }
+
       return {
         ...fallbackResult,
         actualProvider: fallbackProvider,
@@ -3282,6 +3418,7 @@ async function invokeModel(body, options = {}) {
         candidates: routingResult.candidates ?? null,
         pinned: routingResult.pinned ? 1 : 0,
         switch_reason: routingResult.switch_reason ?? null,
+      cache_decision: routingResult._cacheDecision ?? null,
       });
 
       // WS5.4 — feedback loop (double failure). quality=0 is a hard
@@ -3308,6 +3445,8 @@ async function invokeModel(body, options = {}) {
       }, "Both primary and fallback provider failed");
 
       // Return fallback error (more actionable than Ollama error)
+      failureTrail.push(`${fallbackProvider}: ${fallbackErr.message}`);
+      fallbackErr.lynkrFailureTrail = failureTrail;
       throw fallbackErr;
     }
   }
@@ -3370,6 +3509,11 @@ function destroyHttpAgents() {
 
 module.exports = {
   invokeModel,
+  invokeAzureAnthropic,
+  invokeZai,
+  invokeOllama,
+  invokeMoonshot,
+  PROVIDER_INVOKERS,
   stripLynkrBadges,
   destroyHttpAgents,
   normalizeBodyForConverse,

package/src/clients/gpt-utils.js

@@ -61,7 +61,14 @@ function areSimilarToolCalls(call1, call2) {
 
   // Only search-style tools get fuzzy matching; mutating tools with
   // near-identical args may be intentional repeats.
-  const searchTools = ['grep', 'glob', 'search', 'find', 'read', 'bash', 'shell'];
+  // 'read' is deliberately NOT fuzzy-matched: its argument is a file path, and
+  // absolute paths in one repo share nearly every Jaccard token
+  // (/Users/x/project/src/…), so reads of DIFFERENT files scored ≥0.8 and
+  // merged into one "repeated call" signature (live incident: an opencode
+  // code-trace reading server.js, openai-router.js and orchestrator/index.js
+  // was flagged as a loop). A genuine re-read of the same file is caught by
+  // the exact-match branch above.
+  const searchTools = ['grep', 'glob', 'search', 'find', 'bash', 'shell'];
   const toolName = (name1 || '').toLowerCase();
   const isSearchTool = searchTools.some(t => toolName.includes(t));
 

package/src/clients/ollama-utils.js

@@ -128,17 +128,26 @@ function convertAnthropicToolsToOllama(anthropicTools) {
     return [];
   }
 
-  return anthropicTools.map(tool => ({
-    type: "function",
-    function: {
-      name: tool.name,
-      description: tool.description || "",
-      parameters: tool.input_schema || {
-        type: "object",
-        properties: {},
+  return anthropicTools.map(tool => {
+    // Shape-detect: already OpenAI/Ollama-format tools pass through untouched.
+    // Without this, an OpenAI-shape tool ({type:"function", function:{...}})
+    // reaching this helper produces {function:{name:undefined,...}}, which
+    // Ollama's legacy /api/chat endpoint rejects.
+    if (tool?.type === "function" && tool.function) {
+      return tool;
+    }
+    return {
+      type: "function",
+      function: {
+        name: tool.name,
+        description: tool.description || "",
+        parameters: tool.input_schema || {
+          type: "object",
+          properties: {},
+        },
       },
-    },
-  }));
+    };
+  });
 }
 
 module.exports = {

package/src/clients/prompt-cache-injection.js

@@ -4,9 +4,24 @@
  * Injects `cache_control` breakpoints into requests for providers
  * that support explicit prompt caching (Anthropic, Bedrock, Vertex/Gemini).
  *
- * Strategy: "system_and_3" — places up to 4 breakpoints:
- *   1. System prompt (stable across turns — highest cache hit rate)
- *   2-4. Last 3 non-system messages (rolling window)
+ * Strategy: "stable_hierarchy" — up to 4 breakpoints ordered by stability
+ * (Phase 5, cache-aware routing):
+ *   1. Tools block  — never moves (tools render before system in the
+ *      provider's prefix, so this read point survives system edits)
+ *   2. System prompt — never moves
+ *   3. Frozen history boundary — advances only every K user turns
+ *      (K = config.memory.distillation.refreshEveryTurns, default 5; shared
+ *      with the distiller's freeze window). Deterministic from the message
+ *      list, so consecutive requests inside a bucket mark the same bytes.
+ *   4. Rolling marker on the newest message — pays the 1.25x write on the
+ *      per-turn delta once so the next turn reads it at 0.1x. Kept
+ *      deliberately: dropping it would re-pay full input price on
+ *      everything after the boundary every turn until the next refresh.
+ *
+ * The previous "system_and_3" strategy rolled breakpoints 2-4 across the
+ * last three messages; markers moved every turn, and history-rewriting
+ * layers (distiller) invalidated the prefix wholesale. Stability of the
+ * marked bytes is what compounds hits.
  *
  * Providers with automatic caching (OpenAI, DeepSeek) need no injection.
  *
@@ -17,12 +32,64 @@ const logger = require('../logger');
 
 const CACHE_MARKER = { type: 'ephemeral' };
 const MAX_BREAKPOINTS = 4;
+const DEFAULT_BOUNDARY_EVERY_TURNS = 5;
+
+function _boundaryEveryTurns() {
+  try {
+    const config = require('../config');
+    const k = config.memory?.distillation?.refreshEveryTurns;
+    return Number.isFinite(k) && k > 0 ? k : DEFAULT_BOUNDARY_EVERY_TURNS;
+  } catch {
+    return DEFAULT_BOUNDARY_EVERY_TURNS;
+  }
+}
+
+/** Mark the last content block of a message; converts string content. */
+function _markMessage(msg) {
+  if (!msg) return false;
+  if (typeof msg.content === 'string') {
+    msg.content = [{
+      type: 'text',
+      text: msg.content,
+      cache_control: CACHE_MARKER,
+    }];
+    return true;
+  }
+  if (Array.isArray(msg.content) && msg.content.length > 0) {
+    const lastBlock = msg.content[msg.content.length - 1];
+    if (lastBlock && typeof lastBlock === 'object' && !lastBlock.cache_control) {
+      lastBlock.cache_control = CACHE_MARKER;
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Index of the frozen-boundary message: the bucket-th user-role message,
+ * where bucket = floor(userTurns / K) * K. Deterministic in the message
+ * list, so every request inside a K-turn bucket marks the same message —
+ * the marked prefix bytes stay identical until the bucket advances.
+ *
+ * @returns {number} message index, or -1 when the conversation is too
+ *   young (bucket < K) or the boundary can't be placed.
+ */
+function _frozenBoundaryIndex(messages, everyTurns) {
+  if (!Array.isArray(messages) || messages.length === 0) return -1;
+  const userIdx = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i]?.role === 'user') userIdx.push(i);
+  }
+  const bucket = Math.floor(userIdx.length / everyTurns) * everyTurns;
+  if (bucket < everyTurns) return -1;
+  return userIdx[bucket - 1];
+}
 
 /**
  * Inject cache_control breakpoints into an Anthropic-format request body.
  * Mutates the body in-place for zero-copy performance.
  *
- * @param {Object} body - Request body with system and messages
+ * @param {Object} body - Request body with system, tools, and messages
  * @returns {number} Number of breakpoints injected
  */
 function injectAnthropicCacheBreakpoints(body) {
@@ -30,7 +97,16 @@ function injectAnthropicCacheBreakpoints(body) {
 
   let injected = 0;
 
-  // Breakpoint 1: System prompt
+  // Breakpoint 1: tools block — most stable prefix region.
+  if (Array.isArray(body.tools) && body.tools.length > 0) {
+    const lastTool = body.tools[body.tools.length - 1];
+    if (lastTool && typeof lastTool === 'object' && !lastTool.cache_control) {
+      lastTool.cache_control = CACHE_MARKER;
+      injected++;
+    }
+  }
+
+  // Breakpoint 2: system prompt.
   if (body.system) {
     if (typeof body.system === 'string') {
       // Convert string system to array format for cache_control support
@@ -50,32 +126,19 @@ function injectAnthropicCacheBreakpoints(body) {
     }
   }
 
-  // Breakpoints 2-4: Last 3 non-system messages
   if (Array.isArray(body.messages) && body.messages.length > 0) {
-    const remaining = MAX_BREAKPOINTS - injected;
-    const messagesToMark = Math.min(remaining, 3, body.messages.length);
-
-    for (let i = 0; i < messagesToMark; i++) {
-      const msgIdx = body.messages.length - 1 - i;
-      const msg = body.messages[msgIdx];
-      if (!msg) continue;
-
-      if (typeof msg.content === 'string') {
-        // Convert string content to array for cache_control
-        msg.content = [{
-          type: 'text',
-          text: msg.content,
-          cache_control: CACHE_MARKER,
-        }];
-        injected++;
-      } else if (Array.isArray(msg.content) && msg.content.length > 0) {
-        // Mark the last content block in this message
-        const lastBlock = msg.content[msg.content.length - 1];
-        if (lastBlock && typeof lastBlock === 'object' && !lastBlock.cache_control) {
-          lastBlock.cache_control = CACHE_MARKER;
-          injected++;
-        }
-      }
+    const lastIdx = body.messages.length - 1;
+
+    // Breakpoint 3: frozen history boundary (advances every K user turns).
+    const boundaryIdx = _frozenBoundaryIndex(body.messages, _boundaryEveryTurns());
+    if (boundaryIdx >= 0 && boundaryIdx < lastIdx && injected < MAX_BREAKPOINTS) {
+      if (_markMessage(body.messages[boundaryIdx])) injected++;
+    }
+
+    // Breakpoint 4: rolling marker on the newest message — caches this
+    // turn's delta so the next turn reads it instead of re-paying input.
+    if (injected < MAX_BREAKPOINTS) {
+      if (_markMessage(body.messages[lastIdx])) injected++;
     }
   }