aw-live

1// aw-live: the scorer's numbers for THIS session, live inside Claude Code.
2// `/live` toggles a pane (`/live status` answers in text). The headline numbers
3// live in the statusline's Live column (config/statusline.sh), not here.
4// Every number comes from `scorer live --json` (one short Node process, never
5// in-process). A refresh never blocks a hook and every failure is silent: the
6// pane just keeps its last good value.
7
8import { atom, read, update } from 'claude-code'
9import type { EngineInterface, Register } from 'claude-code'
10
11import type { HostUsage, LiveSnapshot, LiveStatus } from '../types'
12import { paneSections, statusText } from './lib/format'
13import type { Tone } from './lib/format'
14import { binCandidates, isDue, liveArgs, runTimeout } from './lib/refresh'
15import { parseSnapshot } from './lib/snapshot'
16
17const PANE = 'aw-live'
18const TITLE = 'Live scorer'
19const PANE_COLUMNS = 72
20
21const snapshot = atom({ plugin: 'aw-live', key: 'snapshot' } as const, null as LiveSnapshot | null)
22const host = atom({ plugin: 'aw-live', key: 'host' } as const, null as HostUsage | null)
23const status = atom({ plugin: 'aw-live', key: 'status' } as const, null as LiveStatus | null)
24
25const TONE_COLOR: Record<Tone, string | undefined> = { ok: '#7ec699', warn: '#d4a054', dim: '#8b949e' }
26
27// Module variables restart on a hot reload; that only costs one extra refresh.
28let lastAt: number | null = null
29let running: Promise<void> | null = null
30
31/** Test seam: forget the refresh bookkeeping so each test starts cold. */
32export const resetForTests = (): void => {
33  lastAt = null
34  running = null
35}
36
37const isTimeout = (err: unknown): boolean => /time/i.test(err instanceof Error ? err.message : String(err))
38
39/** Runs scorer by argv, trying each candidate path; null on any failure. */
40const runScorer = async ($: EngineInterface, args: string[], timeoutMs: number): Promise<string | null> => {
41  const names = binCandidates(await $.env.get('HOME'), 'scorer', await $.env.get('AW_SCORER_BIN'))
42  for (const name of names) {
43    try {
44      const r = await $.process.run([name, ...args], { timeoutMs })
45      if (r.exitCode === 0) return r.stdout
46      return null
47    } catch (err) {
48      // A timeout means the binary exists but is slow: do not stack another wait on it.
49      if (isTimeout(err)) return null
50      // otherwise not runnable at this path: try the next candidate
51    }
52  }
53  return null
54}
55
56const runRefresh = async ($: EngineInterface, force: boolean): Promise<void> => {
57  let now: number | null = null
58  let ok = false
59  try {
60    now = await $.clock.now()
61    if (!force && !isDue(lastAt, now)) return
62    lastAt = now
63    const sessionId = await $.session.id()
64    if (sessionId === '') return
65    const [cwd, usage] = await Promise.all([$.session.cwd(), $.session.usage()])
66    await update($, host, (): HostUsage => ({
67      usd: usage.cost?.usd ?? null,
68      percent: usage.context.percent ?? null,
69      window: usage.context.window,
70    }))
71    const hasSnapshot = (await read($, snapshot)) !== null
72    const out = await runScorer($, liveArgs(sessionId, cwd, usage.context.window), runTimeout(hasSnapshot))
73    const parsed = out === null ? null : parseSnapshot(out)
74    if (parsed !== null) await update($, snapshot, () => parsed)
75    ok = parsed !== null
76  } catch {
77    // fail silent: the pane keeps its last good value
78  } finally {
79    const at = now
80    if (at !== null) await update($, status, (): LiveStatus => ({ ok, at })).catch(() => undefined)
81  }
82}
83
84/** One refresh at a time: a caller that arrives while one runs waits for that one. */
85const refresh = ($: EngineInterface, force: boolean): Promise<void> => {
86  if (running !== null) return running
87  running = runRefresh($, force).finally(() => {
88    running = null
89  })
90  return running
91}
92
93export const register: Register = on => {
94  on('session.start', async ($, e, next) => {
95    try {
96      await $.command.register({ name: 'live', description: 'Toggle the live scorer pane (context, cost, judge, gates)' })
97    } catch {
98      // a host error must not stop session start
99    }
100    return next(e)
101  })
102
103  on('turn.complete', async ($, e, next) => {
104    try {
105      // Only an open pane shows the numbers; /live refreshes on open, so a closed pane costs nothing.
106      if ((await $.ui.panes()).some(pane => pane.id === PANE)) {
107        $.clock.after(0, () => {
108          void refresh($, false)
109        })
110      }
111    } catch {
112      // a host error must not stop the turn
113    }
114    return next(e)
115  })
116
117  on('command.run', { command: 'live' }, async ($, e) => {
118    if (e.args.trim() === 'status') {
119      await refresh($, true)
120      try {
121        return { text: statusText(await read($, snapshot), await read($, host)) }
122      } catch {
123        return { text: 'aw-live: no numbers yet (is scorer installed? scripts/install-scorer.sh)' }
124      }
125    }
126    try {
127      if ((await $.ui.panes()).some(pane => pane.id === PANE)) {
128        await $.ui.close({ id: PANE })
129        return {}
130      }
131      await refresh($, true)
132      await $.ui.open({ id: PANE, title: TITLE, focus: true, closeOnEscape: true, columns: PANE_COLUMNS })
133    } catch {
134      // a host error: leave the pane as it is
135    }
136    return {}
137  })
138
139  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e, next) => {
140    try {
141      const { Box, Text, Button } = $.ui.resolve(e)
142      const s = await read($, snapshot)
143      if (s === null) {
144        return (
145          <Box flexDirection="column">
146            <Text color={TONE_COLOR.dim}>No numbers yet. Is `scorer` installed? (scripts/install-scorer.sh)</Text>
147          </Box>
148        )
149      }
150      const sections = paneSections(s, await read($, host))
151      return (
152        <Box flexDirection="column">
153          {sections.map(section => (
154            <Box key={section.title} borderStyle="round" borderColor="#3d4450" paddingX={1} flexDirection="column">
155              <Text color="#7eb8da">{section.title}</Text>
156              {section.rows.map(row => (
157                <Text key={row.label} wrap="truncate-end">
158                  <Text color={TONE_COLOR.dim}>{row.label.padEnd(14)}</Text>
159                  <Text color={TONE_COLOR[row.tone]}>{row.value}</Text>
160                </Text>
161              ))}
162            </Box>
163          ))}
164          <Box flexDirection="row" columnGap={2} paddingX={1}>
165            <Button key="refresh" label="refresh" hotkey="r" plain onPress={() => refresh($, true)} />
166          </Box>
167        </Box>
168      )
169    } catch {
170      return next(e)
171    }
172  })
173}
174

