comisai 1.0.4

package/node_modules/@comis/agent/dist/executor/stream-wrappers/request-body-injector.js

@@ -0,0 +1,1679 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Request body injector stream wrapper.
+ *
+ * Mutates the outgoing request body via the onPayload hook. Consolidates:
+ * 1. Cache breakpoints (Anthropic-family): cache_control markers
+ * 2. 1M beta header (direct Anthropic only)
+ * 3. service_tier (Responses API + fastMode)
+ * 4. store (Responses API + storeCompletions)
+ *
+ * Cache breakpoints:
+ *
+ * @module
+ */
+import { SYSTEM_PROMPT_DYNAMIC_BOUNDARY, resolveBreakpointStrategy } from "./config-resolver.js";
+import { createAccumulativeLatch } from "../session-latch.js";
+import { MIN_CACHEABLE_TOKENS, DEFAULT_MIN_CACHEABLE_TOKENS, CHARS_PER_TOKEN_RATIO, CHARS_PER_TOKEN_RATIO_STRUCTURED, CACHE_LOOKBACK_WINDOW } from "../../context-engine/index.js";
+import { estimateContextChars } from "../../safety/token-estimator.js";
+import { computeHash, djb2 } from "../cache-break-detection.js";
+// ---------------------------------------------------------------------------
+// Tool schema caches extracted to tool-schema-cache.ts (leaf module).
+// Re-exported here for backward compatibility with existing consumers.
+// ---------------------------------------------------------------------------
+import { sessionRenderedToolCache, getOrCacheRenderedTool } from "./tool-schema-cache.js";
+export { clearSessionRenderedToolCache, getOrCacheRenderedTool, clearSessionPerToolCache } from "./tool-schema-cache.js";
+// ---------------------------------------------------------------------------
+// Sticky-on beta header latches.
+// Tracks individual beta header values seen per session. Once a beta value
+// appears in any API call, it is latched and included in all subsequent calls.
+// Prevents mid-session beta header toggling from busting the cache prefix.
+// ---------------------------------------------------------------------------
+const sessionBetaHeaderLatches = new Map();
+// ---------------------------------------------------------------------------
+// Prefix stability tracking.
+// Hashes the first N messages before microcompaction to detect prefix instability.
+// When the prefix hash changes on consecutive turns, the cache prefix is unstable
+// and every turn will miss cache reads beyond the system prompt.
+// ---------------------------------------------------------------------------
+const sessionPrefixStability = new Map();
+export function clearSessionPrefixStability(sessionKey) {
+    sessionPrefixStability.delete(sessionKey);
+}
+export function clearSessionBetaHeaderLatches(sessionKey) {
+    sessionBetaHeaderLatches.delete(sessionKey);
+}
+// ---------------------------------------------------------------------------
+// Per-model cache retention override resolution.
+// Enables selectively disabling or changing prompt caching for specific model
+// families. Longest-prefix-first matching ensures specific model variants
+// (e.g., "claude-sonnet-4-6") take priority over broad families ("claude-sonnet").
+// ---------------------------------------------------------------------------
+/**
+ * Resolve effective cache retention for a model, considering per-model overrides.
+ * Uses longest-prefix-first matching: "claude-sonnet-4-6" wins over "claude-sonnet".
+ *
+ * @param modelId - Full model identifier (e.g., "claude-sonnet-4-6-20260301")
+ * @param agentRetention - Agent-level default cache retention
+ * @param overrides - Optional per-model family overrides (prefix -> retention)
+ * @returns Resolved cache retention value
+ */
+export function resolveCacheRetention(modelId, agentRetention, overrides) {
+    if (!overrides || Object.keys(overrides).length === 0) {
+        return agentRetention;
+    }
+    // Sort by key length descending (longest-prefix-first)
+    const sorted = Object.entries(overrides).sort((a, b) => b[0].length - a[0].length);
+    for (const [prefix, retention] of sorted) {
+        if (modelId.startsWith(prefix))
+            return retention;
+    }
+    return agentRetention;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Anthropic beta header for 1M context window. */
+const CONTEXT_1M_BETA = "context-1m-2025-08-07";
+/** Anthropic-family providers that support cache_control breakpoints. */
+const ANTHROPIC_FAMILY = new Set(["anthropic", "anthropic-vertex", "amazon-bedrock"]);
+/** Check if a model uses the OpenAI Responses API. */
+function isResponsesApiProvider(model) {
+    return model.api === "openai-responses" || model.api === "azure-openai-responses";
+}
+/** Parse a comma-separated header list, returning individual values. */
+function parseHeaderList(header) {
+    if (!header)
+        return [];
+    return header.split(",").map(s => s.trim()).filter(Boolean);
+}
+/**
+ * Compute a hash of rendered tools excluding cache_control.
+ * Uses computeHash (djb2 over JSON.stringify) from cache-break-detection.
+ */
+function computeRenderedToolsHash(tools) {
+    const forHash = tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.input_schema,
+    }));
+    return computeHash(forHash);
+}
+/**
+ * Pre-sorted MIN_CACHEABLE_TOKENS entries by key length descending.
+ * Ensures longest-prefix-first matching: "claude-opus-4-6" (len 15)
+ * always matches before "claude-opus-4-" (len 14).
+ * Computed once at module load time.
+ */
+const SORTED_MIN_CACHEABLE_ENTRIES = Object.entries(MIN_CACHEABLE_TOKENS).sort((a, b) => b[0].length - a[0].length);
+/**
+ * Resolve minimum cacheable tokens for a model ID.
+ * Matches by prefix: "claude-opus-4-6-20260301" -> "claude-opus-4-6".
+ * Uses pre-sorted entries to guarantee longest prefix wins.
+ * Falls back to DEFAULT_MIN_CACHEABLE_TOKENS (1024).
+ */
+export function getMinCacheableTokens(modelId) {
+    if (!modelId)
+        return DEFAULT_MIN_CACHEABLE_TOKENS;
+    for (const [prefix, threshold] of SORTED_MIN_CACHEABLE_ENTRIES) {
+        if (modelId.startsWith(prefix))
+            return threshold;
+    }
+    return DEFAULT_MIN_CACHEABLE_TOKENS;
+}
+/**
+ * Count existing cache_control breakpoints in an Anthropic API payload.
+ * Counts across tools, system blocks, and message content blocks.
+ * Tools are counted first because their breakpoints consume slots from
+ * the same 4-breakpoint budget.
+ */
+function countCacheBreakpoints(params) {
+    let count = 0;
+    // Count in tools array
+    const tools = params.tools;
+    if (Array.isArray(tools)) {
+        for (const tool of tools) {
+            if (tool.cache_control)
+                count++;
+        }
+    }
+    // Count in system array
+    const system = params.system;
+    if (Array.isArray(system)) {
+        for (const block of system) {
+            if (block.cache_control)
+                count++;
+        }
+    }
+    // Count in messages
+    const messages = params.messages;
+    if (Array.isArray(messages)) {
+        for (const msg of messages) {
+            const content = msg.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.cache_control)
+                        count++;
+                }
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Block types eligible for cache_control markers.
+ * Thinking and redacted_thinking blocks must never receive cache_control
+ * because they waste breakpoint slots.
+ */
+export const CACHEABLE_BLOCK_TYPES = new Set(["text", "tool_use", "tool_result", "image"]);
+/**
+ * Add cache_control marker to the last cacheable content block of a message.
+ *
+ * Walks backwards through the content array to find the last block whose
+ * type is in CACHEABLE_BLOCK_TYPES. Thinking and redacted_thinking blocks
+ * are skipped because they waste breakpoint slots.
+ *
+ * When retention is "long", uses ttl="1h" to match the pi-ai SDK's
+ * Anthropic provider which sets `{ type: "ephemeral", ttl: "1h" }` on
+ * the last user message. The Anthropic API requires TTLs to be
+ * monotonically non-increasing across the request (tools -> system ->
+ * messages). Since Comis places breakpoints earlier in the message array
+ * than the SDK, using the same "1h" TTL ensures ordering compliance.
+ *
+ * When retention is "short" or undefined, uses the 5m default (no
+ * explicit TTL) which is the Anthropic API baseline.
+ */
+export function addCacheControlToLastBlock(message, retention) {
+    const content = message.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return;
+    const cacheControl = retention === "long"
+        ? { type: "ephemeral", ttl: "1h" }
+        : { type: "ephemeral" };
+    // Walk backwards to find the last cacheable block (skip thinking, redacted_thinking, etc.)
+    for (let i = content.length - 1; i >= 0; i--) {
+        const block = content[i];
+        if (CACHEABLE_BLOCK_TYPES.has(block.type)) {
+            block.cache_control = cacheControl;
+            return;
+        }
+    }
+    // Edge case: no cacheable block found -- place on last block as fallback
+    content[content.length - 1].cache_control = cacheControl;
+}
+/** DEFER-TOOL: Check if a model supports Anthropic's tool search (defer_loading).
+ *  Supported: Sonnet 4.x+, Opus 4.x+. NOT supported: Haiku. */
+function supportsToolSearch(modelId) {
+    const lower = modelId.toLowerCase();
+    if (lower.includes("haiku"))
+        return false;
+    // Sonnet 4.x and Opus 4.x support tool search
+    return lower.includes("sonnet") || lower.includes("opus");
+}
+/**
+ * Place exactly 1 cache_control marker on the second-to-last user message.
+ * The SDK already places one on the last user message, so we target second-to-last
+ * to avoid duplication while still getting one Comis-controlled breakpoint.
+ *
+ * When skipCacheWrite is true, target the third-to-last user message instead,
+ * falling back to second-to-last if insufficient user messages exist.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- SDK message types lack public type exports */
+function placeSingleBreakpoint(messages, retention, skipCacheWrite) {
+    if (messages.length < 2)
+        return 0;
+    // When skipCacheWrite, find third-to-last instead of second-to-last
+    const targetOrdinal = skipCacheWrite ? 3 : 2; // 1st=last, 2nd=second-to-last, 3rd=third-to-last
+    let userCount = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            userCount++;
+            if (userCount === targetOrdinal) {
+                addCacheControlToLastBlock(messages[i], retention);
+                return 1;
+            }
+        }
+    }
+    // Fallback: if not enough user messages for the target ordinal,
+    // try second-to-last (skipCacheWrite fallback)
+    if (skipCacheWrite && userCount >= 2) {
+        let fallbackCount = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === "user") {
+                fallbackCount++;
+                if (fallbackCount === 2) {
+                    addCacheControlToLastBlock(messages[i], retention);
+                    return 1;
+                }
+            }
+        }
+    }
+    return 0;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+/**
+ * Place cache breakpoints at strategic positions within the messages array.
+ *
+ * Zone strategy (up to 3 custom breakpoints):
+ * - Breakpoint #2 (semi-stable zone): After the compaction summary or the
+ *   boundary between old and recent messages.
+ * - Breakpoint #3 (recent zone): On the second-to-last user message (the
+ *   SDK places #4 on the last user message).
+ * - Breakpoint #3.5 (mid zone): At the midpoint between semi-stable and
+ *   second-to-last user -- covers the gap in longer conversations.
+ *
+ * @param messages - The messages array from the Anthropic API payload
+ * @param options - Breakpoint placement options
+ * @returns Number of breakpoints actually placed
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- SDK message types lack public type exports */
+function placeCacheBreakpoints(messages, options) {
+    const { minTokens, maxBreakpoints, retention, resolvedRetention, strategy, skipCacheWrite } = options;
+    if (messages.length < 4 || maxBreakpoints <= 0)
+        return 0;
+    // Single-breakpoint strategy dispatch
+    if (strategy === "single") {
+        return placeSingleBreakpoint(messages, retention, skipCacheWrite);
+    }
+    let placed = 0;
+    const remaining = Math.min(maxBreakpoints, 3); // Use full budget (4 total - SDK's 1 = 3 available)
+    // Find the second-to-last user message for breakpoint #3
+    let secondToLastUserIdx = -1;
+    let lastUserIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            if (lastUserIdx === -1) {
+                lastUserIdx = i;
+            }
+            else if (secondToLastUserIdx === -1) {
+                secondToLastUserIdx = i;
+                break;
+            }
+        }
+    }
+    // For sub-agent spawns, shift recent-zone breakpoint back by one
+    // user message to avoid cache_creation on the final message pair.
+    if (skipCacheWrite && secondToLastUserIdx >= 0) {
+        let thirdToLastUserIdx = -1;
+        for (let i = secondToLastUserIdx - 1; i >= 0; i--) {
+            if (messages[i].role === "user") {
+                thirdToLastUserIdx = i;
+                break;
+            }
+        }
+        if (thirdToLastUserIdx >= 0) {
+            secondToLastUserIdx = thirdToLastUserIdx;
+        }
+        // If no third-to-last user found, fall through to original secondToLastUserIdx
+    }
+    // Estimate cumulative tokens for threshold checking.
+    // Uses content-aware char/token ratio: structured content (tool results,
+    // tool use JSON) tokenizes at ~3 chars/token; natural language at ~4.
+    function estimateTokensInRange(start, end) {
+        let tokens = 0;
+        for (let i = start; i <= end && i < messages.length; i++) {
+            const msg = messages[i];
+            const content = msg.content;
+            const isStructured = msg.role === "user"
+                ? Array.isArray(content) && content.some((b) => b.type === "tool_result")
+                : msg.role === "assistant"
+                    ? Array.isArray(content) && content.some((b) => b.type === "tool_use")
+                    : false;
+            const ratio = isStructured ? CHARS_PER_TOKEN_RATIO_STRUCTURED : CHARS_PER_TOKEN_RATIO;
+            if (typeof content === "string") {
+                tokens += Math.ceil(content.length / ratio);
+            }
+            else if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (typeof block.text === "string") {
+                        tokens += Math.ceil(block.text.length / ratio);
+                    }
+                    // tool_result blocks nest text inside block.content[]
+                    if (Array.isArray(block.content)) {
+                        for (const inner of block.content) {
+                            if (typeof inner.text === "string") {
+                                tokens += Math.ceil(inner.text.length / ratio);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return tokens;
+    }
+    // Find compaction summary position (breakpoint #2 candidate)
+    let semiStableIdx = -1;
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role === "user") {
+            const content = msg.content;
+            const text = typeof content === "string" ? content :
+                (Array.isArray(content) ? content.find((b) => b.type === "text")?.text ?? "" : "");
+            if (text.startsWith("<summary>") || text.includes("[Compaction summary]")) {
+                semiStableIdx = i;
+                break;
+            }
+        }
+    }
+    // Place at 50% cumulative token threshold (not 50% message index).
+    // Token-density placement ensures sessions with tool-heavy early messages
+    // place the breakpoint at the actual token midpoint.
+    if (semiStableIdx === -1 && secondToLastUserIdx > 2) {
+        const totalTokens = estimateTokensInRange(0, secondToLastUserIdx);
+        const halfTokens = totalTokens / 2;
+        let cumulative = 0;
+        let crossingIdx = -1;
+        for (let i = 0; i <= secondToLastUserIdx; i++) {
+            cumulative += estimateTokensInRange(i, i);
+            if (cumulative >= halfTokens) {
+                crossingIdx = i;
+                break;
+            }
+        }
+        // Find nearest user message at or before the crossing point
+        if (crossingIdx >= 0) {
+            for (let i = crossingIdx; i >= 0; i--) {
+                if (messages[i].role === "user") {
+                    semiStableIdx = i;
+                    break;
+                }
+            }
+            // Fallback: if no user message at/before crossing, scan forward
+            if (semiStableIdx === -1) {
+                for (let i = crossingIdx + 1; i <= secondToLastUserIdx; i++) {
+                    if (messages[i].role === "user") {
+                        semiStableIdx = i;
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    // Place breakpoint #2 if above threshold
+    if (semiStableIdx >= 0 && placed < remaining) {
+        const tokensToPoint = estimateTokensInRange(0, semiStableIdx);
+        if (tokensToPoint >= minTokens) {
+            addCacheControlToLastBlock(messages[semiStableIdx], resolvedRetention ?? retention);
+            placed++;
+        }
+    }
+    // Place breakpoint #3 on second-to-last user message if above threshold
+    if (secondToLastUserIdx >= 0 && placed < remaining) {
+        const startFrom = semiStableIdx >= 0 ? semiStableIdx + 1 : 0;
+        const tokensInRange = estimateTokensInRange(startFrom, secondToLastUserIdx);
+        if (tokensInRange >= minTokens) {
+            addCacheControlToLastBlock(messages[secondToLastUserIdx], retention);
+            placed++;
+        }
+    }
+    // Place breakpoint at mid-point between semi-stable and second-to-last user.
+    // Covers the gap in longer conversations where the semi-stable zone (compaction summary)
+    // is far from the recent zone (second-to-last user message).
+    if (semiStableIdx >= 0 && secondToLastUserIdx >= 0 && placed < remaining) {
+        const midIdx = Math.floor((semiStableIdx + secondToLastUserIdx) / 2);
+        if (midIdx > semiStableIdx && midIdx < secondToLastUserIdx) {
+            // Find nearest user message at or before the midpoint
+            let midUserIdx = -1;
+            for (let i = midIdx; i > semiStableIdx; i--) {
+                if (messages[i].role === "user") {
+                    midUserIdx = i;
+                    break;
+                }
+            }
+            if (midUserIdx >= 0) {
+                const startFrom = semiStableIdx + 1;
+                const tokensInRange = estimateTokensInRange(startFrom, midUserIdx);
+                if (tokensInRange >= minTokens) {
+                    addCacheControlToLastBlock(messages[midUserIdx], resolvedRetention ?? retention);
+                    placed++;
+                }
+            }
+        }
+    }
+    // Lookback window enforcement: check gaps between consecutive breakpoints.
+    // The Anthropic API uses a 20-block lookback window for cache prefix matching.
+    // If any gap exceeds the window and slots remain, place a bridging breakpoint
+    // at the midpoint of the gap to prevent silent cache misses.
+    if (placed > 0 && placed < Math.min(maxBreakpoints, 3)) {
+        const breakpointPositions = [];
+        for (let i = 0; i < messages.length; i++) {
+            const content = messages[i].content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.cache_control) {
+                        breakpointPositions.push(i);
+                        break;
+                    }
+                }
+            }
+        }
+        // Check gaps between consecutive breakpoints
+        for (let g = 1; g < breakpointPositions.length && placed < Math.min(maxBreakpoints, 3); g++) {
+            const gap = breakpointPositions[g] - breakpointPositions[g - 1];
+            if (gap > CACHE_LOOKBACK_WINDOW) {
+                // Find a user message near the midpoint of the gap
+                const midTarget = Math.floor((breakpointPositions[g - 1] + breakpointPositions[g]) / 2);
+                for (let j = midTarget; j > breakpointPositions[g - 1]; j--) {
+                    if (messages[j].role === "user") {
+                        const startFrom = breakpointPositions[g - 1] + 1;
+                        const tokensInRange = estimateTokensInRange(startFrom, j);
+                        if (tokensInRange >= minTokens) {
+                            addCacheControlToLastBlock(messages[j], resolvedRetention ?? retention);
+                            placed++;
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    return placed;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+// ---------------------------------------------------------------------------
+// Time-based microcompact helper
+// ---------------------------------------------------------------------------
+/** Minimum content length (chars) for a tool result to be considered clearable. */
+const MICROCOMPACT_MIN_CONTENT_LENGTH = 1000;
+/**
+ * Read-only tool names whose results are safely clearable during microcompact.
+ * Edit/write tool results are preserved because they carry the LLM's understanding
+ * of what was changed -- clearing them loses context.
+ */
+const COMPACTABLE_TOOL_NAMES = new Set([
+    "grep", "glob", "file_read", "web_search", "web_fetch",
+    "exec_tool", // Shell equivalent -- output is ephemeral
+    "list_dir", // Directory listing -- ephemeral
+    "search_files", // File search -- ephemeral
+]);
+/**
+ * Edit/write tool names whose tool_use INPUT blocks are clearable during microcompact.
+ * Unlike COMPACTABLE_TOOL_NAMES (which clears tool_result output), this clears the
+ * tool_use input (the request the LLM sent). The tool_result (what the tool returned)
+ * is preserved because edit/write results carry confirmation of what changed.
+ */
+const CLEARABLE_USES_TOOL_NAMES = new Set([
+    "file_edit",
+    "file_write",
+    "notebook_edit",
+]);
+/**
+ * Clear stale tool results from messages, preserving the most recent ones.
+ * Replaces long tool_result content with a placeholder to reduce cache-write
+ * token cost when the cache has expired after an idle gap.
+ *
+ * Only clears read-only (compactable) tool types. Edit/write tool
+ * results and orphaned results (no matching tool_use) are preserved.
+ *
+ * @param messages - The messages array (mutated in place)
+ * @param keepWindow - Number of most recent tool_result messages to preserve
+ * @returns Number of tool results cleared
+ */
+function clearStaleToolResults(messages, keepWindow, fenceIndex = -1) {
+    // Build tool_use_id -> tool_name map for type filtering
+    const toolNameById = new Map();
+    for (const msg of messages) {
+        if (msg.role === "assistant" && Array.isArray(msg.content)) {
+            for (const block of msg.content) {
+                if (block.type === "tool_use" && typeof block.id === "string" && typeof block.name === "string") {
+                    toolNameById.set(block.id, block.name);
+                }
+            }
+        }
+    }
+    // Find all tool_result indices (role === "tool" in Anthropic API format)
+    const toolResultIndices = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].role === "tool") {
+            toolResultIndices.push(i);
+        }
+    }
+    // Protect the last `keepWindow` tool results
+    const clearableIndices = toolResultIndices.slice(0, Math.max(0, toolResultIndices.length - keepWindow));
+    let cleared = 0;
+    for (const idx of clearableIndices) {
+        // Protect messages within the cached prefix (at or below the fence).
+        if (idx <= fenceIndex)
+            continue;
+        const msg = messages[idx];
+        // Only clear compactable (read-only) tool types
+        const toolUseId = msg.tool_use_id;
+        if (toolUseId) {
+            const toolName = toolNameById.get(toolUseId);
+            if (toolName && !COMPACTABLE_TOOL_NAMES.has(toolName)) {
+                continue; // Preserve edit/write tool results
+            }
+            // If tool name not found (orphaned result), skip clearing (conservative)
+            if (!toolName) {
+                continue;
+            }
+        }
+        const content = msg.content;
+        if (Array.isArray(content)) {
+            // Check if any content block exceeds the threshold
+            let totalLen = 0;
+            for (const block of content) {
+                if (typeof block.text === "string") {
+                    totalLen += block.text.length;
+                }
+            }
+            if (totalLen >= MICROCOMPACT_MIN_CONTENT_LENGTH) {
+                // Replace content with lightweight placeholder
+                msg.content = [{ type: "text", text: "[Stale tool result cleared: idle > TTL]" }];
+                cleared++;
+            }
+        }
+        else if (typeof content === "string" && content.length >= MICROCOMPACT_MIN_CONTENT_LENGTH) {
+            msg.content = [{ type: "text", text: "[Stale tool result cleared: idle > TTL]" }];
+            cleared++;
+        }
+    }
+    // Second pass -- clear tool_use input blocks for edit/write tools.
+    // These tool_use blocks contain the full file content the LLM wanted to write/edit.
+    // After the result is confirmed, the input is no longer needed and just wastes cache space.
+    const assistantWithToolUseIndices = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role === "assistant" && Array.isArray(msg.content)) {
+            const content = msg.content;
+            if (content.some(b => b.type === "tool_use")) {
+                assistantWithToolUseIndices.push(i);
+            }
+        }
+    }
+    const clearableAssistantIndices = assistantWithToolUseIndices.slice(0, Math.max(0, assistantWithToolUseIndices.length - keepWindow));
+    for (const idx of clearableAssistantIndices) {
+        // Protect messages within the cached prefix.
+        if (idx <= fenceIndex)
+            continue;
+        const msg = messages[idx];
+        const content = msg.content;
+        for (const block of content) {
+            if (block.type !== "tool_use")
+                continue;
+            const toolName = block.name;
+            if (!CLEARABLE_USES_TOOL_NAMES.has(toolName))
+                continue;
+            const inputStr = JSON.stringify(block.input);
+            if (inputStr.length >= MICROCOMPACT_MIN_CONTENT_LENGTH) {
+                block.input = { _cleared: true, reason: "stale edit/write input" };
+                cleared++;
+            }
+        }
+    }
+    return cleared;
+}
+/**
+ * Clear non-redacted thinking blocks from old assistant messages.
+ * Thinking blocks (5-20K tokens each) waste cache_creation budget when the cache
+ * is cold. This function strips them from assistant messages beyond the keepWindow,
+ * preserving redacted thinking blocks (which carry encrypted signatures for API continuity).
+ *
+ * Mutates messages in place (same pattern as clearStaleToolResults).
+ *
+ * @param messages - The messages array (mutated in place)
+ * @param keepWindow - Number of most recent assistant messages to preserve thinking blocks in
+ * @returns Number of thinking blocks cleared
+ */
+export function clearStaleThinkingBlocks(messages, keepWindow, fenceIndex = -1) {
+    // Collect assistant message indices
+    const assistantIndices = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].role === "assistant") {
+            assistantIndices.push(i);
+        }
+    }
+    // Calculate how many are clearable (beyond keepWindow)
+    const clearableCount = Math.max(0, assistantIndices.length - keepWindow);
+    if (clearableCount === 0)
+        return 0;
+    const clearableIndices = new Set(assistantIndices.slice(0, clearableCount));
+    let cleared = 0;
+    for (const idx of clearableIndices) {
+        // Protect messages within the cached prefix.
+        if (idx <= fenceIndex)
+            continue;
+        const msg = messages[idx];
+        const content = msg.content;
+        if (!Array.isArray(content))
+            continue;
+        // Filter: keep everything EXCEPT non-redacted thinking blocks
+        const filtered = content.filter(block => {
+            if (block.type !== "thinking")
+                return true;
+            // Preserve redacted thinking blocks (encrypted signatures for API continuity)
+            return block.redacted === true;
+        });
+        if (filtered.length < content.length) {
+            cleared += content.length - filtered.length;
+            msg.content = filtered;
+        }
+    }
+    return cleared;
+}
+/**
+ * Reorder content blocks within user messages for deterministic cache prefix.
+ * Moves non-text blocks (images, media) before text blocks within each user message.
+ * This ensures attachments always appear at the start of a message, preventing
+ * cache prefix invalidation when the user sends text+image in varying orders.
+ *
+ * Only reorders within user messages. Assistant and tool messages are unchanged.
+ * Must run AFTER structuredClone and BEFORE any cache_control marker placement.
+ */
+function reorderContentForStablePrefix(messages) {
+    for (const msg of messages) {
+        if (msg.role !== "user" || !Array.isArray(msg.content))
+            continue;
+        const content = msg.content;
+        if (content.length <= 1)
+            continue;
+        // Partition: non-text blocks first, then text blocks (stable sort within groups)
+        const nonText = [];
+        const text = [];
+        for (const block of content) {
+            if (block.type === "text") {
+                text.push(block);
+            }
+            else {
+                nonText.push(block);
+            }
+        }
+        // Only reorder if there are both types (avoid unnecessary mutations)
+        if (nonText.length > 0 && text.length > 0) {
+            msg.content = [...nonText, ...text];
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool suffix ordering for cache-stable Anthropic payloads
+// ---------------------------------------------------------------------------
+/**
+ * Sort tools for Anthropic cache prefix stability: built-in tools first
+ * (preserving original order), then MCP tools sorted alphabetically.
+ *
+ * This ensures dynamic MCP tool late-joins always append AFTER the cached
+ * built-in tool prefix, preventing mid-array insertions from busting
+ * Anthropic's prefix cache matching.
+ *
+ * Server-side tools (type: "tool_search_tool_*") are excluded from sorting
+ * and placed at the end since they are appended by the deferral pipeline.
+ */
+export function sortToolsForCacheStability(tools) {
+    const builtins = [];
+    const mcpTools = [];
+    const serverTools = [];
+    for (const tool of tools) {
+        const name = tool.name ?? "";
+        const type = tool.type ?? "";
+        if (type.startsWith("tool_search_tool_")) {
+            serverTools.push(tool);
+        }
+        else if (name.startsWith("mcp:") || name.startsWith("mcp__")) {
+            mcpTools.push(tool);
+        }
+        else {
+            builtins.push(tool);
+        }
+    }
+    mcpTools.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+    return [...builtins, ...mcpTools, ...serverTools];
+}
+// ---------------------------------------------------------------------------
+// Adaptive TTL promotion helpers
+// ---------------------------------------------------------------------------
+/**
+ * Identify the logical zone for a message breakpoint position.
+ * Three zones based on placeCacheBreakpoints() placement logic:
+ * - "semi-stable": Near compaction summary or first-third boundary (breakpoint #2)
+ * - "mid": Midpoint between semi-stable and recent (breakpoint #3.5)
+ * - "recent": Second-to-last user message (breakpoint #3)
+ *
+ * Uses relative position within the message array since absolute indices drift.
+ * Zone boundaries: first 40% = semi-stable, last 30% = recent, middle = mid.
+ */
+export function identifyBreakpointZone(breakpointIdx, messageCount) {
+    if (messageCount <= 0)
+        return "recent";
+    const ratio = breakpointIdx / messageCount;
+    if (ratio <= 0.4)
+        return "semi-stable";
+    if (ratio >= 0.7)
+        return "recent";
+    return "mid";
+}
+/**
+ * Hash message content at and around a breakpoint position for stability tracking.
+ * Hashes the message at the breakpoint index plus 1 message before it (context window).
+ * Strips cache_control from content blocks to avoid circular dependency where
+ * the hash changes when TTL changes.
+ */
+export function hashBreakpointContent(messages, breakpointIdx) {
+    let combined = "";
+    const start = Math.max(0, breakpointIdx - 1);
+    for (let i = start; i <= breakpointIdx && i < messages.length; i++) {
+        const content = messages[i].content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                // Strip cache_control to avoid circular hash dependency
+                const { cache_control: _cc, ...rest } = block;
+                combined += JSON.stringify(rest);
+            }
+        }
+        else if (typeof content === "string") {
+            combined += content;
+        }
+    }
+    return computeHash(combined);
+}
+/**
+ * Walk placed message breakpoints, record zone hashes, and promote
+ * stable zones from 5m to 1h TTL. Only promotes when resolvedRetention is "long"
+ * (monotonicity constraint: tools >= system >= messages).
+ *
+ * Must be called AFTER placeCacheBreakpoints() and BEFORE onPayloadForCacheDetection().
+ *
+ * @param messages - The messages array with placed breakpoints
+ * @param tracker - BlockStabilityTracker for per-session zone tracking
+ * @param sessionKey - The session key for per-session state
+ * @param threshold - Number of consecutive unchanged calls before promotion
+ * @param resolvedRetention - Current cache retention level (must be "long" for promotion)
+ * @returns Number of breakpoints promoted from 5m to 1h TTL
+ */
+export function maybePromoteBreakpoints(messages, tracker, sessionKey, threshold, resolvedRetention) {
+    // Monotonicity guard: cannot promote to 1h if tools/system use 5m
+    if (resolvedRetention !== "long")
+        return 0;
+    let promoted = 0;
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        const content = msg.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            // Find message-level breakpoints (placed by placeCacheBreakpoints)
+            const cc = block.cache_control;
+            if (!cc || cc.type !== "ephemeral")
+                continue;
+            // Skip breakpoints that already have 1h TTL (tool/system breakpoints)
+            if (cc.ttl === "1h")
+                continue;
+            // This is a message breakpoint with 5m TTL -- check stability
+            const zone = identifyBreakpointZone(i, messages.length);
+            const contentHash = hashBreakpointContent(messages, i);
+            tracker.recordZoneHash(sessionKey, zone, contentHash);
+            if (tracker.isStable(sessionKey, zone, threshold)) {
+                // Promote to 1h TTL
+                block.cache_control = { type: "ephemeral", ttl: "1h" };
+                promoted++;
+            }
+        }
+    }
+    return promoted;
+}
+// ---------------------------------------------------------------------------
+// Main factory
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// 49-01: Per-block token estimator for TTL split estimation
+// ---------------------------------------------------------------------------
+/**
+ * Estimate the token count for a single content block.
+ *
+ * Extracts the `text` field when present (text blocks) and divides by
+ * CHARS_PER_TOKEN_RATIO. For non-text blocks (images, tool_use JSON) falls
+ * back to JSON.stringify length / CHARS_PER_TOKEN_RATIO. The 3.5 ratio
+ * better matches Anthropic's tokenizer than the previously used 4.0 ratio.
+ *
+ * @param block - A content block from the API payload
+ * @returns Estimated token count (always >= 1)
+ */
+export function estimateBlockTokens(block) {
+    const text = typeof block.text === "string" ? block.text : JSON.stringify(block);
+    return Math.ceil(text.length / CHARS_PER_TOKEN_RATIO);
+}
+/**
+ * Create a stream wrapper that mutates the outgoing request body via the
+ * onPayload hook. Consolidates four concerns:
+ *
+ * 1. **Cache breakpoints** (Anthropic-family): injects cache_control markers
+ *    at strategic positions in the message array.
+ * 2. **1M beta header** (direct Anthropic only): appends the context-1m beta
+ *    header for 1M context window models.
+ * 3. **service_tier** (Responses API + fastMode): injects service_tier: "auto".
+ * 4. **store** (Responses API + storeCompletions): injects store: true.
+ *
+ * The wrapper only activates when the model matches at least one concern;
+ * for non-Anthropic non-Responses providers, it passes through unchanged.
+ *
+ * @param config - Request body injector configuration
+ * @param logger - Logger for debug output
+ * @returns A named StreamFnWrapper ("requestBodyInjector")
+ */
+export function createRequestBodyInjector(config, logger) {
+    return function requestBodyInjector(next) {
+        return (model, context, options) => {
+            const needsCacheBreakpoints = ANTHROPIC_FAMILY.has(model.provider);
+            const needsResponsesApiInjection = isResponsesApiProvider(model);
+            if (!needsCacheBreakpoints && !needsResponsesApiInjection) {
+                return next(model, context, options);
+            }
+            const minTokens = config.getMinTokensOverride?.() ?? getMinCacheableTokens(model.id);
+            // Concern 2: 1M beta header (direct Anthropic only -- NOT Bedrock/Vertex)
+            // Must be injected as HTTP headers via options.headers, NOT in the request body.
+            // The pi-ai SDK passes options.headers to createClient() for HTTP transport,
+            // while onPayload mutates the JSON body -- putting headers there causes
+            // Anthropic API to reject with "headers: Extra inputs are not permitted".
+            let mergedHeaders;
+            if (model.provider === "anthropic") {
+                const existingHeaders = options?.headers;
+                const headers = { ...(existingHeaders ?? {}) };
+                const existingBetas = parseHeaderList(headers["anthropic-beta"]);
+                if (!existingBetas.includes(CONTEXT_1M_BETA)) {
+                    existingBetas.push(CONTEXT_1M_BETA);
+                    headers["anthropic-beta"] = existingBetas.join(", ");
+                    mergedHeaders = headers;
+                }
+                // SESS-LATCH: Latch beta header on first use
+                const betaLatch = config.getBetaHeaderLatch?.();
+                if (betaLatch) {
+                    if (mergedHeaders) {
+                        const betaValue = mergedHeaders["anthropic-beta"];
+                        if (betaValue) {
+                            mergedHeaders["anthropic-beta"] = betaLatch.setOnce(betaValue);
+                        }
+                    }
+                    else {
+                        // No new headers to merge but latch has a value -- use latched value
+                        const latched = betaLatch.get();
+                        if (latched) {
+                            mergedHeaders = { ...(existingHeaders ?? {}), "anthropic-beta": latched };
+                        }
+                    }
+                }
+                // Sticky-on beta header latches -- accumulate individual beta
+                // values across calls. Unlike SESS-LATCH (set-once for entire string), this
+                // tracks individual values and ensures once-seen-always-included semantics.
+                if (config.sessionKey) {
+                    // Ensure mergedHeaders exists (even if CONTEXT_1M_BETA was already present)
+                    if (!mergedHeaders) {
+                        mergedHeaders = { ...(existingHeaders ?? {}) };
+                    }
+                    const currentBetas = parseHeaderList(mergedHeaders["anthropic-beta"]);
+                    let latched = sessionBetaHeaderLatches.get(config.sessionKey);
+                    if (!latched) {
+                        latched = createAccumulativeLatch();
+                        sessionBetaHeaderLatches.set(config.sessionKey, latched);
+                    }
+                    // Latch all current beta values (sticky-on: once seen, always included)
+                    for (const beta of currentBetas) {
+                        latched.add(beta);
+                    }
+                    // Merge any previously-latched values not in current set
+                    let changed = false;
+                    for (const beta of latched.getAll()) {
+                        if (!currentBetas.includes(beta)) {
+                            currentBetas.push(beta);
+                            changed = true;
+                        }
+                    }
+                    if (changed) {
+                        mergedHeaders["anthropic-beta"] = currentBetas.join(", ");
+                    }
+                }
+            }
+            // Chain onPayload: preserve any existing onPayload callback
+            const existingOnPayload = options?.onPayload;
+            const enhancedOptions = {
+                ...options,
+                ...(mergedHeaders ? { headers: mergedHeaders } : {}),
+                onPayload: async (payload, payloadModel) => {
+                    // Let existing onPayload run first
+                    const transformed = existingOnPayload
+                        ? await existingOnPayload(payload, payloadModel)
+                        : undefined;
+                    const params = (transformed ?? payload);
+                    // Clone mutable sub-structures before any mutation.
+                    // Prevents contaminating reused content in secondary queries (title generation, compaction)
+                    // that may share the original params reference. The SDK builds params fresh each call
+                    // via buildParams(), but we must not mutate SDK-owned objects to prevent stale marker
+                    // accumulation if the SDK ever caches or reuses params across calls.
+                    const result = { ...params };
+                    if (needsCacheBreakpoints) {
+                        if (Array.isArray(params.system)) {
+                            result.system = structuredClone(params.system);
+                        }
+                        if (Array.isArray(params.tools)) {
+                            result.tools = structuredClone(params.tools);
+                        }
+                        if (Array.isArray(params.messages)) {
+                            result.messages = structuredClone(params.messages);
+                        }
+                    }
+                    // Reorder content blocks for stable prefix (before any cache marker placement)
+                    if (needsCacheBreakpoints && Array.isArray(result.messages)) {
+                        reorderContentForStablePrefix(result.messages);
+                    }
+                    // 2.1: TTL expiry guard for skipCacheWrite -- when the parent's cache write
+                    // timestamp indicates the shared prefix cache has likely expired (>80% of TTL
+                    // elapsed), disable skipCacheWrite so the sub-agent creates its own cache entry
+                    // instead of referencing a stale one. Prevents 100% cache misses on round-2
+                    // sub-agents where the 5-minute TTL expired between rounds.
+                    // Computed early so the W2 guard below can defer to the sub-agent bypass
+                    // path (line ~1854) for SDK-placed tool markers.
+                    let effectiveSkipCacheWrite = config.skipCacheWrite ?? false;
+                    if (effectiveSkipCacheWrite && config.cacheWriteTimestamp != null) {
+                        const TTL_MAP = { short: 300_000, long: 3_600_000 };
+                        const ttlMs = TTL_MAP[config.parentCacheRetention ?? "short"] ?? 300_000;
+                        const SAFETY_MARGIN = 0.8;
+                        const elapsed = Date.now() - config.cacheWriteTimestamp;
+                        if (elapsed > ttlMs * SAFETY_MARGIN) {
+                            effectiveSkipCacheWrite = false;
+                            logger.debug({ elapsed, ttlMs, safetyMargin: SAFETY_MARGIN, sessionKey: config.sessionKey }, "TTL likely expired, disabling skipCacheWrite");
+                        }
+                    }
+                    // pi-ai 0.67.4+ auto-places cache_control on the last tool in
+                    // convertTools(). W2 keeps tools at zero breakpoints (cached
+                    // implicitly via the cumulative hash at the system breakpoint), so
+                    // strip the auto-placed marker before our budget + zone strategy runs.
+                    //
+                    // Skipped for effectiveSkipCacheWrite=true (sub-agent path): single-turn
+                    // sub-agents need SDK-placed markers intact to match the parent's cached
+                    // prefix; multi-turn sub-agents strip+re-place at line ~1874 anyway.
+                    if (needsCacheBreakpoints && !effectiveSkipCacheWrite && Array.isArray(result.tools)) {
+                        for (const tool of result.tools) {
+                            if (tool.cache_control)
+                                delete tool.cache_control;
+                        }
+                    }
+                    // Sort tools for cache-stable prefix: builtins first, MCP alphabetically
+                    if (needsCacheBreakpoints && Array.isArray(result.tools) && result.tools.length > 0) {
+                        result.tools = sortToolsForCacheStability(result.tools);
+                    }
+                    // Rendered tool cache -- ensures byte-identical
+                    // tool JSON across turns when composition is unchanged. On aggregate cache miss,
+                    // per-tool content-addressed memoization preserves unchanged individual tools.
+                    if (config.sessionKey && needsCacheBreakpoints && Array.isArray(result.tools)) {
+                        // When ALL MCP tools use defer_loading, tool composition is guaranteed stable.
+                        // Skip per-tool hash recomputation since no MCP tool connect/disconnect can change schemas.
+                        // Only activate after defer_loading latch is set AND tool cache exists (not first turn).
+                        const allDeferredToolHashSkip = (() => {
+                            if (!config.getDeferredToolNames || !config.getTotalMcpToolCount)
+                                return false;
+                            const deferredNames = config.getDeferredToolNames();
+                            const totalMcpTools = config.getTotalMcpToolCount();
+                            if (totalMcpTools === 0 || deferredNames.size === 0)
+                                return false;
+                            // All MCP tools deferred AND we have a cached entry from a prior turn
+                            return deferredNames.size >= totalMcpTools && sessionRenderedToolCache.has(config.sessionKey);
+                        })();
+                        if (allDeferredToolHashSkip) {
+                            logger.debug({ sessionKey: config.sessionKey }, "All tools deferred, skipping per-tool hash recomputation");
+                            // Use cached tools from prior turn (already in sessionRenderedToolCache)
+                            const cached = sessionRenderedToolCache.get(config.sessionKey);
+                            if (cached) {
+                                result.tools = structuredClone(cached.tools);
+                            }
+                        }
+                        else {
+                            const tools = result.tools;
+                            const renderedHash = computeRenderedToolsHash(tools);
+                            // Include feature flag hash so config changes that affect tool rendering
+                            // invalidate the cached tool array.
+                            const featureFlagHash = config.featureFlagHash ?? "default";
+                            const cached = sessionRenderedToolCache.get(config.sessionKey);
+                            if (cached && cached.hash === renderedHash && cached.featureFlagHash === featureFlagHash) {
+                                // Aggregate cache hit -- replace with cached copy for byte-identical output
+                                result.tools = structuredClone(cached.tools);
+                            }
+                            else {
+                                // Aggregate hash changed -- iterate per-tool cache.
+                                // Unchanged individual tools keep byte-identical references while
+                                // changed ones get new snapshots via getOrCacheRenderedTool().
+                                const perToolCached = tools.map(t => getOrCacheRenderedTool(config.sessionKey, t));
+                                // Store rebuilt array as new aggregate snapshot
+                                result.tools = perToolCached;
+                                sessionRenderedToolCache.set(config.sessionKey, {
+                                    hash: renderedHash,
+                                    featureFlagHash,
+                                    tools: structuredClone(perToolCached), // Snapshot before cache_control
+                                });
+                            }
+                        }
+                    }
+                    // Time-based microcompact -- clear stale tool results when cache is cold.
+                    // Runs BEFORE breakpoint placement because clearing results changes message sizes.
+                    // Fence-aware — skip clearing messages at/below the previous turn's
+                    // cache fence to preserve prefix stability after cache breaks.
+                    if (needsCacheBreakpoints && config.getElapsedSinceLastResponse && config.sessionKey) {
+                        const elapsed = config.getElapsedSinceLastResponse();
+                        if (elapsed !== undefined) {
+                            // Determine TTL from current retention (pre-latch, since we're checking if cache is cold)
+                            const baseRetentionForTtl = config.getCacheRetention() ?? "long";
+                            const ttlMs = baseRetentionForTtl === "long" ? 3_600_000 : 300_000;
+                            if (elapsed > ttlMs && Array.isArray(result.messages)) {
+                                const keepWindow = config.observationKeepWindow ?? 25;
+                                const microcompactFence = config.getCacheFenceIndex?.() ?? -1;
+                                const cleared = clearStaleToolResults(result.messages, keepWindow, microcompactFence);
+                                // Also clear thinking blocks from old assistant messages
+                                const thinkingCleared = clearStaleThinkingBlocks(result.messages, keepWindow, microcompactFence);
+                                if (cleared > 0 || thinkingCleared > 0) {
+                                    config.onContentModification?.();
+                                    if (cleared > 0)
+                                        config.onAdaptiveRetentionReset?.();
+                                    logger.debug({ cleared, thinkingCleared, elapsedMs: elapsed, ttlMs, keepWindow, sessionKey: config.sessionKey }, "Time-based microcompact cleared stale content");
+                                }
+                            }
+                        }
+                    }
+                    // Token-ceiling microcompact -- clear stale content when context grows too large.
+                    // Runs independently of TTL: a session with rapid back-and-forth can accumulate massive
+                    // context within a single TTL window. Unlike TTL trigger, does NOT reset adaptive retention
+                    // because the cache may still be warm.
+                    // Fence-aware — respects cache fence.
+                    if (needsCacheBreakpoints && config.microcompactTokenCeiling && config.sessionKey) {
+                        const msgs = result.messages;
+                        if (Array.isArray(msgs)) {
+                            const estimatedTokens = estimateContextChars(msgs) / CHARS_PER_TOKEN_RATIO;
+                            if (estimatedTokens > config.microcompactTokenCeiling) {
+                                const keepWindow = config.observationKeepWindow ?? 25;
+                                const ceilingFence = config.getCacheFenceIndex?.() ?? -1;
+                                const cleared = clearStaleToolResults(msgs, keepWindow, ceilingFence);
+                                const thinkingCleared = clearStaleThinkingBlocks(msgs, keepWindow, ceilingFence);
+                                if (cleared > 0 || thinkingCleared > 0) {
+                                    config.onContentModification?.();
+                                    // NOTE: Do NOT call onAdaptiveRetentionReset -- cache may still be warm
+                                    logger.debug({ cleared, thinkingCleared, estimatedTokens: Math.round(estimatedTokens), ceiling: config.microcompactTokenCeiling, sessionKey: config.sessionKey }, "Token-ceiling microcompact cleared stale content");
+                                }
+                            }
+                        }
+                    }
+                    // Prefix stability diagnostic — detect when microcompaction
+                    // changes the cache-fenced prefix between turns (indicating permanent cache collapse).
+                    // Fence-index-aware: growing fence (normal conversation growth) is benign unless
+                    // the old prefix content was mutated. Fence shrink (compaction) resets the counter.
+                    // Uses getCacheFenceIndex() to hash only the cached region; skips detection
+                    // when no fence is set yet (early bootstrap / non-Anthropic provider).
+                    if (needsCacheBreakpoints && config.sessionKey && Array.isArray(result.messages)) {
+                        const diagFenceIdx = config.getCacheFenceIndex?.() ?? -1;
+                        if (diagFenceIdx >= 0) {
+                            const msgs = result.messages;
+                            /** Hash role + first 200 chars of content for messages up to endIdx (inclusive). */
+                            const hashMessageSlice = (messages, endIdx) => {
+                                const slice = messages.slice(0, endIdx + 1);
+                                return computeHash(slice.map(m => {
+                                    const c = m.content;
+                                    const text = typeof c === "string" ? c.slice(0, 200) :
+                                        Array.isArray(c) ? c.map(b => String(b.text ?? b.type ?? "")).join("").slice(0, 200) : "";
+                                    return `${m.role}:${text}`;
+                                }));
+                            };
+                            const prefixHash = hashMessageSlice(msgs, diagFenceIdx);
+                            const prev = sessionPrefixStability.get(config.sessionKey);
+                            if (!prev) {
+                                // First observation — store baseline, no comparison needed
+                                sessionPrefixStability.set(config.sessionKey, { hash: prefixHash, fenceIdx: diagFenceIdx, consecutiveChanges: 0 });
+                            }
+                            else if (diagFenceIdx < prev.fenceIdx) {
+                                // Case C: Fence shrank (compaction reset) — reset counter entirely
+                                sessionPrefixStability.set(config.sessionKey, { hash: prefixHash, fenceIdx: diagFenceIdx, consecutiveChanges: 0 });
+                            }
+                            else if (diagFenceIdx > prev.fenceIdx) {
+                                // Case A: Fence grew (normal conversation growth).
+                                // Re-hash using the old fence boundary to check if old prefix content is intact.
+                                const oldRangeHash = hashMessageSlice(msgs, prev.fenceIdx);
+                                if (oldRangeHash === prev.hash) {
+                                    // Old prefix content unchanged — benign growth, reset counter
+                                    sessionPrefixStability.set(config.sessionKey, { hash: prefixHash, fenceIdx: diagFenceIdx, consecutiveChanges: 0 });
+                                }
+                                else {
+                                    // Old prefix content was mutated — genuine instability
+                                    const changes = prev.consecutiveChanges + 1;
+                                    sessionPrefixStability.set(config.sessionKey, { hash: prefixHash, fenceIdx: diagFenceIdx, consecutiveChanges: changes });
+                                    if (changes >= 3) {
+                                        logger.warn({
+                                            sessionKey: config.sessionKey,
+                                            consecutiveChanges: changes,
+                                            hint: "Cache prefix changing every turn — microcompaction or content modification destabilizing the prefix. Cache writes are wasted.",
+                                            errorKind: "performance",
+                                        }, "Unstable prefix detected");
+                                    }
+                                }
+                            }
+                            else {
+                                // Case B: Same fence position — direct hash comparison
+                                if (prev.hash !== prefixHash) {
+                                    const changes = prev.consecutiveChanges + 1;
+                                    sessionPrefixStability.set(config.sessionKey, { hash: prefixHash, fenceIdx: diagFenceIdx, consecutiveChanges: changes });
+                                    if (changes >= 3) {
+                                        logger.warn({
+                                            sessionKey: config.sessionKey,
+                                            consecutiveChanges: changes,
+                                            hint: "Cache prefix changing every turn — microcompaction or content modification destabilizing the prefix. Cache writes are wasted.",
+                                            errorKind: "performance",
+                                        }, "Unstable prefix detected");
+                                    }
+                                }
+                                else {
+                                    // Prefix stable — reset counter
+                                    sessionPrefixStability.set(config.sessionKey, { hash: prefixHash, fenceIdx: diagFenceIdx, consecutiveChanges: 0 });
+                                }
+                            }
+                        }
+                    }
+                    // Hoist resolvedRetention for kill switch access after needsCacheBreakpoints block
+                    let resolvedRetention;
+                    // Concern 1: Cache breakpoints (Anthropic-family)
+                    if (needsCacheBreakpoints) {
+                        // Resolve per-model cache retention override before latching
+                        const baseRetention = config.getCacheRetention() ?? "long";
+                        const modelId = config.getModelId?.() ?? model.id;
+                        const effectiveRetention = resolveCacheRetention(modelId, baseRetention, config.getCacheRetentionOverrides?.());
+                        // Latch retention on first resolution
+                        const rawRetention = effectiveRetention;
+                        const retentionLatch = config.getRetentionLatch?.();
+                        resolvedRetention = retentionLatch
+                            ? retentionLatch.setOnce(rawRetention)
+                            : rawRetention;
+                        // Replace single system block with multi-block for independent caching.
+                        // Must run AFTER structuredClone (operates on cloned system) and BEFORE the
+                        // TTL upgrade (so all new blocks get upgraded). The SDK-placed single-block
+                        // cache_control is discarded -- we inject cache_control on all blocks explicitly.
+                        const promptBlocks = config.getSystemPromptBlocks?.();
+                        if (promptBlocks && Array.isArray(result.system)) {
+                            const blocks = [
+                                { type: "text", text: promptBlocks.staticPrefix + SYSTEM_PROMPT_DYNAMIC_BOUNDARY },
+                            ];
+                            // Attribution block only when non-empty (empty in "none" mode)
+                            if (promptBlocks.attribution) {
+                                blocks.push({ type: "text", text: promptBlocks.attribution });
+                            }
+                            blocks.push({ type: "text", text: promptBlocks.semiStableBody });
+                            result.system = blocks;
+                            // Only last system block gets cache_control -- cumulative hash covers
+                            // all prior blocks. Frees 2 breakpoint slots for message breakpoints.
+                            const sysBlocks = result.system;
+                            for (const block of sysBlocks) {
+                                delete block.cache_control;
+                            }
+                            sysBlocks[sysBlocks.length - 1].cache_control = resolvedRetention === "long"
+                                ? { type: "ephemeral", ttl: "1h" }
+                                : { type: "ephemeral" };
+                            logger.debug({ blockCount: blocks.length, retention: resolvedRetention, modelId: model.id }, "Multi-block system prompt injected");
+                        }
+                        // Log first system prompt block hash for prefix-matching debug.
+                        // Runs after multi-block injection so the hash reflects the final static prefix.
+                        if (Array.isArray(result.system)) {
+                            const sysBlocks = result.system;
+                            if (sysBlocks.length > 0 && typeof sysBlocks[0]?.text === "string") {
+                                const text = sysBlocks[0].text;
+                                logger.debug({
+                                    firstBlockHash: djb2(text),
+                                    firstBlockSnippet: text.slice(0, 80).replace(/\n/g, "\\n"),
+                                    blockCount: sysBlocks.length,
+                                    modelId: model.id,
+                                }, "System prompt first-block hash");
+                            }
+                        }
+                        // Upgrade system prompt TTL to satisfy monotonicity constraint.
+                        // The SDK always sets system blocks to { type: "ephemeral" } (5m) because
+                        // configResolver passes getMessageRetention() = "short" for the SDK's
+                        // cacheRetention option (we can't give the SDK different values for system
+                        // vs last-user-message). But after adaptive escalation, the tool breakpoint
+                        // uses ttl: "1h". Without this upgrade, system(5m) -> tools(1h) violates
+                        // Anthropic's non-increasing TTL requirement, causing the API to silently
+                        // downgrade tools to 5m.
+                        if (resolvedRetention === "long" && Array.isArray(result.system)) {
+                            for (const block of result.system) {
+                                if (block.cache_control) {
+                                    block.cache_control = { type: "ephemeral", ttl: "1h" };
+                                }
+                            }
+                        }
+                        // Count breakpoints on `result` (post-clone, post-multi-block-injection)
+                        // not `params` (pre-clone). Multi-block injection may have added cache_control to
+                        // 2 system blocks that didn't exist in the original params.
+                        const existingCount = countCacheBreakpoints(result);
+                        let slotsAvailable = 4 - existingCount;
+                        // Breakpoint budget audit -- 1 per API call.
+                        {
+                            let systemBpCount = 0;
+                            let toolBpCount = 0;
+                            if (Array.isArray(result.system)) {
+                                for (const block of result.system) {
+                                    if (block.cache_control)
+                                        systemBpCount++;
+                                }
+                            }
+                            if (Array.isArray(result.tools)) {
+                                for (const tool of result.tools) {
+                                    if (tool.cache_control)
+                                        toolBpCount++;
+                                }
+                            }
+                            logger.info({
+                                existingCount,
+                                slotsAvailable,
+                                systemBreakpoints: systemBpCount,
+                                toolBreakpoints: toolBpCount,
+                                modelId: model.id,
+                            }, "Breakpoint budget audit (pre-message-placement)");
+                        }
+                        // W2: Tool breakpoint removed -- tools cached implicitly via cumulative hash
+                        // at system breakpoint position (zero tool breakpoints).
+                        // DEFER-TOOL: Inject defer_loading on deferred tools for Anthropic non-Haiku models.
+                        // Runs after tool cache breakpoints so deferred marking doesn't pollute breakpoint logic.
+                        if (config.getDeferredToolNames && supportsToolSearch(model.id)) {
+                            const deferredNames = config.getDeferredToolNames();
+                            // SESS-LATCH: Latch defer_loading activation
+                            const deferLatch = config.getDeferLoadingLatch?.();
+                            const shouldDeferLoad = deferLatch
+                                ? deferLatch.setOnce(deferredNames.size > 0)
+                                : deferredNames.size > 0;
+                            if (shouldDeferLoad && Array.isArray(result.tools)) {
+                                const tools = result.tools;
+                                let deferCount = 0;
+                                for (const tool of tools) {
+                                    if (deferredNames.has(tool.name)) {
+                                        tool.defer_loading = true;
+                                        deferCount++;
+                                    }
+                                }
+                                // Only switch to server-side tool_search when tools were actually
+                                // marked defer_loading in the payload. When deferred tools are
+                                // excluded upstream (tool-deferral.ts client-side exclusion),
+                                // deferCount is 0 and the payload lacks deferred definitions —
+                                // injecting tool_search_tool without any deferred tools crashes
+                                // the Anthropic API/SDK.
+                                if (deferCount > 0) {
+                                    // Remove client-side discover_tools (replaced by server-side tool_search)
+                                    const discoverIdx = tools.findIndex(t => t.name === "discover_tools");
+                                    if (discoverIdx !== -1) {
+                                        tools.splice(discoverIdx, 1);
+                                    }
+                                    // Append server-side search tool (only if not already present)
+                                    const hasSearchTool = tools.some(t => typeof t.type === "string" && t.type.startsWith("tool_search_tool_"));
+                                    if (!hasSearchTool) {
+                                        tools.push({
+                                            type: "tool_search_tool_regex_20251119",
+                                            name: "tool_search_tool_regex",
+                                        });
+                                    }
+                                }
+                                logger.debug({ deferCount, modelId: model.id, searchToolAppended: deferCount > 0 }, "DEFER-TOOL: Injected defer_loading on deferred tools");
+                            }
+                        }
+                        // GRAPH-BREAKPOINT: Place a cache breakpoint on graph context envelope.
+                        // Wave 2+ subagents and graph-enabled sessions receive injected research
+                        // results as the first user message. This dynamic content (~100K+ tokens)
+                        // falls between the standard cache breakpoints, paying full uncached input
+                        // rate. Placing a breakpoint captures it under the cache prefix.
+                        // Must run INSIDE the budget-aware block to consume a slot from slotsAvailable.
+                        if (slotsAvailable > 0 && !effectiveSkipCacheWrite && Array.isArray(result.messages)) {
+                            const msgs = result.messages;
+                            for (let i = 0; i < Math.min(msgs.length, 3); i++) {
+                                const msg = msgs[i];
+                                if (msg.role !== "user")
+                                    continue;
+                                const content = Array.isArray(msg.content) ? msg.content : [];
+                                const hasGraphContext = content.some((block) => typeof block.text === "string" && block.text.includes("## Graph Context"));
+                                if (hasGraphContext) {
+                                    addCacheControlToLastBlock(msg, resolvedRetention ?? "long");
+                                    slotsAvailable--;
+                                    logger.debug({ modelId: model.id, messageIndex: i, sessionKey: config.sessionKey }, "GRAPH-BREAKPOINT: Placed cache breakpoint on graph context envelope message");
+                                    break;
+                                }
+                            }
+                        }
+                        // During eviction cooldown, limit to 1 breakpoint (recent zone) at "short" retention.
+                        const evictionCooldown = config.getEvictionCooldown?.();
+                        const inCooldown = evictionCooldown != null && evictionCooldown.turnsRemaining > 0;
+                        if (slotsAvailable > 0 && Array.isArray(result.messages)) {
+                            // Conversation breakpoints use zone-aware retention.
+                            // Recent zone always uses "short" (5m); semi-stable/mid zones get escalated retention.
+                            const messageRetention = config.getMessageRetention?.() ?? resolvedRetention;
+                            const placed = placeCacheBreakpoints(result.messages, {
+                                minTokens,
+                                maxBreakpoints: inCooldown ? 1 : slotsAvailable,
+                                retention: "short", // Recent zone always "short" (5m)
+                                resolvedRetention: inCooldown ? "short" : messageRetention, // Force "short" during cooldown
+                                strategy: resolveBreakpointStrategy(config.cacheBreakpointStrategy, model.provider),
+                                skipCacheWrite: effectiveSkipCacheWrite,
+                            });
+                            if (placed > 0) {
+                                logger.debug({
+                                    placed,
+                                    existingCount,
+                                    totalBreakpoints: existingCount + placed,
+                                    minTokens,
+                                    modelId: model.id,
+                                    strategy: resolveBreakpointStrategy(config.cacheBreakpointStrategy, model.provider),
+                                }, "Message breakpoints placed");
+                            }
+                            else if (Array.isArray(result.messages) && result.messages.length >= 4) {
+                                logger.debug({ messageCount: result.messages.length, minTokens, modelId: model.id, existingCount }, "Cache breakpoints skipped: token gaps below minTokens threshold");
+                            }
+                            // W12: Unconditional scan for ANY message breakpoint (including SDK auto-marker).
+                            // Ensures cacheFenceIndex is set for all sessions, not just those with explicit placements.
+                            if (config.onBreakpointsPlaced && Array.isArray(result.messages)) {
+                                let highestBreakpointIdx = -1;
+                                const scanMsgs = result.messages;
+                                for (let i = scanMsgs.length - 1; i >= 0; i--) {
+                                    const content = scanMsgs[i].content;
+                                    if (Array.isArray(content)) {
+                                        for (const block of content) {
+                                            if (block.cache_control) {
+                                                highestBreakpointIdx = i;
+                                                break;
+                                            }
+                                        }
+                                    }
+                                    if (highestBreakpointIdx >= 0)
+                                        break;
+                                }
+                                if (highestBreakpointIdx >= 0) {
+                                    config.onBreakpointsPlaced(highestBreakpointIdx);
+                                    logger.debug({ highestBreakpointIdx, modelId: model.id }, "Cache fence callback fired");
+                                }
+                            }
+                        }
+                        // W12-FALLBACK: When all breakpoint slots are consumed, still scan for SDK auto-marker
+                        // to set cache fence. The SDK always places a marker on the last user message.
+                        if (slotsAvailable <= 0 && config.onBreakpointsPlaced && Array.isArray(result.messages)) {
+                            let highestBreakpointIdx = -1;
+                            const fallbackMsgs = result.messages;
+                            for (let i = fallbackMsgs.length - 1; i >= 0; i--) {
+                                const content = fallbackMsgs[i].content;
+                                if (Array.isArray(content)) {
+                                    for (const block of content) {
+                                        if (block.cache_control) {
+                                            highestBreakpointIdx = i;
+                                            break;
+                                        }
+                                    }
+                                }
+                                if (highestBreakpointIdx >= 0)
+                                    break;
+                            }
+                            if (highestBreakpointIdx >= 0) {
+                                config.onBreakpointsPlaced(highestBreakpointIdx);
+                                logger.debug({ highestBreakpointIdx, modelId: model.id, source: "sdk-auto-marker" }, "W12-FALLBACK: Cache fence set from SDK auto-marker (no explicit slots available)");
+                            }
+                        }
+                        // Warn when cache fence remains unset in mature conversation.
+                        // This indicates no cache_control markers exist on any message -- neither explicit nor SDK auto.
+                        if (config.onBreakpointsPlaced && Array.isArray(result.messages) && result.messages.length >= 10) {
+                            const scanForFence = result.messages;
+                            let fenceFound = false;
+                            for (let i = scanForFence.length - 1; i >= 0; i--) {
+                                const content = scanForFence[i].content;
+                                if (Array.isArray(content)) {
+                                    for (const block of content) {
+                                        if (block.cache_control) {
+                                            fenceFound = true;
+                                            break;
+                                        }
+                                    }
+                                }
+                                if (fenceFound)
+                                    break;
+                            }
+                            if (!fenceFound) {
+                                logger.warn({
+                                    messageCount: result.messages.length,
+                                    modelId: model.id,
+                                    hint: "No cache breakpoint found on any message in mature conversation. Cache fence is unset -- thinking block cleaner has no protection boundary.",
+                                    errorKind: "performance",
+                                }, "Cache fence unset in mature session");
+                            }
+                        }
+                        // W7: Diagnostic WARN when breakpoint budget exhausted on mature conversation.
+                        if (slotsAvailable <= 0 && Array.isArray(result.messages) && result.messages.length >= 20) {
+                            logger.warn({
+                                existingCount,
+                                messageCount: result.messages.length,
+                                modelId: model.id,
+                                hint: "Breakpoint budget exhausted before message breakpoints. System prompt may need consolidation or tool breakpoint reduction.",
+                                errorKind: "performance",
+                            }, "W7: Cache breakpoint budget exhausted -- no message breakpoints placed on mature conversation");
+                        }
+                    }
+                    // Promote stable message breakpoints from 5m to 1h TTL
+                    // Skip breakpoint TTL promotion during eviction cooldown (conservative caching).
+                    {
+                        const cooldownForPromotion = config.getEvictionCooldown?.();
+                        const promotionBlocked = cooldownForPromotion != null && cooldownForPromotion.turnsRemaining > 0;
+                        if (config.blockStabilityTracker && config.sessionKey && !effectiveSkipCacheWrite && !promotionBlocked) {
+                            const promotionThreshold = config.stabilityThreshold ?? 3;
+                            const promotedCount = maybePromoteBreakpoints(result.messages, config.blockStabilityTracker, config.sessionKey, promotionThreshold, resolvedRetention);
+                            if (promotedCount > 0) {
+                                logger.debug({ promoted: promotedCount, threshold: promotionThreshold, modelId: model.id }, "Message breakpoints promoted to 1h TTL");
+                            }
+                        }
+                    } // end eviction cooldown promotion scope
+                    // Sticky-on sweep -- capture any beta headers modified inside onPayload
+                    // and merge previously-latched values. Ensures consistency regardless of where
+                    // beta headers are added (outer scope or inside onPayload callbacks).
+                    if (config.sessionKey && mergedHeaders) {
+                        const allBetas = parseHeaderList(mergedHeaders["anthropic-beta"]);
+                        let latched = sessionBetaHeaderLatches.get(config.sessionKey);
+                        if (!latched) {
+                            latched = createAccumulativeLatch();
+                            sessionBetaHeaderLatches.set(config.sessionKey, latched);
+                        }
+                        for (const beta of allBetas)
+                            latched.add(beta);
+                        // Inject any previously latched values not yet in current headers
+                        let changed = false;
+                        for (const beta of latched.getAll()) {
+                            if (!allBetas.includes(beta)) {
+                                allBetas.push(beta);
+                                changed = true;
+                            }
+                        }
+                        if (changed) {
+                            mergedHeaders["anthropic-beta"] = allBetas.join(", ");
+                        }
+                    }
+                    // Feed payload to cache break detector Phase 1 (after breakpoint placement)
+                    if (config.onPayloadForCacheDetection) {
+                        config.onPayloadForCacheDetection(result, model, mergedHeaders);
+                    }
+                    // SDK-UPGRADE: Upgrade SDK auto-placed 5m markers to 1h when retention is long.
+                    // The pi-ai SDK places cache_control: { type: "ephemeral" } (5m TTL) on the last
+                    // user message. When the session uses "long" retention, these 5m writes waste money
+                    // because they expire before the conversation can reuse them. Upgrading to 1h aligns
+                    // SDK markers with our retention strategy.
+                    // Runs BEFORE (skipCacheWrite overrides these anyway for subagents) and
+                    // BEFORE TTL split estimation (so estimates see the upgraded TTLs).
+                    // Note: message markers respect getMessageRetention (may be "short" even when
+                    // resolvedRetention is "long" -- e.g., adaptive retention splits tool/system from
+                    // conversation). System and tool markers always use resolvedRetention.
+                    if (needsCacheBreakpoints && resolvedRetention === "long" && !effectiveSkipCacheWrite) {
+                        const upgradeMarkers = (blocks) => {
+                            for (const block of blocks) {
+                                const cc = block.cache_control;
+                                if (cc && cc.type === "ephemeral" && !cc.ttl) {
+                                    cc.ttl = "1h";
+                                }
+                            }
+                        };
+                        // Upgrade system blocks (always follow resolvedRetention)
+                        if (Array.isArray(result.system)) {
+                            upgradeMarkers(result.system);
+                        }
+                        // Upgrade tool blocks (always follow resolvedRetention)
+                        if (Array.isArray(result.tools)) {
+                            upgradeMarkers(result.tools);
+                        }
+                        // Do NOT upgrade message markers here. placeCacheBreakpoints
+                        // already assigns zone-aware TTLs: semi-stable/mid get 1h, recent stays 5m.
+                        // Upgrading all message markers would override the intentionally "short"
+                        // recent-zone markers. System and tool markers above still get upgraded.
+                        // The SDK's auto-placed marker on the last user message is in the recent
+                        // zone and should remain at 5m.
+                        logger.debug({ modelId: model.id, sessionKey: config.sessionKey }, "SDK-UPGRADE: Upgraded SDK 5m auto-markers to 1h for long retention");
+                    }
+                    // skipCacheWrite places marker at shared-prefix point instead of stripping all.
+                    // The second-to-last user message is the shared-prefix boundary -- the parent's cache
+                    // already covers everything up to that point. Placing a marker there (instead of stripping)
+                    // lets the server merge with the existing cache entry without creating new writes.
+                    if (needsCacheBreakpoints && effectiveSkipCacheWrite && Array.isArray(result.messages)) {
+                        const msgs = result.messages;
+                        // Count user messages FIRST. Single-turn sub-agents (userCount < 2) have
+                        // no second-to-last-user anchor, so the shared-prefix strip+replace logic
+                        // cannot do anything useful. If we stripped markers unconditionally, the
+                        // request would reach Anthropic with ZERO cache_control anywhere -> 100%
+                        // cache miss, full-price input tokens. Bypass here so the SDK's earlier
+                        // auto-placed markers (system/tools, and last-user at 5m) remain intact
+                        // and the sub-agent can still match the parent's cached prefix.
+                        let userCount = 0;
+                        for (const msg of msgs) {
+                            if (msg.role === "user")
+                                userCount++;
+                        }
+                        if (userCount < 2) {
+                            logger.debug({ modelId: model.id, sessionKey: config.sessionKey, userCount }, "skipCacheWrite bypassed -- single-turn sub-agent keeps standard cache markers");
+                        }
+                        else {
+                            // Strip system block cache_control markers (shared prefix)
+                            if (Array.isArray(result.system)) {
+                                for (const block of result.system) {
+                                    delete block.cache_control;
+                                }
+                            }
+                            // Strip tool definition cache_control markers (shared prefix)
+                            if (Array.isArray(result.tools)) {
+                                for (const tool of result.tools) {
+                                    delete tool.cache_control;
+                                }
+                            }
+                            // Strip all existing message-level cache_control markers
+                            for (const msg of msgs) {
+                                if (Array.isArray(msg.content)) {
+                                    for (const block of msg.content) {
+                                        delete block.cache_control;
+                                    }
+                                }
+                            }
+                            // Then: place marker on second-to-last user message (shared-prefix point)
+                            let seen = 0;
+                            for (let i = msgs.length - 1; i >= 0; i--) {
+                                if (msgs[i].role === "user") {
+                                    seen++;
+                                    if (seen === 2) {
+                                        addCacheControlToLastBlock(msgs[i], resolvedRetention ?? "long");
+                                        break;
+                                    }
+                                }
+                            }
+                            // Re-place marker on last user message (volatile per-turn content).
+                            // The SDK's auto-placed last-user-message marker was stripped above. Re-placing
+                            // with "short" (5m) TTL ensures the last user message (with tool results) gets
+                            // cache reads ($0.30/MTok) instead of full-price uncached input ($3/MTok).
+                            for (let i = msgs.length - 1; i >= 0; i--) {
+                                if (msgs[i].role === "user") {
+                                    addCacheControlToLastBlock(msgs[i], "short");
+                                    break;
+                                }
+                            }
+                            logger.debug({ modelId: model.id, sessionKey: config.sessionKey, markerPlaced: true, lastUserMarkerPlaced: true }, "skipCacheWrite shared-prefix marker placement");
+                        }
+                    }
+                    // Kill switch -- strip ALL cache_control when resolved retention is "none".
+                    // Must run AFTER all breakpoint/marker placement (system, tools, messages) so
+                    // nothing gets re-added after the strip pass.
+                    if (needsCacheBreakpoints && resolvedRetention === "none") {
+                        if (Array.isArray(result.system)) {
+                            for (const block of result.system) {
+                                delete block.cache_control;
+                            }
+                        }
+                        if (Array.isArray(result.tools)) {
+                            for (const tool of result.tools) {
+                                delete tool.cache_control;
+                            }
+                        }
+                        if (Array.isArray(result.messages)) {
+                            for (const msg of result.messages) {
+                                if (Array.isArray(msg.content)) {
+                                    for (const block of msg.content) {
+                                        delete block.cache_control;
+                                    }
+                                }
+                            }
+                        }
+                        logger.debug({ modelId: model.id, sessionKey: config.sessionKey }, "Kill switch active -- stripped all cache_control markers");
+                    }
+                    // Count per-TTL token distribution from final cache_control markers.
+                    // Runs AFTER all breakpoint placement and kill-switch stripping so counts
+                    // reflect the exact markers sent to the API.
+                    if (config.onTtlSplitEstimate && needsCacheBreakpoints) {
+                        let cacheWrite5mTokens = 0;
+                        let cacheWrite1hTokens = 0;
+                        // Uses module-level estimateBlockTokens (text extraction + CHARS_PER_TOKEN_RATIO)
+                        // Count system blocks with cache_control
+                        if (Array.isArray(result.system)) {
+                            for (const block of result.system) {
+                                if (block.cache_control) {
+                                    const tokens = estimateBlockTokens(block);
+                                    const cc = block.cache_control;
+                                    if (cc.ttl === "1h") {
+                                        cacheWrite1hTokens += tokens;
+                                    }
+                                    else {
+                                        cacheWrite5mTokens += tokens;
+                                    }
+                                }
+                            }
+                        }
+                        // Count tool definitions with cache_control
+                        if (Array.isArray(result.tools)) {
+                            for (const tool of result.tools) {
+                                if (tool.cache_control) {
+                                    const tokens = estimateBlockTokens(tool);
+                                    const cc = tool.cache_control;
+                                    if (cc.ttl === "1h") {
+                                        cacheWrite1hTokens += tokens;
+                                    }
+                                    else {
+                                        cacheWrite5mTokens += tokens;
+                                    }
+                                }
+                            }
+                        }
+                        // Count message blocks with cache_control
+                        if (Array.isArray(result.messages)) {
+                            for (const msg of result.messages) {
+                                if (Array.isArray(msg.content)) {
+                                    for (const block of msg.content) {
+                                        if (block.cache_control) {
+                                            const tokens = estimateBlockTokens(block);
+                                            const cc = block.cache_control;
+                                            if (cc.ttl === "1h") {
+                                                cacheWrite1hTokens += tokens;
+                                            }
+                                            else {
+                                                cacheWrite5mTokens += tokens;
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        config.onTtlSplitEstimate({ cacheWrite5mTokens, cacheWrite1hTokens });
+                    }
+                    // Concern 3: service_tier (Responses API + fastMode)
+                    if (needsResponsesApiInjection && config.fastMode) {
+                        result.service_tier = "auto";
+                    }
+                    // Concern 4: store (Responses API + storeCompletions)
+                    if (needsResponsesApiInjection && config.storeCompletions) {
+                        result.store = true;
+                    }
+                    return result;
+                },
+            };
+            return next(model, context, enhancedOptions);
+        };
+    };
+}