The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import { atom } from 'nanostores'
import { capitalize } from '@/lib/text'
export type SubagentStatus = 'completed' | 'failed' | 'interrupted' | 'queued' | 'running'
export type SubagentStreamKind = 'progress' | 'summary' | 'thinking' | 'tool'
export interface SubagentStreamEntry {
at: number
isError?: boolean
kind: SubagentStreamKind
text: string
}
export interface SubagentProgress {
id: string
parentId: null | string
goal: string
/** The child's own stored session id — lets UIs open its session window. */
sessionId?: string
/** Batch (delegation) id — exact grouping key for one fan-out's workers,
* so concurrent/nested batches never merge into one group. */
delegationId?: string
model?: string
status: SubagentStatus
taskCount: number
taskIndex: number
startedAt: number
updatedAt: number
durationSeconds?: number
costUsd?: number
inputTokens?: number
outputTokens?: number
toolCount?: number
filesRead: string[]
filesWritten: string[]
stream: SubagentStreamEntry[]
summary?: string
/** Active tool while running — cleared on terminal status. */
currentTool?: string
}
export interface SubagentNode extends SubagentProgress {
children: SubagentNode[]
}
export type SubagentPayload = Record<string, unknown>
const TERMINAL: ReadonlySet<SubagentStatus> = new Set(['completed', 'failed', 'interrupted'])
const MAX_STREAM = 24
const PREVIEW_MAX = 220
const TOOL_PREVIEW_MAX = 96
export const $subagentsBySession = atom<Record<string, SubagentProgress[]>>({})
// A turn prunes display rows, not child identities. Keep retired IDs with the
// session's current list so late starts/rosters cannot recreate completed work.
// Clearing the session (or resetting the store) releases this history too.
const retiredSubagents = new WeakMap<SubagentProgress[], Set<string>>()
function setSessionSubagents(sid: string, previous: SubagentProgress[], next: SubagentProgress[]) {
const retired = retiredSubagents.get(previous) ?? new Set<string>()
for (const item of previous) {
if (TERMINAL.has(item.status)) {
retired.add(item.id)
}
}
if (retired.size) {
retiredSubagents.set(next, retired)
}
$subagentsBySession.set({ ...$subagentsBySession.get(), [sid]: next })
}
const hasSubagentsForSession = (map: Record<string, SubagentProgress[]>, sid: string): boolean =>
Object.hasOwn(map, sid)
const getSubagentsForSession = (
map: Record<string, SubagentProgress[]>,
sid: string
): SubagentProgress[] | undefined => (hasSubagentsForSession(map, sid) ? map[sid] : undefined)
const isStr = (v: unknown): v is string => typeof v === 'string'
const str = (v: unknown) => (isStr(v) ? v : '')
const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined)
const strList = (v: unknown) => (Array.isArray(v) ? v.filter(isStr) : [])
const asStatus = (v: unknown, terminalEvent = false): SubagentStatus => {
if (v === 'completed' || v === 'failed' || v === 'interrupted') {
return v
}
if (v === 'timeout' || v === 'error') {
return 'failed'
}
if (v === 'cancelled' || v === 'canceled') {
return 'interrupted'
}
// Fail closed on completion: a subagent.complete event is terminal by
// definition, so an unrecognized (or still-active 'queued'/'running')
// status must render as a failure rather than leave a dead row spinning
// as 'running' forever. Live events keep the lenient fallback.
if (terminalEvent) {
return 'failed'
}
return v === 'queued' ? v : 'running'
}
const compact = (text: string, max = PREVIEW_MAX) => {
const line = text.replace(/\s+/g, ' ').trim()
if (!line) {
return ''
}
return line.length > max ? `${line.slice(0, max - 1)}…` : line
}
const toolLabel = (name: string) => name.split('_').filter(Boolean).map(capitalize).join(' ') || name
const formatTool = (name: string, preview = '') => {
const snippet = compact(preview, TOOL_PREVIEW_MAX)
return snippet ? `${toolLabel(name)}("${snippet}")` : toolLabel(name)
}
interface TailEntry {
isError?: boolean
preview?: string
tool?: string
}
const asTail = (v: unknown): TailEntry[] =>
Array.isArray(v)
? v
.filter((item): item is Record<string, unknown> => !!item && typeof item === 'object')
.map(item => ({
isError: item.is_error === true,
preview: str(item.preview) || undefined,
tool: str(item.tool) || undefined
}))
: []
const idOf = (p: SubagentPayload) =>
str(p.subagent_id) || `${str(p.parent_id) || 'root'}:${num(p.task_index) ?? 0}:${str(p.goal)}`
const appendStream = (stream: SubagentStreamEntry[], entry: SubagentStreamEntry) => {
const last = stream.at(-1)
if (last?.kind === entry.kind && last.text === entry.text && last.isError === entry.isError) {
return stream
}
return [...stream, entry].slice(-MAX_STREAM)
}
// The backend sends no summary on a hard child timeout (only a preview like
// "Timed out after 612.3s" + duration_seconds). Synthesize it so the terminal
// row explains why it failed instead of rendering as a bare failure.
const timeoutSummary = (payload: SubagentPayload): string => {
const seconds = num(payload.duration_seconds)
return str(payload.status) === 'timeout' ? `Timed out after ${seconds ?? '?'}s` : ''
}
function streamFromPayload(
payload: SubagentPayload,
status: SubagentStatus,
eventType: string,
at: number
): SubagentStreamEntry[] {
const out: SubagentStreamEntry[] = []
const tool = str(payload.tool_name)
const preview = str(payload.tool_preview) || str(payload.text)
const text = compact(str(payload.text) || preview)
for (const tail of asTail(payload.output_tail)) {
const line = tail.tool ? formatTool(tail.tool, tail.preview ?? '') : compact(tail.preview ?? '')
if (line) {
out.push({ at, isError: tail.isError, kind: tail.tool ? 'tool' : 'progress', text: line })
}
}
if (tool) {
out.push({ at, isError: !!payload.error, kind: 'tool', text: formatTool(tool, preview) })
}
if (eventType === 'subagent.progress' && text) {
out.push({ at, isError: !!payload.error, kind: 'progress', text })
}
if (eventType === 'subagent.thinking' && text) {
out.push({ at, kind: 'thinking', text })
}
const summary = compact(str(payload.summary) || str(payload.text) || timeoutSummary(payload))
if (TERMINAL.has(status) && summary) {
out.push({ at, isError: status === 'failed', kind: 'summary', text: summary })
}
return out
}
function toProgress(payload: SubagentPayload, prev: SubagentProgress | undefined, eventType = ''): SubagentProgress {
const at = Date.now()
const status = asStatus(payload.status, eventType === 'subagent.complete')
const tool = str(payload.tool_name)
const stream = streamFromPayload(payload, status, eventType, at).reduce(appendStream, prev?.stream ?? [])
const filesRead = strList(payload.files_read)
const filesWritten = strList(payload.files_written)
return {
id: prev?.id ?? idOf(payload),
parentId: str(payload.parent_id) || prev?.parentId || null,
goal: str(payload.goal) || prev?.goal || 'Subagent',
sessionId: str(payload.child_session_id) || prev?.sessionId,
delegationId: str(payload.delegation_id) || prev?.delegationId,
model: str(payload.model) || prev?.model,
status,
taskCount: num(payload.task_count) ?? prev?.taskCount ?? 1,
taskIndex: num(payload.task_index) ?? prev?.taskIndex ?? 0,
startedAt: prev?.startedAt ?? at,
updatedAt: at,
durationSeconds: num(payload.duration_seconds) ?? prev?.durationSeconds,
costUsd: num(payload.cost_usd) ?? prev?.costUsd,
inputTokens: num(payload.input_tokens) ?? prev?.inputTokens,
outputTokens: num(payload.output_tokens) ?? prev?.outputTokens,
toolCount: num(payload.tool_count) ?? prev?.toolCount,
filesRead: filesRead.length ? filesRead : (prev?.filesRead ?? []),
filesWritten: filesWritten.length ? filesWritten : (prev?.filesWritten ?? []),
stream,
summary: str(payload.summary) || timeoutSummary(payload) || prev?.summary || undefined,
currentTool: TERMINAL.has(status) ? undefined : tool || prev?.currentTool
}
}
const failedDelegationId = (p: SubagentPayload) => `delegation:${str(p.delegation_id)}:${num(p.task_index) ?? 0}`
/** Reconcile a scoped, race-checked snapshot without replacing stream history.
* `failedDelegations` are durable failed tasks the live roster no longer holds
* (ended, or a renderer reload dropped them): they land as terminal failed rows
* unless a live row already covers that task or a turn already retired it. */
export function reconcileSubagentSnapshot(
sid: string,
children: SubagentPayload[],
failedDelegations: SubagentPayload[] = []
) {
const map = $subagentsBySession.get()
const previous = getSubagentsForSession(map, sid) ?? []
const ids = new Set(children.map(p => str(p.subagent_id)).filter(Boolean))
const next = previous.filter(item => TERMINAL.has(item.status) || ids.has(item.id))
for (const payload of children) {
const id = str(payload.subagent_id)
if (!id || retiredSubagents.get(previous)?.has(id)) {
continue
}
const index = next.findIndex(item => item.id === id)
const prev = next[index]
if (prev && TERMINAL.has(prev.status)) {
continue
}
const projected = toProgress(payload, prev)
projected.startedAt = (num(payload.started_at) ?? 0) * 1000 || prev?.startedAt || projected.startedAt
projected.updatedAt = prev?.updatedAt ?? projected.startedAt
// A roster records the last tool, not a currently executing call. Seed cold
// activity only; a repeated snapshot must not append over newer live text.
if (!projected.stream.length && str(payload.last_tool)) {
projected.stream = [{ at: projected.updatedAt, kind: 'tool', text: formatTool(str(payload.last_tool)) }]
}
if (index < 0) {
next.push(projected)
} else {
next[index] = JSON.stringify(prev) === JSON.stringify(projected) ? prev : projected
}
}
for (const payload of failedDelegations) {
const id = failedDelegationId(payload)
const delegationId = str(payload.delegation_id)
const taskIndex = num(payload.task_index) ?? 0
if (
!delegationId ||
retiredSubagents.get(previous)?.has(id) ||
next.some(item => item.id === id || (item.delegationId === delegationId && item.taskIndex === taskIndex))
) {
continue
}
const at = (num(payload.completed_at) ?? 0) * 1000 || Date.now()
const startedAt = (num(payload.dispatched_at) ?? 0) * 1000 || at
next.push({
...toProgress({ ...payload, subagent_id: id, summary: str(payload.error) }, undefined, 'subagent.complete'),
durationSeconds: Math.max(0, Math.round((at - startedAt) / 1000)),
id,
startedAt,
updatedAt: at
})
}
if (next.length !== previous.length || next.some((item, index) => item !== previous[index])) {
setSessionSubagents(sid, previous, next)
}
}
export function clearSessionSubagents(sid: string) {
const map = $subagentsBySession.get()
if (!hasSubagentsForSession(map, sid)) {
return
}
const { [sid]: _drop, ...rest } = map
$subagentsBySession.set(rest)
}
/**
* Prune terminal-status subagent rows for a session, leaving running/queued
* entries untouched. Used at the `message.start` boundary in the desktop
* message-stream hook so that the *previous* turn's finished rows get flushed
* from the display while background subagents that outlived the spawning turn
* remain visible (and still accept late progress/complete events).
*
* Also what the Stop action uses: Stop ends the turn, not the background
* subagents it spawned. Distinct from `clearSessionSubagents` (drops every row) and from
* `pruneDelegateFallbackSubagents` (which filters by id prefix to remove
* placeholder rows once the real native event arrives).
*/
export function pruneFinishedSessionSubagents(sid: string) {
const map = $subagentsBySession.get()
const list = getSubagentsForSession(map, sid)
if (!list?.length) {
return
}
const next = list.filter(item => item.status === 'running' || item.status === 'queued')
if (next.length === list.length) {
return
}
setSessionSubagents(sid, list, next)
}
export function pruneDelegateFallbackSubagents(sid: string) {
const map = $subagentsBySession.get()
const list = getSubagentsForSession(map, sid)
if (!list?.length) {
return
}
const next = list.filter(item => !item.id.startsWith('delegate-tool:'))
if (next.length === list.length) {
return
}
setSessionSubagents(sid, list, next)
}
export function upsertSubagent(sid: string, payload: SubagentPayload, createIfMissing = true, eventType?: string) {
const map = $subagentsBySession.get()
const list = getSubagentsForSession(map, sid) ?? []
const id = idOf(payload)
const idx = list.findIndex(item => item.id === id)
if (retiredSubagents.get(list)?.has(id) || (idx < 0 && !createIfMissing)) {
return
}
const prev = idx >= 0 ? list[idx] : undefined
if (prev && TERMINAL.has(prev.status)) {
return
}
const next = toProgress(payload, prev, eventType)
const nextList = idx >= 0 ? list.map(item => (item.id === id ? next : item)) : [...list, next]
setSessionSubagents(sid, list, nextList)
}
// Statuses that end a subagent run. The store's asStatus normalizes the last
// three to failed/interrupted, so the event path treats them as terminal too.
const SUBAGENT_TERMINAL_STATUSES = new Set([
'completed',
'failed',
'interrupted',
'timeout',
'error',
'cancelled',
'canceled'
])
/** True only for a `subagent.complete` carrying a status that ends the run —
* the one event the interrupted-session guard in the message-stream must let
* through (#75505). */
export const isTerminalSubagentCompletion = (
eventType: string,
payload: Record<string, unknown> | undefined | null
): boolean =>
eventType === 'subagent.complete' &&
SUBAGENT_TERMINAL_STATUSES.has(typeof payload?.status === 'string' ? payload.status : '')
export function buildSubagentTree(items: readonly SubagentProgress[]): SubagentNode[] {
const nodes = new Map<string, SubagentNode>()
for (const item of items) {
nodes.set(item.id, { ...item, children: [] })
}
const roots: SubagentNode[] = []
for (const node of nodes.values()) {
const parent = node.parentId ? nodes.get(node.parentId) : null
if (parent) {
parent.children.push(node)
} else {
roots.push(node)
}
}
const sort = (a: SubagentNode, b: SubagentNode) =>
a.startedAt - b.startedAt || a.taskIndex - b.taskIndex || a.goal.localeCompare(b.goal)
const walk = (node: SubagentNode) => node.children.sort(sort).forEach(walk)
roots.sort(sort).forEach(walk)
return roots
}
export const activeSubagentCount = (items: readonly SubagentProgress[]) =>
items.filter(item => item.status === 'queued' || item.status === 'running').length
/** Spawn-tree panel scope (#75505): running/queued rows from EVERY session —
* cross-session visibility is the point, a background session's live work
* must stay visible — but terminal rows only for the session the user is in.
* The status-bar indicator counts the same way, so the count and the tree it
* opens can never disagree, while finished history from inactive sessions
* stops accumulating forever. */
export const subagentsForPanel = (
bySession: Record<string, SubagentProgress[]>,
activeSessionId: string | null
): SubagentProgress[] =>
Object.entries(bySession).flatMap(([sid, items]) =>
sid === activeSessionId ? items : items.filter(item => item.status === 'running' || item.status === 'queued')
)
export const failedSubagentCount = (items: readonly SubagentProgress[]) =>
items.filter(item => item.status === 'failed' || item.status === 'interrupted').length
/** Flatten every session's subagents — the scope the Spawn-tree panel and the
* status-bar indicator must agree on. */
export const allSubagents = (bySession: Record<string, SubagentProgress[]>) => Object.values(bySession).flat()