fleet-pane

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, RenderSurface, Timer } from 'claude-code'
3
4import type { FleetPaneCodex, FleetPaneSession, FleetView } from '../types'
5import type { CodexRow, Envelope, FleetSession, FleetSnapshot, FleetSummary } from '../types/fleet.gen'
6
7const view = atom({ plugin: 'fleet-pane', key: 'view' } as const, null as FleetView | null)
8const codex = atom({ plugin: 'fleet-pane', key: 'codex' } as const, [] as FleetPaneCodex[])
9const problem = atom({ plugin: 'fleet-pane', key: 'problem' } as const, null as string | null)
10const replyTo = atom({ plugin: 'fleet-pane', key: 'replyTo' } as const, null as string | null)
11const notice = atom({ plugin: 'fleet-pane', key: 'notice' } as const, null as string | null)
12const self = atom({ plugin: 'fleet-pane', key: 'self' } as const, null as string | null)
13
14const PANE = 'fleet'
15const FAST_MS = 5_000
16const CODEX_MS = 60_000
17const STATUS_MS = 30_000
18const STALE_MS = 2 * 60_000
19const RUN_TIMEOUT_MS = 20_000
20// The row's action buttons, drawn plain: "y: reply  c: copy".
21const ACTIONS_WIDTH = 18
22// "r: refresh  x: close".
23const HEADER_ACTIONS_WIDTH = 22
24const PROJECT_WIDTH = 12
25const DETAIL_WIDTH = 14
26const AGE_WIDTH = 6
27
28// The pane's refresh timers run only while it is open; a reload drops them
29// with the module, and session.start restarts them for a pane still open.
30let fast: Timer | null = null
31let slow: Timer | null = null
32const inFlight = new Set<'fast' | 'codex'>()
33
34// fleet draws what `vybava fleet --json` says and never decides it: grouping
35// and liveness are the Go applet's. The status line reads the summary file
36// the watch daemon publishes, so no session spawns a process on a timer.
37export const register: Register = on => {
38  on('session.start', async ($, e, next) => {
39    const started = await next(e)
40    await $.command.register({
41      name: 'fleet',
42      description: 'Every Claude session on this Mac, waiting on you first; reply or copy a resume line',
43      immediate: true,
44    })
45    const id = await $.session.id()
46    await update($, self, () => id)
47    $.clock.every(STATUS_MS, () => {
48      void refreshStatus($)
49    })
50    void refreshStatus($)
51    const panes = await $.ui.panes()
52    if (panes.some(pane => pane.id === PANE)) {
53      startRefresh($)
54    }
55    return started
56  })
57
58  // /clear and /resume give the session a new id without a session.start.
59  on('classic.SessionStart', async ($, e, next) => {
60    const ran = await next(e)
61    await update($, self, () => e.session_id)
62    return ran
63  })
64
65  on('command.run', { command: 'fleet' }, async $ => {
66    const opened = await $.ui.open({ id: PANE, title: 'Fleet', focus: true, closeOnEscape: true })
67    if (!opened.isPlaced) {
68      $.ui.toast(`the pane is waiting for room (${opened.reason})`)
69    }
70    startRefresh($)
71    return {}
72  })
73
74  on('ui.close', { id: PANE }, async ($, e, next) => {
75    stopRefresh()
76    await update($, replyTo, () => null)
77    return next(e)
78  })
79
80  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
81    const table = $.ui.resolve(e)
82    const { Box, Text, Button } = table
83    const width = Math.max(40, e.props.bodyColumns)
84    const snapshot = await read($, view)
85    const codexRows = await read($, codex)
86    const failure = await read($, problem)
87    const replying = await read($, replyTo)
88    const outcome = await read($, notice)
89    const me = await read($, self)
90
91    if (snapshot === null) {
92      return (
93        <Box flexDirection="column">
94          <Text color={failure === null ? undefined : 'red'} wrap="truncate-end">
95            {failure ?? 'Reading the fleet…'}
96          </Text>
97        </Box>
98      )
99    }
100
101    const groups = groupSessions(snapshot.sessions)
102    const waitingOnYou = groups.waiting.filter(one => one.sessionId !== me).length
103    const first = groups.waiting.find(one => one.sessionId !== me)
104    const textWidth = width - ACTIONS_WIDTH
105
106    const row = (session: FleetPaneSession) => {
107      const isSelf = session.sessionId === me
108      const isDead = session.state === 'dead'
109      const isFirst = first !== undefined && session.sessionId === first.sessionId
110      const target = session
111      return (
112        <Box key={`row:${session.sessionId}`} flexDirection="column">
113          <Box flexDirection="row">
114            <Box width={textWidth}>
115              <Text wrap="truncate-end" dimColor={isSelf}>
116                {sessionLine(session, isSelf, textWidth)}
117              </Text>
118            </Box>
119            <Box flexDirection="row" gap={2}>
120              {!isSelf && !isDead && (
121                <Button
122                  key={`reply:${session.sessionId}`}
123                  label="reply"
124                  plain
125                  dimColor={!isFirst}
126                  {...(isFirst ? { hotkey: 'y' } : {})}
127                  onPress={() => {
128                    void openReply($, target.sessionId)
129                  }}
130                />
131              )}
132              <Button
133                key={`copy:${session.sessionId}`}
134                label="copy"
135                plain
136                dimColor={!isFirst}
137                {...(isFirst ? { hotkey: 'c' } : {})}
138                onPress={press => {
139                  void copyResume($, target, press.surface)
140                }}
141              />
142            </Box>
143          </Box>
144          {replying === session.sessionId && 'Input' in table && (
145            <Box flexDirection="column" paddingLeft={2}>
146              <table.Input
147                key="reply-text"
148                label={`reply to ${displayName(session)}: `}
149                placeholder="type, Enter sends · Esc returns"
150                submitLabel="send"
151                autoFocus
152                onSubmit={value => {
153                  void sendReply($, target, value)
154                }}
155              />
156              <Text dimColor wrap="truncate-end">
157                {session.state === 'busy'
158                  ? 'it is busy: the reply lands inside its running turn'
159                  : 'the reply arrives as a message from the fleet mod'}
160              </Text>
161              <Button
162                key="reply-cancel"
163                label="cancel"
164                plain
165                dimColor
166                onPress={() => {
167                  void update($, replyTo, () => null)
168                }}
169              />
170            </Box>
171          )}
172          {replying === session.sessionId && !('Input' in table) && (
173            <Text dimColor wrap="truncate-end">
174              this surface has no text field: reply from the terminal or desktop
175            </Text>
176          )}
177        </Box>
178      )
179    }
180
181    const idleParts = [`idle · ${groups.idle.length}`]
182    if (snapshot.counts.shell > 0) {
183      idleParts.push(`${snapshot.counts.shell} at a shell`)
184    }
185    if (snapshot.counts.ended + snapshot.counts.unknown > 0) {
186      idleParts.push(`${snapshot.counts.ended + snapshot.counts.unknown} ended or unknown`)
187    }
188
189    return (
190      <Box flexDirection="column">
191        <Box flexDirection="row">
192          <Box width={width - HEADER_ACTIONS_WIDTH}>
193            <Text bold wrap="truncate-end">
194              {`Fleet · ${snapshot.counts.total} sessions · ${waitingOnYou} waiting on you`}
195            </Text>
196          </Box>
197          <Box flexDirection="row" gap={2}>
198            <Button
199              key="refresh"
200              label="refresh"
201              plain
202              hotkey="r"
203              onPress={() => {
204                void refresh($, true)
205              }}
206            />
207            <Button
208              key="close"
209              label="close"
210              plain
211              role="dismiss"
212              hotkey="x"
213              onPress={() => {
214                void closePane($)
215              }}
216            />
217          </Box>
218        </Box>
219        {failure !== null && (
220          <Text color="red" wrap="truncate-end">
221            {failure}
222          </Text>
223        )}
224        {outcome !== null && (
225          <Text dimColor wrap="truncate-end">
226            {outcome}
227          </Text>
228        )}
229        <Text dimColor>{rule(`waiting on you · ${groups.waiting.length}`, width)}</Text>
230        {groups.waiting.length === 0 && <Text dimColor>  nobody is waiting on you</Text>}
231        {groups.waiting.map(row)}
232        {groups.dead.length > 0 && <Text dimColor>{rule(`died while busy · ${groups.dead.length}`, width)}</Text>}
233        {groups.dead.map(row)}
234        <Text dimColor>{rule(`working · ${groups.working.length}`, width)}</Text>
235        {groups.working.map(row)}
236        <Text dimColor>{rule(idleParts.join(' · '), width)}</Text>
237        {codexRows.length > 0 && <Text dimColor>{rule(`codex (read-only) · ${codexRows.length}`, width)}</Text>}
238        {codexRows.map(one => (
239          <Text dimColor wrap="truncate-end">
240            {codexLine(one, snapshot.generatedAt, width)}
241          </Text>
242        ))}
243      </Box>
244    )
245  })
246}
247
248function startRefresh($: EngineInterface): void {
249  if (fast !== null) {
250    return
251  }
252  void refresh($, true)
253  fast = $.clock.every(FAST_MS, () => {
254    void refresh($, false)
255  })
256  slow = $.clock.every(CODEX_MS, () => {
257    void refresh($, true)
258  })
259}
260
261// closePane stops the timers itself: the ui.close hook covers the person's
262// close and Escape, and this covers our own button whatever the chain does.
263async function closePane($: EngineInterface): Promise<void> {
264  stopRefresh()
265  await update($, replyTo, () => null)
266  await $.ui.close({ id: PANE })
267}
268
269function stopRefresh(): void {
270  fast?.cancel()
271  slow?.cancel()
272  fast = null
273  slow = null
274}
275
276// refresh runs `vybava fleet --json`; the Codex rows (lsof per process) only
277// on the slow beat. A failure is logged and drawn, never swallowed.
278async function refresh($: EngineInterface, withCodex: boolean): Promise<void> {
279  const kind = withCodex ? 'codex' : 'fast'
280  if (inFlight.has(kind)) {
281    return
282  }
283  inFlight.add(kind)
284  try {
285    const argv = withCodex ? ['vybava', 'fleet', '--json'] : ['vybava', 'fleet', '--json', '--no-codex']
286    let ran
287    try {
288      ran = await $.process.run(argv, { timeoutMs: RUN_TIMEOUT_MS })
289    } catch (error) {
290      await fail($, `could not run \`vybava fleet\`: ${messageOf(error)}`)
291      return
292    }
293    const envelope = parseEnvelope(ran.stdout)
294    if (envelope === null || !envelope.ok || envelope.data === undefined) {
295      await fail($, `\`vybava fleet\` failed (exit ${ran.exitCode}): ${reasonOf(envelope, ran.stderr)}`)
296      return
297    }
298    const data = envelope.data
299    await update($, view, () => ({ generatedAt: data.generatedAt, counts: data.counts, sessions: data.sessions.map(paneSession) }))
300    if (withCodex) {
301      await update($, codex, () => data.codex.map(paneCodex))
302    }
303    await update($, problem, () => null)
304  } finally {
305    inFlight.delete(kind)
306  }
307}
308
309async function fail($: EngineInterface, text: string): Promise<void> {
310  $.ui.log(text, { to: 'debug' })
311  await update($, problem, () => text)
312}
313
314// refreshStatus reads the published summary: no file, no line (the daemon
315// is not installed); an old file says so instead of showing old counts.
316async function refreshStatus($: EngineInterface): Promise<void> {
317  const home = await $.env.get('HOME')
318  if (home === undefined || home === '') {
319    $.ui.log('HOME is unset; no summary to read', { to: 'debug' })
320    return
321  }
322  const path = `${home}/.local/state/vybava/fleet/summary.json`
323  if (!(await $.fs.exists(path))) {
324    $.ui.status(undefined)
325    return
326  }
327  let summary: FleetSummary
328  try {
329    summary = parseSummary(await $.fs.read(path))
330  } catch (error) {
331    $.ui.log(`${path} is unreadable: ${messageOf(error)}`, { to: 'debug' })
332    $.ui.status('fleet summary unreadable · /fleet')
333    return
334  }
335  const age = (await $.clock.now()) - Date.parse(summary.generatedAt)
336  if (!(age <= STALE_MS)) {
337    $.ui.status('fleet summary stale (is vybava.watchd running?)')
338    return
339  }
340  const me = await read($, self)
341  const waiting = summary.waiting.filter(one => one.sessionId !== me).length
342  $.ui.status(waiting > 0 ? `${waiting} waiting on you · /fleet` : undefined)
343}
344
345async function openReply($: EngineInterface, sessionId: string): Promise<void> {
346  await update($, notice, () => null)
347  await update($, replyTo, () => sessionId)
348}
349
350// sendReply delivers what the person typed and pressed, nothing else.
351async function sendReply($: EngineInterface, session: FleetPaneSession, value: string): Promise<void> {
352  const text = value.trim()
353  if (text === '') {
354    await update($, notice, () => 'nothing sent: the reply was empty')
355    return
356  }
357  const name = displayName(session)
358  let outcome: string
359  try {
360    const sent = await $.session.send({ to: { sessionId: session.sessionId }, text })
361    outcome = sent.isDelivered ? `sent to ${name}` : `not delivered to ${name}: ${sent.reason}`
362  } catch (error) {
363    outcome = `not delivered to ${name}: ${messageOf(error)}`
364    $.ui.log(outcome, { to: 'debug' })
365  }
366  await update($, replyTo, () => null)
367  await update($, notice, () => outcome)
368}
369
370async function copyResume($: EngineInterface, session: FleetPaneSession, surface: RenderSurface): Promise<void> {
371  const copied = await $.ui.copy({ text: session.resume, surface })
372  const outcome = copied.isCopied
373    ? `copied: ${session.resume}`
374    : `copy failed (${copied.reason}): ${session.resume}`
375  await update($, notice, () => outcome)
376}
377
378type Groups = { waiting: FleetPaneSession[]; dead: FleetPaneSession[]; working: FleetPaneSession[]; idle: FleetPaneSession[] }
379
380function groupSessions(sessions: readonly FleetPaneSession[]): Groups {
381  const groups: Groups = { waiting: [], dead: [], working: [], idle: [] }
382  for (const session of sessions) {
383    if (session.state === 'waiting') {
384      groups.waiting.push(session)
385    } else if (session.state === 'dead') {
386      groups.dead.push(session)
387    } else if (session.state === 'busy') {
388      groups.working.push(session)
389    } else {
390      groups.idle.push(session)
391    }
392  }
393  groups.waiting.sort((a, b) => b.ageSeconds - a.ageSeconds)
394  return groups
395}
396
397function sessionLine(session: FleetPaneSession, isSelf: boolean, width: number): string {
398  const mark = session.state === 'waiting' ? '▸' : session.state === 'dead' ? '✕' : ' '
399  const name = `${displayName(session)}${isSelf ? ' (you)' : ''}`
400  const detail = detailOf(session)
401  const age = ageText(session.ageSeconds).padStart(AGE_WIDTH)
402  const fixed = 2 + PROJECT_WIDTH + 1 + 1 + DETAIL_WIDTH + 1 + AGE_WIDTH
403  const nameWidth = width - fixed
404  if (nameWidth < 8) {
405    return fit(`${mark} ${session.project} ${name} ${age.trim()}`, width)
406  }
407  return `${mark} ${fit(session.project, PROJECT_WIDTH)} ${fit(name, nameWidth)} ${fit(detail, DETAIL_WIDTH)} ${age}`
408}
409
410function detailOf(session: FleetPaneSession): string {
411  if (session.state === 'waiting') {
412    return session.waitingFor ?? 'waiting'
413  }
414  if (session.state === 'dead') {
415    return session.openJobs > 0 ? `died · ${session.openJobs} jobs` : 'died while busy'
416  }
417  return session.openJobs > 0 ? `${session.state} · ${session.openJobs} bg` : session.state
418}
419
420function codexLine(row: FleetPaneCodex, generatedAt: string, width: number): string {
421  const name = row.name ?? row.branch ?? row.threadId.slice(0, 8)
422  const last = row.lastCallAt === undefined ? '' : `last call ${ageText(Math.max(0, (Date.parse(generatedAt) - Date.parse(row.lastCallAt)) / 1000))} ago`
423  return fit(`  ${fit(row.project, PROJECT_WIDTH)} ${name} · ${row.calls} calls ${last}`.trimEnd(), width)
424}
425
426// paneSession and paneCodex keep what the pane draws; their parameter types
427// are the generated Go contract, so a drift there fails tsc here.
428function paneSession(session: FleetSession): FleetPaneSession {
429  const { sessionId, name, project, state, waitingFor, ageSeconds, openJobs, resume } = session
430  return { sessionId, name, project, state, waitingFor, ageSeconds, openJobs, resume }
431}
432
433function paneCodex(row: CodexRow): FleetPaneCodex {
434  const { threadId, name, branch, project, calls, lastCallAt } = row
435  return { threadId, name, branch, project, calls, lastCallAt }
436}
437
438function displayName(session: FleetPaneSession): string {
439  return session.name ?? session.sessionId.slice(0, 8)
440}
441
442function rule(title: string, width: number): string {
443  const head = `── ${title} `
444  return head.length >= width ? fit(head, width) : head + '─'.repeat(width - head.length)
445}
446
447function fit(text: string, width: number): string {
448  if (text.length <= width) {
449    return text.padEnd(width)
450  }
451  return width <= 1 ? text.slice(0, width) : `${text.slice(0, width - 1)}…`
452}
453
454function ageText(seconds: number): string {
455  const minutes = Math.floor(seconds / 60)
456  if (minutes < 1) {
457    return `${Math.floor(seconds)}s`
458  }
459  if (minutes < 60) {
460    return `${minutes}m`
461  }
462  const hours = Math.floor(minutes / 60)
463  if (hours < 48) {
464    const rest = minutes % 60
465    return rest === 0 ? `${hours}h` : `${hours}h${rest}m`
466  }
467  return `${Math.floor(hours / 24)}d`
468}
469
470function parseEnvelope(stdout: string): Envelope<FleetSnapshot> | null {
471  let parsed: unknown
472  try {
473    parsed = JSON.parse(stdout)
474  } catch {
475    return null
476  }
477  if (typeof parsed !== 'object' || parsed === null || !('ok' in parsed) || typeof parsed.ok !== 'boolean' || !('diagnostics' in parsed) || !Array.isArray(parsed.diagnostics)) {
478    return null
479  }
480  // The shape past these keys is the Go contract, held by fleet.gen.d.ts's drift test.
481  return parsed as Envelope<FleetSnapshot>
482}
483
484function parseSummary(text: string): FleetSummary {
485  const parsed: unknown = JSON.parse(text)
486  if (typeof parsed !== 'object' || parsed === null || !('generatedAt' in parsed) || typeof parsed.generatedAt !== 'string' || !('waiting' in parsed) || !Array.isArray(parsed.waiting)) {
487    throw new Error('not a fleet summary')
488  }
489  return parsed as FleetSummary
490}
491
492function reasonOf(envelope: Envelope<FleetSnapshot> | null, stderr: string): string {
493  const diagnostic = envelope?.diagnostics.find(one => one.severity === 'error') ?? envelope?.diagnostics[0]
494  if (diagnostic !== undefined) {
495    return `${diagnostic.code}: ${diagnostic.detail}`
496  }
497  const line = stderr.trim().split('\n')[0]
498  return line === undefined || line === '' ? 'no JSON on stdout' : line
499}
500
501function messageOf(error: unknown): string {
502  return error instanceof Error ? error.message : String(error)
503}
504

