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
/**
* The terminal's binary framing: the plain frame a window on this computer gets (`encodeTerminalLocal`),
* the envelope a sealed one travels in, and the hop prefix the relay routes by. The sealing itself is the
* gateway's (lib/e2ee/terminalSeal.ts): the core frames bytes for its windows and never holds a key.
*/
const utf8 = (s: string): Uint8Array => new TextEncoder().encode(s)
export const TERMINAL_BINARY_VERSION = 3
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 TERMINAL_LOCAL_VERSION = 1
export const TERMINAL_LOCAL_HEADER_BYTES = 12
export const TERMINAL_LOCAL_MAX_PAYLOAD_BYTES = 512 * 1024
// A paste is delivered whole, in one frame — unlike every other kind, which is either a small
// bounded control message (keyframe/sync) or already chunked upstream to stay well under the
// keystroke ceiling (input, ≤8 KiB per frame client-side). Reusing that ceiling for paste made an
// entirely ordinary large clipboard paste (a few hundred KB of real code) bounce off a limit sized
// for a keystroke. This is a sanity ceiling against a broken/malicious client, not a real limit —
// see PASTE_MAX_BYTES's own history in terminalStreamManager.ts.
export const TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES = 6 * 1024 * 1024
export const TERMINAL_LOCAL_PASTE_MAX_PAYLOAD_BYTES = 6 * 1024 * 1024
// An image paste (a clipboard screenshot, "Copy Image", ...) is delivered whole, same shape as a
// text paste, but the bytes are already-compressed PNG data rather than text — see
// `terminalStreamManager.ts`'s `pasteImage()`. Mirrors terminal_binary.dart's
// terminalLocalImagePasteMaxPayloadBytes — keep the two in step.
export const TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES = 8 * 1024 * 1024
export const TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES = 8 * 1024 * 1024
// A dropped (non-image) file, delivered whole so its path can be pasted on the far side — see
// terminalStreamManager.ts's pasteFile(). Ordinary files run larger than a screenshot, hence its
// own, more generous ceiling; this is a modest atomic-frame limit, not a general file-transfer
// feature. Mirrors terminal_binary.dart's terminalLocalPasteFileMaxPayloadBytes — keep in step.
export const TERMINAL_BINARY_PASTE_FILE_MAX_CIPHERTEXT_BYTES = 20 * 1024 * 1024
export const TERMINAL_LOCAL_PASTE_FILE_MAX_PAYLOAD_BYTES = 20 * 1024 * 1024
export const enum TerminalBinaryKind {
input = 1,
output = 2,
keyframe = 3,
sync = 4,
/** A clipboard paste made directly into the terminal, delivered as one atomic unit — see
* `pasteRawIntoTmux` in tmux.ts for why this needs its own kind instead of riding `input`. Upload
* (client→CLI) only; nothing ever sends this back down. */
paste = 5,
/** A clipboard IMAGE paste (raw PNG bytes) — same "atomic, out-of-band" shape as `paste`, but
* binary rather than UTF-8 text, so it can't share that kind (`paste()` requires valid UTF-8).
* See `terminalStreamManager.ts`'s `pasteImage()`. Upload (client→CLI) only; nothing ever sends
* this back down. */
imagePaste = 6,
/** A dropped (non-image) FILE — carries the original filename plus its bytes (see
* `pasteFile()`'s payload layout), so the daemon can write it to disk on its own machine and
* paste that path as text. Never touches the OS clipboard and never replays a keystroke, unlike
* `imagePaste` — the goal here is only "the pane gets a valid path". Upload (client→CLI) only;
* nothing ever sends this back down. */
pasteFile = 7,
}
export interface TerminalBinaryClear {
kind: TerminalBinaryKind
streamId: string
seq: number
bytes: Uint8Array
compressed: boolean
cols?: number
rows?: number
/** Origin of this input, inside the authenticated/encrypted payload. */
tabId?: string
}
export interface TerminalBinaryEnvelope {
kind: TerminalBinaryKind
flags: number
counter: number
ciphertext: Uint8Array
aad: Uint8Array
}
export const MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x4d) // HTRM
const HOP_MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x48) // HTRH
const LOCAL_MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x4c) // HTRL
const FLAG_ZLIB = 1
const FLAG_SWARM = 2
const canCarrySwarm = (kind: TerminalBinaryKind): boolean => kind === TerminalBinaryKind.input || kind === TerminalBinaryKind.paste
export const flagsFor = (frame: TerminalBinaryClear): number => (frame.compressed ? FLAG_ZLIB : 0) | (frame.tabId !== undefined ? FLAG_SWARM : 0)
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
|| value === TerminalBinaryKind.sync
|| value === TerminalBinaryKind.paste
|| value === TerminalBinaryKind.imagePaste
|| value === TerminalBinaryKind.pasteFile
}
export function terminalBinaryType(kind: TerminalBinaryKind): string {
if (kind === TerminalBinaryKind.input) return 'terminal_input'
if (kind === TerminalBinaryKind.output) return 'terminal_output'
if (kind === TerminalBinaryKind.keyframe) return 'terminal_keyframe'
if (kind === TerminalBinaryKind.paste) return 'terminal_paste'
if (kind === TerminalBinaryKind.imagePaste) return 'terminal_paste_image'
if (kind === TerminalBinaryKind.pasteFile) return 'terminal_paste_file'
return 'terminal_sync'
}
/** The seal/parse/encode/decode size ceiling for [kind] — paste, imagePaste and pasteFile each get
* a much larger one; see TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES /
* TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES / TERMINAL_BINARY_PASTE_FILE_MAX_CIPHERTEXT_BYTES. */
export function maxCiphertextBytesFor(kind: TerminalBinaryKind): number {
if (kind === TerminalBinaryKind.paste) return TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES
if (kind === TerminalBinaryKind.imagePaste) return TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES
if (kind === TerminalBinaryKind.pasteFile) return TERMINAL_BINARY_PASTE_FILE_MAX_CIPHERTEXT_BYTES
return TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES
}
function maxLocalPayloadBytesFor(kind: TerminalBinaryKind): number {
if (kind === TerminalBinaryKind.paste) return TERMINAL_LOCAL_PASTE_MAX_PAYLOAD_BYTES
if (kind === TerminalBinaryKind.imagePaste) return TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES
if (kind === TerminalBinaryKind.pasteFile) return TERMINAL_LOCAL_PASTE_FILE_MAX_PAYLOAD_BYTES
return TERMINAL_LOCAL_MAX_PAYLOAD_BYTES
}
export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | null {
const id = uuidBytes(frame.streamId)
if (!id || !Number.isSafeInteger(frame.seq) || frame.seq < 0) return null
// Compression is for the SERVER's own output/keyframe frames, which the client already knows how
// to inflate. Nothing on this side inflates an incoming frame, so a client-compressed kind (input,
// sync, and — for now — paste too) would silently hand tmux a compressed blob instead of text.
if ((frame.kind === TerminalBinaryKind.input || frame.kind === TerminalBinaryKind.sync
|| frame.kind === TerminalBinaryKind.paste || frame.kind === TerminalBinaryKind.imagePaste
|| frame.kind === TerminalBinaryKind.pasteFile)
&& frame.compressed) return null
if (frame.kind === TerminalBinaryKind.sync && frame.bytes.length !== 0) return null
const scope = frame.tabId === undefined ? null : Buffer.from(frame.tabId, 'utf8')
if (scope && (!canCarrySwarm(frame.kind) || !/^[A-Za-z0-9_-]{1,128}$/.test(frame.tabId!))) return null
const metaBytes = frame.kind === TerminalBinaryKind.keyframe ? 28 : 24 + (scope ? 1 + scope.length : 0)
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)
}
if (scope) { out[24] = scope.length; out.set(scope, 25) }
out.set(frame.bytes, metaBytes)
return out
}
export function decodeTerminalPlain(kind: TerminalBinaryKind, flags: number, plaintext: Uint8Array): TerminalBinaryClear | null {
if ((flags & ~(FLAG_ZLIB | FLAG_SWARM)) !== 0 || ((flags & FLAG_SWARM) && !canCarrySwarm(kind))
|| ((kind === TerminalBinaryKind.input || kind === TerminalBinaryKind.sync
|| kind === TerminalBinaryKind.paste || kind === TerminalBinaryKind.imagePaste
|| kind === TerminalBinaryKind.pasteFile) && (flags & FLAG_ZLIB) !== 0)) return null
let metaBytes = kind === TerminalBinaryKind.keyframe ? 28 : 24
let tabId: string | undefined
if (flags & FLAG_SWARM) {
const length = plaintext[24]
if (!length || length > 128 || plaintext.length < 25 + length) return null
tabId = Buffer.from(plaintext.subarray(25, 25 + length)).toString('utf8')
if (!/^[A-Za-z0-9_-]{1,128}$/.test(tabId)) return null
metaBytes = 25 + length
}
if (plaintext.length < metaBytes || (kind === TerminalBinaryKind.sync && 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,
...(tabId === undefined ? {} : { tabId }),
...(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 > maxCiphertextBytesFor(bytes[5])
|| 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),
}
}
/** Plain terminal framing for the authenticated loopback desktop transport. */
export function encodeTerminalLocal(frame: TerminalBinaryClear): Uint8Array | null {
const payload = encodeTerminalPlain(frame)
if (!payload || payload.length > maxLocalPayloadBytesFor(frame.kind)) return null
const flags = flagsFor(frame)
const header = new Uint8Array(TERMINAL_LOCAL_HEADER_BYTES)
header.set(LOCAL_MAGIC, 0)
header[4] = TERMINAL_LOCAL_VERSION
header[5] = frame.kind
header[6] = flags
const view = new DataView(header.buffer)
view.setUint32(8, payload.length, false)
const out = new Uint8Array(header.length + payload.length)
out.set(header)
out.set(payload, header.length)
return out
}
/** Decode a terminal frame only after the WebSocket peer passed loopback API-key authentication. */
export function decodeTerminalLocal(raw: Uint8Array): TerminalBinaryClear | null {
const bytes = Uint8Array.from(raw)
if (bytes.length < TERMINAL_LOCAL_HEADER_BYTES) return null
for (let index = 0; index < LOCAL_MAGIC.length; index++) if (bytes[index] !== LOCAL_MAGIC[index]) return null
const kind = bytes[5]
const flags = bytes[6]
if (bytes[4] !== TERMINAL_LOCAL_VERSION || !validKind(kind) || bytes[7] !== 0) return null
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
const length = view.getUint32(8, false)
if (length > maxLocalPayloadBytesFor(kind) || bytes.length !== TERMINAL_LOCAL_HEADER_BYTES + length) return null
return decodeTerminalPlain(kind, flags, bytes.slice(TERMINAL_LOCAL_HEADER_BYTES))
}
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)}`)
}