band-pack

1import type { Register } from 'claude-code'
2
3import { registerBand } from './engine'
4import { watchCalls } from './hosts/calls'
5import { watchTickers } from './hosts/tickers'
6import { startSession } from './hosts/start'
7import { endTurnsWithStore } from './hosts/turn-end-store'
8import { rule as costMeter } from './rules/cost-meter'
9import { rule as latteMeter } from './rules/latte-meter'
10import { rule as contextMeter } from './rules/context-meter'
11import { rule as dailySpend } from './rules/daily-spend'
12import { rule as pomodoro } from './rules/pomodoro'
13import { rule as moodRing } from './rules/mood-ring'
14
15export const register: Register = (on, options) => {
16  const rules = [costMeter, latteMeter, contextMeter, dailySpend, pomodoro, moodRing]
17  registerBand(on, rules, options)
18  watchCalls(on, rules)
19  watchTickers(on, rules)
20  startSession(on, rules)
21  endTurnsWithStore(on, rules)
22}
23

1import { atom, read, update } from 'claude-code'
2import type { Frozen, On, PluginOptions, SessionUsage, TurnCompleteInput } from 'claude-code'
3
4import type { Fetched, GitState, Outcome, Pomodoro, Reading, Tally } from '../types'
5import { localDate } from './date'
6import { hasFetchers } from './fetch'
7import { syncMinuteTick } from './minute'
8import type { MinuteDeps } from './minute'
9import type { BandRule, Segment, Ticker, TurnEnd, TurnTokens } from './rule'
10import { startTurnTimer, stopTurnTimer } from './turn'
11import { bandTree, fitSegments } from './view'
12
13// The build writes the mod's own name in place of the token: `$.state` is
14// written only by the plugin that owns it, and the scan wants the atoms here.
15const reading = atom({ plugin: 'band-pack', key: 'reading' } as const, null)
16const turnStartUsd = atom({ plugin: 'band-pack', key: 'turnStartUsd' } as const, null)
17// The state scan wants each atom spelled in the file that reads or writes it,
18// so watch.ts spells the same two. A turn end replaces `reading` whole, which
19// is why these live apart from it.
20const outcomes = atom({ plugin: 'band-pack', key: 'outcomes' } as const, [] as readonly Outcome[])
21const pomodoro = atom({ plugin: 'band-pack', key: 'pomodoro' } as const, null as Pomodoro | null)
22// Written by tally.ts and git.ts, which spell the same atoms; read here to draw.
23const tally = atom({ plugin: 'band-pack', key: 'tally' } as const, { calls: {}, failures: 0 } as Tally)
24const git = atom({ plugin: 'band-pack', key: 'git' } as const, null as GitState | null)
25// Written by the minute tick and read to draw, so the write redraws the band.
26const minute = atom({ plugin: 'band-pack', key: 'minute' } as const, 0)
27// Written by fetch.ts and turn.ts, which spell the same atoms; read here to draw.
28const fetched = atom({ plugin: 'band-pack', key: 'fetched' } as const, {} as Readonly<Record<string, Fetched | null>>)
29const turnStartedAt = atom({ plugin: 'band-pack', key: 'turnStartedAt' } as const, null as number | null)
30
31export const failed = (where: string, error: unknown): string =>
32  `band: ${where} skipped, ${error instanceof Error ? error.message : String(error)}`
33
34export const tickersOf = (rules: readonly BandRule[]): Ticker[] =>
35  rules.flatMap(rule => (rule.ticker === undefined ? [] : [rule.ticker]))
36
37const segmentsOf = (rules: readonly BandRule[], draw: Parameters<BandRule['segment']>[0]): Segment[] =>
38  rules.flatMap(rule => {
39    try {
40      const segment = rule.segment(draw)
41      return segment === undefined ? [] : [segment]
42    } catch {
43      // A rule that throws leaves its segment out and the rest draw.
44      return []
45    }
46  })
47
48// The turn's cache tokens as the rules read them, or none when it had no usage.
49const tokensOf = (usage: { input_tokens: number; cache_read_input_tokens: number; cache_creation_input_tokens: number } | undefined): TurnTokens | undefined =>
50  usage === undefined ? undefined : { input: usage.input_tokens, cacheRead: usage.cache_read_input_tokens, cacheWrite: usage.cache_creation_input_tokens }
51
52const clampPercent = (percent: number | undefined): number | undefined =>
53  percent === undefined || !Number.isFinite(percent) ? undefined : Math.min(100, Math.max(0, percent))
54
55// The model is a read of its own: a failure leaves the figure out and the
56// rest of the turn end stands.
57const modelOf = async (read: () => Promise<string>): Promise<string | undefined> => {
58  try {
59    const model = (await read()).trim()
60    return model === '' ? undefined : model
61  } catch {
62    return undefined
63  }
64}
65
66// The tools a turn-end host does not give. A rule that calls one is logged and
67// skipped, and its tests fail: name what it uses in engine.json `needs`.
68const absent = (name: string) => (): Promise<never> =>
69  Promise.reject(new Error(`${name} is not given to this mod; name it in engine.json needs`))
70
71export const NO_MODEL: TurnIo['model'] = absent('model')
72export const NO_STORE: TurnIo['store'] = { get: absent('store'), set: absent('store') }
73
74// What a turn end reads and writes, as closures over the hook's `$`.
75// `refresh` runs the fetchers; only the host that runs programs gives it.
76export type TurnIo = {
77  usage: () => Promise<SessionUsage>
78  reading: () => Promise<Reading | null>
79  turnStartUsd: () => Promise<number | null>
80  keep: (now: Reading) => Promise<unknown>
81  spend: () => Promise<unknown>
82  endTimer: () => Promise<unknown>
83  model: () => Promise<string>
84  store: TurnEnd['store']
85  clock: Omit<MinuteDeps, 'tick'>
86  redraw: () => Promise<unknown>
87  log: (text: string) => unknown
88  refresh?: () => void
89}
90
91// The figures are read once, at the turn's end. A render hook never writes,
92// so they go into $.state for it to draw. A subagent's turn is not the
93// person's turn.
94export const turnComplete = async (rules: readonly BandRule[], e: Frozen<TurnCompleteInput>, io: TurnIo): Promise<void> => {
95  if (e.agentId !== undefined) return
96  const isFetching = hasFetchers(rules)
97  const isMinutely = isFetching || rules.some(rule => rule.everyMinute !== undefined)
98  if (rules.some(rule => rule.tracksTurn === true)) {
99    // First and on its own: a failed usage read below must not leave it running.
100    stopTurnTimer()
101    try {
102      await io.endTimer()
103    } catch (error) {
104      await io.log(failed('turn timer', error))
105    }
106  }
107  try {
108    const usage = await io.usage()
109    const usd = usage.cost?.usd
110    const percent = clampPercent(usage.context.percent)
111    const previous = await io.reading()
112    const base = (await io.turnStartUsd()) ?? previous?.usd
113    // A cost that fell (a cleared session) leaves the turn's cost unknown.
114    const turnUsd = usd !== undefined && base !== undefined && usd >= base ? usd - base : undefined
115    const date = localDate(await io.clock.now())
116    const model = await modelOf(io.model)
117
118    const usageTokens = tokensOf(e.usage)
119    let now: Reading = {
120      ...(usd === undefined ? {} : { usd }),
121      ...(turnUsd === undefined ? {} : { turnUsd }),
122      ...(percent === undefined ? {} : { percent }),
123      ...(Number.isFinite(usage.startedAt) ? { startedAt: usage.startedAt } : {}),
124      ...(model === undefined ? {} : { model }),
125    }
126    for (const rule of rules) {
127      if (rule.atTurnEnd === undefined) continue
128      try {
129        now = {
130          ...now,
131          ...(await rule.atTurnEnd({
132            reading: now,
133            previous: previous ?? {},
134            ...(usageTokens === undefined ? {} : { usage: usageTokens }),
135            turnUsd,
136            date,
137            store: io.store,
138          })),
139        }
140      } catch (error) {
141        await io.log(failed(rule.id, error))
142      }
143    }
144    await io.keep(now)
145    // Spent: a second end of the same turn adds nothing.
146    await io.spend()
147    if (isMinutely) {
148      const refresh = (): void => {
149        if (isFetching) io.refresh?.()
150      }
151      refresh()
152      await syncMinuteTick(rules, now, {
153        ...io.clock,
154        tick: async () => {
155          try {
156            refresh()
157            await io.redraw()
158          } catch (error) {
159            await io.log(failed('minute', error))
160          }
161        },
162      })
163    }
164  } catch (error) {
165    await io.log(failed('turn end', error))
166  }
167}
168
169// The hooks every band mod has: the cost as the turn begins, and the band.
170// The rest are hosts (engine.json), so a mod has only what its rules use.
171export const registerBand = (on: On, rules: readonly BandRule[], options: PluginOptions): void => {
172  const isMinutely = hasFetchers(rules) || rules.some(rule => rule.everyMinute !== undefined)
173  const isTurnTimed = rules.some(rule => rule.tracksTurn === true)
174  // The band reads the minute atom, so a tick's write redraws it: each minute,
175  // and each second while a turn runs.
176  const isTicking = isMinutely || isTurnTimed
177
178  // The cost as the turn begins: what this turn's cost is measured from.
179  on('turn.start', async ($, e, next) => {
180    try {
181      const usage = await $.session.usage()
182      await update($, turnStartUsd, () => usage.cost?.usd ?? null)
183    } catch (error) {
184      await $.ui.log(failed('turn start', error))
185    }
186    if (isTurnTimed) {
187      try {
188        // The callbacks close over `$`; they never pass it on.
189        await startTurnTimer({
190          now: () => $.clock.now(),
191          begin: at => update($, turnStartedAt, () => at),
192          every: (ms, fn) => $.clock.every(ms, fn),
193          tick: async () => {
194            try {
195              await update($, minute, n => n + 1)
196            } catch (error) {
197              await $.ui.log(failed('turn tick', error))
198            }
199          },
200        })
201      } catch (error) {
202        await $.ui.log(failed('turn timer', error))
203      }
204    }
205    return next(e)
206  })
207
208  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
209    if (e.props.hasSurvey) return next(e)
210    // A rule may draw from live state before the first turn ends.
211    const current = (await read($, reading)) ?? {}
212    const now = await $.clock.now()
213    const date = localDate(now)
214    const live = {
215      outcomes: await read($, outcomes),
216      pomodoro: await read($, pomodoro),
217      tally: await read($, tally),
218      git: await read($, git),
219      fetched: await read($, fetched),
220      turnStartedAt: await read($, turnStartedAt),
221    }
222    // Read only so its write redraws the band.
223    if (isTicking) await read($, minute)
224    const segments = fitSegments(segmentsOf(rules, { reading: current, options, date, now, ...live }), e.props.bodyColumns)
225    if (segments.length === 0) return next(e)
226
227    const { Box, Text } = $.ui.resolve(e)
228    return bandTree({ Box, Text }, segments)
229  })
230}
231

