cache-frio

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Sessao } from '../types'
5
6const NOVA: Sessao = { fim: 0, ctx: 0, hit: null, rodando: false, avisadoEm: 0, liberado: false }
7const sessao = atom({ plugin: 'cache-frio', key: 'sessao' } as const, NOVA)
8
9const TTL_PADRAO_MIN = 60
10const CTX_MINIMO = 100_000
11const JANELA_SEGUNDO_ENVIO_MS = 3 * 60_000
12const MINUTO = 60_000
13// Fim do último turno, ctx e hit por id de sessão, para a retomada depois de
14// relançar o app; `$.clock.now()` é ms desde a época, comparável entre processos.
15const CHAVE_SESSAO = 'sessao:'
16const MAX_SESSOES = 30
17
18type Guardada = Pick<Sessao, 'fim' | 'ctx' | 'hit'>
19
20const k = (tokens: number) => `${Math.round(tokens / 1000)}k`
21
22const duracao = (ms: number) => {
23  const min = Math.floor(ms / MINUTO)
24
25  return min < 60 ? `${min} min` : `${Math.floor(min / 60)}h${String(min % 60).padStart(2, '0')}`
26}
27
28let ttlMin = TTL_PADRAO_MIN
29let avisa = true
30
31const cache = (s: Sessao, agora: number) => {
32  const resta = s.rodando ? ttlMin * MINUTO : s.fim + ttlMin * MINUTO - agora
33
34  return resta > 0 ? `cache ${Math.ceil(resta / MINUTO)}min` : 'cache frio'
35}
36
37async function linha($: EngineInterface) {
38  const s = await read($, sessao)
39
40  if (s.fim === 0) {
41    return undefined
42  }
43
44  const texto = cache(s, await $.clock.now())
45  const comCtx = s.ctx > 0 ? `ctx ${k(s.ctx)} · ${texto}` : texto
46
47  return s.hit != null ? `${comCtx} · ${s.hit}% hit` : comCtx
48}
49
50async function guarda($: EngineInterface, s: Sessao) {
51  const feita: Guardada = { fim: s.fim, ctx: s.ctx, hit: s.hit ?? null }
52  await $.store.set(CHAVE_SESSAO + (await $.session.id()), feita)
53}
54
55async function restaura($: EngineInterface) {
56  const feita = (await $.store.get(CHAVE_SESSAO + (await $.session.id()))) as Guardada | undefined
57
58  if (feita !== undefined) {
59    await update($, sessao, s => (feita.fim > s.fim ? { ...NOVA, ...feita } : s))
60  }
61}
62
63// O contexto encolheu: o ctx conhecido zera até o próximo turno.
64async function zeraCtx($: EngineInterface) {
65  const s = await read($, sessao)
66  const zerada: Sessao = { ...s, ctx: 0 }
67  await update($, sessao, () => zerada)
68
69  if (s.fim > 0) {
70    await guarda($, zerada)
71  }
72}
73
74async function poda($: EngineInterface) {
75  const chaves = (await $.store.keys()).filter(chave => chave.startsWith(CHAVE_SESSAO))
76
77  if (chaves.length <= MAX_SESSOES) {
78    return
79  }
80
81  const fins = await Promise.all(
82    chaves.map(async chave => ({ chave, fim: ((await $.store.get(chave)) as Guardada).fim })),
83  )
84  fins.sort((a, b) => b.fim - a.fim)
85  await Promise.all(fins.slice(MAX_SESSOES).map(velha => $.store.delete(velha.chave)))
86}
87
88export const register: Register = on => {
89  on('session.start', async ($, e, next) => {
90    ttlMin = Number(await $.store.get('ttl')) || TTL_PADRAO_MIN
91    avisa = (await $.store.get('aviso')) !== false
92    await $.command.register({
93      name: 'cache-frio',
94      description: 'Aviso de cache frio: estado, ttl em minutos, off e on',
95      argumentHint: '[ttl <minutos> | off | on]',
96    })
97    await restaura($)
98    await poda($)
99
100    return next(e)
101  })
102
103  on('command.run', { command: 'cache-frio' }, async ($, e) => {
104    const [acao, valor] = e.args.trim().toLowerCase().split(/\s+/)
105
106    if (acao === 'ttl') {
107      const min = Number(valor)
108
109      if (!Number.isInteger(min) || min < 1) {
110        return { text: 'Use /cache-frio ttl <minutos>, com um número inteiro a partir de 1.' }
111      }
112
113      ttlMin = min
114      await $.store.set('ttl', min)
115    } else if (acao === 'off' || acao === 'on') {
116      avisa = acao === 'on'
117      await $.store.set('aviso', avisa)
118    } else if (acao) {
119      return { text: 'Use /cache-frio, /cache-frio ttl <minutos>, /cache-frio off ou /cache-frio on.' }
120    }
121
122    const estado = (await linha($)) ?? 'sem turno nesta sessão ainda'
123
124    return { text: `${estado} · ttl ${ttlMin} min · aviso ${avisa ? 'ligado' : 'desligado'}` }
125  })
126
127  on('turn.start', async ($, e, next) => {
128    await update($, sessao, s => ({ ...s, rodando: true }))
129
130    return next(e)
131  })
132
133  // O uso de `turn.complete` soma todas as requisições do turno: serve para o
134  // hit, não para o ctx, que é o `context.tokens` da sessão (última requisição).
135  on('turn.complete', async ($, e, next) => {
136    if (e.agentId === undefined) {
137      const [agora, uso, s] = await Promise.all([$.clock.now(), $.session.usage(), read($, sessao)])
138      const lidos = e.usage?.cache_read_input_tokens ?? 0
139      const entrada = lidos + (e.usage?.cache_creation_input_tokens ?? 0) + (e.usage?.input_tokens ?? 0)
140      const fechada: Sessao = {
141        ...NOVA,
142        fim: agora,
143        ctx: uso.context.tokens ?? s.ctx,
144        hit: entrada > 0 ? Math.round((100 * lidos) / entrada) : (s.hit ?? null),
145      }
146      await update($, sessao, () => fechada)
147      await guarda($, fechada)
148    }
149
150    return next(e)
151  })
152
153  on('session.compact', async ($, e, next) => {
154    const feito = await next(e)
155
156    if (e.agentId === undefined && e.trigger !== 'precompute' && feito.skip === undefined) {
157      await zeraCtx($)
158    }
159
160    return feito
161  })
162
163  // A sessão que segue (depois de /clear, de uma retomada ou de relançar o app)
164  // tem outro histórico: o estado zera e volta do store pelo id dela.
165  on('session.end', async ($, e, next) => {
166    await update($, sessao, () => NOVA)
167
168    return next(e)
169  })
170
171  on('prompt.submit', async ($, e, next) => {
172    // Só o Enter do usuário com a sessão ociosa (`composer` no terminal, `sdk` no
173    // app desktop); comando de barra passa, para /compact e /clear nunca serem segurados.
174    const doUsuario = e.origin.kind === 'composer' || e.origin.kind === 'sdk'
175
176    if (!avisa || !doUsuario || e.turnId !== undefined || e.text.startsWith('/')) {
177      return next(e)
178    }
179
180    let s = await read($, sessao)
181
182    // Retomada sem `session.start` (troca de sessão no mesmo processo).
183    if (s.fim === 0) {
184      await restaura($)
185      s = await read($, sessao)
186    }
187
188    if (s.fim === 0 || s.liberado || s.ctx <= CTX_MINIMO) {
189      return next(e)
190    }
191
192    const agora = await $.clock.now()
193    const parado = agora - s.fim
194
195    if (parado <= ttlMin * MINUTO) {
196      return next(e)
197    }
198
199    const libera = () => update($, sessao, x => ({ ...x, liberado: true }))
200
201    if (s.avisadoEm > 0 && agora - s.avisadoEm <= JANELA_SEGUNDO_ENVIO_MS) {
202      await libera()
203
204      return next(e)
205    }
206
207    const custo = `Cache frio: parado há ${duracao(parado)}. Este envio regrava ~${k(s.ctx)} tokens.`
208    const temAnexo = (e.attachments?.length ?? 0) > 0
209    // Só segura o envio com o texto já de volta no campo: anexo não volta por
210    // `prompt.fill`, e um campo que recusa o texto também não (diálogo aberto, ou
211    // o app desktop, que não tem campo na engine: no_composer). Aí só avisa.
212    const voltou = !temAnexo && (await $.prompt.fill({ text: e.text })).isFilled
213
214    if (!voltou) {
215      await libera()
216      $.ui.toast(custo, { timeoutMs: 8000 })
217
218      return next(e)
219    }
220
221    await update($, sessao, x => ({ ...x, avisadoEm: agora }))
222
223    return { drop: `${custo} Enter de novo envia; ou compacte antes (/compact) ou abra sessão nova.` }
224  })
225}
226

1export type Sessao = {
2  /** Fim do último turno da conversa principal, em ms; 0 antes do primeiro. */
3  fim: number
4  /** Tokens de entrada da última requisição principal; 0 quando desconhecido. */
5  ctx: number
6  /** Parte da entrada do último turno principal lida do cache, de 0 a 100; null sem dado. */
7  hit: number | null
8  rodando: boolean
9  /** Quando o envio frio foi segurado, em ms; 0 se ainda não foi. */
10  avisadoEm: number
11  /** O período frio atual já foi avisado e liberado. */
12  liberado: boolean
13}
14
15declare module 'claude-code' {
16  interface PluginState {
17    'cache-frio': {
18      sessao: Sessao
19    }
20  }
21}
22