1// Pure formatting for the pane and `/live status`. No `$` in here.
2
3import type { HostUsage, LiveSnapshot } from '../../types'
4
5export type Tone = 'ok' | 'warn' | 'dim'
6export type Row = { label: string; value: string; tone: Tone }
7export type Section = { title: string; rows: Row[] }
8
9export const WARN_PERCENT = 70
10
11export const fmtTokens = (n: number): string => {
12  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
13  if (n >= 1_000) return `${Math.round(n / 1_000)}k`
14  return String(n)
15}
16
17/** `▓▓▓▓░░░░░░` for a percent; empty cells when unknown. */
18export const bar = (percent: number | null, width: number): string => {
19  const filled = percent === null ? 0 : Math.round((Math.min(100, Math.max(0, percent)) / 100) * width)
20  return '▓'.repeat(filled) + '░'.repeat(width - filled)
21}
22
23/** The host's own context percent when it has one, else the transcript's estimate. */
24export const contextPercent = (s: LiveSnapshot, host: HostUsage | null): number | null =>
25  host?.percent ?? s.context.percent
26
27/** `jev 83% · rules 17%` for the two biggest deciders; empty with none. */
28export const providerShare = (byProvider: Readonly<Record<string, number>>): string => {
29  const entries = Object.entries(byProvider).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
30  const total = entries.reduce((sum, [, n]) => sum + n, 0)
31  return entries.slice(0, 2).map(([name, n]) => `${name} ${Math.round((n / total) * 100)}%`).join(' · ')
32}
33
34const GATE_ORDER = ['scope-gate', 'done-gate', 'send-gate'] as const
35
36const decisionList = (byDecision: Readonly<Record<string, number>>): string =>
37  Object.entries(byDecision).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([d, n]) => `${d} ${n}`).join(' · ')
38
39/** The pane's cards, top to bottom. */
40export const paneSections = (s: LiveSnapshot, host: HostUsage | null): Section[] => {
41  const percent = contextPercent(s, host)
42  const window = host?.window ?? s.context.window
43  const context: Section = {
44    title: 'context',
45    rows: [
46      { label: 'window', value: `${percent === null ? '--' : `${Math.round(percent)}%`} ${bar(percent, 10)}`, tone: percent !== null && percent >= WARN_PERCENT ? 'warn' : 'ok' },
47      { label: 'tokens', value: `${s.context.tokens === null ? '--' : fmtTokens(s.context.tokens)} of ${fmtTokens(window)}`, tone: 'dim' },
48    ],
49  }
50  const session: Section = {
51    title: 'session',
52    rows: [
53      { label: 'cost', value: host?.usd == null ? '--' : `$${host.usd.toFixed(2)}`, tone: 'ok' },
54      { label: 'tokens', value: `${fmtTokens(s.usage.contextTokens)} in · ${fmtTokens(s.usage.outputTokens)} out`, tone: 'dim' },
55      { label: 'calls', value: `${s.usage.calls} (${s.usage.subagentCalls} subagent)`, tone: 'dim' },
56      { label: 'over 200k', value: String(s.usage.callsOver200k), tone: s.usage.callsOver200k > 0 ? 'warn' : 'dim' },
57    ],
58  }
59  if (s.ingest.readErrors > 0) {
60    session.rows.push({ label: 'warning', value: `stale: ${s.ingest.readErrors} transcript read error${s.ingest.readErrors === 1 ? '' : 's'}`, tone: 'warn' })
61  }
62  const sections = [context, session]
63  if (s.judge.state === 'unscoped') {
64    sections.push({ title: 'judge', rows: [{ label: 'sessions', value: 'not linked yet (judge predates decision_details.session_id)', tone: 'dim' }] })
65  }
66  if (s.judge.state === 'ok') {
67    const j = s.judge
68    sections.push({
69      title: 'judge',
70      rows: [
71        { label: 'calls', value: `${j.calls}${providerShare(j.byProvider) === '' ? '' : ` · ${providerShare(j.byProvider)}`}`, tone: 'ok' },
72        { label: 'vs rules', value: `agreed ${j.agreed} · overrode ${j.overrode} · unsure ${j.undecided}`, tone: j.undecided > 0 ? 'warn' : 'dim' },
73        { label: 'latency', value: `p50 ${j.p50LatencyMs} ms · p95 ${j.p95LatencyMs} ms`, tone: 'dim' },
74      ],
75    })
76    sections.push({
77      title: 'gates',
78      rows: GATE_ORDER.map((name): Row => {
79        const g = j.gates[name]
80        return {
81          label: name,
82          value: g.fired === 0 ? 'quiet' : `${g.fired} · ${decisionList(g.byDecision)} · p50 ${g.p50LatencyMs} ms`,
83          tone: g.fired === 0 ? 'dim' : 'ok',
84        }
85      }),
86    })
87  }
88  sections.push({
89    title: 'wakes',
90    rows: [
91      { label: 'queued now', value: String(s.wakes.queuedNow), tone: s.wakes.queuedNow > 0 ? 'warn' : 'dim' },
92      { label: 'context guard', value: `${s.contextGuard.fires} fires`, tone: s.contextGuard.fires > 0 ? 'warn' : 'dim' },
93    ],
94  })
95  return sections
96}
97
98/** The `/live status` answer: every pane row as plain text. */
99export const statusText = (s: LiveSnapshot | null, host: HostUsage | null): string => {
100  if (s === null) return 'aw-live: no numbers yet (is scorer installed? scripts/install-scorer.sh)'
101  const lines = paneSections(s, host).flatMap(section => [
102    `${section.title}`,
103    ...section.rows.map(row => `  ${row.label.padEnd(14)}${row.value}`),
104  ])
105  return lines.join('\n')
106}
107

