cache-warm

1// cache-warm: shows the prompt-cache TTL in the footer and keeps the cache warm.
2//
3// The model API caches the conversation prefix for 5 minutes, counted from the start of
4// each request that uses it; a cached read costs a fraction of an uncached one. After a
5// longer pause the next prompt pays full price for the whole context. This mod sends a
6// tiny side request shortly before the TTL runs out, which renews it, until the user
7// has been idle for IDLE_LIMIT_MS.
8//
9// How a mod works, as far as this file needs it:
10// - `register` receives `on`, which attaches a hook to a host event. A hook gets the
11//   host handle `$`, the event `e` and `next`, the rest of the chain. Calling
12//   `next(e)` (possibly with a changed event) passes control on and returns the
13//   result, so a hook can act before and after the host does.
14// - The module is reloaded on edits and its top-level variables are reset. State that
15//   must survive lives in an atom (below), kept by the host.
16import { atom, read, update } from 'claude-code'
17import type { Register } from 'claude-code'
18
19import type { CacheWarm } from '../types'
20
21// The five values below come from the plugin's userConfig (see plugin.json); register
22// fills them on every load, the defaults hold until then.
23// How long the prompt cache lives after a request has read or written it, counted from
24// the start of that request (5 min on API keys).
25let CACHE_TTL_MS = 5 * 60_000
26// A refresh is sent this long before the cache expires.
27let REFRESH_LEAD_MS = 30_000
28// No refreshes once the last prompt is older than this; the cache then goes cold.
29let IDLE_LIMIT_MS = 30 * 60_000
30// Whether a new session starts with cache-warm on; /cache-warm start and stop switch it
31// for the running session.
32let AUTO_START = true
33// Whether a request that read less than half its input from a cache the footer calls
34// warm raises a warning line and is counted, and a refresh that read far more than
35// the last request of a turn took in raises a warning line. For watching the cache
36// behaviour, off by default.
37let DEBUG_WARNINGS = false
38// After a failed refresh, wait this long before trying again.
39const RETRY_DELAY_MS = 15_000
40// How long a toast stays; the host's default of 4 s is easy to miss.
41const TOAST_MS = 20_000
42// Shown in the footer while a compaction or a turn blocks refreshes.
43const COMPACT_NOTE = 'paused (compact)'
44const TURN_NOTE = 'paused (turn)'
45const IDLE_NOTE = 'idle limit reached'
46// Footer and status text while /cache-warm pause is in effect; derived from isPaused,
47// not stored in note.
48const PAUSE_NOTE = 'paused (until next prompt)'
49
50// The shared state, kept by the host so that a reload does not lose it. `now` is part
51// of it on purpose: writing it every second makes the footer redraw its countdown.
52// Fields: see ../types.
53const cache = atom(
54  { plugin: 'cache-warm', key: 'cache' } as const,
55  {
56    expiresAt: null,
57    now: 0,
58    tokens: 0,
59    disabledReason: '',
60    isEnabled: null,
61    isVerified: false,
62    refreshCount: 0,
63    totalRefreshCount: 0,
64    coldPromptCount: 0,
65    note: '',
66  } as CacheWarm,
67)
68
69const fmt = (ms: number) => {
70  const s = Math.max(0, Math.round(ms / 1000))
71  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`
72}
73
74const describe = (c: CacheWarm) => {
75  if (!c.isEnabled || c.expiresAt === null) return undefined
76  // A request reads the cache as it starts, which renews it, but expiresAt is only
77  // written once the step has ended. Until then count from the request's start (or
78  // from the prompt, which precedes it): never more time than the cache has. After an
79  // ESC before the answer started, requestStartedAt is gone and the old expiry shows
80  // again, since nothing tells whether the request reached the cache.
81  const expiresAt =
82    c.requestStartedAt === undefined
83      ? c.expiresAt
84      : Math.max(c.expiresAt, c.requestStartedAt + CACHE_TTL_MS)
85  // c.now can be older than the request's start: never show more than the lifetime.
86  const left = Math.min(expiresAt - c.now, CACHE_TTL_MS)
87  const state = c.disabledReason !== ''
88    ? 'keep-warm off'
89    : left <= 0
90      ? 'cold'
91      : `warm ${fmt(left)}`
92  // The count tells that refreshes ran since the last prompt; the duration is only
93  // worth showing when a refresh was slow: it took half the refresh lead or longer, so
94  // the lead is getting tight. The lead scales with the setting, a fixed limit would
95  // not fit a large context.
96  const slow =
97    c.lastRefreshMs !== undefined && c.lastRefreshMs >= REFRESH_LEAD_MS / 2
98      ? `, last ${(c.lastRefreshMs / 1000).toFixed(1)}s`
99      : ''
100  const refreshes =
101    c.refreshCount > 0
102      ? ` (${c.refreshCount} ${c.refreshCount === 1 ? 'refresh' : 'refreshes'}${slow})`
103      : ''
104  const note = c.note !== '' ? c.note : c.isPaused ? PAUSE_NOTE : ''
105  return `cache ${state}${refreshes}${note ? ` · ${note}` : ''}`
106}
107
108type RequestUsage = {
109  input_tokens: number
110  cache_read_input_tokens: number
111  cache_creation_input_tokens: number
112}
113
114// True when a request took less than half of its input from the cache. A large pasted
115// prompt also does that, so this is a hint, not proof of a discarded cache.
116const isMostlyUncached = (u: RequestUsage) => {
117  const read = u.cache_read_input_tokens
118  const total = u.input_tokens + read + u.cache_creation_input_tokens
119  return total > 0 && read * 2 < total
120}
121
122// A refresh normally reads about as many tokens from the cache as the last request of
123// a turn took in. At this multiple of that it counts as read twice.
124const DOUBLE_READ_FACTOR = 1.8
125
126const inputOf = (u: RequestUsage) =>
127  u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens
128
129// Pinned as the status line under the prompt, where it stays until the next prompt
130// clears it, for a refresh that read far more from the cache than the last request of
131// a turn took in. `$` is typed `any` as in tick.
132function warnDoubleRead($: any, u: RequestUsage, lastInputTokens: number) {
133  $.ui.status(
134    `refresh read ${u.cache_read_input_tokens} tokens from the cache, ` +
135      `${(u.cache_read_input_tokens / lastInputTokens).toFixed(1)} times the ` +
136      `${lastInputTokens} the last request took in`,
137  )
138}
139
140// Pinned as the status line under the prompt, where it stays until the next prompt
141// clears it. `$` is typed `any` as in tick.
142// The timing tells a server-side early eviction (the footer had time left, the last
143// cache use was recent) from a long gap (a sleeping machine, a stalled clock). Who
144// made that last use matters too: a refresh may reach a cache entry that a turn does
145// not, or the other way round.
146// `before` is the atom as it was when the request started; its expiresAt is not null.
147async function warnRewrite(
148  $: any,
149  source: string,
150  u: RequestUsage,
151  before: CacheWarm,
152  startedAt: number,
153) {
154  await update($, cache, (c: CacheWarm) => ({
155    ...c,
156    rewriteCount: (c.rewriteCount ?? 0) + 1,
157  }))
158  const expiresAt = before.expiresAt as number
159  $.ui.status(
160    `${source} read ${u.cache_read_input_tokens} and wrote ` +
161      `${u.cache_creation_input_tokens} tokens although the cache looked warm ` +
162      `(${fmt(expiresAt - startedAt)} left, last cache use ` +
163      `${fmt(startedAt - (expiresAt - CACHE_TTL_MS))} ago` +
164      `${before.lastUse === undefined ? '' : `, by ${before.lastUse}`})`,
165  )
166}
167
168let lastActivity = 0
169let isRefreshing = false
170// A running turn reads and writes the cache itself; no refresh beside it.
171let isTurnRunning = false
172// A compaction replaces the context; a refresh during it would warm a prefix that is
173// about to be thrown away.
174let isCompacting = false
175let lastFailureAt = 0
176let timer: { cancel: () => void } | undefined
177// The last /cache-warm start or stop. /clear resets the atom but not the module, so
178// this carries the choice over it; a reload resets this, but not the atom.
179let userChoice: boolean | undefined
180
181// Runs every second: updates the clock for the display and, when the cache is about to
182// expire, sends the refresh. It is a top-level function because the host lets `$` be
183// passed only to those; `$` is typed `any` for that reason.
184async function tick($: any) {
185  const now: number = await $.clock.now()
186  const c: CacheWarm = await read($, cache)
187  if (c.expiresAt === null) return
188  // The write redraws the SessionMode hook below, which reads this atom.
189  await update($, cache, (x: CacheWarm) => ({ ...x, now }))
190
191  // A reload resets module variables; count idle time from then on, not from 1970.
192  if (lastActivity === 0) lastActivity = now
193  const isIdle = now - lastActivity > IDLE_LIMIT_MS
194  // Say why the countdown runs down without a refresh. Only into an empty note, so it
195  // is written once and never hides another message; the next prompt replaces it.
196  if (isIdle && c.note === '' && now < c.expiresAt) {
197    await update($, cache, (x: CacheWarm) =>
198      x.note === '' ? { ...x, note: IDLE_NOTE } : x,
199    )
200  }
201  // Not after expiry: a cold cache is rewritten at full price, which the next prompt
202  // does anyway.
203  const isDue = now >= c.expiresAt - REFRESH_LEAD_MS && now < c.expiresAt
204  const isBackingOff = now - lastFailureAt < RETRY_DELAY_MS
205  const isDisabled = c.disabledReason !== ''
206  const isBlocked =
207    isDisabled || isRefreshing || isTurnRunning || isCompacting || c.isPaused === true
208  if (isBlocked || !isDue || isIdle || isBackingOff) return
209
210  isRefreshing = true
211  try {
212    // The API counts the lifetime from the start of the request that reads the cache,
213    // not from the end of its answer, so the new expiry is counted from here too.
214    const startedAt: number = await $.clock.now()
215    let r
216    // A fork repeats the main thread's last request (same model, system prompt, tools
217    // and messages) with this prompt appended and all tools denied. The API therefore
218    // serves the whole conversation from its cache, which renews the TTL; only the
219    // short prompt is computed fresh. Before the first reply there is nothing to fork.
220    try {
221      // The start time makes every prompt different. The text says what the request is
222      // and what to answer, so the model has nothing to look into.
223      r = await $.model.fork({
224        prompt:
225          `Automated keep-alive ${startedAt}: no tools, no commentary, ` +
226          'your entire reply is "ok".',
227      })
228    } catch {
229      r = { isAnswered: false as const, reason: 'error' }
230    }
231    const lastRefreshMs: number = (await $.clock.now()) - startedAt
232    if (!r.isAnswered) {
233      lastFailureAt = startedAt
234      await update($, cache, (x: CacheWarm) => ({
235        ...x,
236        note: `refresh failed: ${r.reason}`,
237      }))
238      return
239    }
240    // Why check at all: nothing in turn.complete says whether the cache was really
241    // written. The footer assumes it was and says "warm" from the first prompt; the
242    // first refresh is the silent test. If it reads any tokens from the cache, caching
243    // works and isVerified is set; if it reads none, the gateway drops caching (or the
244    // cache entry had already expired by then), and every further refresh would pay
245    // the full context price for nothing. Any hit counts, not a share of the context:
246    // the context size is only known roughly (the status line's rounded percentage),
247    // and a cache written just before covers only part of the context. isVerified is
248    // kept in the atom, which a hot reload keeps, and is never checked again once true.
249    if (!c.isVerified) {
250      if (!(r.usage.cache_read_input_tokens > 0)) {
251        await update($, cache, (x: CacheWarm) => ({
252          ...x,
253          disabledReason:
254            'caching verification: first refresh read no tokens from cache',
255          note: 'first refresh read no tokens from cache',
256        }))
257        $.ui.toast('cache-warm: caching not passed through, keep-warm switched off', {
258          timeoutMs: TOAST_MS,
259        })
260        return
261      }
262    }
263    if (DEBUG_WARNINGS && isMostlyUncached(r.usage)) {
264      await warnRewrite($, 'refresh', r.usage, c, startedAt)
265    }
266    if (
267      DEBUG_WARNINGS &&
268      c.lastInputTokens !== undefined &&
269      r.usage.cache_read_input_tokens >= c.lastInputTokens * DOUBLE_READ_FACTOR
270    ) {
271      warnDoubleRead($, r.usage, c.lastInputTokens)
272    }
273    await update($, cache, (x: CacheWarm) => ({
274      ...x,
275      isVerified: true,
276      lastRefreshMs,
277      refreshCount: x.refreshCount + 1,
278      totalRefreshCount: (x.totalRefreshCount ?? 0) + 1,
279      expiresAt: startedAt + CACHE_TTL_MS,
280      lastUse: 'refresh',
281      note: '',
282    }))
283  } finally {
284    isRefreshing = false
285  }
286}
287
288// The value of DISABLE_PROMPT_CACHING when it makes the host send no cache markers
289// (1, true, yes or on), else undefined. `$` is typed `any` here as in tick; the name
290// must be a string literal for `$.env.get`.
291async function cachingDisabledBy($: any): Promise<string | undefined> {
292  const v: string | undefined = await $.env.get('DISABLE_PROMPT_CACHING')
293  return v !== undefined && /^(1|true|yes|on)$/i.test(v.trim()) ? v.trim() : undefined
294}
295
296const envReason = (value: string) => `DISABLE_PROMPT_CACHING=${value}`
297const envText = (value: string) =>
298  `cache-warm: ${envReason(value)}, there is no cache to keep warm`
299
300// Decides the start state while isEnabled is still null: in a new session, and after
301// /clear, which resets the atom but fires no session.start. The option sets the state,
302// never overrides a stop. Without caching a refresh is billed at the normal input
303// price and renews nothing, which the first-refresh check could only find out after
304// paying for one; so the mod does not start at all.
305async function initState($: any) {
306  const envValue = await cachingDisabledBy($)
307  await update($, cache, (c: CacheWarm) => ({
308    ...c,
309    isEnabled: c.isEnabled ?? (envValue === undefined && (userChoice ?? AUTO_START)),
310    // Kept for /cache-warm status, which names why the mod is not running.
311    disabledReason: envValue !== undefined ? envReason(envValue) : c.disabledReason,
312  }))
313  if (envValue !== undefined) $.ui.toast(envText(envValue), { timeoutMs: TOAST_MS })
314}
315
316// A number option, or the default when it is missing, not finite or out of range.
317const num = (v: unknown, fallback: number, min: number, max: number) =>
318  typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max ? v : fallback
319
320export const register: Register = (on, options) => {
321  // A picker over "5" and "60" (see plugin.json); anything else counts as 5.
322  CACHE_TTL_MS = (options.cacheTtlMinutes === '60' ? 60 : 5) * 60_000
323  // The lead must stay below the lifetime, else a refresh is due the moment the cache
324  // is written.
325  REFRESH_LEAD_MS = Math.min(
326    num(options.refreshLeadSeconds, 30, 5, 600) * 1000,
327    CACHE_TTL_MS / 2,
328  )
329  IDLE_LIMIT_MS = num(options.idleLimitMinutes, 30, 1, 720) * 60_000
330  AUTO_START = options.autoStart !== false
331  DEBUG_WARNINGS = options.debugWarnings === true
332
333  // A reload cancels the timer and starts the module afresh; session.start fires again.
334  on('session.start', async ($, e, next) => {
335    // Clears the pinned line an earlier version of this mod left behind.
336    $.ui.status(undefined)
337    // Also runs after a reload, when the atom already holds the user's choice (null
338    // only in a new session).
339    await initState($)
340    await $.command.register({
341      name: 'cache-warm',
342      description: 'Start, stop or pause cache-warm, show its counters and settings',
343      argumentHint: '[start|stop|pause|status]',
344      immediate: true,
345    })
346    if ((await read($, cache)).isEnabled) {
347      timer ??= $.clock.every(1000, () => void tick($))
348    }
349    return next(e)
350  })
351
352  // "status" is the default. start and stop switch the running session only; the
353  // autoStart option decides how the next one begins. pause is for an absence you know
354  // is long: no refreshes until the next prompt, without stopping and starting again.
355  on('command.run', { command: 'cache-warm' }, async ($, e, next) => {
356    const sub = e.args.trim()
357    if (!['', 'status', 'start', 'stop', 'pause'].includes(sub)) {
358      return { text: 'usage: /cache-warm [start|stop|pause|status]' }
359    }
360    if ((await read($, cache)).isEnabled === null) await initState($)
361    if (sub === 'pause') {
362      const c: CacheWarm = await read($, cache)
363      if (!c.isEnabled || c.disabledReason !== '') {
364        return { text: 'nothing to pause, cache-warm is not running' }
365      }
366      await update($, cache, (x: CacheWarm) => ({ ...x, isPaused: true }))
367      return { text: 'paused until your next prompt (start ends it earlier)' }
368    }
369    if (sub === 'start' || sub === 'stop') {
370      const isEnabled = sub === 'start'
371      const envValue = isEnabled ? await cachingDisabledBy($) : undefined
372      if (envValue !== undefined) return { text: envText(envValue) }
373      // `now` is only written by tick, which does not run while stopped: refresh it, or
374      // the footer shows the countdown as it was at stop.
375      const now = await $.clock.now()
376      userChoice = isEnabled
377      await update($, cache, (c: CacheWarm) => ({
378        ...c,
379        isEnabled,
380        now,
381        isPaused: false,
382      }))
383      // Stopped means no timer at all, not a timer that returns at once.
384      if (isEnabled) {
385        timer ??= $.clock.every(1000, () => void tick($))
386      } else {
387        timer?.cancel()
388        timer = undefined
389      }
390      return { text: isEnabled ? 'started' : 'stopped' }
391    }
392    const c: CacheWarm = await read($, cache)
393    // The host puts "cache-warm:" before the text, so the first line is the state.
394    // The footer already shows the cache state.
395    const text = [
396      c.disabledReason !== ''
397        ? `disabled (${c.disabledReason})`
398        : c.isEnabled
399          ? c.isPaused
400            ? PAUSE_NOTE
401            : 'active'
402          : 'stopped (start with /cache-warm start)',
403      ...(c.expiresAt === null ? ['no turn completed yet, no countdown'] : []),
404      `refreshes sent: ${c.totalRefreshCount ?? 0}`,
405      `cold prompts (estimated): ${c.coldPromptCount ?? 0}`,
406      ...(DEBUG_WARNINGS
407        ? [`unexpected rewrites (estimated): ${c.rewriteCount ?? 0}`]
408        : []),
409      `cache lifetime ${CACHE_TTL_MS / 60_000} min, ` +
410        `refresh lead ${REFRESH_LEAD_MS / 1000} s, ` +
411        `idle limit ${IDLE_LIMIT_MS / 60_000} min`,
412    ].join('\n')
413    return { text }
414  })
415
416  // A turn starts here and ends in turn.complete; refreshes stay out in between.
417  // A prompt that arrives after the expiry rewrites the cache at full price: count it.
418  // The prompt's request goes out right after this, so the footer counts from here
419  // (requestStartedAt) until the first step has ended. expiresAt stays: if ESC stops
420  // the request before it reaches the cache, the old expiry is still the true one.
421  // A prompt typed while a turn runs (e.turnId is set) fires this at Enter too, but
422  // sends no request of its own: the running turn picks it up with its next step. It
423  // is the user's activity and nothing else, so the cache fields stay as they are.
424  // A prompt after /cache-warm pause ends the pause. It is not counted as cold: the
425  // user let the cache run out on purpose, as with stop.
426  on('prompt.submit', async ($, e, next) => {
427    if ((await read($, cache)).isEnabled === null) await initState($)
428    const now = await $.clock.now()
429    lastActivity = now
430    if (e.turnId !== undefined) return next(e)
431    // Ends the debugWarnings line of an earlier request.
432    if (DEBUG_WARNINGS) $.ui.status(undefined)
433    isTurnRunning = true
434    await update($, cache, (c: CacheWarm) => ({
435      ...c,
436      refreshCount: 0,
437      coldPromptCount:
438        (c.coldPromptCount ?? 0) +
439        (c.isEnabled &&
440        !c.isReset &&
441        !c.isPaused &&
442        c.expiresAt !== null &&
443        now >= c.expiresAt
444          ? 1
445          : 0),
446      isReset: false,
447      isPaused: false,
448      requestStartedAt: now,
449      note: TURN_NOTE,
450    }))
451    return next(e)
452  })
453
454  // Every model request of a turn (after each tool call, too) reads the cache and so
455  // renews its TTL, counted from the start of the request, not from the end of its
456  // answer. The footer counts from there while the step runs (requestStartedAt);
457  // without this, a step started late in the countdown would show "cold" while the
458  // cache was kept alive. expiresAt is written only after the step has ended, and
459  // only if a response arrived. usage is null when the request failed or was
460  // interrupted before the answer started (measured: ESC about 1 s after sending;
461  // after the first text it is set). Such a request may never have reached the cache,
462  // so the old expiry stays. Idle until the first turn completes: the context size
463  // is unknown before that. Subagents carry an agentId and have contexts of their own,
464  // so only the main agent (no agentId) counts. requestStartedAt is set only within a
465  // turn (isTurnRunning): turn.complete clears it, and a request outside a turn (a
466  // compaction, the refresh's fork) has no turn.complete to do that.
467  on('turn.step', async function* ($, e, next) {
468    if (e.agentId !== undefined) return yield* next(e)
469    const startedAt = await $.clock.now()
470    const before: CacheWarm = await read($, cache)
471    const isWarm =
472      before.isEnabled === true &&
473      before.expiresAt !== null &&
474      startedAt < before.expiresAt
475    if (isTurnRunning) {
476      await update($, cache, (c: CacheWarm) => ({ ...c, requestStartedAt: startedAt }))
477    }
478    const r = yield* next(e)
479    if (r.usage !== null) {
480      const now = await $.clock.now()
481      // lastInputTokens is kept even before the first turn has completed (expiresAt is
482      // still null): a refresh is compared with that turn's own steps.
483      await update($, cache, (c: CacheWarm) =>
484        c.expiresAt === null
485          ? { ...c, lastInputTokens: inputOf(r.usage) }
486          : {
487              ...c,
488              now,
489              expiresAt: startedAt + CACHE_TTL_MS,
490              lastUse: 'turn',
491              lastInputTokens: inputOf(r.usage),
492            },
493      )
494      if (DEBUG_WARNINGS && isWarm && isMostlyUncached(r.usage)) {
495        await warnRewrite($, 'turn step', r.usage, before, startedAt)
496      }
497    }
498    return r
499  })
500
501  // A compaction replaces the context, so the cached prefix no longer matches it. The
502  // compaction itself does not cache the new context (measured: the next request read
503  // only the static system prompt and tools from the cache); the next prompt does.
504  // So a successful compaction marks the cache cold (expiresAt = now) and records the
505  // new, shorter size; isReset keeps the next prompt out of the cold count, and
506  // requestStartedAt goes, or the footer would still count from the old request. A
507  // skipped or aborted compaction leaves the context, and with it the cache,
508  // unchanged. Other triggers than manual and auto are left alone.
509  on('session.compact', async ($, e, next) => {
510    if (e.agentId !== undefined || (e.trigger !== 'manual' && e.trigger !== 'auto')) {
511      return next(e)
512    }
513    isCompacting = true
514    await update($, cache, (c: CacheWarm) => ({ ...c, note: COMPACT_NOTE }))
515    try {
516      const r = await next(e)
517      if (r.skip === undefined) {
518        const now = await $.clock.now()
519        await update($, cache, (c: CacheWarm) =>
520          c.expiresAt === null
521            ? c
522            : {
523                ...c,
524                now,
525                expiresAt: now,
526                tokens: r.tokensAfter ?? 0,
527                isReset: true,
528                requestStartedAt: undefined,
529                lastInputTokens: undefined,
530              },
531        )
532      }
533      return r
534    } finally {
535      isCompacting = false
536      await update($, cache, (c: CacheWarm) =>
537        c.note === COMPACT_NOTE ? { ...c, note: '' } : c,
538      )
539    }
540  })
541
542  // The cache belongs to one model: after a switch the new model starts with an empty
543  // one, whatever the countdown says. Mark it cold, as after a compaction; the next
544  // prompt writes it and is not counted as cold (isReset). isVerified stays: it
545  // describes the gateway, not the model, and no refresh is sent while the cache is
546  // marked cold. requestStartedAt goes for the same reason as in the compaction.
547  on('classic.PostModelSwitch', async ($, e, next) => {
548    if (e.from_model !== e.to_model) {
549      const now = await $.clock.now()
550      await update($, cache, (c: CacheWarm) =>
551        c.expiresAt === null
552          ? c
553          : {
554              ...c,
555              now,
556              expiresAt: now,
557              isReset: true,
558              requestStartedAt: undefined,
559              lastInputTokens: undefined,
560            },
561      )
562    }
563    return next(e)
564  })
565
566  // Adds one entry to the footer's mode labels (SessionMode). Redrawn whenever the
567  // atom changes.
568  on('ui.render', { component: 'SessionMode' }, async ($, e, next) => {
569    const text = describe(await read($, cache))
570    if (text === undefined) return next(e)
571    return next({ ...e, props: { ...e.props, modes: [...e.props.modes, text] } })
572  })
573
574  // The cache lives from the start of the turn's last request (requestStartedAt), not
575  // from the end of its answer: a long answer has used up part of the lifetime. Without
576  // requestStartedAt (cleared by a compaction, model switch or /clear during the turn)
577  // the end of the turn is the fallback. An interrupted turn may or may not have
578  // reached the cache; keep the old expiry. An answer has written the cache, so a
579  // reset by an automatic compaction in the middle of the turn is spent: isReset ends
580  // here, not only at the next prompt.
581  on('turn.complete', async ($, e, next) => {
582    if (e.agentId !== undefined) return next(e)
583    isTurnRunning = false
584    const now = await $.clock.now()
585    const isAnswer = Boolean(e.usage) && e.reason === 'answer'
586    let tokens = 0
587    if (isAnswer) {
588      // Neither e.usage nor context.tokens is the live context: both sum several
589      // requests. The status line's percentage of the window is.
590      const { context } = await $.session.usage()
591      tokens = Math.round(((context.percent ?? 0) / 100) * context.window)
592      if (lastActivity === 0) lastActivity = now
593    }
594    // One write, so the footer never shows the turn as over with the old expiry.
595    await update($, cache, (c: CacheWarm) => ({
596      ...c,
597      ...(isAnswer
598        ? {
599            expiresAt: (c.requestStartedAt ?? now) + CACHE_TTL_MS,
600            now,
601            tokens,
602            isReset: false,
603          }
604        : {}),
605      requestStartedAt: undefined,
606      note: c.note === TURN_NOTE ? '' : c.note,
607    }))
608    if (isAnswer && (await read($, cache)).isEnabled) {
609      timer ??= $.clock.every(1000, () => void tick($))
610    }
611    return next(e)
612  })
613}
614

1export type CacheWarm = {
2  expiresAt: number | null
3  now: number
4  tokens: number
5  // why the mod cannot run (env variable or failed verification); '' when it can
6  disabledReason: string
7  // null until session.start decides it from the autoStart option
8  isEnabled: boolean | null
9  isVerified: boolean
10  lastRefreshMs?: number
11  refreshCount: number
12  totalRefreshCount: number
13  coldPromptCount: number
14  // the host emptied the cache (compaction, model switch) and no answer has written it
15  // since; the next prompt pays for that whether or not the cache was kept warm, so it
16  // is not counted as cold
17  isReset?: boolean
18  // when the latest model request of the running turn started (the prompt's time
19  // until the first one does); set only while a turn runs. The server counts the
20  // cache lifetime from the start of the last request that read or wrote the cache.
21  requestStartedAt?: number
22  // /cache-warm pause: no refreshes until the next prompt, which is not counted as cold
23  isPaused?: boolean
24  // debugWarnings: requests that read under half their input from a cache that looked
25  // warm
26  rewriteCount?: number
27  // what made the latest request that renewed the cache; named in the debugWarnings
28  // line
29  lastUse?: 'turn' | 'refresh'
30  // input (read, written and uncached) of the latest model request of a turn; what a
31  // refresh's cache read is compared with. Unset after a compaction or a model switch,
32  // when the old size no longer fits.
33  lastInputTokens?: number
34  note: string
35}
36
37declare module 'claude-code' {
38  interface PluginState {
39    'cache-warm': { cache: CacheWarm }
40  }
41}
42