Skip to content

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.

feat: implement binary terminal protocol with encryption support for optimized communication

0xken1584fbf8d42983
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 290d8ae40..8daf10850 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -45,6 +45,12 @@ import { readOpencodeMessages } from './engines/opencode/reader.js'
import { readKiloMessages } from './engines/kilo/reader.js'
import { E2eeManager, type PairResult } from './lib/e2ee/manager.js'
import type { TerminalStreamManager } from './lib/terminalStreamManager.js'
+import {
+ decodeTerminalHop,
+ encodeTerminalHop,
+ TerminalHopDirection,
+ type TerminalBinaryClear,
+} from './lib/terminalBinary.js'
import { ENCRYPTED_RPC_RESULT_TYPES, isEncryptedDownType, isWrapped } from './lib/e2ee/core.js'
import { DEVICE_RECENT_SAFE_FRAME_BYTES, fitRecentReplyPayloadForDevice } from './lib/deviceRecentTrim.js'
import { shouldReplayCommander } from './lib/commanderReplay.js'
@@ -412,7 +418,12 @@ export class BackendSocket {
this.appPing = setInterval(() => this.sendBestEffort({ t: 'ping' }), APP_PING_MS)
})
- ws.on('message', (raw) => {
+ ws.on('message', (raw, isBinary) => {
+ if (isBinary) {
+ const hop = decodeTerminalHop(new Uint8Array(raw as Buffer))
+ if (hop?.direction === TerminalHopDirection.down) this.enqueueTerminalBinary(hop.connId, hop.clientFrame)
+ return
+ }
let env_: DownEnvelope
try { env_ = JSON.parse(raw.toString()) as DownEnvelope } catch { return }
if (env_.t === 'down' && env_.frame) {
@@ -497,6 +508,16 @@ export class BackendSocket {
})
}
+ /** Pairwise-encrypted binary terminal output/keyframe. The hop prefix exposes
+ * only connId and direction to the opaque backend relay. */
+ sendTerminalBinaryTo(connId: string, clear: TerminalBinaryClear): boolean {
+ const clientFrame = this.e2ee.wrapTerminalBinary(connId, clear)
+ if (!clientFrame) return false
+ const packet = encodeTerminalHop(TerminalHopDirection.up, connId, clientFrame)
+ if (!packet || !this.ws || this.ws.readyState !== WebSocket.OPEN) return false
+ try { this.ws.send(packet); return true } catch { return false }
+ }
+
/** Send a user-level notification to every logged-in browser that owns this machine. */
sendUser(frame: Frame): void {
this.enqueue({ t: 'up', userEligible: true, webEligible: false, frame })
@@ -544,6 +565,24 @@ export class BackendSocket {
this.downChains.set(key, next)
}
+ private enqueueTerminalBinary(connId: string, raw: Uint8Array): void {
+ const key = connId || '__backend__'
+ const previous = this.downChains.get(key) ?? Promise.resolve()
+ const next = previous
+ .catch(() => { /* prior failure is already logged */ })
+ .then(async () => {
+ const clear = this.e2ee.unwrapTerminalBinary(connId, raw)
+ if (clear) await this.terminalStreams?.handleBinary(connId, clear)
+ })
+ .catch((err) => {
+ console.error('[backend] binary terminal dispatch failed:', err instanceof Error ? err.message : err)
+ })
+ .finally(() => {
+ if (this.downChains.get(key) === next) this.downChains.delete(key)
+ })
+ this.downChains.set(key, next)
+ }
+
private drainQueue(): void {
if (this.draining || !this.queue.length) return
const ws = this.ws
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 3119f7fe2..c787b5a57 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -771,6 +771,7 @@ async function runForeground(token: string): Promise<void> {
terminals,
resolveAgent: (agentId) => registry.resolve(agentId),
sendTarget: (connId, type, payload) => backend.sendTerminalTo(connId, type, payload),
+ sendBinaryTarget: (connId, frame) => backend.sendTerminalBinaryTo(connId, frame),
streamingAvailable: tmuxBackend != null,
})
backend.setTerminalStreamManager(terminalStreams)
diff --git a/cli/src/lib/e2ee/manager.ts b/cli/src/lib/e2ee/manager.ts
index 067a6665c..49ca254fd 100644
--- a/cli/src/lib/e2ee/manager.ts
+++ b/cli/src/lib/e2ee/manager.ts
@@ -11,6 +11,13 @@
* The relay never sees plaintext user content: only ciphertext envelopes + public PAKE messages.
*/
import * as C from './core.js'
+import {
+ deriveTerminalBinaryKey,
+ openTerminalBinary,
+ parseTerminalBinaryEnvelope,
+ sealTerminalBinary,
+ type TerminalBinaryClear,
+} from '../terminalBinary.js'
import { E2eeStore } from './store.js'
type Frame = Record<string, unknown>
@@ -53,6 +60,10 @@ interface Session {
s2c: Uint8Array // adapter → web (welcome + targeted RPC replies)
s2cCounter: number // next send counter (0 was the welcome)
c2sRecv: number // highest counter seen (replay guard)
+ terminalC2s: Uint8Array
+ terminalS2c: Uint8Array
+ terminalS2cCounter: number
+ terminalC2sRecv: number
}
const PAIR_TTL_MS = 60_000
@@ -257,6 +268,29 @@ export class E2eeManager {
return { type, payload: wrapped }
}
+ /** Pairwise-encrypt binary terminal data in a domain-separated counter space. */
+ wrapTerminalBinary(connId: string, clear: TerminalBinaryClear): Uint8Array | null {
+ const session = this.sessions.get(connId)
+ if (!session) return null
+ const sealed = sealTerminalBinary(session.terminalS2c, session.terminalS2cCounter, clear)
+ if (!sealed) return null
+ session.terminalS2cCounter++
+ return sealed
+ }
+
+ /** Open one client→adapter binary terminal frame with the existing pairwise
+ * replay guard. Authenticated but stale/reordered frames are dropped. */
+ unwrapTerminalBinary(connId: string, raw: Uint8Array): TerminalBinaryClear | null {
+ const session = this.sessions.get(connId)
+ if (!session) return null
+ const envelope = parseTerminalBinaryEnvelope(raw)
+ if (!envelope || (session.terminalC2sRecv !== -1 && envelope.counter <= session.terminalC2sRecv)) return null
+ const opened = openTerminalBinary(session.terminalC2s, raw)
+ if (!opened) return null
+ session.terminalC2sRecv = opened.counter
+ return opened.frame
+ }
+
// ── inbound down `message` decryption ────────────────────────────────────────────────────────────
/** Decrypt an encrypted down `message`; plaintext passes through; undecryptable → null (drop). */
@@ -518,7 +552,18 @@ export class E2eeManager {
return true
}
this.evictIfFull()
- this.sessions.set(connId, { webIdentityPub: identityPub, role, c2s: keys.c2s, s2c: keys.s2c, s2cCounter: 1, c2sRecv: -1 })
+ this.sessions.set(connId, {
+ webIdentityPub: identityPub,
+ role,
+ c2s: keys.c2s,
+ s2c: keys.s2c,
+ s2cCounter: 1,
+ c2sRecv: -1,
+ terminalC2s: deriveTerminalBinaryKey(keys.c2s),
+ terminalS2c: deriveTerminalBinaryKey(keys.s2c),
+ terminalS2cCounter: 0,
+ terminalC2sRecv: -1,
+ })
const id = this.store.getIdentity()
const enc = C.aeadSeal(keys.s2c, 0, C.utf8('e2e-welcome'), C.utf8(JSON.stringify({ groupKey: C.b64e(this.groupKey), epoch: this.epoch })))
this.deps.sendTo(connId, {
diff --git a/cli/src/lib/terminalBinary.spec.ts b/cli/src/lib/terminalBinary.spec.ts
new file mode 100644
index 000000000..4fa2c64f7
--- /dev/null
+++ b/cli/src/lib/terminalBinary.spec.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest'
+import {
+ deriveTerminalBinaryKey,
+ openTerminalBinary,
+ parseTerminalBinaryEnvelope,
+ sealTerminalBinary,
+ TerminalBinaryKind,
+} from './terminalBinary.js'
+
+const key = Uint8Array.from({ length: 32 }, (_, index) => index)
+const streamId = '00112233-4455-6677-8899-aabbccddeeff'
+
+describe('terminal binary protocol v2', () => {
+ it('derives the cross-platform terminal key in its own nonce domain', () => {
+ expect(Buffer.from(deriveTerminalBinaryKey(key)).toString('hex')).toBe(
+ '319355ec420991f1458c3a0fb5e4b38a6475f227ec166cd8754e721ab827a733',
+ )
+ })
+
+ it('round-trips raw input without JSON or base64', () => {
+ const sealed = sealTerminalBinary(key, 7, {
+ kind: TerminalBinaryKind.input,
+ streamId,
+ seq: 3,
+ bytes: new TextEncoder().encode('xin chào\r'),
+ compressed: false,
+ })!
+ expect(Buffer.from(sealed.subarray(0, 4)).toString()).toBe('HTRM')
+ expect(openTerminalBinary(key, sealed)).toEqual({
+ counter: 7,
+ frame: {
+ kind: TerminalBinaryKind.input,
+ streamId,
+ seq: 3,
+ bytes: new TextEncoder().encode('xin chào\r'),
+ compressed: false,
+ },
+ })
+ })
+
+ it('round-trips a compressed keyframe with dimensions', () => {
+ const sealed = sealTerminalBinary(key, 9, {
+ kind: TerminalBinaryKind.keyframe,
+ streamId,
+ seq: 12,
+ cols: 144,
+ rows: 43,
+ bytes: Uint8Array.of(0x78, 0x9c, 0x03),
+ compressed: true,
+ })!
+ expect(openTerminalBinary(key, sealed)?.frame).toMatchObject({
+ kind: TerminalBinaryKind.keyframe,
+ streamId,
+ seq: 12,
+ cols: 144,
+ rows: 43,
+ compressed: true,
+ })
+ })
+
+ it('rejects tamper, truncation and unsupported flags', () => {
+ const sealed = sealTerminalBinary(key, 1, {
+ kind: TerminalBinaryKind.output,
+ streamId,
+ seq: 0,
+ bytes: Uint8Array.of(1, 2, 3),
+ compressed: false,
+ })!
+ const tampered = sealed.slice(); tampered[tampered.length - 1] ^= 1
+ expect(openTerminalBinary(key, tampered)).toBeNull()
+ expect(parseTerminalBinaryEnvelope(sealed.subarray(0, sealed.length - 1))).toBeNull()
+ const badFlags = sealed.slice(); badFlags[6] = 0x80
+ expect(openTerminalBinary(key, badFlags)).toBeNull()
+ })
+})
diff --git a/cli/src/lib/terminalBinary.ts b/cli/src/lib/terminalBinary.ts
new file mode 100644
index 000000000..89d5ffef9
--- /dev/null
+++ b/cli/src/lib/terminalBinary.ts
@@ -0,0 +1,190 @@
+import { aeadOpen, aeadSeal, utf8 } from './e2ee/core.js'
+import { hkdf } from '@noble/hashes/hkdf'
+import { sha256 } from '@noble/hashes/sha2'
+
+export const TERMINAL_BINARY_VERSION = 2
+export const TERMINAL_BINARY_HEADER_BYTES = 20
+export const TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES = 512 * 1024
+export const TERMINAL_HOP_HEADER_BYTES = 24
+
+export const enum TerminalBinaryKind {
+ input = 1,
+ output = 2,
+ keyframe = 3,
+}
+
+export interface TerminalBinaryClear {
+ kind: TerminalBinaryKind
+ streamId: string
+ seq: number
+ bytes: Uint8Array
+ compressed: boolean
+ cols?: number
+ rows?: number
+}
+
+export interface TerminalBinaryEnvelope {
+ kind: TerminalBinaryKind
+ flags: number
+ counter: number
+ ciphertext: Uint8Array
+ aad: Uint8Array
+}
+
+const MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x4d) // HTRM
+const HOP_MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x48) // HTRH
+const FLAG_ZLIB = 1
+const TERMINAL_KEY_INFO = utf8('harness-terminal-binary-v2')
+
+/** Keep binary terminal nonces independent from JSON control-frame nonces. */
+export function deriveTerminalBinaryKey(sessionKey: Uint8Array): Uint8Array {
+ return hkdf(sha256, sessionKey, new Uint8Array(), TERMINAL_KEY_INFO, 32)
+}
+
+function safeU64(view: DataView, offset: number): number | null {
+ const value = view.getBigUint64(offset, false)
+ return value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : null
+}
+
+function uuidBytes(id: string): Uint8Array | null {
+ const hex = id.replaceAll('-', '')
+ if (!/^[0-9a-fA-F]{32}$/.test(hex)) return null
+ return Uint8Array.from({ length: 16 }, (_, index) => Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16))
+}
+
+function uuidString(bytes: Uint8Array): string {
+ const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+function validKind(value: number): value is TerminalBinaryKind {
+ return value === TerminalBinaryKind.input || value === TerminalBinaryKind.output || value === TerminalBinaryKind.keyframe
+}
+
+export function terminalBinaryType(kind: TerminalBinaryKind): string {
+ if (kind === TerminalBinaryKind.input) return 'terminal_input'
+ if (kind === TerminalBinaryKind.output) return 'terminal_output'
+ return 'terminal_keyframe'
+}
+
+export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | null {
+ const id = uuidBytes(frame.streamId)
+ if (!id || !Number.isSafeInteger(frame.seq) || frame.seq < 0) return null
+ if (frame.kind === TerminalBinaryKind.input && frame.compressed) return null
+ const metaBytes = frame.kind === TerminalBinaryKind.keyframe ? 28 : 24
+ const out = new Uint8Array(metaBytes + frame.bytes.length)
+ out.set(id, 0)
+ const view = new DataView(out.buffer)
+ view.setBigUint64(16, BigInt(frame.seq), false)
+ if (frame.kind === TerminalBinaryKind.keyframe) {
+ if (!Number.isSafeInteger(frame.cols) || !Number.isSafeInteger(frame.rows)
+ || frame.cols! < 1 || frame.cols! > 0xffff || frame.rows! < 1 || frame.rows! > 0xffff) return null
+ view.setUint16(24, frame.cols!, false)
+ view.setUint16(26, frame.rows!, false)
+ }
+ out.set(frame.bytes, metaBytes)
+ return out
+}
+
+export function decodeTerminalPlain(kind: TerminalBinaryKind, flags: number, plaintext: Uint8Array): TerminalBinaryClear | null {
+ if ((flags & ~FLAG_ZLIB) !== 0 || (kind === TerminalBinaryKind.input && flags !== 0)) return null
+ const metaBytes = kind === TerminalBinaryKind.keyframe ? 28 : 24
+ if (plaintext.length < metaBytes) return null
+ const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength)
+ const seq = safeU64(view, 16)
+ if (seq == null) return null
+ return {
+ kind,
+ streamId: uuidString(plaintext.subarray(0, 16)),
+ seq,
+ bytes: plaintext.slice(metaBytes),
+ compressed: (flags & FLAG_ZLIB) !== 0,
+ ...(kind === TerminalBinaryKind.keyframe ? { cols: view.getUint16(24, false), rows: view.getUint16(26, false) } : {}),
+ }
+}
+
+export function parseTerminalBinaryEnvelope(raw: Uint8Array): TerminalBinaryEnvelope | null {
+ const bytes = Uint8Array.from(raw)
+ if (bytes.length < TERMINAL_BINARY_HEADER_BYTES + 16) return null
+ for (let i = 0; i < MAGIC.length; i++) if (bytes[i] !== MAGIC[i]) return null
+ if (bytes[4] !== TERMINAL_BINARY_VERSION || !validKind(bytes[5]) || bytes[7] !== 0) return null
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+ const counter = safeU64(view, 8)
+ const length = view.getUint32(16, false)
+ if (counter == null || length < 16 || length > TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES
+ || bytes.length !== TERMINAL_BINARY_HEADER_BYTES + length) return null
+ return {
+ kind: bytes[5],
+ flags: bytes[6],
+ counter,
+ ciphertext: bytes.slice(TERMINAL_BINARY_HEADER_BYTES),
+ aad: bytes.slice(0, 16),
+ }
+}
+
+export function sealTerminalBinary(key: Uint8Array, counter: number, frame: TerminalBinaryClear): Uint8Array | null {
+ if (!Number.isSafeInteger(counter) || counter < 0) return null
+ const plaintext = encodeTerminalPlain(frame)
+ if (!plaintext) return null
+ const flags = frame.compressed ? FLAG_ZLIB : 0
+ const header = new Uint8Array(TERMINAL_BINARY_HEADER_BYTES)
+ header.set(MAGIC, 0)
+ header[4] = TERMINAL_BINARY_VERSION
+ header[5] = frame.kind
+ header[6] = flags
+ const view = new DataView(header.buffer)
+ view.setBigUint64(8, BigInt(counter), false)
+ const ciphertext = aeadSeal(key, counter, header.subarray(0, 16), plaintext)
+ if (ciphertext.length > TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES) return null
+ view.setUint32(16, ciphertext.length, false)
+ const out = new Uint8Array(header.length + ciphertext.length)
+ out.set(header)
+ out.set(ciphertext, header.length)
+ return out
+}
+
+export function openTerminalBinary(key: Uint8Array, raw: Uint8Array): { counter: number; frame: TerminalBinaryClear } | null {
+ const envelope = parseTerminalBinaryEnvelope(raw)
+ if (!envelope) return null
+ const plaintext = aeadOpen(key, envelope.counter, envelope.aad, envelope.ciphertext)
+ if (!plaintext) return null
+ const frame = decodeTerminalPlain(envelope.kind, envelope.flags, plaintext)
+ return frame ? { counter: envelope.counter, frame } : null
+}
+
+export const enum TerminalHopDirection {
+ down = 1,
+ up = 2,
+}
+
+export function encodeTerminalHop(direction: TerminalHopDirection, connId: string, clientFrame: Uint8Array): Uint8Array | null {
+ const id = uuidBytes(connId)
+ if (!id || (direction !== TerminalHopDirection.down && direction !== TerminalHopDirection.up)) return null
+ const out = new Uint8Array(TERMINAL_HOP_HEADER_BYTES + clientFrame.length)
+ out.set(HOP_MAGIC, 0)
+ out[4] = TERMINAL_BINARY_VERSION
+ out[5] = direction
+ out.set(id, 8)
+ out.set(clientFrame, TERMINAL_HOP_HEADER_BYTES)
+ return out
+}
+
+export function decodeTerminalHop(raw: Uint8Array): { direction: TerminalHopDirection; connId: string; clientFrame: Uint8Array } | null {
+ const bytes = Uint8Array.from(raw)
+ if (bytes.length < TERMINAL_HOP_HEADER_BYTES + TERMINAL_BINARY_HEADER_BYTES + 16) return null
+ for (let index = 0; index < HOP_MAGIC.length; index++) if (bytes[index] !== HOP_MAGIC[index]) return null
+ if (bytes[4] !== TERMINAL_BINARY_VERSION || bytes[6] !== 0 || bytes[7] !== 0
+ || (bytes[5] !== TerminalHopDirection.down && bytes[5] !== TerminalHopDirection.up)) return null
+ const clientFrame = bytes.slice(TERMINAL_HOP_HEADER_BYTES)
+ if (!parseTerminalBinaryEnvelope(clientFrame)) return null
+ return {
+ direction: bytes[5],
+ connId: uuidString(bytes.subarray(8, 24)),
+ clientFrame,
+ }
+}
+
+/** Stable bytes used by cross-language golden tests and protocol diagnostics. */
+export function terminalBinaryAadLabel(kind: TerminalBinaryKind): Uint8Array {
+ return utf8(`HTRM|${TERMINAL_BINARY_VERSION}|${terminalBinaryType(kind)}`)
+}
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 9b0d712e7..7ed689e52 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -4,6 +4,7 @@ import type { RegisteredSession } from './registry.js'
import { TerminalStreamManager, terminalEngineCapabilities } from './terminalStreamManager.js'
import { TERMINAL_ACTION_SUCCEEDED, type TerminalStreamHandle, type TerminalStreamSink } from './terminalTypes.js'
import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
+import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'
class FakeStream implements TerminalStreamHandle {
readonly runtime = { backend: 'tmux' as const, paneId: '%1' }
@@ -13,14 +14,20 @@ class FakeStream implements TerminalStreamHandle {
snapshots = 0
snapshotHistory: number[] = []
snapshotBytes = Buffer.from('\u001bcfixture')
+ onSnapshot: ((count: number) => void) | null = null
+ pauses = 0
+ resumes = 0
async snapshot(historyLines: number): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {
this.snapshots++
this.snapshotHistory.push(historyLines)
+ this.onSnapshot?.(this.snapshots)
return { state: 'succeeded', value: { bytes: this.snapshotBytes, cols: 120, rows: 40 } }
}
async writeRaw(bytes: Uint8Array) { this.writes.push(bytes); return TERMINAL_ACTION_SUCCEEDED }
async resize(size: { cols: number; rows: number }) { this.sizes.push(size); return TERMINAL_ACTION_SUCCEEDED }
+ async pauseOutput() { this.pauses++; return TERMINAL_ACTION_SUCCEEDED }
+ async resumeOutput() { this.resumes++; return TERMINAL_ACTION_SUCCEEDED }
async close(): Promise<void> { this.closed = true }
}
@@ -36,18 +43,23 @@ describe('TerminalStreamManager', () => {
let sink: TerminalStreamSink | null
let stream: FakeStream
let sent: Array<{ connId: string; type: string; payload: Record<string, unknown> }>
+ let binarySent: Array<{ connId: string; frame: TerminalBinaryClear }>
let manager: TerminalStreamManager
let agents: Map<string, RegisteredSession>
+ let outputBeforeOpen: Uint8Array | null
beforeEach(() => {
vi.useFakeTimers()
sink = null
stream = new FakeStream()
sent = []
+ binarySent = []
+ outputBeforeOpen = null
agents = new Map([['agent-1', session()]])
const terminals = {
openStream: async (_session: RegisteredSession, _size: unknown, nextSink: TerminalStreamSink) => {
sink = nextSink
+ if (outputBeforeOpen) nextSink.onData(outputBeforeOpen)
return { state: 'succeeded' as const, value: stream }
},
} as unknown as TerminalBackendCoordinator
@@ -55,6 +67,7 @@ describe('TerminalStreamManager', () => {
terminals,
resolveAgent: (id) => agents.get(id),
sendTarget: (connId, type, payload) => { sent.push({ connId, type, payload }); return true },
+ sendBinaryTarget: (connId, frame) => { binarySent.push({ connId, frame }); return true },
streamingAvailable: true,
now: () => Date.now(),
})
@@ -77,7 +90,7 @@ describe('TerminalStreamManager', () => {
const agentId = `agent-generic-${index}`
agents.set(agentId, session(engine, agentId))
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: `open-${index}`, protocolVersion: 1, agentId, cols: 100, rows: 30,
+ requestId: `open-${index}`, protocolVersion: 2, agentId, cols: 100, rows: 30,
})
const ready = sent.findLast((frame) => frame.type === 'terminal_ready')
expect(ready?.payload.agentId).toBe(agentId)
@@ -95,43 +108,44 @@ describe('TerminalStreamManager', () => {
unsafe.engine = 'hostile-unregistered-engine'
agents.set('agent-1', unsafe as unknown as RegisteredSession)
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'unsupported', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'unsupported', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
expect(sent.at(-1)?.payload.code).toBe('TERMINAL_ENGINE_UNSUPPORTED')
})
it('rejects an unknown agent without opening a stream', async () => {
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'missing', protocolVersion: 1, agentId: 'does-not-exist', cols: 100, rows: 30,
+ requestId: 'missing', protocolVersion: 2, agentId: 'does-not-exist', cols: 100, rows: 30,
})
expect(sent.at(-1)?.payload.code).toBe('TERMINAL_AGENT_NOT_FOUND')
})
it('opens with a keyframe, streams coalesced output, and writes ordered raw input', async () => {
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'open-1', protocolVersion: 1, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],
+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],
})
- expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready', 'terminal_keyframe'])
+ expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])
+ expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])
const streamId = sent[0].payload.streamId as string
sink!.onData(Buffer.from('hello'))
await vi.advanceTimersByTimeAsync(8)
- expect(sent.at(-1)?.type).toBe('terminal_output')
- expect(sent.at(-1)?.payload.seq).toBe(1)
+ expect(binarySent.at(-1)?.frame.kind).toBe(TerminalBinaryKind.output)
+ expect(binarySent.at(-1)?.frame.seq).toBe(1)
- await manager.handleFrame('web-1', 'terminal_input', {
- streamId, inputSeq: 0, data: Buffer.from('abc').toString('base64'),
+ await manager.handleBinary('web-1', {
+ kind: TerminalBinaryKind.input, streamId, seq: 0, compressed: false, bytes: Buffer.from('abc'),
})
expect(Buffer.from(stream.writes[0]).toString()).toBe('abc')
- await manager.handleFrame('web-1', 'terminal_input', {
- streamId, inputSeq: 2, data: Buffer.from('out-of-order').toString('base64'),
+ await manager.handleBinary('web-1', {
+ kind: TerminalBinaryKind.input, streamId, seq: 2, compressed: false, bytes: Buffer.from('out-of-order'),
})
expect(stream.writes).toHaveLength(1)
expect(sent.at(-1)?.payload.code).toBe('TERMINAL_INPUT_INVALID')
const mouse = Buffer.from('\u001b[<0;12;8M')
- await manager.handleFrame('web-1', 'terminal_input', {
- streamId, inputSeq: 1, data: mouse.toString('base64'),
+ await manager.handleBinary('web-1', {
+ kind: TerminalBinaryKind.input, streamId, seq: 1, compressed: false, bytes: mouse,
})
expect(Buffer.from(stream.writes.at(-1)!).equals(mouse)).toBe(true)
@@ -141,12 +155,43 @@ describe('TerminalStreamManager', () => {
expect(stream.sizes.at(-1)).toEqual({ cols: 140, rows: 50 })
})
+ it('does not replay pre-snapshot repaint bytes after the authoritative keyframe', async () => {
+ outputBeforeOpen = Buffer.from('\u001b[2Jstale repaint')
+ stream.snapshotBytes = Buffer.from('\u001bcnew prompt text')
+
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-snapshot', protocolVersion: 2, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ await vi.advanceTimersByTimeAsync(20)
+
+ expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])
+ expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])
+ expect(binarySent[0].frame.seq).toBe(0)
+ })
+
+ it('recaptures and discards a TUI repaint that arrives during snapshot', async () => {
+ stream.snapshotBytes = Buffer.from('\u001bcnew prompt text')
+ stream.onSnapshot = (count) => {
+ if (count === 1) sink!.onData(Buffer.from('\u001b[2Jin-flight stale repaint'))
+ }
+
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-racing-snapshot', protocolVersion: 2, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ await vi.advanceTimersByTimeAsync(20)
+
+ expect(stream.snapshots).toBe(2)
+ expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])
+ expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])
+ expect(binarySent[0].frame.seq).toBe(0)
+ })
+
it('rejects a second controller and expires the first lease after heartbeat timeout', async () => {
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'open-1', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
await manager.handleFrame('web-2', 'terminal_open', {
- requestId: 'open-2', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'open-2', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
expect(sent.at(-1)?.payload.code).toBe('CONTROL_LEASE_HELD')
@@ -158,45 +203,70 @@ describe('TerminalStreamManager', () => {
it('rejects a second agent alias that resolves to the same tmux pane', async () => {
agents.set('agent-alias', session('claude', 'agent-alias'))
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'open-1', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
await manager.handleFrame('web-2', 'terminal_open', {
- requestId: 'open-2', protocolVersion: 1, agentId: 'agent-alias', cols: 100, rows: 30,
+ requestId: 'open-2', protocolVersion: 2, agentId: 'agent-alias', cols: 100, rows: 30,
})
expect(sent.at(-1)?.payload.code).toBe('CONTROL_LEASE_HELD')
})
it('uses frequent ACKs rather than the five-second heartbeat for output backpressure', async () => {
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'open-1', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
const streamId = sent[0].payload.streamId as string
+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })
for (let i = 0; i < 40; i++) {
sink!.onData(Buffer.alloc(32 * 1024, i))
- const output = sent.at(-1)!
- expect(output.type).toBe('terminal_output')
- await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: output.payload.seq })
+ const output = binarySent.at(-1)!.frame
+ expect(output.kind).toBe(TerminalBinaryKind.output)
+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: output.seq })
}
- expect(sent.filter((frame) => frame.type === 'terminal_keyframe')).toHaveLength(1)
+ expect(binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toHaveLength(1)
+ expect(stream.pauses).toBe(0)
})
- it('bounds unacked output by replacing the backlog with a keyframe', async () => {
+ it('pauses PTY output above the high watermark and resumes below the low watermark', async () => {
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'open-1', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
- for (let i = 0; i < 33; i++) sink!.onData(Buffer.alloc(32 * 1024, i))
+ const streamId = sent[0].payload.streamId as string
+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })
+ for (let i = 0; i < 13; i++) sink!.onData(Buffer.alloc(32 * 1024, i))
+ await vi.advanceTimersByTimeAsync(1)
+ expect(stream.pauses).toBe(1)
+ expect(stream.resumes).toBe(0)
+ const outputs = binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.output)
+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: outputs[9].frame.seq })
await vi.advanceTimersByTimeAsync(1)
- expect(stream.snapshots).toBeGreaterThanOrEqual(2)
- expect(sent.filter((frame) => frame.type === 'terminal_keyframe').length).toBeGreaterThanOrEqual(2)
+ expect(stream.resumes).toBe(1)
+ expect(binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toHaveLength(1)
+ })
+
+ it('closes a stream whose renderer stays stalled after tmux is paused', async () => {
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-stall', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
+ })
+ const streamId = sent[0].payload.streamId as string
+ await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })
+ for (let i = 0; i < 13; i++) sink!.onData(Buffer.alloc(32 * 1024, i))
+ expect(stream.pauses).toBe(1)
+
+ await vi.advanceTimersByTimeAsync(10_000)
+
+ expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code)
+ .toBe('TERMINAL_RENDER_STALLED')
+ expect(stream.closed).toBe(true)
})
- it('fails closed instead of emitting an oversized doubly-base64 keyframe', async () => {
- stream.snapshotBytes = Buffer.alloc(241 * 1024, 0x61)
+ it('fails closed instead of emitting an oversized binary keyframe', async () => {
+ stream.snapshotBytes = Buffer.alloc(481 * 1024, 0x61)
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'oversized', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'oversized', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
expect(stream.snapshotHistory).toEqual([1_000, 500, 250, 100, 0])
- expect(sent.some((frame) => frame.type === 'terminal_keyframe')).toBe(false)
+ expect(binarySent.some(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toBe(false)
expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code)
.toBe('TERMINAL_SNAPSHOT_TOO_LARGE')
expect(stream.closed).toBe(true)
@@ -204,15 +274,16 @@ describe('TerminalStreamManager', () => {
it('disconnect cleanup closes the stream and releases the controller', async () => {
await manager.handleFrame('web-1', 'terminal_open', {
- requestId: 'open-1', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'open-1', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
await manager.closeConnection('web-1')
expect(stream.closed).toBe(true)
const replacement = new FakeStream()
stream = replacement
await manager.handleFrame('web-2', 'terminal_open', {
- requestId: 'open-2', protocolVersion: 1, agentId: 'agent-1', cols: 100, rows: 30,
+ requestId: 'open-2', protocolVersion: 2, agentId: 'agent-1', cols: 100, rows: 30,
})
- expect(sent.at(-2)?.type).toBe('terminal_ready')
+ expect(sent.at(-1)?.type).toBe('terminal_ready')
+ expect(binarySent.at(-1)?.frame.kind).toBe(TerminalBinaryKind.keyframe)
})
})
diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.ts
index 61b44c1f1..91a2d72f4 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -5,21 +5,21 @@ import type { RegisteredSession } from './registry.js'
import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
import { terminalPlacementKey, terminalRouteKey } from './terminalRuntime.js'
import type { TerminalStreamHandle, TerminalStreamSize } from './terminalTypes.js'
+import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'
type FramePayload = Record<string, unknown>
-const PROTOCOL_VERSION = 1
+const PROTOCOL_VERSION = 2
const HEARTBEAT_TIMEOUT_MS = 30_000
const OUTPUT_FLUSH_MS = 8
const OUTPUT_CHUNK_BYTES = 32 * 1024
const INPUT_MAX_BYTES = 64 * 1024
-const MAX_UNACKED_FRAMES = 256
-const MAX_UNACKED_BYTES = 1024 * 1024
-// Terminal data is base64 inside the clear payload, then the entire E2EE
-// ciphertext is base64 again. Keep enough headroom below Backend's 512 KiB
-// outer-envelope limit for both JSON layers, AEAD tag and routing fields.
-const KEYFRAME_MAX_BYTES = 240 * 1024
+const PAUSE_HIGH_WATERMARK_BYTES = 384 * 1024
+const RESUME_LOW_WATERMARK_BYTES = 128 * 1024
+const RENDER_STALL_TIMEOUT_MS = 10_000
+const KEYFRAME_MAX_BYTES = 480 * 1024
const KEYFRAME_HISTORY_ATTEMPTS = [1_000, 500, 250, 100, 0] as const
+const KEYFRAME_SETTLE_ATTEMPTS = 3
const TERMINAL_ENGINES: ReadonlySet<string> = new Set(ENGINES)
interface PendingOutput {
@@ -47,12 +47,15 @@ interface ActiveStream {
snapshotting: boolean
resyncing: boolean
closing: boolean
+ outputPaused: boolean
+ stallTimer: ReturnType<typeof setTimeout> | null
}
export interface TerminalStreamManagerDeps {
terminals: TerminalBackendCoordinator
resolveAgent: (agentId: string) => RegisteredSession | undefined
sendTarget: (connId: string, type: string, payload: FramePayload) => boolean
+ sendBinaryTarget: (connId: string, frame: TerminalBinaryClear) => boolean
streamingAvailable: boolean
now?: () => number
}
@@ -64,19 +67,13 @@ function sizeFrom(payload: FramePayload): TerminalStreamSize | null {
return { cols, rows }
}
-function strictBase64(raw: unknown): Buffer | null {
- if (typeof raw !== 'string' || raw.length === 0 || raw.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(raw)) return null
- const bytes = Buffer.from(raw, 'base64')
- return bytes.toString('base64') === raw ? bytes : null
-}
-
-function encoded(bytes: Uint8Array, compression: 'none' | 'zlib'): { encoding: 'none' | 'zlib'; data: string; plainBytes: number } {
+function encoded(bytes: Uint8Array, compression: 'none' | 'zlib'): { compressed: boolean; bytes: Uint8Array; plainBytes: number } {
const raw = Buffer.from(bytes)
if (compression === 'zlib' && raw.length > 1024) {
const compressed = deflateSync(raw, { level: 1 })
- if (compressed.length < raw.length) return { encoding: 'zlib', data: compressed.toString('base64'), plainBytes: raw.length }
+ if (compressed.length < raw.length) return { compressed: true, bytes: compressed, plainBytes: raw.length }
}
- return { encoding: 'none', data: raw.toString('base64'), plainBytes: raw.length }
+ return { compressed: false, bytes: raw, plainBytes: raw.length }
}
export function terminalEngineCapabilities(
@@ -118,7 +115,7 @@ export class TerminalStreamManager {
this.ack(connId, payload)
return true
case 'terminal_input':
- await this.input(connId, payload)
+ this.sendError(connId, 'TERMINAL_BINARY_REQUIRED', { streamId: typeof payload.streamId === 'string' ? payload.streamId : undefined })
return true
case 'terminal_resize':
await this.resize(connId, payload)
@@ -134,6 +131,13 @@ export class TerminalStreamManager {
}
}
+ async handleBinary(connId: string, frame: TerminalBinaryClear): Promise<void> {
+ if (frame.kind !== TerminalBinaryKind.input) return
+ const state = this.streams.get(frame.streamId)
+ if (!state || state.connId !== connId || state.closing) return
+ await this.input(state, frame.seq, frame.bytes)
+ }
+
private capabilities(connId: string, requestId: unknown): void {
this.deps.sendTarget(connId, 'terminal_capabilities_result', {
requestId,
@@ -268,6 +272,8 @@ export class TerminalStreamManager {
snapshotting: false,
resyncing: false,
closing: false,
+ outputPaused: false,
+ stallTimer: null,
}
this.streams.set(streamId, state)
if (!this.deps.sendTarget(connId, 'terminal_ready', {
@@ -301,25 +307,26 @@ export class TerminalStreamManager {
if (!state) return
const lastSeq = Number(payload.lastSeq)
if (!Number.isSafeInteger(lastSeq) || lastSeq < -1 || lastSeq >= state.nextSeq) return
+ let progressed = false
while (state.pending.length && state.pending[0].seq <= lastSeq) {
state.pendingBytes -= state.pending.shift()!.bytes
+ progressed = true
}
+ if (!progressed) return
+ if (state.outputPaused && state.pendingBytes < RESUME_LOW_WATERMARK_BYTES) void this.resumeOutput(state)
+ else if (state.outputPaused) this.armStallTimer(state)
}
- private async input(connId: string, payload: FramePayload): Promise<void> {
- const state = this.streamFor(connId, payload)
- if (!state) return
- const inputSeq = Number(payload.inputSeq)
- const bytes = strictBase64(payload.data)
- if (!Number.isSafeInteger(inputSeq) || inputSeq !== state.lastInputSeq + 1 || !bytes || bytes.length > INPUT_MAX_BYTES) {
- this.sendError(connId, 'TERMINAL_INPUT_INVALID', { streamId: state.streamId })
+ private async input(state: ActiveStream, inputSeq: number, bytes: Uint8Array): Promise<void> {
+ if (!Number.isSafeInteger(inputSeq) || inputSeq !== state.lastInputSeq + 1 || bytes.length === 0 || bytes.length > INPUT_MAX_BYTES) {
+ this.sendError(state.connId, 'TERMINAL_INPUT_INVALID', { streamId: state.streamId })
return
}
state.lastInputSeq = inputSeq
state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
const result = await state.handle.writeRaw(bytes)
if (result.state !== 'succeeded') {
- this.sendError(connId, 'TERMINAL_INPUT_FAILED', { streamId: state.streamId, message: result.reason })
+ this.sendError(state.connId, 'TERMINAL_INPUT_FAILED', { streamId: state.streamId, message: result.reason })
if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state)
}
}
@@ -354,7 +361,7 @@ export class TerminalStreamManager {
if (state.closing || bytes.length === 0) return
state.output.push(Buffer.from(bytes))
state.outputBytes += bytes.length
- if (state.snapshotting) return
+ if (state.snapshotting || state.outputPaused) return
if (state.outputBytes >= OUTPUT_CHUNK_BYTES) {
this.flushOutput(state)
return
@@ -372,12 +379,12 @@ export class TerminalStreamManager {
const chunk = all.subarray(offset, offset + OUTPUT_CHUNK_BYTES)
const seq = state.nextSeq++
const body = encoded(chunk, state.compression)
- if (!this.deps.sendTarget(state.connId, 'terminal_output', {
- protocolVersion: PROTOCOL_VERSION,
+ if (!this.deps.sendBinaryTarget(state.connId, {
+ kind: TerminalBinaryKind.output,
streamId: state.streamId,
seq,
- encoding: body.encoding,
- data: body.data,
+ compressed: body.compressed,
+ bytes: body.bytes,
})) {
void this.closeStream(state, 'backend disconnected', false)
return
@@ -385,22 +392,79 @@ export class TerminalStreamManager {
state.pending.push({ seq, bytes: body.plainBytes })
state.pendingBytes += body.plainBytes
}
- if ((state.pending.length > MAX_UNACKED_FRAMES || state.pendingBytes > MAX_UNACKED_BYTES) && !state.resyncing) {
- void this.sendKeyframe(state)
+ if (state.pendingBytes > PAUSE_HIGH_WATERMARK_BYTES && !state.outputPaused) void this.pauseOutput(state)
+ }
+
+ private armStallTimer(state: ActiveStream): void {
+ if (state.stallTimer) clearTimeout(state.stallTimer)
+ state.stallTimer = setTimeout(() => {
+ state.stallTimer = null
+ if (!state.closing && state.outputPaused) {
+ this.sendError(state.connId, 'TERMINAL_RENDER_STALLED', { streamId: state.streamId })
+ void this.closeStream(state, 'renderer did not acknowledge terminal output', true)
+ }
+ }, RENDER_STALL_TIMEOUT_MS)
+ }
+
+ private async pauseOutput(state: ActiveStream): Promise<void> {
+ if (state.closing || state.outputPaused) return
+ state.outputPaused = true
+ const result = await state.handle.pauseOutput()
+ if (result.state !== 'succeeded') {
+ this.sendError(state.connId, 'TERMINAL_BACKPRESSURE_FAILED', { streamId: state.streamId, message: result.reason })
+ await this.closeStream(state, result.reason, true)
+ return
+ }
+ this.armStallTimer(state)
+ }
+
+ private async resumeOutput(state: ActiveStream): Promise<void> {
+ if (state.closing || !state.outputPaused) return
+ state.outputPaused = false
+ if (state.stallTimer) clearTimeout(state.stallTimer)
+ state.stallTimer = null
+ const result = await state.handle.resumeOutput()
+ if (result.state !== 'succeeded') {
+ this.sendError(state.connId, 'TERMINAL_BACKPRESSURE_FAILED', { streamId: state.streamId, message: result.reason })
+ await this.closeStream(state, result.reason, true)
+ return
}
+ this.flushOutput(state)
}
private async sendKeyframe(state: ActiveStream): Promise<void> {
if (state.closing || state.resyncing) return
state.resyncing = true
state.snapshotting = true
+ if (state.outputPaused) {
+ state.outputPaused = false
+ if (state.stallTimer) clearTimeout(state.stallTimer)
+ state.stallTimer = null
+ await state.handle.resumeOutput().catch(() => ({ state: 'failed' as const, dispatch: 'not_started' as const, reason: 'resume failed' }))
+ }
if (state.flushTimer) { clearTimeout(state.flushTimer); state.flushTimer = null }
let snapshot: Awaited<ReturnType<TerminalStreamHandle['snapshot']>> = {
state: 'failed',
reason: 'tmux snapshot did not run',
}
for (const historyLines of KEYFRAME_HISTORY_ATTEMPTS) {
- snapshot = await state.handle.snapshot(historyLines)
+ for (let settleAttempt = 0; settleAttempt < KEYFRAME_SETTLE_ATTEMPTS; settleAttempt++) {
+ // A resize makes Codex/Claude repaint while capture-pane is running.
+ // Deltas queued before or during that capture are already reflected in
+ // the snapshot and must never be replayed after it: doing so erased the
+ // Codex prompt while leaving its background and cursor behind.
+ state.output = []
+ state.outputBytes = 0
+ snapshot = await state.handle.snapshot(historyLines)
+ const repaintedDuringCapture = state.outputBytes > 0
+ state.output = []
+ state.outputBytes = 0
+ if (snapshot.state !== 'succeeded'
+ || snapshot.value.bytes.length > KEYFRAME_MAX_BYTES
+ || !repaintedDuringCapture) break
+ // Capture again after the repaint so the keyframe contains its final
+ // state. Three attempts bound latency for continuously animated TUIs.
+ }
if (snapshot.state !== 'succeeded' || snapshot.value.bytes.length <= KEYFRAME_MAX_BYTES) break
}
if (snapshot.state !== 'succeeded') {
@@ -422,14 +486,14 @@ export class TerminalStreamManager {
state.pendingBytes = 0
const seq = state.nextSeq++
const body = encoded(bytes, state.compression)
- const sent = this.deps.sendTarget(state.connId, 'terminal_keyframe', {
- protocolVersion: PROTOCOL_VERSION,
+ const sent = this.deps.sendBinaryTarget(state.connId, {
+ kind: TerminalBinaryKind.keyframe,
streamId: state.streamId,
seq,
cols: snapshot.value.cols,
rows: snapshot.value.rows,
- encoding: body.encoding,
- data: body.data,
+ compressed: body.compressed,
+ bytes: body.bytes,
})
if (!sent) {
state.snapshotting = false
@@ -455,10 +519,13 @@ export class TerminalStreamManager {
if (state.closing) return
state.closing = true
if (state.flushTimer) clearTimeout(state.flushTimer)
+ if (state.stallTimer) clearTimeout(state.stallTimer)
state.flushTimer = null
+ state.stallTimer = null
this.streams.delete(state.streamId)
if (this.controllerByAgent.get(state.agentId) === state.connId) this.controllerByAgent.delete(state.agentId)
if (this.controllerByPlacement.get(state.placementKey) === state.connId) this.controllerByPlacement.delete(state.placementKey)
+ if (state.outputPaused) await state.handle.resumeOutput().catch(() => { /* best effort */ })
await state.handle.close().catch(() => { /* best effort */ })
if (notify) this.deps.sendTarget(state.connId, 'terminal_closed', {
protocolVersion: PROTOCOL_VERSION,
diff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.ts
index bcd8aefd3..57f1469e2 100644
--- a/cli/src/lib/terminalTypes.ts
+++ b/cli/src/lib/terminalTypes.ts
@@ -139,6 +139,8 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalR
snapshot(historyLines: number): Promise<TerminalReadResult<TerminalStreamSnapshot>>
writeRaw(bytes: Uint8Array): Promise<TerminalActionResult>
resize(size: TerminalStreamSize): Promise<TerminalActionResult>
+ pauseOutput(): Promise<TerminalActionResult>
+ resumeOutput(): Promise<TerminalActionResult>
close(): Promise<void>
}
diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.ts
index 8b5192cb9..8e8a455f3 100644
--- a/cli/src/lib/tmuxStream.real.spec.ts
+++ b/cli/src/lib/tmuxStream.real.spec.ts
@@ -6,6 +6,7 @@ import type { RegisteredSession } from './registry.js'
import { TerminalStreamManager } from './terminalStreamManager.js'
import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
import { TmuxControlStream } from './tmuxStream.js'
+import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'
const run = process.env.RUN_REAL_TMUX_STREAM === '1' ? describe : describe.skip
@@ -78,6 +79,7 @@ run('TmuxControlStream real tmux', () => {
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),
@@ -86,13 +88,14 @@ run('TmuxControlStream real tmux', () => {
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: 1,
+ protocolVersion: 2,
agentId,
cols: 90 + index,
rows: 24,
@@ -104,14 +107,16 @@ run('TmuxControlStream real tmux', () => {
expect(typeof streamId).toBe('string')
const marker = `HARNESS_ENGINE_STREAM_${engine.toUpperCase()}`
- await manager.handleFrame('matrix-client', 'terminal_input', {
- streamId,
- inputSeq: 0,
- data: Buffer.from(`printf '${marker}\\n'\r`).toString('base64'),
+ 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(() => frames.some((frame) => {
- if (frame.type !== 'terminal_output' || frame.payload.encoding !== 'none') return false
- return Buffer.from(String(frame.payload.data), 'base64').includes(Buffer.from(marker))
+ 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', {
diff --git a/cli/src/lib/tmuxStream.spec.ts b/cli/src/lib/tmuxStream.spec.ts
index 206455586..3315ea3c3 100644
--- a/cli/src/lib/tmuxStream.spec.ts
+++ b/cli/src/lib/tmuxStream.spec.ts
@@ -1,5 +1,9 @@
import { describe, expect, it } from 'vitest'
-import { decodeTmuxControlData } from './tmuxStream.js'
+import {
+ decodeTmuxControlData,
+ normalizeTmuxCaptureLines,
+ parseTmuxControlOutput,
+} from './tmuxStream.js'
describe('tmux control-mode output decoding', () => {
it('decodes octal bytes without corrupting adjacent UTF-8', () => {
@@ -10,4 +14,38 @@ describe('tmux control-mode output decoding', () => {
it('preserves ordinary backslashes that are not octal escapes', () => {
expect(Buffer.from(decodeTmuxControlData('C:\\Users\\name')).toString()).toBe('C:\\Users\\name')
})
+
+ it('preserves a UTF-8 scalar split across separate output records', () => {
+ const first = parseTmuxControlOutput(Buffer.concat([
+ Buffer.from('%output %7 '),
+ Buffer.from([0xe2, 0x94]),
+ ]))
+ const second = parseTmuxControlOutput(Buffer.concat([
+ Buffer.from('%output %7 '),
+ Buffer.from([0x80]),
+ ]))
+
+ expect(first?.paneId).toBe('%7')
+ expect(second?.paneId).toBe('%7')
+ expect(Buffer.concat([
+ Buffer.from(first!.data),
+ Buffer.from(second!.data),
+ ])).toEqual(Buffer.from('─'))
+ })
+})
+
+describe('tmux snapshot row normalization', () => {
+ it('turns capture-pane LF rows into VT CRLF and drops its final output delimiter', () => {
+ const capture = Buffer.from('first\n\u001b[31m世界\nlast\r\n')
+ expect(Buffer.from(normalizeTmuxCaptureLines(capture))).toEqual(
+ Buffer.from('first\u001b[0m\r\n\u001b[31m世界\u001b[0m\r\nlast\u001b[0m'),
+ )
+ })
+
+ it('stops a styled trailing background from bleeding into the next blank row', () => {
+ const capture = Buffer.from('\u001b[48;5;237mprompt \n\n\u001b[49mreply\n')
+ expect(Buffer.from(normalizeTmuxCaptureLines(capture)).toString()).toBe(
+ '\u001b[48;5;237mprompt \u001b[0m\r\n\u001b[0m\r\n\u001b[49mreply\u001b[0m',
+ )
+ })
})
diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.ts
index 1b324ced6..d30ac3df0 100644
--- a/cli/src/lib/tmuxStream.ts
+++ b/cli/src/lib/tmuxStream.ts
@@ -1,6 +1,5 @@
import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
import { randomUUID } from 'node:crypto'
-import { StringDecoder } from 'node:string_decoder'
import {
TERMINAL_ACTION_SUCCEEDED,
terminalActionNotStarted,
@@ -19,6 +18,7 @@ const MAX_COLS = 300
const MIN_ROWS = 12
const MAX_ROWS = 120
const SMALL_INPUT_BYTES = 4 * 1024
+const CONTROL_OUTPUT_SETTLE_MS = 24
interface PaneMeta {
sessionId: string
@@ -86,19 +86,54 @@ async function paneMeta(paneId: string): Promise<PaneMeta | null> {
/** Decode the octal escaping used by tmux control-mode `%output` notifications. */
export function decodeTmuxControlData(encoded: string): Uint8Array {
+ return decodeTmuxControlBytes(Buffer.from(encoded, 'utf8'))
+}
+
+/** Decode control-mode escaping without first interpreting payload bytes as
+ * UTF-8. A Unicode scalar may be split across separate `%output` records; a
+ * string decoder would permanently replace both halves with U+FFFD. */
+export function decodeTmuxControlBytes(encoded: Uint8Array): Uint8Array {
+ const input = Buffer.from(encoded)
const chunks: Buffer[] = []
let plainStart = 0
- for (let i = 0; i < encoded.length; i++) {
- if (encoded[i] !== '\\' || !/^[0-7]{3}$/.test(encoded.slice(i + 1, i + 4))) continue
- if (i > plainStart) chunks.push(Buffer.from(encoded.slice(plainStart, i), 'utf8'))
- chunks.push(Buffer.from([Number.parseInt(encoded.slice(i + 1, i + 4), 8)]))
+ for (let i = 0; i < input.length; i++) {
+ if (input[i] !== 0x5c
+ || i + 3 >= input.length
+ || input[i + 1] < 0x30 || input[i + 1] > 0x37
+ || input[i + 2] < 0x30 || input[i + 2] > 0x37
+ || input[i + 3] < 0x30 || input[i + 3] > 0x37) continue
+ if (i > plainStart) chunks.push(input.subarray(plainStart, i))
+ const value = ((input[i + 1] - 0x30) << 6)
+ | ((input[i + 2] - 0x30) << 3)
+ | (input[i + 3] - 0x30)
+ chunks.push(Buffer.from([value]))
i += 3
plainStart = i + 1
}
- if (plainStart < encoded.length) chunks.push(Buffer.from(encoded.slice(plainStart), 'utf8'))
+ if (plainStart < input.length) chunks.push(input.subarray(plainStart))
return Buffer.concat(chunks)
}
+export function parseTmuxControlOutput(lineBytes: Uint8Array): { paneId: string; data: Uint8Array } | null {
+ const line = Buffer.from(lineBytes)
+ const plainPrefix = Buffer.from('%output ')
+ if (line.subarray(0, plainPrefix.length).equals(plainPrefix)) {
+ const separator = line.indexOf(0x20, plainPrefix.length)
+ if (separator < 0) return null
+ const paneId = line.subarray(plainPrefix.length, separator).toString('ascii')
+ if (!/^%\d+$/.test(paneId)) return null
+ return { paneId, data: decodeTmuxControlBytes(line.subarray(separator + 1)) }
+ }
+
+ const extendedPrefix = Buffer.from('%extended-output ')
+ if (!line.subarray(0, extendedPrefix.length).equals(extendedPrefix)) return null
+ // latin1 is deliberately used only to locate the ASCII protocol header;
+ // each code unit still maps one-to-one to the original payload byte.
+ const header = /^%extended-output\s+(%\d+)\s+\d+\s+:?\s?/.exec(line.toString('latin1'))
+ if (!header) return null
+ return { paneId: header[1], data: decodeTmuxControlBytes(line.subarray(header[0].length)) }
+}
+
function mouseModes(meta: PaneMeta): string {
let out = ''
if (meta.mouseAll) out += '\u001b[?1003h'
@@ -109,12 +144,52 @@ function mouseModes(meta: PaneMeta): string {
return out
}
+/** `capture-pane -p` separates screen rows with a bare LF. A VT terminal's
+ * LF moves down without returning to column zero, so replaying the capture as
+ * received makes every row staircase to the right. tmux also encodes each
+ * captured row independently: it may leave a background SGR active at EOL
+ * while emitting the following default-style blank row as an empty string.
+ * Reset SGR at every row boundary so styled trailing cells remain on their row
+ * instead of bleeding into the next one when the snapshot is replayed. */
+export function normalizeTmuxCaptureLines(capture: Uint8Array): Uint8Array {
+ const raw = Buffer.from(capture)
+ // `capture-pane -p` prints a line terminator after its final screen row.
+ // Replaying that terminator in a terminal already containing paneHeight rows
+ // scrolls the snapshot by one, while cursor metadata stays in tmux's original
+ // coordinate space. Drop only this command-output delimiter; separators
+ // between captured rows are still normalized below.
+ let end = raw.length
+ if (end > 0 && raw[end - 1] === 0x0a) {
+ end--
+ if (end > 0 && raw[end - 1] === 0x0d) end--
+ }
+ const input = raw.subarray(0, end)
+ let loneLf = 0
+ for (let index = 0; index < input.length; index++) {
+ if (input[index] === 0x0a && (index === 0 || input[index - 1] !== 0x0d)) loneLf++
+ }
+ const sgrReset = Buffer.from('\u001b[0m')
+ const output = Buffer.allocUnsafe(input.length + loneLf * (1 + sgrReset.length) + sgrReset.length)
+ let write = 0
+ for (let index = 0; index < input.length; index++) {
+ if (input[index] === 0x0a && (index === 0 || input[index - 1] !== 0x0d)) {
+ sgrReset.copy(output, write)
+ write += sgrReset.length
+ output[write++] = 0x0d
+ }
+ output[write++] = input[index]
+ }
+ sgrReset.copy(output, write)
+ write += sgrReset.length
+ return output.subarray(0, write)
+}
+
export function synthesizeTmuxSnapshot(capture: Uint8Array, meta: PaneMeta): Uint8Array {
const cursorRow = Math.max(1, Math.min(meta.paneHeight, meta.cursorY + 1))
const cursorCol = Math.max(1, Math.min(meta.paneWidth, meta.cursorX + 1))
const prefix = Buffer.from(`\u001bc\u001b[?25l\u001b[H\u001b[2J\u001b[3J${mouseModes(meta)}`, 'utf8')
const suffix = Buffer.from(`\u001b[${cursorRow};${cursorCol}H\u001b[?25h`, 'utf8')
- return Buffer.concat([prefix, Buffer.from(capture), suffix])
+ return Buffer.concat([prefix, normalizeTmuxCaptureLines(capture), suffix])
}
async function loadAndPaste(paneId: string, bytes: Uint8Array): Promise<TerminalActionResult> {
@@ -148,10 +223,10 @@ async function sendHexBytes(paneId: string, bytes: Uint8Array): Promise<Terminal
export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
readonly runtime: TmuxRuntimeRef
private readonly child: ChildProcessWithoutNullStreams
- private readonly decoder = new StringDecoder('utf8')
- private lineBuffer = ''
+ private lineBuffer = Buffer.alloc(0)
private closed = false
private closeNotified = false
+ private outputPaused = false
private original: PaneMeta
private lastApplied: TerminalStreamSize | null = null
@@ -192,33 +267,30 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
}
private onStdout(chunk: Buffer): void {
- this.lineBuffer += this.decoder.write(chunk)
+ this.lineBuffer = Buffer.concat([this.lineBuffer, chunk])
while (true) {
- const newline = this.lineBuffer.indexOf('\n')
+ const newline = this.lineBuffer.indexOf(0x0a)
if (newline < 0) break
- const line = this.lineBuffer.slice(0, newline).replace(/\r$/, '')
- this.lineBuffer = this.lineBuffer.slice(newline + 1)
+ let line = this.lineBuffer.subarray(0, newline)
+ if (line.at(-1) === 0x0d) line = line.subarray(0, line.length - 1)
+ this.lineBuffer = this.lineBuffer.subarray(newline + 1)
this.onControlLine(line)
}
}
- private onControlLine(line: string): void {
- const output = /^%output\s+(%\d+)\s(.*)$/.exec(line)
+ private onControlLine(line: Buffer): void {
+ const output = parseTmuxControlOutput(line)
if (output) {
- if (output[1] === this.runtime.paneId) this.sink.onData(decodeTmuxControlData(output[2]))
- return
- }
- const extended = /^%extended-output\s+(%\d+)\s+\d+\s+:?\s?(.*)$/.exec(line)
- if (extended) {
- if (extended[1] === this.runtime.paneId) this.sink.onData(decodeTmuxControlData(extended[2]))
+ if (output.paneId === this.runtime.paneId) this.sink.onData(output.data)
return
}
- const paused = /^%pause\s+(%\d+)$/.exec(line)
- if (paused?.[1] === this.runtime.paneId && !this.closed) {
+ const text = line.toString('ascii')
+ const paused = /^%pause\s+(%\d+)$/.exec(text)
+ if (paused?.[1] === this.runtime.paneId && !this.closed && !this.outputPaused) {
this.child.stdin.write(`refresh-client -A ${this.runtime.paneId}:continue\n`)
return
}
- if (line.startsWith('%exit')) this.notifyClose(this.closed ? 'closed' : 'tmux pane/control client closed')
+ if (text.startsWith('%exit')) this.notifyClose(this.closed ? 'closed' : 'tmux pane/control client closed')
}
private notifyClose(reason: string): void {
@@ -231,10 +303,23 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
const meta = await paneMeta(this.runtime.paneId)
if (!meta) return { state: 'failed', reason: 'tmux pane disappeared' }
const boundedHistory = Math.max(0, Math.min(1_000, Math.floor(historyLines)))
- const args = ['capture-pane', '-p', '-e', '-t', this.runtime.paneId]
+ // -N is required for TUI fidelity: styled blank cells (for example the
+ // Codex input box background) live in trailing spaces that tmux otherwise
+ // trims from each captured row.
+ const args = ['capture-pane', '-p', '-e', '-N', '-t', this.runtime.paneId]
if (!meta.alternateOn && boundedHistory > 0) args.push('-S', `-${boundedHistory}`)
+ // Give resize-triggered TUI output a short window to enter the manager's
+ // snapshot buffer before capture, then drain notifications queued just
+ // behind capture-pane's callback. The manager recaptures when either side
+ // of this window observed a repaint.
+ await new Promise((resolve) => setTimeout(resolve, CONTROL_OUTPUT_SETTLE_MS))
const capture = await execTmux(args, 3_000)
if (!capture.ok) return { state: 'failed', reason: 'tmux snapshot failed' }
+ // capture-pane runs in a separate tmux client. Its exec callback can win
+ // the event-loop race against repaint notifications already queued for the
+ // control client. Keep the manager in snapshotting mode long enough to
+ // observe those late deltas; it will then discard them and recapture.
+ await new Promise((resolve) => setTimeout(resolve, CONTROL_OUTPUT_SETTLE_MS))
return {
state: 'succeeded',
value: {
@@ -265,6 +350,30 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {
return TERMINAL_ACTION_SUCCEEDED
}
+ async pauseOutput(): Promise<TerminalActionResult> {
+ if (this.closed || !this.child.stdin.writable) return terminalActionNotStarted('terminal stream is closed')
+ try {
+ this.outputPaused = true
+ this.child.stdin.write(`refresh-client -A ${this.runtime.paneId}:pause\n`)
+ return TERMINAL_ACTION_SUCCEEDED
+ } catch {
+ this.outputPaused = false
+ return terminalActionPossiblyExecuted('tmux output pause did not complete')
+ }
+ }
+
+ async resumeOutput(): Promise<TerminalActionResult> {
+ if (this.closed || !this.child.stdin.writable) return terminalActionNotStarted('terminal stream is closed')
+ try {
+ this.outputPaused = false
+ this.child.stdin.write(`refresh-client -A ${this.runtime.paneId}:continue\n`)
+ return TERMINAL_ACTION_SUCCEEDED
+ } catch {
+ this.outputPaused = true
+ return terminalActionPossiblyExecuted('tmux output resume did not complete')
+ }
+ }
+
async close(): Promise<void> {
if (this.closed) return
this.closed = true