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 type { NodeKind, Project } from '@shared/types'
import type { AgentId, AgentPermissionMode } from '@shared/agents/config'
import {
type CanvasNode,
type NodeData,
createTerminalNode,
createAgentNode,
createEditorNode,
createVideoNode,
createWebNode,
createBrowserNode,
createDiffNode,
createStickyNode,
createDinoNode,
createFilesNode,
createRunNode,
createSimulatorNode,
createWhiteboardNode,
isAccountLoginNode
} from '@renderer/state/workspace'
import { normalizeRunConfig } from '@shared/run-config'
import { normalizeSimulatorConfig } from '@shared/simulator'
import { absolutePosition, type FocusableNode } from './nodeFocus'
import { normalizeNodeIcon } from '@shared/node-icon'
import { normalizeTerminalFontSize } from '../terminal/terminal-font-zoom'
export type RestorableNodeKind = Exclude<NodeKind, 'group' | 'subagent' | 'loop'>
export interface ReopenNodeSnapshot {
type: RestorableNodeKind
/** Raw position as stored on the node — relative to `parentId` when one is set. */
position: { x: number; y: number }
/** Precomputed via `absolutePosition` at snapshot time, for when the parent is gone by
* restore time (its own raw position would then be meaningless on its own). */
absolutePosition: { x: number; y: number }
parentId?: string
extent?: 'parent'
size?: { width: number; height: number }
data: NodeData
/**
* The id of the matching entry this same delete also recorded in the persisted
* `Project.closedSessions` history, when one was recorded — set only by `deleteNodes` (Canvas),
* never by `stateToReopenSnapshot`'s reverse direction. Lets the two ledgers consume each
* other: reopening this ⇧⌘T snapshot drops the persisted twin (`reopenLastClosedCommand`), and
* reopening the persisted twin from the sidebar drops this snapshot out of the ⇧⌘T stack
* (`reopenClosedSessionCommand` → `useReopenHistory.dropByClosedSessionId`) — so a single delete
* can never be reopened twice into two duplicate nodes.
*/
closedSessionId?: string
}
type SnapshotSource = {
/** The node's id — only a whiteboard reads it (its rebuilt copy reads the board by this id). */
id?: string
type?: string
position: { x: number; y: number }
parentId?: string
/** @xyflow/react's `Node.extent` is `'parent' | CoordinateExtent | undefined` — only the
* `'parent'` literal matters here, so this stays loosely typed rather than importing that
* union just to narrow it. */
extent?: unknown
width?: number | null
height?: number | null
data: NodeData
}
// 'trigger' has no matching case in recreateNodeFromSnapshot's buildBase below (it always
// recreates to null) — excluded here so a deleted trigger node never becomes a dead, clickable
// closed-session/reopen-history entry.
const UNRESTORABLE: ReadonlySet<string> = new Set(['group', 'subagent', 'loop', 'trigger'])
/** Captures a node right before deletion. `all` must be the FULL live tree (before any
* mutation), so the parent chain is still walkable. Returns null for kinds this feature
* doesn't cover: group/subagent/loop nodes, and the account-login node (deleting it is a
* distinct "remove this account's node" action, not a close a user wants back). */
export function snapshotNode(
node: SnapshotSource,
all: readonly FocusableNode[]
): ReopenNodeSnapshot | null {
const type = node.type ?? 'terminal'
if (UNRESTORABLE.has(type)) return null
if (isAccountLoginNode(node.data)) return null
const size =
typeof node.width === 'number' && typeof node.height === 'number'
? { width: node.width, height: node.height }
: undefined
return {
type: type as RestorableNodeKind,
position: node.position,
absolutePosition: absolutePosition({ id: '__snapshot__', position: node.position, parentId: node.parentId }, all),
...(node.parentId ? { parentId: node.parentId } : {}),
...(node.extent === 'parent' ? { extent: 'parent' as const } : {}),
...(size ? { size } : {}),
// A whiteboard is rebuilt under a NEW id; it reads the deleted board's file by this one.
data: type === 'whiteboard' ? { ...node.data, whiteboardSource: node.data.whiteboardSource ?? node.id } : node.data
}
}
export interface RecreateContext {
/** ids present in the tree right now — decides whether the original parent group is still
* around to reattach to. Groups are never recreated by this feature, so this only ever
* needs to reflect nodes that were never deleted. */
liveNodeIds: ReadonlySet<string>
project: { ssh?: Project['ssh'] } | undefined
/** Validates/redirects an account id against the accounts that exist right now (a removed
* account must not be stamped onto a new node). */
resolveAccountId: (accountId: string | undefined) => string | undefined
permissionModeFor: (agentId: AgentId) => AgentPermissionMode | undefined
}
const COSMETIC_KEYS = [
'title', 'titleAuto', 'color', 'group', 'tags', 'collapsed', 'expandedHeight', 'shell', 'agentModel'
] as const
function withCosmetics(node: CanvasNode, data: NodeData): CanvasNode {
const cosmetics: Partial<NodeData> = {}
for (const key of COSMETIC_KEYS) {
const value = data[key]
if (value !== undefined) (cosmetics as Record<string, unknown>)[key] = value
}
// The icon is a cosmetic too, but not a plain copy: a persisted snapshot comes from
// workspace.json, which is hand-editable, so it crosses the same validator hydration uses.
// Without this a reopened session came back without the icon it was closed with.
const icon = normalizeNodeIcon(data.icon)
if (icon) cosmetics.icon = icon
// The per-terminal font size (issue #915) is a cosmetic too, and crosses the same validator the
// serializers use: the persisted twin comes from the hand-editable workspace.json.
const terminalFontSize = normalizeTerminalFontSize(data.terminalFontSize)
if (terminalFontSize !== undefined) cosmetics.terminalFontSize = terminalFontSize
return { ...node, data: { ...node.data, ...cosmetics } }
}
function buildBase(snapshot: ReopenNodeSnapshot, ctx: RecreateContext): CanvasNode | null {
const d = snapshot.data
switch (snapshot.type) {
case 'terminal': {
if (d.sshRemoteTmux && d.ssh) {
// `remoteCwd` is non-optional on `Project['ssh']` — a remote node always had a cwd, but
// fall back to '' (server default `~`) rather than asserting the type away.
const sshBinding: Project['ssh'] = { server: d.ssh, remoteCwd: d.cwd ?? '' }
return d.agentId
? createAgentNode(
d.agentId,
0,
d.cwd,
undefined,
undefined,
sshBinding,
ctx.resolveAccountId(d.accountId),
ctx.permissionModeFor(d.agentId)
)
: createTerminalNode(0, d.cwd, undefined, undefined, sshBinding)
}
if (d.ssh) {
// Standalone "SSH terminal" node (local `ssh …`, not a remote-tmux project node).
// Deliberately NOT routed through `createSshTerminalNode(server, …)`: that factory
// RECOMPUTES `execTrusted: server.extraArgs ? true : undefined` from whatever server
// object it's handed, which would mint trust=true for `extraArgs` of unknown
// provenance (e.g. hydrated some other way). `d.ssh` is the LIVE node's own data
// object, captured at snapshot time — its `execTrusted` already reflects genuine
// local provenance (see `SshConnection.execTrusted`'s doc in shared/ssh.ts), so it is
// copied verbatim, never re-derived. Build off `createTerminalNode` for id/size/position
// scaffolding, then stamp `data.ssh` directly (no `sshRemoteTmux` — that flag means the
// OTHER, remote-tmux-project case above).
const scaffold = createTerminalNode(0)
return { ...scaffold, data: { ...scaffold.data, ssh: d.ssh } }
}
if (d.agentId) {
return createAgentNode(
d.agentId,
0,
d.cwd,
undefined,
undefined,
ctx.project?.ssh,
ctx.resolveAccountId(d.accountId),
ctx.permissionModeFor(d.agentId)
)
}
// A run node reopens as a run node (same folder/configuration/device); its run is NOT
// restarted — the toolbar's Run is the user's call, as on first open.
const runConfig = normalizeRunConfig(d.runConfig)
if (runConfig) return createRunNode(0, runConfig)
return createTerminalNode(0, d.cwd, undefined, undefined, ctx.project?.ssh)
}
case 'sticky': {
const node = createStickyNode(0)
return { ...node, data: { ...node.data, text: d.text ?? '' } }
}
case 'editor':
return d.filePath ? createEditorNode(0, d.filePath, undefined, d.sshFs) : null
case 'video':
return d.filePath ? createVideoNode(0, d.filePath, undefined, d.sshFs) : null
// A files node IS restorable — its whole state is the directory it shows — so it gets a case
// here rather than a seat in UNRESTORABLE beside 'trigger'. Registering it in neither list is
// the trap the 'trigger' comment above warns about: the snapshot is taken, the reopen entry is
// written, and `default: return null` then makes it a dead click. Compiles and typechecks
// either way, which is why the rule is written down rather than left to be noticed.
case 'files':
return d.cwd ? createFilesNode(0, d.cwd, undefined, d.sshFs) : null
case 'diff':
return d.cwd && d.filePath ? createDiffNode(0, d.cwd, d.filePath, !!d.diffStaged, undefined, d.commitOid) : null
case 'web':
return createWebNode(0, { url: d.url, filePath: d.filePath })
case 'browser':
return createBrowserNode(0, d.url ?? '', undefined, d.partition)
case 'dino':
return createDinoNode(0, undefined, d.highScore ?? 0)
case 'whiteboard': {
const wb = createWhiteboardNode(0)
// A reopen restores a board; it does not jump into drawing on it.
wb.data.autoEdit = undefined
if (d.whiteboardSource) wb.data.whiteboardSource = d.whiteboardSource
return wb
}
// A Simulator node's whole state is which device it shows.
case 'simulator':
return createSimulatorNode(0, normalizeSimulatorConfig(d.simulator))
default:
return null
}
}
/** Rebuilds a fresh node from a snapshot: same kind, position, parent group (if it still
* exists), and cosmetic metadata — but a NEW id/session, assembled through the same factories
* "New terminal/agent/…" uses, so e.g. an agent node's launch command is computed correctly
* for the CURRENT permission mode rather than replaying a stale one. Returns null for a kind
* this feature doesn't cover, or when required data (e.g. an editor's filePath) is missing —
* never a silently wrong node. */
export function recreateNodeFromSnapshot(snapshot: ReopenNodeSnapshot, ctx: RecreateContext): CanvasNode | null {
const base = buildBase(snapshot, ctx)
if (!base) return null
const node = withCosmetics(base, snapshot.data)
const reattach = !!snapshot.parentId && ctx.liveNodeIds.has(snapshot.parentId)
node.position = reattach ? snapshot.position : snapshot.absolutePosition
node.parentId = reattach ? snapshot.parentId : undefined
// `snapshot.extent` is loosely typed (see SnapshotSource) — narrow back to the one literal
// this codebase ever sets on a child node.
node.extent = reattach && snapshot.extent === 'parent' ? 'parent' : undefined
if (snapshot.size) {
node.width = snapshot.size.width
node.height = snapshot.size.height
node.style = { ...node.style, width: snapshot.size.width, height: snapshot.size.height }
}
return node
}