1import { atom, update } from 'claude-code'
2import type { On } from 'claude-code'
3
4import type { Outcome, Tally } from '../../types'
5import { failed } from '../engine'
6import type { BandRule } from '../rule'
7import { addCall } from '../tally'
8
9const WINDOW = 20
10
11// The same atoms as engine.tsx: the state scan wants each spelled in the
12// file that reads or writes it. The build writes the mod's own name for the token.
13const outcomes = atom({ plugin: 'band-pack', key: 'outcomes' } as const, [] as readonly Outcome[])
14const tally = atom({ plugin: 'band-pack', key: 'tally' } as const, { calls: {}, failures: 0 } as Tally)
15
16// For the rules that draw from how the tool calls ended: the recent outcomes
17// and the tally of the session. The result is passed on as it came: a denied
18// call stays denied. Only one hook may answer `tool.call` without a matcher.
19export const watchCalls = (on: On, rules: readonly BandRule[]): void => {
20  const isOutcomes = rules.some(rule => rule.tracksOutcomes === true)
21  const isTally = rules.some(rule => rule.tracksTools === true)
22
23  on('tool.call', async ($, e, next) => {
24    const ran = await next(e)
25    try {
26      const outcome: Outcome = ran.deny !== undefined ? 'block' : ran.isError === true ? 'error' : 'ok'
27      if (isOutcomes) await update($, outcomes, recent => [...recent, outcome].slice(-WINDOW))
28      if (isTally) await update($, tally, current => addCall(current, e.tool, outcome !== 'ok'))
29    } catch (error) {
30      await $.ui.log(failed('outcomes', error))
31    }
32    return ran
33  })
34}
35

