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 image paste support via OS clipboard integration and fallback to file path pasting

0xken1526a5d4ac7bd0
diff --git a/cli/src/lib/osClipboard.ts b/cli/src/lib/osClipboard.ts
new file mode 100644
index 000000000..7921589df
--- /dev/null
+++ b/cli/src/lib/osClipboard.ts
@@ -0,0 +1,104 @@
+/**
+ * Writing image bytes into the HOST OS's native clipboard — the machine this process itself runs
+ * on, which for a relayed session is the remote machine, not the desktop client's. This is the
+ * other half of native image paste: the engine attached to the tmux pane (Claude Code, Codex CLI,
+ * ...) already reads its OWN OS clipboard on a paste keystroke — see terminalStreamManager.ts's
+ * `pasteImage()` — so writing the clipboard here and then replaying that keystroke is all that's
+ * needed; no OS-level keystroke synthesis is involved.
+ */
+import { execFile, spawn } from 'node:child_process'
+import { binaryOnPath } from './binaryOnPath.js'
+
+export type OsClipboardImageResult =
+ | { state: 'written' }
+ /** No clipboard reachable at all right now (tool missing, or genuinely no X11/Wayland session) —
+ * not an error, just nothing to write to. Caller falls back to pasting a file path instead. */
+ | { state: 'unavailable'; reason: string }
+ /** The clipboard mechanism is present but the write itself failed. */
+ | { state: 'failed'; reason: string }
+
+function runWithStdin(command: string, args: string[], input: Uint8Array): Promise<{ ok: boolean; message?: string }> {
+ return new Promise((resolve) => {
+ let child: ReturnType<typeof spawn>
+ try {
+ child = spawn(command, args, { stdio: ['pipe', 'ignore', 'pipe'] })
+ } catch (error) {
+ resolve({ ok: false, message: error instanceof Error ? error.message : String(error) })
+ return
+ }
+ let stderr = ''
+ child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
+ child.once('error', (error) => resolve({ ok: false, message: error.message }))
+ // 'exit', NOT 'close': both xclip and wl-copy load the clipboard data and then fork into a
+ // background process that STAYS ALIVE to serve paste requests (X11/Wayland clipboard ownership
+ // has no concept of "set once" — someone has to keep answering selection requests) — and that
+ // forked process inherits this one's stdio pipes. Node's 'close' waits for every stdio stream to
+ // close too, which then never happens: confirmed live against real xclip on Ubuntu, where a
+ // `close` listener here hung indefinitely even though the write itself completes in milliseconds.
+ // 'exit' only waits on the process we actually spawned, which is what answers "did the write
+ // succeed" — whatever it forked into afterwards is background clipboard-owner housekeeping we
+ // don't need to wait on.
+ child.once('exit', (code) => {
+ // The stdio PIPE handles this process handed to the child may still be held open by whatever
+ // it forked into (see above), and each is its own libuv handle independent of the child
+ // process handle — `child.unref()` alone measurably left the pipes still keeping the event
+ // loop alive (reproduced live: the write completed but the process needed a hard timeout to
+ // return). `stdin`/`stderr` are `net.Socket`s for pipe-based stdio, which do have `.unref()` at
+ // runtime even though the general `Writable`/`Readable` types TypeScript sees here don't
+ // declare it — hence the cast.
+ type Unrefable = { unref?: () => void }
+ (child.stdin as unknown as Unrefable | null)?.unref?.()
+ ;(child.stderr as unknown as Unrefable | null)?.unref?.()
+ child.unref()
+ resolve(code === 0 ? { ok: true } : { ok: false, message: stderr.trim() || `exited with code ${code}` })
+ })
+ child.stdin?.end(Buffer.from(input))
+ })
+}
+
+/** macOS: `osascript` ships with the OS, nothing to detect. Reads the PNG bytes back off disk (the
+ * `read … as «class PNGf»` idiom needs a POSIX file path, not stdin) — `pngPath` must already hold
+ * `pngBytes`. */
+function writeMacClipboard(pngPath: string): Promise<OsClipboardImageResult> {
+ return new Promise((resolve) => {
+ execFile(
+ 'osascript',
+ ['-e', `set the clipboard to (read (POSIX file ${JSON.stringify(pngPath)}) as «class PNGf»)`],
+ { timeout: 5_000 },
+ (error, _stdout, stderr) => {
+ resolve(error
+ ? { state: 'failed', reason: (typeof stderr === 'string' && stderr.trim()) || error.message }
+ : { state: 'written' })
+ },
+ )
+ })
+}
+
+/** Linux: which clipboard tool applies depends on the ACTIVE session, not the distro, so this is
+ * checked per-call rather than once at startup — `$WAYLAND_DISPLAY`/`$DISPLAY` reflect the
+ * session the daemon is currently running under. Neither set means no display server at all
+ * (a genuinely headless box), which no clipboard tool can fix. */
+async function writeLinuxClipboard(pngBytes: Uint8Array): Promise<OsClipboardImageResult> {
+ if (process.env.WAYLAND_DISPLAY) {
+ if (!binaryOnPath('wl-copy')) {
+ return { state: 'unavailable', reason: 'wl-copy not found (install the wl-clipboard package)' }
+ }
+ const result = await runWithStdin('wl-copy', ['--type', 'image/png'], pngBytes)
+ return result.ok ? { state: 'written' } : { state: 'failed', reason: result.message ?? 'wl-copy failed' }
+ }
+ if (process.env.DISPLAY) {
+ if (!binaryOnPath('xclip')) {
+ return { state: 'unavailable', reason: 'xclip not found (install the xclip package)' }
+ }
+ const result = await runWithStdin('xclip', ['-selection', 'clipboard', '-t', 'image/png', '-i'], pngBytes)
+ return result.ok ? { state: 'written' } : { state: 'failed', reason: result.message ?? 'xclip failed' }
+ }
+ return { state: 'unavailable', reason: 'no X11 or Wayland display on this machine' }
+}
+
+/** Writes `pngBytes` (already saved at `pngPath`) into this machine's native OS clipboard. */
+export async function writeImageToOsClipboard(pngPath: string, pngBytes: Uint8Array): Promise<OsClipboardImageResult> {
+ if (process.platform === 'darwin') return writeMacClipboard(pngPath)
+ if (process.platform === 'linux') return writeLinuxClipboard(pngBytes)
+ return { state: 'unavailable', reason: `no clipboard writer for ${process.platform}` }
+}
diff --git a/cli/src/lib/pasteImageFiles.ts b/cli/src/lib/pasteImageFiles.ts
new file mode 100644
index 000000000..ef10c33ad
--- /dev/null
+++ b/cli/src/lib/pasteImageFiles.ts
@@ -0,0 +1,41 @@
+/**
+ * Where an image paste's PNG bytes land on disk on THIS machine, and how long they stick around.
+ *
+ * A successful native-clipboard write (osClipboard.ts) only needs the file for the instant the OS
+ * takes to ingest it — the OS clipboard owns the bytes after that. The file-path fallback (when no
+ * native clipboard is reachable) is different: the path itself is what gets pasted into the pane,
+ * so the file has to keep resolving after this call returns. Both cases share one directory so a
+ * single prune sweep bounds both.
+ */
+import { randomUUID } from 'node:crypto'
+import { mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { env } from '../config/env.js'
+
+const PASTE_IMAGES_DIR = join(env.ADAPTER_DATA_DIR, 'paste-images')
+const RETENTION_MS = 24 * 60 * 60 * 1000
+
+/** Best-effort: a prune failure must never block an image paste that is otherwise fine. */
+async function pruneStale(): Promise<void> {
+ try {
+ const now = Date.now()
+ const entries = await readdir(PASTE_IMAGES_DIR)
+ await Promise.all(entries.map(async (name) => {
+ const path = join(PASTE_IMAGES_DIR, name)
+ try {
+ const info = await stat(path)
+ if (now - info.mtimeMs > RETENTION_MS) await rm(path, { force: true })
+ } catch { /* raced with something else touching the same file — ignore */ }
+ }))
+ } catch { /* directory not there yet, or unreadable — nothing to prune */ }
+}
+
+/** Writes `bytes` to a freshly named PNG file under the harness data dir, pruning anything older
+ * than a day from the same directory first, and returns its absolute path. */
+export async function writePasteImageFile(bytes: Uint8Array): Promise<string> {
+ await mkdir(PASTE_IMAGES_DIR, { recursive: true })
+ await pruneStale()
+ const path = join(PASTE_IMAGES_DIR, `${randomUUID()}.png`)
+ await writeFile(path, bytes)
+ return path
+}
diff --git a/cli/src/lib/terminalBinary.spec.ts b/cli/src/lib/terminalBinary.spec.ts
index 487daa6c2..61998e30d 100644
--- a/cli/src/lib/terminalBinary.spec.ts
+++ b/cli/src/lib/terminalBinary.spec.ts
@@ -7,8 +7,10 @@ import {
parseTerminalBinaryEnvelope,
sealTerminalBinary,
TerminalBinaryKind,
+ TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES,
TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES,
TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES,
+ TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES,
} from './terminalBinary.js'
const key = Uint8Array.from({ length: 32 }, (_, index) => index)
@@ -125,6 +127,41 @@ describe('terminal binary protocol v3', () => {
})).toBeNull()
})
+ it('round-trips a binary image paste (not valid UTF-8) at its own ceiling', () => {
+ // A PNG magic number plus garbage — the point is that this is NOT valid UTF-8, unlike `paste`,
+ // and must still round-trip untouched.
+ const bytes = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe, 0x00])
+ const sealed = sealTerminalBinary(key, 20, {
+ kind: TerminalBinaryKind.imagePaste,
+ streamId,
+ seq: 0,
+ bytes,
+ compressed: false,
+ })!
+ expect(sealed).not.toBeNull()
+ expect(openTerminalBinary(key, sealed)?.frame).toEqual({
+ kind: TerminalBinaryKind.imagePaste,
+ streamId,
+ seq: 0,
+ bytes,
+ compressed: false,
+ })
+
+ // Its own ceiling, independent of paste's.
+ const tooBig = new Uint8Array(TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES + 1)
+ expect(sealTerminalBinary(key, 21, { kind: TerminalBinaryKind.imagePaste, streamId, seq: 0, bytes: tooBig, compressed: false })).toBeNull()
+ })
+
+ it('rejects a compressed image paste, same reason as paste', () => {
+ expect(sealTerminalBinary(key, 22, {
+ kind: TerminalBinaryKind.imagePaste,
+ streamId,
+ seq: 0,
+ bytes: Uint8Array.of(1, 2, 3),
+ compressed: true,
+ })).toBeNull()
+ })
+
it('rejects tamper, truncation and unsupported flags', () => {
const sealed = sealTerminalBinary(key, 1, {
kind: TerminalBinaryKind.output,
@@ -208,4 +245,35 @@ describe('authenticated loopback terminal framing v1', () => {
compressed: false,
})).toBeNull()
})
+
+ it('carries an image paste well past the ordinary local frame ceiling, independent of paste', () => {
+ // Comfortably over the 512 KiB generic ceiling, well under imagePaste's own 4 MiB one — big
+ // enough to prove the kind-specific ceiling applies, small enough that a byte-for-byte
+ // deep-equal below stays fast.
+ const bytes = new Uint8Array(1.5 * 1024 * 1024).fill(0xab)
+ const encoded = encodeTerminalLocal({
+ kind: TerminalBinaryKind.imagePaste,
+ streamId,
+ seq: 0,
+ bytes,
+ compressed: false,
+ })
+ expect(encoded).not.toBeNull()
+ expect(decodeTerminalLocal(encoded!)).toEqual({
+ kind: TerminalBinaryKind.imagePaste,
+ streamId,
+ seq: 0,
+ bytes,
+ compressed: false,
+ })
+
+ const tooBig = new Uint8Array(TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES + 1)
+ expect(encodeTerminalLocal({
+ kind: TerminalBinaryKind.imagePaste,
+ streamId,
+ seq: 0,
+ bytes: tooBig,
+ compressed: false,
+ })).toBeNull()
+ })
})
diff --git a/cli/src/lib/terminalBinary.ts b/cli/src/lib/terminalBinary.ts
index dbdb8e630..2fd2aafbf 100644
--- a/cli/src/lib/terminalBinary.ts
+++ b/cli/src/lib/terminalBinary.ts
@@ -17,6 +17,12 @@ export const TERMINAL_LOCAL_MAX_PAYLOAD_BYTES = 512 * 1024
// 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 = 4 * 1024 * 1024
+export const TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES = 4 * 1024 * 1024
export const enum TerminalBinaryKind {
input = 1,
@@ -27,6 +33,11 @@ export const enum TerminalBinaryKind {
* `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,
}
export interface TerminalBinaryClear {
@@ -80,6 +91,7 @@ function validKind(value: number): value is TerminalBinaryKind {
|| value === TerminalBinaryKind.keyframe
|| value === TerminalBinaryKind.sync
|| value === TerminalBinaryKind.paste
+ || value === TerminalBinaryKind.imagePaste
}
export function terminalBinaryType(kind: TerminalBinaryKind): string {
@@ -87,21 +99,23 @@ export function terminalBinaryType(kind: TerminalBinaryKind): string {
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'
return 'terminal_sync'
}
-/** The seal/parse/encode/decode size ceiling for [kind] — paste gets a much larger one; see
- * TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES. */
+/** The seal/parse/encode/decode size ceiling for [kind] — paste and imagePaste get a much larger
+ * one each; see TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES /
+ * TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES. */
function maxCiphertextBytesFor(kind: TerminalBinaryKind): number {
- return kind === TerminalBinaryKind.paste
- ? TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES
- : TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES
+ if (kind === TerminalBinaryKind.paste) return TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES
+ if (kind === TerminalBinaryKind.imagePaste) return TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES
+ return TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES
}
function maxLocalPayloadBytesFor(kind: TerminalBinaryKind): number {
- return kind === TerminalBinaryKind.paste
- ? TERMINAL_LOCAL_PASTE_MAX_PAYLOAD_BYTES
- : TERMINAL_LOCAL_MAX_PAYLOAD_BYTES
+ if (kind === TerminalBinaryKind.paste) return TERMINAL_LOCAL_PASTE_MAX_PAYLOAD_BYTES
+ if (kind === TerminalBinaryKind.imagePaste) return TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES
+ return TERMINAL_LOCAL_MAX_PAYLOAD_BYTES
}
export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | null {
@@ -111,7 +125,8 @@ export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | nu
// 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.compressed) return null
+ || frame.kind === TerminalBinaryKind.paste || frame.kind === TerminalBinaryKind.imagePaste)
+ && frame.compressed) return null
if (frame.kind === TerminalBinaryKind.sync && frame.bytes.length !== 0) return null
const metaBytes = frame.kind === TerminalBinaryKind.keyframe ? 28 : 24
const out = new Uint8Array(metaBytes + frame.bytes.length)
@@ -131,7 +146,7 @@ export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | nu
export function decodeTerminalPlain(kind: TerminalBinaryKind, flags: number, plaintext: Uint8Array): TerminalBinaryClear | null {
if ((flags & ~FLAG_ZLIB) !== 0
|| ((kind === TerminalBinaryKind.input || kind === TerminalBinaryKind.sync
- || kind === TerminalBinaryKind.paste) && flags !== 0)) return null
+ || kind === TerminalBinaryKind.paste || kind === TerminalBinaryKind.imagePaste) && flags !== 0)) return null
const metaBytes = kind === TerminalBinaryKind.keyframe ? 28 : 24
if (plaintext.length < metaBytes || (kind === TerminalBinaryKind.sync && plaintext.length !== metaBytes)) return null
const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength)
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 24eabb27e..a4a7a142b 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -5,6 +5,11 @@ import { TerminalStreamManager, terminalEngineCapabilities } from './terminalStr
import { TERMINAL_ACTION_SUCCEEDED, type TerminalStreamHandle, type TerminalStreamSink } from './terminalTypes.js'
import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'
+import { writeImageToOsClipboard, type OsClipboardImageResult } from './osClipboard.js'
+import { writePasteImageFile } from './pasteImageFiles.js'
+
+vi.mock('./osClipboard.js', () => ({ writeImageToOsClipboard: vi.fn() }))
+vi.mock('./pasteImageFiles.js', () => ({ writePasteImageFile: vi.fn() }))
class FakeStream implements TerminalStreamHandle {
readonly runtime = { backend: 'tmux' as const, paneId: '%1' }
@@ -78,6 +83,8 @@ describe('TerminalStreamManager', () => {
streamingAvailable: true,
now: () => Date.now(),
})
+ vi.mocked(writePasteImageFile).mockReset().mockResolvedValue('/fake/paste-images/fake.png')
+ vi.mocked(writeImageToOsClipboard).mockReset().mockResolvedValue({ state: 'written' })
})
afterEach(async () => {
@@ -216,6 +223,91 @@ describe('TerminalStreamManager', () => {
expect(stream.pastes).toHaveLength(3)
})
+ describe('image paste', () => {
+ const pngBytes = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)
+ const imagePaste = (streamId: string): TerminalBinaryClear => ({
+ kind: TerminalBinaryKind.imagePaste, streamId, seq: 0, compressed: false, bytes: pngBytes,
+ })
+
+ it('advertises imagePaste in terminal_capabilities', async () => {
+ await manager.handleFrame('web-1', 'terminal_capabilities', { requestId: 'r1' })
+ expect((sent.at(-1)?.payload.features as Record<string, unknown>).imagePaste).toBe(true)
+ })
+
+ it('rejects a legacy JSON terminal_paste_image the same way as terminal_paste', async () => {
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-img', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ const streamId = sent[0].payload.streamId as string
+ await manager.handleFrame('web-1', 'terminal_paste_image', { streamId })
+ expect(sent.at(-1)?.payload.code).toBe('TERMINAL_BINARY_REQUIRED')
+ })
+
+ it('on a successful clipboard write, replays a literal Ctrl+V and reports outcome "clipboard"', async () => {
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-img', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ const streamId = sent[0].payload.streamId as string
+
+ await manager.handleBinary('web-1', imagePaste(streamId))
+
+ expect(vi.mocked(writeImageToOsClipboard)).toHaveBeenCalledWith('/fake/paste-images/fake.png', pngBytes)
+ expect(stream.writes).toHaveLength(1)
+ expect(Buffer.from(stream.writes[0])).toEqual(Buffer.from([0x16])) // literal Ctrl+V
+ expect(stream.pastes).toHaveLength(0) // never goes through the text-paste path
+ const result = sent.at(-1)!
+ expect(result.type).toBe('terminal_paste_image_result')
+ expect(result.payload).toMatchObject({ streamId, outcome: 'clipboard' })
+ })
+
+ it('falls back to pasting the file path as text when no native clipboard is reachable', async () => {
+ vi.mocked(writeImageToOsClipboard).mockResolvedValue(
+ { state: 'unavailable', reason: 'no X11 or Wayland display on this machine' } satisfies OsClipboardImageResult,
+ )
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-img2', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ const streamId = sent[0].payload.streamId as string
+
+ await manager.handleBinary('web-1', imagePaste(streamId))
+
+ expect(stream.writes).toHaveLength(0) // no Ctrl+V — nothing was put on a clipboard
+ expect(stream.pastes).toEqual(['/fake/paste-images/fake.png'])
+ const result = sent.at(-1)!
+ expect(result.type).toBe('terminal_paste_image_result')
+ expect(result.payload).toMatchObject({
+ streamId, outcome: 'fallback_path', reason: 'no X11 or Wayland display on this machine',
+ })
+ })
+
+ it('reports a genuine clipboard-write failure as an error, not a silent no-op', async () => {
+ vi.mocked(writeImageToOsClipboard).mockResolvedValue(
+ { state: 'failed', reason: 'xclip exited with code 1' } satisfies OsClipboardImageResult,
+ )
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-img3', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ const streamId = sent[0].payload.streamId as string
+
+ await manager.handleBinary('web-1', imagePaste(streamId))
+
+ expect(stream.writes).toHaveLength(0)
+ expect(stream.pastes).toHaveLength(0)
+ expect(sent.at(-1)?.payload).toMatchObject({
+ code: 'TERMINAL_PASTE_IMAGE_FAILED', streamId, message: 'xclip exited with code 1',
+ })
+ })
+
+ it('ignores an empty image paste', async () => {
+ await manager.handleFrame('web-1', 'terminal_open', {
+ requestId: 'open-img4', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
+ })
+ const streamId = sent[0].payload.streamId as string
+ await manager.handleBinary('web-1', { kind: TerminalBinaryKind.imagePaste, streamId, seq: 0, compressed: false, bytes: new Uint8Array() })
+ expect(vi.mocked(writePasteImageFile)).not.toHaveBeenCalled()
+ })
+ })
+
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 16b212bd7..bf4990439 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -1,12 +1,21 @@
import { randomUUID } from 'node:crypto'
+import { unlink } from 'node:fs/promises'
import { deflateSync } from 'node:zlib'
import { ENGINES } from '../engines/types.js'
import type { RegisteredSession } from './registry.js'
+import { writeImageToOsClipboard } from './osClipboard.js'
+import { writePasteImageFile } from './pasteImageFiles.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'
+/** Ctrl+V as a literal byte (ASCII SUB, 0x16) — the same nudge a real Ctrl+V keystroke sends down
+ * the ordinary keystroke pipe. Written after the OS clipboard write below succeeds, so the engine
+ * attached to the pane reads its OWN OS clipboard exactly as it already does for a locally-driven
+ * session — see `pasteImage()`. */
+const CTRL_V_BYTE = Uint8Array.of(0x16)
+
type FramePayload = Record<string, unknown>
const PROTOCOL_VERSION = 3
@@ -150,9 +159,10 @@ export class TerminalStreamManager {
await this.resize(connId, payload)
return true
case 'terminal_paste':
- // Same reason as terminal_input: a paste is a binary frame (TerminalBinaryKind.paste) so it
- // rides the same AEAD channel every other terminal byte does, which is what makes it safe to
- // deliver over a relayed (E2EE) connection. Nothing sends this as JSON.
+ case 'terminal_paste_image':
+ // Same reason as terminal_input: a paste is a binary frame (TerminalBinaryKind.paste /
+ // .imagePaste) so it rides the same AEAD channel every other terminal byte does, which is
+ // what makes it safe to deliver over a relayed (E2EE) connection. Nothing sends this as JSON.
this.sendError(connId, 'TERMINAL_BINARY_REQUIRED', { streamId: typeof payload.streamId === 'string' ? payload.streamId : undefined })
return true
case 'terminal_scroll':
@@ -170,9 +180,14 @@ export class TerminalStreamManager {
}
async handleBinary(connId: string, frame: TerminalBinaryClear): Promise<void> {
- if (frame.kind !== TerminalBinaryKind.input && frame.kind !== TerminalBinaryKind.paste) return
+ if (frame.kind !== TerminalBinaryKind.input && frame.kind !== TerminalBinaryKind.paste
+ && frame.kind !== TerminalBinaryKind.imagePaste) return
const state = this.streams.get(frame.streamId)
if (!state || state.connId !== connId || state.closing) return
+ if (frame.kind === TerminalBinaryKind.imagePaste) {
+ await this.pasteImage(state, frame.bytes)
+ return
+ }
if (frame.kind === TerminalBinaryKind.paste) {
await this.paste(state, frame.bytes)
return
@@ -197,6 +212,10 @@ export class TerminalStreamManager {
// 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,
+ // A client old enough to predate `TerminalBinaryKind.imagePaste` must keep forwarding a bare
+ // Ctrl+V and hoping the engine's own clipboard read finds something local — see
+ // `pasteImage()` for the frame this unlocks.
+ imagePaste: true,
},
engines: terminalEngineCapabilities(this.deps.streamingAvailable),
})
@@ -449,6 +468,69 @@ export class TerminalStreamManager {
}
}
+ /**
+ * A clipboard IMAGE paste (raw PNG bytes) — writes the bytes into THIS machine's own OS
+ * clipboard (see osClipboard.ts), then replays a literal Ctrl+V so whichever engine is attached
+ * to the pane reads that clipboard exactly as it already does for a locally-driven session.
+ * Nothing here is engine-specific: this only bridges the clipboard and the keystroke, the same
+ * way `paste()` only bridges a clipboard string into the pty.
+ *
+ * When no native clipboard is reachable right now (the clipboard tool isn't installed, or this
+ * is a genuinely headless Linux box with no X11/Wayland session at all), this does not fail —
+ * it falls back to pasting the image's file PATH as plain text through the exact same
+ * `pasteRaw` call `paste()` uses, so the user/engine can still get at the image, just not via
+ * the OS clipboard. The client is told which happened (`terminal_paste_image_result`) so it can
+ * show the right feedback instead of a silent difference in behavior.
+ */
+ private async pasteImage(state: ActiveStream, bytes: Uint8Array): Promise<void> {
+ if (bytes.length === 0) return
+ state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
+ let path: string
+ try {
+ path = await writePasteImageFile(bytes)
+ } catch (error) {
+ this.sendError(state.connId, 'TERMINAL_PASTE_IMAGE_FAILED', {
+ streamId: state.streamId,
+ message: error instanceof Error ? error.message : 'could not save the pasted image',
+ })
+ return
+ }
+ const clipboard = await writeImageToOsClipboard(path, bytes)
+ if (clipboard.state === 'written') {
+ // The OS clipboard now owns the bytes — the file was only a hand-off.
+ void unlink(path).catch(() => { /* best effort */ })
+ const result = await state.handle.writeRaw(CTRL_V_BYTE)
+ if (result.state !== 'succeeded') {
+ this.sendError(state.connId, 'TERMINAL_PASTE_IMAGE_FAILED', { streamId: state.streamId, message: result.reason })
+ if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state)
+ return
+ }
+ this.deps.sendTarget(state.connId, 'terminal_paste_image_result', {
+ streamId: state.streamId,
+ outcome: 'clipboard',
+ })
+ return
+ }
+ if (clipboard.state === 'failed') {
+ this.sendError(state.connId, 'TERMINAL_PASTE_IMAGE_FAILED', { streamId: state.streamId, message: clipboard.reason })
+ void unlink(path).catch(() => { /* best effort */ })
+ return
+ }
+ // 'unavailable' — no native clipboard right now. Fall back to the file's path as ordinary text,
+ // and keep the file: it has to keep resolving after this call returns.
+ const result = await state.handle.pasteRaw(path)
+ if (result.state !== 'succeeded') {
+ this.sendError(state.connId, 'TERMINAL_PASTE_IMAGE_FAILED', { streamId: state.streamId, message: result.reason })
+ if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state)
+ return
+ }
+ this.deps.sendTarget(state.connId, 'terminal_paste_image_result', {
+ streamId: state.streamId,
+ outcome: 'fallback_path',
+ reason: clipboard.reason,
+ })
+ }
+
/** 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