Director

1// The director's band and status line. The status line names the memory and what waits for a decision; the band
2// above the prompt shows a plan waiting to run (each task's lane; Run / Move / Cancel), a proposed lesson (its edits,
3// its check, Diff / Accept / Reject) and the delegations not yet brought back. Both read director/ui_state.py and stay silent where the project has no director memory.
4import { atom, read, update } from 'claude-code'
5import type { EngineInterface, Register } from 'claude-code'
6
7import type { Snapshot, Step } from '../types'
8
9const snap = atom({ plugin: 'director', key: 'snap' } as const, null)
10const diff = atom({ plugin: 'director', key: 'diff' } as const, null)
11const busy = atom({ plugin: 'director', key: 'busy' } as const, null)
12const message = atom({ plugin: 'director', key: 'message' } as const, null)
13const notes = atom({ plugin: 'director', key: 'notes' } as const, [] as string[])
14const steps = atom({ plugin: 'director', key: 'steps' } as const, [] as Step[])
15const verbose = atom({ plugin: 'director', key: 'verbose' } as const, true)
16
17const TOOL_PREFIX = 'mcp__plugin_director_director__'
18
19export function statusText(s: Snapshot | null, live: Step[] = [], now = Date.now()): string | undefined {
20  if (!s || !s.memory) return undefined
21  if (s.error) return `director · ${s.error.slice(0, 60)}`
22  const n = s.statements ?? 0
23  const parts = [`director · ${n} statement${n === 1 ? '' : 's'}`, `${s.accepted ?? 0} learned`]
24  const waiting = s.proposals?.length ?? 0
25  if (waiting) parts.push(`${waiting} to decide`)
26  const plans = s.plans?.length ?? 0
27  if (plans) parts.push(`${plans} plan${plans === 1 ? '' : 's'} waiting`)
28  const out = s.delegations?.length ?? 0
29  if (out) parts.push(`${out} delegated`)
30  if (s.recipes_stale) parts.push('recipes stale')
31  if (s.to_reflect) parts.push(`${s.to_reflect} to reflect`)
32  const lanes = laneText(live, s, now)
33  return lanes ? `${parts.join(' · ')} │ ${lanes}` : parts.join(' · ')
34}
35
36const MEMORY_PATH = /\/\.director\/memory\/([^/]+?)\.md$/
37
38// One tool call, seen live: which lane it belongs to and a short label. The director's own steps are its MCP tools
39// and the walk (a read of one of its memory's pages); everything else the session does is the frontier lane, and a
40// plan made on the local model (plan_local) or a task sent to a lane other than the frontier is the local lane.
41export function classify(tool: string, args: Record<string, unknown>): { lane: Step['lane']; label: string } {
42  const str = (k: string) => (typeof args[k] === 'string' ? (args[k] as string) : '')
43  const path = str('file_path') || str('path')
44  const page = path.match(MEMORY_PATH)
45  if (page) return { lane: 'director', label: `walk → ${page[1]}` }
46  if ((tool === 'Grep' || tool === 'Glob') && path.includes('/.director/memory'))
47    return { lane: 'director', label: `search memory: ${str('pattern')}`.slice(0, 80) }
48  if (tool.startsWith(TOOL_PREFIX)) {
49    const name = tool.slice(TOOL_PREFIX.length)
50    if (name === 'plan_local') return { lane: 'local', label: `plan_local: ${str('request')}`.slice(0, 80) }
51    if (name === 'delegate') return { lane: 'local', label: `→ ${str('lane')}: ${str('task')}`.slice(0, 80) }
52    const detail = str('rationale') || str('kind') || str('id') || str('request')
53    return { lane: 'director', label: `${name}${detail ? `: ${detail}` : ''}`.slice(0, 80) }
54  }
55  const base = (f: string) => f.split('/').pop() || f
56  const label =
57    tool === 'Bash'
58      ? str('description') || str('command').split('\n')[0]
59      : tool === 'Read' || tool === 'Edit' || tool === 'Write'
60        ? `${tool} ${base(path)}`
61        : tool === 'Grep' || tool === 'Glob'
62          ? `${tool} ${str('pattern')}`
63          : tool === 'Agent'
64            ? `subagent: ${str('description')}`
65            : tool.startsWith('mcp__')
66              ? tool.split('__').slice(-1)[0]
67              : tool
68  return { lane: 'frontier', label: `${tool === 'Bash' ? '$ ' : ''}${label}`.slice(0, 80) }
69}
70
71function ago(step: Step, now: number): string {
72  const secs = Math.round(((step.ms ?? now - step.t) as number) / 1000)
73  return step.state === 'running' ? `${secs}s…` : step.state === 'error' ? 'failed' : `${secs}s`
74}
75
76// The status line's live half: what each lane is doing now, or did last.
77export function laneText(live: Step[], s: Snapshot | null, now = Date.now()): string {
78  const last = (lane: Step['lane']) => [...live].reverse().find(x => x.lane === lane)
79  const f = last('frontier')
80  const l = last('local')
81  const out = (s?.delegations ?? []).find(d => !d.done)
82  const local = l ? `${l.label} (${ago(l, now)})` : out ? `${out.lane}: ${out.id} (${out.status})` : 'idle'
83  if (!f && !l && !out) return ''
84  return `frontier ▶ ${f ? `${f.label} (${ago(f, now)})` : 'idle'} │ local ▶ ${local}`
85}
86
87type Result = { error?: string } & Record<string, unknown>
88
89let poll: { cancel: () => void } | null = null
90let tick: { cancel: () => void } | null = null
91
92// The status line again from what is already known (no subprocess): called on every step and, while a step runs,
93// every second, so the elapsed time moves.
94async function redraw($: EngineInterface): Promise<void> {
95  const live = await read($, steps)
96  $.ui.status(statusText(await read($, snap), live))
97  const running = live.some(x => x.state === 'running')
98  if (running && !tick) tick = $.clock.every(1_000, () => void redraw($))
99  else if (!running && tick) {
100    tick.cancel()
101    tick = null
102  }
103}
104
105async function record($: EngineInterface, step: Step): Promise<void> {
106  await update($, steps, list => [...list, step].slice(-40))
107  await redraw($)
108}
109
110async function finish($: EngineInterface, t: number, state: Step['state']): Promise<void> {
111  await update($, steps, list => list.map(x => (x.t === t ? { ...x, state, ms: Date.now() - x.t } : x)))
112  await redraw($)
113}
114
115async function run($: EngineInterface, args: string[]): Promise<Result> {
116  const root = await $.session.root()
117  try {
118    const r = await $.process.run(['python3', `${$.plugin.root}/director/ui_state.py`, ...args], {
119      cwd: root,
120      env: { CLAUDE_PROJECT_DIR: root },
121      timeoutMs: args[0] === 'fetch' ? 600_000 : 150_000,
122    })
123    return JSON.parse(r.stdout.trim().split('\n').pop() || '{}') as Result
124  } catch (err) {
125    return { error: `ui_state.py failed: ${String(err).slice(0, 200)}` }
126  }
127}
128
129async function refresh($: EngineInterface): Promise<void> {
130  const s = (await run($, ['status'])) as unknown as Snapshot
131  await update($, snap, () => s)
132  $.ui.status(statusText(s, await read($, steps)))
133  const checking = (s.proposals ?? []).some(p => p.check === 'RUNNING')
134  if (checking && !poll) {
135    poll = $.clock.every(20_000, () => void refresh($))
136  } else if (!checking && poll) {
137    poll.cancel()
138    poll = null
139  }
140}
141
142// An action from a button: run it, say how it went, tell the session on the next prompt, and re-read the state.
143async function act($: EngineInterface, args: string[], note: string | ((r: Result) => string)): Promise<void> {
144  const what = args.join(' ')
145  await update($, busy, () => what)
146  const r = await run($, args)
147  const text = r.error ? `${what}: ${r.error}` : `${what}: done`
148  await update($, message, () => text)
149  if (!r.error) await update($, notes, xs => [...xs, typeof note === 'string' ? note : note(r)])
150  await update($, busy, () => null)
151  $.ui.toast(`director: ${text}`)
152  await refresh($)
153}
154
155// What the session needs to hear after Run: where each task went, and which are its own to do now.
156export function runSummary(r: Result): string {
157  const results = (r.results ?? []) as { id: string; lane: string; status?: string; error?: string }[]
158  return results
159    .map(x =>
160      x.error
161        ? `${x.id} failed on ${x.lane} (${x.error})`
162        : x.lane === 'frontier'
163          ? `${x.id} is yours to do now`
164          : `${x.id} delegated to ${x.lane}`,
165    )
166    .join('; ')
167}
168
169async function showDiff($: EngineInterface, id: string): Promise<void> {
170  const r = await run($, ['diff', id])
171  await update($, diff, () => ({ id, text: String(r.diff ?? r.error ?? '') }))
172}
173
174export const register: Register = on => {
175  on('session.start', async ($, e, next) => {
176    const started = await next(e)
177    // A surface without slash commands still gets the status line and the band.
178    await $.command
179      .register({
180        name: 'director-activity',
181        description: "Show or hide the director's live activity above the prompt (the status line always shows the lanes)",
182      })
183      .catch(() => undefined)
184    await refresh($)
185    return started
186  })
187
188  on('command.run', { command: 'director-activity' }, async $ => {
189    const on_ = !(await read($, verbose))
190    await update($, verbose, () => on_)
191    return { text: `director activity above the prompt: ${on_ ? 'shown' : 'hidden'}` }
192  })
193
194  on('turn.complete', async ($, e, next) => {
195    const done = await next(e)
196    await refresh($)
197    return done
198  })
199
200  // Every tool call, live: recorded on its lane when it starts and closed when it ends, so the status line and the band
201  // show what each lane is doing at every moment. The director's own tools also re-read its state.
202  on('tool.call', async ($, e, next) => {
203    const { lane, label } = classify(e.tool, e as unknown as Record<string, unknown>)
204    const t = Date.now()
205    await record($, { t, lane: e.agentId && lane === 'frontier' ? 'frontier' : lane, label: e.agentId ? `[subagent] ${label}` : label, state: 'running' })
206    try {
207      const result = await next(e)
208      await finish($, t, 'deny' in result && result.deny ? 'error' : result.isError ? 'error' : 'done')
209      if (e.tool.startsWith(TOOL_PREFIX)) void refresh($)
210      return result
211    } catch (err) {
212      await finish($, t, 'error')
213      throw err
214    }
215  }).catch(($, e, next) => next(e))
216
217  // What the person did on the band reaches the model with their next prompt, so the session's picture stays true.
218  on('prompt.submit', async ($, e, next) => {
219    const pending = await read($, notes)
220    if (!pending.length || e.command) return next(e)
221    await update($, notes, () => [])
222    return next({ ...e, context: [...(e.context ?? []), `On the director's band, the person: ${pending.join('; ')}.`] })
223  }).catch(($, e, next) => next(e))
224
225  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
226    const s = await read($, snap)
227    const proposals = s?.proposals ?? []
228    const delegations = s?.delegations ?? []
229    const plans = s?.plans ?? []
230    const live = await read($, steps)
231    const showActivity = (await read($, verbose)) && (live.length > 0 || (s?.recent ?? []).length > 0)
232    if (e.props.hasSurvey || !s?.memory || (!proposals.length && !delegations.length && !plans.length && !showActivity))
233      return next(e)
234
235    const { Box, Button, Text, Code } = $.ui.resolve(e)
236    const shown = await read($, diff)
237    const working = await read($, busy)
238    const said = await read($, message)
239    const p = proposals[0]
240    const plan = plans[0]
241
242    const now = Date.now()
243    const directorSteps = live.filter(x => x.lane === 'director').slice(-5)
244    const journal = (s?.recent ?? []).slice(-3)
245    const laneLine = (lane: Step['lane']) => {
246      const x = [...live].reverse().find(y => y.lane === lane)
247      return x ? `${x.label} · ${ago(x, now)}` : 'idle'
248    }
249
250    return (
251      <Box flexDirection="column">
252        {showActivity && (
253          <Box flexDirection="column">
254            <Text bold>Director · activity</Text>
255            {directorSteps.map(x => (
256              <Text key={`step-${x.t}`} dimColor={x.state !== 'running'}>
257                {x.state === 'running' ? '▶ ' : x.state === 'error' ? '✗ ' : '✓ '}
258                {x.label}
259              </Text>
260            ))}
261            {journal.map(j => (
262              <Text key={`journal-${j.t}-${j.kind}`} dimColor>
263                · {j.kind}: {j.what}
264              </Text>
265            ))}
266            <Text>
267              <Text bold>frontier</Text> ▶ {laneLine('frontier')}
268            </Text>
269            <Text>
270              <Text bold>local</Text> ▶ {laneLine('local')}
271            </Text>
272          </Box>
273        )}
274        {plan && (
275          <Box flexDirection="column">
276            <Text bold>Director · a plan to run{plans.length > 1 ? ` (1 of ${plans.length})` : ''}</Text>
277            {plan.request ? <Text>{plan.request}</Text> : null}
278            {plan.tasks.map(t => (
279              <Box key={`task-${plan.id}-${t.id}`} flexDirection="row" gap={1}>
280                <Text>
281                  <Text bold>{t.lane}</Text> {t.task}
282                  {t.confidential ? <Text dimColor> (confidential)</Text> : null}
283                </Text>
284                {t.movable ? (
285                  <Button
286                    key={`move-${plan.id}-${t.id}`}
287                    label="Move"
288                    onPress={() =>
289                      act($, ['plan-move', plan.id, t.id], r => `moved task ${t.id} from ${t.lane} to ${String(r.to)}`)
290                    }
291                  />
292                ) : null}
293              </Box>
294            ))}
295            <Box flexDirection="row" gap={1}>
296              <Button
297                key={`run-${plan.id}`}
298                label="Run"
299                variant="primary"
300                onPress={() => act($, ['plan-run', plan.id], r => `ran plan ${plan.id}: ${runSummary(r)}`)}
301              />
302              <Button
303                key={`cancel-${plan.id}`}
304                label="Cancel"
305                onPress={() => act($, ['plan-cancel', plan.id], `cancelled plan ${plan.id} (nothing was delegated)`)}
306              />
307            </Box>
308          </Box>
309        )}
310        {p && (
311          <Box flexDirection="column">
312            <Text bold>Director · a lesson to decide{proposals.length > 1 ? ` (1 of ${proposals.length})` : ''}</Text>
313            {p.rationale ? <Text>{p.rationale}</Text> : null}
314            <Text dimColor>{p.edits.join(', ')}</Text>
315            <Text dimColor>
316              {p.check === null ? 'not checked' : `check: ${p.check}`}
317              {p.lint ? ` · ${p.lint} lint problems` : ''}
318            </Text>
319            {!p.acceptable ? <Text color="warning">Cannot be accepted: {p.why_not}</Text> : null}
320            {shown && shown.id === p.id ? <Code source={shown.text || '(no changes)'} format="diff" /> : null}
321            <Box flexDirection="row" gap={1}>
322              <Button
323                key={`diff-${p.id}`}
324                label={shown && shown.id === p.id ? 'Hide diff' : 'Diff'}
325                onPress={() =>
326                  shown && shown.id === p.id ? update($, diff, () => null) : showDiff($, p.id)
327                }
328              />
329              {p.acceptable ? (
330                <Button
331                  key={`accept-${p.id}`}
332                  label="Accept"
333                  variant="primary"
334                  onPress={() => act($, ['accept', p.id], `accepted proposal ${p.id} (now the live memory)`)}
335                />
336              ) : null}
337              <Button
338                key={`reject-${p.id}`}
339                label="Reject"
340                onPress={() => act($, ['reject', p.id], `rejected proposal ${p.id} (the memory is unchanged)`)}
341              />
342            </Box>
343          </Box>
344        )}
345        {delegations.map(d => (
346          <Box key={`lane-${d.id}`} flexDirection="row" gap={1}>
347            <Text>
348              {d.lane}: {d.id} <Text dimColor>{d.status}</Text>
349            </Text>
350            <Button
351              key={`refresh-${d.id}`}
352              label="Status"
353              onPress={() => act($, ['refresh', d.id], `asked lane ${d.lane} for the status of ${d.id}`)}
354            />
355            {d.done ? (
356              <Button
357                key={`fetch-${d.id}`}
358                label="Fetch"
359                onPress={() => act($, ['fetch', d.id], `fetched delegation ${d.id} from lane ${d.lane}`)}
360              />
361            ) : null}
362          </Box>
363        ))}
364        {working ? <Text dimColor>working: {working}…</Text> : said ? <Text dimColor>{said}</Text> : null}
365      </Box>
366    )
367  })
368}
369