1import { atom, read, update } from 'claude-code'
2import type { On, Timer } from 'claude-code'
3
4import type { Pomodoro } from '../../types'
5import { failed, tickersOf } from '../engine'
6import type { BandRule } from '../rule'
7
8// The same atom as engine.tsx: the state scan wants it spelled in the file
9// that reads or writes it. The build writes the mod's own name for the token.
10const pomodoro = atom({ plugin: 'band-pack', key: 'pomodoro' } as const, null as Pomodoro | null)
11
12// The running intervals, by command name. A handle is not drawn state, so it
13// is a module variable. A hot reload cancels the interval and keeps the state:
14// the timer then freezes until its command stops it.
15const running = new Map<string, Timer>()
16
17// For a rule with a ticker: registers its command handler and runs its
18// interval. The command starts the timer when none runs and stops it when one
19// does. The start host registers the command names (`on("session.start")`
20// takes one hook), from `tickersOf`.
21export const watchTickers = (on: On, rules: readonly BandRule[]): void => {
22  const tickers = tickersOf(rules)
23
24  for (const ticker of tickers) {
25    const name = ticker.command.name
26    on('command.run', { command: name }, async $ => {
27      running.get(name)?.cancel()
28      running.delete(name)
29
30      const now = await $.clock.now()
31      const { next, text } = ticker.toggle(await read($, pomodoro), now)
32      await update($, pomodoro, () => next)
33      if (next === null) return { text }
34
35      // The callback closes over `$`; it never passes it on.
36      running.set(
37        name,
38        $.clock.every(ticker.everyMs, async () => {
39          try {
40            const at = await $.clock.now()
41            let toast: string | undefined
42            // A stop that lands during a tick must stay stopped.
43            await update($, pomodoro, current => {
44              if (current === null) return null
45              const ticked = ticker.tick(current, at)
46              toast = ticked.toast
47              return ticked.next
48            })
49            if (toast !== undefined) await $.ui.toast(toast)
50          } catch (error) {
51            await $.ui.log(failed(name, error))
52          }
53        }),
54      )
55      return { text }
56    })
57  }
58}
59

