Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { create } from 'zustand'
import { WORKING_STALE_MS } from '@shared/agents/stale'
/**
* Transient visualization of subagents a Claude node spawns (Task/Agent tool), keyed by the
* tool_use_id from the hooks. These render as ephemeral nodes + edges on the canvas; they are
* never persisted to workspace.json and never enter undo/redo (see Canvas).
*/
export interface SubagentViz {
/** The Claude terminal node that spawned this subagent. */
parentNodeId: string
/** Subagent type, e.g. 'general-purpose'. */
type?: string
/** The task description/prompt. */
label?: string
state: 'working' | 'done'
/** When it started (for the live timer). */
startedAt: number
// Filled on finish (from the PostToolUse tool_response):
durationMs?: number
tokens?: number
toolUses?: number
/** What the subagent produced (shown when the node is expanded). */
result?: string
}
export interface SubagentResult {
durationMs?: number
tokens?: number
toolUses?: number
result?: string
}
interface AgentNodesState {
byId: Record<string, SubagentViz>
/**
* Live transcript text per subagent, streamed while it runs — kept OUT of `byId` on purpose:
* Canvas subscribes to `byId` to lay out the ephemeral nodes, and chunks arrive several times
* a second, so routing them through `byId` re-rendered the whole canvas per chunk. Only the
* expanded SubagentNode subscribes here, per id.
*/
activityById: Record<string, string>
/**
* When each subagent last streamed transcript, for `sweepStaleWorking`. Kept out of `byId` for the
* same reason as `activityById`: it changes on every chunk, and Canvas lays out from `byId`.
*/
lastActivityAt: Record<string, number>
/**
* Per-ephemeral-node UI overrides (keyed by node id: subagent ids + `loop-<parentId>`).
* `positions` holds an OFFSET FROM THE PARENT AGENT NODE, not a canvas position: the card
* always shares the agent's coordinate space (it inherits the agent's `parentId`), so an
* offset survives the space CHANGING under it. Storing the position itself meant that
* grouping or ungrouping the agent — which flips its position between absolute and
* group-relative — teleported every card the user had dragged, by the group's own x/y.
*/
positions: Record<string, { x: number; y: number }>
sizes: Record<string, { width: number; height: number }>
expanded: Record<string, boolean>
/**
* The one selected ephemeral card, or null. Kept here (not in React Flow's selection) because
* the cards are `selectable: false`: a rubber-band or select-all must never sweep up a whole
* subagent fan-out and hand those ids to Group / Duplicate / Delete, which cannot act on a
* derived node. Cards select one at a time, by click, purely to show their resize frame.
*/
selectedId: string | null
/**
* `settings.autoHideFinishedSubagentCards`, mirrored here by Canvas so the store stays free of
* the settings store.
*
* On, a card is DROPPED at the moment its subagent REPORTS done — `finish()`, and only
* `finish()` — rather than left `done` for the next turn boundary to take. Only a finished card
* is ever dropped, so #547's rule (a new turn must keep the cards of subagents that are still
* running) and Eco's `liveSubagents` are untouched.
*
* **`sweepStaleWorking`'s decay is deliberately NOT gated on this.** That sweep fires precisely
* because the end never ARRIVED (crashed CLI, killed pane, slept machine), which is the opposite
* of the setting's promise, and it is the one case where a visible card carries the most
* information: drop it and a fan-out whose subagents died silently leaves nothing on the canvas
* that says a subagent was ever launched. The decay keeps marking `done` and the turn boundary
* takes the card, exactly as it did before this setting existed. It costs Eco nothing — an
* absent card and a `done` card are the same answer to `liveSubagents`.
*
* Off is the default and reproduces the previous behavior exactly.
*/
autoHideFinished: boolean
setAutoHideFinished(on: boolean): void
select(id: string | null): void
setPosition(id: string, offset: { x: number; y: number }): void
setSize(id: string, size: { width: number; height: number }): void
toggleExpanded(id: string): void
/** Drop a card's dragged position + resized size, returning it to its laid-out spot. */
resetPlacement(id: string): void
/**
* Draw (or re-open) a card. `supersedes` names a card this one REPLACES — Claude's first subagent
* of a session is drawn from its tool call, then its native `SubagentStart` arrives under the
* child's own id (core/claude-subagent-lifecycle.ts). The old card's start time, place, size,
* expansion and selection move to the new key, so the user sees one card that never moved. Its
* streamed activity is DROPPED, not moved: the native tail reads the same transcript file from
* its first byte, and moving it would print everything twice.
*
* `lastActivityAt` seeds the sweep's clock for a card replayed after a reload; it is kept out of
* `byId` like every activity time. A superseded card's clock is carried too (it is a time, not
* text, so it cannot double) — the new key must not look older than the card it replaces.
*/
start(
toolUseId: string,
viz: Omit<SubagentViz, 'state' | 'startedAt'> & { startedAt?: number; lastActivityAt?: number },
supersedes?: string
): void
/**
* End a card. Idempotent on a card already done — except that a late end carrying STATS (tokens
* / tool uses) fills them in: Claude's native stop ends a sync child ~40 ms before the tool
* path's end brings the numbers the card shows, and dropping those would be a regression.
*/
finish(toolUseId: string, result: SubagentResult): void
/** Append a chunk of the subagent's live transcript. */
appendActivity(toolUseId: string, chunk: string): void
/**
* Remove ALL subagents spawned by a given parent node, finished or not.
*
* For the paths where the parent itself is gone or its session has ended — node deleted, project
* deleted, cross-project close, orphan-session kill, `SessionEnd`. A node that no longer exists
* has no work left to represent, so there is nothing to preserve.
*
* **NOT for a turn boundary** — see `clearFinishedForParent` and issue #547.
*/
clearForParent(parentNodeId: string): void
/**
* Drop only the FINISHED subagent cards of a parent. The turn-boundary clear.
*
* Issue #547: `clearForParent` ran on every new turn on the assumption that the previous fan-out
* is stale by definition. That holds for a card whose subagent has finished and is false for one
* that has not — Claude launches subagents async, and "waiting for N background agents to finish"
* is exactly the state in which the user types the next prompt. The card vanished permanently
* (nothing rehydrates `byId`: `start()` fires only from a live `PreToolUse`, and a subagent past
* that emits no second one) while the agent kept working. Same permanent loss as #402, different
* trigger.
*
* The more expensive half is not the missing card. Eco's hibernation guard derives `liveSubagents`
* from this same store, so a wiped card let a parent with live background agents read as idle and
* get its CLI `/exit`ed — the regression #402 was raised to close.
*
* `state` already draws the line the fix needs (`'working' | 'done'`, `finish()` idempotent), so
* this needs no new concept. What it does need is the decay: see `sweepStaleWorking`.
*/
clearFinishedForParent(parentNodeId: string): void
/**
* Mark every card still `working` with no sign of life for `staleMs` as done — the decay `clearFinishedForParent`
* depends on.
*
* Without it a subagent whose `finish()` never arrives (crashed CLI, killed pane, slept machine)
* pins its card forever AND pins its parent against Eco forever, which is a worse bug than the
* one being fixed. The number is `WORKING_STALE_MS`, imported rather than chosen: that module
* exists because three surfaces each invented their own timeout, and a subagent card inventing a
* fourth would be the same mistake in a new place.
*
* "No sign of life" counts from the card's last streamed activity, falling back to its start.
* Counting from the start alone declared every subagent that ran longer than the window dead
* while its transcript was still streaming, and the next turn boundary then removed its card.
*
* It marks done rather than deleting, so the card stays readable and the next turn boundary takes
* it; `finish()` landing late is a no-op on an entry that is already done.
*/
sweepStaleWorking(now?: number, staleMs?: number): void
/**
* Drop every dragged position/size/expanded override for a parent's subagent cards, snapping
* them back to the default packed grid (`offsetFrom`'s fallback in Canvas) at base dims — an
* expanded card kept at its larger size would still overlap its grid neighbors. Loop cards are
* excluded — there is only ever one per parent, so there is nothing to pack. If this is ever
* extended to loop cards, route through `saveLoopOverrides` too, or a cleared `loop-*` entry
* would resurrect from its localStorage mirror on reload.
*/
tidyFanout(parentNodeId: string): void
/**
* Drop the loop card's UI overrides (position/size/expanded) for a parent. Separate from
* clearForParent on purpose: a loop/cron card outlives turns, so the per-turn fan-out
* clear must not reset where the user dragged it — this runs only when the loop ends.
*/
clearLoop(parentNodeId: string): void
}
// Loop-card overrides survive restarts: the loop itself is persisted (agentStatus), so its
// dragged position/size must be too, or every launch teleports the card back to the default
// spot. Only `loop-*` keys are stored — subagent cards are per-turn.
// v2: `positions` changed meaning from a canvas position to an offset from the parent agent
// node. Reading a v1 entry as an offset would fling the card across the canvas, so the old key is
// simply abandoned — the cost is one reset of a dragged loop card, not a mystery jump.
const LOOP_CARDS_KEY = 'nodeterm.loopCards.v2'
type Overrides = Pick<AgentNodesState, 'positions' | 'sizes' | 'expanded'>
function loadLoopOverrides(): Overrides {
try {
const raw = localStorage.getItem(LOOP_CARDS_KEY)
if (!raw) return { positions: {}, sizes: {}, expanded: {} }
const d = JSON.parse(raw) as Partial<Overrides>
return { positions: d.positions ?? {}, sizes: d.sizes ?? {}, expanded: d.expanded ?? {} }
} catch {
return { positions: {}, sizes: {}, expanded: {} }
}
}
/** Card ids belonging to one parent. */
function cardsOf(s: AgentNodesState, parentNodeId: string): string[] {
return Object.keys(s.byId).filter((id) => s.byId[id].parentNodeId === parentNodeId)
}
/**
* Drop the given cards and everything keyed by their ids. The one removal body, so the
* unconditional clear and the turn-boundary clear cannot drift in what they take with them.
*/
function dropCards(s: AgentNodesState, ids: string[]): Partial<AgentNodesState> | AgentNodesState {
if (!ids.length) return s
const byId = { ...s.byId }
const activityById = { ...s.activityById }
const lastActivityAt = { ...s.lastActivityAt }
const positions = { ...s.positions }
const sizes = { ...s.sizes }
const expanded = { ...s.expanded }
// Loop-card overrides (`loop-<pid>`) are deliberately NOT dropped here — the card outlives turns;
// its overrides go via clearLoop when the loop itself ends.
for (const id of ids) {
delete byId[id]
delete activityById[id]
delete lastActivityAt[id]
delete positions[id]
delete sizes[id]
delete expanded[id]
}
// A card that just vanished must not stay "selected" — a later card reusing the id would come
// back pre-selected.
const selectedId = s.selectedId && ids.includes(s.selectedId) ? null : s.selectedId
return { byId, activityById, lastActivityAt, positions, sizes, expanded, selectedId }
}
function saveLoopOverrides(s: Overrides): void {
try {
const pick = <T>(m: Record<string, T>): Record<string, T> =>
Object.fromEntries(Object.entries(m).filter(([k]) => k.startsWith('loop-')))
localStorage.setItem(
LOOP_CARDS_KEY,
JSON.stringify({ positions: pick(s.positions), sizes: pick(s.sizes), expanded: pick(s.expanded) })
)
} catch {
// ignore quota / serialization errors
}
}
export const useAgentNodes = create<AgentNodesState>((set) => ({
byId: {},
activityById: {},
lastActivityAt: {},
selectedId: null,
autoHideFinished: false,
...loadLoopOverrides(),
setAutoHideFinished: (on) =>
set((s) => (s.autoHideFinished === on ? s : { autoHideFinished: on })),
select: (id) => set((s) => (s.selectedId === id ? s : { selectedId: id })),
setPosition: (id, offset) =>
set((s) => {
const next = { positions: { ...s.positions, [id]: offset } }
if (id.startsWith('loop-')) saveLoopOverrides({ ...s, ...next })
return next
}),
setSize: (id, size) =>
set((s) => {
const next = { sizes: { ...s.sizes, [id]: size } }
if (id.startsWith('loop-')) saveLoopOverrides({ ...s, ...next })
return next
}),
toggleExpanded: (id) =>
set((s) => {
const next = { expanded: { ...s.expanded, [id]: !s.expanded[id] } }
if (id.startsWith('loop-')) saveLoopOverrides({ ...s, ...next })
return next
}),
resetPlacement: (id) =>
set((s) => {
if (!(id in s.positions) && !(id in s.sizes)) return s
const positions = { ...s.positions }
const sizes = { ...s.sizes }
delete positions[id]
delete sizes[id]
if (id.startsWith('loop-')) saveLoopOverrides({ ...s, positions, sizes })
return { positions, sizes }
}),
start: (toolUseId, { lastActivityAt: seed, ...viz }, supersedes) =>
set((s) => {
const old = supersedes && supersedes !== toolUseId ? s.byId[supersedes] : undefined
const startedAt = viz.startedAt ?? s.byId[toolUseId]?.startedAt ?? old?.startedAt ?? Date.now()
const card: SubagentViz = { ...viz, state: 'working', startedAt }
// The sweep's clock: the newest of the replayed seed, this key's own and the replaced card's.
const clocks = [seed, s.lastActivityAt[toolUseId], old && supersedes ? s.lastActivityAt[supersedes] : undefined]
.filter((t): t is number => t !== undefined)
const withClock = (m: Record<string, number>): Record<string, number> =>
clocks.length ? { ...m, [toolUseId]: Math.max(...clocks) } : m
if (!old || !supersedes) {
return { byId: { ...s.byId, [toolUseId]: card }, lastActivityAt: withClock(s.lastActivityAt) }
}
const next = dropCards(s, [supersedes]) as AgentNodesState
// Move what the user did to the old card, unless the new key already carries its own.
const inherit = !(toolUseId in s.byId)
const carry = <T>(m: Record<string, T>, from: Record<string, T>): Record<string, T> =>
inherit && supersedes in from ? { ...m, [toolUseId]: from[supersedes] } : m
return {
...next,
byId: { ...next.byId, [toolUseId]: card },
lastActivityAt: withClock(next.lastActivityAt),
positions: carry(next.positions, s.positions),
sizes: carry(next.sizes, s.sizes),
expanded: carry(next.expanded, s.expanded),
selectedId: s.selectedId === supersedes ? toolUseId : next.selectedId
}
}),
finish: (toolUseId, result) =>
set((s) => {
const prev = s.byId[toolUseId]
if (!prev) return s
if (prev.state === 'done') {
if (result.tokens === undefined && result.toolUses === undefined) return s
const stats = {
...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
...(result.tokens !== undefined ? { tokens: result.tokens } : {}),
...(result.toolUses !== undefined ? { toolUses: result.toolUses } : {})
}
return { byId: { ...s.byId, [toolUseId]: { ...prev, ...stats } } }
}
if (s.autoHideFinished) return dropCards(s, [toolUseId])
// Async subagents end via a <task-notification> that carries no timing stats — fall
// back to the card's own elapsed time so the duration doesn't vanish on completion.
const durationMs = result.durationMs ?? Date.now() - prev.startedAt
return { byId: { ...s.byId, [toolUseId]: { ...prev, state: 'done', ...result, durationMs } } }
}),
appendActivity: (toolUseId, chunk) =>
set((s) => {
if (!s.byId[toolUseId]) return s
const activity = ((s.activityById[toolUseId] ?? '') + chunk).slice(-12000) // bounded tail
return {
activityById: { ...s.activityById, [toolUseId]: activity },
lastActivityAt: { ...s.lastActivityAt, [toolUseId]: Date.now() }
}
}),
clearForParent: (parentNodeId) => set((s) => dropCards(s, cardsOf(s, parentNodeId))),
clearFinishedForParent: (parentNodeId) =>
set((s) => dropCards(s, cardsOf(s, parentNodeId).filter((id) => s.byId[id].state === 'done'))),
sweepStaleWorking: (now = Date.now(), staleMs = WORKING_STALE_MS) =>
set((s) => {
// An activity time ahead of `now` (the clock stepped back after it was stamped) would keep
// the card working until wall time caught up; clamp it, so the silence window restarts once.
const future = Object.keys(s.lastActivityAt).filter((id) => s.lastActivityAt[id] > now)
const lastActivityAt = future.length
? { ...s.lastActivityAt, ...Object.fromEntries(future.map((id) => [id, now])) }
: s.lastActivityAt
const stale = Object.keys(s.byId).filter(
(id) =>
s.byId[id].state === 'working' &&
now - Math.max(s.byId[id].startedAt, lastActivityAt[id] ?? 0) > staleMs
)
if (!stale.length) return future.length ? { lastActivityAt } : s
const byId = { ...s.byId }
for (const id of stale) {
const prev = byId[id]
// No result to report — the completion signal is what went missing. The elapsed time is
// still true, and it is `finish()`'s own fallback for the async case.
byId[id] = { ...prev, state: 'done', durationMs: prev.durationMs ?? now - prev.startedAt }
}
return future.length ? { byId, lastActivityAt } : { byId }
}),
tidyFanout: (parentNodeId) =>
set((s) => {
const ids = Object.keys(s.byId).filter((id) => s.byId[id].parentNodeId === parentNodeId)
if (!ids.length) return s
const positions = { ...s.positions }
const sizes = { ...s.sizes }
const expanded = { ...s.expanded }
for (const id of ids) {
delete positions[id]
delete sizes[id]
delete expanded[id]
}
return { positions, sizes, expanded }
}),
clearLoop: (parentNodeId) =>
set((s) => {
const id = `loop-${parentNodeId}`
if (!(id in s.positions) && !(id in s.sizes) && !(id in s.expanded)) return s
const positions = { ...s.positions }
const sizes = { ...s.sizes }
const expanded = { ...s.expanded }
delete positions[id]
delete sizes[id]
delete expanded[id]
saveLoopOverrides({ positions, sizes, expanded })
return { positions, sizes, expanded, selectedId: s.selectedId === id ? null : s.selectedId }
})
}))