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.

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.ts
index 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.ts
index 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 | null
return 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.ts
index 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 clipboard
expect(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.ts
index 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: number
pausedAt: number | null
pausedMs: 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 true
case 'terminal_scroll':
await this.scroll(connId, payload)
return true
@@ -186,12 +218,8 @@ export class TerminalStreamManager {
&& frame.kind !== TerminalBinaryKind.imagePaste && frame.kind !== TerminalBinaryKind.pasteFile) 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.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_MS
let path: string
try {
- 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