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.

fix: ensure chunked upload flow handles missing streams, falls back on clipboard failures, and enforces E2EE for control frames

0xken150ee854229970
diff --git a/cli/src/lib/e2ee/core.test.ts b/cli/src/lib/e2ee/core.test.ts
index 9add236c4..f9bea1956 100644
--- a/cli/src/lib/e2ee/core.test.ts
+++ b/cli/src/lib/e2ee/core.test.ts
@@ -140,6 +140,16 @@ describe('e2ee core — codes + fingerprint + classification', () => {
expect(C.isEncryptedDownType('terminal_input')).toBe(true)
})
+ it('gates the chunked-upload begin/cancel frames, same as every other terminal_* down type', () => {
+ // Regression: these were missing from ENCRYPTED_DOWN_TYPES, so relayClient.ts's wrapOutgoing()
+ // silently sent them in the clear across a machine-to-machine relay connection instead of failing
+ // loudly — and the backend's own isEncryptedTerminalFrame() check then rejected the unencrypted
+ // frame outright as TERMINAL_FRAME_REJECTED, freezing the whole terminal pane over what looked
+ // like a completely unrelated image/file-drop action.
+ expect(C.isEncryptedDownType('terminal_chunked_upload_begin')).toBe(true)
+ expect(C.isEncryptedDownType('terminal_chunked_upload_cancel')).toBe(true)
+ })
+
it('gates question_response, which the device encrypts', () => {
// Regression. The firmware wraps this frame because an AskUserQuestion answer is user content, but the
// type was missing from ENCRYPTED_DOWN_TYPES, so dispatchDown never unwrapped it. The failure was
@@ -187,6 +197,6 @@ describe('e2ee core — interop keystone', () => {
it('core.ts still hashes to the pinned value shared with the other implementations', () => {
const here = dirname(fileURLToPath(import.meta.url))
const actual = createHash('sha256').update(readFileSync(join(here, 'core.ts'))).digest('hex')
- expect(actual).toBe('99737b4f286931f4b7cc9956ab069012d818b109458992a6a331ca44811dfc38')
+ expect(actual).toBe('6e910a4da4e4e96550f119302bf64eaa22b7b01b76d54d520730561a6ce630af')
})
})
diff --git a/cli/src/lib/e2ee/core.ts b/cli/src/lib/e2ee/core.ts
index 0d454ba5f..523a2a193 100644
--- a/cli/src/lib/e2ee/core.ts
+++ b/cli/src/lib/e2ee/core.ts
@@ -370,6 +370,12 @@ export const ENCRYPTED_DOWN_TYPES = new Set<string>([
// never see agent ids, terminal bytes, dimensions, sequence numbers, or capability metadata.
'terminal_capabilities', 'terminal_open', 'terminal_alive', 'terminal_ack', 'terminal_input',
'terminal_resize', 'terminal_resync', 'terminal_close', 'terminal_scroll',
+ // Chunked image/file upload control frames — same "remote terminal control is always pairwise
+ // E2EE" rule as every other terminal_* type above. Missing from here for the same reason
+ // 'question_response' once was (see its comment): wrapOutgoing() silently sends the frame in the
+ // clear instead of failing loudly, and the relay's isEncryptedTerminalFrame() check then rejects
+ // it outright as TERMINAL_FRAME_REJECTED — indistinguishable from a real protocol violation.
+ 'terminal_chunked_upload_begin', 'terminal_chunked_upload_cancel',
// WebRTC signaling reveals both peers' network candidates. Keep it inside the already-authenticated
// pairwise session; the backend needs only the outer type + connId to route it.
'p2p_offer', 'p2p_answer', 'p2p_ice_candidate', 'p2p_abort',
diff --git a/cli/src/lib/terminalP2p.spec.ts b/cli/src/lib/terminalP2p.spec.ts
index b60f8b810..ad4024747 100644
--- a/cli/src/lib/terminalP2p.spec.ts
+++ b/cli/src/lib/terminalP2p.spec.ts
@@ -2,7 +2,9 @@ import { describe, expect, it, vi } from 'vitest'
import {
isRelayedPair,
readTurn,
+ TERMINAL_P2P_DOWN_TYPES,
TERMINAL_P2P_NEGOTIATION_TIMEOUT_MS,
+ TERMINAL_P2P_UP_TYPES,
TerminalP2pInitiator,
TerminalP2pResponderPool,
type TerminalP2pSignal,
@@ -247,4 +249,17 @@ describe('terminal WebRTC data channel', () => {
it('does not mistake a host address that merely contains the word', () => {
expect(isRelayedPair('candidate:1 1 udp 1 10.0.0.1 1 typ host raddr relay.example')).toBe(false)
})
+
+ // Regression: a JSON type these two allowlists don't know about is silently dropped the instant a
+ // pane's connection is on a direct p2p data channel (backendSocket.ts's `handleP2pData` / remoteRelay.ts's
+ // p2p-data handler) — no error, no log, indistinguishable from the wire itself hanging. That's exactly
+ // what happened to the chunked-upload types when they were added to the JSON protocol but not here.
+ it('carries the chunked-upload begin/cancel down and its results/progress up', () => {
+ expect(TERMINAL_P2P_DOWN_TYPES.has('terminal_chunked_upload_begin')).toBe(true)
+ expect(TERMINAL_P2P_DOWN_TYPES.has('terminal_chunked_upload_cancel')).toBe(true)
+ expect(TERMINAL_P2P_UP_TYPES.has('terminal_chunked_upload_begin_result')).toBe(true)
+ expect(TERMINAL_P2P_UP_TYPES.has('terminal_chunked_upload_progress')).toBe(true)
+ expect(TERMINAL_P2P_UP_TYPES.has('terminal_paste_image_result')).toBe(true)
+ expect(TERMINAL_P2P_UP_TYPES.has('terminal_paste_file_result')).toBe(true)
+ })
})
diff --git a/cli/src/lib/terminalP2p.ts b/cli/src/lib/terminalP2p.ts
index 0ef66e894..40856b1dd 100644
--- a/cli/src/lib/terminalP2p.ts
+++ b/cli/src/lib/terminalP2p.ts
@@ -40,12 +40,22 @@ export const TERMINAL_P2P_DOWN_TYPES = new Set([
'terminal_input', 'terminal_resize', 'terminal_resync', 'terminal_close', 'terminal_scroll',
// Deliberately no 'terminal_paste' here: it travels as a binary TerminalBinaryKind.paste frame,
// not JSON, so it needs no entry in this JSON-type forwarding list — the binary channel already
- // crosses the P2P data channel on its own.
+ // crosses the P2P data channel on its own. 'terminal_chunked_upload_begin'/'_cancel' ARE JSON
+ // (only the chunk payloads themselves are binary), so they need an entry here same as any other
+ // down-direction control frame — missing this left `handleP2pData` (backendSocket.ts) silently
+ // dropping every begin/cancel for a pane already on a direct p2p connection: no reply, no log,
+ // indistinguishable from the wire itself being stuck.
+ 'terminal_chunked_upload_begin', 'terminal_chunked_upload_cancel',
])
export const TERMINAL_P2P_UP_TYPES = new Set([
'terminal_capabilities_result', 'terminal_ready', 'terminal_keyframe',
'terminal_output', 'terminal_closed', 'terminal_error',
+ // The chunked-upload result/progress JSON replies — same reasoning as the down-direction set
+ // above: dropped here (remoteRelay.ts's p2p-data handler) would strand the client's progress UI
+ // even after the daemon itself did everything right.
+ 'terminal_chunked_upload_begin_result', 'terminal_chunked_upload_progress',
+ 'terminal_paste_image_result', 'terminal_paste_file_result',
])
export type TerminalP2pState = 'connecting' | 'direct' | 'failed' | 'closed'
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index 610884171..e71ce0f86 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -348,6 +348,20 @@ describe('TerminalStreamManager', () => {
expect(sent.some((f) => f.type === 'terminal_chunked_upload_progress')).toBe(false)
})
+ // Regression: previously a `begin` naming a streamId this connection has no live ActiveStream for
+ // (e.g. after a reconnect/resync raced the client) was silently dropped — no reply at all — which
+ // left the client's begin-accepted promise hanging until its own client-side timeout, indistinguishable
+ // from a genuine hang. It must always answer, echoing the streamId the client named.
+ it('replies accepted:false, echoing the streamId, when no live stream matches the begin', async () => {
+ await manager.handleFrame('web-1', 'terminal_chunked_upload_begin', {
+ streamId: 'stream-does-not-exist', uploadKind: 'image', totalBytes: pngBytes.length,
+ })
+ expect(lastResult()).toMatchObject({
+ type: 'terminal_chunked_upload_begin_result',
+ payload: { streamId: 'stream-does-not-exist', accepted: 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 })
@@ -371,7 +385,11 @@ describe('TerminalStreamManager', () => {
})
})
- it('reports a genuine clipboard-write failure as an error, not a silent no-op', async () => {
+ // A clipboard tool that's ON PATH but can't actually reach a display (a stale $DISPLAY with no
+ // X server behind it — exactly what a headless Docker rig hits) lands in 'failed', not
+ // 'unavailable', even though the outcome is identical: no OS clipboard to write to. This used to
+ // freeze the whole session; it must degrade to the same file-path fallback 'unavailable' gets.
+ it('falls back to pasting the file path when the clipboard tool is present but unreachable', async () => {
vi.mocked(writeImageToOsClipboard).mockResolvedValue(
{ state: 'failed', reason: 'xclip exited with code 1' } satisfies OsClipboardImageResult,
)
@@ -379,10 +397,12 @@ describe('TerminalStreamManager', () => {
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.findLast((f) => f.type === 'terminal_error')?.payload).toMatchObject({
- code: 'TERMINAL_PASTE_IMAGE_FAILED', streamId, message: 'xclip exited with code 1',
+ expect(stream.writes).toHaveLength(0) // no Ctrl+V — nothing was put on a clipboard
+ expect(stream.pastes).toEqual(['/fake/paste-images/fake.png'])
+ expect(sent.some((f) => f.type === 'terminal_error')).toBe(false)
+ const result = sent.findLast((f) => f.type === 'terminal_paste_image_result')!
+ expect(result.payload).toMatchObject({
+ streamId, outcome: 'fallback_path', reason: 'xclip exited with code 1',
})
})
diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.ts
index 13d0159ba..a3b27e2f5 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -551,13 +551,13 @@ export class TerminalStreamManager {
})
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.
+ // 'failed' and 'unavailable' get the same treatment: whether the clipboard tool is missing
+ // entirely or was found but couldn't actually reach a display (the exact case a Docker test rig
+ // with a stale $DISPLAY and no X server hits — xclip is on PATH, so this lands in 'failed', not
+ // 'unavailable', even though the outcome — no OS clipboard to write to — is identical), the user
+ // still needs the image. Hard-failing here used to freeze the whole session over what is, from
+ // the engine's perspective, just a degraded paste. 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 })
@@ -609,10 +609,25 @@ export class TerminalStreamManager {
* slow link finds out immediately rather than after transferring several MB for nothing.
*/
private beginChunkedUpload(connId: string, payload: FramePayload): void {
+ // Unlike resize/scroll/ack (silently no-op on a bad lookup is harmless — the next real event
+ // self-corrects), a paste that vanishes here leaves the client's progress overlay waiting on a
+ // reply that will never come, with nothing to explain why: it looks exactly like a hang. Reply
+ // even when this connection doesn't currently own a live stream for the streamId it named,
+ // echoing that streamId back (not a `state`'s, which we don't have) so the client can still
+ // match it against what it's waiting on.
+ const claimedStreamId = typeof payload.streamId === 'string' ? payload.streamId : undefined
const state = this.streamFor(connId, payload)
- if (!state) return
+ if (!state) {
+ this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', {
+ streamId: claimedStreamId,
+ accepted: false,
+ reason: 'no live terminal stream for this pane (reopen it and try again)',
+ })
+ return
+ }
const streamId = state.streamId
const reject = (reason: string): void => {
+ this.diagnostic(state, 'chunked_upload_rejected', { reason })
this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', { streamId, accepted: false, reason })
}
const uploadKind = payload.uploadKind === 'image' ? TerminalBinaryKind.imagePaste
@@ -645,6 +660,7 @@ export class TerminalStreamManager {
chunks: [],
bytesReceived: 0,
}
+ this.diagnostic(state, 'chunked_upload_begin', { uploadKind: payload.uploadKind, totalBytes, filename })
this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', { streamId, accepted: true })
}
@@ -654,6 +670,7 @@ export class TerminalStreamManager {
private cancelChunkedUpload(connId: string, payload: FramePayload): void {
const state = this.streamFor(connId, payload)
if (!state) return
+ if (state.pendingUpload) this.diagnostic(state, 'chunked_upload_cancelled', {})
state.pendingUpload = null
}
@@ -678,9 +695,14 @@ export class TerminalStreamManager {
bytes: Uint8Array,
): Promise<void> {
const pending = state.pendingUpload
- if (!pending || pending.kind !== kind) return
+ if (!pending) {
+ this.diagnostic(state, 'chunked_upload_stray_chunk', { seq, kind })
+ return
+ }
+ if (pending.kind !== kind) return
if (!Number.isSafeInteger(seq) || seq < 0 || seq >= pending.expectedChunks
|| bytes.length === 0 || bytes.length > UPLOAD_CHUNK_BYTES) {
+ this.diagnostic(state, 'chunked_upload_invalid_chunk', { seq, byteLength: bytes.length, expectedChunks: pending.expectedChunks })
this.sendError(state.connId, 'TERMINAL_CHUNKED_UPLOAD_INVALID', { streamId: state.streamId, message: 'malformed upload chunk' })
state.pendingUpload = null
return
@@ -697,6 +719,7 @@ export class TerminalStreamManager {
})
if (pending.bytesReceived < pending.totalBytes) return
state.pendingUpload = null
+ this.diagnostic(state, 'chunked_upload_assembled', { totalBytes: pending.totalBytes })
// 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