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

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

@@ -0,0 +1,213 @@
+import { ICacheDiffResult, INormalizedMessage } from "./chatDebugCacheDiff.js";
+/** Severity of a single cache finding. Rendered as a codicon + color. */
+export declare enum CacheInsightSeverity {
+    /** Expected, healthy behavior (e.g. new turn appended). */
+    Ok = "ok",
+    /** Context that helps interpretation but isn't actionable. */
+    Info = "info",
+    /** Suspicious but not definitively avoidable (e.g. likely expiration). */
+    Warning = "warning",
+    /** An avoidable cache break the user should investigate. */
+    Critical = "critical"
+}
+/**
+ * Coarse classification of what broke (or didn't break) the cache for one
+ * request pair. Used for rail chips and cross-turn aggregation.
+ */
+export declare enum CacheBreakCategory {
+    /** Pure append or fully stable prefix — the cache behaved as designed. */
+    Healthy = "healthy",
+    /** Prefix byte-identical but the cache still missed — TTL/eviction. */
+    Expiration = "expiration",
+    Model = "model",
+    Tools = "tools",
+    System = "system",
+    Options = "options",
+    /** Conversation history rewritten or truncated in place. */
+    History = "history",
+    /** Continuations and other pairs we can't classify. */
+    Unknown = "unknown"
+}
+/** One human-readable finding about the cache behavior of the current request. */
+export interface ICacheInsight {
+    readonly severity: CacheInsightSeverity;
+    /** Short, scannable summary — doubles as the headline verdict for the first non-OK finding. */
+    readonly title: string;
+    /** Evidence: what exactly differs and by how much. */
+    readonly detail?: string;
+    /** Actionable guidance derived from how prefix caches work. */
+    readonly hint?: string;
+    /** Name of the Components entry this finding refers to (e.g. `system`, `tools`, `messages[7]`). */
+    readonly component?: string;
+    /** Break category this finding contributes to, for cross-turn aggregation. */
+    readonly category?: CacheBreakCategory;
+}
+/** A request-option change, pre-formatted by the caller for display. */
+export interface ICacheInsightOptionDelta {
+    readonly key: string;
+    readonly previousLabel: string;
+    readonly currentLabel: string;
+}
+export interface ICacheInsightsInput {
+    readonly aModel: string | undefined;
+    readonly bModel: string | undefined;
+    readonly aSystem: string | undefined;
+    readonly bSystem: string | undefined;
+    readonly aTools: string | undefined;
+    readonly bTools: string | undefined;
+    readonly aMessages: readonly INormalizedMessage[];
+    readonly bMessages: readonly INormalizedMessage[];
+    readonly diff: ICacheDiffResult;
+    readonly optionsDiff: readonly ICacheInsightOptionDelta[];
+    /** Cache hit percentage (0-100) reported for the current request. */
+    readonly hitPct: number;
+    /** Total input tokens reported for the current request (0 when unknown). */
+    readonly inputTokens: number;
+    /** Minutes elapsed between the start of the previous and the current request. */
+    readonly minutesSincePrevious: number | undefined;
+    /** True when the current request is a Responses API continuation (delta-only wire input). */
+    readonly isContinuation: boolean;
+    /** True when the previous request is a Responses API continuation. */
+    readonly previousIsContinuation: boolean;
+    /** False when message-level positional diffing is suppressed (either side is a continuation). */
+    readonly compareInputMessages: boolean;
+}
+/** How two unequal strings relate to each other structurally. */
+export declare enum StringDivergenceShape {
+    /** B is a strict suffix of A — leading bytes were removed. */
+    LeadingRemoved = "leadingRemoved",
+    /** A is a strict suffix of B — bytes were prepended. */
+    LeadingAdded = "leadingAdded",
+    /** B is a strict prefix of A — trailing bytes were removed. */
+    TrailingRemoved = "trailingRemoved",
+    /** A is a strict prefix of B — bytes were appended. */
+    TrailingAdded = "trailingAdded",
+    /** The change happens somewhere in the middle. */
+    InnerEdit = "innerEdit"
+}
+export interface IStringDivergence {
+    readonly shape: StringDivergenceShape;
+    /** Number of leading chars shared by both sides. */
+    readonly commonPrefix: number;
+    /** Number of trailing chars shared by both sides (disjoint from the prefix). */
+    readonly commonSuffix: number;
+    readonly aLength: number;
+    readonly bLength: number;
+    /** Excerpt of the changed region on the A side (capped). */
+    readonly aChanged: string;
+    /** Excerpt of the changed region on the B side (capped). */
+    readonly bChanged: string;
+}
+/**
+ * Locate where two strings diverge: the shared leading/trailing spans and
+ * the changed region in between. Returns `undefined` when the strings are
+ * equal. The common prefix and suffix never overlap, so
+ * `commonPrefix + commonSuffix <= min(aLength, bLength)`.
+ */
+export declare function analyzeStringDivergence(a: string, b: string): IStringDivergence | undefined;
+/** One-line human-readable description of a string divergence. */
+export declare function describeStringDivergence(d: IStringDivergence): string;
+/** Categories of volatile values that classically break prompt caches. */
+export declare enum VolatileValueKind {
+    Timestamp = "timestamp",
+    Uuid = "uuid",
+    Counter = "counter"
+}
+/**
+ * Detect whether the changed region on both sides carries the *same kind* of
+ * volatile value (timestamp, UUID, epoch-like counter) with *different*
+ * contents — the classic silent cache invalidator: `datetime.now()` or a
+ * request id interpolated into the prompt.
+ */
+export declare function detectVolatileValue(aChanged: string, bChanged: string): VolatileValueKind | undefined;
+/** Structured comparison of two JSON tool catalogs. */
+export interface IToolCatalogDelta {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+    /** Tools present on both sides whose definition bytes differ. */
+    readonly modified: readonly string[];
+    /** True when the set and every definition match — only the order differs. */
+    readonly reorderedOnly: boolean;
+    readonly aCount: number;
+    readonly bCount: number;
+}
+/**
+ * Compare two tool catalogs at the tool level: which tools were added,
+ * removed, or had their definition change — or whether the catalog was
+ * merely reordered (same tools, same bytes, different order). Returns
+ * `undefined` when either side isn't a parseable JSON array, in which case
+ * callers should fall back to byte-level divergence.
+ */
+export declare function analyzeToolCatalog(aTools: string | undefined, bTools: string | undefined): IToolCatalogDelta | undefined;
+/** The highest severity present in a findings list (Ok when empty). */
+export declare function maxInsightSeverity(insights: readonly ICacheInsight[]): CacheInsightSeverity;
+/** The first warning-or-worse finding — the headline verdict. */
+export declare function primaryInsight(insights: readonly ICacheInsight[]): ICacheInsight | undefined;
+/**
+ * Produce the ordered findings list for an A→B request comparison.
+ *
+ * Findings are emitted in provider cache-key order (model, tools, system,
+ * options, messages) so the first critical finding is the earliest byte
+ * change — the one that actually broke the cache; later changes are
+ * recomputed regardless.
+ */
+export declare function computeCacheInsights(input: ICacheInsightsInput): ICacheInsight[];
+/** Resolve the break category for one request pair from its findings. */
+export declare function categorizeCacheBreak(insights: readonly ICacheInsight[]): CacheBreakCategory;
+/** Human-readable label for a break category. */
+export declare function cacheBreakCategoryLabel(category: CacheBreakCategory): string;
+/** The outcome of analyzing one consecutive request pair in a session. */
+export interface ISessionPairOutcome {
+    /** Index of the current (B) turn in the session's turn list. */
+    readonly turnIndex: number;
+    readonly category: CacheBreakCategory;
+    /** Input tokens of the B request that were not served from cache. */
+    readonly lostTokens: number;
+}
+/** Aggregate stats for one break category across a session. */
+export interface ISessionCategoryStat {
+    readonly category: CacheBreakCategory;
+    readonly count: number;
+    readonly lostTokens: number;
+}
+/** Token counts for one turn, used for the token-weighted overall hit rate. */
+export interface ISessionTurnTokens {
+    readonly inputTokens: number;
+    readonly cachedTokens: number;
+}
+/**
+ * Token-weighted cache hit across a whole session. Per-request percentages
+ * overweight small utility calls; weighting by input tokens shows the real
+ * cost picture.
+ */
+export interface ISessionOverallHit {
+    readonly inputTokens: number;
+    readonly cachedTokens: number;
+    /** `cachedTokens / inputTokens` as a percentage (0-100). */
+    readonly hitPct: number;
+    /** Number of turns that reported token usage. */
+    readonly turnCount: number;
+}
+/** Cross-turn cache health report for a whole session. */
+export interface ISessionCacheReport {
+    readonly pairCount: number;
+    readonly healthyCount: number;
+    /** Uncached tokens across pairs whose break was avoidable. */
+    readonly avoidableLostTokens: number;
+    /** Token-weighted overall hit rate; undefined when no turn reported usage. */
+    readonly overall: ISessionOverallHit | undefined;
+    /** Per-category stats, sorted by lost tokens descending (healthy excluded). */
+    readonly byCategory: readonly ISessionCategoryStat[];
+    /** Per-turn category, for rail decoration. */
+    readonly causeByTurnIndex: ReadonlyMap<number, CacheBreakCategory>;
+    /** Session-level findings: recurring invalidators and the overall verdict. */
+    readonly findings: readonly ICacheInsight[];
+}
+/**
+ * Aggregate per-pair outcomes into a session-level report: which break
+ * categories recur (a one-off break is a curiosity; a recurring one is a
+ * bug), how many tokens each cost, and the token-weighted overall hit rate
+ * across all turns (`turnTokens` covers every turn, including the first,
+ * which has no pair).
+ */
+export declare function buildSessionCacheReport(pairs: readonly ISessionPairOutcome[], turnTokens?: readonly ISessionTurnTokens[]): ISessionCacheReport;