cache-glance

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import { DEFAULT_TTL_MS, SHORT_TTL_MS, readCache } from './format'
5import type { CacheState } from './format'
6
7// Kept in $.state so a reload of the mod keeps the clock it was running.
8const lastRequestAt = atom({ plugin: 'cache-glance', key: 'lastRequestAt' } as const, 0)
9const ctx = atom({ plugin: 'cache-glance', key: 'ctx' } as const, 0)
10const model = atom({ plugin: 'cache-glance', key: 'model' } as const, null as string | null)
11
12const REFRESH_MS = 30_000
13
14// Theme keys, so the line follows the person's Claude Code theme.
15const STATE_COLOR: Record<CacheState, string | undefined> = {
16  warm: 'success',
17  cold: 'warning',
18  unknown: undefined,
19}
20
21let ttlMs = DEFAULT_TTL_MS
22
23/** The cache lives five minutes when the person set it so, an hour otherwise. */
24async function readTtl($: EngineInterface): Promise<number> {
25  const fromEnv = await $.env.get('CLAUDE_CODE_PROMPT_CACHE_TTL')
26  const fromSettings = (await $.settings.read()).promptCacheTtl
27  return (fromEnv ?? fromSettings) === '5m' ? SHORT_TTL_MS : DEFAULT_TTL_MS
28}
29
30export const register: Register = on => {
31  on('session.start', async ($, e, next) => {
32    const result = await next(e)
33    // An earlier version pinned its line under the prompt; that pin outlives a reload.
34    $.ui.status(undefined)
35    ttlMs = await readTtl($)
36    if ((await read($, model)) === null) {
37      const current = await $.session.model()
38      await update($, model, () => current)
39    }
40    // Loaded into a running session: the window's size is known, its clock is not.
41    if ((await read($, ctx)) === 0) {
42      const tokens = (await $.session.usage()).context.tokens ?? 0
43      await update($, ctx, () => tokens)
44    }
45    // The countdown moves with the clock, not with any value: redraw it on a timer.
46    $.clock.every(REFRESH_MS, () => $.ui.invalidate('ui.render'))
47    return result
48  })
49
50  on('classic.SessionStart', async ($, e, next) => {
51    const result = await next(e)
52    if (e.source === 'clear') {
53      await update($, lastRequestAt, () => 0)
54      await update($, ctx, () => 0)
55    } else if (e.source === 'compact') {
56      // The next request writes the compacted conversation afresh.
57      await update($, lastRequestAt, () => 0)
58    } else if (e.source === 'resume' || e.source === 'fork') {
59      const now = await $.clock.now()
60      const seconds = e.seconds_since_last_response
61      const tokens = e.context_tokens
62      const resumedModel = e.model
63      if (seconds !== undefined) await update($, lastRequestAt, () => now - seconds * 1000)
64      if (tokens !== undefined && tokens > 0) await update($, ctx, () => tokens)
65      if (resumedModel) await update($, model, () => resumedModel)
66    }
67    return result
68  })
69
70  // Each request of the main conversation reads the cache and restarts its clock.
71  on('turn.step', async function* ($, e, next) {
72    if (!e.agentId) {
73      const now = await $.clock.now()
74      await update($, lastRequestAt, () => now)
75    }
76    return yield* next(e)
77  })
78
79  // A fork of the main conversation (cache-tax's keepwarm ping is one) reads the
80  // same cache; when it did read it, the clock starts over just as for a turn.
81  on('model.fork', async ($, e, next) => {
82    const result = await next(e)
83    const answer = 'value' in result ? result.value : undefined
84    if (answer?.isAnswered && answer.usage.cache_read_input_tokens > 0) {
85      const now = await $.clock.now()
86      await update($, lastRequestAt, () => now)
87    }
88    return result
89  })
90
91  on('turn.complete', async ($, e, next) => {
92    const result = await next(e)
93    if (e.agentId) return result
94    const now = await $.clock.now()
95    const usage = e.usage
96    const live = (await $.session.usage()).context.tokens
97    const summed = usage
98      ? usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens
99      : 0
100    const tokens = live && live > 0 ? live : summed
101    if (tokens > 0) await update($, ctx, () => tokens)
102    const answered = usage?.model
103    if (answered) await update($, model, () => answered)
104    // No step stamped this turn (a hook answered it): its end is the latest request.
105    await update($, lastRequestAt, at => (now - at > e.durationMs ? now : at))
106    return result
107  })
108
109  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
110    const rest = await next(e)
111    if (e.props.hasSurvey) return rest
112
113    const glance = {
114      lastRequestAt: await read($, lastRequestAt),
115      ctx: await read($, ctx),
116      model: await read($, model),
117    }
118    const reading = readCache(glance, await $.clock.now(), ttlMs)
119    if (!reading) return rest
120
121    const { Box, Text } = $.ui.resolve(e)
122    const color = STATE_COLOR[reading.state]
123    // Cold costs money on the next send, so its detail reads at full strength.
124    const isQuiet = reading.state !== 'cold'
125
126    return (
127      <Box flexDirection="column">
128        {rest}
129        <Box key="cache-glance" flexDirection="row">
130          <Text dimColor>快取 </Text>
131          {color ? (
132            <Text color={color} bold>
133              {reading.state}
134            </Text>
135          ) : (
136            <Text dimColor>·</Text>
137          )}
138          <Text dimColor={isQuiet}> · {reading.detail}</Text>
139        </Box>
140      </Box>
141    )
142  })
143}
144

