ratchet

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, SessionContextUsage } from 'claude-code'
3
4import type { AgentReading, TaskCost } from './types'
5import {
6  agentWindow,
7  agentsTail,
8  bar,
9  categoryColors,
10  CELESTIAL,
11  cappedPath,
12  cells,
13  compact,
14  fillColor,
15  inputTokens,
16  lastDelta,
17  pushHistory,
18  reached,
19  recordStep,
20  shortType,
21  sparkline,
22  statusLine,
23  taskCost,
24  toReading,
25  topConsumers,
26  turnsToCompact,
27} from './meter'
28
29const PANE = 'context-meter'
30
31const reading = atom({ plugin: 'ratchet', key: 'contextReading' } as const, null)
32const alerted = atom({ plugin: 'ratchet', key: 'contextAlerted' } as const, 0)
33const agents = atom({ plugin: 'ratchet', key: 'contextAgents' } as const, {})
34const history = atom({ plugin: 'ratchet', key: 'contextHistory' } as const, [])
35const task = atom({ plugin: 'ratchet', key: 'contextTask' } as const, null)
36// Whether the session opted in to ratchet; decided again on every session.start.
37const metered = atom({ plugin: 'ratchet', key: 'contextMetered' } as const, false)
38
39/** The directory and each ancestor, nearest first, splitting on both separators. */
40export function ancestors(cwd: string): string[] {
41  const parts = cwd.split(/[\\/]/)
42  const dirs: string[] = []
43  for (let n = parts.length; n >= 1; n--) {
44    const dir = parts.slice(0, n).join('/')
45    dirs.push(dir === '' ? '/' : dir)
46  }
47  return dirs
48}
49
50async function optedIn($: EngineInterface, cwd: string): Promise<boolean> {
51  for (const dir of ancestors(cwd)) {
52    try {
53      const stat = await $.fs.stat(`${dir === '/' ? '' : dir}/ratchet.toml`)
54      if (stat.kind === 'file') return true
55    } catch {
56      // A stat that rejects counts as absent.
57    }
58  }
59  return false
60}
61
62/** The plugin's own binary: `ratchet.exe` where it exists as a file (Windows), else `ratchet`. */
63async function binary($: EngineInterface): Promise<string> {
64  const exe = `${$.plugin.root}/bin/ratchet.exe`
65  try {
66    if ((await $.fs.stat(exe)).kind === 'file') return exe
67  } catch {
68    // A stat that rejects counts as absent.
69  }
70  return `${$.plugin.root}/bin/ratchet`
71}
72
73/** A command's stdout, or the whole output from the file when ratchet capped it. */
74async function fullOutput($: EngineInterface, stdout: string): Promise<string> {
75  const path = cappedPath(stdout)
76
77  return path === null ? stdout : await $.fs.read(path)
78}
79
80/**
81 * Reads what the held task has cost so far; off the hot path, on session start and /ctx only:
82 * a report past ratchet's output cap leaves a file under ~/.ratchet/out on every read.
83 */
84async function refreshTask($: EngineInterface): Promise<void> {
85  try {
86    const ratchet = await binary($)
87    const session = await $.session.id()
88    const listed = await $.process.run([ratchet, 'task', 'list', '--mine', '--json', '--session', session], {
89      timeoutMs: 15_000,
90    })
91    if (listed.exitCode !== 0) return
92    const held = (JSON.parse(await fullOutput($, listed.stdout)) as { id: string; title: string; status: string }[]).find(
93      one => one.status === 'in_progress',
94    )
95    if (held === undefined) {
96      await update($, task, () => null)
97      return
98    }
99    const used = await $.process.run([ratchet, 'usage', held.id, '--json'], { timeoutMs: 30_000 })
100    if (used.exitCode !== 0) return
101    const cost = taskCost(JSON.parse(await fullOutput($, used.stdout)), held.id)
102    // A report with nothing for the task keeps the last figures.
103    if (cost !== null) await update($, task, () => ({ id: held.id, title: held.title, ...cost }))
104  } catch {
105    // The meter never fails the session; the pane keeps the last figures.
106  }
107}
108
109async function running($: EngineInterface): Promise<AgentReading[]> {
110  const readings = await read($, agents)
111  const listed = await $.agent.list()
112
113  return listed
114    .filter(agent => agent.status === 'running')
115    .flatMap(agent => readings[agent.id] ?? [])
116}
117
118async function pin($: EngineInterface): Promise<void> {
119  const now = await read($, reading)
120  if (now === null) return
121  const turns = await read($, history)
122  // A failing agent list leaves the line without its tail.
123  const tail = await running($).then(
124    list => agentsTail(list, now.window),
125    () => '',
126  )
127  $.ui.status(statusLine(now) + lastDelta(turns) + tail)
128}
129
130async function show($: EngineInterface, context: SessionContextUsage): Promise<void> {
131  const now = toReading(context)
132
133  const level = reached(now.percent)
134  const before = await read($, alerted)
135  if (level > before) {
136    $.ui.toast(`Context at ${now.percent}%: run /compact, or write a handoff with ratchet task handoff and continue in a fresh session`, {
137      timeoutMs: 8000,
138    })
139  }
140  // A drop (compaction, /clear) re-arms the thresholds below it.
141  if (level !== before) await update($, alerted, () => level)
142
143  await update($, reading, () => now)
144  await pin($)
145}
146
147export const register: Register = on => {
148  on('session.start', async ($, e, next) => {
149    try {
150      const opted = await optedIn($, e.cwd)
151      await update($, metered, () => opted)
152      if (opted) {
153        // Without the command the line is still worth pinning.
154        await $.command
155          .register({
156            name: 'ctx',
157            description: 'Show the context window broken down by category, live, in a pane',
158            immediate: true,
159          })
160          .catch(() => undefined)
161        void refreshTask($)
162        await show($, (await $.session.usage()).context)
163      }
164    } catch {
165      // The meter never fails the session.
166    }
167
168    return next(e)
169  })
170
171  on('command.run', { command: 'ctx' }, async $ => {
172    await $.ui.open({ id: PANE, title: 'Context' })
173    void refreshTask($)
174
175    return { text: 'Context pane opened.' }
176  })
177
178  on('session.measure', async ($, e, next) => {
179    if (e.changed.includes('context') && (await read($, metered))) {
180      try {
181        // One point per turn: the trend and the status line's move read these.
182        const tokens = e.context.tokens
183        if (tokens !== undefined) await update($, history, all => pushHistory(all, tokens))
184      } catch {
185        // A failed history must not keep the line from refreshing.
186      }
187      try {
188        await show($, e.context)
189      } catch {
190        // The meter never fails the session.
191      }
192    }
193
194    return next(e)
195  })
196
197  // A /clear empties the window: what was tracked for the old one goes with it.
198  on('session.end', async ($, e, next) => {
199    if (e.reason === 'clear') {
200      try {
201        await update($, agents, () => ({}))
202        await update($, history, () => [])
203        await update($, task, () => null)
204      } catch {
205        // The meter never fails the session.
206      }
207    }
208
209    return next(e)
210  })
211
212  // Every model request, main or subagent, reports what it was answered over:
213  // the main loop's moves the status line within a turn, a subagent's is the
214  // only window onto that agent's context.
215  on('turn.step', async function* ($, e, next) {
216    const result = yield* next(e)
217    if (result.usage === null || result.usage === undefined) return result
218
219    try {
220      if (!(await read($, metered))) return result
221      const tokens = inputTokens(result.usage)
222      if (e.agentId === undefined) {
223        const { window } = (await $.session.usage()).context
224        await show($, { window, tokens, percent: Math.round((tokens / window) * 100) })
225      } else {
226        const id = e.agentId
227        const at = await $.clock.now()
228        const who = await $.agent.list().then(
229          list => list.find(agent => agent.id === id),
230          () => undefined,
231        )
232        await update($, agents, all => recordStep(all, id, tokens, result.usage?.model ?? '', at, who))
233        await pin($)
234      }
235    } catch {
236      // The meter never fails a model request.
237    }
238
239    return result
240  })
241
242  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
243    const { Box, Text } = $.ui.resolve(e)
244    try {
245      // Read to subscribe: each new reading redraws the pane.
246      await read($, reading)
247      const readings = await read($, agents)
248      const turns = await read($, history)
249      const held = await read($, task)
250      const said = await $.session.messages({ as: 'api' }).catch(() => [])
251      const consumers = topConsumers(Array.isArray(said) ? said : [], 5)
252      const context = await $.session.usage({ breakdown: 'summary' }).then(
253        usage => usage.context,
254        () => undefined,
255      )
256      const breakdown = context?.breakdown
257
258      if (context === undefined || breakdown === undefined) {
259        return <Text dimColor>No breakdown yet: it arrives with the first response.</Text>
260      }
261
262      const rows = breakdown.categories.filter(row => row.kind !== 'deferred')
263      const width = Math.max(10, e.props.bodyColumns - 2)
264      const widths = cells(
265        rows.map(row => row.tokens),
266        breakdown.rawMaxTokens,
267        width,
268      )
269      const nameWidth = Math.max(...rows.map(row => row.name.length))
270      const colors = categoryColors(rows.map(row => row.kind))
271      // The agent list drops an agent once it is done; the readings keep who it was.
272      const listed = await $.agent.list().catch(() => [])
273      const isRunning = new Set(listed.filter(agent => agent.status === 'running').map(agent => agent.id))
274      const roleCells = held === null ? [] : cells(held.roles.map(role => role.tokens), held.total, width)
275      const recent = Object.entries(readings).sort(([, a], [, b]) => b.at - a.at)
276
277      return (
278        <Box flexDirection="column">
279          <Text bold>
280            <Text color={fillColor(breakdown.percentage)}>{breakdown.percentage}%</Text> · {compact(breakdown.totalTokens)} /{' '}
281            {compact(breakdown.rawMaxTokens)}
282            <Text dimColor> {breakdown.model}</Text>
283          </Text>
284          <Box flexDirection="row">
285            {rows.map((row, i) => (
286              <Text color={colors[i]} dimColor={row.kind === 'free'}>
287                {(row.kind === 'used' ? '█' : row.kind === 'buffer' ? '▒' : '░').repeat(widths[i] ?? 0)}
288              </Text>
289            ))}
290          </Box>
291          {rows.map((row, i) => (
292            <Box flexDirection="row">
293              <Text color={colors[i]}>{row.kind === 'used' ? '■ ' : '□ '}</Text>
294              <Text dimColor={row.kind !== 'used'}>
295                {row.name.padEnd(nameWidth)} {compact(row.tokens).padStart(5)}{' '}
296                {((row.tokens / breakdown.rawMaxTokens) * 100).toFixed(1).padStart(5)}%
297              </Text>
298            </Box>
299          ))}
300          {breakdown.isAutoCompactEnabled && breakdown.autoCompactThreshold !== undefined && (
301            <Text dimColor>auto-compact at {compact(breakdown.autoCompactThreshold)}</Text>
302          )}
303          {turns.length > 1 && (
304            <Text bold color={CELESTIAL.accent}>
305              Trend
306            </Text>
307          )}
308          {turns.length > 1 && (
309            <Text>
310              <Text color={fillColor(breakdown.percentage)}>{sparkline(turns, context.window, width - lastDelta(turns).length)}</Text>
311              {lastDelta(turns)}
312            </Text>
313          )}
314          {turns.length > 1 && breakdown.autoCompactThreshold !== undefined && (
315            <Text dimColor>
316              {(() => {
317                const left = turnsToCompact(turns, breakdown.autoCompactThreshold)
318                if (left === null) return 'not growing'
319                if (left === 0) return 'at the auto-compact threshold'
320                return `~${left} turn${left === 1 ? '' : 's'} to auto-compact at this pace`
321              })()}
322            </Text>
323          )}
324          {consumers.length > 0 && (
325            <Text bold color={CELESTIAL.accent}>
326              Top consumers
327            </Text>
328          )}
329          {consumers.map((one, i) => (
330            <Box flexDirection="row">
331              <Text color={CELESTIAL.series[i % CELESTIAL.series.length]}>{one.tool.padEnd(6)} </Text>
332              <Text wrap="truncate-end">
333                {compact(one.tokens).padStart(5)} {one.label}{' '}
334              </Text>
335            </Box>
336          ))}
337          {consumers.some(one => one.tool === 'Read' && one.tokens >= 5_000) && (
338            <Text dimColor>→ reads this size can go to ratchet:reader</Text>
339          )}
340          {held !== null && held.total > 0 && (
341            <Text bold color={CELESTIAL.accent}>
342              {held.id} <Text dimColor>· {compact(held.total)} tokens so far</Text>
343            </Text>
344          )}
345          {held !== null && held.total > 0 && (
346            <Box flexDirection="row">
347              {roleCells.map((count, i) => (
348                <Text color={CELESTIAL.series[i % CELESTIAL.series.length]}>{'█'.repeat(count)}</Text>
349              ))}
350            </Box>
351          )}
352          {held !== null && held.total > 0 && (
353            <Text wrap="truncate-end">
354              {held.roles.slice(0, 4).map((role, i) => (
355                <Text color={CELESTIAL.series[i % CELESTIAL.series.length]}>
356                  {i > 0 ? ' · ' : ''}
357                  {shortType(role.role)} {Math.round((role.tokens / held.total) * 100)}%
358                </Text>
359              ))}
360            </Text>
361          )}
362          {recent.length > 0 && (
363            <Text bold color={CELESTIAL.accent}>
364              Subagents
365            </Text>
366          )}
367          {recent.map(([id, one]) => {
368            const isLive = isRunning.has(id)
369            const window = agentWindow(one.peak, context.window)
370            const percent = Math.round((one.tokens / window) * 100)
371            const peak = one.peak > one.tokens ? ` · peak ${compact(one.peak)}` : ''
372            const numbers = ` ${percent}% · ${compact(one.tokens)}/${compact(window)} · ${one.steps} req${peak}`
373            const room = Math.max(6, Math.min(20, e.props.bodyColumns - 2 - numbers.length))
374            return (
375              <Box flexDirection="column">
376                <Text dimColor={!isLive} wrap="truncate-end">
377                  {isLive ? '● ' : '○ '}
378                  <Text bold>{one.type}</Text>
379                  {one.description ? `  ${one.description}` : ''}
380                </Text>
381                <Box flexDirection="row">
382                  <Text>{'  '}</Text>
383                  <Text color={fillColor(percent)} dimColor={!isLive}>
384                    {bar(percent, room)}
385                  </Text>
386                  <Text dimColor={!isLive}>{numbers}</Text>
387                </Box>
388              </Box>
389            )
390          })}
391        </Box>
392      )
393    } catch {
394      // Whatever fails while drawing, the pane still says something.
395      return <Text dimColor>No breakdown yet: it arrives with the first response.</Text>
396    }
397  })
398}
399

