@codingame/monaco-vscode-chat-service-override 34.1.3 → 35.0.1

package/vscode/src/vs/workbench/contrib/chat/browser/chatDebug/chatDebugCacheInsights.js

@@ -0,0 +1,720 @@
+
+import { safeIntl } from '@codingame/monaco-vscode-api/vscode/vs/base/common/date';
+import { localize } from '@codingame/monaco-vscode-api/vscode/vs/nls';
+import { CacheDiffKind } from './chatDebugCacheDiff.js';
+
+const numberFormatter = safeIntl.NumberFormat();
+function fmt(n) {
+    return numberFormatter.value.format(n);
+}
+var CacheInsightSeverity;
+(function(CacheInsightSeverity) {
+    CacheInsightSeverity["Ok"] = "ok";
+    CacheInsightSeverity["Info"] = "info";
+    CacheInsightSeverity["Warning"] = "warning";
+    CacheInsightSeverity["Critical"] = "critical";
+})(CacheInsightSeverity || (CacheInsightSeverity = {}));
+var CacheBreakCategory;
+(function(CacheBreakCategory) {
+    CacheBreakCategory["Healthy"] = "healthy";
+    CacheBreakCategory["Expiration"] = "expiration";
+    CacheBreakCategory["Model"] = "model";
+    CacheBreakCategory["Tools"] = "tools";
+    CacheBreakCategory["System"] = "system";
+    CacheBreakCategory["Options"] = "options";
+    CacheBreakCategory["History"] = "history";
+    CacheBreakCategory["Unknown"] = "unknown";
+})(CacheBreakCategory || (CacheBreakCategory = {}));
+var StringDivergenceShape;
+(function(StringDivergenceShape) {
+    StringDivergenceShape["LeadingRemoved"] = "leadingRemoved";
+    StringDivergenceShape["LeadingAdded"] = "leadingAdded";
+    StringDivergenceShape["TrailingRemoved"] = "trailingRemoved";
+    StringDivergenceShape["TrailingAdded"] = "trailingAdded";
+    StringDivergenceShape["InnerEdit"] = "innerEdit";
+})(StringDivergenceShape || (StringDivergenceShape = {}));
+const CHANGED_EXCERPT_CAP = 120;
+function analyzeStringDivergence(a, b) {
+    if (a === b) {
+        return undefined;
+    }
+    const aLength = a.length;
+    const bLength = b.length;
+    const minLength = Math.min(aLength, bLength);
+    let commonPrefix = 0;
+    while (commonPrefix < minLength && a.charCodeAt(commonPrefix) === b.charCodeAt(commonPrefix)) {
+        commonPrefix++;
+    }
+    let commonSuffix = 0;
+    while (commonSuffix < minLength - commonPrefix && a.charCodeAt(aLength - 1 - commonSuffix) === b.charCodeAt(bLength - 1 - commonSuffix)) {
+        commonSuffix++;
+    }
+    let shape;
+    if (commonPrefix === bLength && bLength < aLength) {
+        shape = StringDivergenceShape.TrailingRemoved;
+    } else if (commonPrefix === aLength && aLength < bLength) {
+        shape = StringDivergenceShape.TrailingAdded;
+    } else if (commonSuffix === bLength && bLength < aLength) {
+        shape = StringDivergenceShape.LeadingRemoved;
+    } else if (commonSuffix === aLength && aLength < bLength) {
+        shape = StringDivergenceShape.LeadingAdded;
+    } else {
+        shape = StringDivergenceShape.InnerEdit;
+    }
+    return {
+        shape,
+        commonPrefix,
+        commonSuffix,
+        aLength,
+        bLength,
+        aChanged: a.substring(commonPrefix, aLength - commonSuffix).slice(0, CHANGED_EXCERPT_CAP),
+        bChanged: b.substring(commonPrefix, bLength - commonSuffix).slice(0, CHANGED_EXCERPT_CAP)
+    };
+}
+function describeStringDivergence(d) {
+    switch (d.shape) {
+    case StringDivergenceShape.TrailingAdded:
+        return localize(
+            6678,
+            "{0} chars appended — the previous content survives as a shared prefix",
+            fmt(d.bLength - d.aLength)
+        );
+    case StringDivergenceShape.TrailingRemoved:
+        return localize(
+            6679,
+            "last {0} chars removed — the remaining content still matches the previous bytes",
+            fmt(d.aLength - d.bLength)
+        );
+    case StringDivergenceShape.LeadingAdded:
+        return localize(
+            6680,
+            "{0} chars prepended — this block no longer starts with the same bytes",
+            fmt(d.bLength - d.aLength)
+        );
+    case StringDivergenceShape.LeadingRemoved:
+        return localize(
+            6681,
+            "first {0} chars removed — this block no longer starts with the same bytes",
+            fmt(d.aLength - d.bLength)
+        );
+    case StringDivergenceShape.InnerEdit:
+        return localize(
+            6682,
+            "edited in place — first difference at char {0} ({1} leading and {2} trailing chars unchanged)",
+            fmt(d.commonPrefix),
+            fmt(d.commonPrefix),
+            fmt(d.commonSuffix)
+        );
+    }
+}
+var VolatileValueKind;
+(function(VolatileValueKind) {
+    VolatileValueKind["Timestamp"] = "timestamp";
+    VolatileValueKind["Uuid"] = "uuid";
+    VolatileValueKind["Counter"] = "counter";
+})(VolatileValueKind || (VolatileValueKind = {}));
+const VOLATILE_PATTERNS = [{
+    kind: VolatileValueKind.Uuid,
+    re: /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/
+}, {
+    kind: VolatileValueKind.Timestamp,
+    re: /\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?)?\b/
+}, {
+    kind: VolatileValueKind.Timestamp,
+    re: /\b\d{1,2}:\d{2}:\d{2}\b/
+}, {
+    kind: VolatileValueKind.Counter,
+    re: /\b\d{10,13}\b/
+}];
+function detectVolatileValue(aChanged, bChanged) {
+    for (const {
+        kind,
+        re
+    } of VOLATILE_PATTERNS) {
+        const aMatch = re.exec(aChanged)?.[0];
+        const bMatch = re.exec(bChanged)?.[0];
+        if (aMatch !== undefined && bMatch !== undefined && aMatch !== bMatch) {
+            return kind;
+        }
+    }
+    return undefined;
+}
+const VOLATILE_CONTEXT = 24;
+const VOLATILE_WINDOW_CAP = 240;
+function detectVolatileValueAround(a, b, dv) {
+    const start = Math.max(0, dv.commonPrefix - VOLATILE_CONTEXT);
+    const aWindow = a.substring(start, Math.min(
+        dv.aLength - dv.commonSuffix + VOLATILE_CONTEXT,
+        start + VOLATILE_WINDOW_CAP
+    ));
+    const bWindow = b.substring(start, Math.min(
+        dv.bLength - dv.commonSuffix + VOLATILE_CONTEXT,
+        start + VOLATILE_WINDOW_CAP
+    ));
+    return detectVolatileValue(aWindow, bWindow);
+}
+function volatileValueLabel(kind) {
+    switch (kind) {
+    case VolatileValueKind.Timestamp:
+        return localize(6683, "timestamp");
+    case VolatileValueKind.Uuid:
+        return localize(6684, "unique id (UUID)");
+    case VolatileValueKind.Counter:
+        return localize(6685, "large changing number");
+    }
+}
+function parseToolList(toolsJson) {
+    if (!toolsJson) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(toolsJson);
+    } catch {
+        return undefined;
+    }
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const out = ( new Map());
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        const name = (item && typeof item.name === "string" && item.name) || (item && item.function && typeof item.function.name === "string" && item.function.name) || (item && typeof item.type === "string" && item.type) || `#${i}`;
+        let serialized;
+        try {
+            serialized = JSON.stringify(item);
+        } catch {
+            serialized = String(item);
+        }
+        out.set(name, (out.get(name) ?? "") + serialized);
+    }
+    return out;
+}
+function analyzeToolCatalog(aTools, bTools) {
+    const a = parseToolList(aTools);
+    const b = parseToolList(bTools);
+    if (!a || !b) {
+        return undefined;
+    }
+    const added = [];
+    const removed = [];
+    const modified = [];
+    for (const [name, def] of b) {
+        const aDef = a.get(name);
+        if (aDef === undefined) {
+            added.push(name);
+        } else if (aDef !== def) {
+            modified.push(name);
+        }
+    }
+    for (const name of ( a.keys())) {
+        if (!( b.has(name))) {
+            removed.push(name);
+        }
+    }
+    return {
+        added,
+        removed,
+        modified,
+        reorderedOnly: added.length === 0 && removed.length === 0 && modified.length === 0,
+        aCount: a.size,
+        bCount: b.size
+    };
+}
+const severityRank = {
+    [CacheInsightSeverity.Ok]: 0,
+    [CacheInsightSeverity.Info]: 1,
+    [CacheInsightSeverity.Warning]: 2,
+    [CacheInsightSeverity.Critical]: 3
+};
+function maxInsightSeverity(insights) {
+    let max = CacheInsightSeverity.Ok;
+    for (const i of insights) {
+        if (severityRank[i.severity] > severityRank[max]) {
+            max = i.severity;
+        }
+    }
+    return max;
+}
+function primaryInsight(insights) {
+    return insights.find(i => i.severity === CacheInsightSeverity.Critical) ?? insights.find(i => i.severity === CacheInsightSeverity.Warning);
+}
+const EFFECTIVE_MISS_PCT = 1;
+const TYPICAL_TTL_MINUTES = 5;
+const LOOKBACK_WINDOW_BLOCKS = 20;
+const MIN_CACHEABLE_TOKENS = 4096;
+function computeCacheInsights(input) {
+    const out = [];
+    const modelChanged = input.aModel !== input.bModel;
+    const toolsChanged = (input.aTools ?? "") !== (input.bTools ?? "");
+    const systemChanged = (input.aSystem ?? "") !== (input.bSystem ?? "");
+    if (modelChanged) {
+        out.push({
+            severity: CacheInsightSeverity.Critical,
+            title: ( localize(6686, "Model changed")),
+            detail: ( localize(6687, "{0} → {1}", input.aModel ?? "—", input.bModel ?? "—")),
+            hint: ( localize(
+                6688,
+                "Prompt caches are scoped to a model — switching models recomputes the entire prompt. Route sub-tasks that need a different model through a separate request chain so the main loop keeps its cache."
+            )),
+            category: CacheBreakCategory.Model
+        });
+    }
+    if (toolsChanged) {
+        out.push(toolsInsight(input.aTools, input.bTools));
+    }
+    if (systemChanged) {
+        out.push(systemInsight(input.aSystem, input.bSystem));
+    }
+    if (input.optionsDiff.length > 0) {
+        out.push({
+            severity: CacheInsightSeverity.Warning,
+            title: ( localize(6689, "Request options changed")),
+            detail: ( input.optionsDiff.map(d => `${d.key}: ${d.previousLabel} → ${d.currentLabel}`)).join(" · "),
+            hint: ( localize(
+                6690,
+                "Options are part of the cache key on most providers. Keep per-request options stable when cache reuse matters."
+            )),
+            category: CacheBreakCategory.Options
+        });
+    }
+    if (input.compareInputMessages) {
+        out.push(...messageInsights(input, modelChanged || toolsChanged || systemChanged));
+        if (!modelChanged && !toolsChanged && !systemChanged && input.optionsDiff.length === 0 && !input.diff.break) {
+            out.push(stablePrefixInsight(input));
+        }
+    } else if (input.isContinuation) {
+        out.push({
+            severity: CacheInsightSeverity.Info,
+            title: ( localize(6691, "Responses API continuation")),
+            detail: ( localize(
+                6692,
+                "Only the wire delta is captured for this request; prior context is referenced by previous_response_id and reconstructed provider-side. Analysis is limited to system, tools, and request options."
+            )),
+            category: CacheBreakCategory.Unknown
+        });
+    } else if (input.previousIsContinuation) {
+        out.push({
+            severity: CacheInsightSeverity.Info,
+            title: ( localize(6693, "Message comparison suppressed")),
+            detail: ( localize(
+                6694,
+                "The previous request was a Responses API continuation (delta-only wire input); positionally diffing this full request against it would be misleading."
+            )),
+            category: CacheBreakCategory.Unknown
+        });
+    }
+    return out;
+}
+function toolsInsight(aTools, bTools) {
+    const delta = analyzeToolCatalog(aTools, bTools);
+    const component = "tools";
+    if (delta?.reorderedOnly) {
+        return {
+            severity: CacheInsightSeverity.Critical,
+            title: ( localize(6695, "Tool definitions reordered")),
+            detail: ( localize(
+                6696,
+                "Same {0} tools with identical definitions, sent in a different order.",
+                fmt(delta.bCount)
+            )),
+            hint: ( localize(
+                6697,
+                "Tools render at the very start of the prompt — a pure reorder still changes the bytes and invalidates the entire cache. Serialize the tool list deterministically (e.g. sort by name)."
+            )),
+            component,
+            category: CacheBreakCategory.Tools
+        };
+    }
+    if (delta && (delta.added.length > 0 || delta.removed.length > 0)) {
+        const parts = [];
+        if (delta.added.length > 0) {
+            parts.push(( localize(6698, "added: {0}", delta.added.join(", "))));
+        }
+        if (delta.removed.length > 0) {
+            parts.push(( localize(6699, "removed: {0}", delta.removed.join(", "))));
+        }
+        if (delta.modified.length > 0) {
+            parts.push(( localize(6700, "modified: {0}", delta.modified.join(", "))));
+        }
+        return {
+            severity: CacheInsightSeverity.Critical,
+            title: ( localize(
+                6701,
+                "Tool catalog changed ({0} → {1} tools)",
+                fmt(delta.aCount),
+                fmt(delta.bCount)
+            )),
+            detail: parts.join(" · "),
+            hint: ( localize(
+                6702,
+                "Tool definitions render before everything else, so adding or removing a tool mid-session invalidates the whole prompt. Keep the tool set stable for the life of a session, or use deferred/appended tool loading instead of swapping the catalog."
+            )),
+            component,
+            category: CacheBreakCategory.Tools
+        };
+    }
+    if (delta && delta.modified.length > 0) {
+        return {
+            severity: CacheInsightSeverity.Critical,
+            title: ( localize(6703, "Tool definitions modified")),
+            detail: ( localize(6704, "changed: {0}", delta.modified.join(", "))),
+            hint: ( localize(
+                6705,
+                "A changed tool description or schema rewrites the prompt from the tools block onward. Check for dynamic content (counts, paths, timestamps) inside tool descriptions."
+            )),
+            component,
+            category: CacheBreakCategory.Tools
+        };
+    }
+    const dv = analyzeStringDivergence(aTools ?? "", bTools ?? "");
+    return {
+        severity: CacheInsightSeverity.Critical,
+        title: ( localize(6706, "Tool catalog changed")),
+        detail: dv ? describeStringDivergence(dv) : undefined,
+        hint: ( localize(
+            6707,
+            "The tool catalog is the first block of the prompt — any byte change here invalidates the entire cache."
+        )),
+        component,
+        category: CacheBreakCategory.Tools
+    };
+}
+function systemInsight(aSystem, bSystem) {
+    const dv = analyzeStringDivergence(aSystem ?? "", bSystem ?? "");
+    const volatile = dv ? detectVolatileValueAround(aSystem ?? "", bSystem ?? "", dv) : undefined;
+    return {
+        severity: CacheInsightSeverity.Critical,
+        title: ( localize(6708, "System prompt changed")),
+        detail: dv ? ( localize(
+            6709,
+            "{0} → {1} chars · {2}",
+            fmt(dv.aLength),
+            fmt(dv.bLength),
+            describeStringDivergence(dv)
+        )) : undefined,
+        hint: volatile ? ( localize(
+            6710,
+            "The changed region looks like a {0} — volatile values interpolated into the system prompt break the cache on every request. Move dynamic content after the conversation history or drop it.",
+            volatileValueLabel(volatile)
+        )) : ( localize(
+            6711,
+            "A system prompt change invalidates everything after the tools block. Keep the system prompt byte-stable for the life of a session and inject per-turn context into the newest message instead."
+        )),
+        component: "system",
+        category: CacheBreakCategory.System
+    };
+}
+function messageInsights(input, hasEarlierBreak) {
+    const {
+        diff
+    } = input;
+    if (!diff.break) {
+        return [];
+    }
+    const out = [];
+    const idx = diff.break.index;
+    const component = `messages[${idx}]`;
+    const counts = diff.counts;
+    if (diff.break.kind === CacheDiffKind.OnlyInB) {
+        out.push({
+            severity: hasEarlierBreak ? CacheInsightSeverity.Info : CacheInsightSeverity.Ok,
+            title: ( localize(6712, "New messages appended — expected growth")),
+            detail: ( localize(
+                6713,
+                "{0} new message(s) after {1} unchanged — the shared prefix was extended, not broken. The uncached tokens are the new suffix being written to the cache for the next request.",
+                fmt(counts.onlyInB),
+                fmt(counts.identical)
+            )),
+            component,
+            category: CacheBreakCategory.Healthy
+        });
+        if (counts.onlyInB > LOOKBACK_WINDOW_BLOCKS) {
+            out.push({
+                severity: CacheInsightSeverity.Warning,
+                title: ( localize(
+                    6714,
+                    "{0} blocks appended — beyond the typical cache lookback window",
+                    fmt(counts.onlyInB)
+                )),
+                detail: ( localize(
+                    6715,
+                    "Providers typically look back ~{0} content blocks for a prior cache entry; a turn that appends more can silently miss it even though the prefix matches.",
+                    LOOKBACK_WINDOW_BLOCKS
+                )),
+                hint: ( localize(
+                    6716,
+                    "During long tool loops, place intermediate cache breakpoints every ~15 blocks so the next request can still find a cache entry."
+                ))
+            });
+        }
+        return out;
+    }
+    if (diff.break.kind === CacheDiffKind.OnlyInA) {
+        out.push({
+            severity: CacheInsightSeverity.Critical,
+            title: ( localize(6717, "History truncated at messages[{0}]", idx)),
+            detail: ( localize(
+                6718,
+                "{0} message(s) present in the previous request are missing from this one.",
+                fmt(counts.onlyInA)
+            )),
+            hint: ( localize(
+                6719,
+                "History slicing or compaction shortens the prefix — the cache can only match up to the cut, and everything after it is recomputed."
+            )),
+            component,
+            category: CacheBreakCategory.History
+        });
+        return out;
+    }
+    const tok = diff.signature.find(t => t.index === idx);
+    const role = tok?.bRole ?? tok?.aRole ?? "message";
+    const aMsg = input.aMessages[idx];
+    const bMsg = input.bMessages[idx];
+    const dv = aMsg && bMsg ? analyzeStringDivergence(aMsg.text, bMsg.text) : undefined;
+    const volatile = dv && aMsg && bMsg ? detectVolatileValueAround(aMsg.text, bMsg.text, dv) : undefined;
+    const detailParts = [];
+    if (aMsg && bMsg) {
+        detailParts.push(( localize(
+            6720,
+            "{0} message, {1} → {2} chars",
+            role,
+            fmt(aMsg.charLength),
+            fmt(bMsg.charLength)
+        )));
+    }
+    if (dv) {
+        detailParts.push(describeStringDivergence(dv));
+    }
+    out.push({
+        severity: CacheInsightSeverity.Critical,
+        title: ( localize(6721, "History rewritten at messages[{0}]", idx)),
+        detail: detailParts.join(" · "),
+        hint: volatile ? ( localize(
+            6722,
+            "The changed region looks like a {0} — a volatile value re-rendered into the conversation history breaks the prefix on every request.",
+            volatileValueLabel(volatile)
+        )) : ( localize(
+            6723,
+            "Conversation history must be byte-identical between requests to reuse the cached prefix. A re-serialized {0} turn — trimmed whitespace, dropped reasoning or preamble text, reformatted tool calls — silently invalidates everything after it.",
+            role
+        )),
+        component,
+        category: CacheBreakCategory.History
+    });
+    const changedAfterBreak = counts.contentDrift + counts.lengthChange + counts.onlyInA + counts.onlyInB - 1;
+    if (changedAfterBreak > 0) {
+        out.push({
+            severity: CacheInsightSeverity.Info,
+            title: ( localize(
+                6724,
+                "{0} more changed position(s) after the break",
+                fmt(changedAfterBreak)
+            )),
+            detail: ( localize(
+                6725,
+                "Once the prefix breaks at messages[{0}], everything after it is recomputed regardless — fix the first break first.",
+                idx
+            ))
+        });
+    }
+    return out;
+}
+function stablePrefixInsight(input) {
+    if (input.hitPct < EFFECTIVE_MISS_PCT) {
+        if (input.inputTokens > 0 && input.inputTokens < MIN_CACHEABLE_TOKENS) {
+            return {
+                severity: CacheInsightSeverity.Warning,
+                title: ( localize(6726, "Prompt may be below the minimum cacheable size")),
+                detail: ( localize(
+                    6727,
+                    "{0} input tokens — providers only cache prompts above a minimum prefix size (roughly 1,024-4,096 tokens depending on model), and smaller prompts silently never cache.",
+                    fmt(input.inputTokens)
+                )),
+                hint: ( localize(
+                    6728,
+                    "Small utility requests (titles, summaries) often sit below the threshold; a 0% hit on them is normal and not worth optimizing."
+                )),
+                category: CacheBreakCategory.Expiration
+            };
+        }
+        const minutes = input.minutesSincePrevious;
+        const gap = minutes !== undefined && minutes >= 1 ? ( localize(
+            6729,
+            " {0} minute(s) elapsed since the previous request.",
+            fmt(Math.round(minutes))
+        )) : "";
+        return {
+            severity: CacheInsightSeverity.Warning,
+            title: ( localize(6730, "Likely cache expiration")),
+            detail: ( localize(
+                6731,
+                "The prompt is byte-identical to the previous request but only {0}% was served from cache.{1}",
+                input.hitPct.toFixed(2),
+                gap
+            )),
+            hint: ( localize(
+                6732,
+                "Provider prompt caches expire after a few minutes of inactivity (typically ~{0} min). Long gaps between requests recompute the full prompt even when nothing changed.",
+                TYPICAL_TTL_MINUTES
+            )),
+            category: CacheBreakCategory.Expiration
+        };
+    }
+    return {
+        severity: CacheInsightSeverity.Ok,
+        title: ( localize(6733, "Prompt prefix fully stable")),
+        detail: ( localize(
+            6734,
+            "No divergence detected — {0}% of input tokens were served from cache.",
+            input.hitPct.toFixed(2)
+        )),
+        category: CacheBreakCategory.Healthy
+    };
+}
+function categorizeCacheBreak(insights) {
+    const primary = primaryInsight(insights);
+    if (primary?.category) {
+        return primary.category;
+    }
+    for (const i of insights) {
+        if (i.category) {
+            return i.category;
+        }
+    }
+    return CacheBreakCategory.Unknown;
+}
+function cacheBreakCategoryLabel(category) {
+    switch (category) {
+    case CacheBreakCategory.Healthy:
+        return localize(6735, "healthy growth");
+    case CacheBreakCategory.Expiration:
+        return localize(6736, "expiration / not cacheable");
+    case CacheBreakCategory.Model:
+        return localize(6737, "model changed");
+    case CacheBreakCategory.Tools:
+        return localize(6738, "tool catalog changed");
+    case CacheBreakCategory.System:
+        return localize(6739, "system prompt changed");
+    case CacheBreakCategory.Options:
+        return localize(6740, "request options changed");
+    case CacheBreakCategory.History:
+        return localize(6741, "history rewritten");
+    case CacheBreakCategory.Unknown:
+        return localize(6742, "not classified");
+    }
+}
+const AVOIDABLE_CATEGORIES = [
+    CacheBreakCategory.Model,
+    CacheBreakCategory.Tools,
+    CacheBreakCategory.System,
+    CacheBreakCategory.Options,
+    CacheBreakCategory.History
+];
+const RECURRING_THRESHOLD = 2;
+function buildSessionCacheReport(pairs, turnTokens = []) {
+    let overallInput = 0;
+    let overallCached = 0;
+    let overallTurns = 0;
+    for (const t of turnTokens) {
+        if (t.inputTokens > 0) {
+            overallInput += t.inputTokens;
+            overallCached += Math.min(t.cachedTokens, t.inputTokens);
+            overallTurns++;
+        }
+    }
+    const overall = overallInput > 0 ? {
+        inputTokens: overallInput,
+        cachedTokens: overallCached,
+        hitPct: (overallCached / overallInput) * 100,
+        turnCount: overallTurns
+    } : undefined;
+    const stats = ( new Map());
+    const causeByTurnIndex = ( new Map());
+    let healthyCount = 0;
+    let avoidableLostTokens = 0;
+    for (const pair of pairs) {
+        causeByTurnIndex.set(pair.turnIndex, pair.category);
+        if (pair.category === CacheBreakCategory.Healthy) {
+            healthyCount++;
+            continue;
+        }
+        const stat = stats.get(pair.category) ?? {
+            count: 0,
+            lostTokens: 0
+        };
+        stat.count++;
+        stat.lostTokens += pair.lostTokens;
+        stats.set(pair.category, stat);
+        if (AVOIDABLE_CATEGORIES.includes(pair.category)) {
+            avoidableLostTokens += pair.lostTokens;
+        }
+    }
+    const byCategory = ( [...stats.entries()].map(([category, s]) => ({
+        category,
+        count: s.count,
+        lostTokens: s.lostTokens
+    }))).sort((a, b) => b.lostTokens - a.lostTokens);
+    const findings = [];
+    for (const stat of byCategory) {
+        if (stat.count < RECURRING_THRESHOLD) {
+            continue;
+        }
+        if (AVOIDABLE_CATEGORIES.includes(stat.category)) {
+            findings.push({
+                severity: CacheInsightSeverity.Critical,
+                title: ( localize(
+                    6743,
+                    "Recurring invalidator: {0} in {1} of {2} request pairs",
+                    cacheBreakCategoryLabel(stat.category),
+                    fmt(stat.count),
+                    fmt(pairs.length)
+                )),
+                detail: ( localize(
+                    6744,
+                    "~{0} tokens recomputed across those requests. A break that repeats is systemic — look for the same root cause on every occurrence.",
+                    fmt(stat.lostTokens)
+                )),
+                category: stat.category
+            });
+        } else if (stat.category === CacheBreakCategory.Expiration) {
+            findings.push({
+                severity: CacheInsightSeverity.Warning,
+                title: ( localize(6745, "Cache likely expired {0} times", fmt(stat.count))),
+                detail: ( localize(
+                    6746,
+                    "~{0} tokens recomputed after idle gaps or on prompts below the cacheable minimum.",
+                    fmt(stat.lostTokens)
+                )),
+                hint: ( localize(
+                    6747,
+                    "If long gaps are inherent to the workflow, consider a longer-TTL cache or pre-warming before the user returns."
+                )),
+                category: stat.category
+            });
+        }
+    }
+    if (findings.length === 0 && pairs.length > 0 && healthyCount === pairs.length) {
+        findings.push({
+            severity: CacheInsightSeverity.Ok,
+            title: ( localize(6748, "All request pairs grew the prefix cleanly")),
+            detail: ( localize(
+                6749,
+                "Every request either appended new messages or matched the previous prompt exactly — no avoidable cache breaks in this session."
+            )),
+            category: CacheBreakCategory.Healthy
+        });
+    }
+    return {
+        pairCount: pairs.length,
+        healthyCount,
+        avoidableLostTokens,
+        overall,
+        byCategory,
+        causeByTurnIndex,
+        findings
+    };
+}
+
+export { CacheBreakCategory, CacheInsightSeverity, StringDivergenceShape, VolatileValueKind, analyzeStringDivergence, analyzeToolCatalog, buildSessionCacheReport, cacheBreakCategoryLabel, categorizeCacheBreak, computeCacheInsights, describeStringDivergence, detectVolatileValue, maxInsightSeverity, primaryInsight };