jr-cache-clock

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import { hitRateOf, mmss, remaining } from './cache'
5import { colorAt } from './jr/gradient'
6
7const COUNTDOWN = ['#ef4565', '#ff8c42', '#f4d35e', '#2cb67d']
8const clock = atom({ plugin: 'jr-cache-clock', key: 'clock' } as const, null)
9// Hidden until the person asks for it: the toast before the cache goes cold is enough by default.
10const bandHidden = atom({ plugin: 'jr-cache-clock', key: 'isBandHidden' } as const, true)
11const commands = { isRegistered: false }
12const band = { isLoaded: false }
13
14async function ensureCommand($: EngineInterface) {
15  if (commands.isRegistered) return
16  commands.isRegistered = true
17  await $.command.register({ name: 'jrcache', description: 'Show or hide the cache countdown (hidden by default): /jrcache toggles, /jrcache on or off' })
18}
19
20/** Reads the saved choice once per load of the mod; outside a drawing, which cannot write state. */
21async function loadBand($: EngineInterface) {
22  if (band.isLoaded) return
23  band.isLoaded = true
24  if ((await $.store.get('isBandHidden')) === false) await update($, bandHidden, () => false)
25}
26
27/** True while the band is hidden (until asked for): one choice for every session. */
28async function isBandHidden($: EngineInterface) {
29  await loadBand($)
30  return read($, bandHidden)
31}
32
33const TICK_MS = 1000
34const WARN_MS = 30_000
35
36const live: { isTicking: boolean; warnedFor: number | null; ttlMin: number; warn: boolean } = { isTicking: false, warnedFor: null, ttlMin: 5, warn: true }
37
38async function tick($: EngineInterface) {
39  const now = await $.clock.now()
40  const c = await read($, clock)
41  const lastAt = c?.lastAt ?? null
42  const left = remaining(lastAt, now, live.ttlMin)
43  // Redraw while warm, and once more as it goes cold.
44  if (left > 0 || (c && remaining(lastAt, c.now, live.ttlMin) > 0)) await update($, clock, () => ({ lastAt, now, hitRate: c?.hitRate ?? null }))
45  if (live.warn && lastAt !== null && left > 0 && left <= WARN_MS && live.warnedFor !== lastAt) {
46    live.warnedFor = lastAt
47    $.ui.toast(`jr cache · cache goes cold in ${Math.ceil(left / 1000)} s`)
48  }
49}
50
51async function ensureTicking($: EngineInterface) {
52  if (live.isTicking) return
53  live.isTicking = true
54  const now = await $.clock.now()
55  await update($, clock, c => c ?? { lastAt: null, now, hitRate: null })
56  $.clock.every(TICK_MS, () => {
57    void tick($)
58  })
59}
60
61export const register: Register = (on, options) => {
62  live.ttlMin = Number(options.ttlMinutes ?? 5) || 5
63  live.warn = options.warnBeforeExpiry !== false
64
65  on('session.start', async ($, e, next) => {
66    const started = await next(e)
67    await ensureCommand($)
68    await loadBand($)
69    await ensureTicking($)
70    return started
71  })
72
73  on('turn.complete', async ($, e, next) => {
74    const done = await next(e)
75    if (e.agentId !== undefined) return done
76    await ensureTicking($)
77    const now = await $.clock.now()
78    const hitRate = hitRateOf((e as unknown as { usage?: Parameters<typeof hitRateOf>[0] }).usage)
79    await update($, clock, c => ({ lastAt: now, now, hitRate: hitRate ?? c?.hitRate ?? null }))
80    return done
81  })
82
83  on('command.run', { command: 'jrcache' }, async ($, e) => {
84    const arg = e.args.trim().toLowerCase()
85    await loadBand($)
86    const hide = arg === 'off' || arg === 'hide' ? true : arg === 'on' || arg === 'show' ? false : arg === '' ? !(await isBandHidden($)) : null
87    if (hide === null) return { text: 'jr cache · usage: /jrcache toggles the band, /jrcache on or off' }
88    await $.store.set('isBandHidden', hide)
89    await update($, bandHidden, () => hide)
90    return { text: hide ? 'jr cache · hidden (/jrcache to bring it back); the toast before it goes cold stays' : 'jr cache · shown above the prompt (/jrcache to hide it)' }
91  })
92
93  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
94    const below = await next(e)
95    const c = await read($, clock)
96    if (!live.isTicking) {
97      $.clock.after(0, () => {
98        void ensureTicking($)
99      })
100    }
101    if (!commands.isRegistered || !band.isLoaded) {
102      $.clock.after(0, () => {
103        void ensureCommand($)
104        void loadBand($)
105      })
106    }
107    if (await read($, bandHidden)) return below
108    if (!c || c.lastAt === null || e.props.hasSurvey) return below
109    const { Box, Text } = $.ui.resolve(e)
110    const left = remaining(c.lastAt, c.now, live.ttlMin)
111    // One quiet row on the right: the countdown goes green to red as the cache ages.
112    return (
113      <Box flexDirection="column">
114        <Box justifyContent="flex-end">
115          <Text wrap="truncate-end">
116            <Text dimColor>{'cache '}</Text>
117            {left > 0 ? <Text color={colorAt(COUNTDOWN, left / (live.ttlMin * 60_000))}>{mmss(left)}</Text> : <Text color="#ff8c42">{'cold'}</Text>}
118            {c.hitRate !== null && <Text dimColor>{` · hit ${Math.round(c.hitRate * 100)}%`}</Text>}
119          </Text>
120        </Box>
121        {below}
122      </Box>
123    )
124  })
125}
126

