cache-clock

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import { flagOf } from './flag'
5
6const MOD = 'cache-clock'
7const FIVE_MIN = 5 * 60_000
8const ONE_HOUR = 60 * 60_000
9const MAX_WARM_MS = 2 * 60 * 60_000
10
11const expiresAt = atom({ plugin: 'cache-clock', key: 'expiresAt' } as const, null)
12const now = atom({ plugin: 'cache-clock', key: 'now' } as const, 0)
13const isKeepWarm = atom({ plugin: 'cache-clock', key: 'isKeepWarm' } as const, false)
14const warmSince = atom({ plugin: 'cache-clock', key: 'warmSince' } as const, null)
15const ttlMs = atom({ plugin: 'cache-clock', key: 'ttlMs' } as const, FIVE_MIN)
16const pings = atom({ plugin: 'cache-clock', key: 'pings' } as const, 0)
17const note = atom({ plugin: 'cache-clock', key: 'note' } as const, '')
18
19// Module variables start over on a reload; everything the screen needs is in $.state.
20let isRunning = false
21let isPinging = false
22let lastStepEnd = 0
23let lastContext = 0
24let isFixedTtl = false
25let leadMs = 25_000
26
27// The strip's Keep Warm button bumps this counter; only this mod may flip its own switch.
28const TOGGLES = { plugin: 'switchboard', key: 'toggles' } as const
29let seenToggle = -1
30
31const minutes = (ms: number) => Math.round(ms / 60_000)
32
33const mmss = (ms: number) => {
34  const total = Math.max(0, Math.round(ms / 1000))
35
36  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`
37}
38
39async function setWarm($: EngineInterface, wanted: boolean, why?: string) {
40  const at = await $.clock.now()
41  await update($, isKeepWarm, () => wanted)
42  await update($, warmSince, () => (wanted ? at : null))
43  if (wanted) await update($, pings, () => 0)
44  if (why !== undefined) $.ui.toast(why)
45}
46
47// Heartbeat: a tool-less fork of the session's own transcript. The API serves
48// the whole prefix from cache (reading it keeps the entry alive) and the reply
49// is one word. Nothing is added to the conversation.
50async function heartbeat($: EngineInterface) {
51  if (isPinging) return
52  isPinging = true
53  try {
54    const reply = await $.model.fork({ prompt: 'Reply with exactly one word: ok' })
55    const at = await $.clock.now()
56    if (!reply.isAnswered) {
57      if (reply.reason === 'nothing-to-fork') {
58        await setWarm($, false, 'Keep Warm：还没有可保温的对话，已关闭。')
59      } else {
60        await update($, note, () => `保温心跳失败（${reply.reason}），下次再试`)
61      }
62
63      return
64    }
65    const { input_tokens, cache_read_input_tokens, cache_creation_input_tokens } =
66      reply.usage
67    const total = input_tokens + cache_read_input_tokens + cache_creation_input_tokens
68    const ttl = await read($, ttlMs)
69    await update($, expiresAt, () => at + ttl)
70    if (total > 2000 && cache_read_input_tokens / total < 0.2) {
71      await setWarm($, false, 'Keep Warm：缓存其实已经冷了，这次心跳把它重新写热，先关闭保温。')
72
73      return
74    }
75    await update($, pings, n => n + 1)
76    await update($, note, () => `保温心跳成功，读到缓存 ${cache_read_input_tokens} tokens`)
77  } finally {
78    isPinging = false
79  }
80}
81
82async function tick($: EngineInterface) {
83  const at = await $.clock.now()
84  await update($, now, () => at)
85  const pressed = ((await $.state.get(TOGGLES)).value ?? {})['keep-warm'] ?? 0
86  if (seenToggle < 0) seenToggle = pressed
87  if (pressed !== seenToggle) {
88    seenToggle = pressed
89    if ((await flagOf($, MOD)).isOn) await setWarm($, !(await read($, isKeepWarm)))
90  }
91  if (!(await read($, isKeepWarm))) return
92  if (!(await flagOf($, MOD)).isOn) return
93
94  const since = await read($, warmSince)
95  if (since !== null && at - since >= MAX_WARM_MS) {
96    await setWarm($, false, 'Keep Warm：已连续保温 2 小时，自动关闭。')
97
98    return
99  }
100  const end = await read($, expiresAt)
101  if (end === null || isRunning || isPinging) return
102  if (end > at && end - at <= leadMs) await heartbeat($)
103}
104
105export const register: Register = (on, options) => {
106  isFixedTtl = Number(options.ttlMinutes ?? 0) > 0
107  leadMs = Math.max(8, Number(options.leadSeconds ?? 25)) * 1000
108
109  on('session.start', async ($, e, next) => {
110    await $.command.register({
111      name: 'keep',
112      description: '缓存保温：/keep warm 开关自动续杯',
113      argumentHint: 'warm',
114    })
115    const fixed = Number(options.ttlMinutes ?? 0)
116    if (fixed > 0) {
117      await update($, ttlMs, () => fixed * 60_000)
118    } else {
119      const auth = await $.session.authorize()
120      await update($, ttlMs, () => (auth?.kind === 'bearer' ? ONE_HOUR : FIVE_MIN))
121    }
122    $.clock.every(1000, () => void tick($).catch(() => undefined))
123
124    return next(e)
125  })
126
127  on('session.end', async ($, e, next) => {
128    await update($, expiresAt, () => null)
129    await setWarm($, false)
130
131    return next(e)
132  })
133
134  on('command.run', { command: 'keep' }, async ($, e) => {
135    if (e.args.trim() === '') {
136      const left = (await read($, expiresAt)) === null ? null : (await read($, expiresAt))! - (await $.clock.now())
137      const info = await read($, note)
138
139      return {
140        text: [
141          left === null ? '缓存：还没有（发一条消息后开始计时）' : left <= 0 ? '缓存：已经冷了' : `缓存还剩 ${mmss(left)}`,
142          `Keep Warm：${(await read($, isKeepWarm)) ? '开' : '关'}（/keep warm 开关）`,
143          info === '' ? '' : info,
144        ].filter(line => line !== '').join('\n'),
145      }
146    }
147    const wanted = !(await read($, isKeepWarm))
148    await setWarm($, wanted)
149
150    return {
151      text: wanted
152        ? 'Keep Warm 已开启：缓存快冷前会自动发一条极小的心跳。你发下一条消息或满 2 小时会自动关闭。'
153        : 'Keep Warm 已关闭。',
154    }
155  })
156
157  // A real message from the person ends the loop: that turn keeps the cache warm itself.
158  on('prompt.submit', async ($, e, next) => {
159    if (e.origin.kind === 'composer' && e.command === undefined) {
160      if (await read($, isKeepWarm)) {
161        await setWarm($, false, 'Keep Warm：你发了新消息，自动关闭。')
162      }
163    }
164
165    return next(e)
166  }).catch(($, e, next) => next(e))
167
168  on('turn.start', async ($, e, next) => {
169    if (e.agentId === undefined) isRunning = true
170
171    return next(e)
172  }).catch(($, e, next) => next(e))
173
174  on('turn.complete', async ($, e, next) => {
175    if (e.agentId === undefined) isRunning = false
176
177    return next(e)
178  }).catch(($, e, next) => next(e))
179
180  // Every main-loop request writes or reads the cache, so it restarts the clock.
181  // The first request of a turn also tells us whether the cache was still there,
182  // which is the only real evidence we get of the lifetime.
183  on('turn.step', async function* ($, e, next) {
184    const startedAt = await $.clock.now()
185    const result = yield* next(e)
186    if (e.agentId === undefined && result.usage !== null) {
187      const { input_tokens, cache_read_input_tokens, cache_creation_input_tokens } =
188        result.usage
189      const context = input_tokens + cache_read_input_tokens + cache_creation_input_tokens
190      const ttl = await read($, ttlMs)
191      let ttlNow = ttl
192      const gap = lastStepEnd === 0 ? 0 : startedAt - lastStepEnd
193      if (e.index === 0 && !isFixedTtl && lastContext > 3000 && gap > FIVE_MIN) {
194        const ratio = cache_read_input_tokens / Math.max(1, context)
195        if (ratio >= 0.7 && ttl < ONE_HOUR) {
196          ttlNow = ONE_HOUR
197          await update($, ttlMs, () => ONE_HOUR)
198          await update($, note, () => `实测：隔了 ${minutes(gap)} 分钟缓存还在 → 按 60 分钟计`)
199        } else if (ratio < 0.2) {
200          await update($, note, () => `实测：隔了 ${minutes(gap)} 分钟缓存已冷（那一轮重读了全文）`)
201          if (ttl >= ONE_HOUR && gap < ONE_HOUR - 300_000) {
202            ttlNow = FIVE_MIN
203            await update($, ttlMs, () => FIVE_MIN)
204          }
205        }
206      }
207      const end = await $.clock.now()
208      lastStepEnd = end
209      lastContext = context
210      await update($, expiresAt, () => end + ttlNow)
211    }
212
213    return result
214  })
215}
216

1import type { EngineInterface } from 'claude-code'
2
3const FLAGS = { plugin: 'switchboard', key: 'flags' } as const
4
5export type Flag = { isOn: boolean; isHidden: boolean }
6
7// Switchboard owns the flags. A mod it has never heard of counts as on, shown.
8export async function flagOf($: EngineInterface, mod: string): Promise<Flag> {
9  const { value } = await $.state.get(FLAGS)
10  const own = value?.[mod]
11
12  return { isOn: own?.isOn ?? true, isHidden: own?.isHidden ?? false }
13}
14

1declare module 'claude-code' {
2  interface PluginState {
3    'cache-clock': {
4      // When the prompt cache goes cold (ms since epoch); null before the first reply.
5      expiresAt: number | null
6      // Ticks once a second so the countdown redraws.
7      now: number
8      isKeepWarm: boolean
9      warmSince: number | null
10      ttlMs: number
11      pings: number
12      note: string
13    }
14    // Read-only view of Switchboard's value (it alone writes it).
15    switchboard: {
16      flags: Record<string, { isOn: boolean; isHidden: boolean }>
17      toggles: Record<string, number>
18    }
19  }
20}
21