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 { tmuxUpdateEnvironmentLine } from './agents/model-gateway'
import { leadPaneHookLines } from './tmux-lead-pane'
/**
* Pure helpers for launching the system `ssh` binary as a terminal session program.
* No Electron, no node-pty — unit-testable in isolation.
*/
/** A single SSH connection's parameters (inline-persisted on a node as `data.ssh`). */
export interface SshConnection {
host: string
user: string
/** Defaults to 22. */
port?: number
/** Optional `-i` identity file path. */
identityFile?: string
/** Optional raw extra ssh args (advanced), POSIX-tokenized. */
extraArgs?: string
/**
* PROVENANCE, in memory only: this machine's own `extraArgs`, set by the two local producers —
* `createSshTerminalNode` (copied from the machine-local SSH server store, i.e. typed by the user)
* and `applyLocalNodeExec` (re-attached from the machine-local workspace index). It is NEVER
* written to a project file (`stripSharedNodeExec`) and NEVER accepted off the wire
* (`sanitizeInboundNode`), so a cloned project.json or a canvas-sync peer cannot set it.
*
* Only a trusted `extraArgs` may carry the ssh options that make the LOCAL machine execute a
* command (`ProxyCommand` & co). A corporate jump host is a legitimate reason to have one — an
* untrusted document is not. See `stripLocalExecArgs`.
*/
execTrusted?: boolean
/**
* DERIVED, in memory only (issue #427): the ambient login-agent socket to pin via
* `-o IdentityAgent=<path>` because the host's own effective ssh config says
* `IdentityAgent SSH_AUTH_SOCK` (or an equivalent env reference) — which under the app-private
* agent's env override would resolve to the WRONG agent. Set exclusively by the `ssh -G` probe
* (`core/remote-ssh/agent-probe.ts`); both annotation points (SshProjectManager.connect,
* PtyManager's remote spawn) OVERWRITE any inbound value, so a shared project.json or a
* canvas-sync peer cannot aim our ssh at a socket of their choosing. Never persisted.
*/
identityAgentSock?: string
/** Display label, copied from the saved server when the node is created. */
label?: string
}
/**
* ssh options that make ssh RUN SOMETHING, on this machine unless noted. `-o ProxyCommand=<cmd>`
* is the classic one: ssh executes `<cmd>` locally through /bin/sh, every time the node opens.
*
* - `proxycommand`, `localcommand` (+ `permitlocalcommand`), `knownhostscommand` — local exec.
* - `match` — `Match exec "<cmd>"` runs `<cmd>` locally to decide whether the block applies.
* - `include` — pulls in another config file, which may carry any of the above.
* - `pkcs11provider`, `securitykeyprovider` — dlopen a local shared object: code execution.
* - `proxyusefdpass` — only meaningful alongside ProxyCommand; refused with it.
* - `remotecommand` — exec on the far side rather than here, but still not something a document
* gets to choose.
*/
const LOCAL_EXEC_SSH_OPTIONS = new Set([
'proxycommand',
'localcommand',
'permitlocalcommand',
'knownhostscommand',
'match',
'include',
'pkcs11provider',
'securitykeyprovider',
'proxyusefdpass',
'remotecommand'
])
/** The keyword of an ssh `-o` value: `ProxyCommand=x`, `ProxyCommand x` and a bare `Match` all
* yield `proxycommand` / `match`. */
function optionKeyword(value: string): string {
return value.split(/[=\s]/, 1)[0].trim().toLowerCase()
}
/**
* Remove the exec-enabling options from a tokenized extra-args list — the exec-site guard, in the
* same idiom as `permissionModeFlag` / `SAFE_SESSION_ID`: re-validate where the value BECOMES a
* command, and degrade safely (the connection is still attempted, just without the option that
* would have run code). Everything else — `-J jump`, `-o StrictHostKeyChecking=no`, `-A`, `-v` —
* passes through untouched.
*
* Both spellings of an option are covered (`-o ProxyCommand=x` and `-oProxyCommand=x`), and `-F`
* (an alternate ssh_config, which may itself carry a ProxyCommand) counts as exec-enabling.
*/
export function stripLocalExecArgs(tokens: string[]): { args: string[]; dropped: string[] } {
const args: string[] = []
const dropped: string[] = []
for (let i = 0; i < tokens.length; i++) {
const t = tokens[i]
// `-F <file>` / `-F<file>`: an ssh_config we did not write.
if (t === '-F') {
dropped.push(t, ...(i + 1 < tokens.length ? [tokens[++i]] : []))
continue
}
if (t.startsWith('-F') && t.length > 2) {
dropped.push(t)
continue
}
if (t === '-o') {
const value = tokens[i + 1]
if (value !== undefined && LOCAL_EXEC_SSH_OPTIONS.has(optionKeyword(value))) {
dropped.push(t, value)
i++
continue
}
args.push(t)
continue
}
if (t.startsWith('-o') && t.length > 2 && LOCAL_EXEC_SSH_OPTIONS.has(optionKeyword(t.slice(2)))) {
dropped.push(t)
continue
}
args.push(t)
}
return { args, dropped }
}
/** Would this raw extra-args string make ssh execute something? (Used to decide whether a value of
* unknown provenance may enter the machine-local store — see `localNodeExec`.) */
export function sshExtraArgsEnableLocalExec(extraArgs: string | undefined): boolean {
return stripLocalExecArgs(parseExtraArgs(extraArgs)).dropped.length > 0
}
/** A saved server in the app's SSH store. `label` is required for display. */
export interface SshServer extends SshConnection {
id: string
label: string
/** Where browsing this machine STARTS: the folder the "New remote" project dialog opens at, and
* the folder Test connection dials. It is a starting point, not an inherited default — a node's
* cwd comes from the project or node it was created in, never from here. Absent means `~`. */
remoteCwd?: string
}
/**
* Stable live-connection scope for an SSH host ATTACHED to a canvas project — i.e. a remote node
* living in a project that is not itself that endpoint's SSH project.
*
* Scoped by project AND endpoint, so two projects attaching the same host get their own
* ControlMaster (and their own reconnect loop), and one project attaching two hosts gets two. The
* endpoint is FNV-1a hashed rather than embedded: this id reaches the filesystem as part of the
* ControlMaster socket path, where a raw `user@host:port` would both leak the inventory and blow
* the sun_path length budget on a long hostname.
*/
export function sshAttachmentId(projectId: string, conn: SshConnection): string {
const input = `${conn.user}\0${conn.host}\0${conn.port ?? 22}`
let hash = 2166136261
for (let i = 0; i < input.length; i++) {
hash ^= input.charCodeAt(i)
hash = Math.imul(hash, 16777619)
}
return `attached-${projectId}-${(hash >>> 0).toString(16).padStart(8, '0')}`
}
/**
* Connection scope used by a remote node inside a project.
*
* An SSH PROJECT owns its ControlMaster under the project id — that is the whole of today's
* model, and this returns exactly that whenever the project's own binding already reaches the
* node's machine. A remote node embedded in a LOCAL project (or in an SSH project bound to a
* DIFFERENT machine) owns a host attachment instead, under the stable project × endpoint id.
*
* Every consumer of that connection — spawn (`resolveSshRemote`), reconnect (`SshReconnector`),
* upload — must make the same choice, or a node resolves a master that was opened for someone
* else. Hence one function rather than the rule written out at each site.
*
* ## Why the project's binding wins on a HOST match, user and port included
*
* A node's `ssh` is a SNAPSHOT persisted into the canvas, and an SSH project's canvas lives in
* `<remoteCwd>/.nodeterm/project.json` ON THE HOST — shared with everyone who opens that folder.
* So the `user` (and port) on a node is whoever created it, not whoever is reading it: alice's
* nodes say `alice@box`, and when bob opens the same project as `bob@box` every one of them would
* ask for a second master dialing `alice@box` — which fails for bob, or worse sits on an askpass
* prompt. The project's binding is the authority on how THIS user reaches that machine, so a node
* naming the same host is served by it.
*
* The cost is a deliberate one: inside an SSH project you cannot pin a node to a second ACCOUNT on
* the same host. A different machine still gets its own attachment, which is the case this is for.
*/
export function sshConnectionIdForProject(
projectId: string,
conn: SshConnection,
projectServer?: SshConnection
): string {
// `conn.host` is checked explicitly: a node whose binding lost its host (bad persisted data)
// must not match a LOCAL project's absent one through `undefined === undefined` and get served
// from a master that was never opened for it. Unroutable either way — but failing as an
// attachment ends at `requireRemote` refusing the spawn, which is the safe direction.
return conn.host && projectServer?.host === conn.host
? projectId
: sshAttachmentId(projectId, conn)
}
/**
* Whether a terminal node's `SSH user@host` header chip would only repeat its project: inside an
* SSH project every terminal on that host carries one, so the chip said the same thing on every
* node and told the user nothing the tab did not. It stays wherever it is information — a node on
* a different host (a host attachment), any SSH node in a LOCAL project, and a plain `ssh` node
* dialing another user on the project's host.
*
* The host test is `sshConnectionIdForProject`'s, so the chip disappears exactly for the nodes the
* project's own master serves. A remote-tmux node naming another user is one of them: it runs as
* the PROJECT's user, so its chip was not just redundant but wrong. A plain `ssh` node
* (`sshRemoteTmux` false) runs its own `ssh user@host` and does log in as its own user — for it
* the user must match too.
*/
export function sshChipRepeatsProject(
conn: Pick<SshConnection, 'host' | 'user'>,
sshRemoteTmux: boolean,
projectServer?: Pick<SshConnection, 'host' | 'user'>
): boolean {
if (!conn.host || projectServer?.host !== conn.host) return false
return sshRemoteTmux || conn.user === projectServer.user
}
/**
* Split a raw extra-args string into argv tokens, honoring single and double quotes.
* Unquoted whitespace separates tokens; quotes group; quote chars are stripped.
*/
export function parseExtraArgs(s: string | undefined): string[] {
if (!s || !s.trim()) return []
const tokens: string[] = []
let cur = ''
let quote: '"' | "'" | null = null
let has = false
for (const ch of s) {
if (quote) {
if (ch === quote) quote = null
else cur += ch
} else if (ch === '"' || ch === "'") {
quote = ch
has = true
} else if (/\s/.test(ch)) {
if (has) tokens.push(cur)
cur = ''
has = false
} else {
cur += ch
has = true
}
}
if (has) tokens.push(cur)
return tokens
}
/**
* Stable identity key for the host a connection targets, used to scope managed Claude accounts to
* an SSH project (`ClaudeAccount.host`). `${user}@${host}` — the same target string ssh itself
* builds. Port and identity file are intentionally excluded: a remote account is defined by which
* remote `$HOME` (i.e. which user on which host) its config dir lives under, and two projects that
* reach the same account over different ports still share that one remote dir.
*/
export function sshHostKey(conn: Pick<SshConnection, 'host' | 'user'>): string {
return `${conn.user}@${conn.host}`
}
/**
* Build the `ssh` argv: `-p <port> [-i <id>] [...extra] user@host`.
*
* `extraArgs` is spliced in verbatim ONLY when the connection is `execTrusted` — i.e. the value
* came from this machine (the user's SSH server store, or the machine-local workspace index). Any
* other value contributes NOTHING: a `.nodeterm/project.json` from a cloned repo, or a canvas-sync
* peer's node, must never be able to add ssh flags at all. The connection is still attempted —
* degrade, never block.
*/
export function buildSshArgs(conn: SshConnection): string[] {
const args = ['-p', String(conn.port ?? 22)]
if (conn.identityFile) args.push('-i', conn.identityFile)
const extra = parseExtraArgs(conn.extraArgs)
if (conn.execTrusted) {
args.push(...extra)
}
// else: an UNTRUSTED extraArgs contributes no tokens. `stripLocalExecArgs` removes the
// exec-enabling OPTIONS, but the survivors are still not safe to splice: a bare token
// (`evilhost`) has no exec option so it passes the strip with dropped=[], and ssh reads the
// first positional argument as the DESTINATION — silently retargeting the connection. Flags like
// `-A` (agent forwarding) or `-J` (jump host) from a document are unwanted too. An untrusted
// source has no legitimate need to add ssh args (this branch isn't even reached today —
// untrusted extraArgs is stripped upstream), so the empty list is the only safe degrade; there
// is no residue to reason about token by token.
args.push(`${conn.user}@${conn.host}`)
return args
}
/** Single-quote a string for use as ONE POSIX shell token (safe inside a remote command). */
export function posixQuote(s: string): string {
return `'${s.replace(/'/g, `'\\''`)}'`
}
/**
* Quote a remote path as one shell token, but leave a leading `~` / `~/` UNQUOTED so the remote
* shell tilde-expands it (single quotes suppress `~` expansion). The remainder stays quoted, so a
* directory name can never inject shell. `~` alone → `~`; `~/a b` → `~/'a b'`; `/srv/x` → `'/srv/x'`.
*/
export function quoteRemotePath(p: string): string {
if (p === '~') return '~'
if (p.startsWith('~/')) return p.length > 2 ? `~/${posixQuote(p.slice(2))}` : '~/'
return posixQuote(p)
}
/**
* Directories where tmux commonly lives but that an ssh EXEC channel's PATH misses. An exec
* channel gets a non-login, non-interactive shell — the same trap the remote claude probe hit
* (`core/remote-ssh/claude-version-probe.ts`): on a macOS host Homebrew's `shellenv` lives in
* `~/.zprofile`, which only LOGIN shells source, so `tmux` resolves fine in the user's own
* terminal and every remote command of ours died with `zsh:1: command not found: tmux`
* (issue #449). Known absolute locations beat inherited-PATH luck — `findTmux()`'s rule, applied
* to the machine we cannot install anything on.
*
* - `/opt/homebrew/bin` — Homebrew on Apple Silicon (the issue's report).
* - `/usr/local/bin` — Homebrew on Intel macs; classic hand-installs on Linux/BSD.
* - `/opt/local/bin` — MacPorts.
* - `$HOME/.local/bin` — per-user installs (expanded by the REMOTE shell; the prologue keeps it
* inside double quotes).
*/
export const REMOTE_TMUX_PATH_DIRS = '/opt/homebrew/bin:/usr/local/bin:/opt/local/bin:$HOME/.local/bin'
/**
* Shell prologue (note the trailing `; `) prepended to every remote command that invokes `tmux`.
* APPENDED to PATH, never prepended: a host whose exec-channel PATH already resolves tmux keeps
* using exactly that binary — the same "system first" rule as the local `findTmux()`, and the only
* ordering that cannot re-pair a long-lived tmux server with a different client build. The `$PATH`
* / `$HOME` references expand on the REMOTE side (the whole line travels as one ssh argument).
*/
export function remoteTmuxPathPrologue(): string {
return `PATH="$PATH:${REMOTE_TMUX_PATH_DIRS}"; `
}
/** Remote variant of pty-manager's tmuxConf — same behavior, same reasoning (see `tmuxConf` for
* the long version). Mouse ON: tmux owns scrolling and selection, the pane is on the alternate
* screen, and NOTHING is hydrated on reattach (tmux redraws and its own history is scrollable).
* Copy goes out as OSC 52, which the client's handler writes to the LOCAL clipboard — this is the
* only thing that ever made copying work over SSH. It needs `terminal-features ",*:clipboard"`:
* the `terminal-overrides ',xterm*:Ms=...'` entry this config used to carry emits NOTHING on
* tmux 3.2+ (measured), so it is gone — do not add it back. */
// LEAD-PANE WIDTH (issue #119): same opt-in as the local conf — an agent team spawned on the SSH
// host squeezes the lead pane exactly like a local one, so the setting emits into both configs
// through the ONE shared builder (`leadPaneHookLines`). 0/omitted ⇒ '' ⇒ byte-identical output.
export function remoteTmuxConf(scrollback: number, leadPaneWidth: number = 0): string {
return `# auto-generated by node-terminal (remote) — do not edit
set -g status off
set -g mouse on
set -g history-limit ${Math.max(1000, scrollback)}
set -g default-terminal "xterm-256color"
set -sg escape-time 10
set -g destroy-unattached off
setw -g aggressive-resize on
# Credentials travel HERE, not on argv: over SSH the gateway/custom env is sourced from a 0600
# file into the remote tmux client's environment, and update-environment copies the listed names
# into the session at create/attach. The old '-e KEY=VALUE' route parked the values on the LOCAL
# ssh client's command line for the whole session (and on the remote process table at creation).
${tmuxUpdateEnvironmentLine()}
# OSC 52 to the client, which writes the LOCAL clipboard. BOTH lines are needed on tmux 3.2+ — see
# remoteTmuxConf's doc comment before touching either.
# MIGRATION — do not remove. Older versions of this file blanked smcup/rmcup/indn via
# terminal-overrides, and a long-lived tmux server keeps every entry ever sourced into it (the
# array only grows; -f is read once at server start). With those stale entries present the client
# never returns to the alternate screen and scrolling stays broken NO MATTER what this file sets
# below. Unset both arrays back to defaults, then re-add the one feature we actually want.
set -su terminal-overrides
set -su terminal-features
set -g set-clipboard on
set -as terminal-features ",*:clipboard"
# Truecolor passthrough: tmux clamps 24-bit SGR to the 256 palette unless the OUTER terminal is
# known to speak RGB. The attached client is our xterm.js renderer, which does — declare it via
# terminal-features like the clipboard entry, never terminal-overrides (see MIGRATION). Issue #78.
set -as terminal-features ",*:RGB"
# OSC 8 hyperlink passthrough — tmux strips the escape unless the outer terminal declares it.
set -as terminal-features ",*:hyperlinks"
# And advertise it to the programs INSIDE the panes: half the ecosystem checks COLORTERM before
# emitting 24-bit SGR. Global env, copied into each session at creation — this conf is written and
# source-filed at connect (warm server) and rides -f on cold start, so it lands before sessions do.
# The local path passes COLORTERM per session via tmux -e instead (the PATH/LANG precedent).
set-environment -g COLORTERM truecolor
# Mouse copy: tmux copies to its buffer AND emits OSC 52. No pipe to a local command — it would run
# on the REMOTE host, which is nobody's clipboard.
bind -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel
bind -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel
bind -T copy-mode DoubleClick1Pane send-keys -X select-word \\; send-keys -X copy-pipe-and-cancel
bind -T copy-mode-vi DoubleClick1Pane send-keys -X select-word \\; send-keys -X copy-pipe-and-cancel
bind -T copy-mode TripleClick1Pane send-keys -X select-line \\; send-keys -X copy-pipe-and-cancel
bind -T copy-mode-vi TripleClick1Pane send-keys -X select-line \\; send-keys -X copy-pipe-and-cancel
${leadPaneHookLines(leadPaneWidth)}`
}
/** Build the remote shell command that attaches-or-creates this node's remote tmux session. */
export function remoteTmuxCommand(opts: {
sessionId: string
remoteCwd: string
program?: string
programArgs?: string[]
socket?: string
/** When set, sources this remote conf via `-f` (spliced before `new-session`). */
confPath?: string
}): string {
// Default = the host's own nodeterm socket (`TMUX_SOCKET` in core/tmux-naming, pinned equal by
// core/remote-ssh/unified-socket.test.ts — shared/ must not import core/). An SSH project and a
// nodeterm running ON the host attach the same `nt-<id>` sessions only because this is one name.
const socket = opts.socket ?? 'node-terminal'
const parts = [
'tmux',
'-L',
socket,
...(opts.confPath ? ['-f', posixQuote(opts.confPath)] : []),
'new-session',
'-A',
'-s',
posixQuote(opts.sessionId),
'-c',
quoteRemotePath(opts.remoteCwd)
]
if (opts.program) {
parts.push(posixQuote(opts.program))
for (const a of opts.programArgs ?? []) parts.push(posixQuote(a))
}
return parts.join(' ')
}
/** Parse `ls -1Ap <dir>` output into sorted directory names (trailing `/`), excluding . and .. */
export function parseLsDirs(stdout: string): string[] {
return stdout
.split('\n')
.map((l) => l.trim())
.filter((l) => l.endsWith('/') && l !== './' && l !== '../')
.map((l) => l.slice(0, -1))
.sort((a, b) => a.localeCompare(b))
}
/** A host parsed from `~/.ssh/config`, ready to seed a saved server (no id yet). */
export interface ParsedSshHost {
/** The `Host` alias (display label). */
label: string
/** `HostName` if set, else the alias. */
host: string
user?: string
port?: number
identityFile?: string
}
/**
* Parse `~/.ssh/config` text into named hosts. Each non-wildcard `Host` alias becomes one
* entry, taking the block's `HostName`/`User`/`Port`/`IdentityFile`. Wildcard aliases
* (containing `*` or `?`) and the bare `Host *` catch-all are skipped — they aren't concrete
* servers. Keys are case-insensitive; `key=value` and `key value` forms are both accepted.
*/
export function parseSshConfig(text: string): ParsedSshHost[] {
const hosts: ParsedSshHost[] = []
// Aliases sharing one `Host` line all receive the block's settings.
let current: { aliases: string[]; settings: Record<string, string> } | null = null
const flush = () => {
if (!current) return
for (const alias of current.aliases) {
if (alias.includes('*') || alias.includes('?')) continue
const s = current.settings
const port = s.port ? Number(s.port) : undefined
hosts.push({
label: alias,
host: s.hostname || alias,
user: s.user || undefined,
port: Number.isFinite(port) ? port : undefined,
identityFile: s.identityfile || undefined
})
}
current = null
}
for (const raw of text.split('\n')) {
const line = raw.replace(/#.*$/, '').trim()
if (!line) continue
const eq = line.indexOf('=')
const sp = line.search(/\s/)
let key: string
let value: string
if (eq !== -1 && (sp === -1 || eq < sp)) {
key = line.slice(0, eq).trim()
value = line.slice(eq + 1).trim()
} else if (sp !== -1) {
key = line.slice(0, sp).trim()
value = line.slice(sp + 1).trim()
} else {
key = line
value = ''
}
const lkey = key.toLowerCase()
if (lkey === 'host') {
flush()
current = { aliases: value.split(/\s+/).filter(Boolean), settings: {} }
} else if (current) {
current.settings[lkey] = value
}
}
flush()
return hosts
}