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
feat: add terminal_paste frame support to stream manager for atomic clipboard pasting via tmux paste-buffer
0xken15f90063468657
diff --git a/cli/src/lib/terminalBackendCoordinator.spec.ts b/cli/src/lib/terminalBackendCoordinator.spec.tsindex 71d4baa5a..8a5bb404e 100644--- a/cli/src/lib/terminalBackendCoordinator.spec.ts+++ b/cli/src/lib/terminalBackendCoordinator.spec.ts@@ -40,6 +40,7 @@ function streamHandle(): TerminalStreamHandle {})),endSnapshot: vi.fn(),writeRaw: vi.fn(),+ pasteRaw: vi.fn(),resize: vi.fn(),scroll: vi.fn(),pauseOutput: vi.fn(),diff --git a/cli/src/lib/terminalP2p.ts b/cli/src/lib/terminalP2p.tsindex aa527a46d..3bf214987 100644--- a/cli/src/lib/terminalP2p.ts+++ b/cli/src/lib/terminalP2p.ts@@ -38,6 +38,7 @@ export const TERMINAL_P2P_SIGNAL_TYPES = new Set([export const TERMINAL_P2P_DOWN_TYPES = new Set(['terminal_capabilities', 'terminal_open', 'terminal_alive', 'terminal_ack','terminal_input', 'terminal_resize', 'terminal_resync', 'terminal_close', 'terminal_scroll',+ 'terminal_paste',])export const TERMINAL_P2P_UP_TYPES = new Set([diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex 8105cca3e..992ea6dc6 100644--- a/cli/src/lib/terminalStreamManager.spec.ts+++ b/cli/src/lib/terminalStreamManager.spec.ts@@ -9,6 +9,7 @@ import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.jclass FakeStream implements TerminalStreamHandle {readonly runtime = { backend: 'tmux' as const, paneId: '%1' }writes: Uint8Array[] = []+ pastes: string[] = []sizes: Array<{ cols: number; rows: number }> = []scrolls: Array<{ direction: 'up' | 'down'; lines: number }> = []closed = false@@ -29,6 +30,7 @@ class FakeStream implements TerminalStreamHandle {}endSnapshot() { this.snapshotEnds++; this.onEndSnapshot?.() }async writeRaw(bytes: Uint8Array) { this.writes.push(bytes); return TERMINAL_ACTION_SUCCEEDED }+ async pasteRaw(text: string) { this.pastes.push(text); return TERMINAL_ACTION_SUCCEEDED }async resize(size: { cols: number; rows: number }) { this.sizes.push(size); return TERMINAL_ACTION_SUCCEEDED }async scroll(direction: 'up' | 'down', lines: number) { this.scrolls.push({ direction, lines }); return TERMINAL_ACTION_SUCCEEDED }async pauseOutput() { this.pauses++; return TERMINAL_ACTION_SUCCEEDED }@@ -178,6 +180,30 @@ describe('TerminalStreamManager', () => {expect(sent.at(-1)?.payload.code).toBe('TERMINAL_SCROLL_INVALID')})+ it('routes terminal_paste to pasteRaw as one unit, never through writeRaw', async () => {+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId: 'open-paste', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,+ })+ const streamId = sent[0].payload.streamId as string++ const longPaste = Array.from({ length: 200 }, (_, i) => `line ${i}`).join('\n')+ await manager.handleFrame('web-1', 'terminal_paste', { streamId, text: longPaste })+ expect(stream.pastes).toEqual([longPaste])+ expect(stream.writes).toHaveLength(0)++ // Ctrl+C pasted alongside real content must never reach the pane, same rule as input().+ await manager.handleFrame('web-1', 'terminal_paste', { streamId, text: 'a\x03b' })+ expect(stream.pastes.at(-1)).toBe('ab')++ await manager.handleFrame('web-1', 'terminal_paste', { streamId, text: '' })+ expect(sent.at(-1)?.payload.code).toBe('TERMINAL_PASTE_INVALID')+ expect(stream.pastes).toHaveLength(2)++ await manager.handleFrame('web-1', 'terminal_paste', { streamId, text: 'x'.repeat(65 * 1024) })+ expect(sent.at(-1)?.payload.code).toBe('TERMINAL_PASTE_INVALID')+ expect(stream.pastes).toHaveLength(2)+ })+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')diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.tsindex 9f32041bb..e493142fd 100644--- a/cli/src/lib/terminalStreamManager.ts+++ b/cli/src/lib/terminalStreamManager.ts@@ -149,6 +149,9 @@ export class TerminalStreamManager {case 'terminal_resize':await this.resize(connId, payload)return true+ case 'terminal_paste':+ await this.paste(connId, payload)+ return truecase 'terminal_scroll':await this.scroll(connId, payload)return true@@ -183,6 +186,10 @@ export class TerminalStreamManager {keyframe: true,sync: true,compression: ['none', 'zlib'],+ // A client old enough to predate `terminal_paste` must keep sending a direct terminal paste+ // through `terminal_input` — checked here rather than assumed, so it degrades instead of+ // silently going nowhere against a CLI that doesn't recognize the newer frame type.+ pasteRaw: true,},engines: terminalEngineCapabilities(this.deps.streamingAvailable),})@@ -411,6 +418,36 @@ export class TerminalStreamManager {await this.sendKeyframe(state)}+ /**+ * A clipboard paste made directly into the terminal (not the composer), delivered whole via+ * `TerminalStreamHandle.pasteRaw` instead of the chunked `writeRaw`/`send-keys -H` keystroke path —+ * see `pasteRawIntoTmux` for why the two cannot share a pipe. No seq/ordering guard, unlike `input()`:+ * a paste is one self-contained unit, not part of an ordered keystroke stream.+ */+ private async paste(connId: string, payload: FramePayload): Promise<void> {+ const state = this.streamFor(connId, payload)+ if (!state) return+ const text = payload.text+ if (typeof text !== 'string' || text.length === 0) {+ this.sendError(connId, 'TERMINAL_PASTE_INVALID', { streamId: state.streamId })+ return+ }+ if (Buffer.byteLength(text, 'utf8') > INPUT_MAX_BYTES) {+ this.sendError(connId, 'TERMINAL_PASTE_INVALID', { streamId: state.streamId, message: 'paste too large' })+ return+ }+ state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS+ // Same reason as input(): the engine in the pane has no job-control fallback for an uncaught+ // SIGINT, so a stray 0x03 pasted alongside real content must never reach it.+ const filtered = text.includes('\x03') ? text.replaceAll('\x03', '') : text+ if (filtered.length === 0) return+ const result = await state.handle.pasteRaw(filtered)+ if (result.state !== 'succeeded') {+ this.sendError(connId, 'TERMINAL_PASTE_FAILED', { streamId: state.streamId, message: result.reason })+ if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state)+ }+ }+/** Scroll gestures arrive stream-scoped, same as resize — no ordering/seq guard needed since,* unlike input, an out-of-order or dropped scroll frame just means one gesture scrolled a little* more or less than intended, never a corrupted stream. The pane's live output stream (alreadydiff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.tsindex 6be90ea33..908575213 100644--- a/cli/src/lib/terminalTypes.ts+++ b/cli/src/lib/terminalTypes.ts@@ -167,6 +167,9 @@ export interface TerminalStreamHandle<Ref extends TerminalRuntimeRef = TerminalR/** Release output produced strictly after the snapshot cut. */endSnapshot(): voidwriteRaw(bytes: Uint8Array): Promise<TerminalActionResult>+ /** A clipboard paste, delivered as one atomic unit rather than chunked like `writeRaw` — see+ * `pasteRawIntoTmux` for why a paste needs its own path instead of reusing the keystroke one. */+ pasteRaw(text: string): Promise<TerminalActionResult>resize(size: TerminalStreamSize): Promise<TerminalActionResult>/** Scroll via the backend's own history mechanism (tmux copy-mode for `TmuxControlStream`) rather* than writing bytes into the pty — a program that owns terminal mouse-tracking but doesn'tdiff --git a/cli/src/lib/tmux.ts b/cli/src/lib/tmux.tsindex f9cbc6a2e..623e2feb4 100644--- a/cli/src/lib/tmux.ts+++ b/cli/src/lib/tmux.ts@@ -894,6 +894,22 @@ export function sendLiteralToTmux(pane: string, text: string): Promise<boolean>return tmuxPasteText(pane, text, false)}+/**+ * Dump a live terminal stream's clipboard paste into a pane as ONE bracketed paste, no submit.+ *+ * The desktop app's raw keyboard/paste path used to run a large clipboard paste through the same+ * byte-oriented pipeline as ordinary typing (`TerminalStreamHandle.writeRaw`), which chunks at+ * `INPUT_CHUNK_BYTES` to stay under tmux's `send-keys -H` command-line length — and each chunk landed+ * in the pane far enough apart that the engine's own paste-detector (readline/Ink) registered it as a+ * separate paste, producing dozens of `[Pasted text #N]` markers for what was one clipboard paste.+ * `tmuxPasteText`'s stdin-loaded buffer has no such length limit, so it is the same single-shot+ * mechanism `sendToTmux` already uses for composer messages — just without the trailing Enter, since a+ * paste into a live terminal must not auto-submit.+ */+export function pasteRawIntoTmux(pane: string, text: string): Promise<boolean> {+ return tmuxPasteText(pane, text, true)+}+export function sendKeyToTmux(pane: string, key: string): Promise<boolean> {return new Promise((resolve) => {execFile('tmux', ['send-keys', '-t', pane, key], { timeout: 2000 }, (err) => resolve(!err))diff --git a/cli/src/lib/tmuxStream.real.spec.ts b/cli/src/lib/tmuxStream.real.spec.tsindex 5304da407..dfbb0b691 100644--- a/cli/src/lib/tmuxStream.real.spec.ts+++ b/cli/src/lib/tmuxStream.real.spec.ts@@ -124,6 +124,45 @@ run('TmuxControlStream real tmux', () => {}})+ 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}`diff --git a/cli/src/lib/tmuxStream.ts b/cli/src/lib/tmuxStream.tsindex 0062bb583..7352c58dd 100644--- a/cli/src/lib/tmuxStream.ts+++ b/cli/src/lib/tmuxStream.ts@@ -1,4 +1,5 @@import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'+import { pasteRawIntoTmux } from './tmux.js'import {TERMINAL_ACTION_SUCCEEDED,terminalActionNotStarted,@@ -678,6 +679,21 @@ export class TmuxControlStream implements TerminalStreamHandle<TmuxRuntimeRef> {: terminalActionPossiblyExecuted('tmux raw input stopped after a partial write')}+ /**+ * A clipboard paste, delivered as one bracketed `paste-buffer` rather than chunked `send-keys -H`+ * bursts like `writeRaw` — see `pasteRawIntoTmux` for why a paste needs this instead of the+ * keystroke path (chunking there is fine for typing, but reads as several separate pastes to a+ * program's own paste-detector once split across multiple `send-keys` commands).+ */+ async pasteRaw(text: string): Promise<TerminalActionResult> {+ if (this.closed) return terminalActionNotStarted('terminal stream is closed')+ if (text.length === 0) return TERMINAL_ACTION_SUCCEEDED+ const pasted = await pasteRawIntoTmux(this.runtime.paneId, text)+ return pasted+ ? TERMINAL_ACTION_SUCCEEDED+ : terminalActionNotStarted('tmux paste-buffer could not be sent')+ }+/** Scroll via tmux's own copy-mode rather than writing bytes into the pty. Some remote CLIs (e.g.* Claude Code) declare terminal mouse-tracking and correctly handle SGR wheel reports themselves;* others declare it but don't (confirmed live for Grok: it echoes the raw escape bytes into its