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: 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.ts
index 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.ts
index 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.ts
index 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.j
class 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.ts
index 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 true
case '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 (already
diff --git a/cli/src/lib/terminalTypes.ts b/cli/src/lib/terminalTypes.ts
index 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(): void
writeRaw(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't
diff --git a/cli/src/lib/tmux.ts b/cli/src/lib/tmux.ts
index 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.ts
index 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.ts
index 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