From 7d66e0c0f6e08a84972238b2c6b6d90553695f8d Mon Sep 17 00:00:00 2001 From: Eric Engberg Date: Wed, 14 Oct 2026 19:39:16 -0500 Subject: [PATCH 1/2] feat(widgets): add prompt cache miss widgets Claude Code 2.1.251+ reports the main conversation's prompt cache statistics in the status line payload (`prompt_cache`), the same figures `/usage` shows on its "Prompt cache (main)" line. A cache miss re-sends content the cache already held, which is what makes usage jump without anything else changing. Four new Cache widgets show them: - Cache Misses: misses out of the session's requests (`2/14`) - Last Cache Miss: how long ago the last miss was and its likely cause (`3m ago, tools changed (+2)`; causes need Claude Code 2.1.260+) - Cache Miss Tokens: tokens the misses wrote back to the cache (`310.2k`) - Cache If Cold: what the next request re-caches if the cache has gone cold by then (`45.0k`) They read only the payload: no transcript scan and no network. Without `prompt_cache` (older Claude Code, or before the session's first API response) they render nothing. Cache Misses and Cache Miss Tokens can hide while the session has no misses. The schema drops a `prompt_cache` field in an unexpected shape instead of rejecting the payload, so a future change to the object can't blank the status line. --- docs/USAGE.md | 2 + src/types/StatusJSON.ts | 37 +++- src/types/__tests__/StatusJSON.test.ts | 93 +++++++++ src/utils/widget-manifest.ts | 6 +- src/widgets/CacheIfCold.ts | 40 ++++ src/widgets/CacheMissTokens.ts | 53 +++++ src/widgets/CacheMisses.ts | 50 +++++ src/widgets/LastCacheMiss.ts | 41 ++++ .../__tests__/PromptCacheWidgets.test.ts | 196 ++++++++++++++++++ src/widgets/index.ts | 4 + .../shared/__tests__/prompt-cache.test.ts | 74 +++++++ src/widgets/shared/prompt-cache.ts | 81 ++++++++ 12 files changed, 675 insertions(+), 2 deletions(-) create mode 100644 src/widgets/CacheIfCold.ts create mode 100644 src/widgets/CacheMissTokens.ts create mode 100644 src/widgets/CacheMisses.ts create mode 100644 src/widgets/LastCacheMiss.ts create mode 100644 src/widgets/__tests__/PromptCacheWidgets.test.ts create mode 100644 src/widgets/shared/__tests__/prompt-cache.test.ts create mode 100644 src/widgets/shared/prompt-cache.ts diff --git a/docs/USAGE.md b/docs/USAGE.md index a60352bee..7a6428197 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -57,6 +57,7 @@ ccstatusline --version - **Tokens Input** / **Tokens Output** / **Tokens Cached** / **Tokens Total** - Show current-session token counts. Input/output prefer cumulative transcript metrics and fall back to `context_window.total_input_tokens` / `context_window.total_output_tokens` when transcript metrics are unavailable; cached/total use transcript metrics. - **Cache Hit Rate** / **Cache Read** / **Cache Write** - Show prompt-cache efficiency. Cache Hit Rate uses cache reads divided by cache reads plus cache writes; Cache Read and Cache Write include each value's share of prompt context. They default to the latest turn from `context_window.current_usage`, can switch to cumulative session totals, and can hide when empty. - **Cache Timer** - Estimate time remaining before the current prompt-cache entry expires. It shows `HOT` while a main-chain turn is active, then counts down from the latest assistant request with cache activity and becomes `COLD` just before expiry. Interrupts and local slash commands such as `/cost` end the working state without refreshing that cache anchor. The default TTL is 5 minutes; it can switch to 1 hour, hide when no cache anchor is available, and customize the glyph for each state. Because Claude Code transcripts expose cache token activity rather than the actual expiry timestamp, the countdown is best effort. +- **Cache Misses** / **Last Cache Miss** / **Cache Miss Tokens** / **Cache If Cold** - Show the prompt cache statistics Claude Code reports for the main conversation (Claude Code 2.1.251 or later), the same figures as the `Prompt cache (main)` line of `/usage`. Cache Misses shows the misses out of the session's requests (`2/14`); a miss is a request that re-processed content the cache already held, so rebuilds after a compaction don't count. Last Cache Miss shows when the last miss happened and its likely cause (`3m ago, tools changed (+2)`, `5m TTL expired`, `system prompt changed (+120 chars)`); causes need Claude Code 2.1.260 or later and read `cause unknown` when Claude Code identified none. Cache Miss Tokens shows the tokens the misses wrote back to the cache (`310.2k`), and Cache If Cold what the next request re-caches if the cache has gone cold by then (`45.0k`). They read only the status line payload, so they render nothing until the session's first API response; Last Cache Miss also stays empty until the first miss, and Cache If Cold right after a compaction until the next request. - **Input Speed** / **Output Speed** / **Total Speed** - Show session-average token throughput with an optional per-widget rolling window (`0-120` seconds; `0` = full-session average). - **Context Length** / **Context Window** / **Context %** / **Context % (usable)** / **Context Bar** - Show current context length, total context window size, used/remaining percentage, usable-window percentage, or a progress bar. The window size is taken from Claude Code's reported `context_window.context_window_size` when present, then from a model-name hint (e.g. a `[1m]` suffix), and finally from a fixed fallback. Set `CCSTATUSLINE_CONTEXT_SIZE_FALLBACK` to a positive integer to override that last-resort fallback (defaults to `200000`) — useful when an older Claude Code does not report the window size for a 1M-context model, so the bar would otherwise read against 200k. Immediately after `/compact`, transcript fallback uses the latest `compact_boundary.postTokens` value until a new main-chain turn reports the current size, so the widgets do not retain the pre-compaction context. - **Compaction Counter** - Show how many context compactions have been detected in the current session by scanning transcript compaction markers. It can render as icon plus number, text plus number, or number-only, and can hide while the count is zero. Two optional, independent per-item add-ons toggle extra detail: a trigger split (`↻ 3 (2 auto, 1 manual)`; a compaction whose trigger is missing or unrecognized is bucketed as `unknown`) and tokens reclaimed (`↻ 3 ↓887.0k`, each compaction's `preTokens - postTokens` floored at 0 and summed, shown only when greater than 0 — so very old transcripts predating the `postTokens` field display nothing). Its value selector can instead render the total count, one trigger count (`auto`, `manual`, or `unknown`), or reclaimed tokens as a standalone value; hide-when-zero applies to the selected value. @@ -346,6 +347,7 @@ Supported states by widget family: - **Extra Usage widgets**: `disabled` hides the `n/a` display when extra usage is off, `no-data` hides the error placeholder when usage data is unavailable - **Session / Weekly / Weekly Sonnet / Weekly Opus / Weekly Fable Usage**: `no-data` hides the error placeholder (`[No credentials]`, `[Timeout]`, `[Rate limited]`, `[API Error]`, `[Parse Error]`) when usage data is unavailable - **Cache widgets** (`Cache Hit Rate`, `Cache Read`, `Cache Write`, `Cache Timer`): `empty` hides the widget when there is no cache activity, and on Cache Timer when no cache anchor is available +- **Cache Misses / Cache Miss Tokens**: `zero` hides the widget while the session has no prompt cache misses - **Custom Text / Custom Symbol**: `merge-target-hidden` hides the item when the widget it is merged with renders nothing, so icon prefixes/suffixes disappear together with their widget In `settings.json`, the enabled states are stored as a comma-separated list in diff --git a/src/types/StatusJSON.ts b/src/types/StatusJSON.ts index 7100b8a7f..e7c9fae4b 100644 --- a/src/types/StatusJSON.ts +++ b/src/types/StatusJSON.ts @@ -29,6 +29,40 @@ const SpendLimitSchema = RateLimitPeriodSchema.extend({ export type RateLimitPeriod = z.infer; +// A field Claude Code sends in a shape this version doesn't know is dropped, +// so the rest of the payload (and the status line) still renders. +function tolerant(schema: T) { + return schema.nullable().optional().catch(undefined); +} + +// The likely cause of the last prompt cache miss (Claude Code 2.1.260+): cause +// names such as tools_changed, plus counts for some of them. +const LastMissCauseSchema = z.looseObject({ + causes: z.array(z.string()).catch([]), + tools_added: tolerant(CoercedNumberSchema), + tools_removed: tolerant(CoercedNumberSchema), + system_char_delta: tolerant(CoercedNumberSchema) +}); + +// Prompt cache statistics for the main conversation (Claude Code 2.1.251+). +// Absent until the session's first API response. Timestamps are epoch seconds. +const PromptCacheSchema = z.object({ + warm: tolerant(z.boolean()), + caching_observed: tolerant(z.boolean()), + ttl: tolerant(z.string()), + expires_at: tolerant(CoercedNumberSchema), + requests: tolerant(CoercedNumberSchema), + misses: tolerant(CoercedNumberSchema), + expected_rebuilds: tolerant(CoercedNumberSchema), + hit_ratio: tolerant(CoercedNumberSchema), + cache_write_tokens: tolerant(CoercedNumberSchema), + miss_recache_tokens: tolerant(CoercedNumberSchema), + last_miss_at: tolerant(CoercedNumberSchema), + last_miss_cause: tolerant(LastMissCauseSchema), + miss_causes: tolerant(z.record(z.string(), CoercedNumberSchema)), + recache_tokens_if_cold: tolerant(CoercedNumberSchema) +}); + export const StatusJSONSchema = z.looseObject({ hook_event_name: z.string().optional(), session_id: z.string().optional(), @@ -85,7 +119,8 @@ export const StatusJSONSchema = z.looseObject({ seven_day_sonnet: RateLimitPeriodSchema.nullable().optional(), seven_day_opus: RateLimitPeriodSchema.nullable().optional(), spend_limit: SpendLimitSchema.nullable().optional() - }).nullable().optional() + }).nullable().optional(), + prompt_cache: tolerant(PromptCacheSchema) }); export type StatusJSON = z.infer; diff --git a/src/types/__tests__/StatusJSON.test.ts b/src/types/__tests__/StatusJSON.test.ts index 93b5cc50d..748cfdeaf 100644 --- a/src/types/__tests__/StatusJSON.test.ts +++ b/src/types/__tests__/StatusJSON.test.ts @@ -171,4 +171,97 @@ describe('StatusJSONSchema numeric coercion', () => { expect(result.data.rate_limits?.spend_limit?.used_percentage).toBe(12); expect(result.data.rate_limits?.spend_limit?.used_usd).toBeUndefined(); }); + + it('parses prompt_cache with every documented field', () => { + const result = StatusJSONSchema.safeParse({ + prompt_cache: { + warm: true, + caching_observed: true, + ttl: '1h', + expires_at: 1738429200, + requests: 14, + misses: '2', + expected_rebuilds: 1, + hit_ratio: 0.91, + cache_write_tokens: 352000, + miss_recache_tokens: 310200, + last_miss_at: 1738425230, + last_miss_cause: { causes: ['tools_changed'], tools_added: 2, tools_removed: 0 }, + miss_causes: { tools_changed: 2 }, + recache_tokens_if_cold: 45000 + } + }); + + expect(result.success).toBe(true); + if (!result.success) { + return; + } + + expect(result.data.prompt_cache).toEqual({ + warm: true, + caching_observed: true, + ttl: '1h', + expires_at: 1738429200, + requests: 14, + misses: 2, + expected_rebuilds: 1, + hit_ratio: 0.91, + cache_write_tokens: 352000, + miss_recache_tokens: 310200, + last_miss_at: 1738425230, + last_miss_cause: { causes: ['tools_changed'], tools_added: 2, tools_removed: 0 }, + miss_causes: { tools_changed: 2 }, + recache_tokens_if_cold: 45000 + }); + }); + + it('accepts the nulls prompt_cache documents', () => { + const promptCache = { expires_at: null, hit_ratio: null, last_miss_at: null, last_miss_cause: null, recache_tokens_if_cold: null }; + const result = StatusJSONSchema.safeParse({ prompt_cache: promptCache }); + + expect(result.success).toBe(true); + if (!result.success) { + return; + } + + expect(result.data.prompt_cache?.last_miss_at).toBeNull(); + expect(result.data.prompt_cache?.last_miss_cause).toBeNull(); + }); + + // The status line keeps rendering when Claude Code sends a prompt_cache + // field in a shape this version doesn't know + it('drops a malformed prompt_cache field instead of rejecting the payload', () => { + const result = StatusJSONSchema.safeParse({ + model: { display_name: 'Opus' }, + prompt_cache: { + requests: 14, + misses: 'several', + last_miss_cause: 'tools_changed', + miss_causes: { tools_changed: 'two' } + } + }); + + expect(result.success).toBe(true); + if (!result.success) { + return; + } + + expect(result.data.model).toEqual({ display_name: 'Opus' }); + expect(result.data.prompt_cache?.requests).toBe(14); + expect(result.data.prompt_cache?.misses).toBeUndefined(); + expect(result.data.prompt_cache?.last_miss_cause).toBeUndefined(); + expect(result.data.prompt_cache?.miss_causes).toBeUndefined(); + }); + + it('drops a prompt_cache that is not an object instead of rejecting the payload', () => { + const result = StatusJSONSchema.safeParse({ model: { display_name: 'Opus' }, prompt_cache: 42 }); + + expect(result.success).toBe(true); + if (!result.success) { + return; + } + + expect(result.data.model).toEqual({ display_name: 'Opus' }); + expect(result.data.prompt_cache).toBeUndefined(); + }); }); diff --git a/src/utils/widget-manifest.ts b/src/utils/widget-manifest.ts index b2a753ffb..079510b66 100644 --- a/src/utils/widget-manifest.ts +++ b/src/utils/widget-manifest.ts @@ -108,7 +108,11 @@ export const WIDGET_MANIFEST: WidgetManifestEntry[] = [ { type: 'worktree-branch', create: () => new widgets.GitWorktreeBranchWidget() }, { type: 'worktree-original-branch', create: () => new widgets.GitWorktreeOriginalBranchWidget() }, { type: 'compaction-counter', create: () => new widgets.CompactionCounterWidget() }, - { type: 'cache-timer', create: () => new widgets.CacheTimerWidget() } + { type: 'cache-timer', create: () => new widgets.CacheTimerWidget() }, + { type: 'cache-misses', create: () => new widgets.CacheMissesWidget() }, + { type: 'last-cache-miss', create: () => new widgets.LastCacheMissWidget() }, + { type: 'cache-miss-tokens', create: () => new widgets.CacheMissTokensWidget() }, + { type: 'cache-if-cold', create: () => new widgets.CacheIfColdWidget() } ]; export const LAYOUT_WIDGET_MANIFEST: LayoutWidgetManifestEntry[] = [ diff --git a/src/widgets/CacheIfCold.ts b/src/widgets/CacheIfCold.ts new file mode 100644 index 000000000..375768ad5 --- /dev/null +++ b/src/widgets/CacheIfCold.ts @@ -0,0 +1,40 @@ +import type { RenderContext } from '../types/RenderContext'; +import type { Settings } from '../types/Settings'; +import type { + Widget, + WidgetEditorDisplay, + WidgetItem +} from '../types/Widget'; +import { formatTokens } from '../utils/format-tokens'; +import { resolveNumberFormat } from '../utils/number-format'; + +import { getPromptCache } from './shared/prompt-cache'; +import { formatRawOrLabeledValue } from './shared/raw-or-labeled'; + +const LABEL = 'If cold: '; + +// Claude Code leaves the figure null right after a compaction or a clearing of +// old tool results, until the next request records the conversation's new size +export class CacheIfColdWidget implements Widget { + getDefaultColor(): string { return 'brightCyan'; } + getDescription(): string { return 'Shows the tokens the next request re-caches if the prompt cache has gone cold by then'; } + getDisplayName(): string { return 'Cache If Cold'; } + getCategory(): string { return 'Cache'; } + getLabelPrefix(): string { return LABEL; } + getEditorDisplay(item: WidgetItem): WidgetEditorDisplay { + return { displayText: this.getDisplayName() }; + } + + render(item: WidgetItem, context: RenderContext, settings: Settings): string | null { + const tokens = getPromptCache(context)?.recache_tokens_if_cold; + if (typeof tokens !== 'number') { + return null; + } + + return formatRawOrLabeledValue(item, LABEL, formatTokens(tokens, resolveNumberFormat('token', item, settings))); + } + + supportsRawValue(): boolean { return true; } + supportsColors(item: WidgetItem): boolean { return true; } + supportsNumberFormat(): boolean { return true; } +} diff --git a/src/widgets/CacheMissTokens.ts b/src/widgets/CacheMissTokens.ts new file mode 100644 index 000000000..17bd6ba74 --- /dev/null +++ b/src/widgets/CacheMissTokens.ts @@ -0,0 +1,53 @@ +import type { RenderContext } from '../types/RenderContext'; +import type { Settings } from '../types/Settings'; +import type { + HideableState, + Widget, + WidgetEditorDisplay, + WidgetItem +} from '../types/Widget'; +import { formatTokens } from '../utils/format-tokens'; +import { resolveNumberFormat } from '../utils/number-format'; + +import { isHidden } from './shared/hideable'; +import { + NO_MISSES_HIDEABLE_STATE, + getPromptCache, + hasNoMisses +} from './shared/prompt-cache'; +import { formatRawOrLabeledValue } from './shared/raw-or-labeled'; + +const LABEL = 'Miss recache: '; + +export class CacheMissTokensWidget implements Widget { + getDefaultColor(): string { return 'yellow'; } + getDescription(): string { return 'Shows the tokens this session\'s prompt cache misses wrote back to the cache'; } + getDisplayName(): string { return 'Cache Miss Tokens'; } + getCategory(): string { return 'Cache'; } + getLabelPrefix(): string { return LABEL; } + getEditorDisplay(item: WidgetItem): WidgetEditorDisplay { + return { displayText: this.getDisplayName() }; + } + + getHideableStates(): HideableState[] { + return [NO_MISSES_HIDEABLE_STATE]; + } + + render(item: WidgetItem, context: RenderContext, settings: Settings): string | null { + const cache = getPromptCache(context); + if (typeof cache?.miss_recache_tokens !== 'number') { + return null; + } + + if (hasNoMisses(cache) && isHidden(item, NO_MISSES_HIDEABLE_STATE.key)) { + return null; + } + + const value = formatTokens(cache.miss_recache_tokens, resolveNumberFormat('token', item, settings)); + return formatRawOrLabeledValue(item, LABEL, value); + } + + supportsRawValue(): boolean { return true; } + supportsColors(item: WidgetItem): boolean { return true; } + supportsNumberFormat(): boolean { return true; } +} diff --git a/src/widgets/CacheMisses.ts b/src/widgets/CacheMisses.ts new file mode 100644 index 000000000..344f5fd3a --- /dev/null +++ b/src/widgets/CacheMisses.ts @@ -0,0 +1,50 @@ +import type { RenderContext } from '../types/RenderContext'; +import type { Settings } from '../types/Settings'; +import type { + HideableState, + Widget, + WidgetEditorDisplay, + WidgetItem +} from '../types/Widget'; + +import { isHidden } from './shared/hideable'; +import { + NO_MISSES_HIDEABLE_STATE, + getPromptCache, + hasNoMisses +} from './shared/prompt-cache'; +import { formatRawOrLabeledValue } from './shared/raw-or-labeled'; + +const LABEL = 'Misses: '; + +export class CacheMissesWidget implements Widget { + getDefaultColor(): string { return 'yellow'; } + getDescription(): string { return 'Shows prompt cache misses out of the session\'s requests, as Claude Code reports them'; } + getDisplayName(): string { return 'Cache Misses'; } + getCategory(): string { return 'Cache'; } + getLabelPrefix(): string { return LABEL; } + getEditorDisplay(item: WidgetItem): WidgetEditorDisplay { + return { displayText: this.getDisplayName() }; + } + + getHideableStates(): HideableState[] { + return [NO_MISSES_HIDEABLE_STATE]; + } + + render(item: WidgetItem, context: RenderContext, settings: Settings): string | null { + const cache = getPromptCache(context); + if (typeof cache?.misses !== 'number') { + return null; + } + + if (hasNoMisses(cache) && isHidden(item, NO_MISSES_HIDEABLE_STATE.key)) { + return null; + } + + const value = typeof cache.requests === 'number' ? `${cache.misses}/${cache.requests}` : `${cache.misses}`; + return formatRawOrLabeledValue(item, LABEL, value); + } + + supportsRawValue(): boolean { return true; } + supportsColors(item: WidgetItem): boolean { return true; } +} diff --git a/src/widgets/LastCacheMiss.ts b/src/widgets/LastCacheMiss.ts new file mode 100644 index 000000000..e87ed4745 --- /dev/null +++ b/src/widgets/LastCacheMiss.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 { + formatMissAge, + formatMissCause, + getPromptCache +} from './shared/prompt-cache'; +import { formatRawOrLabeledValue } from './shared/raw-or-labeled'; + +const LABEL = 'Last miss: '; + +// Renders nothing until the session's first miss, so it needs no hide option +export class LastCacheMissWidget implements Widget { + getDefaultColor(): string { return 'yellow'; } + getDescription(): string { return 'Shows when the last prompt cache miss happened and its likely cause, as Claude Code reports them'; } + getDisplayName(): string { return 'Last Cache Miss'; } + getCategory(): string { return 'Cache'; } + getLabelPrefix(): string { return LABEL; } + getEditorDisplay(item: WidgetItem): WidgetEditorDisplay { + return { displayText: this.getDisplayName() }; + } + + render(item: WidgetItem, context: RenderContext, settings: Settings): string | null { + const cache = getPromptCache(context); + if (typeof cache?.last_miss_at !== 'number') { + return null; + } + + const value = `${formatMissAge(cache.last_miss_at)}, ${formatMissCause(cache.last_miss_cause)}`; + return formatRawOrLabeledValue(item, LABEL, value); + } + + supportsRawValue(): boolean { return true; } + supportsColors(item: WidgetItem): boolean { return true; } +} diff --git a/src/widgets/__tests__/PromptCacheWidgets.test.ts b/src/widgets/__tests__/PromptCacheWidgets.test.ts new file mode 100644 index 000000000..3c2d37092 --- /dev/null +++ b/src/widgets/__tests__/PromptCacheWidgets.test.ts @@ -0,0 +1,196 @@ +import { + afterEach, + beforeEach, + describe, + expect, + it, + vi +} from 'vitest'; + +import type { RenderContext } from '../../types'; +import { DEFAULT_SETTINGS } from '../../types/Settings'; +import type { StatusJSON } from '../../types/StatusJSON'; +import type { WidgetItem } from '../../types/Widget'; +import { getWidget } from '../../utils/widgets'; +import { CacheIfColdWidget } from '../CacheIfCold'; +import { CacheMissTokensWidget } from '../CacheMissTokens'; +import { CacheMissesWidget } from '../CacheMisses'; +import { LastCacheMissWidget } from '../LastCacheMiss'; + +type PromptCache = NonNullable; + +// Three minutes after the docs' example miss +const NOW_SECONDS = 1738425410; + +// The docs' example session: 2 misses in 14 requests, the last from 2 added tools +const DOCS_EXAMPLE: PromptCache = { + warm: true, + caching_observed: true, + ttl: '1h', + expires_at: 1738429200, + requests: 14, + misses: 2, + expected_rebuilds: 1, + hit_ratio: 0.91, + cache_write_tokens: 352000, + miss_recache_tokens: 310200, + last_miss_at: 1738425230, + last_miss_cause: { causes: ['tools_changed'], tools_added: 2, tools_removed: 0 }, + miss_causes: { tools_changed: 2 }, + recache_tokens_if_cold: 45000 +}; + +const NO_MISSES: PromptCache = { + requests: 6, + misses: 0, + miss_recache_tokens: 0, + last_miss_at: null, + last_miss_cause: null, + recache_tokens_if_cold: 30000 +}; + +const item = (type: string, extra: Partial = {}): WidgetItem => ({ id: type, type, ...extra }); +const hideZero = (type: string): WidgetItem => item(type, { metadata: { hide: 'zero' } }); +const withCache = (promptCache: PromptCache): RenderContext => ({ data: { prompt_cache: promptCache } }); +const PREVIEW: RenderContext = { isPreview: true }; +const NO_CACHE: RenderContext = { data: {} }; + +describe('Prompt cache widgets', () => { + beforeEach(() => { + vi.spyOn(Date, 'now').mockReturnValue(NOW_SECONDS * 1000); + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + it('describes each widget in the Cache category', () => { + const widgets = [new CacheMissesWidget(), new LastCacheMissWidget(), new CacheMissTokensWidget(), new CacheIfColdWidget()]; + + expect(widgets.map(widget => widget.getDisplayName())).toEqual(['Cache Misses', 'Last Cache Miss', 'Cache Miss Tokens', 'Cache If Cold']); + expect(widgets.map(widget => widget.getLabelPrefix())).toEqual(['Misses: ', 'Last miss: ', 'Miss recache: ', 'If cold: ']); + for (const widget of widgets) { + expect(widget.getCategory()).toBe('Cache'); + expect(widget.supportsRawValue()).toBe(true); + } + }); + + it('registers each widget under its type', () => { + expect(getWidget('cache-misses')).toBeInstanceOf(CacheMissesWidget); + expect(getWidget('last-cache-miss')).toBeInstanceOf(LastCacheMissWidget); + expect(getWidget('cache-miss-tokens')).toBeInstanceOf(CacheMissTokensWidget); + expect(getWidget('cache-if-cold')).toBeInstanceOf(CacheIfColdWidget); + }); + + describe('Cache Misses', () => { + const widget = new CacheMissesWidget(); + const render = (widgetItem: WidgetItem, context: RenderContext) => widget.render(widgetItem, context, DEFAULT_SETTINGS); + + it('shows the misses out of the session\'s requests', () => { + expect(render(item('cache-misses'), withCache(DOCS_EXAMPLE))).toBe('Misses: 2/14'); + expect(render(item('cache-misses', { rawValue: true }), withCache(DOCS_EXAMPLE))).toBe('2/14'); + }); + + it('shows zero misses unless hidden', () => { + expect(render(item('cache-misses'), withCache(NO_MISSES))).toBe('Misses: 0/6'); + expect(render(hideZero('cache-misses'), withCache(NO_MISSES))).toBeNull(); + expect(render(hideZero('cache-misses'), withCache(DOCS_EXAMPLE))).toBe('Misses: 2/14'); + }); + + it('shows the count alone when the request count is missing', () => { + expect(render(item('cache-misses'), withCache({ misses: 2 }))).toBe('Misses: 2'); + }); + + it('renders nothing without a miss count', () => { + expect(render(item('cache-misses'), NO_CACHE)).toBeNull(); + expect(render(item('cache-misses'), withCache({ requests: 14 }))).toBeNull(); + }); + + it('previews the docs\' example', () => { + expect(render(item('cache-misses'), PREVIEW)).toBe('Misses: 2/14'); + }); + + it('can hide while the session has no misses', () => { + expect(widget.getHideableStates()).toEqual([{ key: 'zero', label: 'when there are no misses' }]); + }); + }); + + describe('Last Cache Miss', () => { + const widget = new LastCacheMissWidget(); + const render = (widgetItem: WidgetItem, context: RenderContext) => widget.render(widgetItem, context, DEFAULT_SETTINGS); + + it('shows how long ago the last miss was and its likely cause', () => { + expect(render(item('last-cache-miss'), withCache(DOCS_EXAMPLE))).toBe('Last miss: 3m ago, tools changed (+2)'); + expect(render(item('last-cache-miss', { rawValue: true }), withCache(DOCS_EXAMPLE))).toBe('3m ago, tools changed (+2)'); + }); + + it('lists several causes', () => { + const cache = { ...DOCS_EXAMPLE, last_miss_cause: { causes: ['system_prompt_changed', 'ttl_expired_5m'], system_char_delta: 120 } }; + + expect(render(item('last-cache-miss'), withCache(cache))).toBe('Last miss: 3m ago, system prompt changed (+120 chars), 5m TTL expired'); + }); + + it('says the cause is unknown when Claude Code identified none', () => { + expect(render(item('last-cache-miss'), withCache({ ...DOCS_EXAMPLE, last_miss_cause: null }))).toBe('Last miss: 3m ago, cause unknown'); + }); + + it('renders nothing before the first miss', () => { + expect(render(item('last-cache-miss'), withCache(NO_MISSES))).toBeNull(); + expect(render(item('last-cache-miss'), NO_CACHE)).toBeNull(); + }); + + it('previews the docs\' example', () => { + expect(render(item('last-cache-miss'), PREVIEW)).toBe('Last miss: 3m ago, tools changed (+2)'); + }); + }); + + describe('Cache Miss Tokens', () => { + const widget = new CacheMissTokensWidget(); + const render = (widgetItem: WidgetItem, context: RenderContext) => widget.render(widgetItem, context, DEFAULT_SETTINGS); + + it('shows the tokens the misses wrote back to the cache', () => { + expect(render(item('cache-miss-tokens'), withCache(DOCS_EXAMPLE))).toBe('Miss recache: 310.2k'); + expect(render(item('cache-miss-tokens', { rawValue: true }), withCache(DOCS_EXAMPLE))).toBe('310.2k'); + }); + + it('applies the token number format', () => { + expect(render(item('cache-miss-tokens', { numberFormat: { style: 'whole' } }), withCache(DOCS_EXAMPLE))).toBe('Miss recache: 310k'); + }); + + it('shows zero unless hidden while the session has no misses', () => { + expect(render(item('cache-miss-tokens'), withCache(NO_MISSES))).toBe('Miss recache: 0'); + expect(render(hideZero('cache-miss-tokens'), withCache(NO_MISSES))).toBeNull(); + expect(widget.getHideableStates()).toEqual([{ key: 'zero', label: 'when there are no misses' }]); + }); + + it('renders nothing without the token count', () => { + expect(render(item('cache-miss-tokens'), NO_CACHE)).toBeNull(); + expect(render(item('cache-miss-tokens'), withCache({ misses: 2 }))).toBeNull(); + }); + + it('previews the docs\' example', () => { + expect(render(item('cache-miss-tokens'), PREVIEW)).toBe('Miss recache: 310.2k'); + }); + }); + + describe('Cache If Cold', () => { + const widget = new CacheIfColdWidget(); + const render = (widgetItem: WidgetItem, context: RenderContext) => widget.render(widgetItem, context, DEFAULT_SETTINGS); + + it('shows what the next request re-caches if the cache has gone cold', () => { + expect(render(item('cache-if-cold'), withCache(DOCS_EXAMPLE))).toBe('If cold: 45.0k'); + expect(render(item('cache-if-cold', { rawValue: true }), withCache(DOCS_EXAMPLE))).toBe('45.0k'); + expect(render(item('cache-if-cold', { numberFormat: { style: 'whole' } }), withCache(DOCS_EXAMPLE))).toBe('If cold: 45k'); + }); + + // Null right after a compaction, until the next request + it('renders nothing while Claude Code has no figure', () => { + expect(render(item('cache-if-cold'), withCache({ ...DOCS_EXAMPLE, recache_tokens_if_cold: null }))).toBeNull(); + expect(render(item('cache-if-cold'), NO_CACHE)).toBeNull(); + }); + + it('previews the docs\' example', () => { + expect(render(item('cache-if-cold'), PREVIEW)).toBe('If cold: 45.0k'); + }); + }); +}); diff --git a/src/widgets/index.ts b/src/widgets/index.ts index 30bcd816d..d2ac7b289 100644 --- a/src/widgets/index.ts +++ b/src/widgets/index.ts @@ -90,3 +90,7 @@ export { SandboxStatusWidget } from './SandboxStatus'; export { VoiceStatusWidget } from './VoiceStatus'; export { RemoteControlStatusWidget } from './RemoteControlStatus'; export { CacheTimerWidget } from './CacheTimer'; +export { CacheMissesWidget } from './CacheMisses'; +export { LastCacheMissWidget } from './LastCacheMiss'; +export { CacheMissTokensWidget } from './CacheMissTokens'; +export { CacheIfColdWidget } from './CacheIfCold'; diff --git a/src/widgets/shared/__tests__/prompt-cache.test.ts b/src/widgets/shared/__tests__/prompt-cache.test.ts new file mode 100644 index 000000000..85a70bec4 --- /dev/null +++ b/src/widgets/shared/__tests__/prompt-cache.test.ts @@ -0,0 +1,74 @@ +import { + describe, + expect, + it +} from 'vitest'; + +import { + formatMissAge, + formatMissCause, + getPromptCache +} from '../prompt-cache'; + +describe('formatMissCause', () => { + it('names changed tools with how many were added and removed, leaving out zeros', () => { + expect(formatMissCause({ causes: ['tools_changed'], tools_added: 2, tools_removed: 0 })).toBe('tools changed (+2)'); + expect(formatMissCause({ causes: ['tools_changed'], tools_added: 0, tools_removed: 3 })).toBe('tools changed (−3)'); + expect(formatMissCause({ causes: ['tools_changed'], tools_added: 2, tools_removed: 1 })).toBe('tools changed (+2, −1)'); + expect(formatMissCause({ causes: ['tools_changed'] })).toBe('tools changed'); + }); + + it('gives the system prompt\'s change in length with its sign', () => { + expect(formatMissCause({ causes: ['system_prompt_changed'], system_char_delta: 120 })).toBe('system prompt changed (+120 chars)'); + expect(formatMissCause({ causes: ['system_prompt_changed'], system_char_delta: -45 })).toBe('system prompt changed (−45 chars)'); + expect(formatMissCause({ causes: ['system_prompt_changed'], system_char_delta: 0 })).toBe('system prompt changed'); + expect(formatMissCause({ causes: ['system_prompt_changed'] })).toBe('system prompt changed'); + }); + + it('names an expired TTL by its lifetime', () => { + expect(formatMissCause({ causes: ['ttl_expired_5m'] })).toBe('5m TTL expired'); + expect(formatMissCause({ causes: ['ttl_expired_1h'] })).toBe('1h TTL expired'); + }); + + it('reads the server-side cause and causes it doesn\'t know as words', () => { + expect(formatMissCause({ causes: ['likely_server_side'] })).toBe('likely server side'); + expect(formatMissCause({ causes: ['model_switched'] })).toBe('model switched'); + }); + + it('joins several causes', () => { + expect(formatMissCause({ causes: ['tools_changed', 'ttl_expired_5m'], tools_added: 1 })).toBe('tools changed (+1), 5m TTL expired'); + }); + + it('says the cause is unknown when Claude Code identified none', () => { + expect(formatMissCause(null)).toBe('cause unknown'); + expect(formatMissCause(undefined)).toBe('cause unknown'); + expect(formatMissCause({ causes: [] })).toBe('cause unknown'); + }); +}); + +describe('formatMissAge', () => { + // Three minutes after a miss at 1738425230 + const nowMs = 1738425410 * 1000; + + it('gives the time since the miss compactly', () => { + expect(formatMissAge(1738425230, nowMs)).toBe('3m ago'); + expect(formatMissAge(1738425230 - 3600, nowMs)).toBe('1h3m ago'); + }); + + it('says just now within a minute, and for a miss stamped ahead of the clock', () => { + expect(formatMissAge(1738425400, nowMs)).toBe('just now'); + expect(formatMissAge(1738425500, nowMs)).toBe('just now'); + }); +}); + +describe('getPromptCache', () => { + it('reads prompt_cache from the status line payload', () => { + expect(getPromptCache({ data: { prompt_cache: { requests: 14, misses: 2 } } })).toEqual({ requests: 14, misses: 2 }); + }); + + it('returns null before Claude Code reports one', () => { + expect(getPromptCache({})).toBeNull(); + expect(getPromptCache({ data: {} })).toBeNull(); + expect(getPromptCache({ data: { prompt_cache: null } })).toBeNull(); + }); +}); diff --git a/src/widgets/shared/prompt-cache.ts b/src/widgets/shared/prompt-cache.ts new file mode 100644 index 000000000..e5301989f --- /dev/null +++ b/src/widgets/shared/prompt-cache.ts @@ -0,0 +1,81 @@ +import type { RenderContext } from '../../types/RenderContext'; +import type { StatusJSON } from '../../types/StatusJSON'; +import type { HideableState } from '../../types/Widget'; +import { formatUsageDuration } from '../../utils/usage-windows'; + +// Claude Code's prompt cache statistics for the main conversation, from the +// status line payload (Claude Code 2.1.251+). The cache miss widgets read only +// this: no transcript scan and no network. +export type PromptCache = NonNullable; +type LastMissCause = NonNullable; + +export const NO_MISSES_HIDEABLE_STATE: HideableState = { key: 'zero', label: 'when there are no misses' }; + +// The documentation's example session, for the TUI preview: 2 misses in 14 +// requests, the last 3 minutes ago because 2 tools were added +function getPreviewPromptCache(nowMs: number): PromptCache { + return { + requests: 14, + misses: 2, + miss_recache_tokens: 310200, + last_miss_at: Math.floor(nowMs / 1000) - 3 * 60, + last_miss_cause: { causes: ['tools_changed'], tools_added: 2, tools_removed: 0 }, + recache_tokens_if_cold: 45000 + }; +} + +export function getPromptCache(context: RenderContext): PromptCache | null { + if (context.isPreview) { + return getPreviewPromptCache(Date.now()); + } + + return context.data?.prompt_cache ?? null; +} + +export function hasNoMisses(cache: PromptCache): boolean { + return cache.misses === 0; +} + +const MINUS = '−'; + +function formatSigned(value: number): string { + return value < 0 ? `${MINUS}${Math.abs(value)}` : `+${value}`; +} + +function formatCause(name: string, details: LastMissCause): string { + if (name === 'tools_changed') { + const counts = [ + details.tools_added ? `+${details.tools_added}` : null, + details.tools_removed ? `${MINUS}${details.tools_removed}` : null + ].filter(count => count !== null); + return counts.length > 0 ? `tools changed (${counts.join(', ')})` : 'tools changed'; + } + + if (name === 'system_prompt_changed') { + const delta = details.system_char_delta; + return delta ? `system prompt changed (${formatSigned(delta)} chars)` : 'system prompt changed'; + } + + const ttl = /^ttl_expired_(.+)$/.exec(name); + if (ttl) { + return `${ttl[1]} TTL expired`; + } + + // likely_server_side and any cause a later Claude Code adds + return name.replaceAll('_', ' '); +} + +// Claude Code leaves last_miss_cause null when it couldn't identify a cause, +// and older versions (before 2.1.260) don't send it at all +export function formatMissCause(cause: LastMissCause | null | undefined): string { + if (!cause || cause.causes.length === 0) { + return 'cause unknown'; + } + + return cause.causes.map(name => formatCause(name, cause)).join(', '); +} + +export function formatMissAge(lastMissAtSeconds: number, nowMs = Date.now()): string { + const ageMs = nowMs - lastMissAtSeconds * 1000; + return ageMs < 60 * 1000 ? 'just now' : `${formatUsageDuration(ageMs, true)} ago`; +} From d996781a40901ef2410d7d959e3f1085a6ab941f Mon Sep 17 00:00:00 2001 From: Matthew Breedlove Date: Fri, 30 Oct 2026 18:57:07 -0400 Subject: [PATCH 2/2] fix(widgets): preserve Node 14 compatibility in cache cause formatting --- src/widgets/shared/prompt-cache.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/widgets/shared/prompt-cache.ts b/src/widgets/shared/prompt-cache.ts index e5301989f..644b861d1 100644 --- a/src/widgets/shared/prompt-cache.ts +++ b/src/widgets/shared/prompt-cache.ts @@ -62,7 +62,7 @@ function formatCause(name: string, details: LastMissCause): string { } // likely_server_side and any cause a later Claude Code adds - return name.replaceAll('_', ' '); + return name.replace(/_/g, ' '); } // Claude Code leaves last_miss_cause null when it couldn't identify a cause,