flow-stack

1// flow-stack's mod: what bash hooks can't do.
2//   - the flow band above the prompt, and the slice beside the spinner (state from skills/flow/scripts/status.sh)
3//   - each flow-stack agent spawns on the model its role gets in the profile's budget:
4//   - /flow-pane: the task's slices, open gates with Approve/Reject, the other leads, this session's
5//     subagents, the evidence history, and context and cost gauges, animated while open
6import type { EngineInterface, Register, SessionUsage, Timer } from 'claude-code'
7
8type Status = {
9  task?: string
10  where?: 'main' | 'lead' | 'lane'
11  slice: { id: string; title: string } | null
12  done: number
13  total: number
14  tdd: string
15  evidence: { label: string; verdict: string; ts: string } | null
16  stale: boolean
17  // with status.sh --full, while the pane is open
18  slices?: { id: string; title: string; status: string; verdict: string }[]
19  gates?: { n: number; question: string; detail: string }[]
20  leads?: { id: string; repo: string; branch: string; task: string; slice: string }[]
21  runs?: string[]
22  est_usd?: number | null
23}
24
25// A subagent this session spawned: started at agent.spawn, counted on each tool.call it makes,
26// ended at its turn.complete.
27type Lane = { role: string; model: string; what: string; start: number; tools: number; end?: number; ok?: boolean }
28
29const PANE = 'flow-pane'
30
31type Budget = 'subagent_model' | 'build_model' | 'design_model'
32
33// A flow-stack agent the Agent call names without a model runs on the model its role gets.
34// Only flow-stack's own agents: built-ins like Explore keep Claude Code's choice.
35const ROLE: Record<string, Budget> = {
36  'flow-stack:advocate': 'design_model',
37  'flow-stack:reviewer': 'design_model',
38  'flow-stack:worker': 'build_model',
39  'flow-stack:checker': 'build_model',
40  'flow-stack:flow-agent': 'build_model',
41}
42
43// A model alias, or a full id from the API, Bedrock (us.anthropic.claude-…, ARNs), or Vertex (claude-…@date).
44const MODEL = /^(haiku|sonnet|opus|fable|inherit|[\w.:@\/-]*claude[\w.:@\/-]*)(\[1m\])?$/
45
46// The profile's frontmatter `budget:` block ("  build_model: sonnet   # comment"). A value that
47// isn't a model is dropped into `rejected`, so a typo leaves the spawn on Claude Code's choice.
48export function parseBudget(profile: string) {
49  const models: Partial<Record<Budget, string>> = {}
50  const rejected: string[] = []
51  const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(profile)?.[1] ?? ''
52  for (const m of front.matchAll(/^[ \t]+(subagent_model|build_model|design_model):[ \t]*([^\s#]+)/gm)) {
53    const [, key, value] = m as unknown as [string, Budget, string]
54    if (MODEL.test(value)) models[key] = value
55    else rejected.push(`${key}: ${value}`)
56  }
57  return { models, rejected }
58}
59
60export function bandText(s: Status): string {
61  const parts = [`flow · ${s.where === 'lane' ? 'lane of ' : ''}${s.task}`]
62  if (s.slice) parts.push(`${s.slice.id} ${s.slice.title}`)
63  if (s.total) parts.push(`${s.done}/${s.total} slices`)
64  if (s.tdd) parts.push(`tdd ${s.tdd}`)
65  if (s.evidence) {
66    parts.push(`${s.evidence.label} ${s.evidence.verdict}${s.stale ? ' · edited since' : ''}`)
67  }
68  return parts.join(' · ')
69}
70
71const SPIN = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
72const EIGHTHS = ' ▏▎▍▌▋▊▉'
73const FRAME_MS = 100
74
75// A progress bar `width` cells wide, filled to `fraction` in eighths of a cell.
76export function bar(fraction: number, width: number): string {
77  const eighths = Math.round(Math.min(1, Math.max(0, fraction)) * width * 8)
78  const full = Math.floor(eighths / 8)
79  const part = eighths % 8 ? EIGHTHS[eighths % 8] : ''
80  return '█'.repeat(full) + part + '░'.repeat(width - full - (part ? 1 : 0))
81}
82
83export const spin = (frame: number) => SPIN[frame % SPIN.length]
84
85// Consecutive equal verdicts as one run of ■, so the strip is a few Texts, not forty.
86export function strip(runs: string[]): { verdict: string; cells: string }[] {
87  const out: { verdict: string; cells: string }[] = []
88  for (const v of runs) {
89    const last = out.at(-1)
90    if (last?.verdict === v) last.cells += '■'
91    else out.push({ verdict: v, cells: '■' })
92  }
93  return out
94}
95
96export function laneText(l: Lane, now: number): string {
97  const secs = Math.max(0, Math.round(((l.end ?? now) - l.start) / 1000))
98  return `${l.role.padEnd(10)} ${l.model.padEnd(7)} ${l.what}  ${secs}s · ${l.tools} tools`
99}
100
101const LANE_LINGER_MS = 8000
102
103// Drops lanes that ended more than LANE_LINGER_MS ago; called wherever the clock is read.
104function prune(t: number) {
105  now = t
106  for (const [id, l] of lanes) if (l.end !== undefined && t - l.end > LANE_LINGER_MS) lanes.delete(id)
107}
108
109// The pane's animation: a frame count, the bar easing toward done/total, rows fading in after open.
110let frame = 0
111let openedAt = 0
112let shown = 0
113let ticker: Timer | null = null
114let now = 0
115let usage: SessionUsage | null = null
116const lanes = new Map<string, Lane>()
117
118let status: Status | null = null
119let models: Partial<Record<Budget, string>> = {}
120let paneOpen = false
121const deciding = new Set<number>()
122let running = false
123let again = false
124const toasted = new Set<string>()
125
126// Re-read the task's state; calls that land while one runs fold into one more pass.
127async function refresh($: EngineInterface) {
128  if (running) {
129    again = true
130    return
131  }
132  running = true
133  try {
134    do {
135      again = false
136      try {
137        const args = [...(paneOpen ? ['--full'] : []), await $.session.cwd()]
138        const { stdout } = await $.process.run([`${$.plugin.root}/skills/flow/scripts/status.sh`, ...args])
139        const next = JSON.parse(stdout || '{}') as Status
140        status = next.task ? next : null
141      } catch {
142        status = null
143      }
144      $.ui.invalidate('ui.render')
145    } while (again)
146  } finally {
147    running = false
148  }
149}
150
151// A gate button: record the decision (only if gate n still reads as shown), then tell Claude.
152// The question stays out of the prompt: GATES.md is repo text, the decision is the human's.
153async function decide($: EngineInterface, n: number, question: string, verdict: 'approve' | 'reject') {
154  if (deciding.has(n)) return
155  deciding.add(n)
156  try {
157    const ran = await $.process.run(
158      [`${$.plugin.root}/skills/flow/scripts/task.sh`, 'gate', String(n), verdict, question],
159      { cwd: await $.session.cwd() },
160    )
161    if (ran.exitCode !== 0) {
162      $.ui.toast(`flow-stack: ${(ran.stderr || ran.stdout).trim()}`)
163    } else {
164      const past = verdict === 'approve' ? 'approved' : 'rejected'
165      await $.prompt.submit({ text: `The human ${past} gate ${n} in the /flow-pane; see GATES.md and DECISIONS.tsv.` })
166    }
167  } finally {
168    deciding.delete(n)
169    await refresh($)
170  }
171}
172
173export const register: Register = on => {
174  on('session.start', async ($, e, next) => {
175    const home = (await $.env.get('FLOW_STACK_HOME')) ?? `${await $.env.get('HOME')}/.flow-stack`
176    const budget = parseBudget(await $.fs.read(`${home}/profile.md`).catch(() => ''))
177    models = budget.models
178    if (budget.rejected.length) {
179      $.ui.toast(`flow-stack: ignoring budget ${budget.rejected.join(', ')} (not a model name)`, { timeoutMs: 10000 })
180    }
181    await $.command.register({ name: 'flow-pane', description: "Open flow-stack's pane: slices, gates to approve, leads" })
182    void refresh($)
183    return next(e)
184  })
185
186  on('command.run', { command: 'flow-pane' }, async $ => {
187    await $.ui.open({ id: PANE, title: 'flow' })
188    paneOpen = true
189    openedAt = frame
190    shown = 0
191    ticker ??= $.clock.every(FRAME_MS, () => {
192      frame++
193      const target = status?.total ? status.done / status.total : 0
194      shown = Math.abs(target - shown) < 0.005 ? target : shown + (target - shown) * 0.25
195      void $.clock.now().then(prune)
196      if (frame % 10 === 1) void $.session.usage().then(u => (usage = u), () => {})
197      $.ui.invalidate('ui.render')
198    })
199    void refresh($)
200    return {}
201  })
202
203  on('ui.close', { id: PANE }, async ($, e, next) => {
204    const closed = await next(e)
205    paneOpen = false
206    ticker?.cancel()
207    ticker = null
208    return closed
209  })
210
211  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
212    const { Box, Button, Text } = $.ui.resolve(e)
213    const { slices = [], gates = [], leads = [], runs = [], est_usd = null } = status ?? {}
214    const age = frame - openedAt
215    const pulse = Math.floor(frame / 5) % 2 === 0
216    // row i fades in on frame i after the pane opens
217    const faded = (i: number) => age <= i
218    const verdictColor = (v: string) => (v === 'PASS' ? 'success' : v === 'FAIL' ? 'error' : 'subtle')
219    const ctx = usage?.context.percent
220    const usd = usage?.cost?.usd
221    const agents = [...lanes.entries()]
222    const busy = agents.filter(([, l]) => l.end === undefined).length
223    return (
224      <Box flexDirection="column" gap={1}>
225        {status ? (
226          <Box gap={1}>
227            <Text color="claude">{spin(frame)}</Text>
228            <Text bold>{bandText(status)}</Text>
229          </Box>
230        ) : (
231          <Text dimColor>No active flow task. Start one with /flow-stack:flow.</Text>
232        )}
233        {status && status.total > 0 && (
234          <Box gap={1}>
235            <Text color="claude">{bar(shown, 24)}</Text>
236            <Text dimColor>
237              {status.done}/{status.total}
238            </Text>
239          </Box>
240        )}
241        <Box flexDirection="column">
242          {slices.map((s, i) => {
243            const active = s.id === status?.slice?.id && s.status !== 'done'
244            const icon = s.status === 'done' ? '✓' : active ? spin(frame + i) : '○'
245            const iconColor = faded(i) ? 'subtle' : s.status === 'done' ? 'success' : active ? 'claude' : 'subtle'
246            return (
247              <Box key={`slice-${s.id}`} gap={1}>
248                <Text color={iconColor}>{icon}</Text>
249                <Text dimColor={faded(i) || s.status === 'done'} bold={active && !faded(i)}>
250                  {s.id} {s.title} · {s.status}
251                </Text>
252                {s.verdict !== '' && <Text color={faded(i) ? 'subtle' : verdictColor(s.verdict)}>{s.verdict}</Text>}
253              </Box>
254            )
255          })}
256        </Box>
257        {runs.length > 0 && (
258          <Box gap={1}>
259            <Box>
260              {strip(runs).map((g, i) => (
261                <Text key={`run-${i}`} color={verdictColor(g.verdict)}>
262                  {g.cells}
263                </Text>
264              ))}
265            </Box>
266            <Text dimColor>
267              last {runs.length} checks · {runs.filter(v => v === 'PASS').length} pass
268            </Text>
269          </Box>
270        )}
271        {(ctx !== undefined || usd !== undefined) && (
272          <Box flexDirection="column">
273            {ctx !== undefined && (
274              <Box gap={1}>
275                <Text color={ctx >= 80 ? 'error' : ctx >= 60 ? 'warning' : 'success'}>{bar(ctx / 100, 24)}</Text>
276                <Text dimColor>context {Math.round(ctx)}%</Text>
277              </Box>
278            )}
279            {usd !== undefined && (
280              <Text dimColor>
281                ${usd.toFixed(2)} this session{est_usd ? ` · task est $${est_usd.toFixed(2)}` : ''}
282              </Text>
283            )}
284          </Box>
285        )}
286        {agents.length > 0 && (
287          <Box flexDirection="column">
288            <Text bold>AGENTS · {busy} running</Text>
289            {agents.map(([id, l], i) => (
290              <Box key={`agent-${id}`} gap={1}>
291                <Text color={l.end === undefined ? 'claude' : l.ok ? 'success' : 'error'}>
292                  {l.end === undefined ? spin(frame + i * 2) : l.ok ? '✓' : '✗'}
293                </Text>
294                <Text dimColor={l.end !== undefined} wrap="truncate-end">
295                  {laneText(l, now)}
296                </Text>
297              </Box>
298            ))}
299          </Box>
300        )}
301        {gates.length > 0 && (
302          <Box flexDirection="column">
303            <Text bold color={pulse ? 'warning' : 'subtle'}>
304              {pulse ? '◆' : '◇'} GATES · {gates.length} waiting on you
305            </Text>
306            {gates.map(g => (
307              <Box key={`gate-${g.n}`} flexDirection="column">
308                <Text>{g.question}</Text>
309                {g.detail !== '' && <Text dimColor>{g.detail}</Text>}
310                <Box gap={1}>
311                  <Button key={`approve-${g.n}`} label="Approve" onPress={() => decide($, g.n, g.question, 'approve')} />
312                  <Button key={`reject-${g.n}`} label="Reject" onPress={() => decide($, g.n, g.question, 'reject')} />
313                  {deciding.has(g.n) && <Text color="claude">{spin(frame)} recording…</Text>}
314                </Box>
315              </Box>
316            ))}
317          </Box>
318        )}
319        {leads.length > 0 && (
320          <Box flexDirection="column">
321            <Text bold>LEADS</Text>
322            {leads.map((l, i) => (
323              <Box key={`lead-${l.id}`} gap={1}>
324                <Text color={Math.floor((frame + i * 3) / 4) % 2 === 0 ? 'success' : 'subtle'}>●</Text>
325                <Text dimColor>
326                  {l.id} · {l.repo} · {l.branch}
327                  {l.task ? ` · ${l.task}` : ''}
328                  {l.slice ? ` ${l.slice}` : ''}
329                </Text>
330              </Box>
331            ))}
332          </Box>
333        )}
334      </Box>
335    )
336  })
337
338  // evidence.sh, task.sh, and edits all change what the band shows
339  on('tool.call', async ($, e, next) => {
340    const lane = e.agentId ? lanes.get(e.agentId) : undefined
341    if (lane) lane.tools++
342    const ran = await next(e)
343    if (/^(Bash|Edit|Write|MultiEdit)$/.test(e.tool)) void refresh($)
344    return ran
345  })
346
347  on('turn.complete', async ($, e, next) => {
348    const lane = e.agentId ? lanes.get(e.agentId) : undefined
349    if (lane) {
350      lane.end = await $.clock.now()
351      lane.ok = e.reason === 'answer'
352      prune(lane.end)
353    }
354    void refresh($)
355    return next(e)
356  })
357
358  on('agent.spawn', async ($, e, next) => {
359    const role = ROLE[e.subagentType]
360    const model = !e.model && role ? models[role] : undefined
361    if (model && !toasted.has(e.subagentType)) {
362      toasted.add(e.subagentType)
363      $.ui.toast(`${e.subagentType.replace('flow-stack:', '')} → ${model}`)
364    }
365    const started = await next(model ? { ...e, model } : e)
366    if (started.agentId) {
367      const what = e.description || e.subagentType
368      const start = await $.clock.now()
369      prune(start)
370      lanes.set(started.agentId, { role: e.subagentType.replace('flow-stack:', ''), model: started.model, what, start, tools: 0 })
371    }
372    return started
373  })
374
375  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
376    if (!status || e.props.hasSurvey) return next(e)
377    const { Text } = $.ui.resolve(e)
378    return <Text dimColor wrap="truncate-end">{bandText(status)}</Text>
379  })
380
381  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
382    const s = status?.slice
383    if (!s) return next(e)
384    const tdd = status?.tdd ? ` · ${status.tdd}` : ''
385    return next({ ...e, props: { ...e.props, suffix: ` · ${s.id}${tdd}…` } })
386  })
387}
388