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 native transport against a REAL SSH protocol peer: ssh2's own Server, in-process, on
// loopback. No sshd, no Docker, so it runs identically on the macOS, Linux and windows-latest CI
// legs — which is the point: this transport exists for Windows.
import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest'
import fs from 'fs'
import os from 'os'
import path from 'path'
import { AddressInfo } from 'net'
import { Client, Server, utils, type Connection, type ConnectConfig } from 'ssh2'
import { NativeMux, noMasterMessage } from './native-mux'
import { parseSshArgv } from './ssh-argv'
import { childArgs, masterRoundTripArgs, remoteTmuxPtyArgs } from '../control-master'
import type { ResolvedHost } from './ssh-config'
import type { SshConnection } from '../../../shared/ssh'
import { ed25519KeyPair } from './test-keys'
const hostKey = ed25519KeyPair()
const otherHostKey = ed25519KeyPair()
const clientKey = ed25519KeyPair()
const lockedKey = ed25519KeyPair({ passphrase: 'open sesame', cipher: 'aes256-cbc', rounds: 4 })
let dir: string
let server: Server
let port: number
let connections = 0
let live: Connection[] = []
let serverHostKey = hostKey.private
/** Per session: the requests seen before its exec ('auth-agent', 'pty'), with the command. */
let sessions: { requests: string[]; cmd: string }[] = []
/** Whether the server grants agent forwarding (AllowAgentForwarding). */
let allowAgentFwd = true
function pubMatches(offered: { algo: string; data: Buffer }, pub: string): boolean {
const k = utils.parseKey(pub)
const one = Array.isArray(k) ? k[0] : k
return !(one instanceof Error) && offered.algo === one.type && offered.data.equals(one.getPublicSSH())
}
function startServer(): Promise<void> {
server = new Server({ hostKeys: [serverHostKey] }, (client) => {
connections++
live.push(client)
client.on('authentication', (ctx) => {
if (ctx.method !== 'publickey') return ctx.reject(['publickey'])
const ok = pubMatches(ctx.key, clientKey.public) || pubMatches(ctx.key, lockedKey.public)
if (!ok) return ctx.reject(['publickey'])
if (!ctx.signature) return ctx.accept() // key-ok probe
ctx.accept()
})
client.on('ready', () => {
client.on('session', (accept) => {
const session = accept()
const requests: string[] = []
let ptyInfo: { cols: number; rows: number } | undefined
session.on('auth-agent', (acceptFwd, rejectFwd) => {
requests.push('auth-agent')
if (allowAgentFwd) acceptFwd?.()
else rejectFwd?.()
})
session.on('pty', (acceptPty, _reject, info) => {
requests.push('pty')
ptyInfo = { cols: info.cols, rows: info.rows }
acceptPty?.()
})
session.on('exec', (acceptExec, _reject, info) => {
const ch = acceptExec()
const cmd = info.command
sessions.push({ requests: [...requests], cmd })
if (cmd === 'cat') {
const chunks: Buffer[] = []
ch.on('data', (d: Buffer) => chunks.push(d))
ch.on('end', () => {
ch.write(Buffer.concat(chunks))
ch.exit(0)
ch.end()
})
return
}
if (cmd === 'hang') return // never answers
if (cmd.startsWith('fail ')) {
ch.stderr.write('boom\n')
ch.exit(Number(cmd.slice(5)))
return ch.end()
}
if (ptyInfo) ch.write(`pty ${ptyInfo.cols}x${ptyInfo.rows}\r\n`)
ch.write(`ran: ${cmd}\n`)
ch.exit(0)
ch.end()
})
})
})
client.on('error', () => {})
})
return new Promise((r) =>
server.listen(0, '127.0.0.1', () => {
port = (server.address() as AddressInfo).port
r()
})
)
}
function host(): ResolvedHost {
return {
hostname: '127.0.0.1',
port,
user: 'dev',
identityFiles: [path.join(dir, 'id')],
identitiesOnly: true,
userKnownHostsFiles: [path.join(dir, 'known_hosts')],
globalKnownHostsFiles: [],
strictHostKeyChecking: 'ask'
}
}
function mux(extra: Partial<ConstructorParameters<typeof NativeMux>[0]> = {}): NativeMux {
return new NativeMux({ resolveHost: async () => host(), defaultAgent: () => undefined, ...extra })
}
const conn = (): SshConnection => ({ user: 'dev', host: '127.0.0.1', port, identityFile: path.join(dir, 'id') })
const CP = (): string => path.join(dir, 'cm.sock')
const exec = (cmd: string) => {
const p = parseSshArgv(childArgs(conn(), CP(), cmd))
if (p.kind !== 'exec') throw new Error('not exec')
return p
}
beforeAll(async () => {
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-native-'))
fs.writeFileSync(path.join(dir, 'id'), clientKey.private)
await startServer()
})
afterAll(() => {
server.close()
fs.rmSync(dir, { recursive: true, force: true })
})
const muxes: NativeMux[] = []
afterEach(() => {
for (const m of muxes.splice(0)) m.exitAll()
for (const c of live.splice(0)) c.end()
sessions = []
allowAgentFwd = true
})
const track = (m: NativeMux): NativeMux => (muxes.push(m), m)
describe('NativeMux over a real SSH protocol peer', () => {
it('shares ONE connection across many commands (ControlMaster=auto)', async () => {
const m = track(mux())
const before = connections
const results = await Promise.all([1, 2, 3, 4, 5].map((i) => m.exec(exec(`echo ${i}`))))
expect(results.map((r) => r.stdout.toString())).toEqual([1, 2, 3, 4, 5].map((i) => `ran: echo ${i}\n`))
expect(results.every((r) => r.code === 0)).toBe(true)
expect(connections - before).toBe(1)
expect(m.check(CP())).toBe(true)
})
it('pipes stdin, and reports exit code and stderr', async () => {
const m = track(mux())
const r = await m.exec(exec('cat'), { stdin: 'hello\nworld' })
expect(r.stdout.toString()).toBe('hello\nworld')
const f = await m.exec(exec('fail 3'))
expect(f.code).toBe(3)
expect(f.stderr.toString()).toBe('boom\n')
})
it('-O exit closes it; ControlMaster=no then never re-creates the shared one', async () => {
const m = track(mux())
await m.exec(exec('echo up'))
expect(await m.exit(CP())).toBe(true)
expect(m.check(CP())).toBe(false)
const rt = parseSshArgv(masterRoundTripArgs(conn(), CP()))
if (rt.kind !== 'exec') throw new Error()
const r = await m.exec(rt)
// One-off connection, like OpenSSH's direct fallback — and still no shared master afterwards.
expect(r.code).toBe(0)
expect(m.check(CP())).toBe(false)
})
it('times a command out like execFile, and a dropped connection ends channels with 255', async () => {
const m = track(mux())
const t = await m.exec(exec('hang'), { timeoutMs: 300 })
expect(t.timedOut).toBe(true)
const pending = m.exec(exec('hang'))
await new Promise((r) => setTimeout(r, 100))
for (const c of live) c.end()
const d = await pending
expect(d.code).toBe(255)
expect(m.check(CP())).toBe(false)
})
it('opens a pty channel with the requested size', async () => {
const m = track(mux())
const p = parseSshArgv(remoteTmuxPtyArgs(conn(), CP(), 'nt-x', '~'))
if (p.kind !== 'exec') throw new Error()
const ch = await m.shell(p, { cols: 132, rows: 43 })
const out = await new Promise<string>((resolve) => {
let s = ''
ch.on('data', (d: Buffer) => (s += d.toString()))
ch.on('close', () => resolve(s))
})
expect(out).toContain('pty 132x43')
})
it('records a first-seen host key, then refuses a CHANGED one', async () => {
const m = track(mux())
await m.exec(exec('echo a'))
expect(fs.readFileSync(path.join(dir, 'known_hosts'), 'utf8')).toContain(`[127.0.0.1]:${port} ssh-ed25519`)
m.exitAll()
server.close()
serverHostKey = otherHostKey.private
await startServer() // new port → rewrite the known_hosts entry under the new port name
const kh = path.join(dir, 'known_hosts')
const text = fs.readFileSync(kh, 'utf8').replace(/\[127\.0\.0\.1\]:\d+/, `[127.0.0.1]:${port}`)
fs.writeFileSync(kh, text)
const r = await track(mux()).exec(exec('echo b'))
expect(r.code).toBe(255)
expect(r.stderr.toString()).toMatch(/REMOTE HOST IDENTIFICATION HAS CHANGED/)
})
it('asks for a passphrase for an encrypted key — but never in BatchMode', async () => {
fs.rmSync(path.join(dir, 'known_hosts'), { force: true })
fs.writeFileSync(path.join(dir, 'id'), lockedKey.private)
try {
const asked: string[] = []
const m = track(
mux({
askPassphrase: async (f) => {
asked.push(f)
return asked.length === 1 ? 'wrong' : 'open sesame'
}
})
)
const r = await m.exec(exec('echo locked'))
expect(r.stdout.toString()).toBe('ran: echo locked\n')
expect(asked).toHaveLength(2)
const batch = track(mux({ askPassphrase: async () => 'open sesame' }))
const rt = parseSshArgv(masterRoundTripArgs(conn(), path.join(dir, 'other.sock')))
if (rt.kind !== 'exec') throw new Error()
const b = await batch.exec(rt)
expect(b.code).toBe(255)
expect(b.stderr.toString()).toMatch(/Permission denied/)
} finally {
fs.writeFileSync(path.join(dir, 'id'), clientKey.private)
}
})
it('offers a freshly unlocked key to the agent AFTER it authenticated — once, fail-open', async () => {
fs.rmSync(path.join(dir, 'known_hosts'), { force: true })
fs.writeFileSync(path.join(dir, 'id'), lockedKey.private)
try {
const asked: { agentPath: string; identityFile: string }[] = []
const added: { agentPath: string; type: string; comment: string; lifetimeSec?: number }[] = []
// IdentitiesOnly with no id.pub: the agent step is skipped (nothing to filter to), so the
// key file is what authenticates — the case the add exists for.
const m = track(
mux({
defaultAgent: () => '/fake/agent.sock',
askPassphrase: async () => 'open sesame',
agentAdd: (req) => {
asked.push({ agentPath: req.agentPath, identityFile: req.identityFile })
return { lifetimeSec: 600 }
},
addKeyToAgent: async (agentPath, key, comment, opts) => {
added.push({ agentPath, type: key.type, comment, lifetimeSec: opts?.lifetimeSec })
return 'added'
}
})
)
expect((await m.exec(exec('echo one'))).code).toBe(0)
expect((await m.exec(exec('echo two'))).code).toBe(0)
await new Promise((r) => setTimeout(r, 20))
expect(asked).toEqual([{ agentPath: '/fake/agent.sock', identityFile: path.join(dir, 'id') }])
expect(added).toEqual([{ agentPath: '/fake/agent.sock', type: 'ssh-ed25519', comment: path.join(dir, 'id'), lifetimeSec: 600 }])
// A policy that says no adds nothing; an agent that throws costs the connection nothing.
const noAdd = track(
mux({
defaultAgent: () => '/fake/agent.sock',
askPassphrase: async () => 'open sesame',
agentAdd: () => null,
addKeyToAgent: async () => {
throw new Error('must not be called')
}
})
)
expect((await noAdd.exec(exec('echo three'))).code).toBe(0)
const logs: string[] = []
const broken = track(
mux({
defaultAgent: () => '/fake/agent.sock',
askPassphrase: async () => 'open sesame',
log: (l) => logs.push(l),
agentAdd: () => {
throw new Error('policy exploded')
}
})
)
expect((await broken.exec(exec('echo four'))).code).toBe(0)
const failing = track(
mux({
defaultAgent: () => '/fake/agent.sock',
askPassphrase: async () => 'open sesame',
log: (l) => logs.push(l),
agentAdd: () => ({}),
addKeyToAgent: async () => {
throw new Error('agent exploded')
}
})
)
expect((await failing.exec(exec('echo five'))).code).toBe(0)
await new Promise((r) => setTimeout(r, 20))
expect(logs.some((l) => /could not add .* to the ssh agent \(error\)/.test(l))).toBe(true)
} finally {
fs.writeFileSync(path.join(dir, 'id'), clientKey.private)
}
})
it('never offers a key that needed no passphrase', async () => {
let consulted = 0
const m = track(
mux({
defaultAgent: () => '/fake/agent.sock',
agentAdd: () => {
consulted++
return {}
}
})
)
expect((await m.exec(exec('echo plain'))).code).toBe(0)
expect(consulted).toBe(0)
})
it('forward on a path with no connection fails the way ssh does', async () => {
const m = track(mux())
await expect(
m.forward(CP(), { remoteSocket: '/r.sock', localHost: '127.0.0.1', localPort: 1 })
).rejects.toThrow(noMasterMessage(CP()))
})
})
describe('ForwardAgent (target PTY channels only)', () => {
const pty = () => {
const p = parseSshArgv(remoteTmuxPtyArgs(conn(), CP(), 'nt-fwd', '~'))
if (p.kind !== 'exec') throw new Error()
return p
}
const drain = (ch: NodeJS.ReadableStream & NodeJS.EventEmitter): Promise<void> =>
new Promise((r) => {
ch.on('close', () => r())
ch.resume()
})
const fwdMux = (forwardAgent: string | undefined, extra: Partial<ConstructorParameters<typeof NativeMux>[0]> = {}) =>
track(
mux({
resolveHost: async () => ({ ...host(), forwardAgent }),
defaultAgent: () => '/fake/agent.sock',
...extra
})
)
it('`yes`: the pty channel asks for forwarding; background execs never do', async () => {
const m = fwdMux('yes')
expect((await m.exec(exec('echo bg'))).code).toBe(0)
await drain(await m.shell(pty(), { cols: 80, rows: 24 }))
expect((await m.exec(exec('echo bg2'))).code).toBe(0)
const bg = sessions.filter((x) => x.cmd.startsWith('echo'))
expect(bg.every((x) => !x.requests.includes('auth-agent'))).toBe(true)
const term = sessions.find((x) => x.cmd.includes('new-session'))
expect(term?.requests).toEqual(['auth-agent', 'pty'])
})
it('`no` / absent: nothing is requested', async () => {
for (const v of ['no', undefined]) {
const m = fwdMux(v)
await drain(await m.shell(pty(), { cols: 80, rows: 24 }))
m.exitAll()
}
expect(sessions.some((x) => x.requests.includes('auth-agent'))).toBe(false)
})
it('a server that refuses forwarding still gets its terminal, and is not asked again', async () => {
allowAgentFwd = false
const logs: string[] = []
const m = fwdMux('yes', { log: (l) => logs.push(l) })
const out = await new Promise<string>((resolve, reject) => {
m.shell(pty(), { cols: 80, rows: 24 }).then((ch) => {
let text = ''
ch.on('data', (d: Buffer) => (text += d.toString()))
ch.on('close', () => resolve(text))
}, reject)
})
expect(out).toContain('pty 80x24')
await drain(await m.shell(pty(), { cols: 80, rows: 24 }))
const terms = sessions.filter((x) => x.cmd.includes('new-session'))
expect(terms.map((x) => x.requests.includes('auth-agent'))).toEqual([false, false])
expect(logs.filter((l) => /refused agent forwarding/.test(l))).toHaveLength(1)
})
})
describe('agent selection on Windows (Pageant pipe)', () => {
const me = os.userInfo().username
const capture = (): { agents: unknown[]; restore(): void } => {
const agents: unknown[] = []
const real = Client.prototype.connect
Client.prototype.connect = function (this: Client, cfg: ConnectConfig) {
agents.push(cfg.agent)
return real.call(this, cfg)
}
return { agents, restore: () => void (Client.prototype.connect = real) }
}
it('`IdentityAgent pageant` is the discovered pipe — never the string ssh2 turns into pagent.exe', async () => {
const cap = capture()
try {
const m = track(
mux({
platform: 'win32',
listWindowsPipes: () => ['openssh-ssh-agent', `pageant.${me}.abc123`],
resolveHost: async () => ({ ...host(), identityAgent: 'pageant', forwardAgent: 'yes' })
})
)
expect((await m.exec(exec('echo pg'))).code).toBe(0)
expect(cap.agents).toEqual([`\\\\.\\pipe\\pageant.${me}.abc123`])
} finally {
cap.restore()
}
})
it('no Pageant pipe: no agent at all, and one warning saying why', async () => {
const cap = capture()
const logs: string[] = []
try {
const m = track(
mux({
platform: 'win32',
listWindowsPipes: () => ['openssh-ssh-agent'],
log: (l) => logs.push(l),
resolveHost: async () => ({ ...host(), identityAgent: 'PAGEANT', forwardAgent: 'yes' })
})
)
expect((await m.exec(exec('echo nopg'))).code).toBe(0)
expect(cap.agents).toEqual([undefined])
expect(logs.filter((l) => /IdentityAgent pageant: no Pageant pipe/.test(l))).toHaveLength(1)
} finally {
cap.restore()
}
})
it('POSIX keeps the value as written', async () => {
const cap = capture()
try {
const m = track(mux({ platform: 'linux', resolveHost: async () => ({ ...host(), identityAgent: '/tmp/a.sock', forwardAgent: 'yes' }) }))
expect((await m.exec(exec('echo posix'))).code).toBe(0)
expect(cap.agents).toEqual(['/tmp/a.sock'])
} finally {
cap.restore()
}
})
})
describe('unsupported ~/.ssh/config options', () => {
it('are named in ONE warning, and the connection still comes up', async () => {
const logs: string[] = []
const m = track(
mux({ log: (l) => logs.push(l), resolveHost: async () => ({ ...host(), unsupported: ['certificatefile', 'localforward'] }) })
)
expect((await m.exec(exec('echo a'))).code).toBe(0)
await m.exit(CP())
expect((await m.exec(exec('echo b'))).code).toBe(0)
expect(logs.filter((l) => /does not support are ignored: certificatefile, localforward/.test(l))).toHaveLength(1)
})
})