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
Forward remote harness viewers over paired encrypted connections
Dee4fc3909e3f82
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex bd782b808..2390676f6 100644--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@ -51,6 +51,8 @@ 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 { ViewerForwarder } from './lib/viewerForwarder.js'+import { VIEWER_DOWN_TYPES } from './lib/viewerWire.js'import { codexMessagesToEvents, windowCodexLines } from './engines/codex/normalizer.js'import { codexSubagentResolverFor } from './engines/codex/subagent.js'import { parseHostTheme, type HostTheme } from './lib/hostTheme.js'@@ -378,6 +380,18 @@ export class BackendSocket {onDshRemove: ((id: string) => { ok: true } | { ok: false; error: string; detail: string }) | null = null/** What the daemon knows about an agent's DSH companions (viewer URL, verdict); null when nothing. */dshFrameProvider: ((session: RegisteredSession) => AgentDshContext | null) | null = null+ viewerTargetProvider: ((agentId: string) => string | null) | null = null+ readonly viewerForwarder = new ViewerForwarder({+ target: (agentId) => this.viewerTargetProvider?.(agentId) ?? null,+ send: (connId, type, payload) => {+ if (this.localClients.has(connId)) { this.sendTo(connId, { type, payload }); return true }+ if (!this.isConnected()) return false+ const frame = this.e2ee.wrapTarget(connId, type, payload)+ if (!frame) return false+ this.sendTo(connId, frame)+ return true+ },+ })private readonly agentCreations = new AgentCreationReceipts(join(env.ADAPTER_DATA_DIR, 'agent-creations'))/** Injectable for queue-isolation tests; production uses the machine-local probe. */engineProbeProvider: typeof probeEngines = probeEngines@@ -550,6 +564,7 @@ export class BackendSocket {isConnectionAvailable: connId => this.directDeviceSinks.has(connId) || this.isConnected(),onIdentityPaired: (connId, pub) => { if (this.directDeviceSinks.has(connId)) this.directDevicePins.set(connId, pub) },onIdentityRevoked: identity => { this.autonomousDeviceRelay?.revoke(identity); this.onDirectDeviceRevoked?.(fingerprint(b64d(identity))) },+ onSessionDropped: (connId) => this.viewerForwarder.closeConnection(connId),})this.terminalP2p = new TerminalP2pResponderPool({sendSignal: (connId, type, payload) => this.sendP2pSignal(connId, type, payload),@@ -687,6 +702,7 @@ export class BackendSocket {// completing during the gap burns a `claude -p` recap that goes nowhere. attachAdapter always// re-pushes the true count via recomputeAndSendClients on reconnect (and 0→N re-fires the replay).this.setCommanderCount(0, null) // active count is unknown until the next __clients snapshot+ this.viewerForwarder.closeAll()void this.terminalStreams?.closeConnectionsWhere((connId) => !isLocalClientId(connId),'backend disconnected',@@ -756,6 +772,7 @@ export class BackendSocket {async stop(): Promise<void> {this.closed = true+ this.viewerForwarder.closeAll()if (this.heartbeat) this.heartbeat.stop()if (this.appPing) clearInterval(this.appPing)await this.terminalStreams?.stop()@@ -906,6 +923,7 @@ export class BackendSocket {/** Release all connection-scoped state when the loopback WebSocket closes. */async unregisterLocalClient(connId: string): Promise<void> {if (!this.localClients.delete(connId)) return+ this.viewerForwarder.closeConnection(connId)// The window left before any link could hear it attach: nothing happened, as far as the backend// is concerned, and a later link must not be told otherwise.if (this.localClients.size === 0) this.appOpenOwed = false@@ -1179,7 +1197,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_') && type !== 'agent_read_file' && type !== 'project_preview') {+ if (env.LOG_FRAMES && !type.startsWith('terminal_') && !type.startsWith('viewer_') && type !== 'agent_read_file' && type !== 'project_preview') {logFrame('←', connId ? `conn:${sid(connId)}` : 'backend', frame)}const reply = (t: string, rid: unknown, p: Record<string, unknown>): void => this.emitReply(connId, t, rid, p)@@ -1213,6 +1231,7 @@ export class BackendSocket {// terminal controller lease until the 30-second heartbeat timeout.this.autonomousDeviceRelay?.drop(connId)this.e2ee.dropSession(connId)+ this.viewerForwarder.closeConnection(connId)await this.terminalP2p.closeConnection(connId, 'client_disconnected', false)this.p2pPendingOpens.delete(connId)this.p2pStreams.delete(connId)@@ -1245,6 +1264,13 @@ export class BackendSocket {const payload = (frame.payload ?? {}) as Record<string, unknown>const requestId = payload.requestId+ if (type.startsWith('viewer_')) {+ if (VIEWER_DOWN_TYPES.has(type) && (local || this.e2ee.sessionRole(connId) === 'web')) {+ this.viewerForwarder.handle(connId, type, payload)+ }+ return+ }+if (type.startsWith('terminal_')) {this.noteTerminalInputRoute(connId, type, payload, transport)if (this.terminalStreams) await this.terminalStreams.handleFrame(connId, type, payload)diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex adcb7ef6c..f9b89052d 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -1479,6 +1479,7 @@ async function runForeground(session: AuthSession): Promise<void> {const dshViewers = new DshViewerManager({onUrl: (agentId, url) => {dshFrameFor(agentId).viewerUrl = url+ backendRef?.viewerForwarder.refresh(agentId)syncCompanion(agentId)},log: (line) => console.log(line),@@ -1550,6 +1551,7 @@ async function runForeground(session: AuthSession): Promise<void> {})}, computerId())backendRef = backend+ backend.viewerTargetProvider = (agentId) => dshViewers.forwardingUrl(agentId)/*** Is ANY device surface watching this machine?diff --git a/cli/src/dsh/viewer.ts b/cli/src/dsh/viewer.tsindex 0dd28f1a5..fdd53b380 100644--- a/cli/src/dsh/viewer.ts+++ b/cli/src/dsh/viewer.ts@@ -20,6 +20,7 @@ import { installedDsh, type InstalledDsh } from './installed.js'import { isViewerPackage } from './manifest.js'import { resolveDshCommand } from './materialize.js'import { isShellNoise, killProcessGroup, spawnDshCommand } from './shell.js'+import { viewerTarget } from '../lib/viewerWire.js'/** The viewer that will actually run for a harness: its own, or the package it points at. */export interface ResolvedViewer {@@ -158,6 +159,13 @@ export class DshViewerManager {return this.states.get(agentId)?.url ?? null}+ /** Forward only the port this manager allocated to this running viewer. */+ forwardingUrl(agentId: string): string | null {+ const state = this.states.get(agentId)+ const target = viewerTarget(state?.url)+ return state?.child && target && Number(target.port) === state.port ? state.url : null+ }+/** Idempotent: the same agent, DSH and workspace keep their running viewer. */async start(agentId: string, dsh: InstalledDsh, workspace: string): Promise<void> {if (!dsh.manifest.viewer) returndiff --git a/cli/src/lib/e2ee/core.ts b/cli/src/lib/e2ee/core.tsindex 9dd3e5850..a1fb8b565 100644--- a/cli/src/lib/e2ee/core.ts+++ b/cli/src/lib/e2ee/core.ts@@ -381,6 +381,8 @@ export const ENCRYPTED_DOWN_TYPES = new Set<string>([// The desktop's pane colours for this machine's tmux sessions (lib/hostTheme.ts). Same trap as// above if missing: the envelope would never be opened and the app would wait out its timeout.'theme_set',+ // Viewer HTTP/WebSocket bytes and control travel only inside the paired machine session.+ 'viewer_request', 'viewer_data', 'viewer_ack', 'viewer_end', 'viewer_close','device_e2ee_pair', 'e2ee_pairings_list', 'e2ee_pairing_unpair','e2ee_pairings_unpair_all', 'e2ee_browser_link_create',// Remote terminal control is always pairwise E2EE. The relay may route by outer type/connId but mustdiff --git a/cli/src/lib/e2ee/manager.ts b/cli/src/lib/e2ee/manager.tsindex 270ef585b..a65eaab96 100644--- a/cli/src/lib/e2ee/manager.ts+++ b/cli/src/lib/e2ee/manager.ts@@ -109,6 +109,8 @@ export interface E2eeManagerDeps {isConnectionAvailable?: (connId: string) => booleanonIdentityPaired?: (connId: string, identityPub: string) => voidonIdentityRevoked?: (identityPub: string) => void+ /** Release connection-scoped resources on revoke, eviction, replacement and disconnect. */+ onSessionDropped?: (connId: string) => void}export class E2eeManager {@@ -157,7 +159,7 @@ export class E2eeManager {deviceConnected(): boolean { return [...this.sessions.values()].some((s) => s.role === 'device') }dropSessionsByRole(role: C.PairRole, preserve: (connId: string) => boolean = () => false): void {for (const [connId, s] of [...this.sessions.entries()]) {- if (s.role === role && !preserve(connId)) this.sessions.delete(connId)+ if (s.role === role && !preserve(connId)) this.dropSession(connId)}}@@ -236,7 +238,7 @@ export class E2eeManager {const count = this.store.count()// Device cleanup first: it needs the live session to seal a pair.revoke frame before deny drops it.for (const paired of this.store.list()) { try { this.deps.onIdentityRevoked?.(paired.identityPub) } catch { /* Continue revoking every stored identity. */ } }- for (const s of [...this.sessions.entries()]) { this.deny(s[0]); this.sessions.delete(s[0]) }+ for (const s of [...this.sessions.entries()]) { this.deny(s[0]); this.dropSession(s[0]) }this.store.clear()this.rotateGroupKey()return { count }@@ -254,7 +256,7 @@ export class E2eeManager {}private denyAndDropSessionsFor(identityPubB64: string): void {for (const [connId, s] of [...this.sessions.entries()]) {- if (s.webIdentityPub === identityPubB64) { this.deny(connId); this.sessions.delete(connId) }+ if (s.webIdentityPub === identityPubB64) { this.deny(connId); this.dropSession(connId) }}}/** New group key + epoch; re-deliver to the REMAINING (still-paired) sessions so a revoked browser@@ -718,6 +720,7 @@ export class E2eeManager {return true}this.evictIfFull()+ this.dropSession(connId)this.sessions.set(connId, {webIdentityPub: identityPub,role,@@ -734,7 +737,7 @@ export class E2eeManager {const enc = C.aeadSeal(keys.s2c, 0, C.utf8('e2e-welcome'), C.utf8(JSON.stringify({groupKey: C.b64e(this.groupKey),epoch: this.epoch,- features: { terminalP2p: 1 },+ features: { terminalP2p: 1, viewerForwarding: 1 },})))this.deps.sendTo(connId, {type: 'e2e_welcome',@@ -751,7 +754,10 @@ export class E2eeManager {/** Drop a session when its web connection closes (called from backendSocket on down close is n/a —* connections are relayed; sessions are pruned by LRU + overwrite-on-new-hello). Also cleans up any* in-progress password-PAKE attempt on this connId — the joiner may have disconnected mid-round. */- dropSession(connId: string): void { this.sessions.delete(connId); this.clearPwSlot(connId) }+ dropSession(connId: string): void {+ if (this.sessions.delete(connId)) this.deps.onSessionDropped?.(connId)+ this.clearPwSlot(connId)+ }// ── helpers ──────────────────────────────────────────────────────────────────────────────────@@ -779,7 +785,7 @@ export class E2eeManager {private evictIfFull(): void {if (this.sessions.size < MAX_SESSIONS) returnconst oldest = this.sessions.keys().next().value- if (oldest) this.sessions.delete(oldest)+ if (oldest) this.dropSession(oldest)}}diff --git a/cli/src/lib/e2ee/relayClient.ts b/cli/src/lib/e2ee/relayClient.tsindex 60637721d..e6c70ec15 100644--- a/cli/src/lib/e2ee/relayClient.ts+++ b/cli/src/lib/e2ee/relayClient.ts@@ -36,12 +36,14 @@ export class RelaySessionCrypto {private groupKey: Uint8Array | null = nullprivate epoch = ''private p2pVersion = 0+ private viewerVersion = 0private groupRecv = new Map<string, number>() // epoch -> highest counter seenconstructor(private readonly deps: RelayCryptoDeps) {}get ready(): boolean { return this.c2s !== null && this.s2c !== null }get terminalP2pVersion(): number { return this.p2pVersion }+ get viewerForwardingVersion(): number { return this.viewerVersion }helloFrame(): Frame {return {@@ -69,7 +71,7 @@ export class RelaySessionCrypto {} catch { return false }const opened = C.aeadOpen(keys.s2c, 0, C.utf8('e2e-welcome'), C.b64d(encB64))if (!opened) return false- let initial: { groupKey?: string; epoch?: string; features?: { terminalP2p?: unknown } }+ let initial: { groupKey?: string; epoch?: string; features?: { terminalP2p?: unknown; viewerForwarding?: unknown } }try { initial = JSON.parse(new TextDecoder().decode(opened)) as typeof initial } catch { return false }if (!initial.groupKey || !initial.epoch) return falsethis.c2s = keys.c2s@@ -81,6 +83,7 @@ export class RelaySessionCrypto {this.p2pVersion = Number.isSafeInteger(initial.features?.terminalP2p)? Number(initial.features?.terminalP2p): 0+ this.viewerVersion = initial.features?.viewerForwarding === 1 ? 1 : 0return true}diff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.tsindex 7772ce5c2..94c300ec1 100644--- a/cli/src/lib/remoteRelay.ts+++ b/cli/src/lib/remoteRelay.ts@@ -31,6 +31,9 @@ import {type TerminalP2pPolicy,} from './terminalP2p.js'import { warmStunUrls } from './stunSelect.js'+import { RemoteViewerProxy } from './remoteViewerProxy.js'+import { VIEWER_UP_TYPES } from './viewerWire.js'+import { isWrapped } from './e2ee/core.js'const CONNECT_TIMEOUT_MS = 15_000const LINGER_MS = 30_000@@ -88,6 +91,7 @@ function binaryBytes(raw: RawData): Uint8Array {}interface Entry {+ viewers?: RemoteViewerProxyws: WebSocketcrypto: RelaySessionCryptosink: LocalClientSink | null@@ -188,6 +192,7 @@ export class RemoteRelayPool {const entry = this.entries.get(machineId)if (!entry) returnthis.entries.delete(machineId)+ entry.viewers?.close()entry.heartbeat?.stop()if (entry.lingerTimer) clearTimeout(entry.lingerTimer)if (entry.p2pRetryTimer) clearTimeout(entry.p2pRetryTimer)@@ -289,6 +294,14 @@ export class RemoteRelayPool {upgradeOrphan: null,upgradeDone: false,}+ entry.viewers = new RemoteViewerProxy({+ supported: () => crypto.viewerForwardingVersion === 1,+ deliver: (frame) => { entry.sink?.sendFrame(frame) },+ send: (type, payload) => {+ if (!crypto.ready || ws.readyState !== WebSocket.OPEN) return false+ try { ws.send(JSON.stringify(crypto.wrapOutgoing({ type, payload }))); return true } catch { return false }+ },+ })// Two phases before this connection is usable: (1) machine_select ack, (2) this daemon's own// e2e_hello/e2e_welcome as the "client" role — see lib/e2ee/relayClient.ts. Only once BOTH are done// does the app's onOutgoing/sink start receiving anything, so it never sees a half-encrypted stream.@@ -409,6 +422,9 @@ export class RemoteRelayPool {try { ws.close(4404, 'peer revoked trust') } catch { ws.terminate() }return}+ // The relay cannot inject response bytes/headers into a local browser in plaintext.+ if (typeof frame.type === 'string' && VIEWER_UP_TYPES.has(frame.type)+ && (!isWrapped(frame.payload) || frame.payload.__e2e?.k !== 'p')) returnconst plain = crypto.unwrapIncoming(frame)if (!plain) returnconst type = typeof plain.type === 'string' ? plain.type : ''@@ -438,6 +454,7 @@ export class RemoteRelayPool {// synchronously inside it) must arrive after, or the app-side stream-id match silently drops it// (streamId is still null at that point, since terminal_ready — the thing that sets it — has// not been delivered yet).+ if (entry.sink && entry.viewers?.receive(plain)) returnentry.sink?.sendFrame(plain)this.noteTerminalResponse(entry, plain, 'relay')})@@ -454,6 +471,7 @@ export class RemoteRelayPool {try {await handshake} catch (err) {+ entry.viewers?.close()// A rejected handshake MUST take the socket down with it. Only `e2e_denied` used to; the timeout// (peer never answered e2e_hello) and `machine_select_error` just dropped their reference, leaving// an OPEN socket nothing could reach — not in `entries`, no heartbeat, but still auto-answering@@ -470,6 +488,7 @@ export class RemoteRelayPool {}// Handshake done — from here on, a close is the entry's real end-of-life, not a handshake failure.ws.on('close', (code, reasonBuf) => {+ entry.viewers?.close()entry.heartbeat?.stop()if (entry.p2pRetryTimer) clearTimeout(entry.p2pRetryTimer)if (entry.upgradeTimer) clearTimeout(entry.upgradeTimer)@@ -547,6 +566,7 @@ export class RemoteRelayPool {if (p2pFailed) this.demoteP2p(machineId, entry, 'send_failed')},detach: () => {+ entry.viewers?.reset()entry.sink = nullentry.onClosed = nullentry.lingerTimer = setTimeout(() => {diff --git a/cli/src/lib/remoteViewerProxy.faults.spec.ts b/cli/src/lib/remoteViewerProxy.faults.spec.tsnew file mode 100644index 000000000..79c8e9d45--- /dev/null+++ b/cli/src/lib/remoteViewerProxy.faults.spec.ts@@ -0,0 +1,271 @@+import { afterEach, describe, expect, it, vi } from 'vitest'+import { PassThrough } from 'node:stream'+import { RemoteViewerProxy } from './remoteViewerProxy.js'+import type { Frame } from '../backendSocket.js'++const cleanup: Array<() => void> = []+afterEach(() => { cleanup.splice(0).reverse().forEach((close) => close()); vi.restoreAllMocks() })+const tick = () => new Promise<void>((resolve) => setImmediate(resolve))++function fixture() {+ const delivered: Frame[] = []+ const send = vi.fn((_type: string, _p: Record<string, unknown>) => true)+ const proxy = new RemoteViewerProxy({ supported: () => true, send, deliver: (f) => delivered.push(f) })+ cleanup.push(() => proxy.close())+ // Fault injection at the HTTP boundary: production instances and handlers, synthetic broken peers.+ const state = proxy as any+ const announce = async (agent: unknown) => {+ proxy.receive({ type: 'agent_synced', payload: { agent } })+ await state.metadata+ return (delivered.at(-1)?.payload as any)?.agent+ }+ const gateway = async () => {+ await announce({ id: 'a', viewerUrl: 'http://127.0.0.1:4321/' })+ return state.gateways.get('a')+ }+ return { proxy, state, send, delivered, announce, gateway }+}++class Response extends PassThrough {+ status = 0+ headersSent = false+ headers: Record<string, unknown> = {}+ setHeader(key: string, value: unknown) { this.headers[key.toLowerCase()] = value }+ writeHead(status: number, headers: Record<string, unknown> = {}) { this.status = status; Object.assign(this.headers, headers); this.headersSent = true; return this }+ flushHeaders() {}+}++function request(gateway: any, overrides: Record<string, unknown> = {}) {+ return Object.assign(new PassThrough(), {+ url: '/', method: 'GET', headers: {+ host: new URL(gateway.origin).host, cookie: `${gateway.cookie}=${gateway.token}`,+ }, ...overrides,+ })+}++describe('remote viewer metadata lifecycle', () => {+ it('passes non-viewer events, malformed metadata and public URLs without allocating a gateway', async () => {+ const f = fixture()+ expect(f.proxy.receive({})).toBe(false)+ expect(f.proxy.receive({ type: 'turn_started' })).toBe(false)+ expect(f.proxy.receive({ type: 'viewer_data' })).toBe(true)+ expect(f.proxy.receive({ type: 'viewer_response', payload: { streamId: 'absent' } })).toBe(true)+ for (const frame of [{ type: 'agent_deleted' }, { type: 'agent_created', payload: {} }]) {+ f.proxy.receive(frame)+ await f.state.metadata+ expect(f.delivered.at(-1)).toEqual(frame)+ }+ for (const raw of ['agent', { name: 'no id' }, { id: 'a', viewerUrl: 'https://example.com/' }, { id: 'b', viewerUrl: 'not a URL' }]) {+ expect(await f.announce(raw)).toEqual(raw)+ }+ expect(await f.announce({ id: 'a', viewerUrl: 'https://localhost:443/' })).toMatchObject({ viewerUrl: null, viewerError: expect.any(String) })+ f.proxy.receive({ type: 'agents_list_result', payload: { agents: [null, { id: 'a' }] } })+ await f.state.metadata+ expect((f.delivered.at(-1)?.payload as any).agents).toEqual([null, { id: 'a' }])+ })++ it('replaces gateways on port changes, deletes agents and caps the number of open viewers', async () => {+ const f = fixture()+ const gateway = await f.gateway()+ f.proxy.receive({ type: 'agents_list_result', payload: { agents: [{ id: 'a', viewerUrl: 'http://127.0.0.1:4321/' }] } })+ await f.state.metadata+ expect(f.state.gateways.get('a')).toBe(gateway)+ await f.announce({ id: 'a', viewerUrl: 'http://127.0.0.1:4322/' })+ expect(f.state.gateways.get('a')).not.toBe(gateway)+ f.proxy.receive({ type: 'agent_deleted', payload: { agentId: 'a' } })+ await f.state.metadata+ expect(f.state.gateways.size).toBe(0)+ f.proxy.receive({ type: 'agents_list_result', payload: { agents: Array.from({ length: 65 }, (_, i) => ({ id: `a${i}`, viewerUrl: 'http://127.0.0.1:4321/' })) } })+ await f.state.metadata+ expect(f.state.gateways.size).toBe(64)+ expect((f.delivered.at(-1)?.payload as any).agents.at(-1).viewerError).toContain('Too many')+ })++ it('drops queued frames and pending binds when the client detaches, without leaking listeners', async () => {+ const f = fixture()+ f.proxy.receive({ type: 'agent_created', payload: { agent: { id: 'a', viewerUrl: 'http://127.0.0.1:4321/' } } })+ f.proxy.reset()+ await f.state.metadata+ expect(f.delivered).toHaveLength(0)+ const create = f.state.createGateway.bind(f.state)+ vi.spyOn(f.state, 'createGateway').mockImplementation(async (...args: unknown[]) => {+ const gateway = await create(...args)+ f.proxy.reset()+ return gateway+ })+ f.proxy.receive({ type: 'agents_list_result', payload: { agents: [{ id: 'a', viewerUrl: 'http://127.0.0.1:4321/' }, { id: 'b', viewerUrl: 'http://127.0.0.1:4321/' }] } })+ await f.state.metadata+ expect(f.state.gateways.size).toBe(0)+ expect(f.delivered).toHaveLength(0)+ f.proxy.close()+ await f.announce({ id: 'b', viewerUrl: 'http://127.0.0.1:4321/' })+ expect(f.delivered).toHaveLength(0)+ })++ it('returns safe updateable metadata on bind failure instead of timing out the agent RPC', async () => {+ const f = fixture()+ vi.spyOn(f.state, 'createGateway').mockRejectedValue(new Error('no ports available'))+ const failed = await f.announce({ id: 'a', viewerUrl: 'http://127.0.0.1:4321/' })+ expect(failed.viewerUrl).toBeNull()+ expect(failed.viewerError).toContain('could not be opened')+ f.proxy.receive({ type: 'agents_list_result', payload: { agents: [{ id: 'a', viewerUrl: 'http://127.0.0.1:4321/' }, { id: 'b', viewerUrl: 'https://example.com/' }, null] } })+ await f.state.metadata+ expect((f.delivered.at(-1)?.payload as any).agents[1].viewerUrl).toBe('https://example.com/')+ vi.spyOn(f.state, 'rewrite').mockRejectedValue(new Error('interrupted metadata processing'))+ f.proxy.receive({ type: 'agent_created' })+ await f.state.metadata+ expect(f.delivered.at(-1)).toEqual({ type: 'agent_created' })+ f.proxy.receive({ type: 'agent_created', payload: {} })+ await f.state.metadata+ expect(f.delivered.at(-1)).toEqual({ type: 'agent_created', payload: {} })+ f.proxy.receive({ type: 'agent_created', payload: { agent: 'malformed' } })+ await f.state.metadata+ expect((f.delivered.at(-1)?.payload as any).agent).toBe('malformed')+ const delivered = f.delivered.length+ f.proxy.receive({ type: 'agent_created' })+ await Promise.resolve() // let rewrite start, then cancel before its rejection is handled+ f.proxy.reset()+ await f.state.metadata+ expect(f.delivered.length).toBe(delivered)+ })+})++describe('local HTTP boundaries and remote failures', () => {+ it('contains socket/server errors and refuses CONNECT, invalid HTTP and unsafe bootstrap redirects', async () => {+ const f = fixture()+ const gateway = await f.gateway()+ const socket = new PassThrough()+ gateway.server.emit('connection', socket)+ socket.emit('error', new Error('peer disconnected'))+ gateway.server.emit('connect', {}, socket)+ expect(socket.destroyed).toBe(true)+ const malformed = new PassThrough()+ gateway.server.emit('clientError', new Error('invalid HTTP'), malformed)+ expect(malformed.destroyed).toBe(true)+ for (const url of ['http://evil.example/', '//[', '/back\\slash', '/space here']) {+ const response = new Response()+ f.state.serve(gateway, request(gateway, { url }), response)+ expect(response.status).toBe(400)+ }+ const foreign = request(gateway)+ Object.assign(foreign.headers, { referer: 'https://evil.example/' })+ const forbidden = new Response()+ f.state.serve(gateway, foreign, forbidden)+ expect(forbidden.status).toBe(403)+ f.state.serve(gateway, request(gateway, { url: undefined }), new Response())+ const noCookie = request(gateway)+ delete (noCookie.headers as any).cookie+ f.state.open(gateway, noCookie, false, () => {})+ for (const path of ['https://evil.example', '//evil.example', '/\\evil.example', '/\nfoo']) {+ const res = new Response()+ f.state.serve(gateway, request(gateway, { url: `/__harness_viewer/${gateway.token}?path=${encodeURIComponent(path)}` }), res)+ expect(res.status).toBe(400)+ }+ const res = new Response()+ f.state.serve(gateway, request(gateway, { url: `/__harness_viewer/${gateway.token}` }), res)+ expect(res.headers.Location).toBe('/')+ gateway.server.emit('error', new Error('listener failed'))+ expect(f.state.gateways.size).toBe(0)+ })++ it.each([199, 600, 200.5, 'bad', 101])('rejects invalid upstream HTTP status %s', async (status) => {+ const f = fixture()+ const gateway = await f.gateway()+ const res = new Response()+ f.state.serve(gateway, request(gateway), res)+ const stream = [...f.state.wires.values()][0] as any+ stream.response({ status, headers: {} })+ await tick()+ expect(res.status).toBe(502)+ })++ it('refuses unsolicited upgrade metadata, duplicate responses, bad headers and interrupted bodies', async () => {+ const f = fixture()+ const gateway = await f.gateway()+ for (const kind of ['upgrade', 'headers', 'duplicate', 'interrupted', 'request-error']) {+ const req = request(gateway)+ const res = new Response()+ f.state.serve(gateway, req, res)+ const stream = [...f.state.wires.values()].at(-1) as any+ if (kind === 'upgrade') stream.response({ status: 200, headers: {}, upgrade: true })+ else if (kind === 'headers') stream.response({ status: 200, headers: { bad: '\n' } })+ else if (kind === 'request-error') req.emit('error', new Error('upload interrupted'))+ else {+ stream.response({ status: 200, headers: {} })+ if (kind === 'duplicate') stream.response({ status: 200, headers: {} })+ else stream.wire.handle('viewer_close', { error: 'lost upstream' })+ }+ await tick()+ expect(res.destroyed || res.status === 502, kind).toBe(true)+ }+ })++ it('caps active requests and rejects new work on a disposed proxy', async () => {+ const f = fixture()+ const gateway = await f.gateway()+ for (let i = 0; i < 64; i++) f.state.open(gateway, request(gateway), false, () => {})+ const res = new Response()+ f.state.serve(gateway, request(gateway), res)+ expect(res.status).toBe(503)+ const socket = new PassThrough()+ f.state.serveUpgrade(gateway, request(gateway, { headers: { host: new URL(gateway.origin).host, cookie: `${gateway.cookie}=${gateway.token}`, upgrade: 'websocket' } }), socket, Buffer.alloc(0))+ expect(socket.destroyed).toBe(true)+ f.proxy.close()+ expect(f.state.open(gateway, request(gateway), false, () => {})).toBeNull()+ })++ it('handles a failed send and malformed outgoing headers without exposing loopback cookies', async () => {+ const f = fixture()+ const gateway = await f.gateway()+ for (const invalidHeaders of [false, true]) {+ const res = new Response()+ const req = request(gateway)+ if (invalidHeaders) (req.headers as any).invalid = '\r\n'+ f.send.mockReturnValue(false)+ f.state.serve(gateway, req, res)+ await tick()+ expect(res.status).toBe(502)+ }+ const req = request(gateway)+ Object.assign(req.headers, { referer: `${gateway.origin}/page`, origin: gateway.origin })+ f.send.mockReturnValue(true)+ f.state.open(gateway, req, false, () => {})+ expect(f.send).toHaveBeenCalledWith('viewer_request', expect.objectContaining({ headers: expect.objectContaining({ referer: 'http://127.0.0.1:4321/page' }) }))+ expect(f.state.responseHeaders(gateway, { location: 'https://example.com/', 'set-cookie': 'a=b; Domain=localhost; Path=/' }))+ .toMatchObject({ location: 'https://example.com/', 'set-cookie': [`${gateway.cookie}_a=b; Path=/`] })+ })+})++describe('WebSocket proxy failures', () => {+ it('refuses unauthorized upgrades before sending any remote request', async () => {+ const f = fixture()+ const gateway = await f.gateway()+ const req = request(gateway)+ for (const headers of [{}, { ...req.headers, origin: 'https://evil.example' }, { ...req.headers, cookie: '', upgrade: 'websocket' }, { ...req.headers, upgrade: 'h2c' }]) {+ const socket = new PassThrough()+ f.state.serveUpgrade(gateway, request(gateway, { headers }), socket, Buffer.alloc(0))+ expect(socket.read()?.toString()).toContain('403')+ }+ expect(f.send).not.toHaveBeenCalled()+ })++ it.each(['declined', 'not-upgrade', 'headers', 'duplicate', 'socket-error'])('cleans up a %s upgrade', async (kind) => {+ const f = fixture()+ const gateway = await f.gateway()+ const req = request(gateway)+ Object.assign(req.headers, { upgrade: 'websocket' })+ const socket = new PassThrough()+ f.state.serveUpgrade(gateway, req, socket, Buffer.from('client-head'))+ const stream = [...f.state.wires.values()][0] as any+ if (kind === 'declined') stream.response({ status: 403 })+ else if (kind === 'not-upgrade') stream.response({ status: 101, upgrade: false })+ else if (kind === 'headers') stream.response({ status: 101, upgrade: true, headers: { bad: '\n' } })+ else {+ stream.response({ status: 101, upgrade: true, headers: { 'set-cookie': ['a=b', 'c=d'] } })+ if (kind === 'duplicate') stream.response({ status: 101, upgrade: true, headers: {} })+ else socket.emit('error', new Error('client dropped'))+ }+ await tick()+ expect(socket.destroyed).toBe(true)+ })+})diff --git a/cli/src/lib/remoteViewerProxy.spec.ts b/cli/src/lib/remoteViewerProxy.spec.tsnew file mode 100644index 000000000..2895af940--- /dev/null+++ b/cli/src/lib/remoteViewerProxy.spec.ts@@ -0,0 +1,238 @@+import { afterEach, describe, expect, it } from 'vitest'+import { once } from 'node:events'+import { createServer, request, type IncomingHttpHeaders, type Server } from 'node:http'+import type { AddressInfo } from 'node:net'+import { WebSocket, WebSocketServer } from 'ws'+import { RemoteViewerProxy } from './remoteViewerProxy.js'+import { ViewerForwarder } from './viewerForwarder.js'+import { VIEWER_CHUNK_BYTES, VIEWER_WINDOW_BYTES, ViewerWire } from './viewerWire.js'+import type { Frame } from '../backendSocket.js'++const cleanup: Array<() => void | Promise<void>> = []+afterEach(async () => { for (const close of cleanup.splice(0).reverse()) await close() })++async function listen(server: Server): Promise<string> {+ server.listen(0, '127.0.0.1')+ await once(server, 'listening')+ cleanup.push(() => { server.closeAllConnections(); server.close() })+ return `http://127.0.0.1:${(server.address() as AddressInfo).port}`+}++function http(url: string, headers: Record<string, string> = {}, body?: Buffer): Promise<{ status: number; headers: IncomingHttpHeaders; bytes: Buffer }> {+ return new Promise((resolve, reject) => {+ const req = request(url, { headers, method: body ? 'POST' : 'GET', agent: false }, (res) => {+ const parts: Buffer[] = []+ res.on('data', (data) => parts.push(data))+ res.on('error', reject)+ res.on('end', () => resolve({ status: res.statusCode!, headers: res.headers, bytes: Buffer.concat(parts) }))+ })+ req.on('error', reject)+ req.end(body)+ })+}++async function fixture(options: { supported?: boolean } = {}) {+ const bytes = Buffer.alloc(1024 * 1024 + 137)+ for (let i = 0; i < bytes.length; i++) bytes[i] = i % 251+ const seen: Array<{ path: string; headers: IncomingHttpHeaders }> = []+ const server = createServer((req, res) => {+ seen.push({ path: req.url!, headers: req.headers })+ if (req.url === '/bytes') {+ const partial = req.headers.range === 'bytes=17-991'+ const content = partial ? bytes.subarray(17, 992) : bytes+ res.writeHead(partial ? 206 : 200, { 'Content-Type': 'application/octet-stream', 'Content-Length': content.length, ...(partial ? { 'Content-Range': `bytes 17-991/${bytes.length}` } : {}) })+ res.end(content)+ } else if (req.url === '/upload') {+ req.pipe(res)+ } else if (req.url === '/redirect') {+ res.writeHead(302, { Location: `${origin}/page?q=1` }).end()+ } else if (req.url === '/cookie') {+ res.writeHead(200, { 'Set-Cookie': ['session=remote-secret; Path=/; HttpOnly'] }).end('cookie')+ } else if (req.url === '/events') {+ res.writeHead(200, { 'Content-Type': 'text/event-stream' })+ res.write('data: first\n\n')+ // Deliberately leave it live until the local consumer cancels.+ } else res.end('<html><img src="/bytes">Remote viewer</html>')+ })+ const origin = await listen(server)+ const wss = new WebSocketServer({ server })+ cleanup.push(() => { for (const socket of wss.clients) socket.terminate(); wss.close() })+ wss.on('connection', (socket, req) => {+ seen.push({ path: req.url!, headers: req.headers })+ socket.on('message', (data, binary) => socket.send(data, { binary }))+ })+ const targets = new Map([['agent-a', `${origin}/page?file=a.step`], ['agent-b', `${origin}/`]])+ let deliver: (frame: Frame) => void = () => {}+ let proxy: RemoteViewerProxy+ const forwarder = new ViewerForwarder({+ target: (id) => targets.get(id) ?? null,+ send: (_conn, type, payload) => { queueMicrotask(() => proxy.receive({ type, payload })); return true },+ })+ proxy = new RemoteViewerProxy({+ supported: () => options.supported ?? true,+ send: (type, payload) => { queueMicrotask(() => forwarder.handle('owner', type, payload)); return true },+ deliver: (frame) => deliver(frame),+ })+ cleanup.push(() => { proxy.close(); forwarder.closeAll() })+ const frame = (type: string, payload: Record<string, unknown>) => new Promise<Record<string, any>>((resolve) => {+ deliver = (result) => resolve(result.payload as Record<string, any>)+ proxy.receive({ type, payload })+ })+ const agent = async (id = 'agent-a') => (await frame('agent_synced', { agent: { id, viewerUrl: targets.get(id) ?? null } })).agent as { viewerUrl: string | null; viewerError?: string }+ const open = async (id = 'agent-a') => {+ const rewritten = await agent(id)+ const bootstrap = await http(rewritten.viewerUrl!)+ expect(bootstrap.status).toBe(302)+ const local = new URL(rewritten.viewerUrl!).origin+ const cookie = bootstrap.headers['set-cookie']![0].split(';')[0]+ return { local, cookie, url: rewritten.viewerUrl!, bootstrap }+ }+ return { origin, bytes, seen, proxy, forwarder, targets, frame, agent, open }+}++describe('remote viewer HTTP and WebSocket forwarding', () => {+ it('rewrites only remote viewer URLs, preserves paths, and streams assets and byte ranges', async () => {+ const f = await fixture()+ const { local, cookie, bootstrap } = await f.open()+ expect(bootstrap.headers.location).toBe('/page?file=a.step')+ expect(local).not.toBe(f.origin)+ expect((await http(local + bootstrap.headers.location, { cookie })).bytes.toString()).toContain('Remote viewer')+ const full = await http(local + '/bytes', { cookie })+ expect(full.bytes.equals(f.bytes)).toBe(true)+ const range = await http(local + '/bytes', { cookie, range: 'bytes=17-991' })+ expect(range.status).toBe(206)+ expect(range.headers['content-range']).toBe(`bytes 17-991/${f.bytes.length}`)+ expect(range.bytes.equals(f.bytes.subarray(17, 992))).toBe(true)+ expect((await http(local + '/redirect', { cookie })).headers.location).toBe(local + '/page?q=1')+ const upload = await http(local + '/upload', { cookie, origin: local }, f.bytes)+ expect(upload.bytes.equals(f.bytes)).toBe(true)+ expect(f.seen.at(-1)?.headers.origin).toBe(f.origin)+ expect(f.seen.at(-1)?.headers.host).toBe(new URL(f.origin).host)+ })++ it('blocks unauthenticated access, foreign origins, DNS rebinding and cross-viewer cookies', async () => {+ const f = await fixture()+ const a = await f.open()+ const b = await f.open('agent-b')+ expect(a.local).not.toBe(b.local)+ const denied: Array<Record<string, string>> = [+ {}, { cookie: b.cookie }, { cookie: a.cookie, origin: 'https://evil.example' },+ { cookie: a.cookie, origin: 'null' }, { cookie: a.cookie, host: 'evil.example' },+ { cookie: a.cookie, 'sec-fetch-site': 'cross-site' },+ ]+ for (const headers of denied) expect((await http(a.local + '/', headers)).status).toBe(403)+ expect(f.seen).toHaveLength(0)+ const response = await http(a.local + '/cookie', { cookie: `${a.cookie}; unrelated=local-secret` })+ const remoteCookie = response.headers['set-cookie']![0].split(';')[0]+ await http(a.local + '/', { cookie: `${a.cookie}; ${remoteCookie}; unrelated=local-secret` })+ expect(f.seen.at(-1)?.headers.cookie).toBe('session=remote-secret')+ })++ it('delivers SSE before the response ends and cancels it when the pane connection closes', async () => {+ const f = await fixture()+ const { local, cookie } = await f.open()+ await new Promise<void>((resolve, reject) => {+ const req = request(local + '/events', { headers: { cookie }, agent: false }, (res) => {+ res.once('data', (chunk) => {+ expect(chunk.toString()).toBe('data: first\n\n')+ expect(res.complete).toBe(false)+ res.destroy()+ resolve()+ })+ res.on('error', reject)+ })+ req.on('error', reject)+ req.end()+ })+ })++ it('preserves WebSocket protocol, origin and large binary messages', async () => {+ const f = await fixture()+ const { local, cookie } = await f.open()+ const socket = new WebSocket(local.replace('http:', 'ws:') + '/ws', ['viewer-live'], { headers: { cookie }, origin: local })+ cleanup.push(() => socket.terminate())+ await once(socket, 'open')+ expect(socket.protocol).toBe('viewer-live')+ const answer = once(socket, 'message')+ socket.send(f.bytes)+ const [bytes, binary] = await answer+ expect(binary).toBe(true)+ expect((bytes as Buffer).equals(f.bytes)).toBe(true)+ expect(f.seen.at(-1)?.headers.origin).toBe(f.origin)+ socket.close()+ await once(socket, 'close')+ })++ it('updates artifacts on the same gateway and removes access on viewer stop, detach and missing agents', async () => {+ const f = await fixture()+ const a = await f.open()+ f.targets.set('agent-a', `${f.origin}/?file=new%20part.step#view`)+ const changed = await f.agent()+ expect(new URL(changed.viewerUrl!).origin).toBe(a.local)+ expect((await http(changed.viewerUrl!)).headers.location).toBe('/?file=new%20part.step#view')+ f.targets.delete('agent-a')+ f.forwarder.refresh('agent-a')+ expect((await f.agent()).viewerUrl).toBeNull()+ await expect(http(a.local + '/', { cookie: a.cookie })).rejects.toThrow()+ const b = await f.open('agent-b')+ await f.frame('agents_list_result', { agents: [] })+ await expect(http(b.local + '/', { cookie: b.cookie })).rejects.toThrow()+ const c = await f.open('agent-b')+ f.proxy.reset()+ await expect(http(c.local + '/', { cookie: c.cookie })).rejects.toThrow()+ })++ it('gives update guidance for old daemons and never exposes their loopback URL', async () => {+ const f = await fixture({ supported: false })+ expect(await f.agent()).toMatchObject({ viewerUrl: null, viewerError: expect.stringContaining('Update Harness') })+ })++ it('rejects arbitrary destinations and isolates stream ids by connection', async () => {+ const f = await fixture()+ const replies: Array<{ conn: string; type: string; payload: Record<string, unknown> }> = []+ const forwarder = new ViewerForwarder({+ target: (id) => f.targets.get(id) ?? null,+ send: (conn, type, payload) => { replies.push({ conn, type, payload }); return true },+ })+ cleanup.push(() => forwarder.closeAll())+ const base = { streamId: 'test', agentId: 'agent-a', origin: f.origin, path: '/', method: 'GET', headers: {} }+ for (const override of [+ { agentId: 'missing' }, { origin: 'http://127.0.0.1:22' }, { path: 'http://evil.example/' },+ { method: 'CONNECT' }, { headers: { host: 'localhost\r\nBad: x' } },+ ]) {+ forwarder.handle('owner', 'viewer_request', { ...base, ...override })+ expect(replies.at(-1)?.type).toBe('viewer_close')+ }+ expect(f.seen).toHaveLength(0)+ forwarder.handle('owner', 'viewer_request', base)+ forwarder.handle('intruder', 'viewer_close', { streamId: 'test' })+ forwarder.handle('owner', 'viewer_end', { streamId: 'test' })+ await new Promise<void>((resolve) => {+ const timer = setInterval(() => {+ if (replies.some((r) => r.type === 'viewer_response')) { clearInterval(timer); resolve() }+ }, 5)+ })+ expect(replies.find((r) => r.type === 'viewer_response')?.conn).toBe('owner')+ })+})++describe('viewer flow control', () => {+ it('caps bytes in flight while a receiver is stalled and rejects excess credit/data', async () => {+ const sent: Array<{ type: string; p: Record<string, unknown> }> = []+ const wire = new ViewerWire('a', (type, p) => { sent.push({ type, p }); return true })+ cleanup.push(() => { wire.destroy() })+ wire.write(Buffer.alloc(VIEWER_WINDOW_BYTES * 3))+ expect(sent.filter((f) => f.type === 'viewer_data')).toHaveLength(VIEWER_WINDOW_BYTES / VIEWER_CHUNK_BYTES)+ wire.handle('viewer_ack', { bytes: VIEWER_CHUNK_BYTES })+ expect(sent.filter((f) => f.type === 'viewer_data')).toHaveLength(VIEWER_WINDOW_BYTES / VIEWER_CHUNK_BYTES + 1)+ wire.handle('viewer_ack', { bytes: VIEWER_WINDOW_BYTES + 1 })+ expect(wire.destroyed).toBe(true)++ const receiver = new ViewerWire('b', () => true)+ cleanup.push(() => { receiver.destroy() })+ for (let i = 0; i <= VIEWER_WINDOW_BYTES / VIEWER_CHUNK_BYTES; i++) {+ receiver.handle('viewer_data', { data: Buffer.alloc(VIEWER_CHUNK_BYTES).toString('base64') })+ }+ expect(receiver.destroyed).toBe(true)+ })+})diff --git a/cli/src/lib/remoteViewerProxy.ts b/cli/src/lib/remoteViewerProxy.tsnew file mode 100644index 000000000..ab6d53447--- /dev/null+++ b/cli/src/lib/remoteViewerProxy.ts@@ -0,0 +1,284 @@+import { randomBytes, randomUUID } from 'node:crypto'+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'+import type { AddressInfo, Socket } from 'node:net'+import type { Duplex } from 'node:stream'+import type { Frame } from '../backendSocket.js'+import { VIEWER_MAX_STREAMS, VIEWER_UP_TYPES, ViewerWire, viewerHeaders, viewerTarget, type ViewerSend } from './viewerWire.js'++interface Gateway {+ agentId: string+ target: URL+ server: Server+ origin: string+ token: string+ cookie: string+ sockets: Set<Socket>+ wires: Set<ViewerWire>+}++const BOOTSTRAP = '/__harness_viewer/'+const MAX_VIEWERS = 64++/**+ * Runs on the desktop's daemon, after E2EE decryption. One private HTTP origin per remote viewer+ * preserves root-relative assets, iframes, EventSource, Range requests and WebSocket URLs. The+ * bootstrap URL establishes an HttpOnly cookie then redirects to the viewer's original path.+ * Cross-origin requests and requests without that cookie never reach the remote machine.+ */+export class RemoteViewerProxy {+ private readonly gateways = new Map<string, Gateway>()+ private readonly wires = new Map<string, { wire: ViewerWire; response: (payload: Record<string, unknown>) => void }>()+ private metadata = Promise.resolve()+ private generation = 0+ private disposed = false++ constructor(private readonly deps: {+ supported: () => boolean+ send: ViewerSend+ deliver: (frame: Frame) => void+ }) {}++ /** Viewer bytes are consumed here, never delivered to the desktop's control socket. */+ receive(frame: Frame): boolean {+ const type = typeof frame.type === 'string' ? frame.type : ''+ const payload = frame.payload && typeof frame.payload === 'object' ? frame.payload as Record<string, unknown> : {}+ if (VIEWER_UP_TYPES.has(type)) {+ const stream = this.wires.get(String(payload.streamId))+ if (type === 'viewer_response') stream?.response(payload)+ else stream?.wire.handle(type, payload)+ return true+ }+ const metadata = ['agents_list_result', 'agent_synced', 'agent_created', 'agent_create_result', 'agent_create_status_result', 'agent_restart_result', 'agent_deleted'].includes(type)+ if (!metadata) return false+ const generation = this.generation+ this.metadata = this.metadata.then(async () => {+ if (this.disposed || generation !== this.generation) return+ const rewritten = await this.rewrite(frame)+ if (!this.disposed && generation === this.generation) this.deps.deliver(rewritten)+ }).catch(() => {+ // A local bind failure must not turn an agents_list RPC into a timeout.+ if (!this.disposed && generation === this.generation) this.deps.deliver(frameWithViewerError(frame))+ })+ return true+ }++ private async rewrite(frame: Frame): Promise<Frame> {+ const generation = this.generation+ const p = frame.payload as Record<string, unknown> | undefined+ if (!p) return frame+ if (frame.type === 'agent_deleted' && typeof p.agentId === 'string') this.remove(p.agentId)+ if (Array.isArray(p.agents)) {+ const ids = new Set(p.agents.map((a) => (a as { id?: unknown })?.id))+ for (const id of this.gateways.keys()) if (!ids.has(id)) this.remove(id)+ const agents = []+ for (const agent of p.agents) {+ if (this.disposed || generation !== this.generation) return frame+ agents.push(await this.rewriteAgent(agent))+ }+ return { ...frame, payload: { ...p, agents } }+ }+ if (p.agent) return { ...frame, payload: { ...p, agent: await this.rewriteAgent(p.agent) } }+ return frame+ }++ private async rewriteAgent(raw: unknown): Promise<unknown> {+ const generation = this.generation+ if (!raw || typeof raw !== 'object') return raw+ const agent = raw as Record<string, unknown>+ if (typeof agent.id !== 'string') return raw+ const target = viewerTarget(agent.viewerUrl)+ if (!target) {+ this.remove(agent.id)+ // Public HTTP(S) URLs remain ordinary URLs; remote loopback URLs must never be opened locally.+ if (agent.viewerUrl && isLoopbackUrl(agent.viewerUrl)) return { ...agent, viewerUrl: null, viewerError: 'This remote viewer requires an HTTP loopback URL.' }+ return raw+ }+ if (!this.deps.supported()) {+ this.remove(agent.id)+ return { ...agent, viewerUrl: null, viewerError: 'Update Harness on the remote machine to show its viewer.' }+ }+ let gateway = this.gateways.get(agent.id)+ if (gateway?.target.origin !== target.origin) { this.remove(agent.id); gateway = undefined }+ if (!gateway) {+ if (this.gateways.size >= MAX_VIEWERS) return { ...agent, viewerUrl: null, viewerError: 'Too many remote viewers are open.' }+ gateway = await this.createGateway(agent.id, target)+ if (this.disposed || generation !== this.generation) { this.closeGateway(gateway); return { ...agent, viewerUrl: null } }+ this.gateways.set(agent.id, gateway)+ }+ gateway.target = target+ const path = target.pathname + target.search + target.hash+ return { ...agent, viewerUrl: `${gateway.origin}${BOOTSTRAP}${gateway.token}?path=${encodeURIComponent(path)}`, viewerError: null }+ }++ private async createGateway(agentId: string, target: URL): Promise<Gateway> {+ const token = randomBytes(24).toString('hex')+ const server = createServer()+ const gateway: Gateway = { agentId, target, server, token, cookie: `hv_${token}`, origin: '', sockets: new Set(), wires: new Set() }+ server.on('connection', (socket) => {+ gateway.sockets.add(socket)+ socket.on('error', () => {})+ socket.on('close', () => gateway.sockets.delete(socket))+ })+ server.on('request', (req, res) => this.serve(gateway, req, res))+ server.on('upgrade', (req, socket, head) => this.serveUpgrade(gateway, req, socket, head))+ server.on('connect', (_req, socket) => socket.destroy())+ server.on('clientError', (_error, socket) => socket.destroy())+ await new Promise<void>((resolve, reject) => {+ server.once('error', reject)+ server.listen(0, '127.0.0.1', () => { server.off('error', reject); resolve() })+ })+ server.on('error', () => this.remove(agentId))+ server.unref()+ gateway.origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`+ return gateway+ }++ private allowed(gateway: Gateway, req: IncomingMessage): boolean {+ return req.headers.host === new URL(gateway.origin).host+ && (!req.headers.origin || req.headers.origin === gateway.origin)+ && !['cross-site', 'same-site'].includes(String(req.headers['sec-fetch-site']))+ && (!req.headers.referer || req.headers.referer.startsWith(`${gateway.origin}/`))+ }++ private authenticated(gateway: Gateway, req: IncomingMessage): boolean {+ return String(req.headers.cookie ?? '').split(';').some((part) => part.trim() === `${gateway.cookie}=${gateway.token}`)+ }++ private serve(gateway: Gateway, req: IncomingMessage, res: ServerResponse): void {+ res.setHeader('Referrer-Policy', 'no-referrer')+ res.setHeader('Cache-Control', 'no-store')+ if (!this.allowed(gateway, req)) { res.writeHead(403).end('Viewer access denied'); return }+ const requestPath = req.url ?? '/'+ if (!requestPath.startsWith('/') || requestPath.startsWith('//') || /[\s\\]/.test(requestPath)) {+ res.writeHead(400).end('Invalid viewer path'); return+ }+ const url = new URL(requestPath, gateway.origin)+ if (req.method === 'GET' && url.pathname === `${BOOTSTRAP}${gateway.token}`) {+ const path = url.searchParams.get('path') ?? '/'+ if (!path.startsWith('/') || path.startsWith('//') || /[\r\n\\]/.test(path)) { res.writeHead(400).end(); return }+ res.setHeader('Set-Cookie', `${gateway.cookie}=${gateway.token}; Path=/; HttpOnly; SameSite=Strict`)+ res.writeHead(302, { Location: path }).end()+ return+ }+ if (!this.authenticated(gateway, req)) { res.writeHead(403).end('Viewer access denied'); return }+ let responded = false+ const wire = this.open(gateway, req, false, (p, stream) => {+ if (responded) { stream.destroy(new Error('Duplicate viewer response')); return }+ try {+ const status = Number(p.status)+ if (!Number.isInteger(status) || status < 200 || status > 599 || p.upgrade === true) throw new Error('Invalid response')+ responded = true+ res.writeHead(status, this.responseHeaders(gateway, p.headers))+ res.flushHeaders()+ stream.ready()+ stream.pipe(res)+ } catch { stream.destroy(new Error('Invalid viewer response')) }+ })+ if (!wire) { res.writeHead(503).end('Too many viewer requests'); return }+ wire.on('error', () => {+ if (res.headersSent) res.destroy()+ else res.writeHead(502).end('The remote viewer disconnected. Reload to try again.')+ })+ res.on('close', () => wire.destroy())+ req.on('error', () => wire.destroy(new Error('Viewer request interrupted')))+ req.pipe(wire)+ }++ private serveUpgrade(gateway: Gateway, req: IncomingMessage, socket: Duplex, head: Buffer): void {+ if (!this.allowed(gateway, req) || !this.authenticated(gateway, req) || req.headers.upgrade?.toLowerCase() !== 'websocket') {+ socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'); return+ }+ let responded = false+ const wire = this.open(gateway, req, true, (p, stream) => {+ if (responded) { stream.destroy(); return }+ responded = true+ if (p.status !== 101 || p.upgrade !== true) { socket.end('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'); stream.destroy(); return }+ try {+ const headers = this.responseHeaders(gateway, p.headers, true)+ const lines = Object.entries(headers).flatMap(([key, value]) => (Array.isArray(value) ? value : [value]).map((v) => `${key}: ${v}`))+ socket.write(`HTTP/1.1 101 Switching Protocols\r\n${lines.join('\r\n')}\r\n\r\n`)+ stream.ready()+ if (head.length) stream.write(head)+ socket.pipe(stream).pipe(socket)+ } catch { stream.destroy() }+ })+ if (!wire) { socket.destroy(); return }+ wire.on('error', () => socket.destroy())+ wire.on('close', () => socket.destroy())+ socket.on('error', () => wire.destroy())+ socket.on('close', () => wire.destroy())+ }++ private open(gateway: Gateway, req: IncomingMessage, upgrade: boolean, response: (p: Record<string, unknown>, wire: ViewerWire) => void): ViewerWire | null {+ if (this.disposed || this.wires.size >= VIEWER_MAX_STREAMS) return null+ const id = randomUUID()+ const wire = new ViewerWire(id, this.deps.send)+ this.wires.set(id, { wire, response: (p) => response(p, wire) })+ gateway.wires.add(wire)+ wire.on('close', () => { this.wires.delete(id); gateway.wires.delete(wire) })+ try {+ const headers = viewerHeaders(req.headers, upgrade)+ headers.host = gateway.target.host+ if (headers.origin) headers.origin = gateway.target.origin+ if (headers.referer) headers.referer = String(headers.referer).replace(gateway.origin, gateway.target.origin)+ // Cookies are scoped to hosts, not ports. Only this gateway's namespaced viewer cookies cross+ // the wire; the bootstrap credential and other loopback apps' cookies stay on this computer.+ const cookies = String(headers.cookie ?? '').split(';').map((s) => s.trim())+ .filter((s) => s.startsWith(`${gateway.cookie}_`)).map((s) => s.slice(gateway.cookie.length + 1))+ delete headers.cookie+ if (cookies.length) headers.cookie = cookies.join('; ')+ if (!this.deps.send('viewer_request', {+ streamId: id, agentId: gateway.agentId, origin: gateway.target.origin,+ path: req.url, method: req.method, headers, upgrade,+ })) queueMicrotask(() => wire.destroy(new Error('Viewer connection closed')))+ } catch { queueMicrotask(() => wire.destroy(new Error('Invalid viewer request'))) }+ return wire+ }++ private responseHeaders(gateway: Gateway, raw: unknown, upgrade = false): ReturnType<typeof viewerHeaders> {+ const headers = viewerHeaders(raw, upgrade)+ if (typeof headers.location === 'string') {+ const location = new URL(headers.location, gateway.target)+ if (location.origin === gateway.target.origin) headers.location = gateway.origin + location.pathname + location.search + location.hash+ }+ if (headers['set-cookie']) {+ const values = headers['set-cookie']+ headers['set-cookie'] = (Array.isArray(values) ? values : [values]).map((value) =>+ `${gateway.cookie}_${value.replace(/;\s*Domain=[^;]*/ig, '')}`)+ }+ headers['referrer-policy'] = 'no-referrer'+ return headers+ }++ private closeGateway(gateway: Gateway): void {+ for (const wire of gateway.wires) wire.destroy()+ for (const socket of gateway.sockets) socket.destroy()+ gateway.server.close()+ }++ private remove(agentId: string): void {+ const gateway = this.gateways.get(agentId)+ this.gateways.delete(agentId)+ if (gateway) this.closeGateway(gateway)+ }++ /** Detach closes all access immediately, even though the terminal relay pool lingers. */+ reset(): void {+ this.generation+++ for (const id of this.gateways.keys()) this.remove(id)+ }++ close(): void { this.disposed = true; this.reset() }+}++function isLoopbackUrl(raw: unknown): boolean {+ try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(String(raw)).hostname) } catch { return false }+}++function frameWithViewerError(frame: Frame): Frame {+ const p = frame.payload as Record<string, unknown> | undefined+ if (!p) return frame+ const failed = (a: unknown): unknown => a && typeof a === 'object' && isLoopbackUrl((a as Record<string, unknown>).viewerUrl)+ ? { ...a, viewerUrl: null, viewerError: 'The remote viewer could not be opened. Reconnect to try again.' } : a+ return { ...frame, payload: { ...p, ...(p.agent ? { agent: failed(p.agent) } : {}), ...(Array.isArray(p.agents) ? { agents: p.agents.map(failed) } : {}) } }+}diff --git a/cli/src/lib/remoteViewerRelay.spec.ts b/cli/src/lib/remoteViewerRelay.spec.tsnew file mode 100644index 000000000..b278fd7e7--- /dev/null+++ b/cli/src/lib/remoteViewerRelay.spec.ts@@ -0,0 +1,145 @@+import { afterEach, expect, it } from 'vitest'+import { once } from 'node:events'+import { createServer, request } from 'node:http'+import type { AddressInfo } from 'node:net'+import { WebSocket, WebSocketServer } from 'ws'+import { BackendSocket, type Frame } from '../backendSocket.js'+import { attachLocalWsServer } from '../localWsServer.js'+import { env } from '../config/env.js'+import { DshViewerManager } from '../dsh/viewer.js'+import { E2eeStore } from './e2ee/store.js'+import { b64e, fingerprint, newIdentity } from './e2ee/core.js'+import { MachinePeerStore } from './e2ee/machinePeers.js'+import { RemoteRelayPool } from './remoteRelay.js'+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import type { InstalledDsh } from '../dsh/installed.js'++const cleanup: Array<() => unknown | Promise<unknown>> = []+afterEach(async () => { for (const close of cleanup.splice(0).reverse()) await close() })++/** An opaque backend fixture: real sockets and production daemon handlers on both sides. */+it('desktop local-ws → relay → E2EE → daemon → spawned viewer, including restart and revocation', async () => {+ const machineId = 'a1234567890123456789012345678901a'+ const localIdentity = newIdentity()+ const remoteStore = new E2eeStore()+ const remoteIdentity = remoteStore.init()+ remoteStore.addPaired(b64e(localIdentity.pub), 'viewer e2e fixture', Date.now())+ const peers = new MachinePeerStore()+ peers.pin(machineId, b64e(remoteIdentity.pub), 'viewer e2e fixture')+ const relayServer = createServer()+ const relay = new WebSocketServer({ server: relayServer })+ let remote: WebSocket | undefined+ let client: WebSocket | undefined+ const encrypted: string[] = []+ relay.on('connection', (ws, req) => {+ if (req.url?.startsWith('/api/adapter-ws')) {+ remote = ws+ ws.on('message', (raw) => {+ const envelope = JSON.parse(raw.toString())+ if (envelope.t !== 'up') return+ if (String(envelope.frame.type).startsWith('viewer_')) encrypted.push(raw.toString())+ if (client?.readyState === WebSocket.OPEN) client.send(JSON.stringify(envelope.frame))+ })+ } else {+ client = ws+ ws.on('message', (raw) => {+ const frame = JSON.parse(raw.toString())+ if (frame.type === 'machine_select') { ws.send(JSON.stringify({ type: 'connected', payload: { machineId } })); return }+ if (String(frame.type).startsWith('viewer_')) encrypted.push(raw.toString())+ remote?.send(JSON.stringify({ t: 'down', connId: 'viewer-client', frame }))+ })+ ws.on('close', () => remote?.readyState === WebSocket.OPEN && remote.send(JSON.stringify({ t: 'down', connId: 'viewer-client', frame: { type: '__client_disconnected' } })))+ }+ })+ relayServer.listen(0, '127.0.0.1')+ await once(relayServer, 'listening')+ cleanup.push(() => { for (const ws of relay.clients) ws.terminate(); relay.close(); relayServer.close() })+ const base = `ws://127.0.0.1:${(relayServer.address() as AddressInfo).port}`+ const previousBase = env.BACKEND_WS_URL+ env.BACKEND_WS_URL = base+ cleanup.push(() => { env.BACKEND_WS_URL = previousBase })+ let connected!: () => void+ const online = new Promise<void>((resolve) => { connected = resolve })+ const daemon = new BackendSocket(machineId, undefined, (up) => { if (up) connected() })+ cleanup.push(() => daemon.stop())+ daemon.connect()+ await online++ const dir = mkdtempSync(join(tmpdir(), 'harness-viewer-e2e-'))+ cleanup.push(() => rmSync(dir, { recursive: true, force: true }))+ writeFileSync(join(dir, 'viewer.mjs'), `import http from 'node:http';+const server = http.createServer((req, res) => {+ if (req.url === '/events') { res.writeHead(200, {'Content-Type': 'text/event-stream'}); res.write('data: encrypted-live-output\\n\\n'); }+ else res.end('<html>encrypted-viewer-output<img src="/asset.svg"></html>');+});+server.listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1');`)+ const manager = new DshViewerManager({+ onUrl: (agentId, viewerUrl) => {+ daemon.viewerForwarder.refresh(agentId)+ daemon.send({ type: 'agent_synced', payload: { agent: { id: agentId, viewerUrl, name: 'remote viewer fixture' } } })+ },+ })+ daemon.viewerTargetProvider = (agentId) => manager.forwardingUrl(agentId)+ cleanup.push(() => manager.stopAll())+ const dsh: InstalledDsh = {+ id: 'test/viewer', realDir: dir, dir, source: '', ref: null, commit: null, linked: false, installedAt: 0,+ manifest: { spec: 1, id: 'test/viewer', name: 'Viewer test', engine: 'claude', viewer: { command: `${JSON.stringify(process.execPath)} viewer.mjs`, url: 'http://127.0.0.1:${port}/?file=${artifact}' } },+ }++ const pool = new RemoteRelayPool({ accessToken: async () => 'fixture-token' } as never, base, localIdentity, peers)+ cleanup.push(() => pool.invalidate(machineId))+ const localServer = createServer()+ const localWs = attachLocalWsServer(localServer, { machineId: 'this-computer', backend: daemon, relayPool: pool, autonomousEnv: 'prod' })+ localServer.listen(0, '127.0.0.1')+ await once(localServer, 'listening')+ cleanup.push(async () => { await localWs.close(); localServer.close() })+ const desktop = new WebSocket(`ws://127.0.0.1:${(localServer.address() as AddressInfo).port}/api/local-ws`)+ cleanup.push(() => desktop.terminate())+ const frames: Frame[] = []+ desktop.on('message', (raw) => frames.push(JSON.parse(raw.toString())))+ async function until(predicate: () => boolean): Promise<void> {+ const deadline = Date.now() + 5000+ while (!predicate()) {+ if (Date.now() > deadline) throw new Error('E2E condition did not arrive')+ await new Promise((resolve) => setTimeout(resolve, 10))+ }+ }+ await once(desktop, 'open')+ desktop.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))+ await until(() => frames.some((f) => f.type === 'connected'))+ await manager.start('agent', dsh, dir)+ const urls = () => frames.filter((f) => f.type === 'agent_synced').map((f) => (f.payload as any).agent.viewerUrl as string | null)+ await until(() => urls().some(Boolean))+ const url = urls().at(-1)!+ expect(new URL(url).origin).not.toBe(new URL(manager.url('agent')!).origin)+ const bootstrap = await fetch(url, { redirect: 'manual' })+ const cookie = bootstrap.headers.get('set-cookie')!.split(';')[0]+ const localOrigin = new URL(url).origin+ const page = await fetch(localOrigin + bootstrap.headers.get('location'), { headers: { cookie } })+ expect(await page.text()).toContain('encrypted-viewer-output')+ const live = await fetch(localOrigin + '/events', { headers: { cookie } })+ const reader = live.body!.getReader()+ expect(new TextDecoder().decode((await reader.read()).value)).toContain('encrypted-live-output')+ expect(encrypted.length).toBeGreaterThan(3)+ for (const raw of encrypted) {+ expect(raw).toContain('"__e2e"')+ expect(raw).not.toMatch(/encrypted-viewer-output|encrypted-live-output|"agentId"|"path"|"headers"|"data"/)+ }++ // Both incomplete streaming responses and the previous local origin die on a viewer restart.+ await manager.stop('agent')+ await expect(reader.read()).rejects.toThrow()+ await manager.start('agent', dsh, dir)+ await until(() => urls().at(-1) !== null && urls().at(-1) !== url)+ await expect(fetch(url)).rejects.toThrow()+ const restarted = urls().at(-1)!+ expect((await fetch(restarted, { redirect: 'manual' })).status).toBe(302)+ const ended = once(desktop, 'close')+ expect(daemon.revoke(fingerprint(localIdentity.pub)).ok).toBe(true)+ const [code] = await ended+ expect(code).toBe(4404)+ await expect(fetch(restarted)).rejects.toThrow()+ expect(peers.get(machineId)).toBeNull()+}, 20_000)diff --git a/cli/src/lib/viewerForwarder.spec.ts b/cli/src/lib/viewerForwarder.spec.tsnew file mode 100644index 000000000..a8f6be278--- /dev/null+++ b/cli/src/lib/viewerForwarder.spec.ts@@ -0,0 +1,139 @@+import { afterEach, describe, expect, it, vi } from 'vitest'+import { PassThrough } from 'node:stream'+import { ViewerForwarder } from './viewerForwarder.js'++const requestStub = vi.hoisted(() => ({ call: vi.fn() }))+vi.mock('node:http', () => ({ request: requestStub.call }))++const clean: ViewerForwarder[] = []+afterEach(() => { clean.splice(0).forEach((f) => f.closeAll()); vi.restoreAllMocks() })++function fixture() {+ const send = vi.fn(() => true)+ const target = vi.fn((_id: string) => 'http://localhost:4321/')+ const requests: PassThrough[] = []+ requestStub.call.mockReset().mockImplementation(() => {+ const req = new PassThrough()+ requests.push(req)+ return req+ })+ const forwarder = new ViewerForwarder({ send, target })+ clean.push(forwarder)+ const base = { streamId: 's', agentId: 'a', origin: 'http://localhost:4321', path: '/', method: 'GET', headers: {} }+ const open = (p: Record<string, unknown> = {}, conn = 'owner') => forwarder.handle(conn, 'viewer_request', { ...base, ...p })+ const response = (status: number | undefined = 200, headers: unknown = {}) => Object.assign(new PassThrough(), { statusCode: status, headers })+ return { send, target, requests, forwarder, base, open, response }+}++describe('viewer forwarding boundaries', () => {+ it('ignores invalid stream identifiers and rejects a request without an agent or valid destination', () => {+ const f = fixture()+ f.open({ streamId: '../other' })+ expect(f.send).not.toHaveBeenCalled()+ f.open({ agentId: 123 })+ expect(f.send).toHaveBeenCalledWith('owner', 'viewer_close', expect.anything())+ expect(requestStub.call).not.toHaveBeenCalled()+ })++ it.each([+ { path: 42 }, { path: '/'.repeat(17000) }, { path: 'relative' }, { path: '//other' },+ { path: '/back\\slash' }, { path: '/new\nline' }, { method: 2 }, { method: 'CONNECT' },+ { upgrade: true, method: 'POST' }, { headers: { invalid: ['\r\n'] } },+ ])('rejects malformed requests %j before connecting', (input) => {+ const f = fixture()+ f.open(input)+ expect(requestStub.call).not.toHaveBeenCalled()+ expect(f.send).toHaveBeenCalledWith('owner', 'viewer_close', expect.anything())+ })++ it('never replaces a live stream id, and caps per-client and daemon-wide streams', () => {+ const f = fixture()+ f.open()+ f.open()+ expect(requestStub.call).toHaveBeenCalledTimes(1)+ f.forwarder.closeAll()+ const bounded = fixture()+ for (let c = 0; c < 4; c++) {+ for (let i = 0; i < 64; i++) bounded.open({ streamId: `s${i}` }, `client${c}`)+ bounded.open({ streamId: 'overflow' }, `client${c}`)+ }+ bounded.open({ streamId: 'overflow' }, 'client4')+ expect(requestStub.call).toHaveBeenCalledTimes(256)+ expect(bounded.send).toHaveBeenCalledTimes(5)+ })++ it('pins IPv6 loopback and closes only the matching connection or a changed viewer origin', () => {+ const f = fixture()+ f.target.mockReturnValue('http://[::1]:4321/')+ f.open({ origin: 'http://[::1]:4321' })+ expect(requestStub.call).toHaveBeenCalledWith(expect.objectContaining({ hostname: '::1', port: '4321' }))+ f.open({ streamId: 'other', agentId: 'b', origin: 'http://[::1]:4321' }, 'other-owner')+ f.forwarder.refresh('a')+ expect(f.requests[0].destroyed).toBe(false)+ f.target.mockReturnValue('http://[::1]:4322/')+ f.forwarder.refresh('a')+ expect(f.send).toHaveBeenCalledWith('owner', 'viewer_close', expect.anything())+ expect(f.send).not.toHaveBeenCalledWith('other-owner', 'viewer_close', expect.anything())+ f.forwarder.closeConnection('other-owner')+ expect(f.send).toHaveBeenCalledWith('other-owner', 'viewer_close', expect.anything())+ })+})++describe('upstream HTTP and WebSocket failures', () => {+ it('contains synchronous connection failures and malformed response headers', () => {+ const f = fixture()+ requestStub.call.mockImplementationOnce(() => { throw new Error('connect failed') })+ f.open()+ f.open({ streamId: 'bad-header' })+ f.requests[0].emit('response', f.response(200, { bad: '\n' }))+ expect(f.send.mock.calls.filter((args: unknown[]) => args[1] === 'viewer_close')).toHaveLength(2)+ })++ it('fails closed on a dead relay, missing status, interrupted response and upstream error', () => {+ const f = fixture()+ f.open()+ f.send.mockReturnValue(false)+ f.requests[0].emit('response', f.response(200))+ f.send.mockReturnValue(true)+ f.open({ streamId: 'nostatus' })+ const response = Object.assign(new PassThrough(), { statusCode: undefined, headers: {} })+ f.requests[1].emit('response', response)+ expect(f.send).toHaveBeenCalledWith('owner', 'viewer_response', expect.objectContaining({ status: 502 }))+ response.emit('error', new Error('interrupted'))+ f.open({ streamId: 'request-error' })+ f.requests[2].emit('error', new Error('connect failed'))+ })++ it('handles declined and unsolicited upgrades, including malformed upgrade headers', () => {+ const f = fixture()+ f.open({ upgrade: true })+ f.requests[0].emit('response', f.response(403))+ f.open({ streamId: 'normal' })+ const normalSocket = new PassThrough()+ f.requests[1].emit('upgrade', f.response(101), normalSocket, Buffer.alloc(0))+ expect(normalSocket.destroyed).toBe(true)+ f.open({ streamId: 'badstatus', upgrade: true })+ const badSocket = new PassThrough()+ f.requests[2].emit('upgrade', f.response(200), badSocket, Buffer.alloc(0))+ expect(badSocket.destroyed).toBe(true)+ f.open({ streamId: 'badheaders', upgrade: true })+ const headerSocket = new PassThrough()+ f.requests[3].emit('upgrade', f.response(101, { bad: '\n' }), headerSocket, Buffer.alloc(0))+ expect(headerSocket.destroyed).toBe(true)+ })++ it('forwards upgrade head bytes and closes both sides on socket error, close or client cancellation', async () => {+ const f = fixture()+ for (let i = 0; i < 3; i++) {+ f.open({ streamId: `ws${i}`, upgrade: true })+ const socket = new PassThrough()+ f.requests[i].emit('upgrade', f.response(101), socket, i ? Buffer.alloc(0) : Buffer.from('head'))+ if (i === 0) socket.emit('error', new Error('socket failed'))+ else if (i === 1) socket.emit('close')+ else f.forwarder.handle('owner', 'viewer_close', { streamId: 'ws2' })+ await new Promise((resolve) => setImmediate(resolve))+ expect(socket.destroyed).toBe(true)+ }+ expect(f.send).toHaveBeenCalledWith('owner', 'viewer_data', expect.objectContaining({ data: Buffer.from('head').toString('base64') }))+ })+})diff --git a/cli/src/lib/viewerForwarder.ts b/cli/src/lib/viewerForwarder.tsnew file mode 100644index 000000000..d118f7b01--- /dev/null+++ b/cli/src/lib/viewerForwarder.ts@@ -0,0 +1,101 @@+import { request } from 'node:http'+import { VIEWER_MAX_STREAMS, ViewerWire, viewerHeaders, viewerStreamId, viewerTarget, type ViewerSend } from './viewerWire.js'++interface Forward {+ connId: string+ agentId: string+ origin: string+ wire: ViewerWire+}++/** Runs on the harness's machine. A request names an agent, never a destination host or port. */+export class ViewerForwarder {+ private readonly streams = new Map<string, Forward>()++ constructor(private readonly deps: {+ target: (agentId: string) => string | null+ send: (connId: string, type: string, payload: Record<string, unknown>) => boolean+ }) {}++ handle(connId: string, type: string, payload: Record<string, unknown>): void {+ const id = payload.streamId+ if (!viewerStreamId(id)) return+ const key = `${connId}/${id}`+ if (type !== 'viewer_request') {+ this.streams.get(key)?.wire.handle(type, payload)+ return+ }+ // Reusing a live id never replaces its request or changes its agent.+ if (this.streams.has(key)) { this.streams.get(key)!.wire.destroy(new Error('Duplicate viewer stream')); return }+ const send: ViewerSend = (t, p) => this.deps.send(connId, t, p)+ const refuse = (error: string): void => { send('viewer_close', { streamId: id, error }) }+ const agentId = payload.agentId+ const target = typeof agentId === 'string' ? viewerTarget(this.deps.target(agentId)) : null+ if (!target || target.origin !== payload.origin) { refuse('Viewer is no longer available'); return }+ if (this.streams.size >= VIEWER_MAX_STREAMS * 4+ || [...this.streams.values()].filter((s) => s.connId === connId).length >= VIEWER_MAX_STREAMS) {+ refuse('Too many viewer requests'); return+ }+ const path = payload.path+ const method = payload.method+ const upgrade = payload.upgrade === true+ if (typeof path !== 'string' || path.length > 16 * 1024 || !path.startsWith('/') || path.startsWith('//')+ || /[\s\x00-\x1f\x7f\\]/.test(path) || typeof method !== 'string'+ || !['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'].includes(method)+ || (upgrade && method !== 'GET')) {+ refuse('Invalid viewer request'); return+ }+ let headers: ReturnType<typeof viewerHeaders>+ try { headers = viewerHeaders(payload.headers, upgrade) } catch { refuse('Invalid viewer headers'); return }+ headers.host = target.host+ const wire = new ViewerWire(id, send)+ this.streams.set(key, { connId, agentId: agentId as string, origin: target.origin, wire })+ try {+ const upstream = request({+ // The viewer manager checks its allocated port; pin localhost to the loopback literal.+ hostname: target.hostname === '[::1]' ? '::1' : '127.0.0.1',+ port: target.port, path, method, headers, agent: false,+ })+ const reply = (status: number, rawHeaders: unknown, switched = false): void => {+ wire.ready()+ if (!send('viewer_response', { streamId: id, status, headers: viewerHeaders(rawHeaders, switched), upgrade: switched })) wire.destroy()+ }+ upstream.on('response', (response) => {+ try { reply(response.statusCode ?? 502, response.headers) } catch { wire.destroy(); return }+ response.on('error', () => wire.destroy(new Error('Viewer response interrupted')))+ if (upgrade) wire.resume() // An unsuccessful upgrade has no request body to consume.+ response.pipe(wire)+ })+ upstream.on('upgrade', (response, socket, head) => {+ if (!upgrade || response.statusCode !== 101) { socket.destroy(); wire.destroy(); return }+ try { reply(101, response.headers, true) } catch { socket.destroy(); wire.destroy(); return }+ socket.on('error', () => wire.destroy(new Error('Viewer WebSocket interrupted')))+ socket.on('close', () => wire.destroy())+ wire.on('close', () => socket.destroy())+ if (head.length) wire.write(head)+ socket.pipe(wire).pipe(socket)+ })+ upstream.on('error', () => wire.destroy(new Error('Viewer did not answer')))+ wire.on('close', () => { this.streams.delete(key); upstream.destroy() })+ if (upgrade) upstream.end()+ else wire.pipe(upstream)+ } catch {+ this.streams.delete(key)+ wire.destroy(new Error('Invalid viewer request'))+ }+ }++ /** Called on port changes/stop, before another process can reuse the old viewer port. */+ refresh(agentId: string): void {+ const origin = viewerTarget(this.deps.target(agentId))?.origin+ for (const stream of this.streams.values()) {+ if (stream.agentId === agentId && stream.origin !== origin) stream.wire.destroy()+ }+ }++ closeConnection(connId: string): void {+ for (const stream of this.streams.values()) if (stream.connId === connId) stream.wire.destroy()+ }++ closeAll(): void { for (const stream of this.streams.values()) stream.wire.destroy() }+}diff --git a/cli/src/lib/viewerWire.spec.ts b/cli/src/lib/viewerWire.spec.tsnew file mode 100644index 000000000..b02ac8bbe--- /dev/null+++ b/cli/src/lib/viewerWire.spec.ts@@ -0,0 +1,91 @@+import { afterEach, describe, expect, it, vi } from 'vitest'+import { ViewerWire, VIEWER_CHUNK_BYTES, VIEWER_WINDOW_BYTES, viewerHeaders, viewerStreamId, viewerTarget } from './viewerWire.js'++afterEach(() => vi.useRealTimers())++describe('viewer protocol validation', () => {+ it.each([undefined, '', 'not a url', 'http://[', 'http://127.0.0.1:123/a b', 'x'.repeat(8193),+ 'https://127.0.0.1:123/', 'http://example.com:123/', 'http://user:password@localhost:123/', 'http://localhost/'])('rejects destination %s', (url) => {+ expect(viewerTarget(url)).toBeNull()+ })+ it.each(['http://127.0.0.1:123/', 'http://localhost:123/?file=a', 'http://[::1]:123/'])('accepts an explicit HTTP loopback port %s', (url) => {+ expect(viewerTarget(url)?.href).toBe(url)+ })+ it('requires a bounded stream id and bounded valid headers', () => {+ for (const id of [null, 1, '', 'a/b', 'a'.repeat(65)]) expect(viewerStreamId(id)).toBe(false)+ expect(viewerStreamId('valid-id')).toBe(true)+ for (const headers of [null, [], 'header', { 'Bad:Key': 'value' }, { valid: [1] }, { valid: 'bad\r\nvalue' }, { valid: 'x'.repeat(32769) }]) {+ expect(() => viewerHeaders(headers)).toThrow()+ }+ expect(viewerHeaders({ connection: 'x-private, keep-alive', 'x-private': 'hidden', 'set-cookie': ['a=b', 'c=d'] }))+ .toEqual({ 'set-cookie': ['a=b', 'c=d'] })+ })+})++describe('viewer stream lifecycle and failure handling', () => {+ it('expires unopened connections and stalled transfers, while idle live streams stay open', async () => {+ vi.useFakeTimers()+ const unopened = new ViewerWire('a', () => true)+ await vi.advanceTimersByTimeAsync(30001)+ expect(unopened.destroyed).toBe(true)+ const active = new ViewerWire('b', () => true)+ active.ready()+ await vi.advanceTimersByTimeAsync(60000)+ expect(active.destroyed).toBe(false)+ active.write(Buffer.from('data'))+ await vi.advanceTimersByTimeAsync(30001)+ expect(active.destroyed).toBe(true)+ })++ it('handles failed sends, cancellation with queued writes and data arriving after close', () => {+ const failed = new ViewerWire('a', () => false)+ failed.write(Buffer.from('data'), () => {})+ expect(failed.destroyed).toBe(true)+ failed.handle('viewer_data', { data: 'not read' })+ expect((failed as any).emitWire('viewer_ack')).toBe(false)+ const cancelled = new ViewerWire('b', () => true)+ cancelled.write(Buffer.alloc(VIEWER_WINDOW_BYTES * 2), () => {})+ cancelled.destroy()+ const done = new ViewerWire('c', () => true)+ done.destroy(new Error('cancelled'))+ expect(done.destroyed).toBe(true)+ })++ it.each([+ { data: 1 }, { data: 'a'.repeat(50000) }, { data: '?' }, { data: 'YQ' }, { data: '' },+ ])('refuses malformed data %j', (payload) => {+ const stream = new ViewerWire('a', () => true)+ stream.handle('viewer_data', payload)+ expect(stream.destroyed).toBe(true)+ })++ it('does not accept data after end, repeat end, zero credit or oversized credit', () => {+ const stream = new ViewerWire('a', () => true)+ stream.handle('viewer_end', {})+ stream.handle('viewer_end', {})+ stream.handle('viewer_data', { data: 'YQ==' })+ expect(stream.destroyed).toBe(true)+ for (const bytes of [0, 1, '1', -1, 1.5]) {+ const stream = new ViewerWire('b', () => true)+ stream.handle('viewer_ack', { bytes })+ expect(stream.destroyed).toBe(true)+ }+ })++ it('accepts partial credit, resumes a held read and handles peer cancellation without echoing it', async () => {+ const send = vi.fn((_type: string, _payload: Record<string, unknown>) => true)+ const stream = new ViewerWire('a', send)+ stream.handle('unknown_viewer_frame', {})+ stream.write(Buffer.alloc(10))+ stream.handle('viewer_ack', { bytes: 5 })+ stream.handle('viewer_ack', { bytes: 5 })+ stream.handle('viewer_data', { data: Buffer.alloc(VIEWER_CHUNK_BYTES).toString('base64') })+ stream.resume()+ await new Promise((resolve) => setImmediate(resolve))+ expect(send).toHaveBeenCalledWith('viewer_ack', expect.objectContaining({ bytes: VIEWER_CHUNK_BYTES }))+ stream.handle('viewer_close', {})+ expect(send.mock.calls.some(([type]) => type === 'viewer_close')).toBe(false)+ const second = new ViewerWire('b', () => true)+ second.handle('viewer_close', { error: 'remote stopped' })+ })+})diff --git a/cli/src/lib/viewerWire.ts b/cli/src/lib/viewerWire.tsnew file mode 100644index 000000000..e7f97d5a0--- /dev/null+++ b/cli/src/lib/viewerWire.ts@@ -0,0 +1,168 @@+import { Duplex } from 'node:stream'++/** Pairwise encrypted JSON frames; no payload may be logged or broadcast. */+export const VIEWER_DOWN_TYPES = new Set(['viewer_request', 'viewer_data', 'viewer_ack', 'viewer_end', 'viewer_close'])+export const VIEWER_UP_TYPES = new Set(['viewer_response', 'viewer_data', 'viewer_ack', 'viewer_end', 'viewer_close'])+export const VIEWER_CHUNK_BYTES = 32 * 1024+export const VIEWER_WINDOW_BYTES = 128 * 1024+export const VIEWER_MAX_STREAMS = 64+export const VIEWER_TIMEOUT_MS = 30_000+export type ViewerSend = (type: string, payload: Record<string, unknown>) => boolean++/** Only the daemon's managed HTTP loopback viewers can be forwarded. Never resolve a hostname. */+export function viewerTarget(raw: unknown): URL | null {+ if (typeof raw !== 'string' || raw.length > 8192 || /[\s\x00-\x1f\x7f]/.test(raw)) return null+ try {+ const url = new URL(raw)+ return url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)+ && !url.username && !url.password && Number(url.port) > 0 ? url : null+ } catch { return null }+}++export function viewerStreamId(value: unknown): value is string {+ return typeof value === 'string' && /^[a-zA-Z0-9-]{1,64}$/.test(value)+}++/**+ * A half-closeable, bounded byte stream over ordered frames. Credit is returned only while the+ * consumer is draining. This keeps a video or a stalled WebSocket from buffering an entire file+ * in either daemon, and leaves room on the shared relay for terminal input.+ */+export class ViewerWire extends Duplex {+ private credit = VIEWER_WINDOW_BYTES+ private receiveCredit = VIEWER_WINDOW_BYTES+ private heldAck = 0+ private incomingEnded = false+ private peerClosed = false+ private pending: { bytes: Buffer; offset: number; done: (error?: Error | null) => void } | null = null+ private deadline: NodeJS.Timeout++ constructor(readonly id: string, private readonly send: ViewerSend) {+ super({ allowHalfOpen: true, highWaterMark: VIEWER_CHUNK_BYTES })+ // Owners attach their own error handlers too. A late cancellation must never crash the daemon.+ this.on('error', () => {})+ this.deadline = setTimeout(() => this.destroy(new Error('Viewer connection timed out')), VIEWER_TIMEOUT_MS)+ this.deadline.unref()+ }++ /** The HTTP headers arrived. An idle SSE/WebSocket is valid; stalled writes still have a deadline. */+ ready(): void { clearTimeout(this.deadline) }++ private armDeadline(): void {+ clearTimeout(this.deadline)+ this.deadline = setTimeout(() => this.destroy(new Error('Viewer transfer stalled')), VIEWER_TIMEOUT_MS)+ this.deadline.unref()+ }++ private emitWire(type: string, payload: Record<string, unknown> = {}): boolean {+ if (this.destroyed) return false+ if (this.send(type, { streamId: this.id, ...payload })) return true+ this.destroy(new Error('Viewer connection closed'))+ return false+ }++ override _read(): void {+ if (!this.heldAck) return+ const bytes = this.heldAck+ this.heldAck = 0+ this.receiveCredit += bytes+ this.emitWire('viewer_ack', { bytes })+ }++ override _write(bytes: Buffer, _encoding: BufferEncoding, done: (error?: Error | null) => void): void {+ this.pending = { bytes, offset: 0, done }+ this.flushPending()+ }++ private flushPending(): void {+ const pending = this.pending+ if (!pending || this.destroyed) return+ while (pending.offset < pending.bytes.length && this.credit > 0) {+ const length = Math.min(VIEWER_CHUNK_BYTES, this.credit, pending.bytes.length - pending.offset)+ const data = pending.bytes.subarray(pending.offset, pending.offset + length).toString('base64')+ this.credit -= length+ pending.offset += length+ this.armDeadline()+ if (!this.emitWire('viewer_data', { data })) return+ }+ if (pending.offset === pending.bytes.length) {+ this.pending = null+ pending.done()+ }+ }++ override _final(done: (error?: Error | null) => void): void {+ this.emitWire('viewer_end')+ done()+ }++ handle(type: string, payload: Record<string, unknown>): void {+ if (this.destroyed) return+ if (type === 'viewer_close') {+ this.peerClosed = true+ this.destroy(new Error(typeof payload.error === 'string' ? payload.error.slice(0, 160) : 'Viewer connection closed'))+ } else if (type === 'viewer_end') {+ if (this.incomingEnded) return+ this.incomingEnded = true+ this.push(null)+ } else if (type === 'viewer_ack') {+ const bytes = payload.bytes+ if (!Number.isSafeInteger(bytes) || Number(bytes) <= 0 || Number(bytes) > VIEWER_WINDOW_BYTES - this.credit) {+ this.destroy(new Error('Invalid viewer credit'))+ return+ }+ this.credit += Number(bytes)+ if (this.credit === VIEWER_WINDOW_BYTES) clearTimeout(this.deadline)+ else this.armDeadline()+ this.flushPending()+ } else if (type === 'viewer_data') {+ const data = payload.data+ if (this.incomingEnded || typeof data !== 'string' || data.length > Math.ceil(VIEWER_CHUNK_BYTES / 3) * 4) {+ this.destroy(new Error('Invalid viewer data'))+ return+ }+ const bytes = Buffer.from(data, 'base64')+ if (!bytes.length || bytes.length > this.receiveCredit || bytes.toString('base64') !== data) {+ this.destroy(new Error('Invalid viewer data'))+ return+ }+ this.receiveCredit -= bytes.length+ if (this.push(bytes)) {+ this.receiveCredit += bytes.length+ this.emitWire('viewer_ack', { bytes: bytes.length })+ } else {+ this.heldAck += bytes.length+ }+ }+ }++ override _destroy(error: Error | null, done: (error?: Error | null) => void): void {+ clearTimeout(this.deadline)+ if (!this.peerClosed && (error || !this.readableEnded || !this.writableFinished)) {+ this.send('viewer_close', { streamId: this.id, error: 'Viewer connection closed' })+ }+ const pending = this.pending+ this.pending = null+ pending?.done(error ?? new Error('Viewer connection closed'))+ done(error)+ }+}++/** Hop-by-hop headers belong to each HTTP connection, not the encrypted hop between them. */+export function viewerHeaders(raw: unknown, upgrade = false): Record<string, string | string[]> {+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Invalid viewer headers')+ const headers: Record<string, string | string[]> = Object.create(null)+ let size = 0+ for (const [key, value] of Object.entries(raw)) {+ if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(key)) throw new Error('Invalid viewer header')+ const values = Array.isArray(value) ? value : [value]+ if (!values.every((v) => typeof v === 'string' && !/[\r\n\x00]/.test(v))) throw new Error('Invalid viewer header')+ size += key.length + values.join('').length+ if (size > 32 * 1024) throw new Error('Viewer headers too large')+ headers[key] = value as string | string[]+ }+ const connection = String(headers.connection ?? '').toLowerCase().split(',').map((s) => s.trim())+ for (const name of [...connection, 'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']) delete headers[name]+ if (upgrade) { headers.connection = 'Upgrade'; headers.upgrade = 'websocket' }+ return headers+}diff --git a/desktop/lib/core/models.dart b/desktop/lib/core/models.dartindex 14faac712..64a1f9a54 100644--- a/desktop/lib/core/models.dart+++ b/desktop/lib/core/models.dart@@ -195,6 +195,9 @@ class Agent {/// when there is none (yet). A change means the viewer pane must navigate.final String? viewerUrl;+ /// Why this remote viewer could not be forwarded, including old-daemon update guidance.+ final String? viewerError;+/// What the harness's viewer pane is called — the shared viewer's own name ("3D Viewer"), or/// the harness's name and "Viewer" for one it ships ("Marp Viewer") — as the daemon worked it/// out. Null from an older daemon or with no viewer; see [PaneGrid] for what stands in.@@ -225,6 +228,7 @@ class Agent {this.dsh,this.dshName,this.viewerUrl,+ this.viewerError,this.viewerName,this.verdict,});@@ -287,6 +291,7 @@ class Agent {dsh: _safeDsh(j['dsh']),dshName: _safeLabel(j['dshName']),viewerUrl: _safeViewerUrl(j['viewerUrl']),+ viewerError: _safeDetail(j['viewerError']),viewerName: _safeLabel(j['viewerName']),verdict: AgentVerdict.fromJson(j['verdict']),);@@ -314,6 +319,7 @@ class Agent {dsh: dsh,dshName: dshName,viewerUrl: viewerUrl,+ viewerError: viewerError,viewerName: viewerName,verdict: verdict,);diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dartindex 351114ecb..e79bb3939 100644--- a/desktop/lib/state/app_state.dart+++ b/desktop/lib/state/app_state.dart@@ -3129,6 +3129,7 @@ class AppNotifier extends ChangeNotifier {prev.dsh != agent.dsh ||prev.dshName != agent.dshName ||prev.viewerUrl != agent.viewerUrl ||+ prev.viewerError != agent.viewerError ||prev.viewerName != agent.viewerName ||prev.verdict != agent.verdict) {return false;@@ -4268,9 +4269,10 @@ class AppNotifier extends ChangeNotifier {void _syncViewerPane(MachineState machine, Agent agent) {final machineId = machine.machine.machineId;final url = agent.viewerUrl;+ final viewerState = url ?? agent.viewerError;final dismissed =- url != null &&- _dismissedViewers[_viewerKey(machineId, agent.id)] == url;+ viewerState != null &&+ _dismissedViewers[_viewerKey(machineId, agent.id)] == viewerState;var changed = false;// Tab by tab: wherever this agent's terminal is, its viewer is beside it,// and nowhere else. A terminal opened in a second tab gets a second@@ -4289,7 +4291,7 @@ class AppNotifier extends ChangeNotifier {pane.ownerAgentId == agent.id)pane,];- if (url == null || at < 0) {+ if (viewerState == null || at < 0) {for (final pane in viewers) {swarm.remove(pane);changed = true;@@ -4301,6 +4303,7 @@ class AppNotifier extends ChangeNotifier {// place rather than reopening a tile.for (final pane in viewers) {pane.url = url;+ pane.viewerError = agent.viewerError;}continue;}@@ -4313,6 +4316,7 @@ class AppNotifier extends ChangeNotifier {machineId: machineId,kind: PaneKind.web,url: url,+ viewerError: agent.viewerError,ownerAgentId: agent.id,);swarm.panes.insert(insertion, pane);@@ -4362,7 +4366,10 @@ class AppNotifier extends ChangeNotifier {}final machine = machineStates[machineId];final agent = machine?.agents.where((a) => a.id == agentId).firstOrNull;- if (machine == null || agent == null || agent.viewerUrl == null) return;+ if (machine == null ||+ agent == null ||+ (agent.viewerUrl == null && agent.viewerError == null))+ return;_dismissedViewers.remove(_viewerKey(machineId, agentId));_syncViewerPane(machine, agent);notifyListeners();@@ -5978,8 +5985,9 @@ class AppNotifier extends ChangeNotifier {// frame carries the same URL and must not reopen it. A different URL —// a new artifact, a restarted viewer — is news, and opens again.final owner = pane.ownerAgentId;- if (owner != null && pane.url != null) {- _dismissedViewers[_viewerKey(pane.machineId, owner)] = pane.url!;+ final viewerState = pane.url ?? pane.viewerError;+ if (owner != null && viewerState != null) {+ _dismissedViewers[_viewerKey(pane.machineId, owner)] = viewerState;}}if (pane.agentId != null) {diff --git a/desktop/lib/state/terminal_pane.dart b/desktop/lib/state/terminal_pane.dartindex 54e37a404..1b0d75aad 100644--- a/desktop/lib/state/terminal_pane.dart+++ b/desktop/lib/state/terminal_pane.dart@@ -28,6 +28,7 @@ class TerminalPane {this.agentId,this.kind = PaneKind.terminal,this.url,+ this.viewerError,this.ownerAgentId,}) : assert(kind == PaneKind.terminal || (agentId == null && ownerAgentId != null),@@ -40,6 +41,7 @@ class TerminalPane {/// [PaneKind.web] only: what the tile loads. Changes when the agent's frame/// names a new viewer URL; the panel navigates rather than remounts.String? url;+ String? viewerError;/// [PaneKind.web] only: the agent whose viewer this is. Kept OFF [agentId]/// on purpose — everything that attaches a terminal, persists a layout ordiff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dartindex 021f43c7e..0c24b450d 100644--- a/desktop/lib/widgets/terminal_panel.dart+++ b/desktop/lib/widgets/terminal_panel.dart@@ -1731,7 +1731,8 @@ class _TerminalHeader extends StatelessWidget {composerVisible: composerVisible,// A harness agent's viewer, shown or hidden from the// pane it belongs to.- onToggleViewer: agent?.viewerUrl == null+ onToggleViewer:+ agent?.viewerUrl == null && agent?.viewerError == null? null: () => notifier.toggleViewerPane(session.machineId,diff --git a/desktop/lib/widgets/web_pane_panel.dart b/desktop/lib/widgets/web_pane_panel.dartindex 864c6fc6f..67662fc6a 100644--- a/desktop/lib/widgets/web_pane_panel.dart+++ b/desktop/lib/widgets/web_pane_panel.dart@@ -269,6 +269,14 @@ class _WebPanePanelState extends State<WebPanePanel> {}Widget _body(BuildContext context) {+ if (widget.pane.viewerError case final error?) {+ return _Notice(+ key: const ValueKey('web-pane-error'),+ icon: LucideIcons.unplug,+ title: 'Viewer unavailable',+ detail: error,+ );+ }final controller = _controller;final url = widget.pane.url;if (controller == null) {diff --git a/desktop/test/web_pane_test.dart b/desktop/test/web_pane_test.dartindex 752041ed4..40defec0c 100644--- a/desktop/test/web_pane_test.dart+++ b/desktop/test/web_pane_test.dart@@ -17,6 +17,7 @@ import 'swarm_state_test.dart' show createApp;Map<String, dynamic> _frame(String id, {String? viewerUrl,+ String? viewerError,String? viewerName,Map<String, dynamic>? verdict,}) => {@@ -26,6 +27,7 @@ Map<String, dynamic> _frame('dsh': 'autonomous/autonomous-circuit','dshName': 'Autonomous Circuit','viewerUrl': ?viewerUrl,+ 'viewerError': ?viewerError,'viewerName': ?viewerName,'verdict': ?verdict,'terminal': {@@ -40,6 +42,7 @@ Future<void> _synced(AppNotifier app,String id, {String? viewerUrl,+ String? viewerError,String? viewerName,Map<String, dynamic>? verdict,}) => app.handleEventForTest('m', {@@ -48,6 +51,7 @@ Future<void> _synced('agent': _frame(id,viewerUrl: viewerUrl,+ viewerError: viewerError,viewerName: viewerName,verdict: verdict,),@@ -58,6 +62,37 @@ List<TerminalPane> _viewers(AppNotifier app) =>app.panes.where((pane) => pane.isWeb).toList();void main() {+ testWidgets(+ 'remote viewer update guidance can be dismissed and recovers to a forwarded URL',+ (tester) async {+ final app = createApp();+ addTearDown(app.dispose);+ app.stateOf('m')!.nodeOnline = true;+ app.adoptSessionForTest(terminal('a0', <TerminalBinaryFrame>[]));+ await mount(tester, app);+ const error = 'Update Harness on the remote machine to show its viewer.';+ await _synced(app, 'a0', viewerError: error);+ await tester.pump();+ expect(find.text(error), findsOneWidget);+ expect(_viewers(app).single.url, isNull);+ await app.closePane(_viewers(app).single.id);+ await _synced(app, 'a0', viewerError: error);+ expect(_viewers(app), isEmpty);+ await app.toggleViewerPane('m', 'a0');+ expect(_viewers(app).single.viewerError, error);+ await _synced(+ app,+ 'a0',+ viewerUrl: 'http://127.0.0.1:4180/__harness_viewer/token?path=%2F',+ );+ await tester.pump();+ expect(find.text(error), findsNothing);+ expect(_viewers(app).single.viewerError, isNull);+ await tester.pump(const Duration(milliseconds: 300));+ expect(tester.takeException(), isNull);+ },+ );+test('a viewer opens to the left of its agent and follows the URL', () async {final app = createApp();addTearDown(app.dispose);