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 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 * 1024export 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 * 1024export 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 nullif (frame.kind === TerminalBinaryKind.sync && frame.bytes.length !== 0) return nullconst metaBytes = frame.kind === TerminalBinaryKind.keyframe ? 28 : 24const out = new Uint8Array(metaBytes + frame.bytes.length)@@ -131,7 +146,7 @@ export function encodeTerminalPlain(frame: TerminalBinaryClear): Uint8Array | nuexport 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 nullconst metaBytes = kind === TerminalBinaryKind.keyframe ? 28 : 24if (plaintext.length < metaBytes || (kind === TerminalBinaryKind.sync && plaintext.length !== metaBytes)) return nullconst view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength)diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex 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 './terminalStrimport { 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.tsindex 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 truecase '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 truecase '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) returnconst 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