1import type { Glance } from '../types'
2
3const MINUTE = 60_000
4const HOUR = 60 * MINUTE
5
6/** The prompt cache's lifetime after the last request: one hour on a subscription. */
7export const DEFAULT_TTL_MS = HOUR
8export const SHORT_TTL_MS = 5 * MINUTE
9
10// $ per million tokens for a one-hour cache write, list prices September 2026.
11// From cache-tax by Karan Bansal (MIT), so both mods quote the same figure.
12// Longer family names first: a model id matches the first row it contains.
13const WRITE_PRICES: Array<[string, number]> = [
14  ['fable-5-1', 20],
15  ['fable-5', 20],
16  ['opus-5', 10],
17  ['opus-4', 10],
18  ['sonnet-5', 4],
19  ['sonnet', 6],
20  ['haiku', 2],
21]
22
23// A five-minute write costs 1.25x the base input rate, a one-hour write 2x.
24const SHORT_WRITE_SHARE = 1.25 / 2
25
26/** What re-writing `tokens` into the cache costs on `model`, or null for a model not in the table. */
27export const rewriteUsd = (model: string | null, tokens: number, ttlMs = DEFAULT_TTL_MS): number | null => {
28  const id = (model ?? '').toLowerCase().replace(/[\s.]+/g, '-')
29  const row = WRITE_PRICES.find(([family]) => id.includes(family))
30  if (!row) return null
31  const perMillion = ttlMs <= SHORT_TTL_MS ? row[1] * SHORT_WRITE_SHARE : row[1]
32  return (tokens * perMillion) / 1e6
33}
34
35/** 47m, 1h 5m, <1m */
36export const formatDuration = (ms: number): string => {
37  if (ms < MINUTE) return '<1m'
38  const hours = Math.floor(ms / HOUR)
39  const minutes = Math.floor((ms % HOUR) / MINUTE)
40  return hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`
41}
42
43export type CacheState = 'warm' | 'cold' | 'unknown'
44
45/** The line's two parts, drawn in their own colors; undefined before there is a conversation to cache. */
46export type Reading = { state: CacheState; detail: string }
47
48export const readCache = (g: Glance, now: number, ttlMs = DEFAULT_TTL_MS): Reading | undefined => {
49  if (g.ctx <= 0) return undefined
50  if (g.lastRequestAt <= 0) return { state: 'unknown', detail: '下次回覆後開始計時' }
51
52  const usd = rewriteUsd(g.model, g.ctx, ttlMs)
53  const left = g.lastRequestAt + ttlMs - now
54  if (left > 0) {
55    const cost = usd === null ? '' : ` · 過期重寫約 $${usd.toFixed(2)}`
56    return { state: 'warm', detail: `${formatDuration(left)} 後過期${cost}` }
57  }
58  const cost = usd === null ? '' : ` · 下次送出重寫約 $${usd.toFixed(2)}`
59  return { state: 'cold', detail: `已過期 ${formatDuration(-left)}${cost}` }
60}
61
62/** The whole line as plain text: 快取 warm · 47m 後過期 · 過期重寫約 $3.91 */
63export const lineText = (r: Reading): string =>
64  r.state === 'unknown' ? `快取 · ${r.detail}` : `快取 ${r.state} · ${r.detail}`
65

1/** What the line under the prompt is computed from. */
2export type Glance = {
3  /** When the main conversation last sent a request, in $.clock.now() ms; 0 while unknown. */
4  lastRequestAt: number
5  /** Tokens the prompt cache holds for the main conversation. */
6  ctx: number
7  /** The model that answered last, for its cache-write price. */
8  model: string | null
9}
10
11declare module 'claude-code' {
12  interface PluginState {
13    'cache-glance': {
14      lastRequestAt: Glance['lastRequestAt']
15      ctx: Glance['ctx']
16      model: Glance['model']
17    }
18  }
19}
20