margins

1// margins as a Claude Code mod: a band above the prompt with one row per
2// dialog this session holds, saying whose turn it is and whether the file is
3// watched, redrawn from the session's state file once a second.
4//
5// MARGINS_BAND=0 turns it off.
6import { parse, row, type Dialog, type Seg } from './dialogs.ts'
7
8let sid = ''
9let file = ''
10let seen = -1
11let busy = false
12let show = true
13let hasProc = false
14let ownNs = ''
15let dialogs: Dialog[] = []
16let live = new Set<string>()
17let checked = 0
18// Closed dialogs leave the band at the first prompt the person sends after
19// they closed; the watch's own end notification is not one.
20let promptedAt = 0
21
22// The session's state file, resolved the way margins.sh resolves it
23async function locate($) {
24  show = (await $.env.get('MARGINS_BAND')) !== '0'
25  hasProc = await $.fs.exists('/proc/self/stat')
26  let dir = (await $.env.get('MARGINS_DIR')) ?? ''
27  if (dir === '') {
28    const xdg = (await $.env.get('XDG_RUNTIME_DIR')) ?? ''
29    if (xdg !== '' && (await $.fs.exists(xdg))) {
30      dir = xdg + '/margins'
31    } else {
32      const tmp = (await $.env.get('TMPDIR')) || '/tmp'
33      const id = await $.process.run(['id', '-u'])
34      dir = tmp.replace(/\/$/, '') + '/margins-' + id.stdout.trim()
35    }
36  }
37  if (hasProc) {
38    const link = await $.process.run(['readlink', '/proc/self/ns/pid'])
39    ownNs = link.stdout.replace(/[^0-9]/g, '')
40  }
41  file = dir + '/' + sid.replace(/[^A-Za-z0-9._-]/g, '_') + '.log'
42  seen = -1
43  dialogs = []
44}
45
46// A watch whose process is gone no longer sees saves. Across pid namespaces
47// (a sandbox) the pid means nothing here, so it counts as alive.
48async function alive($, d: Dialog): Promise<boolean> {
49  if (!d.pid) return false
50  if (d.ns && ownNs && d.ns !== ownNs) return true
51  if (hasProc) return $.fs.exists('/proc/' + d.pid)
52  const r = await $.process.run(['kill', '-0', d.pid])
53  return r.exitCode === 0
54}
55
56async function refresh($) {
57  if (busy) return
58  busy = true
59  try {
60    await tick($)
61  } finally {
62    busy = false
63  }
64}
65
66async function tick($) {
67  const now = (await $.clock.now()) / 1000
68  const id = String(await $.session.id())
69  if (id !== sid) {
70    sid = id
71    await locate($)
72  }
73  const stat = await $.fs.stat(file).catch(() => undefined)
74  let changed = false
75  if (!stat) {
76    changed = dialogs.length > 0
77    dialogs = []
78  } else if (stat.mtimeMs !== seen) {
79    seen = stat.mtimeMs
80    dialogs = parse(await $.fs.read(file).catch(() => ''))
81    changed = true
82  }
83  if (dialogs.length > 0 && (changed || now - checked >= 2)) {
84    checked = now
85    const next = new Set<string>()
86    for (const d of dialogs) if (await alive($, d)) next.add(d.path)
87    if (next.size !== live.size || [...next].some((p) => !live.has(p))) changed = true
88    live = next
89  }
90  if (changed) $.ui.invalidate('ui.render')
91}
92
93const shown = () => dialogs.filter((d) => d.phase !== 'closed' || d.at >= promptedAt)
94
95export function register(on) {
96  on('session.start', async ($, e, next) => {
97    $.clock.every(1000, () => refresh($))
98    return next(e)
99  })
100
101  on('prompt.submit', async ($, e, next) => {
102    try {
103      if (e.origin?.kind !== 'composer' && e.origin?.kind !== 'bridge') return next(e)
104      promptedAt = (await $.clock.now()) / 1000
105      if (dialogs.some((d) => d.phase === 'closed')) $.ui.invalidate('ui.render')
106    } catch {
107      // The band is a courtesy; the prompt goes through regardless.
108    }
109    return next(e)
110  })
111
112  // One row per dialog, with anything other mods draw there kept below.
113  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
114    const rows = shown()
115    if (!show || rows.length === 0 || e.props.hasSurvey) return next(e)
116    const { Box, Text } = $.ui.resolve(e)
117    const draw = (seg: Seg) =>
118      seg.color || seg.dim || seg.bold
119        ? Text({ color: seg.color, dimColor: seg.dim, bold: seg.bold, children: [seg.text] })
120        : seg.text
121    const room = Math.max(1, e.props.maxRows - 1)
122    const lines = rows
123      .slice(-room)
124      .map((d) => Text({ wrap: 'truncate-end', children: row(d, live.has(d.path), e.props.isWorking).map(draw) }))
125    const theirs = await next(e)
126    return Box({ flexDirection: 'column', children: theirs ? [...lines, theirs] : lines })
127  })
128}
129

