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
refactor: implement chunked terminal uploads and remove legacy paste payload encoding
0xken153ca13e631679
diff --git a/cli/src/lib/terminalBinary.spec.ts b/cli/src/lib/terminalBinary.spec.tsindex dbbeb1a37..c229deee2 100644--- a/cli/src/lib/terminalBinary.spec.ts+++ b/cli/src/lib/terminalBinary.spec.ts@@ -1,9 +1,7 @@import { describe, expect, it } from 'vitest'import {deriveTerminalBinaryKey,- decodePasteFilePayload,decodeTerminalLocal,- encodePasteFilePayload,encodeTerminalLocal,openTerminalBinary,parseTerminalBinaryEnvelope,@@ -166,23 +164,22 @@ describe('terminal binary protocol v3', () => {})).toBeNull()})- it('round-trips a pasteFile payload (filename + content) at its own ceiling', () => {- const payload = encodePasteFilePayload('report.pdf', Uint8Array.of(0x25, 0x50, 0x44, 0x46))!- expect(payload).not.toBeNull()+ it('round-trips a pasteFile chunk (raw bytes, seq is the chunk index) at its own ceiling', () => {+ const chunk = Uint8Array.of(0x25, 0x50, 0x44, 0x46)const sealed = sealTerminalBinary(key, 30, {kind: TerminalBinaryKind.pasteFile,streamId,- seq: 0,- bytes: payload,+ seq: 3,+ bytes: chunk,compressed: false,})!expect(sealed).not.toBeNull()expect(openTerminalBinary(key, sealed)?.frame).toEqual({kind: TerminalBinaryKind.pasteFile,streamId,- seq: 0,- bytes: payload,+ seq: 3,+ bytes: chunk,compressed: false,})@@ -316,20 +313,23 @@ describe('authenticated loopback terminal framing v1', () => {})).toBeNull()})- it('carries a pasteFile well past the ordinary local frame ceiling, independent of paste/imagePaste', () => {+ it('carries a pasteFile chunk well past the ordinary local frame ceiling, independent of paste/imagePaste', () => {+ // A single chunk is capped at UPLOAD_CHUNK_BYTES (256 KiB) in practice, but the WIRE ceiling+ // itself is still the whole-upload one — this proves the kind-specific ceiling still applies+ // at the framing layer regardless of how the CLI's application logic chunks it.const content = new Uint8Array(2 * 1024 * 1024).fill(0xcd)- const payload = encodePasteFilePayload('archive.zip', content)!const encoded = encodeTerminalLocal({kind: TerminalBinaryKind.pasteFile,streamId,- seq: 0,- bytes: payload,+ seq: 2,+ bytes: content,compressed: false,})expect(encoded).not.toBeNull()const decoded = decodeTerminalLocal(encoded!)expect(decoded?.kind).toBe(TerminalBinaryKind.pasteFile)- expect(decodePasteFilePayload(decoded!.bytes)).toEqual({ filename: 'archive.zip', content })+ expect(decoded?.seq).toBe(2)+ expect(decoded?.bytes).toEqual(content)const tooBig = new Uint8Array(TERMINAL_LOCAL_PASTE_FILE_MAX_PAYLOAD_BYTES + 1)expect(encodeTerminalLocal({@@ -341,25 +341,3 @@ describe('authenticated loopback terminal framing v1', () => {})).toBeNull()})})--describe('pasteFile payload sub-format', () => {- it('round-trips filename + content', () => {- const content = Uint8Array.of(1, 2, 3, 4, 5)- const payload = encodePasteFilePayload('xin chào.txt', content)!- expect(payload).not.toBeNull()- expect(decodePasteFilePayload(payload)).toEqual({ filename: 'xin chào.txt', content })- })-- it('rejects an empty filename', () => {- expect(encodePasteFilePayload('', Uint8Array.of(1))).toBeNull()- })-- it('rejects malformed/truncated payloads', () => {- expect(decodePasteFilePayload(new Uint8Array(0))).toBeNull()- expect(decodePasteFilePayload(Uint8Array.of(0, 0))).toBeNull() // zero-length filename- // Claims a 10-byte filename but supplies none.- const truncated = new Uint8Array(2)- new DataView(truncated.buffer).setUint16(0, 10, false)- expect(decodePasteFilePayload(truncated)).toBeNull()- })-})diff --git a/cli/src/lib/terminalBinary.ts b/cli/src/lib/terminalBinary.tsindex 071a9e0ac..20e8dc29d 100644--- a/cli/src/lib/terminalBinary.ts+++ b/cli/src/lib/terminalBinary.ts@@ -261,34 +261,6 @@ export function decodeTerminalLocal(raw: Uint8Array): TerminalBinaryClear | nullreturn decodeTerminalPlain(kind, flags, bytes.slice(TERMINAL_LOCAL_HEADER_BYTES))}-/** `pasteFile`'s payload (the frame's opaque `bytes`) is itself a tiny sub-format: a 2-byte- * big-endian filename length, the UTF-8 filename, then the file's own content — one small header- * inside the existing opaque `bytes` field, so the outer frame format needs no changes for this. */-export function encodePasteFilePayload(filename: string, content: Uint8Array): Uint8Array | null {- const nameBytes = utf8(filename)- if (nameBytes.length === 0 || nameBytes.length > 0xffff) return null- const out = new Uint8Array(2 + nameBytes.length + content.length)- const view = new DataView(out.buffer)- view.setUint16(0, nameBytes.length, false)- out.set(nameBytes, 2)- out.set(content, 2 + nameBytes.length)- return out-}--export function decodePasteFilePayload(payload: Uint8Array): { filename: string; content: Uint8Array } | null {- if (payload.length < 2) return null- const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength)- const nameLength = view.getUint16(0, false)- if (nameLength === 0 || payload.length < 2 + nameLength) return null- let filename: string- try {- filename = new TextDecoder('utf-8', { fatal: true }).decode(payload.subarray(2, 2 + nameLength))- } catch {- return null- }- return { filename, content: payload.subarray(2 + nameLength) }-}-export const enum TerminalHopDirection {down = 1,up = 2,diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.tsindex d61a0b401..610884171 100644--- a/cli/src/lib/terminalStreamManager.spec.ts+++ b/cli/src/lib/terminalStreamManager.spec.ts@@ -1,10 +1,10 @@import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import { ENGINES } from '../engines/types.js'import type { RegisteredSession } from './registry.js'-import { TerminalStreamManager, terminalEngineCapabilities } from './terminalStreamManager.js'+import { TerminalStreamManager, terminalEngineCapabilities, UPLOAD_CHUNK_BYTES } from './terminalStreamManager.js'import { TERMINAL_ACTION_SUCCEEDED, type TerminalStreamHandle, type TerminalStreamSink } from './terminalTypes.js'import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'-import { encodePasteFilePayload, TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'+import { TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'import { writeImageToOsClipboard, type OsClipboardImageResult } from './osClipboard.js'import { writePasteDropFile, writePasteImageFile } from './pasteDropFiles.js'@@ -224,58 +224,148 @@ describe('TerminalStreamManager', () => {expect(stream.pastes).toHaveLength(3)})- describe('image paste', () => {+ describe('chunked image/file upload', () => {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,- })+ const fileContent = Uint8Array.of(0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34)++ async function openStream(requestId = 'open'): Promise<string> {+ await manager.handleFrame('web-1', 'terminal_open', {+ requestId, protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,+ })+ return sent.findLast((f) => f.type === 'terminal_ready')!.payload.streamId as string+ }- it('advertises imagePaste in terminal_capabilities', async () => {+ function begin(streamId: string, fields: Record<string, unknown>): Promise<boolean> {+ return manager.handleFrame('web-1', 'terminal_chunked_upload_begin', { streamId, ...fields })+ }++ function chunk(streamId: string, kind: TerminalBinaryKind.imagePaste | TerminalBinaryKind.pasteFile, seq: number, bytes: Uint8Array): Promise<void> {+ return manager.handleBinary('web-1', { kind, streamId, seq, compressed: false, bytes })+ }++ function lastResult(): { connId: string; type: string; payload: Record<string, unknown> } {+ return sent.at(-1)!+ }++ it('advertises imagePaste and pasteFile 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)+ const features = sent.at(-1)?.payload.features as Record<string, unknown>+ expect(features.imagePaste).toBe(true)+ expect(features.pasteFile).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+ it('rejects legacy JSON terminal_paste_image/terminal_paste_file the same way as terminal_paste', async () => {+ const streamId = await openStream()await manager.handleFrame('web-1', 'terminal_paste_image', { streamId })- expect(sent.at(-1)?.payload.code).toBe('TERMINAL_BINARY_REQUIRED')+ expect(lastResult().payload.code).toBe('TERMINAL_BINARY_REQUIRED')+ await manager.handleFrame('web-1', 'terminal_paste_file', { streamId })+ expect(lastResult().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+ it('accepts a begin, reports progress per chunk, and finishes an image via the clipboard', async () => {+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })+ expect(lastResult()).toMatchObject({ type: 'terminal_chunked_upload_begin_result', payload: { streamId, accepted: true } })++ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)- await manager.handleBinary('web-1', imagePaste(streamId))+ const progress = sent.filter((f) => f.type === 'terminal_chunked_upload_progress')+ expect(progress).toHaveLength(1)+ expect(progress[0].payload).toMatchObject({ streamId, bytesWritten: pngBytes.length, totalBytes: pngBytes.length })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')+ const result = sent.findLast((f) => f.type === 'terminal_paste_image_result')!expect(result.payload).toMatchObject({ streamId, outcome: 'clipboard' })})+ // Real chunk boundaries, not arbitrary test-only slicing: every chunk but the last is exactly+ // UPLOAD_CHUNK_BYTES, matching how a real client actually splits an upload — the daemon's own+ // per-chunk validation rejects a seq beyond `ceil(totalBytes / UPLOAD_CHUNK_BYTES)`.+ const CHUNK = UPLOAD_CHUNK_BYTES++ it('assembles multiple chunks in order across several progress events', async () => {+ const streamId = await openStream()+ const big = new Uint8Array(CHUNK * 2 + 100).fill(0xab)+ await begin(streamId, { uploadKind: 'image', totalBytes: big.length })++ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, big.subarray(0, CHUNK))+ await chunk(streamId, TerminalBinaryKind.imagePaste, 1, big.subarray(CHUNK, CHUNK * 2))+ await chunk(streamId, TerminalBinaryKind.imagePaste, 2, big.subarray(CHUNK * 2, big.length))++ const progress = sent.filter((f) => f.type === 'terminal_chunked_upload_progress')+ expect(progress.map((f) => f.payload.bytesWritten)).toEqual([CHUNK, CHUNK * 2, big.length])+ expect(vi.mocked(writeImageToOsClipboard)).toHaveBeenCalledWith('/fake/paste-images/fake.png', big)+ })++ it('tolerates chunks arriving out of order', async () => {+ const streamId = await openStream()+ const big = new Uint8Array(CHUNK * 2 + 50).fill(0xcd)+ await begin(streamId, { uploadKind: 'image', totalBytes: big.length })++ await chunk(streamId, TerminalBinaryKind.imagePaste, 1, big.subarray(CHUNK, CHUNK * 2))+ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, big.subarray(0, CHUNK))+ await chunk(streamId, TerminalBinaryKind.imagePaste, 2, big.subarray(CHUNK * 2, big.length))++ expect(vi.mocked(writeImageToOsClipboard)).toHaveBeenCalledWith('/fake/paste-images/fake.png', big)+ })++ it('ignores a re-sent chunk (same seq) rather than double-counting its bytes', async () => {+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length * 2 })+ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)+ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes) // duplicate++ const progress = sent.filter((f) => f.type === 'terminal_chunked_upload_progress')+ expect(progress.every((f) => f.payload.bytesWritten === pngBytes.length)).toBe(true)+ expect(vi.mocked(writeImageToOsClipboard)).not.toHaveBeenCalled() // still short of totalBytes+ })++ it('finishes a file upload by writing it under its original name and pasting the path — never the clipboard', async () => {+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'file', filename: 'report.pdf', totalBytes: fileContent.length })+ await chunk(streamId, TerminalBinaryKind.pasteFile, 0, fileContent)++ expect(vi.mocked(writePasteDropFile)).toHaveBeenCalledWith('report.pdf', fileContent)+ expect(vi.mocked(writeImageToOsClipboard)).not.toHaveBeenCalled()+ expect(stream.writes).toHaveLength(0) // no Ctrl+V replay for a file+ expect(stream.pastes).toEqual(['/fake/paste-drops/id-report.pdf'])+ const result = sent.findLast((f) => f.type === 'terminal_paste_file_result')!+ expect(result.payload).toMatchObject({ streamId, path: '/fake/paste-drops/id-report.pdf' })+ })++ it('rejects a begin with no filename for a file upload', async () => {+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'file', totalBytes: fileContent.length })+ expect(lastResult().payload).toMatchObject({ streamId, accepted: false })+ })++ it('rejects a begin over the per-kind size ceiling before any chunk is sent', async () => {+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'image', totalBytes: 4 * 1024 * 1024 + 1 })+ expect(lastResult().payload).toMatchObject({ streamId, accepted: false })+ expect(sent.some((f) => f.type === 'terminal_chunked_upload_progress')).toBe(false)+ })++ it('rejects a second begin while one upload is already in progress on the same pane', async () => {+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })+ await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })+ expect(lastResult().payload).toMatchObject({ streamId, accepted: false })+ })+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))+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })+ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)expect(stream.writes).toHaveLength(0) // no Ctrl+V — nothing was put on a clipboardexpect(stream.pastes).toEqual(['/fake/paste-images/fake.png'])- const result = sent.at(-1)!- expect(result.type).toBe('terminal_paste_image_result')+ const result = sent.findLast((f) => f.type === 'terminal_paste_image_result')!expect(result.payload).toMatchObject({streamId, outcome: 'fallback_path', reason: 'no X11 or Wayland display on this machine',})@@ -285,103 +375,50 @@ describe('TerminalStreamManager', () => {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))+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })+ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)expect(stream.writes).toHaveLength(0)expect(stream.pastes).toHaveLength(0)- expect(sent.at(-1)?.payload).toMatchObject({+ expect(sent.findLast((f) => f.type === 'terminal_error')?.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()- })- })-- describe('file paste (dropped non-image file)', () => {- const fileContent = Uint8Array.of(0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34)- const pasteFile = (streamId: string, filename = 'report.pdf'): TerminalBinaryClear => ({- kind: TerminalBinaryKind.pasteFile, streamId, seq: 0, compressed: false,- bytes: encodePasteFilePayload(filename, fileContent)!,- })-- it('advertises pasteFile in terminal_capabilities', async () => {- await manager.handleFrame('web-1', 'terminal_capabilities', { requestId: 'r1' })- expect((sent.at(-1)?.payload.features as Record<string, unknown>).pasteFile).toBe(true)- })+ it('reports a genuine file write failure as an error', async () => {+ vi.mocked(writePasteDropFile).mockRejectedValue(new Error('disk full'))+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'file', filename: 'report.pdf', totalBytes: fileContent.length })+ await chunk(streamId, TerminalBinaryKind.pasteFile, 0, fileContent)- it('rejects a legacy JSON terminal_paste_file the same way as terminal_paste/terminal_paste_image', async () => {- await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-file', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,+ expect(stream.pastes).toHaveLength(0)+ expect(sent.findLast((f) => f.type === 'terminal_error')?.payload).toMatchObject({+ code: 'TERMINAL_PASTE_FILE_FAILED', streamId, message: 'disk full',})- const streamId = sent[0].payload.streamId as string- await manager.handleFrame('web-1', 'terminal_paste_file', { streamId })- expect(sent.at(-1)?.payload.code).toBe('TERMINAL_BINARY_REQUIRED')})- it('writes the file under its original name and pastes the resulting path as text — never the clipboard', async () => {- await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-file', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,- })- const streamId = sent[0].payload.streamId as string-- await manager.handleBinary('web-1', pasteFile(streamId))-- expect(vi.mocked(writePasteDropFile)).toHaveBeenCalledWith('report.pdf', fileContent)- expect(vi.mocked(writeImageToOsClipboard)).not.toHaveBeenCalled() // no clipboard attempt at all- expect(stream.writes).toHaveLength(0) // no Ctrl+V replay either- expect(stream.pastes).toEqual(['/fake/paste-drops/id-report.pdf'])- const result = sent.at(-1)!- expect(result.type).toBe('terminal_paste_file_result')- expect(result.payload).toMatchObject({ streamId, path: '/fake/paste-drops/id-report.pdf' })+ it('ignores a chunk with no matching begin', async () => {+ const streamId = await openStream()+ await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)+ expect(vi.mocked(writeImageToOsClipboard)).not.toHaveBeenCalled()+ expect(sent.some((f) => f.type === 'terminal_chunked_upload_progress')).toBe(false)})- it('rejects a malformed payload (bad filename-length header) without touching disk', async () => {- await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-file2', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,- })- const streamId = sent[0].payload.streamId as string-- await manager.handleBinary('web-1', {- kind: TerminalBinaryKind.pasteFile, streamId, seq: 0, compressed: false,- bytes: Uint8Array.of(0xff, 0xff, 1, 2), // claims a 65535-byte filename, supplies 2 bytes- })+ it('cancel discards the in-flight upload without writing or pasting anything', async () => {+ const streamId = await openStream()+ await begin(streamId, { uploadKind: 'file', filename: 'report.pdf', totalBytes: fileContent.length * 2 })+ await chunk(streamId, TerminalBinaryKind.pasteFile, 0, fileContent)+ await manager.handleFrame('web-1', 'terminal_chunked_upload_cancel', { streamId })+ // A late-arriving second chunk after cancel must not resurrect the upload.+ await chunk(streamId, TerminalBinaryKind.pasteFile, 1, fileContent)expect(vi.mocked(writePasteDropFile)).not.toHaveBeenCalled()- expect(sent.at(-1)?.payload.code).toBe('TERMINAL_PASTE_FILE_INVALID')- })-- it('reports a genuine write failure as an error', async () => {- vi.mocked(writePasteDropFile).mockRejectedValue(new Error('disk full'))- await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-file3', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,- })- const streamId = sent[0].payload.streamId as string-- await manager.handleBinary('web-1', pasteFile(streamId))-expect(stream.pastes).toHaveLength(0)- expect(sent.at(-1)?.payload).toMatchObject({ code: 'TERMINAL_PASTE_FILE_FAILED', streamId, message: 'disk full' })- })- it('ignores an empty file paste', async () => {- await manager.handleFrame('web-1', 'terminal_open', {- requestId: 'open-file4', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,- })- const streamId = sent[0].payload.streamId as string- await manager.handleBinary('web-1', { kind: TerminalBinaryKind.pasteFile, streamId, seq: 0, compressed: false, bytes: new Uint8Array() })- expect(vi.mocked(writePasteDropFile)).not.toHaveBeenCalled()+ // And a fresh begin afterwards works normally — cancel actually cleared the slot.+ await begin(streamId, { uploadKind: 'file', filename: 'retry.pdf', totalBytes: fileContent.length })+ expect(lastResult().payload).toMatchObject({ streamId, accepted: true })})})diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.tsindex cacb26d6a..13d0159ba 100644--- a/cli/src/lib/terminalStreamManager.ts+++ b/cli/src/lib/terminalStreamManager.ts@@ -8,7 +8,12 @@ import { writePasteDropFile, writePasteImageFile } from './pasteDropFiles.js'import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'import { terminalPlacementKey, terminalRouteKey } from './terminalRuntime.js'import type { TerminalStreamHandle, TerminalStreamSize } from './terminalTypes.js'-import { decodePasteFilePayload, TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'+import {+ TerminalBinaryKind,+ TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES,+ TERMINAL_LOCAL_PASTE_FILE_MAX_PAYLOAD_BYTES,+ 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@@ -16,6 +21,26 @@ import { decodePasteFilePayload, TerminalBinaryKind, type TerminalBinaryClear }* session — see `pasteImage()`. */const CTRL_V_BYTE = Uint8Array.of(0x16)+/** Per-chunk size for a chunked image/file upload — comfortably under the 512 KiB per-binary-message+ * ceiling shared by the backend relay and the P2P data channel (with AEAD/framing overhead room to+ * spare), and large enough that a 4 MB image is ~16 chunks / a 10 MB file ~40. Deliberately NOT a+ * credit/window scheme like the firmware pusher's (cli/src/cable/fwPush.ts) — that exists because+ * USB Serial/JTAG has no real backpressure; a WebSocket already backpressures at the socket layer,+ * so the client just sends chunks back-to-back. Mirrors the Dart client's own chunk size — keep+ * the two in step. */+export const UPLOAD_CHUNK_BYTES = 256 * 1024++interface PendingUpload {+ kind: TerminalBinaryKind.imagePaste | TerminalBinaryKind.pasteFile+ /** Only meaningful (and required) for a `pasteFile` upload. */+ filename?: string+ totalBytes: number+ expectedChunks: number+ /** Indexed by chunk seq; sparse until every chunk has arrived. */+ chunks: (Buffer | undefined)[]+ bytesReceived: number+}+type FramePayload = Record<string, unknown>const PROTOCOL_VERSION = 3@@ -69,6 +94,7 @@ interface ActiveStream {peakBufferedBytes: numberpausedAt: number | nullpausedMs: number+ pendingUpload: PendingUpload | null}export interface TerminalStreamManagerDeps {@@ -167,6 +193,12 @@ export class TerminalStreamManager {// sends this as JSON.this.sendError(connId, 'TERMINAL_BINARY_REQUIRED', { streamId: typeof payload.streamId === 'string' ? payload.streamId : undefined })return true+ case 'terminal_chunked_upload_begin':+ this.beginChunkedUpload(connId, payload)+ return true+ case 'terminal_chunked_upload_cancel':+ this.cancelChunkedUpload(connId, payload)+ return truecase 'terminal_scroll':await this.scroll(connId, payload)return true@@ -186,12 +218,8 @@ export class TerminalStreamManager {&& frame.kind !== TerminalBinaryKind.imagePaste && frame.kind !== TerminalBinaryKind.pasteFile) 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.pasteFile) {- await this.pasteFile(state, frame.bytes)+ if (frame.kind === TerminalBinaryKind.imagePaste || frame.kind === TerminalBinaryKind.pasteFile) {+ await this.receiveUploadChunk(state, frame.kind, frame.seq, frame.bytes)return}if (frame.kind === TerminalBinaryKind.paste) {@@ -363,6 +391,7 @@ export class TerminalStreamManager {peakBufferedBytes: 0,pausedAt: null,pausedMs: 0,+ pendingUpload: null,}this.streams.set(streamId, state)if (!this.deps.sendTarget(connId, 'terminal_ready', {@@ -479,11 +508,12 @@ 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.+ * A clipboard IMAGE paste (raw PNG bytes, already fully assembled from a chunked upload — see+ * `receiveUploadChunk`) — 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 —@@ -542,24 +572,19 @@ export class TerminalStreamManager {}/**- * A dropped (non-image) FILE — writes it to disk on THIS machine (under its original name, see+ * A dropped (non-image) FILE (bytes already fully assembled from a chunked upload — see+ * `receiveUploadChunk`) — writes it to disk on THIS machine (under its original name, see* `writePasteDropFile`) and pastes that path as plain text, the same `pasteRaw` call `paste()`* uses. Unlike `pasteImage()`, there is no OS-clipboard attempt and no Ctrl+V replay: the goal* here is only "the pane gets a valid path", not "the engine auto-attaches this" — a client only* sends this at all for a genuinely REMOTE pane (a local one pastes its own already-valid path* without ever reaching the wire), so there is no local/remote branch to make here either.*/- private async pasteFile(state: ActiveStream, payload: Uint8Array): Promise<void> {- if (payload.length === 0) return- const decoded = decodePasteFilePayload(payload)- if (!decoded) {- this.sendError(state.connId, 'TERMINAL_PASTE_FILE_INVALID', { streamId: state.streamId, message: 'malformed file paste payload' })- return- }+ private async pasteFile(state: ActiveStream, filename: string, bytes: Uint8Array): Promise<void> {state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MSlet path: stringtry {- path = await writePasteDropFile(decoded.filename, decoded.content)+ path = await writePasteDropFile(filename, bytes)} catch (error) {this.sendError(state.connId, 'TERMINAL_PASTE_FILE_FAILED', {streamId: state.streamId,@@ -576,6 +601,114 @@ export class TerminalStreamManager {this.deps.sendTarget(state.connId, 'terminal_paste_file_result', { streamId: state.streamId, path })}+ /**+ * Announces a new chunked image/file upload for this stream — see UPLOAD_CHUNK_BYTES's doc for+ * why this is chunked at all (a per-binary-message ceiling shared by the backend relay and the+ * P2P data channel) rather than the single atomic frame `imagePaste`/`pasteFile` used to be.+ * Validated and either accepted or rejected up front, before any chunk is sent, so a client on a+ * slow link finds out immediately rather than after transferring several MB for nothing.+ */+ private beginChunkedUpload(connId: string, payload: FramePayload): void {+ const state = this.streamFor(connId, payload)+ if (!state) return+ const streamId = state.streamId+ const reject = (reason: string): void => {+ this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', { streamId, accepted: false, reason })+ }+ const uploadKind = payload.uploadKind === 'image' ? TerminalBinaryKind.imagePaste+ : payload.uploadKind === 'file' ? TerminalBinaryKind.pasteFile+ : null+ const totalBytes = Number(payload.totalBytes)+ const filename = typeof payload.filename === 'string' ? payload.filename : undefined+ if (!uploadKind || !Number.isSafeInteger(totalBytes) || totalBytes <= 0+ || (uploadKind === TerminalBinaryKind.pasteFile && !filename)) {+ reject('malformed upload request')+ return+ }+ if (state.pendingUpload) {+ reject('an upload is already in progress on this pane')+ return+ }+ const ceiling = uploadKind === TerminalBinaryKind.imagePaste+ ? TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES+ : TERMINAL_LOCAL_PASTE_FILE_MAX_PAYLOAD_BYTES+ if (totalBytes > ceiling) {+ reject(`exceeds the ${Math.floor(ceiling / (1024 * 1024))} MB limit`)+ return+ }+ state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS+ state.pendingUpload = {+ kind: uploadKind,+ filename,+ totalBytes,+ expectedChunks: Math.ceil(totalBytes / UPLOAD_CHUNK_BYTES),+ chunks: [],+ bytesReceived: 0,+ }+ this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', { streamId, accepted: true })+ }++ /** The user's own Cancel — stop and discard whatever has arrived so far. Nothing has been+ * written to disk yet at this point (chunks are only assembled and handed off once every one+ * has arrived), so there is no partial file to clean up — just drop the in-memory buffer. */+ private cancelChunkedUpload(connId: string, payload: FramePayload): void {+ const state = this.streamFor(connId, payload)+ if (!state) return+ state.pendingUpload = null+ }++ /**+ * One chunk of an in-flight upload announced by `beginChunkedUpload`. `seq` is the chunk index+ * (not an ordered keystroke sequence the way `input()`'s is) — stored by index rather than+ * assumed in-order, since nothing guarantees frame ordering survives a relay hop-by-hop, though+ * in practice it should. A stray chunk with no matching (or a kind-mismatched) `pendingUpload` is+ * ignored rather than errored: it most likely means a cancel or a previous upload's tail-end+ * arrived late.+ *+ * Progress is acked once per chunk, after it is durably held here — matching the firmware+ * pusher's philosophy (`fwPush.ts`'s `fw.progress`) of reporting confirmed receipt, not merely+ * "sent", which is what makes the client's percentage honest on a slow link. Once every expected+ * byte has arrived, this hands the assembled bytes to the SAME finishing logic `pasteImage`/+ * `pasteFile` already had before this feature existed — only how the bytes arrived changed.+ */+ private async receiveUploadChunk(+ state: ActiveStream,+ kind: TerminalBinaryKind.imagePaste | TerminalBinaryKind.pasteFile,+ seq: number,+ bytes: Uint8Array,+ ): Promise<void> {+ const pending = state.pendingUpload+ if (!pending || pending.kind !== kind) return+ if (!Number.isSafeInteger(seq) || seq < 0 || seq >= pending.expectedChunks+ || bytes.length === 0 || bytes.length > UPLOAD_CHUNK_BYTES) {+ this.sendError(state.connId, 'TERMINAL_CHUNKED_UPLOAD_INVALID', { streamId: state.streamId, message: 'malformed upload chunk' })+ state.pendingUpload = null+ return+ }+ state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS+ if (pending.chunks[seq] === undefined) {+ pending.chunks[seq] = Buffer.from(bytes)+ pending.bytesReceived += bytes.length+ }+ this.deps.sendTarget(state.connId, 'terminal_chunked_upload_progress', {+ streamId: state.streamId,+ bytesWritten: pending.bytesReceived,+ totalBytes: pending.totalBytes,+ })+ if (pending.bytesReceived < pending.totalBytes) return+ state.pendingUpload = null+ // A plain Uint8Array, not a Buffer — pasteImage/pasteFile hand this to code (osClipboard,+ // pasteDropFiles) written against the same Uint8Array shape the old atomic frame's `bytes`+ // always was, and callers/tests comparing against a Uint8Array must not have to know this+ // path happens to assemble through Buffer internally.+ const assembled = new Uint8Array(Buffer.concat(pending.chunks.filter((chunk): chunk is Buffer => chunk !== undefined)))+ if (kind === TerminalBinaryKind.imagePaste) {+ await this.pasteImage(state, assembled)+ } else {+ await this.pasteFile(state, pending.filename!, assembled)+ }+ }+/** 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