1// Pure pieces of the refresh loop. register.tsx owns every `$` call.
2
3export const MIN_GAP_MS = 2_000
4export const RUN_TIMEOUT_MS = 5_000
5/** The first refresh has no snapshot to fall back on; a cold ingest of a long session needs longer. */
6export const RUN_TIMEOUT_FIRST_MS = 30_000
7
8export const runTimeout = (hasSnapshot: boolean): number => (hasSnapshot ? RUN_TIMEOUT_MS : RUN_TIMEOUT_FIRST_MS)
9
10/** The `scorer live` command line. `window` is the host's context window, when known. */
11export const liveArgs = (sessionId: string, cwd: string, window: number | null): string[] => [
12  'live', '--session', sessionId, '--cwd', cwd, ...(window === null ? [] : ['--window', String(window)]), '--json',
13]
14
15/** Where to look for an aw CLI: an explicit override, the installer's directory, then PATH. */
16export const binCandidates = (home: string | undefined, name: 'scorer' | 'judge', override?: string): string[] => [
17  ...(override === undefined || override === '' ? [] : [override]),
18  ...(home === undefined || home === '' ? [name] : [`${home}/.local/bin/${name}`, name]),
19]
20
21/** A refresh is due when none has run yet or the last one is at least `minGapMs` old. */
22export const isDue = (lastAt: number | null, now: number, minGapMs: number = MIN_GAP_MS): boolean =>
23  lastAt === null || now - lastAt >= minGapMs
24