1import type { ModelUsage, SessionContextUsage } from 'claude-code'
2
3import type { AgentReading, Reading } from './types'
4
5export const THRESHOLDS = [70, 85]
6const AGENTS_KEPT = 20
7
8/** What a request was answered over: uncached, cache-written and cache-read input together. */
9export function inputTokens(usage: ModelUsage): number {
10  return usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens
11}
12
13/**
14 * The window a subagent runs in. The engine reports none per agent, so take the
15 * session model's window, or the agent's peak when it went past that.
16 */
17export function agentWindow(peak: number, sessionWindow: number): number {
18  return Math.max(peak, sessionWindow)
19}
20
21/** The Celestial theme's palette (a darker Horizon), by role. */
22export const CELESTIAL = {
23  calm: '#29D398',
24  warm: '#FAB795',
25  hot: '#E95678',
26  accent: '#B877DB',
27  muted: '#6C6F93',
28  series: ['#26BBD9', '#B877DB', '#F09483', '#EE64AC', '#59E1E3', '#FAB795', '#29D398'],
29} as const
30
31/** The colour of a fill: calm, then warm at the first threshold, hot at the second. */
32export function fillColor(percent: number): string {
33  if (percent >= THRESHOLDS[1]!) return CELESTIAL.hot
34  if (percent >= THRESHOLDS[0]!) return CELESTIAL.warm
35
36  return CELESTIAL.calm
37}
38
39/** One colour per breakdown row: the series for what is used, muted for the buffer and free space. */
40export function categoryColors(kinds: readonly string[]): string[] {
41  let used = 0
42
43  return kinds.map(kind =>
44    kind === 'used' ? CELESTIAL.series[used++ % CELESTIAL.series.length]! : CELESTIAL.muted,
45  )
46}
47
48/** Folds one request of a subagent into the readings, keeping the most recent few. */
49export function recordStep(
50  agents: Record<string, AgentReading>,
51  id: string,
52  tokens: number,
53  model: string,
54  at: number,
55  who?: { type: string; description: string },
56): Record<string, AgentReading> {
57  const before = agents[id]
58  const next = {
59    ...agents,
60    [id]: {
61      tokens,
62      peak: Math.max(tokens, before?.peak ?? 0),
63      steps: (before?.steps ?? 0) + 1,
64      model,
65      at,
66      type: who?.type ?? before?.type ?? 'agent',
67      description: who?.description ?? before?.description ?? '',
68    },
69  }
70  // Ties on `at` keep the agent just updated.
71  const kept = Object.entries(next)
72    .sort(([keyA, a], [keyB, b]) => b.at - a.at || Number(keyB === id) - Number(keyA === id))
73    .slice(0, AGENTS_KEPT)
74
75  return Object.fromEntries(kept)
76}
77
78/** An agent type without its plugin prefix: `ratchet:reader` reads `reader`. */
79export function shortType(type: string): string {
80  return type.slice(type.indexOf(':') + 1)
81}
82
83const TAIL_AGENTS = 3
84
85/** The status line's tail: a small bar per running subagent, the fullest first, `+N` past three. */
86export function agentsTail(running: readonly AgentReading[], sessionWindow: number): string {
87  if (running.length === 0) return ''
88  const shown = [...running].sort((a, b) => b.tokens - a.tokens).slice(0, TAIL_AGENTS)
89  const parts = shown.map(agent => {
90    const percent = Math.round((agent.tokens / agentWindow(agent.peak, sessionWindow)) * 100)
91    return `${shortType(agent.type)} ${bar(percent, 5)} ${percent}%`
92  })
93  const more = running.length > shown.length ? ` +${running.length - shown.length}` : ''
94
95  return ` │ ${parts.join(' · ')}${more}`
96}
97
98export function compact(tokens: number): string {
99  if (tokens >= 1_000) {
100    const thousands = Math.round(tokens / 1_000)
101    // 999600 rounds to 1000k: that is a million.
102    if (thousands < 1_000) return `${thousands}k`
103    return `${(tokens / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`
104  }
105
106  return String(tokens)
107}
108
109export function bar(percent: number, width: number): string {
110  const filled = Math.max(0, Math.min(width, Math.round((percent / 100) * width)))
111
112  return '█'.repeat(filled) + '░'.repeat(width - filled)
113}
114
115export function toReading(context: SessionContextUsage): Reading {
116  return {
117    tokens: context.tokens ?? null,
118    window: context.window,
119    percent: context.percent ?? null,
120  }
121}
122
123export function statusLine(reading: Reading): string {
124  if (reading.tokens === null || reading.percent === null) {
125    return `ctx ${bar(0, 10)} –/${compact(reading.window)}`
126  }
127
128  return `ctx ${bar(reading.percent, 10)} ${reading.percent}% · ${compact(reading.tokens)}/${compact(reading.window)}`
129}
130
131/** The highest threshold the fill has reached; 0 below all of them or with no reading. */
132export function reached(percent: number | null): number {
133  return THRESHOLDS.filter(t => (percent ?? 0) >= t).at(-1) ?? 0
134}
135
136/** Splits `width` cells among `parts` in proportion to `total`, rounding cumulatively so the cells add up. */
137export function cells(parts: readonly number[], total: number, width: number): number[] {
138  let sum = 0
139  let start = 0
140
141  return parts.map(part => {
142    sum += part
143    const end = Math.min(width, Math.round((sum / total) * width))
144    const count = Math.max(0, end - start)
145    start = Math.max(start, end)
146    return count
147  })
148}
149
150const HISTORY_KEPT = 60
151const LEVELS = '▁▂▃▄▅▆▇█'
152
153/** Appends one turn's main-window tokens, keeping the most recent sixty. */
154export function pushHistory(history: readonly number[], tokens: number): number[] {
155  return [...history, tokens].slice(-HISTORY_KEPT)
156}
157
158/** The last turn's move, `+12k` or `-30k`; empty with fewer than two turns or no move. */
159export function lastDelta(history: readonly number[]): string {
160  const last = history.at(-1)
161  const before = history.at(-2)
162  if (last === undefined || before === undefined || last === before) return ''
163
164  return last > before ? ` +${compact(last - before)}` : ` -${compact(before - last)}`
165}
166
167/** One block per turn, its height the window's fill at that turn. */
168export function sparkline(history: readonly number[], window: number, width: number): string {
169  return history
170    .slice(-width)
171    .map(tokens => LEVELS[Math.min(7, Math.floor((tokens / window) * 8))])
172    .join('')
173}
174
175/**
176 * Turns left before auto-compaction at the pace of the last few turns since the
177 * window last shrank (a compaction or /clear); null when it is not growing.
178 */
179export function turnsToCompact(history: readonly number[], threshold: number): number | null {
180  const growth: number[] = []
181  for (let i = history.length - 1; i > 0 && growth.length < 5; i--) {
182    const step = history[i]! - history[i - 1]!
183    if (step < 0) break
184    growth.push(step)
185  }
186  const pace = growth.reduce((a, b) => a + b, 0) / Math.max(1, growth.length)
187  const now = history.at(-1) ?? 0
188  if (now >= threshold) return 0
189  if (pace <= 0) return null
190
191  return Math.ceil((threshold - now) / pace)
192}
193
194/** A rough token count of a tool result as the model read it: four characters a token. */
195export function estimateTokens(text: string): number {
196  return Math.ceil(text.length / 4)
197}
198
199/** What a tool call was about, in a few words: the file, the command, the pattern. */
200export function toolLabel(tool: string, input: Record<string, unknown>): string {
201  const text = (key: string) => (typeof input[key] === 'string' ? (input[key] as string) : '')
202  const path = text('file_path') || text('notebook_path') || text('path')
203  if (path !== '') return path.split(/[\\/]/).slice(-3).join('/')
204  const command = text('command').split('\n')[0] ?? ''
205  if (command !== '') return command.length > 48 ? `${command.slice(0, 47)}…` : command
206
207  return text('pattern') || text('url') || text('description') || text('subagent_type') || text('query')
208}
209
210export type Consumer = { tool: string; label: string; tokens: number }
211
212type ApiBlock = { type: string; [field: string]: unknown }
213
214/** A tool result's text: its content when a string, else its text blocks joined. */
215function resultText(content: unknown): string {
216  if (typeof content === 'string') return content
217  if (!Array.isArray(content)) return ''
218
219  return (content as ApiBlock[])
220    .filter(block => block.type === 'text' && typeof block.text === 'string')
221    .map(block => block.text as string)
222    .join('')
223}
224
225/** The heaviest tool results among Messages API messages, largest first. */
226export function topConsumers(messages: readonly { role: string; content: readonly ApiBlock[] }[], count: number): Consumer[] {
227  const blocks = messages.flatMap(message => (Array.isArray(message.content) ? message.content : []))
228  const uses = new Map<string, { name: string; input: Record<string, unknown> }>()
229  for (const block of blocks) {
230    if (block.type === 'tool_use' && typeof block.id === 'string') {
231      uses.set(block.id, { name: String(block.name), input: (block.input ?? {}) as Record<string, unknown> })
232    }
233  }
234
235  return blocks
236    .flatMap(block => {
237      const use = block.type === 'tool_result' ? uses.get(String(block.tool_use_id)) : undefined
238      if (use === undefined) return []
239      return [{ tool: use.name, label: toolLabel(use.name, use.input), tokens: estimateTokens(resultText(block.content)) }]
240    })
241    .sort((a, b) => b.tokens - a.tokens)
242    .slice(0, count)
243}
244
245/** The path a capped output names: its last non-empty line reads `… (<n> lines in <path>)`. */
246export function cappedPath(stdout: string): string | null {
247  const lines = stdout.trimEnd().split('\n')
248  const match = /^… \(\d+ lines in (.+)\)$/.exec(lines.at(-1) ?? '')
249
250  return match?.[1] ?? null
251}
252
253/** Sums `ratchet usage <id> --json`'s buckets by role, input to output (thinking is inside output). */
254export function taskCost(json: unknown, id: string): { total: number; roles: { role: string; tokens: number }[] } | null {
255  const tasks = (json as { tasks?: { id?: string; buckets?: { role?: string; tokens?: Record<string, number> }[] }[] })?.tasks
256  const task = tasks?.find(one => one.id === id)
257  if (task === undefined) return null
258  const byRole = new Map<string, number>()
259  for (const bucket of task.buckets ?? []) {
260    const t = bucket.tokens ?? {}
261    const sum = (t['input'] ?? 0) + (t['cache_write'] ?? 0) + (t['cache_read'] ?? 0) + (t['output'] ?? 0)
262    const role = bucket.role ?? 'unknown'
263    byRole.set(role, (byRole.get(role) ?? 0) + sum)
264  }
265  const roles = [...byRole].map(([role, tokens]) => ({ role, tokens })).sort((a, b) => b.tokens - a.tokens)
266
267  return { total: roles.reduce((a, r) => a + r.tokens, 0), roles }
268}
269

1export type Reading = {
2  tokens: number | null
3  window: number
4  percent: number | null
5}
6
7/** One subagent's context, as its last model request reported it. */
8export type AgentReading = {
9  tokens: number
10  peak: number
11  steps: number
12  model: string
13  at: number
14  /** Captured while the agent was still in `$.agent.list()`, which drops it once done. */
15  type: string
16  description: string
17}
18
19/** What the task this session holds has cost so far, from `ratchet usage <id> --json`. */
20export type TaskCost = {
21  id: string
22  title: string
23  total: number
24  roles: { role: string; tokens: number }[]
25}
26
27declare module 'claude-code' {
28  interface PluginState {
29    ratchet: {
30      contextReading: Reading | null
31      contextAlerted: number
32      contextAgents: Record<string, AgentReading>
33      contextHistory: number[]
34      contextTask: TaskCost | null
35      contextMetered: boolean
36    }
37  }
38}
39