1import type { On } from 'claude-code'
2
3import { tickersOf } from '../engine'
4import type { BandRule } from '../rule'
5
6// The slash commands of the timer rules. `on("session.start")` takes one hook,
7// so a pack of timer and fetching rules needs a host that does both.
8export const startSession = (on: On, rules: readonly BandRule[]): void => {
9  const tickers = tickersOf(rules)
10  on('session.start', async ($, e, next) => {
11    for (const { command } of tickers) await $.command.register(command)
12    return next(e)
13  })
14}
15

1import { atom, read, update } from 'claude-code'
2import type { On } from 'claude-code'
3
4import type { Reading } from '../../types'
5import { NO_MODEL, turnComplete } from '../engine'
6import type { BandRule } from '../rule'
7
8// The same atoms as engine.tsx: the state scan wants each spelled in the file
9// that reads or writes it. The build writes the mod's own name for the token.
10const reading = atom({ plugin: 'band-pack', key: 'reading' } as const, null)
11const turnStartUsd = atom({ plugin: 'band-pack', key: 'turnStartUsd' } as const, null)
12const turnStartedAt = atom({ plugin: 'band-pack', key: 'turnStartedAt' } as const, null as number | null)
13const minute = atom({ plugin: 'band-pack', key: 'minute' } as const, 0)
14
15// The turn's end, for a mod whose rules keep a figure across sessions in the
16// mod's own store. It gives no model read.
17export const endTurnsWithStore = (on: On, rules: readonly BandRule[]): void => {
18  on('turn.complete', async ($, e, next) => {
19    // The callbacks close over `$`; they never pass it on.
20    await turnComplete(rules, e, {
21      usage: () => $.session.usage(),
22      reading: () => read($, reading),
23      turnStartUsd: () => read($, turnStartUsd),
24      keep: (now: Reading) => update($, reading, () => now),
25      spend: () => update($, turnStartUsd, () => null),
26      endTimer: () => update($, turnStartedAt, () => null),
27      model: NO_MODEL,
28      store: {
29        get: (key: string) => $.store.get(key),
30        set: (key: string, value: unknown) => $.store.set(key, value),
31      },
32      clock: {
33        now: () => $.clock.now(),
34        after: (ms, fn) => $.clock.after(ms, fn),
35        every: (ms, fn) => $.clock.every(ms, fn),
36      },
37      redraw: () => update($, minute, n => n + 1),
38      log: text => $.ui.log(text),
39    })
40    return next(e)
41  })
42}
43