1// The contract with `scorer live --json`. scorer/src/live-snapshot.ts holds the zod
2// schema for the same shape; scorer/tests/live-contract.test.ts parses this mod's
3// fixture with it, so the two cannot drift apart unnoticed.
4
5import type { LiveSnapshot } from '../../types'
6
7const isObject = (value: unknown): value is Record<string, unknown> =>
8  typeof value === 'object' && value !== null && !Array.isArray(value)
9
10const JUDGE_STATES = ['none', 'unscoped', 'ok']
11
12/** Parses the CLI's stdout; null for anything that is not a version-1 snapshot. */
13export const parseSnapshot = (text: string): LiveSnapshot | null => {
14  let value: unknown
15  try {
16    value = JSON.parse(text)
17  } catch {
18    return null
19  }
20  if (!isObject(value) || value.v !== 1 || typeof value.sessionId !== 'string') return null
21  const { ingest, context, usage, judge, contextGuard, wakes } = value
22  if (!isObject(ingest) || !isObject(context) || !isObject(usage) || !isObject(contextGuard) || !isObject(wakes)) return null
23  if (!isObject(judge) || typeof judge.state !== 'string' || !JUDGE_STATES.includes(judge.state)) return null
24  return value as unknown as LiveSnapshot
25}
26

1export type GateName = 'scope-gate' | 'done-gate' | 'send-gate'
2
3export type GateStats = {
4  question: string
5  fired: number
6  byDecision: Record<string, number>
7  p50LatencyMs: number
8}
9
10export type JudgeLatest = {
11  id: string
12  ts: string
13  question: string
14  decision: string
15  provider: string
16  confidence: number
17  /** The eval_items id for this decision, once `judge label import` has made one. */
18  itemId: string | null
19}
20
21export type JudgeLive =
22  | { state: 'none' }
23  | { state: 'unscoped' }
24  | {
25      state: 'ok'
26      calls: number
27      byProvider: Record<string, number>
28      undecided: number
29      agreed: number
30      overrode: number
31      p50LatencyMs: number
32      p95LatencyMs: number
33      gates: Record<GateName, GateStats>
34      labelable: boolean
35      latest: JudgeLatest | null
36    }
37
38export type LiveSnapshot = {
39  v: 1
40  sessionId: string
41  at: string
42  transcript: { found: boolean; files: number }
43  /** readErrors: transcript files the scorer could not read this pass; the numbers may be stale. */
44  ingest: { newLines: number; ms: number; readErrors: number }
45  context: { tokens: number | null; window: number; percent: number | null }
46  usage: { calls: number; subagentCalls: number; contextTokens: number; outputTokens: number; callsOver200k: number }
47  judge: JudgeLive
48  contextGuard: { fires: number }
49  wakes: { queuedNow: number }
50}
51
52/** What the host itself reports; shown in preference to the transcript's estimate. */
53export type HostUsage = { usd: number | null; percent: number | null; window: number | null }
54
55export type LiveStatus = { ok: boolean; at: number }
56
57declare module 'claude-code' {
58  interface PluginState {
59    'aw-live': { snapshot: LiveSnapshot | null; host: HostUsage | null; status: LiveStatus | null }
60  }
61}
62