1// fleet's state contract: the session values its hooks keep in $.state.
2// Self-contained by rule, so it restates the few fields the pane draws from
3// fleet.gen.d.ts (the Go contract); register.tsx assigns the generated types
4// to these, so tsc fails if the two ever stop fitting.
5
6export type FleetPaneState = 'waiting' | 'busy' | 'idle' | 'shell' | 'dead' | 'ended' | 'unknown'
7
8/** One Claude session as the pane draws it. */
9export type FleetPaneSession = {
10  sessionId: string
11  name?: string
12  project: string
13  state: FleetPaneState
14  waitingFor?: string
15  ageSeconds: number
16  openJobs: number
17  /** `cd '<cwd>' && claude --resume <id>`, what [copy] puts on the clipboard. */
18  resume: string
19}
20
21export type FleetPaneCounts = {
22  total: number
23  waiting: number
24  busy: number
25  idle: number
26  shell: number
27  dead: number
28  ended: number
29  unknown: number
30}
31
32/** One live Codex thread, read-only. */
33export type FleetPaneCodex = {
34  threadId: string
35  name?: string
36  branch?: string
37  project: string
38  calls: number
39  lastCallAt?: string
40}
41
42/** What the pane draws from: the last `vybava fleet --json` that succeeded. */
43export type FleetView = {
44  generatedAt: string
45  counts: FleetPaneCounts
46  sessions: FleetPaneSession[]
47}
48
49declare module 'claude-code' {
50  interface PluginState {
51    'fleet-pane': {
52      view: FleetView | null
53      /** Codex rows from the last refresh that read them (every ~60 s). */
54      codex: FleetPaneCodex[]
55      /** Why the last refresh failed; null once one succeeds. */
56      problem: string | null
57      /** The session whose reply field is open. */
58      replyTo: string | null
59      /** The last action's outcome: sent, not delivered, copied. */
60      notice: string | null
61      /** This session's own id: its row is marked and left out of the count. */
62      self: string | null
63    }
64  }
65}
66