nursery

1import { atom, read, update } from 'claude-code'
2import type { AgentInfo, AgentStatus, EngineInterface, Register, RenderNode, Timer } from 'claude-code'
3
4import type { NurseryActivity, NurseryAgent, NurseryAgentStatus } from '../types'
5
6const PANE = 'nursery-panel'
7const TITLE = 'Subagentes'
8const MAX_AGENTS = 30
9const MAX_ACTIVITY = 5
10const TOOL_LABEL_MAX = 80
11const TEXT_LABEL_MAX = 120
12const TYPE_WIDTH = 15
13const TICK_MS = 1000
14const RECONCILE_EVERY = 5
15const MAX_ENDED_EARLY = 50
16const ABSENT_GRACE_MS = 30_000
17const WIDE_COLUMNS = 80
18const FRAME_ROWS = 2
19const MIN_PANE_ROWS = 4
20const MIN_PANE_COLUMNS = 44
21const FRAME_COLUMNS = 4
22const NURSERY_PREFIX = 'nursery:'
23
24const agents = atom({ plugin: 'nursery', key: 'agents' } as const, [])
25const clockNow = atom({ plugin: 'nursery', key: 'now' } as const, 0)
26const isPaneOffered = atom({ plugin: 'nursery', key: 'isPaneOffered' } as const, false)
27
28const TOOL_DETAIL: Readonly<Record<string, string>> = {
29  Bash: 'command',
30  Read: 'file_path',
31  Edit: 'file_path',
32  Write: 'file_path',
33  Grep: 'pattern',
34  Glob: 'pattern',
35  Agent: 'description',
36}
37
38const PATH_TOOLS = new Set(['Read', 'Edit', 'Write'])
39
40const STATUS_FROM_LIST: Readonly<Record<AgentStatus, NurseryAgentStatus>> = {
41  pending: 'running',
42  running: 'running',
43  waiting: 'running',
44  idle: 'completed',
45  completed: 'completed',
46  failed: 'failed',
47  killed: 'killed',
48}
49
50const STATUS_GLYPH: Readonly<Record<NurseryAgentStatus, string>> = {
51  running: '●',
52  completed: '✓',
53  failed: '✗',
54  killed: '■',
55}
56
57const STATUS_COLOR: Readonly<Record<NurseryAgentStatus, string>> = {
58  running: 'claude',
59  completed: 'success',
60  failed: 'error',
61  killed: 'inactive',
62}
63
64const PANE_COLOR = {
65  background: '#1e1e1e',
66  text: '#d4d4d4',
67  muted: '#8a8a8a',
68  accent: '#e5a050',
69  error: '#f07070',
70  success: '#6ccf8a',
71  border: '#5a5a5a',
72} as const
73
74const PANE_STATUS_COLOR: Readonly<Record<NurseryAgentStatus, string>> = {
75  running: PANE_COLOR.accent,
76  completed: PANE_COLOR.success,
77  failed: PANE_COLOR.error,
78  killed: PANE_COLOR.muted,
79}
80
81const ACTIVITY_GLYPH: Readonly<Record<NurseryActivity['state'], string>> = {
82  running: '…',
83  done: '✓',
84  failed: '✗',
85}
86
87type Placed = { agent: NurseryAgent; depth: number }
88
89type Ending = { status: NurseryAgentStatus; endedAt: number }
90
91const ESCAPE_SEQUENCE = /\u001b(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|[@-Z\\-_])/g
92const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g
93
94let ticker: Timer | undefined
95let ticks = 0
96let cwd: string | undefined
97const endedEarly = new Map<string, Ending>()
98let missedOnce = new Set<string>()
99
100const sanitize = (text: string): string =>
101  text.replace(ESCAPE_SEQUENCE, '').replace(/\t/g, ' ').replace(CONTROL, '')
102
103const firstLine = (text: string): string =>
104  text
105    .split(/\r\n|\r|\n/)
106    .map(line => sanitize(line).trim())
107    .find(line => line.length > 0) ?? ''
108
109const clip = (text: string, max: number): string =>
110  text.length > max ? `${text.slice(0, Math.max(0, max - 1))}…` : text
111
112const relativeTo = (path: string, root: string | undefined): string => {
113  if (root === undefined || root === '') return path
114  const prefix = root.endsWith('/') ? root : `${root}/`
115
116  return path.startsWith(prefix) ? path.slice(prefix.length) : path
117}
118
119const toolLabel = (
120  tool: string,
121  input: Readonly<Record<string, unknown>>,
122  root: string | undefined,
123): string => {
124  const field = TOOL_DETAIL[tool]
125  const raw = field === undefined ? undefined : input[field]
126  const value = typeof raw === 'string' ? raw : ''
127  const detail = firstLine(PATH_TOOLS.has(tool) ? relativeTo(value, root) : value)
128
129  return clip(detail === '' ? tool : `${tool} ${detail}`, TOOL_LABEL_MAX)
130}
131
132const formatElapsed = (ms: number): string => {
133  const total = Math.max(0, Math.floor(ms / 1000))
134  const hours = Math.floor(total / 3600)
135  const minutes = Math.floor((total % 3600) / 60)
136  const seconds = total % 60
137
138  return hours > 0
139    ? `${hours}h${String(minutes).padStart(2, '0')}m`
140    : `${minutes}m${String(seconds).padStart(2, '0')}s`
141}
142
143const shortType = (type: string): string =>
144  type.startsWith(NURSERY_PREFIX) ? type.slice(NURSERY_PREFIX.length) : type
145
146const isRunning = (agent: NurseryAgent): boolean => agent.status === 'running'
147
148const elapsedOf = (agent: NurseryAgent, now: number): string =>
149  formatElapsed((agent.endedAt ?? now) - agent.startedAt)
150
151const withActivity = (agent: NurseryAgent, activity: NurseryActivity): NurseryAgent => ({
152  ...agent,
153  activity: [...agent.activity, activity].slice(-MAX_ACTIVITY),
154})
155
156const byStatusThenStart = (a: NurseryAgent, b: NurseryAgent): number =>
157  Number(isRunning(b)) - Number(isRunning(a)) || a.startedAt - b.startedAt
158
159const arrange = (list: readonly NurseryAgent[]): Placed[] => {
160  const ids = new Set(list.map(agent => agent.id))
161  const children = new Map<string | undefined, NurseryAgent[]>()
162
163  for (const agent of list) {
164    const parent = agent.parentId !== undefined && ids.has(agent.parentId) ? agent.parentId : undefined
165    children.set(parent, [...(children.get(parent) ?? []), agent])
166  }
167
168  const walk = (parent: string | undefined, depth: number): Placed[] =>
169    [...(children.get(parent) ?? [])]
170      .sort(byStatusThenStart)
171      .flatMap(agent => [{ agent, depth }, ...walk(agent.id, depth + 1)])
172
173  return walk(undefined, 0)
174}
175
176const quietly = async (work: () => Promise<unknown>): Promise<void> => {
177  try {
178    await work()
179  } catch {
180    return
181  }
182}
183
184const isWatched = async ($: EngineInterface, agentId: string | undefined): Promise<boolean> => {
185  if (agentId === undefined) return false
186  try {
187    return (await read($, agents)).some(agent => agent.id === agentId)
188  } catch {
189    return false
190  }
191}
192
193const change = ($: EngineInterface, agentId: string, fn: (agent: NurseryAgent) => NurseryAgent) =>
194  update($, agents, list => list.map(agent => (agent.id === agentId ? fn(agent) : agent)))
195
196const toolsText = (count: number, isWide: boolean): string =>
197  isWide ? `${count} ${count === 1 ? 'herramienta' : 'herramientas'}` : `${count} herr.`
198
199const rememberEnding = (agentId: string, ending: Ending): void => {
200  endedEarly.delete(agentId)
201  endedEarly.set(agentId, ending)
202  for (const stale of endedEarly.keys()) {
203    if (endedEarly.size <= MAX_ENDED_EARLY) break
204    endedEarly.delete(stale)
205  }
206}
207
208const reconcile = async ($: EngineInterface): Promise<void> => {
209  const listed = await $.agent.list()
210  const statusById = new Map(listed.map(info => [info.id, STATUS_FROM_LIST[info.status]] as const))
211  const now = await $.clock.now()
212  const marked = missedOnce
213  const list = await update($, agents, current =>
214    current.map(agent => {
215      if (!isRunning(agent)) return agent
216      const status = statusById.get(agent.id)
217      if (status === undefined) {
218        const isPastGrace = now - (agent.resumedAt ?? agent.startedAt) > ABSENT_GRACE_MS
219
220        return marked.has(agent.id) && isPastGrace ? { ...agent, status: 'completed', endedAt: now } : agent
221      }
222
223      return status === 'running' ? agent : { ...agent, status, endedAt: now }
224    }),
225  )
226  missedOnce = new Set(list.filter(agent => isRunning(agent) && !statusById.has(agent.id)).map(agent => agent.id))
227}
228
229const stopTicking = (): void => {
230  ticker?.cancel()
231  ticker = undefined
232  missedOnce = new Set()
233}
234
235const tick = async ($: EngineInterface): Promise<void> => {
236  if (!(await read($, agents)).some(isRunning)) {
237    stopTicking()
238    return
239  }
240  ticks += 1
241  if (ticks % RECONCILE_EVERY === 0) await quietly(() => reconcile($))
242  const now = await $.clock.now()
243  await update($, clockNow, () => now)
244}
245
246const keepTicking = ($: EngineInterface): void => {
247  if (ticker !== undefined) return
248  ticker = $.clock.every(TICK_MS, () => {
249    void quietly(() => tick($))
250  })
251}
252
253const sessionCwd = async ($: EngineInterface): Promise<string | undefined> => {
254  if (cwd !== undefined) return cwd
255  try {
256    cwd = await $.session.cwd()
257  } catch {
258    return undefined
259  }
260
261  return cwd
262}
263
264const fromInfo = (info: AgentInfo, now: number): NurseryAgent => ({
265  id: info.id,
266  type: info.type,
267  description: info.description,
268  ...(info.parentId === undefined ? {} : { parentId: info.parentId }),
269  status: STATUS_FROM_LIST[info.status],
270  startedAt: now,
271  ...(STATUS_FROM_LIST[info.status] === 'running' ? {} : { endedAt: now }),
272  toolCount: 0,
273  activity: [],
274})
275
276const seed = async ($: EngineInterface): Promise<void> => {
277  const listed = await $.agent.list()
278  if (listed.length === 0) return
279  const now = await $.clock.now()
280  const list = await update($, agents, current => {
281    const known = new Set(current.map(agent => agent.id))
282    const fresh = listed.filter(info => !known.has(info.id)).map(info => fromInfo(info, now))
283
284    return [...current, ...fresh].slice(-MAX_AGENTS)
285  })
286  if (list.some(isRunning)) keepTicking($)
287}
288
289const textOf = (content: readonly { type: string; [field: string]: unknown }[]): string =>
290  content
291    .filter(block => block.type === 'text' && typeof block['text'] === 'string')
292    .map(block => block['text'] as string)
293    .join('\n')
294
295const viewAgent = async ($: EngineInterface, agentId: string): Promise<void> => {
296  const viewed = await $.ui.view({ agentId })
297  if (viewed.deny !== undefined) $.ui.toast(`No se pudo abrir el subagente: ${viewed.deny}`)
298}
299
300const offerPane = async ($: EngineInterface): Promise<void> => {
301  if (await read($, isPaneOffered)) return
302  await update($, isPaneOffered, () => true)
303  await $.ui.open({ id: PANE, title: TITLE })
304}
305
306const statusOfTurn = (reason: string): NurseryAgentStatus =>
307  reason === 'answer' ? 'completed' : reason === 'aborted' ? 'killed' : 'failed'
308
309export const register: Register = on => {
310  on('session.start', async ($, e, next) => {
311    cwd = e.cwd
312    missedOnce = new Set()
313    await quietly(() =>
314      $.command.register({ name: 'nursery-panel', description: 'Abre el panel en vivo de los subagentes' }),
315    )
316    await quietly(() => seed($))
317
318    return next(e)
319  })
320
321  on('command.run', { command: 'nursery-panel' }, async $ => {
322    const opened = await $.ui.open({ id: PANE, title: TITLE })
323
324    return {
325      text: opened.isPlaced
326        ? 'Panel de subagentes abierto.'
327        : `El panel de subagentes espera lugar: ${opened.reason}`,
328    }
329  })
330
331  on('agent.spawn', async ($, e, next) => {
332    const started = await next(e)
333    const agentId = started.agentId
334    if (agentId === undefined) return started
335
336    await quietly(async () => {
337      const now = await $.clock.now()
338      const early = e.resume === undefined ? endedEarly.get(agentId) : undefined
339      endedEarly.delete(agentId)
340      if (e.resume !== undefined) missedOnce.delete(agentId)
341      const list = await update($, agents, list => {
342        const previous = list.find(agent => agent.id === agentId)
343        const base: NurseryAgent = previous ?? {
344          id: agentId,
345          type: e.subagentType,
346          description: e.description,
347          ...(e.parentAgentId === undefined ? {} : { parentId: e.parentAgentId }),
348          status: 'running',
349          startedAt: now,
350          toolCount: 0,
351          activity: [],
352        }
353        const { endedAt: _ended, ...rest } = base
354        const agent: NurseryAgent =
355          e.resume !== undefined
356            ? { ...rest, status: 'running', resumedAt: now }
357            : early !== undefined
358              ? { ...rest, ...early }
359              : previous !== undefined && !isRunning(previous)
360                ? previous
361                : { ...rest, status: 'running' }
362
363        return [...list.filter(one => one.id !== agentId), agent].slice(-MAX_AGENTS)
364      })
365      if (list.some(isRunning)) keepTicking($)
366      await offerPane($)
367    })
368
369    return started
370  }).catch(($, e, next) => next(e))
371
372  on('tool.call', async ($, e, next) => {
373    const agentId = e.agentId
374    if (agentId === undefined || !(await isWatched($, agentId))) return next(e)
375
376    const tool = String(e.tool)
377    const callId = e.tool_use_id
378    await quietly(async () => {
379      const label = toolLabel(tool, e as unknown as Record<string, unknown>, await sessionCwd($))
380      await change($, agentId, agent =>
381        withActivity(agent, { kind: 'tool', label, state: 'running', id: callId }),
382      )
383    })
384
385    const finish = (state: NurseryActivity['state']) =>
386      quietly(() =>
387        change($, agentId, agent => ({
388          ...agent,
389          toolCount: agent.toolCount + 1,
390          activity: agent.activity.map(one =>
391            one.kind === 'tool' && one.id === callId ? { ...one, state } : one,
392          ),
393        })),
394      )
395
396    let ran: Awaited<ReturnType<typeof next>>
397    try {
398      ran = await next(e)
399    } catch (error) {
400      await finish('failed')
401      throw error
402    }
403    await finish(ran.deny !== undefined || ran.isError === true ? 'failed' : 'done')
404
405    return ran
406  }).catch(($, e, next) => next(e))
407
408  on('session.append', async ($, e, next) => {
409    const stored = await next(e)
410    const agentId = e.agentId
411
412    if (e.message.type === 'assistant' && (await isWatched($, agentId)) && agentId !== undefined) {
413      await quietly(async () => {
414        const line = firstLine(textOf(e.message.content))
415        if (line === '') return
416        await change($, agentId, agent =>
417          withActivity(agent, { kind: 'text', label: clip(line, TEXT_LABEL_MAX), state: 'done' }),
418        )
419      })
420    }
421
422    return stored
423  }).catch(($, e, next) => next(e))
424
425  on('turn.complete', async ($, e, next) => {
426    const done = await next(e)
427    const agentId = e.agentId
428
429    if (agentId !== undefined) {
430      await quietly(async () => {
431        const ending: Ending = { status: statusOfTurn(e.reason), endedAt: await $.clock.now() }
432        if (await isWatched($, agentId)) {
433          await change($, agentId, agent => ({ ...agent, ...ending }))
434        } else {
435          rememberEnding(agentId, ending)
436        }
437      })
438    }
439
440    return done
441  }).catch(($, e, next) => next(e))
442
443  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
444    const { Box, Button, Text } = $.ui.resolve(e)
445    const list = await read($, agents)
446    await read($, clockNow)
447    const now = await $.clock.now()
448    if (list.some(isRunning)) keepTicking($)
449    const bodyRows = Math.max(
450      MIN_PANE_ROWS,
451      e.props.scroll.bodyRows > 0 ? e.props.scroll.bodyRows : (e.viewport?.rows ?? 24) - 4,
452    )
453    const room = bodyRows - FRAME_ROWS
454    const columns = Math.max(MIN_PANE_COLUMNS, e.props.bodyColumns) - FRAME_COLUMNS
455    const isWide = columns >= WIDE_COLUMNS
456    const frame = (...content: RenderNode[]) => (
457      <Box flexDirection="column" width="100%" height={bodyRows} backgroundColor={PANE_COLOR.background}>
458        <Box
459          flexDirection="column"
460          flexGrow={1}
461          borderStyle="round"
462          borderColor={PANE_COLOR.border}
463          paddingX={1}
464        >
465          <Text bold color={PANE_COLOR.text}>
466            {TITLE}
467          </Text>
468          {content}
469        </Box>
470      </Box>
471    )
472
473    if (list.length === 0) {
474      return frame(<Text color={PANE_COLOR.muted}>Ningún subagente en esta sesión.</Text>)
475    }
476
477    const lines = arrange(list).flatMap(({ agent, depth }) => {
478      const indent = '  '.repeat(depth)
479      const isDone = !isRunning(agent)
480      const type = shortType(agent.type)
481      const isNursery = type !== agent.type
482      const tail = `${elapsedOf(agent, now).padStart(6)} ${toolsText(agent.toolCount, isWide).padStart(isWide ? 16 : 8)}`
483      const descriptionWidth = Math.max(8, columns - indent.length - TYPE_WIDTH - tail.length - 5)
484      const description = clip(firstLine(agent.description), descriptionWidth).padEnd(descriptionWidth)
485      const typeColor = isDone ? PANE_COLOR.muted : isNursery ? PANE_COLOR.accent : PANE_COLOR.text
486      const row = (
487        <Button key={`agent-${agent.id}`} plain onPress={() => void quietly(() => viewAgent($, agent.id))}>
488          {indent}
489          <Text color={PANE_STATUS_COLOR[agent.status]}>{STATUS_GLYPH[agent.status]}</Text>{' '}
490          <Text bold color={typeColor}>
491            {clip(type, TYPE_WIDTH).padEnd(TYPE_WIDTH)}
492          </Text>{' '}
493          <Text color={isDone ? PANE_COLOR.muted : PANE_COLOR.text}>{description}</Text>
494          <Text color={PANE_COLOR.muted}>{` ${tail}`}</Text>
495        </Button>
496      )
497      const activity = isDone
498        ? []
499        : agent.activity.map(one => {
500            const color =
501              one.kind === 'tool' && one.state === 'done' ? PANE_COLOR.muted : PANE_COLOR.text
502
503            return (
504              <Text wrap="truncate" color={color}>
505                {indent}
506                {'  '}
507                <Text color={one.state === 'failed' ? PANE_COLOR.error : color}>
508                  {one.kind === 'text' ? '»' : ACTIVITY_GLYPH[one.state]}
509                </Text>{' '}
510                {one.label}
511              </Text>
512            )
513          })
514
515      return [row, ...activity]
516    })
517
518    const visible = lines.length > room - 1 ? lines.slice(0, Math.max(1, room - 2)) : lines
519    const hidden = lines.length - visible.length
520
521    return frame(
522      ...visible,
523      ...(hidden > 0 ? [<Text color={PANE_COLOR.muted}>{`+${hidden} más`}</Text>] : []),
524    )
525  })
526
527  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
528    if (e.props.hasSurvey) return next(e)
529
530    const running = (await read($, agents)).filter(isRunning)
531    if (running.length === 0) return next(e)
532
533    const panes = await $.ui.panes()
534    if (panes.some(pane => pane.id === PANE && pane.isPlaced)) return next(e)
535
536    keepTicking($)
537    const { Box, Text } = $.ui.resolve(e)
538    await read($, clockNow)
539    const now = await $.clock.now()
540    const shown = running.slice(0, Math.max(1, e.props.maxRows))
541
542    return (
543      <Box flexDirection="column">
544        {shown.map(agent => {
545          const current =
546            [...agent.activity].reverse().find(one => one.kind === 'tool')?.label ??
547            firstLine(agent.description)
548          const line = `${shortType(agent.type)} · ${elapsedOf(agent, now)} · ${current}`
549
550          return (
551            <Text wrap="truncate">
552              <Text color={STATUS_COLOR.running}>{STATUS_GLYPH.running}</Text> {line}
553            </Text>
554          )
555        })}
556      </Box>
557    )
558  })
559}
560

1export type NurseryActivityKind = 'tool' | 'text'
2
3export type NurseryActivityState = 'running' | 'done' | 'failed'
4
5export type NurseryActivity = {
6  kind: NurseryActivityKind
7  label: string
8  state: NurseryActivityState
9  id?: string
10}
11
12export type NurseryAgentStatus = 'running' | 'completed' | 'failed' | 'killed'
13
14export type NurseryAgent = {
15  id: string
16  type: string
17  description: string
18  parentId?: string
19  status: NurseryAgentStatus
20  startedAt: number
21  endedAt?: number
22  resumedAt?: number
23  toolCount: number
24  activity: NurseryActivity[]
25}
26
27declare module 'claude-code' {
28  interface PluginState {
29    nursery: { agents: NurseryAgent[]; now: number; isPaneOffered: boolean }
30  }
31}
32