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
// `PtyManager.captureVisible` — the visible-screen capture: WHICH binary is asked with WHICH argv, and
// the failure contract. The argv's meaning (exact target, visible rows only, the cursor line from the
// same invocation) is proven against a real tmux in `capture-route.realtmux.test.ts` and
// through a real /bin/sh in `remote-ssh/capture-visible.realsh.test.ts`; this file pins dispatch.
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform } from './platform-fake'
import { TMUX_SOCKET, sessionName } from './tmux-naming'
import { RMT_TMUX_SOCKET } from './remote-ssh/control-master'
import { VISIBLE_CAPTURE_FORMAT, unavailableCapture } from './capture-route'
/** Every `runAsync` in pty-manager lands here. `answer` decides what each call resolves to. */
const calls: Array<{ file: string; args: string[] }> = []
const script = vi.hoisted(() => ({
answer: (() => ({ stdout: '' })) as (file: string, args: string[]) => { stdout: string }
}))
vi.mock('child_process', () => {
type Cb = (err: Error | null, res?: { stdout: string; stderr: string }) => void
const execFile = (file: string, args: string[], a?: unknown, b?: unknown): unknown => {
const cb = (typeof a === 'function' ? a : b) as Cb | undefined
calls.push({ file, args })
try {
cb?.(null, { ...script.answer(file, args), stderr: '' })
} catch (e) {
cb?.(e as Error)
}
return {}
}
return { execFile, execFileSync: (): string => '' }
})
const ssh = vi.hoisted(() => ({ path: '/usr/bin/ssh' as string | null }))
vi.mock('./exec-path', async (importOriginal) => ({
...(await importOriginal<typeof import('./exec-path')>()),
findExecutableSync: (bin: string) => (bin === 'ssh' ? ssh.path : null),
shellPathNow: () => '/usr/bin:/bin',
resolveShellPath: async () => '/usr/bin:/bin'
}))
vi.mock('node-pty', () => ({
spawn: () => ({
onData: () => {},
onExit: () => {},
write: () => {},
resize: () => {},
pause: () => {},
resume: () => {},
kill: () => {},
pid: 4321
})
}))
const hostCapture = vi.hoisted(() => vi.fn(async () => 'HISTORY LINE 1\nHISTORY LINE 2\n'))
// The host's negotiated visible-only read; null = an older host without the feature.
const hostCaptureVisible = vi.hoisted(() =>
vi.fn(async (_name: string): Promise<{ screen: string; cursor: { x: number; y: number } | null; altScreen: boolean } | null> => null)
)
vi.mock('./session-host-backend', async (original) => ({
...(await original<typeof import('./session-host-backend')>()),
sessionHostCapture: hostCapture,
sessionHostCaptureVisible: hostCaptureVisible
}))
const NODE = 'node-1'
const TARGET = `=${sessionName(NODE)}:`
const SSH_REMOTE = { conn: { host: 'h', user: 'u' }, controlPath: '/tmp/cm-abc', remoteCwd: '/srv' }
/** A manager with one registered session, built without `create` — `captureVisible` reads only the
* session's backend fields, so a spawn harness would be noise around the thing under test. */
async function manager(session: Record<string, unknown>, tmux: string | null = '/usr/bin/tmux') {
const { PtyManager } = await import('./pty-manager')
const mgr = new PtyManager() as unknown as {
tmuxPath: string | null
sessions: Map<string, unknown>
captureVisible(id: string): Promise<unknown>
}
mgr.tmuxPath = tmux
mgr.sessions.set('sess-1', { persistKey: NODE, indexKey: NODE, tmuxBacked: true, ...session })
return mgr
}
beforeEach(() => {
calls.length = 0
ssh.path = '/usr/bin/ssh'
hostCapture.mockClear()
script.answer = () => ({ stdout: 'hello\n\n2 0\n' })
// `findSsh` memoizes per module; a fresh module per test lets one test say "no ssh here".
vi.resetModules()
initPlatform(fakePlatform())
})
afterEach(() => resetPlatformForTests())
describe('captureVisible — local tmux', () => {
it('asks the local tmux once: visible screen + cursor, exact target, no history', async () => {
const m = await manager({})
expect(await m.captureVisible('sess-1')).toEqual({
screen: 'hello\n\n',
cursor: { x: 2, y: 0 }
})
expect(calls).toEqual([
{
file: '/usr/bin/tmux',
args: [
'-L',
TMUX_SOCKET,
'capture-pane',
'-p',
'-e',
'-t',
TARGET,
';',
'display-message',
'-p',
'-t',
TARGET,
VISIBLE_CAPTURE_FORMAT
]
}
])
expect(calls[0].args).not.toContain('-S')
})
it('a failed capture is unavailable, never a partial answer', async () => {
script.answer = () => {
throw Object.assign(new Error("can't find session: nt-node-1"), { code: 1 })
}
const m = await manager({})
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
})
it('a plain shell (not tmux-backed) gets no visible capture and runs nothing', async () => {
const m = await manager({ tmuxBacked: false })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
expect(calls).toEqual([])
})
it('no tmux binary: no visible capture, nothing run', async () => {
const m = await manager({}, null)
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
expect(calls).toEqual([])
})
it('an unknown session is unavailable', async () => {
const m = await manager({})
expect(await m.captureVisible('nope')).toEqual(unavailableCapture())
expect(calls).toEqual([])
})
})
describe('captureVisible — never history', () => {
it("a session-host session's visible capture is the host's visible-only read, with its own altScreen", async () => {
hostCaptureVisible.mockResolvedValueOnce({ screen: 'vis\n', cursor: { x: 3, y: 0 }, altScreen: false })
const m = await manager({ sessionHost: true })
expect(await m.captureVisible('sess-1')).toEqual({ screen: 'vis\n', cursor: { x: 3, y: 0 }, altScreen: false })
expect(hostCaptureVisible).toHaveBeenCalledWith(sessionName(NODE))
expect(hostCapture).not.toHaveBeenCalled()
expect(calls).toEqual([])
})
it('a session host without the read (older build) gets NO visible capture — never its scrollback capture', async () => {
hostCaptureVisible.mockResolvedValueOnce(null)
const m = await manager({ sessionHost: true })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
expect(hostCapture).not.toHaveBeenCalled()
expect(calls).toEqual([])
})
it('a direct Windows pane gets no visible capture either', async () => {
const capture = vi.fn(() => 'HISTORY')
const m = await manager({ nativeWindowsPane: { capture } })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
expect(capture).not.toHaveBeenCalled()
expect(calls).toEqual([])
})
})
describe('captureVisible — SSH project', () => {
it('asks the REMOTE tmux over the ControlMaster, one invocation, no history', async () => {
const m = await manager({ sshRemote: SSH_REMOTE })
expect(await m.captureVisible('sess-1')).toEqual({
screen: 'hello\n\n',
cursor: { x: 2, y: 0 }
})
expect(calls).toHaveLength(1)
expect(calls[0].file).toBe('/usr/bin/ssh')
const remote = calls[0].args.at(-1)!
expect(remote).toContain(`tmux -L "$_nts" capture-pane -p -e -t '${TARGET}' ';' display-message`)
expect(remote).not.toMatch(/-S\b/)
expect(calls[0].args).toContain('ControlPath=/tmp/cm-abc')
})
it('never falls through to the LOCAL tmux for a remote node', async () => {
ssh.path = null
const m = await manager({ sshRemote: SSH_REMOTE })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
expect(calls).toEqual([])
})
it('a dead ControlMaster is unavailable', async () => {
script.answer = () => {
throw Object.assign(new Error('mux_client_request_session: read from master failed'), { code: 255 })
}
const m = await manager({ sshRemote: SSH_REMOTE })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
})
})