cache-timer

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, TurnUsage } from 'claude-code'
3
4import type { LastResponse, Ttl } from '../types'
5
6const lastResponse = atom({ plugin: 'cache-timer', key: 'last' } as const, null)
7const learnedTtl = atom({ plugin: 'cache-timer', key: 'learnedTtl' } as const, '1h')
8
9const MINUTE = 60_000
10const TTL_MS: Record<Ttl, number> = { '5m': 5 * MINUTE, '1h': 60 * MINUTE }
11// A request this close past five minutes may still have caught a 5m entry.
12const SLACK_MS = 15_000
13
14const label = (seconds: number): string => {
15  if (seconds <= 0) {
16    return 'Cache cold'
17  }
18  const mm = String(Math.floor(seconds / 60)).padStart(2, '0')
19  const ss = String(seconds % 60).padStart(2, '0')
20
21  return `Cache ${mm}:${ss}`
22}
23
24// What one main-thread response says about the lifetime: only a request sent
25// 5 to 60 minutes after the previous one, on the same model, tells 5m from 1h.
26const infer = (idleMs: number, usage: TurnUsage): Ttl | null => {
27  const isTelling = idleMs > TTL_MS['5m'] + SLACK_MS && idleMs < TTL_MS['1h']
28  if (!isTelling) {
29    return null
30  }
31  if (usage.cache_read_input_tokens > 0) {
32    return '1h'
33  }
34
35  return usage.cache_creation_input_tokens > 0 ? '5m' : null
36}
37
38async function shown($: EngineInterface, fixedTtl: Ttl | null): Promise<string | null> {
39  const last = await read($, lastResponse)
40  if (last === null) {
41    return null
42  }
43  const ttl = fixedTtl ?? (await read($, learnedTtl))
44  // whole wall-clock seconds, so the label steps once at each redraw (beat) however late its timer fires
45  const seconds = Math.floor((last.at + TTL_MS[ttl]) / 1000) - Math.floor((await $.clock.now()) / 1000)
46
47  return label(seconds)
48}
49
50// Redraws just after each wall-clock second. Every redraw makes the desktop
51// show the other plugins' pictures afresh; plan-progress draws its band on
52// the same second, so the screen changes once a second, not twice. One chain
53// per module, however often the session starts.
54let isBeating = false
55function beat($: EngineInterface, now: number): void {
56  isBeating = true
57  $.clock.after(1000 - (now % 1000) + 25, async () => {
58    $.ui.invalidate('ui.render')
59    beat($, await $.clock.now())
60  })
61}
62
63export const register: Register = (on, options) => {
64  const fixedTtl: Ttl | null = options.ttl === '1h' || options.ttl === '5m' ? options.ttl : null
65
66  on('session.start', async ($, e, next) => {
67    const started = await next(e)
68    if (!isBeating) {
69      beat($, await $.clock.now())
70    }
71
72    return started
73  })
74
75  // A dim label at the head of the footer's mode chip, left of the model. A
76  // tree of its own: the desktop draws the chip from the props it holds, so a
77  // rewritten `modes` never reaches its screen; the status line would prefix
78  // the plugin's name.
79  on('ui.render', { component: 'SessionMode' }, async ($, e, next) => {
80    const text = await shown($, fixedTtl)
81    if (text === null) {
82      return next(e)
83    }
84    const { Box, Text } = $.ui.resolve(e)
85    // other mods add to the chip beneath us; keep what they drew
86    const below = await next(e)
87
88    return (
89      <Box flexDirection="row" alignItems="center" gap={1}>
90        <Text dimColor>{text}</Text>
91        {below}
92      </Box>
93    )
94  })
95
96  // A resumed transcript's cache is as old as its last response.
97  on('classic.SessionStart', async ($, e, next) => {
98    if (e.seconds_since_last_response !== undefined) {
99      const resumed: LastResponse = { at: (await $.clock.now()) - e.seconds_since_last_response * 1000, model: null }
100      await update($, lastResponse, () => resumed)
101      $.ui.invalidate('ui.render')
102    }
103
104    return next(e)
105  })
106
107  // The one place the engine names the lifetime outright.
108  on('classic.PostModelSwitch', async ($, e, next) => {
109    await update($, learnedTtl, () => e.cache_ttl)
110    $.ui.invalidate('ui.render')
111
112    return next(e)
113  })
114
115  on('turn.step', async function* ($, e, next) {
116    const sentAt = await $.clock.now()
117    const result = yield* next(e)
118
119    // Subagents keep caches of their own; only the main thread's is timed.
120    if (e.agentId !== undefined || result.usage === null) {
121      return result
122    }
123    const previous = await read($, lastResponse)
124    if (previous !== null && previous.model === result.usage.model) {
125      const seen = infer(sentAt - previous.at, result.usage)
126      if (seen !== null) {
127        await update($, learnedTtl, () => seen)
128      }
129    }
130    const last: LastResponse = { at: sentAt, model: result.usage.model }
131    await update($, lastResponse, () => last)
132    $.ui.invalidate('ui.render')
133
134    return result
135  })
136}
137

1export type Ttl = '5m' | '1h'
2
3/** The main thread's last request that got a response. */
4export type LastResponse = {
5  /** When it was sent, ms since the epoch. */
6  at: number
7  /** The model that answered, null when unknown (a resumed session); a different one starts a cache of its own. */
8  model: string | null
9}
10
11declare module 'claude-code' {
12  interface PluginState {
13    'cache-timer': {
14      last: LastResponse | null
15      /** The lifetime `auto` has settled on so far. */
16      learnedTtl: Ttl
17    }
18  }
19}
20