earpiece-widget

1import { atom, read, update } from 'claude-code'
2import type { AgentInfo, AgentStatus, Elements, EngineInterface, Register, RenderElement, RenderSurface, SessionMessage, Timer } from 'claude-code'
3import type { WidgetsPlace } from 'widgets'
4
5import type { EarpieceRow } from '../types'
6import { fit } from './lib'
7
8type Tags = Pick<Elements[RenderSurface], 'Box' | 'Text'>
9type Said = SessionMessage[] | { deny: string } | null
10type Whisper = EarpieceRow['whisper']
11
12const PANE = 'widgets'
13const CARD_COLUMNS = 40
14const USAGE = 'Usage: /earpiece-widget [on|off]'
15const WHISPER_USAGE = 'Usage: /whisper <number> <note>'
16const HINT = '/whisper <number> <note>'
17const EMPTY = `No agents running. When Claude starts subagents, each gets a row here, and ${HINT} slips one a note.`
18const BLIND = 'Could not read the agents.'
19const OFF = 'Earpiece is off.'
20const FRAME = 'Note from the person running this session, typed while you work (sent with /whisper): '
21const LIVE: readonly AgentStatus[] = ['pending', 'running', 'waiting']
22const BLANK = { rows: [], next: 1, skipped: [], readAt: 0, isBlind: false }
23const UNRUN = { begun: 0, landed: 0 }
24const MOST = 4
25const PERIOD_MS = 3000
26const WAIT_MS = 3000
27const SEEK_MS = 4000
28const GAP_MS = 750
29const LOOKS = 3
30const THROTTLE_MS = 1000
31const WIDE = 30
32const ROOMY = 18
33const HINT_COLUMNS = 24
34const LINE_MAX = 200
35const TOOL_MAX = 10
36const NOTE_MAX = 300
37const REASON_MAX = 120
38const LISTED_MAX = 80
39const DESCRIPTION_MAX = 80
40const site = { plugin: 'widgets', key: 'site' } as const
41const widths = { plugin: 'widgets', key: 'widths' } as const
42const isOn = atom({ plugin: 'earpiece-widget', key: 'isOn' } as const, false)
43const roster = atom({ plugin: 'earpiece-widget', key: 'roster' } as const, BLANK)
44const lap = atom({ plugin: 'earpiece-widget', key: 'lap' } as const, UNRUN)
45
46let timer: Timer | undefined
47
48const flat = (text: string): string => text.replace(/\s+/g, ' ').trim()
49
50const cut = (text: string, room: number): string => {
51  if (text.length <= room) return text
52
53  return room < 1 ? '' : `${text.slice(0, room - 1).trimEnd()}…`
54}
55
56const wrapped = (text: string, room: number): string[] =>
57  text.split(' ').reduce<string[]>((lines, word) => {
58    const last = lines.at(-1)
59
60    return last !== undefined && last.length + 1 + word.length <= room ? [...lines.slice(0, -1), `${last} ${word}`] : [...lines, word]
61  }, [])
62
63const named = (agent: AgentInfo): string => {
64  const name = flat(agent.description) || flat(agent.type) || 'agent'
65
66  return name.length <= DESCRIPTION_MAX ? name : `${name.slice(0, DESCRIPTION_MAX - 1)}…`
67}
68
69const isLive = (row: EarpieceRow): boolean => row.status === 'live' || row.status === 'waiting'
70
71const ranked = (rows: readonly EarpieceRow[]): EarpieceRow[] =>
72  [...rows].sort((one, other) => Number(isLive(other)) - Number(isLive(one)) || one.number - other.number)
73
74const wordOf = (row: EarpieceRow): string => {
75  if (!isLive(row)) return row.status
76
77  return row.tool || (row.status === 'waiting' ? 'waiting' : '')
78}
79
80const lineOf = (said: readonly SessionMessage[]): string => {
81  const last = said.findLast(message => message.role === 'assistant' && message.text.trim() !== '')
82
83  return last === undefined ? '' : (flat(last.text).split(/(?<=[.!?])\s+/).at(-1) ?? '').slice(0, LINE_MAX)
84}
85
86const toolOf = (said: readonly SessionMessage[]): string => {
87  const use = said.findLast(message => message.role === 'assistant')?.toolUses.at(-1)
88  if (use === undefined || use.text !== undefined) return ''
89
90  return (use.tool.startsWith('mcp__') ? use.tool.split('__').slice(2).join('__') || use.tool : use.tool).slice(0, TOOL_MAX)
91}
92
93const weigh = (whisper: Whisper, said: readonly SessionMessage[] | undefined, isOver: boolean): Whisper => {
94  if (whisper?.status !== 'sent') return whisper
95
96  const answers = said?.filter(message => message.role === 'assistant').length
97  if (answers !== undefined && whisper.seen !== null && answers > whisper.seen) return { ...whisper, status: 'heard' }
98
99  return { ...whisper, seen: whisper.seen ?? answers ?? null, status: isOver ? 'missed' : 'sent' }
100}
101
102const statusOf = (agent: AgentInfo | undefined): EarpieceRow['status'] => {
103  if (agent === undefined) return 'done'
104  if (agent.status === 'waiting') return 'waiting'
105  if (LIVE.includes(agent.status)) return 'live'
106  if (agent.status === 'failed') return 'failed'
107
108  return agent.status === 'killed' ? 'stopped' : 'done'
109}
110
111const settle = (row: EarpieceRow, agent: AgentInfo | undefined, said: Said | undefined): EarpieceRow => {
112  const status = isLive(row) ? statusOf(agent) : row.status
113  const isOver = status !== 'live' && status !== 'waiting'
114  const texts = Array.isArray(said) ? said : undefined
115
116  return {
117    ...row,
118    status,
119    line: texts === undefined ? row.line : lineOf(texts),
120    tool: isOver ? '' : texts === undefined ? row.tool : toolOf(texts),
121    isUnread: said === undefined ? row.isUnread : texts === undefined,
122    whisper: weigh(row.whisper, texts, isOver),
123  }
124}
125
126const listing = (row: EarpieceRow): string =>
127  [`${row.number} ${row.description}`, wordOf(row), row.whisper?.status ?? '', row.isUnread ? 'unread' : '', cut(row.line, LISTED_MAX)].filter(part => part !== '').join(' · ')
128
129const face = ({ Box, Text }: Tags, row: EarpieceRow, inner: number): RenderElement[] => {
130  const isOver = !isLive(row)
131  const heard = row.whisper?.status ?? ''
132  const mark = inner >= WIDE ? [wordOf(row), heard].filter(part => part !== '').join(' · ') : heard || wordOf(row)
133  const head = `${row.number}`
134  const room = Math.max(0, inner - head.length - 1 - (mark === '' ? 0 : mark.length + 1))
135
136  return [
137    <Box key={`agent-${row.number}`} justifyContent="space-between">
138      <Text key={`name-${row.number}`} wrap="truncate-end" dimColor={isOver}>
139        <Text bold>{head}</Text>
140        {` ${cut(row.description, room)}`}
141      </Text>
142      <Text key={`mark-${row.number}`} wrap="truncate-end" dimColor={isOver} color={isOver ? undefined : heard === 'heard' ? 'green' : heard === 'sent' ? 'yellow' : 'cyan'}>
143        {mark}
144      </Text>
145    </Box>,
146    <Text key={`line-${row.number}`} wrap="truncate-end" dimColor>
147      {`  ${cut(row.line || 'starting…', inner - 2)}`}
148    </Text>,
149  ]
150}
151
152const roll = async ($: EngineInterface): Promise<AgentInfo[] | undefined> => {
153  try {
154    return await $.agent.list()
155  } catch {
156    return undefined
157  }
158}
159
160const peek = async ($: EngineInterface, agentId: string): Promise<Said> => {
161  try {
162    return await $.session.messages({ agentId })
163  } catch {
164    return null
165  }
166}
167
168const slip = async ($: EngineInterface, agentId: string, note: string): Promise<string | undefined> => {
169  try {
170    const kept = await $.session.append({ agentId, message: { type: 'user', content: [{ type: 'text', text: note }] } })
171
172    return typeof kept.uuid === 'string' ? undefined : (kept.deny ?? '')
173  } catch (error) {
174    return error instanceof Error ? error.message : String(error)
175  }
176}
177
178const begin = async ($: EngineInterface): Promise<number> =>
179  (await update($, lap, kept => ({ ...(kept ?? UNRUN), begun: (kept ?? UNRUN).begun + 1 }))).begun
180
181const land = async ($: EngineInterface, ticket: number): Promise<boolean> =>
182  (await update($, lap, kept => ((kept ?? UNRUN).landed > ticket ? (kept ?? UNRUN) : { ...(kept ?? UNRUN), landed: ticket }))).landed === ticket
183
184const outdate = async ($: EngineInterface): Promise<void> => {
185  await land($, await begin($))
186}
187
188const refresh = async ($: EngineInterface): Promise<number> => {
189  if (!(await read($, isOn))) return 0
190
191  const ticket = await begin($)
192  const held = await read($, roster)
193  const listed = await roll($)
194  if (listed === undefined) {
195    if (await land($, ticket)) await update($, roster, kept => ({ ...(kept ?? BLANK), isBlind: true }))
196
197    return 0
198  }
199
200  const agents = new Map(listed.map(agent => [agent.id, agent]))
201  const isRunning = (id: string): boolean => LIVE.includes(agents.get(id)?.status ?? 'completed')
202  const wanted = new Set([
203    ...listed.filter(agent => isRunning(agent.id) && !held.skipped.includes(agent.id) && !held.rows.some(row => row.id === agent.id)).map(agent => agent.id),
204    ...ranked(held.rows.filter(row => isLive(row) && isRunning(row.id))).slice(0, MOST).map(row => row.id),
205    ...held.rows.filter(row => isLive(row) && (!isRunning(row.id) || row.whisper?.status === 'sent')).map(row => row.id),
206  ])
207  const seen = new Map(await Promise.all([...wanted].map(async id => [id, await peek($, id)] as const)))
208  if (!(await land($, ticket))) return 0
209
210  let found = 0
211  await update($, roster, kept => {
212    const base = kept ?? BLANK
213    const fresh = listed.filter(
214      agent => seen.has(agent.id) && isRunning(agent.id) && !base.skipped.includes(agent.id) && !base.rows.some(row => row.id === agent.id),
215    )
216    found = fresh.length
217    const isDenied = (agent: AgentInfo): boolean => {
218      const said = seen.get(agent.id)
219
220      return said !== undefined && said !== null && !Array.isArray(said)
221    }
222    const added = fresh
223      .filter(agent => !isDenied(agent))
224      .map((agent, at) =>
225        settle(
226          { id: agent.id, number: base.next + at, description: named(agent), status: 'live', tool: '', line: '', isUnread: true, whisper: null },
227          agent,
228          seen.get(agent.id),
229        ),
230      )
231
232    return {
233      rows: [...base.rows.map(row => settle(row, agents.get(row.id), seen.get(row.id))), ...added],
234      next: base.next + added.length,
235      skipped: [...base.skipped, ...fresh.filter(isDenied).map(agent => agent.id)],
236      readAt: base.readAt,
237      isBlind: false,
238    }
239  })
240  await sync($)
241
242  return found
243}
244
245const kick = ($: EngineInterface): void => {
246  void refresh($).catch(() => undefined)
247}
248
249const within = async ($: EngineInterface, ms: number, work: () => Promise<unknown>): Promise<void> => {
250  await new Promise<void>(done => {
251    const wait = $.clock.after(ms, done)
252    void work()
253      .catch(() => undefined)
254      .then(() => {
255        wait.cancel()
256        done()
257      })
258  })
259}
260
261const pause = async ($: EngineInterface, ms: number): Promise<void> => {
262  await new Promise<void>(done => {
263    $.clock.after(ms, done)
264  })
265}
266
267const catchUp = async ($: EngineInterface): Promise<void> => within($, WAIT_MS, () => refresh($))
268
269const seek = async ($: EngineInterface, number: number): Promise<void> => {
270  let isSought = true
271  await within($, SEEK_MS, async () => {
272    for (let look = 0; look < LOOKS; look += 1) {
273      if (look > 0) await pause($, GAP_MS)
274      if (!isSought) return
275
276      await refresh($)
277      const held = await read($, roster)
278      if (held.isBlind || held.rows.some(row => row.number === number)) return
279    }
280  })
281  isSought = false
282}
283
284const follow = async ($: EngineInterface): Promise<void> => {
285  for (let look = 0; look < LOOKS; look += 1) {
286    if (look > 0) await pause($, GAP_MS)
287    if (!(await read($, isOn)) || (await refresh($)) > 0) return
288  }
289}
290
291const sync = async ($: EngineInterface): Promise<void> => {
292  const isWanted = (await read($, isOn)) && (await read($, roster)).rows.some(isLive)
293  if (isWanted && timer === undefined) {
294    timer = $.clock.every(PERIOD_MS, () => kick($))
295  }
296  if (!isWanted && timer !== undefined) {
297    timer.cancel()
298    timer = undefined
299  }
300}
301
302const glance = async ($: EngineInterface): Promise<void> => {
303  const now = await $.clock.now()
304  let isDue = false
305  await update($, roster, kept => {
306    const base = kept ?? BLANK
307    isDue = now - base.readAt >= THROTTLE_MS
308
309    return isDue ? { ...base, readAt: now } : base
310  })
311  if (isDue) kick($)
312}
313
314const show = async (
315  $: EngineInterface,
316  { Box, Text }: Tags,
317  beneath: RenderElement,
318  place: WidgetsPlace,
319  columns: number,
320): Promise<RenderElement> => {
321  if (!(await read($, isOn))) return beneath
322  if ((await $.state.get(site)).value !== place) return beneath
323
324  const width = fit((await $.state.get(widths)).value?.['earpiece-widget'] ?? CARD_COLUMNS, columns)
325  const inner = width - 4
326  const held = await read($, roster)
327  const live = held.rows.filter(isLive).length
328  const drawn = ranked(held.rows)
329  const isQuiet = held.isBlind || held.rows.length === 0
330
331  return $.widgets.card({
332    beneath,
333    width,
334    title: 'Earpiece',
335    ...(isQuiet ? {} : { note: live === 0 ? 'done' : live <= 99 ? `${live} live` : inner < ROOMY ? '99+' : '99+ live' }),
336    body: isQuiet ? (
337      <Box key={held.isBlind ? 'blind' : 'empty'} flexDirection="column">
338        {wrapped(held.isBlind ? BLIND : EMPTY, inner).map((line, at) => (
339          <Text key={`say-${at}`} wrap="truncate-end" color={held.isBlind ? 'red' : undefined}>
340            {line}
341          </Text>
342        ))}
343      </Box>
344    ) : (
345      <Box key="agents" flexDirection="column">
346        {drawn.slice(0, MOST).flatMap(row => face({ Box, Text }, row, inner))}
347        {drawn.length > MOST && (
348          <Text key="more" wrap="truncate-end" dimColor>
349            +{drawn.length - MOST} more
350          </Text>
351        )}
352        {live > 0 && inner >= HINT_COLUMNS && (
353          <Text key="hint" wrap="truncate-end" dimColor>
354            {HINT}
355          </Text>
356        )}
357      </Box>
358    ),
359  })
360}
361
362export const register: Register = on => {
363  on('session.start', async ($, e, next) => {
364    await $.command.register({
365      name: 'earpiece-widget',
366      description: 'Toggle the Earpiece card',
367      argumentHint: '[on|off]',
368    })
369    await $.command.register({
370      name: 'whisper',
371      description: 'Slip a note to one running subagent on the Earpiece card',
372      argumentHint: '<number> <note>',
373      immediate: true,
374    })
375    if ((await $.store.get('isOn')) === true) await update($, isOn, () => true)
376    if (await read($, isOn)) await catchUp($)
377    await sync($)
378
379    return next(e)
380  })
381
382  on('command.run', { command: 'earpiece-widget' }, async ($, e) => {
383    const arg = e.args.trim().toLowerCase()
384    if (arg !== '' && arg !== 'on' && arg !== 'off') return { text: USAGE }
385
386    const isShown = await update($, isOn, shown => (arg === '' ? !(shown ?? false) : arg === 'on'))
387    await $.store.set('isOn', isShown)
388    if (isShown) await catchUp($)
389    else {
390      await outdate($)
391      await update($, roster, () => BLANK)
392    }
393    await sync($)
394
395    return { text: isShown ? 'Earpiece on; /widgets places it.' : 'Earpiece off.' }
396  })
397
398  on('command.run', { command: 'whisper' }, async ($, e) => {
399    if (!(await read($, isOn))) return { text: OFF }
400
401    const args = e.args.trim()
402    if (args === '') {
403      await catchUp($)
404      const shown = await read($, roster)
405      if (shown.isBlind) return { text: BLIND }
406
407      return { text: shown.rows.length === 0 ? 'No agents on the card.' : shown.rows.map(listing).join('\n') }
408    }
409
410    const asked = /^(\d{1,4})\s+(\S[\s\S]*)$/.exec(args)
411    if (asked === null) return { text: WHISPER_USAGE }
412
413    const text = asked[2] ?? ''
414    if (text.length > NOTE_MAX) return { text: `A whisper is at most ${NOTE_MAX} characters.` }
415
416    const number = Number(asked[1])
417    if (!(await read($, roster)).rows.some(kept => kept.number === number)) await seek($, number)
418
419    const held = await read($, roster)
420    const row = held.rows.find(kept => kept.number === number)
421    if (row === undefined && !held.isBlind) return { text: `No agent ${number} on the card.` }
422
423    const listed = await roll($)
424    if (listed === undefined) return { text: BLIND }
425    if (row === undefined) return { text: `No agent ${number} on the card.` }
426    if (!listed.some(agent => agent.id === row.id && LIVE.includes(agent.status))) return { text: `Agent ${number} has finished.` }
427
428    const note = `${FRAME}${text}`
429    const refusal = await slip($, row.id, note)
430    if (refusal !== undefined) return { text: `Agent ${number} could not be reached: ${cut(flat(refusal), REASON_MAX) || 'no reason given'}` }
431
432    await outdate($)
433    await update($, roster, kept => ({
434      ...(kept ?? BLANK),
435      rows: (kept ?? BLANK).rows.map(other => (other.id === row.id ? { ...other, whisper: { note, status: 'sent' as const, seen: null } } : other)),
436    }))
437    kick($)
438
439    return { text: `Whispered to agent ${number} (${row.description}). The card says heard once it has answered.` }
440  })
441
442  on('agent.spawn', async ($, e, next) => {
443    const started = await next(e)
444    if (await read($, isOn)) void follow($).catch(() => undefined)
445
446    return started
447  })
448
449  on('tool.call', ($, e, next) => {
450    if (e.agentId !== undefined) {
451      void read($, isOn)
452        .then(shown => (shown ? glance($) : undefined))
453        .catch(() => undefined)
454    }
455
456    return next(e)
457  })
458
459  on('turn.complete', async ($, e, next) => {
460    if (e.agentId !== undefined && (await read($, isOn))) kick($)
461
462    return next(e)
463  })
464
465  on('turn.start', async ($, e, next) => {
466    if (await read($, isOn)) {
467      await update($, roster, kept => {
468        const rows = (kept ?? BLANK).rows.filter(isLive)
469
470        return { ...(kept ?? BLANK), rows, next: rows.length === 0 ? 1 : (kept ?? BLANK).next }
471      })
472    }
473
474    return next(e)
475  })
476
477  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e, next) =>
478    show($, $.ui.resolve(e), await next(e), 'side', e.props.bodyColumns),
479  )
480
481  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) =>
482    e.props.hasSurvey ? next(e) : show($, $.ui.resolve(e), await next(e), 'above', e.props.bodyColumns),
483  )
484
485  on('ui.render', { component: 'PromptHint' }, async ($, e, next) =>
486    show($, $.ui.resolve(e), await next(e), 'below', e.viewport?.columns ?? 80),
487  )
488}
489

