comisai 1.0.37 → 1.0.41

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

@@ -0,0 +1,282 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Multi-zone + single-breakpoint placement primitives.
+ *
+ * Hosts the breakpoint-placement primitives: `placeSingleBreakpoint`,
+ * `placeCacheBreakpoints`, and the `BreakpointOptions` interface they share.
+ *
+ * @module
+ */
+import { CHARS_PER_TOKEN_RATIO, CHARS_PER_TOKEN_RATIO_STRUCTURED, CACHE_LOOKBACK_WINDOW, } from "../../../context-engine/index.js";
+import { addCacheControlToLastBlock } from "./cache-control-block.js";
+import { sessionCadenceTracker } from "./cadence-tracker.js";
+/**
+ * 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 */
+export 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 */
+export 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) {
+            // Promote recent-zone to "long" when cadence indicates user pauses exceed 5m.
+            // Monotonicity guard: recent zone can only be promoted when
+            // resolvedRetention (tool/system) is already "long".
+            let recentRetention = retention;
+            if (options.promoteRecentZoneOnSlowCadence && options.sessionKey) {
+                const cadence = sessionCadenceTracker.get(options.sessionKey);
+                if (cadence?.promoted && resolvedRetention === "long") {
+                    recentRetention = "long";
+                }
+            }
+            addCacheControlToLastBlock(messages[secondToLastUserIdx], recentRetention);
+            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 < maxBreakpoints) {
+        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 < maxBreakpoints; 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 */

package/node_modules/@comis/agent/dist/executor/stream-wrappers/request-body/cache-breakpoints.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Cache breakpoint helpers + adaptive TTL promotion.
+ *
+ * Hosts (directly):
+ *  - `resolveCacheRetention` (public): per-model cache-retention override resolution.
+ *  - `getMinCacheableTokens` (public): per-model minTokens threshold lookup.
+ *  - `clearSessionPrefixStability` (public) + `sessionPrefixStability`
+ *    (module-level state mutated by the factory).
+ *  - `sortToolsForCacheStability` (public): tool ordering.
+ *  - `identifyBreakpointZone`, `hashBreakpointContent`, `maybePromoteBreakpoints`
+ *    (public): adaptive TTL promotion helpers.
+ *  - `computeRenderedToolsHash`, `countCacheBreakpoints` (internal helpers
+ *    consumed by the factory).
+ *
+ * Re-exports (canonical names) from sibling modules:
+ *  - `addCacheControlToLastBlock`, `CACHEABLE_BLOCK_TYPES` from
+ *    `./cache-control-block.js`
+ *  - `placeCacheBreakpoints`, `placeSingleBreakpoint`, `BreakpointOptions`
+ *    from `./breakpoint-placement.js`
+ *  - `clearSessionCadenceTracker`, cadence threshold constants from
+ *    `./cadence-tracker.js`
+ *
+ * @module
+ */
+import type { CacheRetention } from "@earendil-works/pi-ai";
+import type { BlockStabilityTracker } from "../../block-stability-tracker.js";
+export { addCacheControlToLastBlock, CACHEABLE_BLOCK_TYPES, } from "./cache-control-block.js";
+export { placeCacheBreakpoints, placeSingleBreakpoint, } from "./breakpoint-placement.js";
+export type { BreakpointOptions } from "./breakpoint-placement.js";
+export { clearSessionCadenceTracker, sessionCadenceTracker, SLOW_CADENCE_MS, SLOW_CADENCE_PROMOTION_THRESHOLD, FAST_CADENCE_DEMOTION_THRESHOLD, } from "./cadence-tracker.js";
+export type { CadenceTrackerEntry } from "./cadence-tracker.js";
+export declare const sessionPrefixStability: Map<string, {
+    hash: number;
+    fenceIdx: number;
+    consecutiveChanges: number;
+}>;
+export declare function clearSessionPrefixStability(sessionKey: string): void;
+/**
+ * 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 declare function resolveCacheRetention(modelId: string, agentRetention: CacheRetention, overrides?: Record<string, CacheRetention>): CacheRetention;
+/**
+ * Compute a hash of rendered tools excluding cache_control.
+ * Uses computeHash (djb2 over JSON.stringify) from cache-detection/.
+ */
+export declare function computeRenderedToolsHash(tools: Array<Record<string, unknown>>): number;
+/**
+ * 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 declare function getMinCacheableTokens(modelId: string | undefined): number;
+/**
+ * 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.
+ */
+export declare function countCacheBreakpoints(params: Record<string, unknown>): number;
+/**
+ * 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 declare function sortToolsForCacheStability(tools: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+/**
+ * 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 declare function identifyBreakpointZone(breakpointIdx: number, messageCount: number): "semi-stable" | "mid" | "recent";
+/**
+ * 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 declare function hashBreakpointContent(messages: Array<Record<string, unknown>>, breakpointIdx: number): number;
+/**
+ * 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 declare function maybePromoteBreakpoints(messages: Array<Record<string, unknown>>, tracker: BlockStabilityTracker, sessionKey: string, threshold: number, resolvedRetention: CacheRetention | undefined): number;

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

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Cache breakpoint helpers + adaptive TTL promotion.
+ *
+ * Hosts (directly):
+ *  - `resolveCacheRetention` (public): per-model cache-retention override resolution.
+ *  - `getMinCacheableTokens` (public): per-model minTokens threshold lookup.
+ *  - `clearSessionPrefixStability` (public) + `sessionPrefixStability`
+ *    (module-level state mutated by the factory).
+ *  - `sortToolsForCacheStability` (public): tool ordering.
+ *  - `identifyBreakpointZone`, `hashBreakpointContent`, `maybePromoteBreakpoints`
+ *    (public): adaptive TTL promotion helpers.
+ *  - `computeRenderedToolsHash`, `countCacheBreakpoints` (internal helpers
+ *    consumed by the factory).
+ *
+ * Re-exports (canonical names) from sibling modules:
+ *  - `addCacheControlToLastBlock`, `CACHEABLE_BLOCK_TYPES` from
+ *    `./cache-control-block.js`
+ *  - `placeCacheBreakpoints`, `placeSingleBreakpoint`, `BreakpointOptions`
+ *    from `./breakpoint-placement.js`
+ *  - `clearSessionCadenceTracker`, cadence threshold constants from
+ *    `./cadence-tracker.js`
+ *
+ * @module
+ */
+import { MIN_CACHEABLE_TOKENS, DEFAULT_MIN_CACHEABLE_TOKENS, } from "../../../context-engine/index.js";
+import { computeHash } from "../../cache-detection/index.js";
+// Re-exports — the new sub-modules host the canonical implementations.
+export { addCacheControlToLastBlock, CACHEABLE_BLOCK_TYPES, } from "./cache-control-block.js";
+export { placeCacheBreakpoints, placeSingleBreakpoint, } from "./breakpoint-placement.js";
+export { clearSessionCadenceTracker, sessionCadenceTracker, SLOW_CADENCE_MS, SLOW_CADENCE_PROMOTION_THRESHOLD, FAST_CADENCE_DEMOTION_THRESHOLD, } from "./cadence-tracker.js";
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+export const sessionPrefixStability = new Map();
+export function clearSessionPrefixStability(sessionKey) {
+    sessionPrefixStability.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
+// ---------------------------------------------------------------------------
+/**
+ * Compute a hash of rendered tools excluding cache_control.
+ * Uses computeHash (djb2 over JSON.stringify) from cache-detection/.
+ */
+export 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.
+ */
+export 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;
+}
+// ---------------------------------------------------------------------------
+// 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;
+}
+// Need to import addCacheControlToLastBlock for maybePromoteBreakpoints' usage path?
+// No — maybePromoteBreakpoints mutates cache_control inline; it does not call addCacheControlToLastBlock.
+// The import in breakpoint-placement.ts handles the helper consumption.