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 { afterEach, describe, it, expect, vi } from 'vitest'
import {
createHostHandlers,
type HostPtyManager,
type HostRelaySocket
} from '../../src/main/remote/host-service'
import { OP } from '../../src/main/remote/framing'
import { RESUME_REPAINT_PREFIX } from '../../src/shared/capture-paint'
import type { DetachedSinks } from '../../src/main/pty-manager'
import type { PtyCreateOptions } from '../../src/shared/types'
// A fake pty-manager that records calls and lets the test fire the captured sinks.
function fakePty() {
const calls: { method: string; args: unknown[] }[] = []
let lastSinks: DetachedSinks | null = null
let lastOptions: PtyCreateOptions | null = null
let counter = 0
let snapshot = ''
let sessionLive = true
// The relay attach is decided in core (`prepareRelayAttach`); this fake composes it from its own
// probe/snapshot/attach so the sequence the host runs them in stays observable in `calls`.
const mgr: HostPtyManager & {
attachDetached(persistKey: string, sinks: DetachedSinks, options?: Omit<PtyCreateOptions, 'persistKey'>): string
captureSnapshot(persistKey: string): Promise<string>
} = {
prepareRelayAttach: async (nodeId, size) => ({
kind: 'ready',
remote: false,
sessionExists: () => mgr.sessionExists(nodeId),
snapshot: () => mgr.captureSnapshot(nodeId),
attach: async (sinks) => mgr.attachDetached(nodeId, sinks, size)
}),
createDetached(options, sinks) {
lastOptions = options
lastSinks = sinks
const id = `pty-${++counter}`
calls.push({ method: 'createDetached', args: [options, id] })
return id
},
attachDetached(persistKey, sinks, options) {
lastSinks = sinks
const id = `pty-${++counter}`
calls.push({ method: 'attachDetached', args: [persistKey, id, options] })
return id
},
captureSnapshot: async (persistKey) => {
calls.push({ method: 'captureSnapshot', args: [persistKey] })
return snapshot
},
sessionExists: async (persistKey) => {
calls.push({ method: 'sessionExists', args: [persistKey] })
return sessionLive
},
write: (clientId, sessionId, data) =>
calls.push({ method: 'write', args: [clientId, sessionId, data] }),
resize: (clientId, sessionId, cols, rows) =>
calls.push({ method: 'resize', args: [clientId, sessionId, cols, rows] }),
// A relay-served (detached) pty has no ClientId: its pause is owed by the host's sink (null).
setFlow: (clientId, sessionId, resume) =>
calls.push({ method: 'setFlow', args: [clientId, sessionId, resume] }),
// Relay-served ptys are killed with clientId null (they have no UI subscribers).
kill: (clientId, sessionId) => calls.push({ method: 'kill', args: [clientId, sessionId] })
}
return {
mgr,
calls,
sinks: () => lastSinks!,
options: () => lastOptions!,
setSnapshot: (s: string) => {
snapshot = s
},
setSessionLive: (live: boolean) => {
sessionLive = live
}
}
}
function fakeSocket(sendOk = true) {
const responses: { id: string; ok: boolean; body: unknown }[] = []
const frames: { op: number; streamId: number; seq: number; payload: Uint8Array }[] = []
// `ok` / `buffered` are mutable so a test can stall the socket and then let it drain.
const state = { ok: sendOk, buffered: 0 }
const socket: HostRelaySocket = {
respond: (id, ok, body) => responses.push({ id, ok, body }),
sendFrame: (op, streamId, seq, payload) => {
frames.push({ op, streamId, seq, payload })
return state.ok
},
bufferedAmount: () => state.buffered
}
return { socket, responses, frames, state }
}
const resizePayload = (cols: number, rows: number) => {
const buf = new Uint8Array(4)
const view = new DataView(buf.buffer)
view.setUint16(0, cols, true)
view.setUint16(2, rows, true)
return buf
}
// Open a stream the only way a remote client can: pty.attach to an existing session. Resolves
// once the async snapshot+attach has bound the sinks (sessionId 'pty-1'). Returns streamId 1.
async function openViaAttach(
h: ReturnType<typeof createHostHandlers>,
nodeId = 'node-1'
): Promise<void> {
h.onRpc({ id: `open-${nodeId}`, method: 'pty.attach', params: { nodeId, cols: 80, rows: 24 } })
await new Promise((r) => setTimeout(r, 0))
}
describe('createHostHandlers', () => {
it('rejects pty.create — remote clients may only attach to existing sessions', () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
h.onRpc({ id: 'r1', method: 'pty.create', params: { cols: 100, rows: 30, cwd: '/', shell: '/bin/sh' } })
expect(sock.responses[0]).toMatchObject({ id: 'r1', ok: false })
expect(pty.calls.some((c) => c.method === 'createDetached')).toBe(false)
})
it('maps pty.attach to a snapshot sequence then attachDetached on the existing session', async () => {
const pty = fakePty()
pty.setSnapshot('CURRENT SCREEN')
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
h.onRpc({ id: 'r1', method: 'pty.attach', params: { nodeId: 'node-9', cols: 100, rows: 30 } })
// The stream is reserved SYNCHRONOUSLY — that, not the timing of the response, is what lets
// the host route this streamId's inbound frames right away. The response itself now waits on
// the `fresh` probe (a tmux side-call), because whether the attach CREATED the session has to
// be asked before `attachDetached` does it.
h.onFrame({ op: OP.Input, streamId: 1, seq: 0, payload: new TextEncoder().encode('x') })
expect(pty.calls.some((c) => c.method === 'write')).toBe(true)
// Capture + attach are async (a tmux side-call).
await new Promise((r) => setTimeout(r, 0))
expect(sock.responses).toEqual([{ id: 'r1', ok: true, body: { streamId: 1, fresh: false } }])
expect(pty.calls).toContainEqual({ method: 'captureSnapshot', args: ['node-9'] })
expect(pty.calls).toContainEqual({
method: 'attachDetached',
args: ['node-9', 'pty-1', { cols: 100, rows: 30 }]
})
// Snapshot frames precede any live output: Start, one Chunk (the screen text), End.
expect(sock.frames[0]).toMatchObject({ op: OP.SnapshotStart, streamId: 1 })
expect(sock.frames[1]).toMatchObject({ op: OP.SnapshotChunk, streamId: 1 })
expect(Buffer.from(sock.frames[1].payload).toString('utf8')).toBe('CURRENT SCREEN')
expect(sock.frames[2]).toMatchObject({ op: OP.SnapshotEnd, streamId: 1 })
// Live output then drives the same stream.
pty.sinks().onData('live')
const out = sock.frames.find((f) => f.op === OP.Output)
expect(out).toBeDefined()
expect(Buffer.from(out!.payload).toString('utf8')).toBe('live')
})
// A node whose tmux session died (host reboot, tmux server gone) still ATTACHES — the client
// needs a live pane to type its cold restore (`cd <cwd>; claude --resume <id>`) into, exactly as
// the SSH path gets one from `tmux new-session -A`. What changed is that the reply now SAYS it
// was a cold start, so the client runs that restore instead of presenting the bare login shell
// under the node's title, which is what a phone saw as `~ %` on a Claude session.
it('still creates on a cold node, but reports fresh=true so the client can restore', async () => {
const pty = fakePty()
pty.setSessionLive(false)
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
h.onRpc({ id: 'r1', method: 'pty.attach', params: { nodeId: 'cold-1', cols: 80, rows: 24 } })
await new Promise((r) => setTimeout(r, 0))
expect(sock.responses).toEqual([{ id: 'r1', ok: true, body: { streamId: 1, fresh: true } }])
// Deliberately NOT a refusal: refusing would leave the client with nowhere to resume.
expect(pty.calls).toContainEqual({
method: 'attachDetached',
args: ['cold-1', 'pty-1', { cols: 80, rows: 24 }]
})
})
it('attach sends an empty snapshot when the session has no current screen', async () => {
const pty = fakePty() // snapshot defaults to ''
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
h.onRpc({ id: 'r1', method: 'pty.attach', params: { nodeId: 'node-1', cols: 80, rows: 24 } })
await new Promise((r) => setTimeout(r, 0))
// Empty snapshot: Start, End, no Chunk.
expect(sock.frames.map((f) => f.op)).toContain(OP.SnapshotStart)
expect(sock.frames.map((f) => f.op)).toContain(OP.SnapshotEnd)
expect(sock.frames.some((f) => f.op === OP.SnapshotChunk)).toBe(false)
expect(pty.calls).toContainEqual({
method: 'attachDetached',
args: ['node-1', 'pty-1', { cols: 80, rows: 24 }]
})
})
it('rejects pty.attach without a nodeId', () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
h.onRpc({ id: 'r1', method: 'pty.attach', params: { cols: 80, rows: 24 } })
expect(sock.responses[0]).toMatchObject({ id: 'r1', ok: false })
})
it('pipes PTY output into OP.Output frames with an incrementing seq', async () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h)
pty.sinks().onData('hello')
pty.sinks().onData('world')
const outs = sock.frames.filter((f) => f.op === OP.Output)
expect(outs).toHaveLength(2)
expect(outs[0]).toMatchObject({ op: OP.Output, streamId: 1 })
expect(Buffer.from(outs[0].payload).toString('utf8')).toBe('hello')
expect(outs[1].seq).toBe(outs[0].seq + 1) // monotonic
})
it('routes OP.Input frames to write and OP.Resize frames to resize', async () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h)
h.onFrame({ op: OP.Input, streamId: 1, seq: 0, payload: new TextEncoder().encode('ls\n') })
h.onFrame({ op: OP.Resize, streamId: 1, seq: 0, payload: resizePayload(120, 40) })
// No presence slot wired (getClientId defaults to null) → the input still reaches the pty, it
// is simply not attributed to a typing peer.
expect(pty.calls).toContainEqual({ method: 'write', args: [null, 'pty-1', 'ls\n'] })
// clientId null: the relay-served pty's size is recorded against its sink, not a UI client.
expect(pty.calls).toContainEqual({ method: 'resize', args: [null, 'pty-1', 120, 40] })
})
it('attributes an OP.Input frame to the bridged phone (typing badge, no iOS change needed)', async () => {
const pty = fakePty()
const sock = fakeSocket()
// The phone's presence ClientId, read per frame from its PhonePresence slot (joined on bridge).
const h = createHostHandlers(pty.mgr, sock.socket, undefined, undefined, undefined, () => 1_000_001)
await openViaAttach(h)
h.onFrame({ op: OP.Input, streamId: 1, seq: 0, payload: new TextEncoder().encode('ls\n') })
expect(pty.calls).toContainEqual({ method: 'write', args: [1_000_001, 'pty-1', 'ls\n'] })
})
it('ignores frames for unknown streams', () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
h.onFrame({ op: OP.Input, streamId: 99, seq: 0, payload: new TextEncoder().encode('x') })
expect(pty.calls).toHaveLength(0)
})
// A paused node-pty emits NO further onData, so a resume that waits for
// "the next successful send" never comes and the phone's terminal froze for good after one >8 MB
// burst. These tests deliver nothing after the pause — the drain sweep alone must resume it.
describe('relay backpressure: the drain sweep resumes a paused stream', () => {
afterEach(() => {
vi.useRealTimers()
})
const resumes = (pty: ReturnType<typeof fakePty>) =>
pty.calls.filter((c) => c.method === 'setFlow' && c.args[2] === true)
async function pausedStream(screen = 'SCREEN') {
const pty = fakePty()
pty.setSnapshot(screen)
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h)
vi.useFakeTimers()
sock.state.ok = false // the relay buffer is over 8 MB: sendFrame refuses (and drops)
sock.state.buffered = 9_000_000
pty.sinks().onData('a')
expect(pty.calls).toContainEqual({ method: 'setFlow', args: [null, 'pty-1', false] })
return { pty, sock, h }
}
it('resumes once drained, with no further pty output, and repaints BEFORE resuming', async () => {
const { pty, sock } = await pausedStream()
const order: string[] = []
sock.socket.sendFrame = (op) => {
order.push(`frame:${op}`)
return true
}
const realSetFlow = pty.mgr.setFlow
pty.mgr.setFlow = (...args) => {
order.push(`setFlow:${String(args[2])}`)
realSetFlow(...args)
}
sock.state.ok = true
sock.state.buffered = 0 // drained — and the paused pty delivers NOTHING
await vi.advanceTimersByTimeAsync(300)
expect(resumes(pty)).toEqual([{ method: 'setFlow', args: [null, 'pty-1', true] }])
// A fresh screen (the frame that crossed the line was dropped), and only then live output.
expect(order).toEqual([
`frame:${OP.SnapshotStart}`,
`frame:${OP.SnapshotChunk}`,
`frame:${OP.SnapshotEnd}`,
'setFlow:true'
])
expect(vi.getTimerCount()).toBe(0) // the sweep disarms once nothing is paused
})
const resumePayload = (sock: ReturnType<typeof fakeSocket>, from: number): string => {
const start = sock.frames.findIndex((f, i) => i >= from && f.op === OP.SnapshotStart)
expect(start).toBeGreaterThanOrEqual(0)
const chunks: string[] = []
for (let i = start + 1; i < sock.frames.length && sock.frames[i].op === OP.SnapshotChunk; i++) {
chunks.push(Buffer.from(sock.frames[i].payload).toString('utf8'))
}
return chunks.join('')
}
it('the resume repaint clears and homes first and paints with CRLF line endings', async () => {
// The phone feeds a snapshot into its emulator as-is, with no reset, and the frame that
// crossed the 8 MB line was dropped: written raw, the capture lands at the phone's current
// cursor over the old screen, and its bare LFs staircase (SwiftTerm runs convertEol off).
const { sock } = await pausedStream('row one\nrow two\n')
sock.state.ok = true
sock.state.buffered = 0
const from = sock.frames.length
await vi.advanceTimersByTimeAsync(300)
const payload = resumePayload(sock, from)
expect(payload.startsWith(RESUME_REPAINT_PREFIX)).toBe(true)
expect(RESUME_REPAINT_PREFIX).toContain('\x1b[H\x1b[2J')
// One trailing newline dropped (it would scroll the top row away), every LF made CRLF.
expect(payload).toBe(RESUME_REPAINT_PREFIX + 'row one\r\nrow two')
})
it('the resume repaint puts the cursor where the pane has it when the capture says', async () => {
const pty = fakePty()
pty.setSnapshot('ATTACH SCREEN\n')
const visible: string[] = []
;(pty.mgr as HostPtyManager).captureVisible = async (sessionId) => {
visible.push(sessionId)
return { screen: 'prompt $ \nstatus\n', cursor: { x: 9, y: 0 } }
}
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h)
// The attach snapshot is byte-identical to before: the raw capture, no prefix, no cursor.
expect(Buffer.from(sock.frames[1].payload).toString('utf8')).toBe('ATTACH SCREEN\n')
vi.useFakeTimers()
sock.state.ok = false
sock.state.buffered = 9_000_000
pty.sinks().onData('a')
sock.state.ok = true
sock.state.buffered = 0
const from = sock.frames.length
await vi.advanceTimersByTimeAsync(300)
expect(visible).toEqual(['pty-1'])
expect(resumePayload(sock, from)).toBe(RESUME_REPAINT_PREFIX + 'prompt $ \r\nstatus' + '\x1b[1;10H')
})
it('an unavailable visible capture falls back to the attach capture, with no cursor', async () => {
const pty = fakePty()
pty.setSnapshot('FALLBACK\n')
;(pty.mgr as HostPtyManager).captureVisible = async () => ({ screen: '', cursor: null, unavailable: true })
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h)
vi.useFakeTimers()
sock.state.ok = false
sock.state.buffered = 9_000_000
pty.sinks().onData('a')
sock.state.ok = true
sock.state.buffered = 0
const from = sock.frames.length
await vi.advanceTimersByTimeAsync(300)
expect(resumePayload(sock, from)).toBe(RESUME_REPAINT_PREFIX + 'FALLBACK')
})
it('stays paused while the socket is above the low-water mark', async () => {
const { pty, sock } = await pausedStream()
sock.state.ok = true
sock.state.buffered = 1_000_000 // draining, but not below 256 KB yet
await vi.advanceTimersByTimeAsync(2_000)
expect(resumes(pty)).toEqual([])
sock.state.buffered = 100_000
await vi.advanceTimersByTimeAsync(300)
expect(resumes(pty)).toHaveLength(1)
})
it('drops output still queued after the pause instead of streaming a desynced screen', async () => {
const { pty, sock } = await pausedStream()
const outputs = () => sock.frames.filter((f) => f.op === OP.Output).length
const before = outputs()
pty.sinks().onData('late batch') // the one queueData batch already in flight
expect(outputs()).toBe(before)
})
it('an empty capture still resumes (no repaint) rather than staying frozen', async () => {
const { pty, sock } = await pausedStream('')
sock.state.ok = true
sock.state.buffered = 0
const framesBefore = sock.frames.length
await vi.advanceTimersByTimeAsync(300)
expect(resumes(pty)).toHaveLength(1)
expect(sock.frames.slice(framesBefore).some((f) => f.op === OP.SnapshotStart)).toBe(false)
})
it('a snapshot the socket refuses keeps the stream paused and retries with backoff', async () => {
const { pty, sock } = await pausedStream()
const captures = () => pty.calls.filter((c) => c.method === 'captureSnapshot').length
const capturesAtPause = captures()
// Reports drained, but every send fails — what a relay between transports looks like
// (bufferedAmount 0, state not ready). Must not become a capture per tick.
sock.state.buffered = 0
await vi.advanceTimersByTimeAsync(5_000)
expect(resumes(pty)).toEqual([])
// 250 ms ticks for 5 s would be 20 captures; the backoff (250, 500, 1 s, 2 s …) allows ~5.
expect(captures() - capturesAtPause).toBeLessThanOrEqual(6)
sock.state.ok = true
await vi.advanceTimersByTimeAsync(10_500)
expect(resumes(pty)).toHaveLength(1)
})
it('closeAll while paused disarms the sweep and never resumes the released pty', async () => {
const { pty, sock, h } = await pausedStream()
h.closeAll()
expect(vi.getTimerCount()).toBe(0)
sock.state.ok = true
sock.state.buffered = 0
await vi.advanceTimersByTimeAsync(1_000)
expect(resumes(pty)).toEqual([])
})
it('pty.kill while paused disarms the sweep', async () => {
const { h } = await pausedStream()
h.onRpc({ id: 'k', method: 'pty.kill', params: { streamId: 1 } })
expect(vi.getTimerCount()).toBe(0)
})
})
it('rejects unknown RPC methods', () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
h.onRpc({ id: 'r9', method: 'pty.bogus', params: {} })
expect(sock.responses[0]).toMatchObject({ id: 'r9', ok: false })
})
it('pty.kill kills the session and forgets the stream', async () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h)
h.onRpc({ id: 'r2', method: 'pty.kill', params: { streamId: 1 } })
expect(pty.calls).toContainEqual({ method: 'kill', args: [null, 'pty-1'] })
// After kill, input for the dropped stream is ignored.
pty.calls.length = 0
h.onFrame({ op: OP.Input, streamId: 1, seq: 0, payload: new TextEncoder().encode('x') })
expect(pty.calls).toHaveLength(0)
})
it('emits an OP.Error frame on PTY exit and drops the stream', async () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h)
pty.sinks().onExit(0)
const errFrame = sock.frames.find((f) => f.op === OP.Error)
expect(errFrame).toBeDefined()
expect(JSON.parse(Buffer.from(errFrame!.payload).toString('utf8'))).toEqual({ exitCode: 0 })
})
it('closeAll kills every live session', async () => {
const pty = fakePty()
const sock = fakeSocket()
const h = createHostHandlers(pty.mgr, sock.socket)
await openViaAttach(h, 'node-1')
await openViaAttach(h, 'node-2')
h.closeAll()
expect(pty.calls.filter((c) => c.method === 'kill')).toHaveLength(2)
})
})