Skip to content

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

Forward remote harness viewers over paired encrypted connections

Dee4fc3909e3f82
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 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.ts
index 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.ts
index 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) return
diff --git a/cli/src/lib/e2ee/core.ts b/cli/src/lib/e2ee/core.ts
index 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 must
diff --git a/cli/src/lib/e2ee/manager.ts b/cli/src/lib/e2ee/manager.ts
index 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) => boolean
onIdentityPaired?: (connId: string, identityPub: string) => void
onIdentityRevoked?: (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) return
const 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.ts
index 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 = null
private epoch = ''
private p2pVersion = 0
+ private viewerVersion = 0
private groupRecv = new Map<string, number>() // epoch -> highest counter seen
constructor(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 false
this.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 : 0
return true
}
diff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.ts
index 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_000
const LINGER_MS = 30_000
@@ -88,6 +91,7 @@ function binaryBytes(raw: RawData): Uint8Array {
}
interface Entry {
+ viewers?: RemoteViewerProxy
ws: WebSocket
crypto: RelaySessionCrypto
sink: LocalClientSink | null
@@ -188,6 +192,7 @@ export class RemoteRelayPool {
const entry = this.entries.get(machineId)
if (!entry) return
this.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')) return
const plain = crypto.unwrapIncoming(frame)
if (!plain) return
const 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)) return
entry.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 = null
entry.onClosed = null
entry.lingerTimer = setTimeout(() => {
diff --git a/cli/src/lib/remoteViewerProxy.faults.spec.ts b/cli/src/lib/remoteViewerProxy.faults.spec.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.dart
index 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.dart
index 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.dart
index 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 or
diff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dart
index 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.dart
index 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.dart
index 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);