1import { dollars } from '../money'
2import type { BandRule } from '../rule'
3
4// The session cost so far, and the last turn's cost once it is known.
5export const rule: BandRule = {
6  id: 'cost-meter',
7  segment: ({ reading }) => {
8    if (reading.usd === undefined) return undefined
9    const turn = reading.turnUsd === undefined ? '' : ` +${dollars(reading.turnUsd)}`
10    return { key: 'cost-meter', text: `${dollars(reading.usd)}${turn}` }
11  },
12}
13

1import type { BandRule } from '../rule'
2
3export const DEFAULT_LATTE_PRICE = 5
4
5// The session cost in coffees. The price is in the cost's currency (US
6// dollars); one that cannot divide falls back to the default.
7export const rule: BandRule = {
8  id: 'latte-meter',
9  segment: ({ reading, options }) => {
10    if (reading.usd === undefined) return undefined
11    const set = options['lattePrice']
12    const price = typeof set === 'number' && Number.isFinite(set) && set > 0 ? set : DEFAULT_LATTE_PRICE
13    const count = (reading.usd / price).toFixed(1)
14    return { key: 'latte-meter', text: `${count} ${count === '1.0' ? 'latte' : 'lattes'}` }
15  },
16}
17

1import type { BandRule } from '../rule'
2
3const CELLS = 10
4const YELLOW_FROM = 60
5const RED_FROM = 80
6
7// The color is a second cue: the number says the same without it.
8const colorOf = (percent: number): string | undefined =>
9  percent >= RED_FROM ? 'red' : percent >= YELLOW_FROM ? 'yellow' : undefined
10
11// Context used as a 10 cell bar and a percent. A cell fills per whole ten
12// percent, so the bar reads full only at 100.
13export const rule: BandRule = {
14  id: 'context-meter',
15  segment: ({ reading }) => {
16    if (reading.percent === undefined) return undefined
17    const whole = Math.round(reading.percent)
18    const filled = Math.min(CELLS, Math.floor(whole / 10))
19    const color = colorOf(whole)
20    return {
21      key: 'context-meter',
22      text: `[${'#'.repeat(filled)}${'-'.repeat(CELLS - filled)}] ${whole}%`,
23      ...(color === undefined ? {} : { color }),
24    }
25  },
26}
27

1import type { BandRule } from '../rule'
2import { dollars } from '../money'
3
4const keyFor = (date: string): string => `daily:${date}`
5
6// Today's total across sessions. The store holds one number per local date;
7// each turn adds its own cost delta once (the engine measures it from the
8// cost at turn start, so a turn that ends twice has a delta of zero the
9// second time). Two sessions ending a turn in the same instant can lose one
10// add: the store has no atomic update.
11export const rule: BandRule = {
12  id: 'daily-spend',
13  atTurnEnd: async ({ turnUsd, date, store }) => {
14    const stored = await store.get(keyFor(date))
15    const total = typeof stored === 'number' && Number.isFinite(stored) ? stored : undefined
16    if (turnUsd !== undefined && turnUsd > 0) {
17      const next = (total ?? 0) + turnUsd
18      await store.set(keyFor(date), next)
19      return { dailyUsd: next, dailyDate: date }
20    }
21    return total === undefined ? {} : { dailyUsd: total, dailyDate: date }
22  },
23  segment: ({ reading, date }) =>
24    reading.dailyUsd === undefined || reading.dailyDate !== date
25      ? undefined
26      : { key: 'daily-spend', text: `today ${dollars(reading.dailyUsd)}` },
27}
28

