diff --git a/docs/USAGE.md b/docs/USAGE.md index 78b0dc451..58aacbf73 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -58,6 +58,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** - Show time remaining before the current prompt-cache entry expires. When Claude Code provides usable `prompt_cache` data, the widget counts down to `expires_at` or shows `COLD` when `warm` is false. The reported `ttl` (`5m` or `1h`) controls the fresh/draining/urgent glyph thresholds. This reported state takes precedence even during a turn, so the Working glyph (`🔥 HOT`) is used only in the transcript fallback. Without usable reported state (including `caching_observed: false`), the widget shows `HOT` while a main-chain turn is active, then estimates expiry from the latest assistant request with cache activity. Interrupts and local slash commands such as `/cost` end that working state without refreshing the cache anchor. The `t` setting selects a 5-minute or 1-hour TTL for this fallback countdown; it also supplies glyph thresholds when a reported expiry has no recognized TTL. Each state's glyph can be customized, and the widget can hide when neither reported state nor a transcript cache anchor is available. +- **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). Token totals and speed metrics count repeated content-block records with the same response ID once, including interleaved records. - **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. When Claude Code omits a percentage, the percentage calculated from its current usage counts input, cache-read, and cache-write tokens, excluding output tokens until a later turn reads them as input. Reported percentages retain precedence. 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. @@ -372,6 +373,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 - **Block / 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 neither usable reported cache state nor a transcript 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 41a169e8d..e53632707 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,14 +119,7 @@ export const StatusJSONSchema = z.looseObject({ // Claude Code reports the live prompt-cache state, including the real // expiry timestamp, so consumers do not have to infer it from transcript // timings. Absent on older Claude Code versions. - prompt_cache: z.object({ - warm: z.boolean().nullable().optional(), - caching_observed: z.boolean().nullable().optional(), - ttl: z.string().nullable().optional(), - expires_at: CoercedNumberSchema.nullable().optional(), // Unix epoch seconds - hit_ratio: CoercedNumberSchema.nullable().optional(), - recache_tokens_if_cold: CoercedNumberSchema.nullable().optional() - }).nullable().optional(), + prompt_cache: tolerant(PromptCacheSchema), rate_limits: z.object({ five_hour: RateLimitPeriodSchema.optional(), seven_day: RateLimitPeriodSchema.optional(), diff --git a/src/types/__tests__/StatusJSON.test.ts b/src/types/__tests__/StatusJSON.test.ts index 546f6b329..912a4ad49 100644 --- a/src/types/__tests__/StatusJSON.test.ts +++ b/src/types/__tests__/StatusJSON.test.ts @@ -232,4 +232,97 @@ describe('StatusJSONSchema numeric coercion', () => { expect(result.data.fast_mode).toBeUndefined(); expect(result.data.model).toEqual({ id: 'claude-opus-4-6' }); }); + + 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 8c0967608..8ceb8bd7a 100644 --- a/src/utils/widget-manifest.ts +++ b/src/utils/widget-manifest.ts @@ -112,7 +112,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 64bae3312..b19a9280a 100644 --- a/src/widgets/index.ts +++ b/src/widgets/index.ts @@ -94,3 +94,7 @@ export { VoiceStatusWidget } from './VoiceStatus'; export { FastModeWidget } from './FastMode'; 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..644b861d1 --- /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.replace(/_/g, ' '); +} + +// 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`; +}