feat(widget): add cache-hit-rate widget

src/types/TokenMetrics.ts

@@ -17,6 +17,8 @@ export interface TokenMetrics {
     inputTokens: number;
     outputTokens: number;
     cachedTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
     totalTokens: number;
     contextLength: number;
 }

src/utils/__tests__/jsonl-metrics.test.ts

@@ -156,6 +156,8 @@ describe('jsonl transcript metrics', () => {
             inputTokens: 1799,
             outputTokens: 141,
             cachedTokens: 92,
+            cacheReadTokens: 56,
+            cacheCreationTokens: 36,
             totalTokens: 2032,
             contextLength: 250
         });
@@ -222,6 +224,8 @@ describe('jsonl transcript metrics', () => {
             inputTokens: 2,           // 1 + 1
             outputTokens: 550,        // 150 + 400
             cachedTokens: 46500,      // (12000 + 11000) + (23000 + 500)
+            cacheReadTokens: 35000,   // 12000 + 23000
+            cacheCreationTokens: 11500, // 11000 + 500
             totalTokens: 47052,       // 2 + 550 + 46500
             contextLength: 23501      // last main-chain final entry: 1 + 23000 + 500
         });
@@ -267,6 +271,8 @@ describe('jsonl transcript metrics', () => {
             inputTokens: 4,
             outputTokens: 140,
             cachedTokens: 1200,
+            cacheReadTokens: 1000,
+            cacheCreationTokens: 200,
             totalTokens: 1344,
             contextLength: 1204
         });
@@ -320,6 +326,8 @@ describe('jsonl transcript metrics', () => {
             inputTokens: 5,
             outputTokens: 200,
             cachedTokens: 375,
+            cacheReadTokens: 300,
+            cacheCreationTokens: 75,
             totalTokens: 580,
             contextLength: 228
         });
@@ -357,6 +365,8 @@ describe('jsonl transcript metrics', () => {
             inputTokens: 300,
             outputTokens: 130,
             cachedTokens: 80,
+            cacheReadTokens: 50,
+            cacheCreationTokens: 30,
             totalTokens: 510,
             contextLength: 250
         });
@@ -368,6 +378,8 @@ describe('jsonl transcript metrics', () => {
             inputTokens: 0,
             outputTokens: 0,
             cachedTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
             totalTokens: 0,
             contextLength: 0
         });

src/utils/jsonl-metrics.ts

@@ -152,14 +152,16 @@ export async function getTokenMetrics(transcriptPath: string): Promise<TokenMetr
     try {
         // Use Node.js-compatible file reading
         if (!fs.existsSync(transcriptPath)) {
-            return { inputTokens: 0, outputTokens: 0, cachedTokens: 0, totalTokens: 0, contextLength: 0 };
+            return { inputTokens: 0, outputTokens: 0, cachedTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, totalTokens: 0, contextLength: 0 };
         }
 
         const lines = await readJsonlLines(transcriptPath);
 
         let inputTokens = 0;
         let outputTokens = 0;
         let cachedTokens = 0;
+        let cacheReadTokens = 0;
+        let cacheCreationTokens = 0;
         let contextLength = 0;
 
         // Parse each line and sum up token usage for totals.
@@ -200,6 +202,8 @@ export async function getTokenMetrics(transcriptPath: string): Promise<TokenMetr
 
             inputTokens += usage.input_tokens || 0;
             outputTokens += usage.output_tokens || 0;
+            cacheReadTokens += usage.cache_read_input_tokens ?? 0;
+            cacheCreationTokens += usage.cache_creation_input_tokens ?? 0;
             cachedTokens += usage.cache_read_input_tokens ?? 0;
             cachedTokens += usage.cache_creation_input_tokens ?? 0;
 
@@ -224,9 +228,9 @@ export async function getTokenMetrics(transcriptPath: string): Promise<TokenMetr
 
         const totalTokens = inputTokens + outputTokens + cachedTokens;
 
-        return { inputTokens, outputTokens, cachedTokens, totalTokens, contextLength };
+        return { inputTokens, outputTokens, cachedTokens, cacheReadTokens, cacheCreationTokens, totalTokens, contextLength };
     } catch {
-        return { inputTokens: 0, outputTokens: 0, cachedTokens: 0, totalTokens: 0, contextLength: 0 };
+        return { inputTokens: 0, outputTokens: 0, cachedTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, totalTokens: 0, contextLength: 0 };
     }
 }
 

src/utils/widget-manifest.ts

