The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { execFile } from 'node:child_process'
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { randomUUID } from 'node:crypto'
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
import { ENGINES } from '../engines/types.js'
import type { RegisteredSession } from './registry.js'
import { TerminalStreamManager } from './terminalStreamManager.js'
import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
import { pasteRawIntoTmux } from './tmux.js'
import { TmuxControlStream } from './tmuxStream.js'
import { tmuxFeatures } from './tmuxVersion.js'
import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'
const run = process.env.RUN_REAL_TMUX_STREAM === '1' ? describe : describe.skip
function tmux(args: string[]): Promise<string> {
return new Promise((resolve, reject) => {
execFile('tmux', ['-f', '/dev/null', ...args], { timeout: 3_000 }, (error, stdout) => error ? reject(error) : resolve(stdout.trim()))
})
}
async function eventually(predicate: () => boolean | Promise<boolean>, timeoutMs = 3_000): Promise<void> {
// A predicate that throws has not come true yet: a file the pane's process is about to create reads
// ENOENT for the ~200 ms an older tmux takes to start it.
const settled = async () => { try { return await predicate() } catch { return false } }
const deadline = Date.now() + timeoutMs
while (!await settled() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 20))
expect(await predicate()).toBe(true)
}
run('TmuxControlStream real tmux', () => {
const session = `harness-stream-${randomUUID().slice(0, 8)}`
let paneId = ''
let socketRoot = ''
beforeAll(async () => {
// A managed client must not attach to a developer's existing server of another tmux version.
socketRoot = await mkdtemp(join(tmpdir(), 'harness-stream-server-'))
vi.stubEnv('TMUX_TMPDIR', socketRoot)
vi.stubEnv('TMUX', undefined)
vi.stubEnv('TMUX_PANE', undefined)
})
afterAll(async () => {
await tmux(['kill-server']).catch(() => {})
vi.unstubAllEnvs()
await rm(socketRoot, { recursive: true, force: true })
})
beforeEach(async () => {
paneId = await tmux(['new-session', '-d', '-P', '-F', '#{pane_id}', '-s', session, 'bash', '--noprofile', '--norc'])
})
afterEach(async () => {
await tmux(['kill-session', '-t', session]).catch(() => { /* exact disposable session only */ })
})
it('captures, streams raw output, accepts input, and resizes one-pane windows', async () => {
const chunks: Buffer[] = []
let closedReason = ''
const opened = await TmuxControlStream.open(paneId, { cols: 96, rows: 28 }, {
onData: (bytes) => chunks.push(Buffer.from(bytes)),
onClose: (reason) => { closedReason = reason },
})
expect(opened.state).toBe('succeeded')
if (opened.state !== 'succeeded') return
const historyMarker = 'HARNESS_OLD_TUI_FRAME_MUST_NOT_REPLAY'
const styledHistoryMarker = 'HARNESS_STYLED_HISTORY'
const snapshotMarker = 'HARNESS_SNAPSHOT_OK'
await opened.value.writeRaw(Buffer.from(
`printf '\\033[31m${styledHistoryMarker}\\033[0m\\n${historyMarker}\\n'; for i in {1..40}; do printf 'filler-%s\\n' "$i"; done; printf '${snapshotMarker}\\n'\r`,
))
await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes(snapshotMarker))
opened.value.beginSnapshot()
const snapshot = await opened.value.snapshot()
expect(snapshot.state).toBe('succeeded')
if (snapshot.state === 'succeeded') {
expect(snapshot.value.cols).toBe(96)
expect(snapshot.value.rows).toBe(28)
expect(Buffer.from(snapshot.value.bytes).includes(Buffer.from('\u001bc'))).toBe(true)
expect(Buffer.from(snapshot.value.bytes).includes(Buffer.from(snapshotMarker))).toBe(true)
expect(Buffer.from(snapshot.value.bytes).includes(Buffer.from(historyMarker))).toBe(true)
expect(Buffer.from(snapshot.value.bytes).includes(Buffer.from(`\u001b[31m${styledHistoryMarker}`))).toBe(true)
}
const postCutMarker = 'HARNESS_POST_CUT_OK'
await opened.value.writeRaw(Buffer.from(`printf '${postCutMarker}\\n'\r`))
await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes(postCutMarker))
expect(Buffer.concat(chunks).includes(Buffer.from(postCutMarker))).toBe(false)
opened.value.endSnapshot()
await eventually(() => Buffer.concat(chunks).includes(Buffer.from(postCutMarker)))
await opened.value.writeRaw(Buffer.from("printf 'HARNESS_STREAM_OK\\n'\r"))
const deadline = Date.now() + 3_000
while (!Buffer.concat(chunks).includes(Buffer.from('HARNESS_STREAM_OK')) && Date.now() < deadline) {
await new Promise((resolve) => setTimeout(resolve, 20))
}
expect(Buffer.concat(chunks).includes(Buffer.from('HARNESS_STREAM_OK'))).toBe(true)
expect((await opened.value.scroll('up', 5)).state).toBe('succeeded')
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_in_mode}'])).toBe('0')
expect((await opened.value.scroll('down', 1)).state).toBe('succeeded')
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_in_mode}'])).toBe('0')
expect((await opened.value.resize({ cols: 110, rows: 35 })).state).toBe('succeeded')
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}'])).toBe('110x35')
await opened.value.close()
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}'])).toBe('110x35')
expect(closedReason === '' || closedReason === 'closed').toBe(true)
})
it('opens and resizes narrow and short panes without flooring them to desktop dimensions', async () => {
const opened = await TmuxControlStream.open(paneId, { cols: 30, rows: 8 }, {
onData: () => {}, onClose: () => {},
})
expect(opened.state).toBe('succeeded')
try {
if (opened.state !== 'succeeded') return
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}'])).toBe('30x8')
// Before tmux 2.9 a control client sizes the window, and tmux takes no client under 2x2.
const least = (await tmuxFeatures()).resizeWindow ? 1 : 2
for (const asked of [{ cols: 1, rows: 1 }, { cols: 39, rows: 11 }, { cols: 120, rows: 40 }]) {
const size = { cols: Math.max(least, asked.cols), rows: Math.max(least, asked.rows) }
expect((await opened.value.resize(asked)).state).toBe('succeeded')
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}'])).toBe(`${size.cols}x${size.rows}`)
opened.value.beginSnapshot()
const snapshot = await opened.value.snapshot()
expect(snapshot.state).toBe('succeeded')
if (snapshot.state === 'succeeded') expect(snapshot.value).toMatchObject(size)
opened.value.endSnapshot()
}
} finally {
if (opened.state === 'succeeded') await opened.value.close()
}
})
// A reply laid out for a desktop's width, after a phone took the pane: tmux re-wraps its history by the cell.
it('seeds a conversation\'s whole history re-wrapped by word, and any other pane\'s last screens as tmux has them', async () => {
const opened = await TmuxControlStream.open(paneId, { cols: 120, rows: 10 }, { onData: () => {}, onClose: () => {} })
expect(opened.state).toBe('succeeded')
try {
if (opened.state !== 'succeeded') return
const reply = join(socketRoot, 'reply.txt')
await writeFile(reply, `• I work right on your machine: I read and edit files, and run terminal commands. The main things:\n${
Array.from({ length: 800 }, (_, index) => `filler ${index}`).join('\n')}\n`)
await tmux(['send-keys', '-t', paneId, '-l', `cat '${reply}'`])
await tmux(['send-keys', '-t', paneId, 'Enter'])
await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes('filler 799'))
expect((await opened.value.resize({ cols: 40, rows: 10 })).state).toBe('succeeded')
const keyframe = async (options?: { conversationHistory?: boolean }) => {
opened.value.beginSnapshot()
const snapshot = await opened.value.snapshot(options)
opened.value.endSnapshot()
expect(snapshot.state).toBe('succeeded')
return snapshot.state === 'succeeded' ? Buffer.from(snapshot.value.bytes).toString('utf8') : ''
}
// 800 rows of filler under the reply: the last 500 rows of history leave the reply out, the conversation's all.
const plain = await keyframe()
expect(plain).not.toContain('I work right on your machine')
expect(plain).toContain('filler 799')
const conversation = await keyframe({ conversationHistory: true })
// tmux cut it at 40 columns as `… I read a` / `nd edit files …`.
expect(conversation).not.toMatch(/I read a\u001b\[0m\r\nnd edit/)
expect(conversation).toContain('• I work right on your machine: I read\u001b[0m\r\n and edit files, and run terminal\u001b[0m\r\n'
+ ' commands. The main things:\u001b[0m\r\n')
} finally {
if (opened.state === 'succeeded') await opened.value.close()
}
})
// Codex in its scrollback answers a resize about 80 ms later by clearing the screen and its scrollback, then
// printing its transcript again in one synchronized update; a phone drew the cleared screen at every raise and
// lower of its keyboard. At work it redraws its status line every few ms, so its output never pauses.
it('holds the keyframe after a resize until the print an engine declares ends, and the viewer never gets its clear', async () => {
const script = join(socketRoot, 'repaint.sh')
await writeFile(script, [
`trap 'sleep 0.08; printf "\\033[2J\\033[3J\\033[H\\033[?2026hREPAINTED\\n\\033[?2026l"' WINCH`,
`printf 'ready\\n'`,
`while :; do printf '\\033[?2026h\\rworking %s\\033[?2026l' "$RANDOM"; sleep 0.02; done`,
].join('\n') + '\n')
await tmux(['respawn-pane', '-k', '-t', paneId, 'bash', script])
await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes('ready'))
const live: Buffer[] = []
const opened = await TmuxControlStream.open(paneId, { cols: 80, rows: 20 }, { onData: (bytes) => { live.push(Buffer.from(bytes)) }, onClose: () => {} })
expect(opened.state).toBe('succeeded')
try {
if (opened.state !== 'succeeded') return
await new Promise((resolve) => setTimeout(resolve, 400))
const repaint = { clears: '\u001b[3J', ends: '\u001b[?2026l', withinMs: 250 }
for (const [rows, options] of [[12, undefined], [20, { repaint }]] as const) {
expect((await opened.value.resize({ cols: 80, rows })).state).toBe('succeeded')
live.length = 0
opened.value.beginSnapshot()
const began = Date.now()
const snapshot = await opened.value.snapshot(options)
const took = Date.now() - began
opened.value.endSnapshot()
await new Promise((resolve) => setTimeout(resolve, 400))
const after = Buffer.concat(live).toString('latin1')
expect(snapshot.state).toBe('succeeded')
if (options) {
// Ended by the print's own end, not by a pause the status line never leaves.
expect(took).toBeLessThan(400)
expect(after).not.toContain('\u001b[3J')
expect(snapshot.state === 'succeeded' && Buffer.from(snapshot.value.bytes).toString('utf8')).toContain('REPAINTED')
} else {
expect(after).toContain('\u001b[3J')
}
}
} finally {
if (opened.state === 'succeeded') await opened.value.close()
}
})
// The print began before the capture's cut and had not ended at it, after the wait for it had given up: the keyframe
// held a cleared, half-printed screen, and the rest of the print came as output with no clear in it (review of #1310).
it('takes the keyframe again when an engine\'s print was under way at the capture\'s cut', async () => {
const script = join(socketRoot, 'late-repaint.sh')
await writeFile(script, [
`trap 'printf "\\033[2J\\033[3J\\033[H\\033[?2026hHALF\\n"; sleep 0.5; printf "REPAINTED\\n\\033[?2026l"' WINCH`,
`printf 'ready\\n'`,
'while :; do sleep 0.02; done',
].join('\n') + '\n')
await tmux(['respawn-pane', '-k', '-t', paneId, 'bash', script])
await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes('ready'))
const live: Buffer[] = []
// The session's own size: opening does not resize it, and sets off no print of its own.
const opened = await TmuxControlStream.open(paneId, { cols: 80, rows: 24 }, { onData: (bytes) => { live.push(Buffer.from(bytes)) }, onClose: () => {} })
expect(opened.state).toBe('succeeded')
try {
if (opened.state !== 'succeeded') return
await new Promise((resolve) => setTimeout(resolve, 100))
opened.value.beginSnapshot()
expect((await opened.value.resize({ cols: 80, rows: 12 })).state).toBe('succeeded')
// Past the 250 ms the snapshot waits from a resize for the print to begin, which it did, and still under way.
await new Promise((resolve) => setTimeout(resolve, 300))
const screen = await tmux(['capture-pane', '-p', '-t', paneId])
expect(screen).toContain('HALF')
expect(screen).not.toContain('REPAINTED')
live.length = 0
const snapshot = await opened.value.snapshot({ repaint: { clears: '\u001b[3J', ends: '\u001b[?2026l', withinMs: 250 } })
opened.value.endSnapshot()
await new Promise((resolve) => setTimeout(resolve, 300))
expect(snapshot.state).toBe('succeeded')
expect(snapshot.state === 'succeeded' && Buffer.from(snapshot.value.bytes).toString('utf8')).toContain('REPAINTED')
expect(Buffer.concat(live).toString('latin1')).not.toContain('REPAINTED')
} finally {
if (opened.state === 'succeeded') await opened.value.close()
}
})
// The stream manager reads the output a keyframe held back as it reads live output, and begins the keyframe for
// Codex's print from it: what follows the clear precedes that keyframe's cut, and must not reach the viewer after it.
it('gives a keyframe the cursor of the grid it captured, while the pane is still printing', async () => {
// Keys are echoed while their own pane's keyframe is taken (backendSocket.ts `enqueueTerminalBinary`): a
// cursor read before the grid, a round trip earlier, sat behind the echo it came with, and the receiver
// drew the next one over it.
const opened = await TmuxControlStream.open(paneId, { cols: 200, rows: 10 }, { onData: () => {}, onClose: () => {} })
expect(opened.state).toBe('succeeded')
if (opened.state !== 'succeeded') return
try {
await opened.value.writeRaw(Buffer.from(`clear; for i in $(seq 1 150); do printf x; sleep 0.005; done; printf '\\nDONE\\n'\r`))
await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).startsWith('xx'))
const mismatches: string[] = []
let judged = 0
for (let attempt = 0; attempt < 20; attempt++) {
opened.value.beginSnapshot()
const shot = await opened.value.snapshot()
opened.value.endSnapshot()
expect(shot.state).toBe('succeeded')
if (shot.state !== 'succeeded') return
const text = Buffer.from(shot.value.bytes).toString('latin1')
const cursor = /\u001b\[(\d+);(\d+)H\u001b\[\?7h\u001b\[\?25[hl]$/.exec(text)
const firstRow = /\u001b\[1;1H(?:\u001b\[[0-9;]*m)*([^\u001b]*)/.exec(text)?.[1] ?? ''
const printed = /^x*/.exec(firstRow)![0].length
// Only while the loop is still printing on the first row: once done the prompt moves the cursor on.
if (cursor?.[1] !== '1' || printed >= 150) break
judged++
if (Number(cursor[2]) !== printed + 1) mismatches.push(`grid has ${printed} x, cursor at column ${cursor[2]}`)
}
expect(judged).toBeGreaterThan(3)
expect(mismatches).toEqual([])
} finally {
await opened.value.close()
}
})
it('holds what is left of the output a snapshot releases behind the next one its sink begins', async () => {
const delivered: string[] = []
let regate: (() => void) | null = null
const opened = await TmuxControlStream.open(paneId, { cols: 80, rows: 20 }, {
onData: (bytes) => {
delivered.push(Buffer.from(bytes).toString('utf8'))
const begin = regate
regate = null
begin?.()
},
onClose: () => {},
})
expect(opened.state).toBe('succeeded')
try {
if (opened.state !== 'succeeded') return
opened.value.beginSnapshot()
expect((await opened.value.snapshot()).state).toBe('succeeded')
const script = join(socketRoot, 'chunks.sh')
await writeFile(script, "printf 'one,'; sleep 0.1; printf 'two,'; sleep 0.1; printf 'three'; sleep 30\n")
await tmux(['respawn-pane', '-k', '-t', paneId, 'bash', script])
await eventually(async () => (await tmux(['capture-pane', '-p', '-t', paneId])).includes('one,two,three'))
await new Promise((resolve) => setTimeout(resolve, 100))
delivered.length = 0
regate = () => opened.value.beginSnapshot()
opened.value.endSnapshot()
// The first chunk began a snapshot: the rest are held behind it, and released with it, in order.
expect(delivered).toHaveLength(1)
opened.value.endSnapshot()
expect(delivered.length).toBeGreaterThan(1)
expect(delivered.join('')).toContain('one,two,three')
} finally {
if (opened.state === 'succeeded') await opened.value.close()
}
})
it('streams large styled Unicode and control-byte output without losing or changing bytes', async () => {
const directory = await mkdtemp(join(tmpdir(), 'harness-stream-bytes-'))
const path = join(directory, 'payload.bin')
const payload = Buffer.from(`BEGIN_STREAM_BYTES\n${'\x1b[38;5;112m─世界🚀\\\0\x1b[0m\r\n'.repeat(4_000)}END_STREAM_BYTES\n`)
await writeFile(path, payload)
const chunks: Buffer[] = []
const opened = await TmuxControlStream.open(paneId, { cols: 96, rows: 28 }, {
onData: bytes => chunks.push(Buffer.from(bytes)), onClose: () => {},
})
try {
expect(opened.state).toBe('succeeded')
if (opened.state !== 'succeeded') return
// The payload is a file, so a shell echo cannot make the assertion pass.
// Disable tty newline rewriting before cat sends the exact binary bytes.
const quotedPath = `'${path.replace(/'/g, `'\\''`)}'`
expect((await opened.value.writeRaw(Buffer.from(`stty -echo -opost; cat ${quotedPath}\r`))).state).toBe('succeeded')
await eventually(() => Buffer.concat(chunks).includes(Buffer.from('END_STREAM_BYTES\n')))
expect(Buffer.concat(chunks).includes(payload)).toBe(true)
} finally {
if (opened.state === 'succeeded') await opened.value.close()
await rm(directory, { recursive: true, force: true })
}
})
it('types every byte exactly as given: quotes, a trailing semicolon, a leading dash, control bytes, UTF-8', async () => {
// tmux before 3.0 has no `send-keys -H`: there the bytes go as quoted literal text and keys, and this
// is the case that would show a byte its command parser took for syntax (`literalKeyCommands`).
const directory = await mkdtemp(join(tmpdir(), 'harness-typed-'))
const sink = join(directory, 'typed.bin')
const typed = Buffer.concat([
Buffer.from("-l 'single' \"double\" $HOME #not-a-comment ~ a;b \\; \t\r\u001b[A\u007f 世界🚀 "),
Buffer.from([0x0a, 0x00, 0x01, 0x1f]),
Buffer.from('x'.repeat(5_000) + "';"),
])
const typedSession = `harness-typed-${randomUUID().slice(0, 8)}`
// A raw tty: every byte reaches `head` as it was written, none taken for a signal or a line edit.
const typedPane = await tmux([
'new-session', '-d', '-P', '-F', '#{pane_id}', '-s', typedSession,
'bash', '--noprofile', '--norc', '-c', `stty raw -echo; head -c ${typed.length} > ${sink}`,
])
try {
const opened = await TmuxControlStream.open(typedPane, { cols: 120, rows: 30 }, { onData: () => {}, onClose: () => {} })
expect(opened.state).toBe('succeeded')
if (opened.state !== 'succeeded') return
// The pane's `stty raw` must land before the first byte, or the tty would still edit lines.
await new Promise((resolve) => setTimeout(resolve, 500))
expect((await opened.value.writeRaw(typed)).state).toBe('succeeded')
await eventually(async () => (await readFile(sink)).length === typed.length, 5_000)
expect((await readFile(sink)).equals(typed)).toBe(true)
await opened.value.close()
} finally {
await tmux(['kill-session', '-t', typedSession]).catch(() => { /* best effort */ })
}
})
it('delivers a multi-chunk paste to the pane whole and in order', async () => {
// 8 KiB in one writeRaw spans several `send-keys -H` commands (INPUT_CHUNK_BYTES is 2 KiB).
// They are pipelined into the control client, so this is the case that would expose either a
// lost chunk or a reordered one. Lines stay under the tty's canonical-mode limit on purpose.
const directory = await mkdtemp(join(tmpdir(), 'harness-paste-'))
const sink = join(directory, 'paste.txt')
const pasteSession = `harness-paste-${randomUUID().slice(0, 8)}`
// tmux runs the command with execvp, not a shell, so the redirect needs an explicit one.
const pastePane = await tmux([
'new-session', '-d', '-P', '-F', '#{pane_id}', '-s', pasteSession,
'bash', '--noprofile', '--norc', '-c', `cat > ${sink}`,
])
try {
const opened = await TmuxControlStream.open(pastePane, { cols: 120, rows: 30 }, {
onData: () => { /* echo is irrelevant; the file is the assertion */ },
onClose: () => { /* torn down below */ },
})
expect(opened.state).toBe('succeeded')
if (opened.state !== 'succeeded') return
const lines = Array.from({ length: 100 }, (_, index) => `${String(index).padStart(4, '0')}${'y'.repeat(96)}`)
const payload = Buffer.from(`${lines.join('\r')}\r`)
// Spans five `send-keys -H` commands at INPUT_CHUNK_BYTES.
expect(Math.ceil(payload.length / 2048)).toBeGreaterThanOrEqual(5)
expect((await opened.value.writeRaw(payload)).state).toBe('succeeded')
await eventually(async () => (await readFile(sink, 'utf8')).split('\n').length > lines.length)
const written = (await readFile(sink, 'utf8')).split('\n').filter((line) => line.length > 0)
expect(written).toEqual(lines)
await opened.value.close()
} finally {
await tmux(['kill-session', '-t', pasteSession]).catch(() => { /* best effort */ })
}
})
it('delivers a paste via pasteRaw as one atomic paste-buffer, whole and in order', async () => {
// Same shape as the writeRaw multi-chunk test above, but through pasteRaw — the point of this
// test is that a payload big enough to span several `send-keys -H` commands via writeRaw still
// lands as ONE `tmux paste-buffer` here, which is what lets the program in the pane (readline,
// Ink, ...) see it as a single paste instead of one per chunk.
const directory = await mkdtemp(join(tmpdir(), 'harness-pasteraw-'))
const sink = join(directory, 'paste.txt')
const pasteSession = `harness-pasteraw-${randomUUID().slice(0, 8)}`
const pastePane = await tmux([
'new-session', '-d', '-P', '-F', '#{pane_id}', '-s', pasteSession,
'bash', '--noprofile', '--norc', '-c', `cat > ${sink}`,
])
try {
const opened = await TmuxControlStream.open(pastePane, { cols: 120, rows: 30 }, {
onData: () => { /* echo is irrelevant; the file is the assertion */ },
onClose: () => { /* torn down below */ },
})
expect(opened.state).toBe('succeeded')
if (opened.state !== 'succeeded') return
const lines = Array.from({ length: 100 }, (_, index) => `${String(index).padStart(4, '0')}${'z'.repeat(96)}`)
const text = `${lines.join('\n')}\n`
// Same size class as the writeRaw test — big enough that writeRaw would span 5+ send-keys
// commands, so pasteRaw's single paste-buffer path is genuinely exercised, not a size where
// the two approaches would coincide anyway.
expect(Math.ceil(Buffer.byteLength(text) / 2048)).toBeGreaterThanOrEqual(5)
expect((await opened.value.pasteRaw(text)).state).toBe('succeeded')
await eventually(async () => (await readFile(sink, 'utf8')).split('\n').length > lines.length)
const written = (await readFile(sink, 'utf8')).split('\n').filter((line) => line.length > 0)
expect(written).toEqual(lines)
await opened.value.close()
} finally {
await tmux(['kill-session', '-t', pasteSession]).catch(() => { /* best effort */ })
}
})
it('runs every catalog engine through the same manager and real tmux stream', async () => {
for (const [index, engine] of ENGINES.entries()) {
const agentId = `real-tmux-${engine}`
const registered = {
agentId,
sessionId: `session-${engine}`,
engine,
active: true,
registeredAt: Date.now(),
touchedAt: Date.now(),
runtimes: [{ backend: 'tmux', paneId }],
primaryRuntimeKey: `tmux:default:${paneId}`,
} as unknown as RegisteredSession
const frames: Array<{ type: string; payload: Record<string, unknown> }> = []
const binaryFrames: TerminalBinaryClear[] = []
const terminals = {
openStream: async (_session: RegisteredSession, size: { cols: number; rows: number }, sink: Parameters<typeof TmuxControlStream.open>[2]) =>
TmuxControlStream.open(paneId, size, sink),
} as unknown as TerminalBackendCoordinator
const manager = new TerminalStreamManager({
terminals,
resolveAgent: (candidate) => candidate === agentId ? registered : undefined,
sendTarget: (_connId, type, payload) => { frames.push({ type, payload }); return true },
sendBinaryTarget: (_connId, frame) => { binaryFrames.push(frame); return true },
streamingAvailable: true,
})
try {
await manager.handleFrame('matrix-client', 'terminal_open', {
requestId: `open-${engine}`,
protocolVersion: 3,
agentId,
cols: 90 + index,
rows: 24,
compression: ['none'],
})
const ready = frames.find((frame) => frame.type === 'terminal_ready')
expect(ready?.payload).toMatchObject({ agentId, engineId: engine })
const streamId = ready?.payload.streamId
expect(typeof streamId).toBe('string')
const marker = `HARNESS_ENGINE_STREAM_${engine.toUpperCase()}`
await manager.handleBinary('matrix-client', {
kind: TerminalBinaryKind.input,
streamId: streamId as string,
seq: 0,
compressed: false,
bytes: Buffer.from(`printf '${marker}\\n'\r`),
})
await eventually(() => binaryFrames.some((frame) => {
if (frame.kind !== TerminalBinaryKind.output || frame.compressed) return false
return Buffer.from(frame.bytes).includes(Buffer.from(marker))
}))
await manager.handleFrame('matrix-client', 'terminal_resize', {
streamId,
resizeSeq: 0,
cols: 100 + index,
rows: 30,
})
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_width}x#{pane_height}']))
.toBe(`${100 + index}x30`)
await manager.handleFrame('matrix-client', 'terminal_close', { streamId })
} finally {
await manager.stop()
}
}
}, 60_000)
it('never mistakes the control client handshake for the first snapshot command', async () => {
for (let attempt = 0; attempt < 12; attempt++) {
const opened = await TmuxControlStream.open(paneId, { cols: 100, rows: 30 }, {
onData: () => {},
onClose: () => {},
})
expect(opened.state).toBe('succeeded')
if (opened.state !== 'succeeded') continue
opened.value.beginSnapshot()
const snapshot = await opened.value.snapshot()
expect(snapshot.state).toBe('succeeded')
opened.value.endSnapshot()
await opened.value.close()
}
})
it('keeps the tmux server up while terminals open and close side by side and messages are pasted', async () => {
// Before tmux 3.7 a notification for every control client (one going, a paste buffer set or deleted)
// that met one still attaching crashed the server, every agent's pane with it (tmux issue 4980,
// tmuxControlGate.ts). This is windows.e2e.ts's churn, which found it: on Ubuntu 24.04's tmux 3.4,
// without the gate, the server segfaulted within the first few hundred of these rounds.
const beside = `${session}-beside`
const besidePane = await tmux(['new-session', '-d', '-P', '-F', '#{pane_id}', '-s', beside, 'cat'])
const sink = { onData: () => {}, onClose: () => {} }
const openAndClose = async (pane: string, readOnly: boolean) => {
const opened = await TmuxControlStream.open(pane, { cols: 90, rows: 25 }, sink, readOnly)
expect(opened.state, opened.state === 'failed' ? opened.reason : '').toBe('succeeded')
if (opened.state === 'succeeded') await opened.value.close()
}
try {
for (let round = 0; round < 300; round++) {
await Promise.all([
openAndClose(paneId, false),
openAndClose(besidePane, true),
openAndClose(paneId, true),
pasteRawIntoTmux(besidePane, `round ${round}\n`),
])
}
expect(await tmux(['display-message', '-p', '-t', paneId, '#{pane_id}'])).toBe(paneId)
} finally {
await tmux(['kill-session', '-t', beside]).catch(() => { /* best effort */ })
}
}, 120_000)
})