Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat(cli): serve encrypted remote media preview chunks

023dev06bb8b502d24
diff --git a/cli/README.md b/cli/README.md
index b62e3e3eb..90162d28f 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -28,6 +28,25 @@ native module to compile — the same `cli.js` runs everywhere.
Windows is not supported.
+## Remote media previews
+
+Harness Desktop can download an agent's image/video and open it on the viewing
+computer. The CLI advertises `features.mediaPreview` in `terminal_capabilities`.
+The existing encrypted `agent_read_file` RPC accepts a media-only variant:
+`{agentId, path, media: true, offset, revision?}`. Replies carry `media`, `filename`,
+`totalBytes`, `offset`, `revision`, and `contentBase64`. Chunks are 128 KiB; every
+chunk after the first must supply its revision. The maximum file size is 512 MiB.
+
+Absolute paths, home-relative paths and file URLs resolve on the owning machine;
+relative paths (including symlink targets) stay inside the agent's working folder.
+Media suffixes and file signatures are checked. The original text-reading rules
+remain unchanged. Reads are stateless, close their handles after each request,
+and reject file changes during transfer. Paths and contents are omitted from frame
+logs. This reuses the existing E2EE request/reply types and needs no backend release.
+
+`scripts/smoke-media-peer.ts` is an opt-in fixture for Desktop's A/B smoke test;
+it uses temporary identities and loopback sockets, never live machine state.
+
## Install & run (`harness`)
Prerequisite: **Node ≥ 20**. Install the CLI, then sign in once with the same SSO account used by
diff --git a/cli/scripts/smoke-media-peer.ts b/cli/scripts/smoke-media-peer.ts
new file mode 100644
index 000000000..47ff22466
--- /dev/null
+++ b/cli/scripts/smoke-media-peer.ts
@@ -0,0 +1,95 @@
+/** Opt-in two-machine fixture for Desktop's remote_media_smoke_test.dart.
+ * A relays loopback app frames; B serves real files. Both use production E2EE
+ * handshake/wrapping and media reads, with isolated identities and data dirs. */
+import { WebSocket, WebSocketServer } from 'ws'
+import { newIdentity, b64e, isWrapped } from '../src/lib/e2ee/core.js'
+import { E2eeStore } from '../src/lib/e2ee/store.js'
+import { E2eeManager } from '../src/lib/e2ee/manager.js'
+import { RelaySessionCrypto } from '../src/lib/e2ee/relayClient.js'
+import { MediaPreviewError, readMediaPreviewChunk } from '../src/lib/mediaPreview.js'
+
+if (process.env.HARNESS_MEDIA_SMOKE !== '1' || !process.env.ADAPTER_DATA_DIR || !process.argv[2]) {
+ throw new Error('This test fixture requires explicit smoke mode, an isolated data directory and an artifact directory.')
+}
+const root = process.argv[2]
+const identityA = newIdentity()
+const storeB = new E2eeStore()
+const identityB = storeB.init()
+storeB.addPaired(b64e(identityA.pub), 'Smoke machine A', Date.now())
+const connections = new Map<string, WebSocket>()
+let encryptedRequests = 0
+let encryptedReplies = 0
+let maxFrameBytes = 0
+const managerB = new E2eeManager({
+ machineId: 'smoke-B', isConnected: () => true,
+ sendTo: (id, frame) => connections.get(id)?.send(JSON.stringify(frame)),
+})
+const peerB = new WebSocketServer({ host: '127.0.0.1', port: 0 })
+await new Promise<void>(resolve => peerB.once('listening', resolve))
+let sequence = 0
+peerB.on('connection', socket => {
+ const id = `smoke-A-${++sequence}`
+ connections.set(id, socket)
+ socket.on('close', () => { connections.delete(id); managerB.dropSession(id) })
+ socket.on('message', async raw => {
+ const frame = JSON.parse(raw.toString())
+ if (frame.type.startsWith('e2e_')) { managerB.handleFrame(id, frame); return }
+ if (frame.type !== 'agent_read_file' || !isWrapped(frame.payload)) throw new Error('Media request was not encrypted')
+ encryptedRequests++
+ const decoded = managerB.unwrapDown(id, frame)
+ if (!decoded) throw new Error('Media request failed authentication')
+ const payload = decoded.payload as Record<string, unknown>
+ // Network fault injection is confined to this opt-in fixture.
+ if (Number(payload.offset) > 0 && payload.smokeDisconnect) { socket.close(); return }
+ if (Number(payload.offset) > 0 && payload.smokeDelay) await new Promise(resolve => setTimeout(resolve, 100))
+ let result: Record<string, unknown>
+ try {
+ result = { ...await readMediaPreviewChunk(root, String(payload.path), payload.offset, payload.revision) }
+ } catch (error) {
+ result = { error: error instanceof MediaPreviewError ? error.message : 'MEDIA_READ_FAILED' }
+ }
+ if (socket.readyState !== WebSocket.OPEN) return
+ const wrapped = managerB.wrapRpcReply(id, 'agent_read_file_result', payload.requestId, result)
+ if (!wrapped || !isWrapped(wrapped.payload)) throw new Error('Media reply was not encrypted')
+ const wire = JSON.stringify(wrapped)
+ maxFrameBytes = Math.max(maxFrameBytes, Buffer.byteLength(wire))
+ encryptedReplies++
+ socket.send(wire)
+ })
+})
+
+const appA = new WebSocketServer({ host: '127.0.0.1', port: 0 })
+await new Promise<void>(resolve => appA.once('listening', resolve))
+appA.on('connection', local => {
+ const cryptoA = new RelaySessionCrypto({ machineId: 'smoke-B', selfIdentity: identityA, peerPub: identityB.pub })
+ const peer = new WebSocket(`ws://127.0.0.1:${(peerB.address() as { port: number }).port}`)
+ peer.on('open', () => peer.send(JSON.stringify(cryptoA.helloFrame())))
+ peer.on('message', raw => {
+ const frame = JSON.parse(raw.toString())
+ if (frame.type === 'e2e_welcome') {
+ if (!cryptoA.handleWelcome(frame.payload)) throw new Error('Smoke handshake failed')
+ local.send(JSON.stringify({ type: 'connected', payload: { machineId: 'smoke-B' } }))
+ return
+ }
+ const decoded = cryptoA.unwrapIncoming(frame)
+ if (!decoded) throw new Error('Media reply failed authentication')
+ if (local.readyState === WebSocket.OPEN) local.send(JSON.stringify(decoded))
+ })
+ peer.on('close', () => local.close())
+ local.on('close', () => peer.close())
+ local.on('message', raw => {
+ const frame = JSON.parse(raw.toString())
+ if (frame.type === 'machine_select') return
+ if (frame.type === 'smoke_stats') {
+ local.send(JSON.stringify({ type: 'smoke_stats_result', payload: {
+ requestId: frame.payload.requestId, encryptedRequests, encryptedReplies, maxFrameBytes,
+ } }))
+ return
+ }
+ if (!cryptoA.ready) throw new Error('App sent media before the handshake')
+ peer.send(JSON.stringify(cryptoA.wrapOutgoing(frame)))
+ })
+})
+console.log(JSON.stringify({ port: (appA.address() as { port: number }).port }))
+process.stdin.resume()
+process.stdin.on('end', () => process.exit(0))
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 98d5e3dbc..c349d6967 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -5,6 +5,7 @@ import { BackendSocket, compactRuntimePickerModels, deviceAgentListItem, grokHis
import type { TerminalStreamManager } from './lib/terminalStreamManager.js'
import { decodeTerminalLocal, TerminalBinaryKind } from './lib/terminalBinary.js'
import { registry, type RegisteredSession } from './lib/registry.js'
+import * as mediaPreview from './lib/mediaPreview.js'
const wsMock = vi.hoisted(() => {
const instances: MockWebSocket[] = []
@@ -213,6 +214,51 @@ describe('BackendSocket outbound queue', () => {
await socket.stop()
})
+ it('serves media only to the requesting encrypted connection', async () => {
+ vi.spyOn(registry, 'resolve').mockReturnValue({ cwd: '/remote/workspace' } as RegisteredSession)
+ const media = { media: true as const, filename: 'preview.png', offset: 0, totalBytes: 3,
+ revision: 'a'.repeat(64), contentBase64: 'AQID' }
+ const read = vi.spyOn(mediaPreview, 'readMediaPreviewChunk').mockResolvedValue(media)
+ const socket = new BackendSocket('token')
+ socket.connect()
+ const ws = wsMock.instances[0]
+ ws.open()
+ vi.spyOn(socket.e2ee, 'unwrapDown').mockReturnValue({ type: 'agent_read_file', payload: {
+ requestId: 'media-1', agentId: 'agent-b', path: '/tmp/preview.png', media: true, offset: 0,
+ } })
+ vi.spyOn(socket.e2ee, 'hasSession').mockReturnValue(true)
+ const wrap = vi.spyOn(socket.e2ee, 'wrapRpcReply').mockReturnValue({
+ type: 'agent_read_file_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-media' } },
+ })
+ ws.message({ t: 'down', connId: 'viewer-a', frame: {
+ type: 'agent_read_file', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-request' } },
+ } })
+ await vi.waitFor(() => expect(wrap).toHaveBeenCalledWith('viewer-a', 'agent_read_file_result', 'media-1', media))
+ expect(read).toHaveBeenCalledWith('/remote/workspace', '/tmp/preview.png', 0, undefined)
+ const sent = parseSent(ws)
+ expect(sent).toContainEqual(expect.objectContaining({ targetConnId: 'viewer-a', frame: {
+ type: 'agent_read_file_result', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'encrypted-media' } },
+ } }))
+ expect(JSON.stringify(sent)).not.toContain('AQID')
+ await socket.stop()
+ })
+
+ it('refuses a plaintext media request before reading any file', async () => {
+ const read = vi.spyOn(mediaPreview, 'readMediaPreviewChunk')
+ const socket = new BackendSocket('token')
+ socket.connect()
+ const ws = wsMock.instances[0]
+ ws.open()
+ ws.message({ t: 'down', connId: 'unpaired-viewer', frame: {
+ type: 'agent_read_file', payload: { requestId: 'media-unsafe', agentId: 'agent-b', path: '/tmp/preview.png', media: true, offset: 0 },
+ } })
+ await vi.waitFor(() => expect(parseSent(ws)).toContainEqual(expect.objectContaining({
+ targetConnId: 'unpaired-viewer', frame: expect.objectContaining({ payload: { requestId: 'media-unsafe', error: 'E2EE_REQUIRED' } }),
+ })))
+ expect(read).not.toHaveBeenCalled()
+ await socket.stop()
+ })
+
it('includes engine session correlation in the web agent list', async () => {
const session: RegisteredSession = {
schemaVersion: 2,
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 441b54c25..a84a269a1 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -34,6 +34,7 @@ import { routeVoiceTask } from './lib/voiceRouter.js'
import { tailFile } from './lib/sessions.js'
import { messagesToEvents, windowRawLines, subagentStatsFromRawLines, type SessionEvent } from './lib/normalize.js'
import { listFileTree, readProjectFile } from './lib/files.js'
+import { MediaPreviewError, readMediaPreviewChunk } from './lib/mediaPreview.js'
import { codexMessagesToEvents, windowCodexLines } from './engines/codex/normalizer.js'
import { cursorMessagesToEvents, windowCursorLines } from './engines/cursor/normalizer.js'
import { loadCursorReplayTaskLinks } from './engines/cursor/subagent.js'
@@ -964,7 +965,7 @@ export class BackendSocket {
private emitReply(connId: string, type: string, requestId: unknown, payload: Record<string, unknown>): void {
const resultType = `${type}_result`
// Before the E2EE wrap: an RPC reply is only readable here.
- if (env.LOG_FRAMES) logFrame('→', connId ? `conn:${sid(connId)}` : 'backend', { type: resultType, payload: { requestId, ...payload } })
+ if (env.LOG_FRAMES && type !== 'agent_read_file') logFrame('→', connId ? `conn:${sid(connId)}` : 'backend', { type: resultType, payload: { requestId, ...payload } })
if (this.localClients.has(connId)) {
this.sendTo(connId, { type: resultType, payload: { requestId, ...payload } })
return
@@ -1038,7 +1039,7 @@ export class BackendSocket {
// than as an opaque __e2e envelope.
// Terminal frames contain raw keystrokes, paste text and screen bytes after
// unwrap. Never pass them to the frame logger, even in diagnostic mode.
- if (env.LOG_FRAMES && !type.startsWith('terminal_')) {
+ if (env.LOG_FRAMES && !type.startsWith('terminal_') && type !== 'agent_read_file') {
logFrame('←', connId ? `conn:${sid(connId)}` : 'backend', frame)
}
const reply = (t: string, rid: unknown, p: Record<string, unknown>): void => this.emitReply(connId, t, rid, p)
@@ -1670,12 +1671,21 @@ export class BackendSocket {
}
case 'agent_read_file': {
- // View one file — ≤5MB, text-only (mirror the hosted runtime’s guard).
+ // Text reads keep their ≤5 MB guard; media uses bounded binary chunks.
const projectId = payload.agentId as string | undefined
const path = payload.path as string | undefined
if (!projectId || !path) { reply(type, requestId, { error: 'MISSING_AGENT_OR_PATH' }); return }
const s = registry.resolve(projectId)
if (!s?.cwd) { reply(type, requestId, { error: 'AGENT_NOT_FOUND' }); return }
+ if (payload.media === true) {
+ if (typeof path !== 'string') { reply(type, requestId, { error: 'MEDIA_INVALID_REQUEST' }); return }
+ try {
+ reply(type, requestId, { ...await readMediaPreviewChunk(s.cwd, path, payload.offset, payload.revision) })
+ } catch (error) {
+ reply(type, requestId, { error: error instanceof MediaPreviewError ? error.message : 'MEDIA_READ_FAILED' })
+ }
+ return
+ }
try { reply(type, requestId, { path, content: readProjectFile(s.cwd, path) }) }
catch (e) { reply(type, requestId, { error: e instanceof Error ? e.message : 'NOT_FOUND' }) }
return
diff --git a/cli/src/lib/mediaPreview.spec.ts b/cli/src/lib/mediaPreview.spec.ts
new file mode 100644
index 000000000..22e9ddc5c
--- /dev/null
+++ b/cli/src/lib/mediaPreview.spec.ts
@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdir, mkdtemp, open, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { readProjectFile } from './files.js'
+import { MEDIA_PREVIEW_CHUNK_BYTES, MEDIA_PREVIEW_MAX_BYTES, readMediaPreviewChunk } from './mediaPreview.js'
+
+describe('remote media preview reads', () => {
+ let root: string
+ const pngHeader = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])
+ beforeEach(async () => { root = await mkdtemp(join(tmpdir(), 'harness-media-test-')) })
+ afterEach(async () => { await rm(root, { recursive: true, force: true }) })
+
+ it('reassembles exact bytes across bounded reads with one stable revision', async () => {
+ const image = Buffer.alloc(MEDIA_PREVIEW_CHUNK_BYTES * 3 + 17, 91)
+ pngHeader.copy(image)
+ await writeFile(join(root, 'ảnh one.png'), image)
+ const chunks: Buffer[] = []
+ let revision: string | undefined
+ for (let offset = 0; offset < image.length; offset += MEDIA_PREVIEW_CHUNK_BYTES) {
+ const reply = await readMediaPreviewChunk(root, 'ảnh one.png', offset, revision)
+ expect(reply).toMatchObject({ media: true, filename: 'ảnh one.png', offset, totalBytes: image.length })
+ expect(reply.revision).toMatch(/^[a-f0-9]{64}$/)
+ if (revision) expect(reply.revision).toBe(revision)
+ revision = reply.revision
+ chunks.push(Buffer.from(reply.contentBase64, 'base64'))
+ // Include the second base64 expansion used by an encrypted JSON envelope.
+ expect(Buffer.byteLength(Buffer.from(JSON.stringify(reply)).toString('base64')) + 4096).toBeLessThan(256 * 1024)
+ }
+ expect(Buffer.concat(chunks)).toEqual(image)
+ })
+
+ it('reads absolute and file URI artifacts outside the agent cwd', async () => {
+ const path = join(root, '100% ảnh #1.png')
+ await writeFile(path, pngHeader)
+ for (const target of [path, pathToFileURL(path).href]) {
+ const reply = await readMediaPreviewChunk(join(root, 'workspace'), target, 0)
+ expect(Buffer.from(reply.contentBase64, 'base64')).toEqual(pngHeader)
+ }
+ })
+
+ it.each([
+ ['clip.mp4', Buffer.from([0, 0, 0, 24, ...Buffer.from('ftypisom'), 0, 0, 0, 0])],
+ ['clip.webm', Buffer.from([26, 69, 223, 163, 0, 0])],
+ ['clip.mov', Buffer.from([0, 0, 0, 24, ...Buffer.from('ftypqt '), 0, 0, 0, 0])],
+ ['image.jpg', Buffer.from([255, 216, 255, 224])],
+ ['image.svg', Buffer.from('<?xml version="1.0"?>\n<svg xmlns="http://www.w3.org/2000/svg"></svg>')],
+ ['image.gif', Buffer.from('GIF89a0000')],
+ ])('supports %s media without interpreting it as UTF-8 text', async (filename, bytes) => {
+ await writeFile(join(root, filename), bytes)
+ expect(Buffer.from((await readMediaPreviewChunk(root, filename, 0)).contentBase64, 'base64')).toEqual(bytes)
+ })
+
+ it('preserves the existing text reader restrictions', async () => {
+ await writeFile(join(root, 'image.png'), Buffer.concat([pngHeader, Buffer.from([0])]))
+ await writeFile(join(root, 'source.txt'), 'hello')
+ expect(readProjectFile(root, 'source.txt')).toBe('hello')
+ expect(() => readProjectFile(root, 'image.png')).toThrow('NOT_TEXT')
+ await expect(readMediaPreviewChunk(root, 'source.txt', 0)).rejects.toThrow('MEDIA_UNSUPPORTED')
+ })
+
+ it('rejects renamed non-media files and symlinks to non-media', async () => {
+ await writeFile(join(root, 'credentials.txt'), 'a-private-credential')
+ await writeFile(join(root, 'renamed.png'), 'a-private-credential')
+ await symlink(join(root, 'credentials.txt'), join(root, 'linked.png'))
+ for (const target of ['renamed.png', 'linked.png']) {
+ await expect(readMediaPreviewChunk(root, target, 0)).rejects.toThrow('MEDIA_UNSUPPORTED')
+ }
+ })
+
+ it('refuses to mix versions when a file changes or is replaced mid-download', async () => {
+ const path = join(root, 'image.png')
+ const image = Buffer.alloc(MEDIA_PREVIEW_CHUNK_BYTES + 10)
+ pngHeader.copy(image)
+ await writeFile(path, image)
+ const first = await readMediaPreviewChunk(root, path, 0)
+ await rm(path)
+ await writeFile(path, image)
+ await expect(readMediaPreviewChunk(root, path, MEDIA_PREVIEW_CHUNK_BYTES, first.revision)).rejects.toThrow('MEDIA_CHANGED')
+ })
+
+ it('keeps relative symlink targets inside the agent workspace', async () => {
+ const workspace = join(root, 'workspace')
+ await mkdir(workspace)
+ await writeFile(join(root, 'outside.png'), pngHeader)
+ await symlink(join(root, 'outside.png'), join(workspace, 'linked.png'))
+ await expect(readMediaPreviewChunk(workspace, 'linked.png', 0)).rejects.toThrow('MEDIA_INVALID_REQUEST')
+ expect((await readMediaPreviewChunk(workspace, join(root, 'outside.png'), 0)).totalBytes).toBe(pngHeader.length)
+ })
+
+ it('refuses a missing file and an empty file', async () => {
+ await expect(readMediaPreviewChunk(root, 'gone.png', 0)).rejects.toThrow('MEDIA_NOT_FOUND')
+ await writeFile(join(root, 'empty.png'), '')
+ await expect(readMediaPreviewChunk(root, 'empty.png', 0)).rejects.toThrow('MEDIA_NOT_FOUND')
+ })
+
+ it('rejects oversized files using metadata before reading contents', async () => {
+ const file = await open(join(root, 'large.mp4'), 'w')
+ await file.truncate(MEDIA_PREVIEW_MAX_BYTES + 1)
+ await file.close()
+ await expect(readMediaPreviewChunk(root, 'large.mp4', 0)).rejects.toThrow('MEDIA_TOO_LARGE')
+ })
+
+ it.each([-1, 1.5, 1, '0', null, Number.MAX_SAFE_INTEGER + 1])('rejects invalid offset %s', async (offset) => {
+ await expect(readMediaPreviewChunk(root, 'image.png', offset)).rejects.toThrow('MEDIA_INVALID_REQUEST')
+ })
+
+ it.each(['../outside.png', 'file://other-host/tmp/photo.png', 'https://example.com/photo.png', 'bad\0.png'])('refuses invalid target %s', async (target) => {
+ await expect(readMediaPreviewChunk(root, target, 0)).rejects.toThrow('MEDIA_INVALID_REQUEST')
+ })
+
+ it('requires the first revision for every subsequent chunk', async () => {
+ await expect(readMediaPreviewChunk(root, 'image.png', MEDIA_PREVIEW_CHUNK_BYTES)).rejects.toThrow('MEDIA_INVALID_REQUEST')
+ })
+})
diff --git a/cli/src/lib/mediaPreview.ts b/cli/src/lib/mediaPreview.ts
new file mode 100644
index 000000000..82f641858
--- /dev/null
+++ b/cli/src/lib/mediaPreview.ts
@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto'
+import { constants, type BigIntStats } from 'node:fs'
+import { open, realpath } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, extname, isAbsolute, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Base64 inside an E2EE JSON envelope stays below 256 KiB per reply. The client
+// requests bounded chunks, so neither machine holds an entire video in memory.
+export const MEDIA_PREVIEW_CHUNK_BYTES = 128 * 1024
+export const MEDIA_PREVIEW_MAX_BYTES = 512 * 1024 * 1024
+
+export class MediaPreviewError extends Error {
+ constructor(code: string) { super(code); this.name = 'MediaPreviewError' }
+}
+
+const extensions = new Set([
+ '.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.heic', '.heif', '.bmp',
+ '.tif', '.tiff', '.svg', '.ico', '.mp4', '.m4v', '.mov', '.webm', '.mkv',
+ '.avi', '.mpeg', '.mpg', '.ogv', '.3gp',
+])
+
+function fail(code: string): never { throw new MediaPreviewError(code) }
+
+/** A media-only variant of agent_read_file, not a relaxation of its text-file
+ * guard. Absolute paths are intentional: agent artifacts often live in /tmp.
+ * Relative paths stay under the selected agent's working folder; ~ and file://
+ * are resolved on the machine that owns the file, never on the viewing machine. */
+function resolveTarget(root: string, target: string): { path: string; relative: boolean } {
+ if (!target || target.length > 4096 || /[\x00-\x1f\x7f]/.test(target)) fail('MEDIA_INVALID_REQUEST')
+ let path = target
+ if (/^file:/i.test(path)) {
+ try {
+ const uri = new URL(path)
+ if (uri.hostname && uri.hostname !== 'localhost') fail('MEDIA_INVALID_REQUEST')
+ uri.search = ''; uri.hash = ''
+ path = fileURLToPath(uri)
+ } catch { fail('MEDIA_INVALID_REQUEST') }
+ } else if (/^[a-z][a-z0-9+.-]*:/i.test(path) && !/^[a-z]:[\\/]/i.test(path)) {
+ fail('MEDIA_INVALID_REQUEST')
+ }
+ if (path.startsWith('~/')) path = resolve(homedir(), path.slice(2))
+ if (!extensions.has(extname(path).toLowerCase())) fail('MEDIA_UNSUPPORTED')
+ const relative = !isAbsolute(path)
+ if (relative) {
+ const base = resolve(root)
+ path = resolve(base, path)
+ if (!path.startsWith(base.endsWith(sep) ? base : base + sep)) fail('MEDIA_INVALID_REQUEST')
+ }
+ return { path, relative }
+}
+
+/** Check content as well as the suffix, so a renamed text/credential file does
+ * not become a media download. Container checks are deliberately lightweight;
+ * decoding/playback remains the OS viewer's job. */
+function hasMediaHeader(bytes: Buffer, extension: string): boolean {
+ const starts = (...signature: number[]) => bytes.subarray(0, signature.length).equals(Buffer.from(signature))
+ const text = (start: number, end: number) => bytes.toString('ascii', start, end)
+ switch (extension) {
+ case '.png': return starts(137, 80, 78, 71, 13, 10, 26, 10)
+ case '.jpg': case '.jpeg': return starts(255, 216, 255)
+ case '.gif': return ['GIF87a', 'GIF89a'].includes(text(0, 6))
+ case '.webp': return text(0, 4) === 'RIFF' && text(8, 12) === 'WEBP'
+ case '.bmp': return text(0, 2) === 'BM'
+ case '.tif': case '.tiff': return starts(73, 73, 42, 0) || starts(77, 77, 0, 42)
+ case '.ico': return starts(0, 0, 1, 0)
+ case '.svg': {
+ const xml = bytes.toString('utf8').replace(/^\uFEFF/, '').trimStart()
+ return /^(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg(?:\s|>)/.test(xml)
+ }
+ case '.avi': return text(0, 4) === 'RIFF' && text(8, 12) === 'AVI '
+ case '.webm': case '.mkv': return starts(26, 69, 223, 163)
+ case '.ogv': return text(0, 4) === 'OggS'
+ case '.mpg': case '.mpeg': return starts(0, 0, 1, 186) || starts(0, 0, 1, 179)
+ case '.avif': case '.heic': case '.heif': {
+ if (text(4, 8) !== 'ftyp') return false
+ const brands = bytes.toString('ascii', 8, Math.min(bytes.length, 128))
+ return extension === '.avif' ? /avif|avis/.test(brands) : /heic|heix|hevc|hevx|mif1|msf1/.test(brands)
+ }
+ case '.mp4': case '.m4v': case '.3gp': return text(4, 8) === 'ftyp'
+ case '.mov': return ['ftyp', 'moov', 'mdat', 'wide'].includes(text(4, 8))
+ default: return false
+ }
+}
+
+function revisionOf(path: string, stat: BigIntStats): string {
+ return createHash('sha256').update(JSON.stringify([
+ path, stat.dev.toString(), stat.ino.toString(), stat.size.toString(),
+ stat.mtimeNs.toString(), stat.ctimeNs.toString(),
+ ])).digest('hex')
+}
+
+export interface MediaPreviewChunk {
+ media: true
+ filename: string
+ totalBytes: number
+ offset: number
+ revision: string
+ contentBase64: string
+}
+
+/** Stateless bounded reads: cancelling stops future requests, and disconnects
+ * leave no file handles or transfer sessions behind on the remote machine. */
+export async function readMediaPreviewChunk(
+ root: string,
+ target: string,
+ offset: unknown,
+ expectedRevision?: unknown,
+): Promise<MediaPreviewChunk> {
+ if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0
+ || offset % MEDIA_PREVIEW_CHUNK_BYTES !== 0
+ || (offset > 0 && (typeof expectedRevision !== 'string' || !/^[a-f0-9]{64}$/.test(expectedRevision)))) {
+ fail('MEDIA_INVALID_REQUEST')
+ }
+ const requested = resolveTarget(root, target)
+ const requestedPath = requested.path
+ try {
+ const canonicalPath = await realpath(requestedPath)
+ if (requested.relative) {
+ const base = await realpath(root)
+ if (!canonicalPath.startsWith(base.endsWith(sep) ? base : base + sep)) fail('MEDIA_INVALID_REQUEST')
+ }
+ // Resolve symlinks once, then refuse a last-component swap. NONBLOCK avoids
+ // hanging on a FIFO before fstat can reject anything other than a file.
+ const file = await open(canonicalPath, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW)
+ try {
+ const before = await file.stat({ bigint: true })
+ if (!before.isFile() || before.size <= 0n) fail('MEDIA_NOT_FOUND')
+ if (before.size > BigInt(MEDIA_PREVIEW_MAX_BYTES)) fail('MEDIA_TOO_LARGE')
+ const totalBytes = Number(before.size)
+ if (offset >= totalBytes) fail('MEDIA_INVALID_REQUEST')
+ const revision = revisionOf(canonicalPath, before)
+ if (expectedRevision !== undefined && expectedRevision !== revision) fail('MEDIA_CHANGED')
+ const header = Buffer.alloc(Math.min(4096, totalBytes))
+ const headerRead = await file.read(header, 0, header.length, 0)
+ if (!hasMediaHeader(header.subarray(0, headerRead.bytesRead), extname(requestedPath).toLowerCase())) {
+ fail('MEDIA_UNSUPPORTED')
+ }
+ const bytes = Buffer.alloc(Math.min(MEDIA_PREVIEW_CHUNK_BYTES, totalBytes - offset))
+ let read = 0
+ while (read < bytes.length) {
+ const result = await file.read(bytes, read, bytes.length - read, offset + read)
+ if (!result.bytesRead) fail('MEDIA_CHANGED')
+ read += result.bytesRead
+ }
+ if (revisionOf(canonicalPath, await file.stat({ bigint: true })) !== revision) fail('MEDIA_CHANGED')
+ return { media: true, filename: basename(requestedPath), totalBytes, offset, revision, contentBase64: bytes.toString('base64') }
+ } finally {
+ await file.close()
+ }
+ } catch (error) {
+ if (error instanceof MediaPreviewError) throw error
+ if (['ENOENT', 'ENOTDIR', 'ELOOP'].includes((error as NodeJS.ErrnoException).code ?? '')) fail('MEDIA_NOT_FOUND')
+ fail('MEDIA_READ_FAILED')
+ }
+}
diff --git a/cli/src/lib/terminalStreamManager.spec.ts b/cli/src/lib/terminalStreamManager.spec.ts
index ba3e3f47f..4b7be05b1 100644
--- a/cli/src/lib/terminalStreamManager.spec.ts
+++ b/cli/src/lib/terminalStreamManager.spec.ts
@@ -252,6 +252,7 @@ describe('TerminalStreamManager', () => {
const features = sent.at(-1)?.payload.features as Record<string, unknown>
expect(features.imagePaste).toBe(true)
expect(features.pasteFile).toBe(true)
+ expect(features.mediaPreview).toBe(true)
})
it('rejects legacy JSON terminal_paste_image/terminal_paste_file the same way as terminal_paste', async () => {
diff --git a/cli/src/lib/terminalStreamManager.ts b/cli/src/lib/terminalStreamManager.ts
index a3b27e2f5..3a1f6112f 100644
--- a/cli/src/lib/terminalStreamManager.ts
+++ b/cli/src/lib/terminalStreamManager.ts
@@ -254,6 +254,8 @@ export class TerminalStreamManager {
// dropped non-image file to a REMOTE pane at all (a local pane needs no capability — it
// pastes the file's own path directly, never touching the wire) — see `pasteFile()`.
pasteFile: true,
+ // Bounded media reads through the already encrypted agent_read_file RPC.
+ mediaPreview: true,
},
engines: terminalEngineCapabilities(this.deps.streamingAvailable),
})