cache-clock

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, TurnStepInput, TurnUsage } from 'claude-code'
3
4import type { CacheLastStep, CacheWindow } from '../types'
5
6const TICK_MS = 10_000
7const MISS_BAND_MS = 3 * 60_000
8const SHORT_TTL_MS = 5 * 60_000
9
10const window = atom({ plugin: 'cache-clock', key: 'window' } as const, null)
11const last = atom({ plugin: 'cache-clock', key: 'last' } as const, null)
12
13const num = (v: unknown, fallback: number) =>
14  typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : fallback
15
16const mmss = (ms: number) => {
17  const s = Math.max(0, Math.round(ms / 1000))
18  const m = Math.floor(s / 60)
19  if (m > 60) return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m`
20  return m >= 10 ? `${m}m` : `${m}m${String(s % 60).padStart(2, '0')}s`
21}
22
23const bar = (fraction: number, cells = 12) => {
24  const lit = Math.max(0, Math.min(cells, Math.round(fraction * cells)))
25  // Block Elements render in every monospace font; ▮▯ fell back to tofu boxes.
26  return '█'.repeat(lit) + '░'.repeat(cells - lit)
27}
28
29
30type Config = { ttlMs: number; warnMs: number; missTokens: number }
31// Module-level: lost on a reload, which costs at worst one repeated toast.
32const mem: { warnedFor: number | null } = { warnedFor: null }
33
34async function refresh($: EngineInterface, cfg: Config) {
35  const { ttlMs, warnMs } = cfg
36  const now = await $.clock.now()
37  const w = await read($, window)
38  if (w === null) {
39    $.ui.status(undefined)
40    return
41  }
42  const remaining = ttlMs - (now - w.startedAt)
43  const l = await read($, last)
44  const missTag = l?.isMiss && now - l.at < MISS_BAND_MS ? ' · MISS' : ''
45
46  if (remaining <= 0) {
47    $.ui.status(`cache COLD (${mmss(-remaining)} past TTL)${missTag}`)
48  } else if (remaining <= warnMs) {
49    $.ui.status(`cache ${mmss(remaining)} left ⚠${missTag}`)
50    if (mem.warnedFor !== w.startedAt) {
51      mem.warnedFor = w.startedAt
52      $.ui.toast(`Prompt cache lapses in ${mmss(remaining)}. Any prompt resets the ${Math.round(ttlMs / 60_000)}m window.`, { timeoutMs: 8000 })
53    }
54  } else {
55    $.ui.status(`cache ${mmss(remaining)}${missTag}`)
56  }
57  // Coarse clock the band redraws from; one write per tick, not per ms.
58  if (now - w.now >= TICK_MS - 500) await update($, window, cur => (cur ? { ...cur, now } : cur))
59}
60
61// Why this request has no warm prefix to read, or undefined when it should have one.
62function coldReason(cfg: Config, e: TurnStepInput, at: number, previous: CacheWindow | null) {
63  if (previous === null) return 'first request'
64  if (at - previous.startedAt >= cfg.ttlMs) return 'TTL lapsed'
65  if (previous.rewritten) return 'compaction'
66  if (previous.model !== undefined && previous.model !== e.model) return 'model switch'
67  if (previous.effort !== e.effort) return 'effort switch'
68  return undefined
69}
70
71async function note(
72  $: EngineInterface,
73  cfg: Config,
74  usage: TurnUsage,
75  at: number,
76  previous: CacheWindow | null,
77  prevStep: CacheLastStep | null,
78  reason: string | undefined,
79) {
80  const { ttlMs, missTokens } = cfg
81  const read_ = usage.cache_read_input_tokens
82  const written = usage.cache_creation_input_tokens
83  // A miss is the cache failing to serve the prefix the last request left; a big paste on a small context reads all of it.
84  const served = prevStep ? prevStep.read + prevStep.written : written
85  const isFullWrite = written >= missTokens && read_ < served / 2
86  const isColdWrite = isFullWrite && reason !== undefined
87  const isMiss = isFullWrite && reason === undefined
88  const step: CacheLastStep = {
89    at, isMiss, isColdWrite, ...(isColdWrite ? { coldReason: reason } : {}),
90    read: read_, written, uncached: usage.input_tokens, model: usage.model,
91  }
92  await update($, last, () => step)
93  if (isMiss && previous) {
94    const elapsed = at - previous.startedAt
95    // Under 5m no TTL explains it, so the prefix itself changed.
96    const why = elapsed < SHORT_TTL_MS
97      ? 'the prompt prefix changed (CLAUDE.md, MCP tools or system prompt)'
98      : 'the TTL may have dropped to 5m, or the prompt prefix changed'
99    $.ui.toast(`Cache MISS ${mmss(elapsed)} after the last request, ${mmss(ttlMs - elapsed)} left on the clock: ${why}. Rewrote ${Math.round(written / 1000)}k tokens.`, { timeoutMs: 10_000 })
100  }
101}
102
103export const register: Register = (on, options) => {
104  const cfg: Config = {
105    ttlMs: num(options.ttlMinutes, 60) * 60_000,
106    warnMs: num(options.warnMinutes, 5) * 60_000,
107    missTokens: num(options.missTokens, 20_000),
108  }
109  const { ttlMs, warnMs } = cfg
110  let tick: { cancel: () => void } | null = null
111
112  on('session.start', async ($, e, next) => {
113    await $.command.register({
114      name: 'cache',
115      description: 'Prompt-cache window: time left, last request hit or miss, token counts',
116    })
117    tick?.cancel()
118    tick = $.clock.every(TICK_MS, () => { void refresh($, cfg) })
119    return next(e)
120  })
121
122  on('session.end', async ($, e, next) => {
123    // /clear and an in-session /resume go on in the same process with no session.start, so the clock keeps ticking.
124    if (e.reason === 'clear' || e.reason === 'resume') {
125      await update($, window, () => null)
126      await update($, last, () => null)
127    } else {
128      tick?.cancel()
129      tick = null
130    }
131    $.ui.status(undefined)
132    return next(e)
133  })
134
135  on('session.compact', async ($, e, next) => {
136    const result = await next(e)
137    // precompute installs nothing; the compaction that later uses it lands here again.
138    if (e.agentId === undefined && e.trigger !== 'precompute' && result.messages !== undefined) {
139      // Never let bookkeeping fail the compaction the engine already made.
140      try {
141        await update($, window, cur => (cur ? { ...cur, rewritten: true } : cur))
142      } catch { /* the next full write reads as a miss, nothing worse */ }
143    }
144    return result
145  })
146
147  on('turn.step', async function* ($, e, next) {
148    // A subagent's request has its own prefix; only main-thread requests touch the main cache.
149    const isMain = e.agentId === undefined
150    const startedAt = await $.clock.now()
151    const previous = isMain ? await read($, window) : null
152    const prevStep = isMain ? await read($, last) : null
153    const reason = coldReason(cfg, e, startedAt, previous)
154    if (isMain) {
155      await update($, window, () => ({
156        startedAt, now: startedAt, model: e.model, ...(e.effort !== undefined ? { effort: e.effort } : {}),
157      }))
158    }
159
160    const stream = next(e)
161    for await (const chunk of stream) {
162      if (isMain && chunk.kind === 'stop' && chunk.usage) {
163        await note($, cfg, chunk.usage, startedAt, previous, prevStep, reason)
164      }
165      yield chunk
166    }
167    if (isMain) void refresh($, cfg)
168    return stream.result
169  })
170
171  on('command.run', { command: 'cache' }, async $ => {
172    const now = await $.clock.now()
173    const w = await read($, window)
174    const l = await read($, last)
175    if (w === null) return { text: 'No model request yet this session; the cache clock starts on the first one.' }
176    const remaining = ttlMs - (now - w.startedAt)
177    const lines = [
178      remaining > 0
179        ? `Cache warm: ${mmss(remaining)} of ${Math.round(ttlMs / 60_000)}m left (TTL counts from the start of the last request).`
180        : `Cache cold: TTL passed ${mmss(-remaining)} ago. The next request rewrites the whole context at 2× input price.`,
181    ]
182    if (l) {
183      const kind = l.isMiss ? 'MISS' : l.isColdWrite ? `cold write (expected: ${l.coldReason ?? 'first request'})` : 'hit'
184      lines.push(
185        `Last request: ${kind} · read ${l.read.toLocaleString()} · wrote ${l.written.toLocaleString()} · uncached ${l.uncached.toLocaleString()} · ${l.model}`,
186      )
187    }
188    return { text: lines.join('\n') }
189  })
190
191  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
192    const w = await read($, window)
193    if (e.props.hasSurvey || w === null) return next(e)
194    const l = await read($, last)
195    const now = Math.max(w.now, l?.at ?? 0)
196    const remaining = ttlMs - (now - w.startedAt)
197    const showMiss = l?.isMiss === true && now - l.at < MISS_BAND_MS
198    const showWarn = remaining <= warnMs
199    if (!showMiss && !showWarn) return next(e)
200
201    const { Box, Text } = $.ui.resolve(e)
202    const color = remaining <= 0 ? 'error' : remaining <= warnMs / 2 ? 'error' : 'warning'
203    return (
204      <Box flexDirection="column">
205        {showWarn ? (
206          <Text color={color}>
207            {remaining > 0
208              ? `${bar(remaining / ttlMs)} cache lapses in ${mmss(remaining)} · any prompt resets the window`
209              : `cache COLD · next request pays a full context rewrite`}
210          </Text>
211        ) : null}
212        {showMiss && l ? (
213          <Text color="error">
214            cache MISS on last request · rewrote {Math.round(l.written / 1000)}k tokens, read {Math.round(l.read / 1000)}k
215          </Text>
216        ) : null}
217      </Box>
218    )
219  })
220}
221

1export type CacheWindow = {
2  // Start of the request that last read or wrote the cache; the TTL counts from here.
3  startedAt: number
4  // Coarse clock used to redraw the band; refreshed by the tick timer, not every ms.
5  now: number
6  // Model and effort that request ran under; a switch leaves the cached prefix behind.
7  model?: string
8  effort?: string | number
9  // Set when compaction rewrote the conversation under the cache; cleared by the next request.
10  rewritten?: boolean
11}
12
13export type CacheLastStep = {
14  at: number
15  isMiss: boolean
16  // A full write the window predicted (first request, TTL lapsed, compaction, model or effort switch); never a miss.
17  isColdWrite: boolean
18  coldReason?: string
19  read: number
20  written: number
21  uncached: number
22  model: string
23}
24
25declare module 'claude-code' {
26  interface PluginState {
27    'cache-clock': { window: CacheWindow | null; last: CacheLastStep | null }
28  }
29}
30