1export type Proposal = {
2  id: string
3  rationale: string
4  edits: string[]
5  lint: number
6  check: string | null
7  probes: number
8  acceptable: boolean
9  why_not: string
10}
11
12export type Delegation = { id: string; lane: string; status: string; done: boolean }
13
14export type PlanTask = { id: string; task: string; lane: string; confidential: boolean; movable: boolean }
15
16export type Plan = { id: string; request: string; tasks: PlanTask[] }
17
18export type Snapshot = {
19  memory: string | null
20  statements?: number
21  accepted?: number
22  proposals?: Proposal[]
23  delegations?: Delegation[]
24  plans?: Plan[]
25  recipes_stale?: boolean
26  to_reflect?: number
27  recent?: { t: string; kind: string; what: string }[]
28  error?: string
29}
30
31/** One step seen live in this session: a tool call on a lane, or a step of the director's own. */
32export type Step = { t: number; lane: 'frontier' | 'local' | 'director'; label: string; state: 'running' | 'done' | 'error'; ms?: number }
33
34declare module 'claude-code' {
35  interface PluginState {
36    director: {
37      snap: Snapshot | null
38      diff: { id: string; text: string } | null
39      busy: string | null
40      message: string | null
41      notes: string[]
42      steps: Step[]
43      verbose: boolean
44    }
45  }
46}
47