1import type { Pomodoro } from '../../types'
2import type { BandRule } from '../rule'
3
4export const FOCUS_MS = 25 * 60_000
5export const BREAK_MS = 5 * 60_000
6// One tick per second is also one redraw per second at most.
7export const TICK_MS = 1000
8
9const PHASE_MS = { focus: FOCUS_MS, break: BREAK_MS } as const
10
11// MM:SS, rounded up so the timer never reads 00:00 before it switches.
12export const clockText = (ms: number): string => {
13  const total = Math.ceil(Math.max(0, ms) / 1000)
14  return `${String(Math.floor(total / 60)).padStart(2, '0')}:${String(total % 60).padStart(2, '0')}`
15}
16
17const TOAST = {
18  break: 'Focus block done. Take a 5 minute break.',
19  focus: 'Break over. Back to focus for 25 minutes.',
20} as const
21
22// A 25/5 focus timer. `/pomodoro` starts it and a second `/pomodoro` stops it.
23// It sits in the band engine because the segment is the band's and the
24// command's whole job is to move that segment; the engine runs the command
25// and the interval for any rule that names a `ticker`.
26export const rule: BandRule = {
27  id: 'pomodoro',
28  ticker: {
29    command: { name: 'pomodoro', description: 'Start or stop a 25 minute focus, 5 minute break timer in the band.' },
30    everyMs: TICK_MS,
31    toggle: (current, now) =>
32      current === null
33        ? {
34            next: { phase: 'focus', endsAt: now + FOCUS_MS, now },
35            text: 'Pomodoro started: 25 minutes of focus. Run /pomodoro again to stop it.',
36          }
37        : { next: null, text: 'Pomodoro stopped.' },
38    // A phase that ended gives way to the other one, measured from now: a tick
39    // that came late (a sleeping laptop) does not replay the missed phases.
40    tick: (current, now): { next: Pomodoro; toast?: string } => {
41      if (now < current.endsAt) return { next: { ...current, now } }
42      const phase = current.phase === 'focus' ? 'break' : 'focus'
43      return { next: { phase, endsAt: now + PHASE_MS[phase], now }, toast: TOAST[phase] }
44    },
45  },
46  segment: ({ pomodoro }) =>
47    pomodoro === null ? undefined : { key: 'pomodoro', text: `${pomodoro.phase} ${clockText(pomodoro.endsAt - pomodoro.now)}` },
48}
49

1import type { Outcome } from '../../types'
2import type { BandRule } from '../rule'
3
4const TENSE_FROM = 0.1
5const STORMY_FROM = 0.3
6
7type Mood = { word: string; color: string }
8
9// The share of the window that errored or was blocked. Under 10 percent is
10// calm, under 30 tense, from 30 stormy.
11export const moodOf = (recent: readonly Outcome[]): Mood => {
12  const bad = recent.filter(outcome => outcome !== 'ok').length
13  const rate = bad / recent.length
14  if (rate >= STORMY_FROM) return { word: 'stormy', color: 'red' }
15  if (rate >= TENSE_FROM) return { word: 'tense', color: 'yellow' }
16  return { word: 'calm', color: 'green' }
17}
18
19// A colored dot and a word for how the last 20 tool calls went (the engine
20// keeps that window). The word says the same without the color. Calls from
21// subagents count too: they are part of how the session is going.
22export const rule: BandRule = {
23  id: 'mood-ring',
24  tracksOutcomes: true,
25  segment: ({ outcomes }) => {
26    if (outcomes.length === 0) return undefined
27    const { word, color } = moodOf(outcomes)
28    return { key: 'mood-ring', text: `● ${word}`, color }
29  },
30}
31