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
// The seam between "an ssh/scp argv this app built" and the in-process transport. Every runner
// that used to hand an argv to the ssh binary can hand it here instead and get the answer in the
// shape it already handles: `-O` ops answer like OpenSSH's control client, a command answers like
// execFile, a master looks like the spawned master process the manager watches.
//
// WHEN it is used is one decision, `useNativeSsh()`: always on Windows (where OpenSSH cannot
// multiplex — see native-mux.ts), and on POSIX only when NODETERM_NATIVE_SSH=1 asks for it, which
// exists so the transport can be exercised end to end against a real host from a Mac or Linux
// desktop. It is read at call time, never cached, so a test can flip it.
import { EventEmitter } from 'events'
import { PassThrough } from 'stream'
import fs from 'fs'
import path from 'path'
import type { SFTPWrapper } from 'ssh2'
import { NativeMux, channelExit, noMasterMessage, type ExecResult } from './native-mux'
import { parseScpArgv, parseSshArgv, type ParsedSsh } from './ssh-argv'
import { localChildName, uniqueChildName } from '../../download-name'
export function useNativeSsh(
platform: NodeJS.Platform = process.platform,
env: NodeJS.ProcessEnv = process.env
): boolean {
if (env.NODETERM_NATIVE_SSH === '0') return false
return platform === 'win32' || env.NODETERM_NATIVE_SSH === '1'
}
/**
* Run any non-master ssh argv: `-O check|exit|forward|cancel` or a command. Never throws; an
* argv the parser refuses is exit 255 with the reason on stderr, so a new flag in a builder shows
* up as a named failure rather than as a command run with a different meaning.
*/
export async function runSshArgv(
mux: NativeMux,
argv: string[],
io: { stdin?: string | Buffer; timeoutMs?: number } = {}
): Promise<ExecResult> {
let p: ParsedSsh
try {
p = parseSshArgv(argv)
} catch (e) {
return result(255, '', `${(e as Error).message}\n`)
}
if (p.kind === 'master') {
return result(255, '', 'native ssh transport: a master is started with startNativeMaster, not run\n')
}
if (p.kind === 'exec') return mux.exec(p, io)
const cp = p.options.controlPath
if (!cp) return result(255, '', 'native ssh transport: -O without a ControlPath\n')
switch (p.op) {
case 'check':
return mux.check(cp) ? result(0, '', 'Master running (pid=0)\n') : result(255, '', `${noMasterMessage(cp)}\n`)
case 'exit':
return (await mux.exit(cp)) ? result(0, '', 'Exit request sent.\n') : result(255, '', `${noMasterMessage(cp)}\n`)
case 'forward':
try {
if (p.forward.kind === 'local') await mux.forwardLocal(cp, p.forward)
else await mux.forward(cp, p.forward)
return result(0, '', '')
} catch (e) {
return result(255, '', `${(e as Error).message}\n`)
}
case 'cancel':
if (p.forward.kind === 'local') await mux.cancelLocal(cp, p.forward)
else await mux.cancel(cp, p.forward)
return result(0, '', '')
}
}
/** What SshProjectManager watches for a spawned master process (Runners.spawnMaster). */
export interface NativeMasterHandle {
kill(): void
on(event: string, cb: (...a: unknown[]) => void): void
stderr(): string
exited(): boolean
pid(): number | undefined
}
/**
* `ssh -M -N …` as a pseudo-process: "exits" when the connection fails to come up or later drops,
* with the reason on stderr (the manager reads its last line as the user-facing error, exactly as
* it reads a real master's). `-O check` answers true from the moment it is authenticated.
*/
export function startNativeMaster(mux: NativeMux, argv: string[]): NativeMasterHandle {
const events = new EventEmitter()
let stderr = ''
let exited = false
const finish = (code: number | null, why: string): void => {
if (exited) return
exited = true
if (why) stderr += why.endsWith('\n') ? why : `${why}\n`
events.emit('exit', code)
}
let controlPath: string | undefined
try {
const p = parseSshArgv(argv)
if (p.kind !== 'master' || !p.options.controlPath) throw new Error('native ssh transport: not a master argv')
controlPath = p.options.controlPath
mux.master(controlPath, p.target, p.options).then(
({ closed }) => void closed.then((why) => finish(255, why)),
(e: Error) => finish(255, e.message)
)
} catch (e) {
// Report on the next tick, as a failed spawn does, so the caller's listeners are attached.
queueMicrotask(() => finish(255, (e as Error).message))
}
return {
kill: () => {
if (controlPath) void mux.exit(controlPath)
},
on: (ev, cb) => {
if (ev === 'exit') events.on('exit', cb)
},
stderr: () => stderr,
exited: () => exited,
// No OS process. The manager only uses the pid to correlate askpass prompts, which the native
// transport raises itself.
pid: () => undefined
}
}
/**
* The scp argv scpArgs / scpDownArgs build, over SFTP on the shared connection. Files and (for a
* download) directory trees; a recursive UPLOAD is not something any builder produces.
*/
export async function runScpArgv(
mux: NativeMux,
argv: string[],
platform: NodeJS.Platform = process.platform
): Promise<{ code: number; stderr: string; renamed?: number }> {
let p: ReturnType<typeof parseScpArgv>
try {
p = parseScpArgv(argv)
} catch (e) {
return { code: 1, stderr: (e as Error).message }
}
const cp = p.options.controlPath
try {
const sftp = await mux.sftp(cp, p.target, p.options)
try {
const remote = await realRemotePath(sftp, p.remotePath)
const renamed = { count: 0 }
if (p.direction === 'up') {
if (p.recursive) throw new Error('scp: recursive upload is not supported')
await promisify<void>((cb) => sftp.fastPut(p.localPath, remote, cb))
} else {
await download(sftp, remote, p.localPath, p.recursive, platform, renamed)
}
return renamed.count ? { code: 0, stderr: '', renamed: renamed.count } : { code: 0, stderr: '' }
} finally {
sftp.end()
}
} catch (e) {
return { code: 1, stderr: (e as Error).message }
}
}
/** scp's remote path semantics: relative to the login directory (remoteScpPath already turned `~/x` into `x`). */
async function realRemotePath(sftp: SFTPWrapper, p: string): Promise<string> {
if (p.startsWith('/')) return p
const home = await promisify<string>((cb) => sftp.realpath('.', cb))
return p === '' || p === '.' ? home : `${home.replace(/\/$/, '')}/${p}`
}
/**
* One remote file, or a directory tree. Each CHILD name is made valid for this machine and unique
* within its directory (download-name.ts) — the top-level name is the caller's — and every name
* that had to change is counted in `renamed`.
*/
export async function download(
sftp: Pick<SFTPWrapper, 'stat' | 'readdir' | 'fastGet'>,
remote: string,
local: string,
recursive: boolean,
platform: NodeJS.Platform = process.platform,
renamed: { count: number } = { count: 0 }
): Promise<void> {
const st = await promisify<{ isDirectory(): boolean }>((cb) => sftp.stat(remote, cb))
if (!st.isDirectory()) {
await promisify<void>((cb) => sftp.fastGet(remote, local, cb))
return
}
if (!recursive) throw new Error(`scp: ${remote}: not a regular file`)
fs.mkdirSync(local, { recursive: true })
const entries = await promisify<{ filename: string }[]>((cb) => sftp.readdir(remote, cb))
const taken = new Set<string>()
for (const e of entries) {
const safe = localChildName(e.filename, platform)
if (safe === null) continue
const name = uniqueChildName(safe, taken, platform)
if (name !== e.filename) renamed.count++
await download(sftp, `${remote}/${e.filename}`, path.join(local, name), true, platform, renamed)
}
}
function promisify<T>(fn: (cb: (err: Error | null | undefined, v: T) => void) => void): Promise<T> {
return new Promise((resolve, reject) => fn((err, v) => (err ? reject(err) : resolve(v))))
}
function result(code: number, stdout: string, stderr: string): ExecResult {
return { code, signal: null, stdout: Buffer.from(stdout), stderr: Buffer.from(stderr), timedOut: false }
}
/** What a streaming caller uses of a ChildProcess (the setup runner): pipes, `close`, `error`, kill. */
export interface NativeStreamChild extends EventEmitter {
stdout: PassThrough
stderr: PassThrough
kill(signal?: string): boolean
}
/**
* `spawn(ssh, argv, {stdio: ['ignore','pipe','pipe']})` over the native transport. Emits `close`
* with the remote exit status (255 when the channel is cut off or cannot be opened, ssh's code);
* `kill` closes the channel — the same thing killing the local mux client did.
*/
export function spawnSshArgvStream(mux: NativeMux, argv: string[]): NativeStreamChild {
const child = new EventEmitter() as NativeStreamChild
child.stdout = new PassThrough()
child.stderr = new PassThrough()
let closeChannel: (() => void) | null = null
let killed = false
let done = false
const finish = (code: number): void => {
if (done) return
done = true
child.stdout.end()
child.stderr.end()
child.emit('close', code)
}
child.kill = () => {
killed = true
// Asynchronously, as a real child reports its exit: a caller may attach 'close' after kill().
if (closeChannel) closeChannel()
else queueMicrotask(() => finish(255))
return true
}
let p: ParsedSsh
try {
p = parseSshArgv(argv)
if (p.kind !== 'exec') throw new Error('native ssh transport: not a command argv')
} catch (e) {
queueMicrotask(() => {
if (done) return
child.stderr.write(`${(e as Error).message}\n`)
finish(255)
})
return child
}
mux.channel(p).then(
(ch) => {
if (killed) {
ch.close()
return
}
closeChannel = () => ch.close()
ch.pipe(child.stdout, { end: false })
ch.stderr.pipe(child.stderr, { end: false })
ch.on('close', () => finish(channelExit(ch).code ?? 255))
if (channelExit(ch).closed) queueMicrotask(() => finish(channelExit(ch).code ?? 255))
ch.on('error', () => {})
ch.end()
},
(e: Error) => {
// Killed before the open failed: the child already closed and its pipes are ended. A write
// here would throw ERR_STREAM_WRITE_AFTER_END as an uncaught exception in main.
if (done) return
child.stderr.write(`${e.message}\n`)
finish(255)
}
)
return child
}