lynkr 9.10.0 → 9.12.0

package/src/clients/databricks.js

@@ -310,6 +310,18 @@ async function invokeAzureAnthropic(body, incomingHeaders = {}) {
     incomingAuth = null;
   }
 
+  // Anthropic OAuth tokens are only meaningful at api.anthropic.com. When this
+  // provider points at any OTHER Anthropic-compatible host (Azure AI Foundry
+  // Claude, a corporate gateway), forwarding Claude Code's sk-ant-oat token
+  // earns a 401 there — and the configured x-api-key below is the right auth.
+  // This also means a subscription token never leaves the box unless the
+  // endpoint is Anthropic itself.
+  const isAnthropicDirect = String(config.azureAnthropic.endpoint || "").includes("api.anthropic.com");
+  if (incomingAuth && !isAnthropicDirect) {
+    logger.debug({ endpoint: config.azureAnthropic.endpoint }, "Azure Anthropic: non-Anthropic endpoint — using configured API key instead of client OAuth token");
+    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
   // headers (its terse anti-proxy response). Forward every Anthropic-relevant
@@ -560,9 +572,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) {
@@ -1934,6 +1957,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,
@@ -2019,13 +2057,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.
@@ -2033,7 +2075,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";
 
@@ -2047,19 +2094,23 @@ 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),
-    stream: false,  // Force non-streaming - OpenAI SSE to Anthropic SSE conversion not implemented
+    temperature: isKimiPinned ? 1 : (body.temperature ?? 0.7),
+    top_p: isKimiPinned ? 0.95 : (body.top_p ?? 1.0),
+    // Streaming honored since the Phase-2b sse-transformer landed: the raw
+    // OpenAI SSE stream is returned below and reshaped in flight by the
+    // orchestrator (moonshot is in DEFAULT_OPENAI_SSE_PROVIDERS). Buffered
+    // requests keep the Anthropic conversion path unchanged.
+    stream: body.stream ?? false,
   };
 
   if (Array.isArray(body.tools) && body.tools.length > 0) {
@@ -2097,6 +2148,13 @@ async function invokeMoonshot(body, incomingHeaders = {}) {
     throw err;
   }
 
+  // Streaming request: hand the raw OpenAI SSE stream to the orchestrator's
+  // stream branch (sse-transformer reshapes it). The Anthropic conversion
+  // below is buffered-only — it would consume the stream.
+  if (response?.stream) {
+    return response;
+  }
+
   const rawMsg = response?.json?.choices?.[0]?.message;
   logger.debug({
     responseOk: response?.ok,
@@ -2678,6 +2736,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();
@@ -2834,34 +2929,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;
@@ -2954,6 +3022,9 @@ 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,
+      cache_read_tokens: result.json?.usage?.cache_read_input_tokens ?? null,
+      cache_creation_tokens: result.json?.usage?.cache_creation_input_tokens ?? null,
     });
 
     // WS5.4 — feedback loop (success path).
@@ -3035,6 +3106,14 @@ 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
@@ -3097,6 +3176,7 @@ async function invokeModel(body, options = {}) {
               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;
           }
 
@@ -3127,6 +3207,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(
@@ -3175,6 +3256,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
@@ -3194,6 +3276,7 @@ async function invokeModel(body, options = {}) {
         },
       });
 
+      err.lynkrFailureTrail = failureTrail;
       throw err;
     }
 
@@ -3221,26 +3304,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;
@@ -3311,6 +3375,9 @@ 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,
+      cache_read_tokens: fallbackResult.json?.usage?.cache_read_input_tokens ?? null,
+      cache_creation_tokens: fallbackResult.json?.usage?.cache_creation_input_tokens ?? null,
       });
 
       // WS5.4 — feedback loop (fallback success). The served provider
@@ -3330,6 +3397,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,
@@ -3368,6 +3445,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
@@ -3394,6 +3472,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;
     }
   }
@@ -3459,6 +3539,8 @@ module.exports = {
   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++;
     }
   }