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
// WHICH CANVAS answers a canvas-control request — the routing half of the `nodeterm` CLI's
// authorization boundary (Canvas's onAgentControl effect). Pure, so it is unit-testable where the
// React component is not (vitest runs in the node environment); same reasoning as presenceTravel,
// whose project-travel rules this reuses.
//
// WHY IT EXISTS: React Flow only ever holds the ACTIVE project's nodes, but tmux sessions of every
// OTHER open project keep running — they survive an app restart and are re-adopted on boot. Their
// agents still hold NODETERM_CANVAS_CONTROL and still reach the (rewritten) hook endpoint, so their
// control calls arrive at a canvas that has never heard of the source node. Looking the source up
// in the live canvas alone therefore rejected every agent outside the project the app happened to
// come up on — reported as "source node is not a control-capable agent", which is what a node
// carrying a non-control agent gets, so the failure read as a lost capability rather than as the
// wrong canvas answering. Resolve the OWNING project instead, then travel to it (or, for a verb
// that reads and changes nothing, answer straight out of its serialized nodes).
import { canControlCanvas, type AgentId } from '@shared/agents/config'
import { formatIssueRef } from '@shared/github-issue-ref'
import { formatPrWaits, normalizePrWaitHold } from '@shared/pr-wait'
import {
normalizeSuccessWaitHold,
outcomeOf,
successWaitStatus,
successWaitSummary,
type StationOutcomeRecord
} from '@shared/station-outcome'
import { prHoldExpired } from './prWait'
import {
controlLaunchState,
handedOverDeps,
holdReason,
successDepFacts,
type HandoverById,
type LaunchDelivery,
type StatusById
} from './pendingLaunch'
import { projectTravel } from './presenceTravel'
import { geometryText, storedNodeGeometry, type NodeGeometry } from './nodeGeometry'
import {
projectCapabilityGrantedFor,
type CapabilityAckMap
} from '@shared/project-capability-consent'
/** The little the routing needs to know about a project (a structural subset of `Project`). */
export interface ControlProject {
id: string
closed?: boolean
unavailable?: boolean
nodes: readonly { id: string }[]
}
/** A serialized node, as the projects store keeps them for non-active projects. */
export interface StoredNode {
id: string
kind?: string
title?: string
pendingLaunch?: unknown
agentId?: string
/** The GitHub issue the session was started on — hostile until `formatIssueRef` says otherwise. */
issueRef?: unknown
/** Persisted geometry (`CanvasNodeState`): an off-screen project's rows derive their place and
* size from these (`storedNodeGeometry`). */
position?: { x: number; y: number }
size?: { width: number; height: number }
parentId?: string
collapsed?: boolean
/** Precomputed by the LIVE canvas (`liveNodeGeometry` — measured sizes); wins over the fields above. */
geometry?: NodeGeometry
}
/**
* Where a control request must be applied:
* - `active` — the source is on the live canvas (or its project is already active): apply here.
* - `switch` — an open project's canvas: activate that tab first.
* - `reopen` — a closed project (its sessions still run): restore the tab, then activate it.
* - `blocked` — a project whose files are unreadable: travelling there would show an empty canvas.
* - `unknown` — no open project owns this node id.
*/
export type ControlRoute =
| { kind: 'active' }
| { kind: 'switch'; projectId: string }
| { kind: 'reopen'; projectId: string }
| { kind: 'blocked'; projectId: string }
| { kind: 'unknown' }
/** Which project owns `sourceNodeId`, and what Canvas must do to be able to act on it. */
export function routeControlSource(
projects: readonly ControlProject[],
activeProjectId: string,
sourceNodeId: string
): ControlRoute {
const owner = projects.find((p) => p.nodes.some((n) => n.id === sourceNodeId))
if (!owner) return { kind: 'unknown' }
const travel = projectTravel(
projects.map((p) => ({ id: p.id, closed: p.closed, unavailable: p.unavailable, nodes: [] })),
activeProjectId,
owner.id
)
// `none` means "already there" — the live canvas is the right one even if its store copy lags.
if (travel.kind === 'none') return { kind: 'active' }
if (travel.kind === 'blocked') return { kind: 'blocked', projectId: owner.id }
return travel
}
/**
* The off-screen verb table lives in `@shared/control-off-screen` because CORE renders the
* agent-facing help from it and core cannot import the renderer. Re-exported here so every
* renderer caller keeps one import for "how does canvas control route".
*/
export {
needsLiveCanvas,
canColdOpen,
answersOffCanvas,
answersFromStoredNodes,
offScreenDisposition,
offScreenRefusal,
offScreenGuidanceLines,
controlVerbSetsForTests,
type OffScreenDisposition
} from '@shared/control-off-screen'
/**
* The capability half of the guard: may a session in this node drive the canvas?
*
* Plain terminals are not agent nodes. Treating missing identity as Claude made a bare shell look
* control-capable and let recovery code relabel it as an agent. A hand-launched CLI is still
* observable through its runtime hooks, but the serialized node does not gain agent authority.
*/
export function sourceIsControlCapable(agentId: unknown): boolean {
return typeof agentId === 'string' && agentId.length > 0 && canControlCanvas(agentId as AgentId)
}
/**
* The `browser` verb's resolve answer — the two things ONLY the renderer knows, computed purely so
* Canvas.tsx's IPC handler is a thin wrapper testable here. Main asks over `browserControlResolve`,
* makes the security decision itself (owner + capability + CDP gate), and does the CDP work; this
* function NEVER touches a debugger.
*
* WHY MAIN STILL DECIDES from these facts: an XSS-in-a-node-title-style bug lands in the renderer,
* the more attackable half, so the allowlist and the ledger stay main-side. The renderer reports
* facts (does this node's project exist, is the source control-capable, is the capability on right
* now — read LIVE via `projectCapabilityGrantedFor`, never cached); main re-orders them into the
* refusal decision in `browser-drive.ts`.
*/
export interface BrowserResolveNode {
id: string
agentId?: unknown
/** The node's display title — reported so main can make the cookie-read trace human-readable
* (PR 9). Never a security input. */
title?: string
}
export interface BrowserResolveProject {
id: string
cwd?: string
agentBrowserControl?: boolean
capabilityAck?: CapabilityAckMap
nodes: readonly BrowserResolveNode[]
}
export type BrowserResolveAnswer =
| { ok: false; refusal: string }
| {
ok: true
projectId: string
projectCwd?: string
sourceControlCapable: boolean
capabilityOn: boolean
/** The owner (source) agent node's title and the driven browser node's title — for the cookie
* trace only. Empty string when unknown; main falls back to the node id. */
sourceTitle: string
browserTitle: string
}
export function answerBrowserResolve(
project: BrowserResolveProject | undefined,
sourceNodeId: string,
browserNodeId?: string
): BrowserResolveAnswer {
// No open project owns the source, or the node is not on its canvas: a named, non-revoking
// refusal. (Same class as every other verb's "source node is not on an open canvas".)
if (!project) return { ok: false, refusal: 'source node is not on an open canvas' }
const node = project.nodes.find((n) => n.id === sourceNodeId)
if (!node) return { ok: false, refusal: 'source node is not on an open canvas' }
const browserNode = browserNodeId ? project.nodes.find((n) => n.id === browserNodeId) : undefined
return {
ok: true,
projectId: project.id,
projectCwd: project.cwd,
sourceControlCapable: sourceIsControlCapable(node.agentId),
// LIVE read — the drive-time capability check the whole feature's safety rests on. A project.json
// hand-edit that flipped the switch off is reflected here the next time an agent drives, which is
// exactly drive time.
// `{}`: browser control has no machine default (CAPABILITY_MACHINE_DEFAULTS) — an absent switch is
// off, and no setting on this machine can change that.
capabilityOn: projectCapabilityGrantedFor(project, 'agentBrowserControl', {}),
sourceTitle: typeof node.title === 'string' ? node.title : '',
browserTitle: typeof browserNode?.title === 'string' ? browserNode.title : ''
}
}
/** `list`'s rows, built from serialized nodes — the same shape the live canvas answers with
* (`n.type` is the persisted `kind`, `n.data.title` the persisted `title`). */
export function storedNodeListing(
nodes: readonly StoredNode[],
statuses: StatusById & Record<string, { dropped?: boolean } | undefined> = {},
deliveries: Record<string, LaunchDelivery | undefined> = {},
now: number = Date.now(),
/** Every station's latest task report (`report-outcome`, core's store mirrored). */
outcomes: Readonly<Record<string, StationOutcomeRecord>> = {},
/** Stations with unfinished handed-over work (core/station-handover.ts, mirrored). */
handovers: HandoverById = {}
) {
const live = new Set(nodes.map((n) => n.id))
// Every row carries its geometry (issue #1288), so a script needs no flag to read it; the TEXT form
// shows it only behind `list --geometry on`. A row of the live canvas arrives with it measured; a
// stored row's is derived here from the persisted fields, parent chain included.
const placed = nodes.filter(
(n): n is StoredNode & { position: { x: number; y: number }; size: { width: number; height: number } } =>
!!n.position && !!n.size
)
const geometryOf = (n: StoredNode): NodeGeometry | undefined =>
n.geometry ?? (n.position && n.size ? storedNodeGeometry({ ...n, position: n.position, size: n.size }, placed) : undefined)
const titleOf = (id: string): string => {
const t = nodes.find((n) => n.id === id)?.title
return t ? `${id} "${t}"` : id
}
return nodes.map((n) => {
const status = statuses[n.id]
// `--after-pr`: the row names what the node waits on (the pull request STATUS is the canvas's
// to judge; `list` states the wait and whether its deadline has passed, which needs no board).
const prHold = normalizePrWaitHold((n.pendingLaunch as { afterPr?: unknown } | undefined)?.afterPr)
const prExpired = !!prHold && prHoldExpired(prHold, now)
// `--after-success`: judged here in full — every fact it needs (the stations' reports, their
// turn state, whether they still exist) is already in hand, so the row can say WAITING FOR
// SUCCESS, BLOCKED BY FAILURE or EXPIRED and name the station and its note.
const successHold = normalizeSuccessWaitHold(
(n.pendingLaunch as { afterSuccess?: unknown } | undefined)?.afterSuccess
)
const successFacts = (d: string) =>
successDepFacts(d, statuses, live, outcomes, handovers)
const successState = successHold ? successWaitStatus(successHold, successFacts, now) : undefined
// Every agent row names its state: an unlabelled row used to mean idle, waiting on a person, or
// not an agent at all, so an orchestrator read a station stuck on a permission prompt as finished.
const launchState = controlLaunchState(!!n.pendingLaunch, deliveries[n.id] ?? ((n.pendingLaunch as { manualOnly?: boolean } | undefined)?.manualOnly ? { kind: 'failed', attempts: 1, at: 0 } : undefined), status, prExpired, successState) ??
(n.agentId ? agentRowState(status?.state) : undefined)
// A session started on an issue is told so on its OWN row, so `list` is enough for an agent to
// learn it is bound (and which card to move). Only a reference `formatIssueRef` vouches for.
const issue = formatIssueRef(n.issueRef)
// What this node said about its OWN task, if anything — so an orchestrator reads every
// station's verdict in the one call it already makes.
const reported = outcomeOf(outcomes, n.id)
const successWait =
successHold && !successHold.invalid && successState !== 'met'
? successWaitSummary(successHold, successFacts, titleOf)
: undefined
// Plain `--after` deps whose `done` is from BEFORE the work just handed to them: named, so an
// orchestrator reading QUEUED next to a station that reads idle knows what it is waiting for.
// (`pendingLaunch` is unvalidated here: only a list of strings is read.)
const rawAfter = (n.pendingLaunch as { after?: unknown } | undefined)?.after
const handedOver = Array.isArray(rawAfter)
? handedOverDeps(
{
id: n.id,
data: {
pendingLaunch: {
after: rawAfter.filter((d): d is string => typeof d === 'string'),
command: ''
}
}
},
live,
handovers
)
: []
const geometry = geometryOf(n)
return {
id: n.id, kind: n.kind ?? 'terminal', title: n.title ?? '',
...(geometry ?? {}),
...(issue ? { issue } : {}),
...(status?.lastTurnError ? { lastTurnErrored: true } : {}),
...(status?.lastTurnInterrupted && !status.lastTurnError ? { lastTurnInterrupted: true } : {}),
...(launchState ? { launchState } : {}),
...(launchState === 'queued' && prHold && !prHold.invalid ? { prWait: formatPrWaits(prHold) } : {}),
...(successWait ? { successWait } : {}),
...(handedOver.some((d) => holdReason(handovers[d]) === 'work')
? { handoverWait: handedOver.filter((d) => holdReason(handovers[d]) === 'work').map(titleOf).join(', ') }
: {}),
...(handedOver.some((d) => holdReason(handovers[d]) === 'background')
? { backgroundWait: handedOver.filter((d) => holdReason(handovers[d]) === 'background').map(titleOf).join(', ') }
: {}),
...(reported
? {
outcome: reported.outcome,
...(reported.note ? { outcomeNote: reported.note } : {}),
...(reported.workPending ? { outcomeSuperseded: true } : {})
}
: {})
}
})
}
/** An agent row with no launch or drop to report: its live state, in the canvas badge's words. */
function agentRowState(state: string | undefined): 'idle' | 'needs-you' | 'unconfirmed' {
if (state === 'done') return 'idle'
if (state === 'waiting' || state === 'blocked') return 'needs-you'
return 'unconfirmed'
}
const launchLabels = {
idle: 'IDLE',
'needs-you': 'NEEDS YOU',
queued: 'QUEUED',
failed: 'LAUNCH FAILED',
stalled: 'QUEUED (terminal not ready)',
starting: 'STARTING',
'brief-missing': 'HELD (its prompt file no longer exists; run it with `run` to start without it)',
dropped: 'DROPPED',
working: 'WORKING',
unconfirmed: 'AGENT STATUS UNCONFIRMED',
expired: 'EXPIRED (PR wait deadline passed; run it with `run`)',
'success-expired': 'EXPIRED (success wait deadline passed; run it with `run`)',
'waiting-success': 'WAITING FOR SUCCESS',
'blocked-failure': 'BLOCKED BY FAILURE (will not start on its own; run it with `run`)'
} as const
/** The `--geometry on` suffix of one row (`storedNodeListing` spreads the geometry flat), or '' for a
* row that has none. */
function rowGeometryText(n: ReturnType<typeof storedNodeListing>[number]): string {
const g = n as Partial<NodeGeometry>
if (typeof g.x !== 'number' || typeof g.y !== 'number' || typeof g.width !== 'number' || typeof g.height !== 'number') {
return ''
}
return geometryText({ x: g.x, y: g.y, width: g.width, height: g.height, parent: g.parent ?? null, collapsed: g.collapsed, expandedHeight: g.expandedHeight })
}
/** `list`'s text answer. `geometry` (`list --geometry on`) adds each node's place and size; off by
* default so the line an agent reads most stays short. */
export function controlListingText(
rows: ReturnType<typeof storedNodeListing>,
opts: { geometry?: boolean } = {}
): string {
return rows.map((n) => `${n.id} [${n.kind}] ${n.title}` +
(opts.geometry ? rowGeometryText(n) : '') +
(n.issue ? ` — issue ${n.issue}` : '') +
(n.launchState ? ` — ${launchLabels[n.launchState]}` : '') +
(n.prWait ? ` — waits on ${n.prWait}` : '') +
(n.successWait ? ` — needs success from: ${n.successWait}` : '') +
(n.handoverWait ? ` — waiting for ${n.handoverWait} to finish the work handed to it` : '') +
(n.backgroundWait ? ` — waiting for ${n.backgroundWait} to finish the tasks still running in its background` : '') +
(n.outcome ? ` — REPORTED ${n.outcome === 'succeeded' ? 'SUCCESS' : 'FAILURE'}${n.outcomeNote ? ` ("${n.outcomeNote}")` : ''}` : '') +
(n.outcomeSuperseded ? ' (before new work queued for it; not counted until it reports again)' : '') +
(n.lastTurnErrored ? ' — LAST TURN ERRORED' : '') +
(n.lastTurnInterrupted ? ' — LAST TURN INTERRUPTED' : '')
).join('\n')
}