1// The state file margins.sh appends to, read back as one entry per dialog.
2// Each line is `<epoch> TAB <event> TAB <absolute path> TAB <detail>`.
3
4export type Phase = 'yours' | 'saved' | 'claude' | 'closed'
5
6export type Dialog = {
7  path: string
8  name: string
9  phase: Phase
10  turn: number
11  // The watch armed last, while it has not said it ended
12  pid: string
13  ns: string
14  at: number
15}
16
17export type Seg = { text: string; color?: string; dim?: boolean; bold?: boolean }
18
19export function parse(text: string): Dialog[] {
20  const byPath = new Map<string, Dialog>()
21  for (const line of text.split('\n')) {
22    const [at, event, path, detail = ''] = line.split('\t')
23    if (!path) continue
24    let d = byPath.get(path)
25    if (!d) {
26      d = { path, name: path.split('/').pop() ?? path, phase: 'yours', turn: 0, pid: '', ns: '', at: 0 }
27      byPath.set(path, d)
28    }
29    d.at = Number(at) || d.at
30    const n = Number(detail)
31    switch (event) {
32      case 'open':
33      case 'reply':
34        d.phase = 'yours'
35        break
36      case 'save':
37        d.phase = 'saved'
38        break
39      case 'turn':
40        d.phase = 'claude'
41        break
42      case 'closed':
43        d.phase = 'closed'
44        d.pid = ''
45        break
46      case 'watch': {
47        const [pid = '', ns = ''] = detail.split(' ')
48        d.pid = pid
49        d.ns = ns
50        if (d.phase === 'closed') d.phase = 'yours'
51        continue
52      }
53      case 'unwatch':
54        if (d.pid === detail) d.pid = ''
55        continue
56      default:
57        continue
58    }
59    if (event !== 'save' && Number.isFinite(n) && detail !== '') d.turn = n
60  }
61  return [...byPath.values()]
62}
63
64// One row of the band: what the dialog waits for, and whether a save will be seen.
65export function row(d: Dialog, watching: boolean, working: boolean): Seg[] {
66  const head: Seg[] = [
67    { text: d.phase === 'closed' ? '✔ ' : '✎ ', color: d.phase === 'closed' ? 'green' : 'magenta' },
68    { text: d.name, bold: d.phase !== 'closed', dim: d.phase === 'closed' },
69  ]
70  if (d.phase === 'closed') {
71    return [...head, { text: ` · closed after ${d.turn} turns`, dim: true }]
72  }
73  const segs: Seg[] = [...head, { text: ` · turn ${d.turn} · `, dim: true }]
74  // A turn that needed no reply leaves no event behind, so Claude only holds
75  // the turn while it is working.
76  if (d.phase === 'yours' || (d.phase === 'claude' && !working)) segs.push({ text: 'your turn', color: 'green' })
77  if (d.phase === 'saved') segs.push({ text: 'you saved, Claude is reading', color: 'yellow' })
78  if (d.phase === 'claude' && working) segs.push({ text: 'Claude is answering in the file', color: 'cyan' })
79  segs.push({ text: ' · ', dim: true })
80  segs.push(watching ? { text: 'watching', dim: true } : { text: 'not watched, a save goes unanswered', color: 'red' })
81  return segs
82}
83