The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat(cli): serve encrypted remote media preview chunks
023dev06bb8b502d24
diff --git a/cli/README.md b/cli/README.mdindex 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 bydiff --git a/cli/scripts/smoke-media-peer.ts b/cli/scripts/smoke-media-peer.tsnew file mode 100644index 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.tsindex 98d5e3dbc..c349d6967 100644--- a/cli/src/backendSocket.spec.ts+++ b/cli/src/backendSocket.spec.ts@@ -5,6 +5,7 @@ import { BackendSocket, compactRuntimePickerModels, deviceAgentListItem, grokHisimport 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.tsindex 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 | undefinedconst path = payload.path as string | undefinedif (!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' }) }returndiff --git a/cli/src/lib/mediaPreview.spec.ts b/cli/src/lib/mediaPreview.spec.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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),})