1const MIN_CARD = 20
2const BARS = '▁▂▃▄▅▆▇█'
3
4export const fit = (wanted: number, columns: number): number => Math.min(wanted, Math.max(MIN_CARD, columns))
5
6export const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? '' : 's'}`
7
8export const span = (ms: number): string => {
9  const seconds = Math.max(0, Math.round(ms / 1000))
10  if (seconds < 60) return `${seconds}s`
11  const minutes = Math.floor(seconds / 60)
12  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, '0')}s`
13  const hours = Math.floor(minutes / 60)
14  if (hours < 24) return `${hours}h ${String(minutes % 60).padStart(2, '0')}m`
15
16  return `${Math.floor(hours / 24)}d ${hours % 24}h`
17}
18
19export const spark = (values: readonly number[], width: number): string => {
20  const shown = width > 0 ? values.slice(-width) : []
21  const top = Math.max(...shown, 0)
22
23  return shown
24    .map(value => (top <= 0 ? BARS[0] : BARS[Math.min(BARS.length - 1, Math.round((Math.max(0, value) / top) * (BARS.length - 1)))]))
25    .join('')
26}
27
28export const hash = (text: string): number => {
29  let held = 2166136261
30  for (const letter of text) held = Math.imul(held ^ (letter.codePointAt(0) ?? 0), 16777619)
31
32  return held >>> 0
33}
34
35export const shade = (color: number, factor: number): number =>
36  (Math.round((color >> 16) * factor) << 16) |
37  (Math.round(((color >> 8) & 255) * factor) << 8) |
38  Math.round((color & 255) * factor)
39
40export const folder = (path: string): string => {
41  const flat = path.replaceAll('\\', '/').replace(/\/+$/, '')
42
43  return /^[a-z]:/i.test(flat) ? flat.toLowerCase() : flat
44}
45

1export type EarpieceSwitch = boolean
2
3export type EarpieceRow = {
4  id: string
5  number: number
6  description: string
7  status: 'live' | 'waiting' | 'done' | 'failed' | 'stopped'
8  tool: string
9  line: string
10  isUnread: boolean
11  whisper: { note: string; status: 'sent' | 'heard' | 'missed'; seen: number | null } | null
12}
13
14declare module 'claude-code' {
15  interface PluginState {
16    'earpiece-widget': {
17      isOn: EarpieceSwitch
18      roster: { rows: EarpieceRow[]; next: number; skipped: string[]; readAt: number; isBlind: boolean }
19      lap: { begun: number; landed: number }
20    }
21  }
22}
23