1/** Milliseconds of cache life left, or 0 once cold (or before any response). */
2export const remaining = (lastAt: number | null, now: number, ttlMin: number) =>
3  lastAt === null ? 0 : Math.max(0, lastAt + ttlMin * 60_000 - now)
4
5/** "3:41" */
6export const mmss = (ms: number) => {
7  const s = Math.ceil(ms / 1000)
8  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`
9}
10
11type Usage = { input_tokens: number; cache_read_input_tokens: number; cache_creation_input_tokens: number }
12
13/** Share of the input served from the cache. */
14export const hitRateOf = (usage: Usage | undefined) => {
15  if (!usage) return null
16  const total = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens
17  return total > 0 ? usage.cache_read_input_tokens / total : null
18}
19

1// Shared look of every jr mod: one palette, gradients drawn one cell at a time.
2// Synced into each plugin's hooks/jr/ by scripts/sync-shared.sh: edit it here only.
3
4export type Rgb = readonly [number, number, number]
5
6const hexToRgb = (hex: string): Rgb => {
7  const n = Number.parseInt(hex.replace('#', ''), 16)
8  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
9}
10
11const rgbToHex = ([r, g, b]: Rgb) =>
12  `#${[r, g, b].map(v => Math.round(v).toString(16).padStart(2, '0')).join('')}`
13
14export const GRADIENTS = {
15  // The jr signature: violet to pink to amber.
16  brand: ['#7f5af0', '#ff5ca8', '#ffb86b'],
17  // Calm to alarm, for gauges where full is bad.
18  heat: ['#2cb67d', '#f4d35e', '#ff8c42', '#ef4565'],
19  // Cool, for neutral figures.
20  ice: ['#3da9fc', '#7f5af0'],
21  // Money and growth.
22  money: ['#2cb67d', '#a8e6cf'],
23} as const satisfies Record<string, readonly string[]>
24
25export type GradientName = keyof typeof GRADIENTS
26
27/** The color at `t` (0..1) along the stops. */
28export const colorAt = (stops: readonly string[], t: number): string => {
29  if (stops.length === 1) return stops[0]!
30  const clamped = Math.min(1, Math.max(0, t))
31  const span = clamped * (stops.length - 1)
32  const i = Math.min(stops.length - 2, Math.floor(span))
33  const a = hexToRgb(stops[i]!)
34  const b = hexToRgb(stops[i + 1]!)
35  const local = span - i
36  return rgbToHex([0, 1, 2].map(k => a[k]! + (b[k]! - a[k]!) * local) as unknown as Rgb)
37}
38
39/** One color per character of `text`, spread across the stops. */
40export const paint = (text: string, stops: readonly string[]) => {
41  const chars = [...text]
42  return chars.map((char, i) => ({ char, color: colorAt(stops, chars.length > 1 ? i / (chars.length - 1) : 0) }))
43}
44
45const EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']
46
47/**
48 * A bar `width` cells wide filled to `ratio` (0..1), with eighth-cell precision.
49 * Each filled cell takes the gradient color of its position along the whole bar,
50 * so a nearly full heat bar ends red and a low one stays green.
51 */
52export const bar = (ratio: number, width: number, stops: readonly string[]) => {
53  const filled = Math.min(1, Math.max(0, ratio)) * width
54  const full = Math.floor(filled)
55  const partial = EIGHTHS[Math.round((filled - full) * 7)] ?? ''
56  const cells: { char: string; color: string; empty?: true }[] = []
57  for (let i = 0; i < width; i++) {
58    const color = colorAt(stops, width > 1 ? i / (width - 1) : 0)
59    if (i < full) cells.push({ char: '█', color })
60    else if (i === full && partial) cells.push({ char: partial, color })
61    else cells.push({ char: '·', color, empty: true })
62  }
63  return cells
64}
65
66export const formatTokens = (n: number) =>
67  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 10_000 ? `${Math.round(n / 1000)}k` : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : `${n}`
68
69export const formatDuration = (ms: number) => {
70  const minutes = Math.max(0, Math.round(ms / 60_000))
71  const h = Math.floor(minutes / 60)
72  const m = minutes % 60
73  return h > 0 ? `${h}h${String(m).padStart(2, '0')}` : `${m}min`
74}
75

1export type JrCacheClock = {
2  /** When the main loop's last model response ended (epoch ms). */
3  lastAt: number | null
4  now: number
5  /** Share of the last turn's input read from the cache, 0..1, when the engine said. */
6  hitRate: number | null
7}
8
9declare module 'claude-code' {
10  interface PluginState {
11    'jr-cache-clock': { clock: JrCacheClock | null; isBandHidden: boolean }
12  }
13}
14