@@ -57,6 +57,7 @@ export const WIDGET_MANIFEST: WidgetManifestEntry[] = [
     { type: 'tokens-output', create: () => new widgets.TokensOutputWidget() },
     { type: 'tokens-cached', create: () => new widgets.TokensCachedWidget() },
     { type: 'tokens-total', create: () => new widgets.TokensTotalWidget() },
+    { type: 'cache-hit-rate', create: () => new widgets.CacheHitRateWidget() },
     { type: 'input-speed', create: () => new widgets.InputSpeedWidget() },
     { type: 'output-speed', create: () => new widgets.OutputSpeedWidget() },
     { type: 'total-speed', create: () => new widgets.TotalSpeedWidget() },

src/widgets/CacheHitRate.ts

@@ -0,0 +1,41 @@
+import type { RenderContext } from '../types/RenderContext';
+import type { Settings } from '../types/Settings';
+import type {
+    Widget,
+    WidgetEditorDisplay,
+    WidgetItem
+} from '../types/Widget';
+
+import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
+
+export class CacheHitRateWidget implements Widget {
+    getDefaultColor(): string { return 'green'; }
+    getDescription(): string { return 'Shows prompt-cache hit rate for the current session (matches Anthropic Console formula)'; }
+    getDisplayName(): string { return 'Cache Hit Rate'; }
+    getCategory(): string { return 'Tokens'; }
+    getEditorDisplay(item: WidgetItem): WidgetEditorDisplay {
+        return { displayText: this.getDisplayName() };
+    }
+
+    render(item: WidgetItem, context: RenderContext, settings: Settings): string | null {
+        if (context.isPreview) {
+            return formatRawOrLabeledValue(item, 'Cache: ', '87%');
+        }
+
+        const metrics = context.tokenMetrics;
+        if (!metrics)
+            return null;
+
+        const cacheRead = metrics.cacheReadTokens ?? 0;
+        const cacheCreation = metrics.cacheCreationTokens ?? 0;
+        const denom = cacheRead + cacheCreation + metrics.inputTokens;
+        if (denom === 0)
+            return null;
+
+        const pct = Math.round((cacheRead / denom) * 100);
+        return formatRawOrLabeledValue(item, 'Cache: ', `${pct}%`);
+    }
+
+    supportsRawValue(): boolean { return true; }
+    supportsColors(item: WidgetItem): boolean { return true; }
+}

src/widgets/__tests__/CacheHitRate.test.ts

@@ -0,0 +1,113 @@
+import {
+    describe,
+    expect,
+    it
+} from 'vitest';
+
+import type { RenderContext } from '../../types';
+import { DEFAULT_SETTINGS } from '../../types/Settings';
+import { CacheHitRateWidget } from '../CacheHitRate';
+
+const widget = new CacheHitRateWidget();
+const item = { id: 'chr', type: 'cache-hit-rate' } as const;
+
+describe('CacheHitRateWidget', () => {
+    it('returns null when no tokenMetrics', () => {
+        expect(widget.render(item, {}, DEFAULT_SETTINGS)).toBeNull();
+    });
+
+    it('returns null when denominator is zero', () => {
+        const context: RenderContext = {
+            tokenMetrics: {
+                inputTokens: 0,
+                outputTokens: 0,
+                cachedTokens: 0,
+                cacheReadTokens: 0,
+                cacheCreationTokens: 0,
+                totalTokens: 0,
+                contextLength: 0
+            }
+        };
+        expect(widget.render(item, context, DEFAULT_SETTINGS)).toBeNull();
+    });
+
+    it('returns 100% when only cache reads', () => {
+        const context: RenderContext = {
+            tokenMetrics: {
+                inputTokens: 0,
+                outputTokens: 50,
+                cachedTokens: 1000,
+                cacheReadTokens: 1000,
+                cacheCreationTokens: 0,
+                totalTokens: 1050,
+                contextLength: 1000
+            }
+        };
+        expect(widget.render(item, context, DEFAULT_SETTINGS)).toBe('Cache: 100%');
+    });
+
+    it('returns 0% when no cache reads', () => {
+        const context: RenderContext = {
+            tokenMetrics: {
+                inputTokens: 500,
+                outputTokens: 100,
+                cachedTokens: 200,
+                cacheReadTokens: 0,
+                cacheCreationTokens: 200,
+                totalTokens: 800,
+                contextLength: 700
+            }
+        };
+        expect(widget.render(item, context, DEFAULT_SETTINGS)).toBe('Cache: 0%');
+    });
+
+    it('computes rounded percentage from read/creation/input mix', () => {
+        // 700 / (700 + 200 + 100) = 70%
+        const context: RenderContext = {
+            tokenMetrics: {
+                inputTokens: 100,
+                outputTokens: 50,
+                cachedTokens: 900,
+                cacheReadTokens: 700,
+                cacheCreationTokens: 200,
+                totalTokens: 1050,
+                contextLength: 1000
+            }
+        };
+        expect(widget.render(item, context, DEFAULT_SETTINGS)).toBe('Cache: 70%');
+    });
+
+    it('treats missing cache fields as 0', () => {
+        const context: RenderContext = {
+            tokenMetrics: {
+                inputTokens: 500,
+                outputTokens: 100,
+                cachedTokens: 0,
+                totalTokens: 600,
+                contextLength: 500
+            }
+        };
+        expect(widget.render(item, context, DEFAULT_SETTINGS)).toBe('Cache: 0%');
+    });
+
+    it('returns raw value without label', () => {
+        const context: RenderContext = {
+            tokenMetrics: {
+                inputTokens: 100,
+                outputTokens: 0,
+                cachedTokens: 900,
+                cacheReadTokens: 700,
+                cacheCreationTokens: 200,
+                totalTokens: 1000,
+                contextLength: 1000
+            }
+        };
+        expect(widget.render({ ...item, rawValue: true }, context, DEFAULT_SETTINGS)).toBe('70%');
+    });
+
+    it('renders preview', () => {
+        const context: RenderContext = { isPreview: true };
+        expect(widget.render(item, context, DEFAULT_SETTINGS)).toBe('Cache: 87%');
+        expect(widget.render({ ...item, rawValue: true }, context, DEFAULT_SETTINGS)).toBe('87%');
+    });
+});

src/widgets/index.ts

@@ -29,6 +29,7 @@ export { TokensInputWidget } from './TokensInput';
 export { TokensOutputWidget } from './TokensOutput';
 export { TokensCachedWidget } from './TokensCached';
 export { TokensTotalWidget } from './TokensTotal';
+export { CacheHitRateWidget } from './CacheHitRate';
 export { ContextLengthWidget } from './ContextLength';
 export { ContextWindowWidget } from './ContextWindow';
 export { ContextPercentageWidget } from './ContextPercentage';