The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import type { Socket } from 'node:net'
import http from 'node:http'
import net, { type AddressInfo } from 'node:net'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { WebSocket } from 'ws'
import type { Frame, LocalClientSink } from './backendSocket.js'
import { attachLocalWsServer, LOCAL_WS_CLOSE_GRACE_MS, type LocalWsBackend, type LocalWsServer, type LocalWsServerOptions } from './localWsServer.js'
import { encodeTerminalLocal, TerminalBinaryKind, type TerminalBinaryClear } from './lib/terminalBinary.js'
import { listenLocalSocket } from './lib/localSocket.js'
import { RelayConnectError } from './lib/relayFrames.js'
import { mkdtempSync, rmSync } from 'node:fs'
import { randomBytes } from 'node:crypto'
import { join } from 'node:path'
import { newPipeNonce, newPipePath, PIPE_AUTH_HEADER, pipeAuthValue, pipeProven } from './lib/windows/pipeAuth.js'
import { WindowForm } from './cable/windowForm.js'
const machineId = 'machine-123'
const streamId = '00112233-4455-6677-8899-aabbccddeeff'
class FakeBackend implements LocalWsBackend {
sink: LocalClientSink | null = null
connId: string | null = null
frames: Frame[] = []
binaries: TerminalBinaryClear[] = []
unregisters: string[] = []
focuses: Array<[string, string | null]> = []
tools: string[] = []
surfaces: Array<string | undefined> = []
registerLocalClient(connId: string, sink: LocalClientSink, opts: { tool?: boolean; surface?: 'tui' } = {}): boolean {
this.connId = connId
this.sink = sink
if (opts.tool) this.tools.push(connId)
this.surfaces.push(opts.surface)
return true
}
async unregisterLocalClient(connId: string): Promise<void> {
this.unregisters.push(connId)
}
handleLocalFrame(_connId: string, frame: Frame): void {
this.frames.push(frame)
}
async handleLocalBinary(_connId: string, frame: TerminalBinaryClear): Promise<void> {
this.binaries.push(frame)
}
visibles: Array<[string, readonly string[] | undefined]> = []
setLocalTerminalFocus(connId: string, agentId: string | null, visibleAgents?: readonly string[]): void {
this.focuses.push([connId, agentId])
this.visibles.push([connId, visibleAgents])
}
observed: Array<[string, unknown]> = []
observeProduct(connId: string, payload: unknown): void {
this.observed.push([connId, payload])
}
}
function onceOpen(ws: WebSocket): Promise<void> {
return new Promise((resolve, reject) => {
ws.once('open', () => resolve())
ws.once('error', reject)
})
}
function onceMessage(ws: WebSocket): Promise<Frame> {
return new Promise((resolve, reject) => {
ws.once('message', (raw) => {
try { resolve(JSON.parse(raw.toString()) as Frame) } catch (error) { reject(error) }
})
ws.once('error', reject)
})
}
function gate(): { promise: Promise<void>; resolve: () => void } {
let resolve!: () => void
const promise = new Promise<void>((done) => { resolve = done })
return { promise, resolve }
}
describe('local CLI WebSocket', () => {
let server: http.Server | null = null
let local: LocalWsServer | null = null
afterEach(async () => {
await local?.close()
await new Promise<void>((resolve) => server?.close(() => resolve()) ?? resolve())
local = null
server = null
})
async function start(backend: FakeBackend, extra: Partial<LocalWsServerOptions> = {}): Promise<string> {
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, { machineId, backend, ...extra })
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const port = (server.address() as AddressInfo).port
return `ws://127.0.0.1:${port}/api/local-ws`
}
it('closes within a moment, however long a client takes to answer the close', async () => {
// A client that never answers the close frame: a raw socket past the handshake that reads nothing.
const url = new URL(await start(new FakeBackend()))
const raw = net.connect(Number(url.port), '127.0.0.1')
await new Promise<void>((resolve) => raw.once('connect', () => resolve()))
raw.write(['GET /api/local-ws HTTP/1.1', `Host: 127.0.0.1:${url.port}`, 'Upgrade: websocket', 'Connection: Upgrade',
'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==', 'Sec-WebSocket-Version: 13', '', ''].join('\r\n'))
await new Promise<void>((resolve) => raw.once('data', () => resolve()))
raw.pause()
const started = performance.now()
await local!.close()
local = null
// ws alone waits 30 s for it.
expect(performance.now() - started).toBeLessThan(LOCAL_WS_CLOSE_GRACE_MS + 2_000)
raw.destroy()
})
it('registers `harness tui` as its own surface, and every other window as the desktop app', async () => {
for (const [client, surface] of [['tui', 'tui'], [undefined, undefined], ['desktop', undefined]] as const) {
const backend = new FakeBackend()
const ws = new WebSocket(await start(backend))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1, ...(client ? { client } : {}) } }))
await connected
expect(backend.surfaces).toEqual([surface])
ws.close()
await local!.close()
local = null
}
})
it('keeps notification identities on the local read and snapshot paths', async () => {
const backend = new FakeBackend(), seen = vi.fn(), unread = vi.fn()
const ws = new WebSocket(await start(backend, { onAgentSeen: seen, onAppUnread: unread }))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
const item = { agentId: 'a', machineId: 'remote', question: true, text: 'Publish?', readToken: 'question-1' }
ws.send(JSON.stringify({ type: 'app_unread', payload: { items: [item] } }))
ws.send(JSON.stringify({ type: 'agent_seen', payload: { agentId: 'a', readToken: item.readToken } }))
for (const readToken of ['', 42, 'x'.repeat(64)]) ws.send(JSON.stringify({ type: 'agent_seen', payload: { agentId: 'a', readToken } }))
await vi.waitFor(() => expect(seen).toHaveBeenCalledExactlyOnceWith('a', 'question-1'))
expect(unread).toHaveBeenCalledExactlyOnceWith([item])
expect(backend.frames).toEqual([])
ws.close()
})
it('serves the same endpoint over the daemon socket, with no Host to name and no Origin allowed', async () => {
const dir = mkdtempSync('/tmp/hsock-')
const socketPath = join(dir, 'daemon.sock')
const backend = new FakeBackend()
const unix = await listenLocalSocket((_req, res) => { res.statusCode = 404; res.end() }, socketPath)
await start(backend, { localSocketServer: unix.server })
const url = `ws+unix://${socketPath}:/api/local-ws`
try {
// No port, no loopback Host — refused on TCP, served here.
const ws = new WebSocket(url, { headers: { host: 'rebind.evil.example' } })
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
expect(await connected).toMatchObject({ type: 'connected', payload: { machineId, transport: 'local' } })
expect(backend.connId).toMatch(/^local:/)
ws.close()
// A browser still has no business here, whichever way it arrived.
const browser = new WebSocket(url, { headers: { origin: 'http://localhost' } })
const status = await new Promise<number>((resolve) => browser.once('unexpected-response', (_req, res) => resolve(res.statusCode ?? 0)))
expect(status).toBe(403)
} finally {
await local?.close()
local = null
await unix.close()
rmSync(dir, { recursive: true, force: true })
}
})
it('over the Windows pipe, proves the daemon token in the upgrade and drops one without auth', async () => {
// A real pipe on Windows; elsewhere a Unix socket with a pipe's name.
const dir = process.platform === 'win32' ? null : mkdtempSync('/tmp/hsock-')
const pipePath = dir ? join(dir, `harness-${randomBytes(16).toString('hex')}`) : newPipePath()
const token = randomBytes(32)
const backend = new FakeBackend()
const pipe = await listenLocalSocket((_req, res) => { res.statusCode = 404; res.end() }, pipePath, { token })
await start(backend, { localSocketServer: pipe.server })
const createConnection = () => net.connect(pipePath)
try {
const nonce = newPipeNonce(pipePath)
const ws = new WebSocket('ws://localhost/api/local-ws', { createConnection, headers: { [PIPE_AUTH_HEADER]: pipeAuthValue(token, nonce) } })
const upgraded = new Promise<http.IncomingMessage>((resolve) => ws.once('upgrade', resolve))
await onceOpen(ws)
expect(pipeProven((await upgraded).headers, token, nonce)).toBe(true)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
expect(await connected).toMatchObject({ type: 'connected', payload: { machineId, transport: 'local' } })
ws.close()
const stranger = new WebSocket('ws://localhost/api/local-ws', { createConnection })
await expect(onceOpen(stranger)).rejects.toThrow()
} finally {
await local?.close()
local = null
await pipe.close()
if (dir) rmSync(dir, { recursive: true, force: true })
}
})
// The port takes any OS user's process — a guest's harness running as its own user
// (docs/plans/2026-10-19-guest-machine-sharing-plan.md); only this user can read the 0600 credential.
it('takes a TCP upgrade only with the daemon\'s local credential, by header or bearer', async () => {
const credential = 'c'.repeat(43)
const url = await start(new FakeBackend(), { localCredential: credential })
const refused = async (headers: Record<string, string>): Promise<number> => {
const ws = new WebSocket(url, { headers })
return new Promise<number>((resolve) => ws.once('unexpected-response', (_req, res) => resolve(res.statusCode ?? 0)))
}
expect(await refused({})).toBe(401)
expect(await refused({ 'x-harness-local': 'w'.repeat(43) })).toBe(401)
for (const headers of [{ 'x-harness-local': credential }, { authorization: `Bearer ${credential}` }]) {
const ws = new WebSocket(url, { headers })
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
expect(await connected).toMatchObject({ type: 'connected', payload: { machineId } })
ws.close()
}
})
// Audit H1: another account may have heard it while it held this port during a restart.
it('refuses a TCP upgrade with the right credential from another account', async () => {
const credential = 'c'.repeat(43)
const url = await start(new FakeBackend(), { localCredential: credential, peerAccount: async () => false })
const ws = new WebSocket(url, { headers: { 'x-harness-local': credential } })
expect(await new Promise<number>((resolve) => ws.once('unexpected-response', (_req, res) => resolve(res.statusCode ?? 0)))).toBe(401)
})
it('survives a client that resets while the lookup of who it is runs', async () => {
const credential = 'c'.repeat(43)
let release: (mine: boolean) => void = () => {}
let held: Socket | undefined
const url = await start(new FakeBackend(), { localCredential: credential, peerAccount: (socket) => { held = socket; return new Promise((resolve) => { release = resolve }) } })
const ws = new WebSocket(url, { headers: { 'x-harness-local': credential } })
ws.on('error', () => {})
for (let n = 0; n < 200 && !held; n++) await new Promise(resolve => setTimeout(resolve, 5))
expect(held!.listenerCount('error')).toBeGreaterThan(0)
held!.emit('error', new Error('read ECONNRESET'))
held!.destroy()
release(true)
await new Promise(resolve => setTimeout(resolve, 20))
expect(ws.readyState).not.toBe(WebSocket.OPEN)
})
it('takes an upgrade over the daemon\'s socket with no credential, the TCP port still wanting one', async () => {
const dir = mkdtempSync('/tmp/lws-cred-')
const socketPath = join(dir, 'daemon.sock')
const unix = await listenLocalSocket((_req, res) => { res.statusCode = 404; res.end() }, socketPath)
const tcp = await start(new FakeBackend(), { localSocketServer: unix.server, localCredential: 'c'.repeat(43) })
try {
const ws = new WebSocket(`ws+unix://${socketPath}:/api/local-ws`)
await onceOpen(ws)
ws.close()
const refused = new WebSocket(tcp)
expect(await new Promise<number>((resolve) => refused.once('unexpected-response', (_req, res) => resolve(res.statusCode ?? 0)))).toBe(401)
} finally {
await local?.close()
local = null
await unix.close()
rmSync(dir, { recursive: true, force: true })
}
})
it('refuses an upgrade whose Host is not a loopback name for this port', async () => {
const url = await start(new FakeBackend())
const ws = new WebSocket(url, { headers: { host: 'rebind.evil.example:' + new URL(url).port } })
const status = await new Promise<number>((resolve) => ws.once('unexpected-response', (_req, res) => resolve(res.statusCode ?? 0)))
expect(status).toBe(403)
})
it('hands a window that connects late the questions still open', async () => {
const asked = { type: 'commander_question', agentId: 'a1', dbSessionId: 's1', payload: { requestId: 'q_1', questions: [] } }
const ws = new WebSocket(await start(new FakeBackend(), { openQuestions: () => [asked] }))
await onceOpen(ws)
const frames: Frame[] = []
const got = new Promise<void>((resolve) => ws.on('message', (raw) => {
frames.push(JSON.parse(raw.toString()) as Frame)
if (frames.length === 3) resolve()
}))
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await got
expect(frames.map((f) => f.type)).toEqual(['connected', 'commander_question', 'commander_questions_open'])
expect(frames[1]).toEqual(asked)
expect(frames[2]).toEqual({ type: 'commander_questions_open', payload: { requestIds: ['q_1'] } })
ws.close()
})
it('consumes validated preparation UI acknowledgements locally', async () => {
const backend = new FakeBackend(), opened = vi.fn()
const ws = new WebSocket(await start(backend, { onDevicePrepareOpened: opened }))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'device_prepare_opened', payload: { operationId: 'invalid', agentId: 'a' } }))
ws.send(JSON.stringify({ type: 'device_prepare_opened', payload: { operationId: 'a'.repeat(64), agentId: 'agent1' } }))
await vi.waitFor(() => expect(opened).toHaveBeenCalledExactlyOnceWith('a'.repeat(64), 'agent1'))
expect(backend.frames).toEqual([])
ws.close()
})
it.each(['selection', 'visit', 'form'])('addresses one window for %s and consumes its result locally', async kind => {
const backend = new FakeBackend(), reply = vi.fn()
const ws = new WebSocket(await start(backend, { [kind === 'form' ? 'onFormReply' : kind === 'visit' ? 'onVisitReply' : 'onSelectionReply']: reply }))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
expect(local!.sendToWindow('unknown', { type: `dial_${kind}`, payload: {} })).toBe(false)
const request = onceMessage(ws)
expect(local!.sendToWindow(backend.connId!, { type: `dial_${kind}`, payload: { requestId: 'selection' } })).toBe(true)
expect(await request).toEqual({ type: `dial_${kind}`, payload: { requestId: 'selection' } })
ws.send(JSON.stringify({ type: `app_${kind}_result`, payload: { text: 'private selected text' } }))
await vi.waitFor(() => expect(reply).toHaveBeenCalledWith(backend.connId, machineId, { text: 'private selected text' }))
expect(backend.frames).toEqual([])
const id = backend.connId!
ws.close()
await vi.waitFor(() => expect(local!.sendToWindow(id, { type: `dial_${kind}`, payload: {} })).toBe(false))
})
it.each(['selection', 'visit', 'form'])('keeps %s on this desk and ignores upstream gestures', async kind => {
const backend = new FakeBackend(), reply = vi.fn(), focus = vi.fn()
const relayed: Frame[] = [], received: Frame[] = []
let upstream: LocalClientSink | undefined
const relayPool = {
acquire: async (_id: string, _env: string, _select: Frame, sink: LocalClientSink) => {
upstream = sink
sink.sendFrame({ type: 'connected', payload: { machineId: 'remote', e2ee: false } })
return { send: async (frame: Frame) => { relayed.push(frame) }, sendBinary: async () => {}, detach: () => {} }
},
acquireIsolated: async () => { throw new Error('unused') }, invalidate: () => {},
}
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test', [kind === 'form' ? 'onFormReply' : kind === 'visit' ? 'onVisitReply' : 'onSelectionReply']: reply, onAppFocusState: focus,
relayPool: relayPool as unknown as NonNullable<LocalWsServerOptions['relayPool']>,
}))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'remote', localProtocolVersion: 1 } }))
await connected
ws.on('message', raw => received.push(JSON.parse(raw.toString())))
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'remote-agent' } }))
await vi.waitFor(() => expect(focus).toHaveBeenCalled())
const connId = focus.mock.calls[0][2] as string
upstream!.sendFrame({ type: `dial_${kind}`, payload: { requestId: 'upstream' } })
const selection = onceMessage(ws)
expect(local!.sendToWindow(connId, { type: `dial_${kind}`, payload: { requestId: 'from-device' } })).toBe(true)
expect((await selection).payload).toEqual({ requestId: 'from-device' })
ws.send(JSON.stringify({ type: `app_${kind}_result`, payload: { text: 'quoted remote output' } }))
await vi.waitFor(() => expect(reply).toHaveBeenCalledWith(connId, 'remote', { text: 'quoted remote output' }))
expect(relayed.some(frame => frame.type === `app_${kind}_result`)).toBe(false)
expect(received.filter(frame => frame.type === `dial_${kind}`)).toHaveLength(1)
expect(backend.frames).toEqual([])
ws.close()
})
it('relays addressed device commands without sending legacy writes to the local cable', async () => {
const backend = new FakeBackend(), localSettings = vi.fn(), relayed: Frame[] = []
const relayPool = {
acquire: async (_id: string, _env: string, _select: Frame, sink: LocalClientSink) => {
sink.sendFrame({ type: 'connected', payload: { machineId: 'remote', e2ee: false } })
return { send: async (frame: Frame) => { relayed.push(frame) }, sendBinary: async () => {}, detach: () => {} }
},
}
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test', onDialSettings: localSettings,
relayPool: relayPool as unknown as NonNullable<LocalWsServerOptions['relayPool']>,
}))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'remote', localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'dial_settings', payload: { id: 'same-usb', brightness: 90 } }))
const addressed = { type: 'harness_device_settings', payload: { id: 'same-usb', patch: { brightness: 35 }, requestId: 'one' } }
ws.send(JSON.stringify(addressed))
await vi.waitFor(() => expect(relayed).toContainEqual(addressed))
expect(localSettings).not.toHaveBeenCalled()
expect(backend.frames).toEqual([])
expect(relayed).toHaveLength(1)
ws.close()
})
it('accepts loopback, selects the exact machine, and routes JSON plus HTRL binary', async () => {
const backend = new FakeBackend()
const url = await start(backend)
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({
type: 'machine_select',
payload: { machineId, localProtocolVersion: 1 },
}))
await expect(connected).resolves.toMatchObject({
type: 'connected',
payload: { machineId, transport: 'local', e2ee: false },
})
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'r1' } }))
const binary = encodeTerminalLocal({
kind: TerminalBinaryKind.input,
streamId,
seq: 1,
bytes: new TextEncoder().encode('hello'),
compressed: false,
})!
ws.send(binary)
await new Promise((resolve) => setTimeout(resolve, 20))
expect(backend.frames).toEqual([{ type: 'agents_list', payload: { requestId: 'r1' } }])
expect(backend.binaries[0]).toMatchObject({
kind: TerminalBinaryKind.input,
streamId,
seq: 1,
})
const reply = onceMessage(ws)
expect(backend.sink?.sendFrame({ type: 'agents_list_result', payload: { requestId: 'r1', agents: [] } })).toBe(true)
await expect(reply).resolves.toMatchObject({ type: 'agents_list_result' })
ws.close()
})
it.each(['local binary', 'remote JSON', 'remote binary'] as const)(
'keeps later messages behind an unfinished %s operation', async (kind) => {
const backend = new FakeBackend(), pending = gate(), entered = gate()
const trace: string[] = []
const first = async () => {
trace.push('first started')
entered.resolve()
await pending.promise
trace.push('first finished')
}
backend.handleLocalFrame = () => { trace.push('second') }
backend.handleLocalBinary = first
const remote = kind.startsWith('remote')
const relay = {
send: async (frame: Frame) => {
if ((frame.payload as { requestId?: string })?.requestId === 'first') await first()
else trace.push('second')
},
sendBinary: first,
detach: () => {},
}
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test',
relayPool: {
acquire: async (_id: string, _env: string, _select: Frame, sink: LocalClientSink) => {
sink.sendFrame({ type: 'connected', payload: {} })
return relay
},
} as unknown as LocalWsServerOptions['relayPool'],
}))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: remote ? 'remote' : machineId, localProtocolVersion: 1 } }))
await connected
if (kind.endsWith('binary')) {
ws.send(encodeTerminalLocal({ kind: TerminalBinaryKind.input, streamId, seq: 1, bytes: new Uint8Array([97]), compressed: false })!)
} else {
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'first', text: 'route me' } }))
}
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'second' } }))
await entered.promise
// Let the real socket deliver the queued frame while the first operation is held open.
await new Promise((resolve) => setTimeout(resolve, 20))
expect(trace).toEqual(['first started'])
pending.resolve()
await vi.waitFor(() => expect(trace).toEqual(['first started', 'first finished', 'second']))
ws.close()
},
)
it.each(['route_task', 'route_send'] as const)('answers %s off the ordered chain: a window\'s later frames are never held behind it', async (type) => {
// The answer is the devices' (the fleet's router), which may be in a process of their own: one that
// hangs must not hold the window's typing until the request times out.
const backend = new FakeBackend(), pending = gate(), entered = gate()
const trace: string[] = []
const held = async () => { trace.push('route started'); entered.resolve(); await pending.promise; trace.push('route answered') }
backend.handleLocalFrame = () => { trace.push('next') }
const ws = new WebSocket(await start(backend, {
async onRouteTask(this: LocalWsServerOptions) {
expect(this.machineId).toBe(machineId)
await held()
return { agentId: '', machineId: '', name: '', confidence: 0, reason: '', candidates: [], weighed: 0, machines: 0, via: '' }
},
async onRouteSend(this: LocalWsServerOptions) {
expect(this.machineId).toBe(machineId)
await held()
return { ok: true as const }
},
}))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
const answered = new Promise<Frame>((resolve) => ws.on('message', (raw) => {
const frame = JSON.parse(raw.toString()) as Frame
if (frame.type === (type === 'route_task' ? 'route_result' : 'route_send_result')) resolve(frame)
}))
ws.send(JSON.stringify({ type, payload: { requestId: 'first', agentId: 'a1', text: 'route me' } }))
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'second' } }))
await entered.promise
await vi.waitFor(() => expect(trace).toEqual(['route started', 'next']))
pending.resolve()
expect((await answered).payload).toMatchObject({ requestId: 'first' })
expect(trace).toEqual(['route started', 'next', 'route answered'])
ws.close()
})
it.each(['local JSON', 'local binary', 'remote JSON', 'remote binary'] as const)(
'closes the socket when %s dispatch fails', async (kind) => {
const backend = new FakeBackend()
backend.handleLocalFrame = () => { throw new Error('dispatch failed') }
backend.handleLocalBinary = async () => { throw new Error('dispatch failed') }
const relay = { send: async () => { throw new Error('dispatch failed') }, sendBinary: async () => { throw new Error('dispatch failed') }, detach: () => {} }
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test',
relayPool: {
acquire: async (_id: string, _env: string, _select: Frame, sink: LocalClientSink) => {
sink.sendFrame({ type: 'connected', payload: {} })
return relay
},
} as unknown as LocalWsServerOptions['relayPool'],
}))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: kind.startsWith('remote') ? 'remote' : machineId, localProtocolVersion: 1 } }))
await connected
const closed = new Promise<[number, string]>((resolve) => ws.once('close', (code, reason) => resolve([code, reason.toString()])))
if (kind.endsWith('binary')) {
ws.send(encodeTerminalLocal({ kind: TerminalBinaryKind.input, streamId, seq: 1, bytes: new Uint8Array([97]), compressed: false })!)
} else {
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'first' } }))
}
await expect(closed).resolves.toEqual([1011, 'local dispatch failed'])
},
)
it.each(['owned', 'isolated', 'shared'] as const)(
'queues frames during a pending %s relay handshake', async (kind) => {
const backend = new FakeBackend(), pending = gate(), entered = gate()
const frames: Frame[] = []
const acquire = vi.fn(async () => {
entered.resolve()
await pending.promise
return { send: async (frame: Frame) => { frames.push(frame) }, sendBinary: async () => {}, detach: () => {} }
})
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test',
relayPool: { acquire, acquireIsolated: acquire, acquireShare: acquire } as unknown as LocalWsServerOptions['relayPool'],
}))
await onceOpen(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: {
machineId: 'remote', localProtocolVersion: 1,
...(kind === 'shared' ? { shareId: 'share' } : {}), relayIsolation: kind === 'isolated',
} }))
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'queued' } }))
await entered.promise
await new Promise((resolve) => setTimeout(resolve, 20))
expect(acquire).toHaveBeenCalledTimes(1)
expect(frames).toEqual([])
pending.resolve()
await vi.waitFor(() => expect(frames).toEqual([{ type: 'agents_list', payload: { requestId: 'queued' } }]))
expect(backend.frames).toEqual([])
ws.close()
},
)
// Watching a shared harness goes through the gateway's Share relay (gateway/share.ts): the window is told
// what the Share relay said, with the close it set (4403 the share ended, 1013 out of reach).
it.each([
['a share that ended', new RelayConnectError('Sharing ended or invitation expired', 4403), [4403, 'Sharing ended or invitation expired']],
['one out of reach', new RelayConnectError('The owner’s machine is offline.', 1013), [1013, 'The owner’s machine is offline.']],
['one failing without a close', new Error('boom'), [1013, 'boom']],
['one failing with no words', 'down', [1013, 'Sharing unavailable']],
] as const)('closes a window watching %s with the close the Share relay gave', async (_name, error, expected) => {
const backend = new FakeBackend()
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test',
relayPool: { acquire: vi.fn(), acquireShare: vi.fn(async () => { throw error }) } as unknown as LocalWsServerOptions['relayPool'],
}))
await onceOpen(ws)
const closed = new Promise<[number, string]>((resolve) => ws.once('close', (code, reason) => resolve([code, reason.toString()])))
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'owner', localProtocolVersion: 1, shareId: 'share' } }))
expect(await closed).toEqual(expected)
})
it('refuses to watch a shared harness with no gateway to watch it through', async () => {
const backend = new FakeBackend()
const ws = new WebSocket(await start(backend, { autonomousEnv: 'test', relayPool: { acquire: vi.fn() } as unknown as LocalWsServerOptions['relayPool'] }))
await onceOpen(ws)
const closed = new Promise<[number, string]>((resolve) => ws.once('close', (code, reason) => resolve([code, reason.toString()])))
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'owner', localProtocolVersion: 1, shareId: 'share' } }))
expect(await closed).toEqual([4403, 'Sharing is unavailable'])
})
it.each(['owned', 'shared'] as const)('detaches a late %s relay after its window disconnects', async (kind) => {
const backend = new FakeBackend(), pending = gate(), entered = gate(), disconnected = gate(), detach = vi.fn()
const acquire = async () => {
entered.resolve()
await pending.promise
return { send: async () => {}, sendBinary: async () => {}, detach }
}
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test',
relayPool: { acquire, acquireShare: acquire } as unknown as LocalWsServerOptions['relayPool'],
}))
server!.once('connection', (socket) => socket.once('close', disconnected.resolve))
await onceOpen(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: {
machineId: 'remote', localProtocolVersion: 1, ...(kind === 'shared' ? { shareId: 'share' } : {}),
} }))
await entered.promise
const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()))
ws.close()
await closed
await disconnected.promise
pending.resolve()
await vi.waitFor(() => expect(detach).toHaveBeenCalledTimes(1))
expect(backend.unregisters).toEqual([])
})
// A window from before it introduced itself on `terminal_open` still gets named on the far
// machine's "took control" banner: this daemon knows the window is its own desktop.
it('introduces a silent window on a relayed terminal_open, and believes one that speaks', async () => {
const backend = new FakeBackend()
const relayed: Frame[] = []
const relayPool = {
acquire: async (_machineId: string, _env: string, _select: Frame, sink: LocalClientSink) => {
sink.sendFrame({ type: 'connected', payload: { machineId: 'other-machine', e2ee: false } })
return { send: async (frame: Frame) => { relayed.push(frame) }, sendBinary: async () => {}, detach: () => {} }
},
acquireIsolated: async () => { throw new Error('unused') },
invalidate: () => {},
}
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId, backend, autonomousEnv: 'test',
relayPool: relayPool as unknown as NonNullable<Parameters<typeof attachLocalWsServer>[1]['relayPool']>,
localClient: () => ({ kind: 'desktop', name: 'This Mac', machineId }),
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'other-machine', localProtocolVersion: 1 } }))
await expect(connected).resolves.toMatchObject({ type: 'connected' })
ws.send(JSON.stringify({ type: 'terminal_open', payload: { requestId: 'o1', agentId: 'a', cols: 80, rows: 24, protocolVersion: 3 } }))
ws.send(JSON.stringify({ type: 'terminal_open', payload: { requestId: 'o2', agentId: 'a', cols: 80, rows: 24, protocolVersion: 3, client: { kind: 'desktop', name: 'Named by the window' } } }))
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'r1' } }))
await new Promise((resolve) => setTimeout(resolve, 30))
expect(relayed).toEqual([
{ type: 'terminal_open', payload: { requestId: 'o1', agentId: 'a', cols: 80, rows: 24, protocolVersion: 3, client: { kind: 'desktop', name: 'This Mac', machineId } } },
{ type: 'terminal_open', payload: { requestId: 'o2', agentId: 'a', cols: 80, rows: 24, protocolVersion: 3, client: { kind: 'desktop', name: 'Named by the window' } } },
{ type: 'agents_list', payload: { requestId: 'r1' } },
])
ws.close()
})
it('takes the window\'s tile roster, keeps it off the wire, and forgets it on close', async () => {
const backend = new FakeBackend()
const rosters: string[][] = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onAppPanes: (ids) => rosters.push(ids),
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_panes', payload: { agentIds: ['a1', 'a2', '', 7, null] } }))
await new Promise((resolve) => setTimeout(resolve, 20))
// Anything that is not a usable id is dropped rather than trusted.
expect(rosters).toEqual([['a1', 'a2']])
// Like app_focus: it describes a screen at this desk, so the machine never sees it.
expect(backend.frames.map((frame) => frame.type)).toEqual([])
ws.close()
// A window that went away has no tiles open. Left standing, the roster would go on silencing the
// dial for agents nobody can see any more — backwards, and permanently.
await vi.waitFor(() => expect(rosters).toEqual([['a1', 'a2'], []]))
})
it('says whether the window those tiles belong to is actually in front', async () => {
// The roster alone cannot answer it: every pane keeps its place on the tab
// while the window sits behind a browser. Without this the dial stayed quiet
// about work nobody could see, which is the one case it exists for.
const backend = new FakeBackend()
const seen: Array<{ ids: string[]; foreground: boolean }> = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onAppPanes: (ids, foreground) => seen.push({ ids, foreground }),
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_panes', payload: { agentIds: ['a1'], foreground: true } }))
ws.send(JSON.stringify({ type: 'app_panes', payload: { agentIds: ['a1'], foreground: false } }))
// A window that predates the field only ever sent this list while it was up,
// so absence reads as in front — the behaviour it has today.
ws.send(JSON.stringify({ type: 'app_panes', payload: { agentIds: ['a1'] } }))
await vi.waitFor(() => expect(seen).toHaveLength(3))
expect(seen.map((row) => row.foreground)).toEqual([true, false, true])
ws.close()
// No window at all is not a window in front.
await vi.waitFor(() => expect(seen[3]).toEqual({ ids: [], foreground: false }))
})
it('takes the window\'s swarms, drops what is not a swarm, and forgets them on close', async () => {
const backend = new FakeBackend()
const seen: unknown[] = []
const tabs = vi.fn()
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onAppSwarms: (swarms) => seen.push(swarms),
onAppTabAgents: tabs,
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_swarms', payload: {
active: 's2',
swarms: [
{ id: 's1', name: 'Workshop', agentIds: ['a1', '', 7, 'a2'], panes: 3 },
{ id: '', name: 'no id' },
'junk',
{ id: 's2', name: 'Launch' },
],
} }))
await new Promise((resolve) => setTimeout(resolve, 20))
expect(seen).toEqual([{ active: 's2', swarms: [
// Three tiles, two of them agents: the third is a shell or a viewer, and saying so is the
// point — see the terminal-only tab below.
{ id: 's1', name: 'Workshop', agentIds: ['a1', 'a2'], panes: 3 },
// No count at all, from a window too old to send one: as many tiles as agents, which is what
// this row meant before the field existed.
{ id: 's2', name: 'Launch', agentIds: [], panes: 0 },
// This window sent no `tiles`, which is how every window behaved until it had a device with a
// face big enough to draw one. Empty is the honest reading, and the device falls back to
// deriving the shape from the count exactly as it does today.
], tiles: [] }])
// Like app_panes: a fact about this desk, so the machine never sees it.
expect(backend.frames.map((frame) => frame.type)).toEqual([])
expect(tabs).toHaveBeenCalledExactlyOnceWith(backend.connId, ['a1', 'a2'])
ws.close()
// The window is gone, and so are its tabs.
await vi.waitFor(() => expect(seen).toHaveLength(2))
expect(seen[1]).toBeNull()
expect(tabs).toHaveBeenLastCalledWith(backend.connId, null)
})
it('keeps a Swarm tab\'s superTabId and projectId when they are ids, and the fromDevice mark; drops them otherwise', async () => {
const backend = new FakeBackend()
const seen: unknown[] = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, { machineId, backend, onAppSwarms: (swarms) => seen.push(swarms) })
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_swarms', payload: {
active: 's1', fromDevice: true,
swarms: [
{ id: 's1', name: 'Swarm', agentIds: [], panes: 1, superTabId: 'st_1', projectId: 'p-1' },
{ id: 's2', name: 'Bad', agentIds: [], panes: 1, superTabId: 'no spaces', projectId: 7 },
{ id: 's3', name: 'Long', agentIds: [], panes: 1, superTabId: 'x'.repeat(48), projectId: 'y'.repeat(48) },
],
} }))
ws.send(JSON.stringify({ type: 'app_swarms', payload: { active: 's1', fromDevice: 'yes', swarms: [{ id: 's1', name: 'Swarm', agentIds: [], panes: 0, superTabId: 'st_1' }] } }))
await vi.waitFor(() => expect(seen).toHaveLength(2))
expect(seen).toEqual([
{ active: 's1', fromDevice: true, tiles: [], swarms: [
{ id: 's1', name: 'Swarm', agentIds: [], panes: 1, superTabId: 'st_1', projectId: 'p-1' },
{ id: 's2', name: 'Bad', agentIds: [], panes: 1 },
{ id: 's3', name: 'Long', agentIds: [], panes: 1 },
] },
// Only a literal true marks it: anything else is an ordinary announce.
{ active: 's1', tiles: [], swarms: [{ id: 's1', name: 'Swarm', agentIds: [], panes: 0, superTabId: 'st_1' }] },
])
ws.close()
})
it('app_swarms keeps the open thread\'s root beside its conversation, and drops one that is not an id', async () => {
const backend = new FakeBackend()
const seen: unknown[] = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, { machineId, backend, onAppSwarms: (swarms) => seen.push(swarms) })
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_swarms', payload: { active: 's1', swarms: [
{ id: 's1', name: 'Swarm', agentIds: [], panes: 1, superTabId: 'st_1', conversationId: 'pm-1', threadRoot: 'm-1' },
{ id: 's2', name: 'Bad', agentIds: [], panes: 1, superTabId: 'st_1', conversationId: 'pm-1', threadRoot: 'no spaces' },
{ id: 's3', name: 'Alone', agentIds: [], panes: 1, superTabId: 'st_1', threadRoot: 'm-1' },
] } }))
await vi.waitFor(() => expect(seen).toHaveLength(1))
expect(seen[0]).toEqual({ active: 's1', tiles: [], swarms: [
{ id: 's1', name: 'Swarm', agentIds: [], panes: 1, superTabId: 'st_1', conversationId: 'pm-1', threadRoot: 'm-1' },
{ id: 's2', name: 'Bad', agentIds: [], panes: 1, superTabId: 'st_1', conversationId: 'pm-1' },
// A thread is of a conversation: with none named, there is none.
{ id: 's3', name: 'Alone', agentIds: [], panes: 1, superTabId: 'st_1' },
] })
ws.close()
})
it('app_swarms keeps a Swarm tab\'s conversationId, and drops one that is not an id', async () => {
const backend = new FakeBackend()
const seen: unknown[] = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, { machineId, backend, onAppSwarms: (swarms) => seen.push(swarms) })
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_swarms', payload: { active: 's1', swarms: [
{ id: 's1', name: 'Swarm', agentIds: [], panes: 1, superTabId: 'st_1', projectId: 'p-1', conversationId: 'pm-1' },
{ id: 's2', name: 'Bad', agentIds: [], panes: 1, superTabId: 'st_1', conversationId: 'no spaces' },
{ id: 's3', name: 'Long', agentIds: [], panes: 1, superTabId: 'st_1', conversationId: 'c'.repeat(48) },
{ id: 's4', name: 'Number', agentIds: [], panes: 1, superTabId: 'st_1', conversationId: 7 },
] } }))
await vi.waitFor(() => expect(seen).toHaveLength(1))
expect(seen[0]).toEqual({ active: 's1', tiles: [], swarms: [
{ id: 's1', name: 'Swarm', agentIds: [], panes: 1, superTabId: 'st_1', projectId: 'p-1', conversationId: 'pm-1' },
{ id: 's2', name: 'Bad', agentIds: [], panes: 1, superTabId: 'st_1' },
{ id: 's3', name: 'Long', agentIds: [], panes: 1, superTabId: 'st_1' },
{ id: 's4', name: 'Number', agentIds: [], panes: 1, superTabId: 'st_1' },
] })
ws.close()
})
for (const latestCloses of [false, true]) {
it(`keeps the device's desk when a ${latestCloses ? 'latest' : 'background'} machine connection closes`, async () => {
const backend = new FakeBackend(), panes = vi.fn(), swarms = vi.fn(), tabs = vi.fn()
const url = await start(backend, {
onAppPanes: panes, onAppSwarms: swarms, onAppTabAgents: tabs,
relayPool: {
acquire: async (_machine, _env, _select, sink) => {
sink.sendFrame({ type: 'connected', payload: { machineId: 'remote' } })
return { send: async () => {}, sendBinary: async () => {}, detach: () => {} }
},
acquireIsolated: vi.fn(),
invalidate: () => {}, invalidateIsolated: () => {},
} as NonNullable<LocalWsServerOptions['relayPool']>,
autonomousEnv: 'prod',
})
const connect = async (selected: string) => {
const ws = new WebSocket(url)
await onceOpen(ws)
const ready = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: selected, localProtocolVersion: 1 } }))
await ready
return ws
}
const first = await connect(machineId), second = await connect('remote')
const roster = { active: 'tab', swarms: [{ id: 'tab', name: 'Work', agentIds: ['a1'], panes: 1 }], tiles: [] }
const announce = async (ws: WebSocket, foreground: boolean) => {
const count = panes.mock.calls.length
ws.send(JSON.stringify({ type: 'app_panes', payload: { agentIds: ['a1'], foreground } }))
ws.send(JSON.stringify({ type: 'app_swarms', payload: roster }))
await vi.waitFor(() => {
expect(panes).toHaveBeenCalledTimes(count + 1)
expect(swarms).toHaveBeenCalledTimes(count + 1)
})
}
await announce(first, false)
await announce(second, true)
// Reannouncing on an existing socket makes it the newest reporter too.
await announce(first, false)
const closing = latestCloses ? first : second, surviving = latestCloses ? second : first
closing.close()
await vi.waitFor(() => expect(tabs).toHaveBeenCalledTimes(4))
expect(panes).toHaveBeenLastCalledWith(['a1'], latestCloses)
expect(swarms).toHaveBeenLastCalledWith(roster)
expect(panes.mock.calls.some(([ids]) => ids.length === 0)).toBe(false)
expect(swarms.mock.calls.some(([rows]) => rows === null)).toBe(false)
surviving.close()
await vi.waitFor(() => expect(panes).toHaveBeenLastCalledWith([], false))
expect(swarms).toHaveBeenLastCalledWith(null)
})
}
it('follows an explicit app_focus, and keeps it off the wire', async () => {
const backend = new FakeBackend()
const moves: Array<{ machineId: string; agentId: string }> = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onAppFocus: (m, a) => moves.push({ machineId: m, agentId: a }),
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
// hn with no terminal reading a pane is no one's focus.
ws.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'agent-watched', watch: true } }))
// Opening a terminal still counts: that is all an older app build sends.
ws.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'agent-opened' } }))
// And a window that MOVED without opening anything now says so — which is every click on a pane
// that already holds a live session, the case the dial used to miss entirely.
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'agent-focused' } }))
ws.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'background-restored' } }))
await new Promise((resolve) => setTimeout(resolve, 20))
expect(moves).toEqual([
{ machineId, agentId: 'agent-opened' },
{ machineId, agentId: 'agent-focused' },
])
// Consumed locally: it describes a hand at this desk, and the machine has no use for an unknown
// frame type arriving on every pane click.
expect(backend.frames.map((frame) => frame.type)).toEqual(['terminal_open', 'terminal_open', 'terminal_open'])
ws.close()
})
it('app_focus with visibleAgents reaches setLocalTerminalFocus', async () => {
const backend = new FakeBackend()
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, { machineId, backend })
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'a', visibleAgents: ['a', 'b', 7, ''] } }))
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: null, visibleAgents: [] } }))
// An older desktop sends no list: it must stay undefined so the window keeps counting as looking.
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'a' } }))
await vi.waitFor(() => expect(backend.visibles).toHaveLength(3))
expect(backend.visibles.map(([, list]) => list)).toEqual([['a', 'b'], [], undefined])
ws.close()
})
it('reports only explicit voice focus and clears by originating connection', async () => {
const backend = new FakeBackend()
const states: Array<{ machine: string; agent: string | null; conn: string }> = []
const disconnected = vi.fn()
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId, backend,
onAppFocusState: (machine, agent, conn) => states.push({ machine, agent, conn }),
onAppDisconnect: disconnected,
})
await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'background' } }))
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'focused' } }))
ws.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'another-background' } }))
await vi.waitFor(() => expect(states).toHaveLength(1))
expect(states[0]).toMatchObject({ machine: machineId, agent: 'focused' })
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: null } }))
await vi.waitFor(() => expect(states).toHaveLength(2))
expect(states[1]).toEqual({ ...states[0], agent: null })
expect(backend.frames.map(frame => frame.type)).toEqual(['terminal_open', 'terminal_open'])
ws.close()
await vi.waitFor(() => expect(disconnected).toHaveBeenCalledExactlyOnceWith(machineId, states[0].conn))
expect(states).toHaveLength(2)
})
it('keeps Find on the live desktop when a background or replaced socket closes', async () => {
const backend = new FakeBackend(), disconnected = vi.fn()
let focused: { machineId: string; connId: string } | undefined
const form = new WindowForm({ focus: () => focused,
send: (conn, payload) => local!.sendToWindow(conn, { type: 'dial_form', payload }) })
const url = await start(backend, {
onAppFocusState: (machineId, _agent, connId) => { focused = { machineId, connId } },
onAppDisconnect: (machine, conn) => {
disconnected(machine, conn)
if (focused?.connId === conn) focused = undefined
form.disconnected(conn)
},
onFormReply: (conn, machine, payload) => form.reply(conn, machine, payload),
})
const connect = async () => {
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
return { ws, connId: backend.connId! }
}
const select = async (client: Awaited<ReturnType<typeof connect>>, agentId: string | null) => {
client.ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId } }))
await vi.waitFor(() => expect(focused?.connId).toBe(client.connId))
}
const close = async (client: Awaited<ReturnType<typeof connect>>) => {
client.ws.close()
await vi.waitFor(() => expect(backend.unregisters).toContain(client.connId))
}
const ready = async (client: Awaited<ReturnType<typeof connect>>, id: string) => {
const received = onceMessage(client.ws)
const result = form.command({ op: 'open', surface: 'find', formId: id })
const frame = await received
expect(frame.type).toBe('dial_form')
client.ws.send(JSON.stringify({ type: 'app_form_result', payload: {
...(frame.payload as Record<string, unknown>), ok: true, active: true, revision: 1, position: 0, total: 0,
busy: false, enabled: false, canQuery: true, title: 'Find Harness', label: 'Say a name',
} }))
expect(await result).toMatchObject({ ok: true, active: true, canQuery: true })
}
const desktop = await connect()
await select(desktop, null) // An empty workspace can still open Find.
const background = await connect()
await close(background)
expect(focused?.connId).toBe(desktop.connId)
await ready(desktop, 'find-after-background-close')
const replacement = await connect()
await select(replacement, 'selected-pane')
await close(desktop) // The old connection closes after the new one reports focus.
expect(focused?.connId).toBe(replacement.connId)
await ready(replacement, 'find-after-reconnect')
await close(replacement)
expect(focused).toBeUndefined()
expect(disconnected).toHaveBeenCalledTimes(3)
expect(await form.command({ op: 'open', surface: 'find', formId: 'find-offline' }))
.toMatchObject({ ok: false, active: false })
expect(backend.frames).toEqual([])
expect(backend.binaries).toEqual([])
})
it('keeps background connections from stealing selection and releases compatibility mode on disconnect', async () => {
const backend = new FakeBackend(), dial = vi.fn()
const url = await start(backend, { onAppFocus: dial })
const select = async () => {
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
return ws
}
const selected = await select()
selected.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'hn' } }))
await vi.waitFor(() => expect(dial).toHaveBeenCalledExactlyOnceWith(machineId, 'hn'))
const background = await select()
background.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'firmware' } }))
await vi.waitFor(() => expect(backend.frames).toHaveLength(1))
expect(dial).toHaveBeenCalledTimes(1)
selected.send(JSON.stringify({ type: 'app_focus', payload: { agentId: null } }))
selected.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'another-background' } }))
await vi.waitFor(() => expect(backend.frames).toHaveLength(2))
expect(dial).toHaveBeenCalledTimes(1) // a cleared selection must also stay clear
selected.close()
await vi.waitFor(() => expect(backend.unregisters).toHaveLength(1))
background.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'legacy-window' } }))
await vi.waitFor(() => expect(dial).toHaveBeenLastCalledWith(machineId, 'legacy-window'))
background.close()
})
it('keeps stale automatic focus off the dial and forwards its revision for validation', async () => {
const backend = new FakeBackend()
const focus = vi.fn(() => false), dial = vi.fn()
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, { machineId, backend, onAppFocusState: focus, onAppFocus: dial })
await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'first', focusRevision: 'old:0' } }))
ws.send(JSON.stringify({ type: 'terminal_open', payload: { agentId: 'background' } }))
await vi.waitFor(() => expect(focus).toHaveBeenCalledTimes(1))
await vi.waitFor(() => expect(backend.frames).toHaveLength(1))
expect(focus).toHaveBeenCalledWith(machineId, 'first', expect.any(String), 'old:0')
expect(dial).not.toHaveBeenCalled()
expect(backend.frames.map((frame) => frame.type)).toEqual(['terminal_open'])
ws.close()
})
it('tells this daemon\'s terminals which one is focused, even when the dial refuses the move', async () => {
const backend = new FakeBackend()
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
// A stale revision keeps the dial where it is; it says nothing about the terminal in front of the person.
local = attachLocalWsServer(server, { machineId, backend, onAppFocusState: () => false })
await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'focused', focusRevision: 'old:0' } }))
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: '' } })) // malformed: ignored
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: null } }))
await vi.waitFor(() => expect(backend.focuses).toHaveLength(2))
expect(backend.focuses).toEqual([[backend.connId, 'focused'], [backend.connId, null]])
ws.close()
})
it('never hands a relayed machine\'s focus to this daemon\'s terminals', async () => {
const backend = new FakeBackend()
const relayPool = {
acquire: async (_machineId: string, _env: string, _select: Frame, sink: LocalClientSink) => {
sink.sendFrame({ type: 'connected', payload: { machineId: 'other-machine', e2ee: false } })
return { send: async () => {}, sendBinary: async () => {}, detach: () => {} }
},
acquireIsolated: async () => { throw new Error('unused') },
invalidate: () => {},
}
const states: Array<string | null> = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId, backend, autonomousEnv: 'test',
relayPool: relayPool as unknown as NonNullable<Parameters<typeof attachLocalWsServer>[1]['relayPool']>,
onAppFocusState: (_machine, agent) => { states.push(agent) },
})
await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve))
const ws = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'other-machine', localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'app_focus', payload: { agentId: 'remote-agent' } }))
await vi.waitFor(() => expect(states).toEqual(['remote-agent']))
expect(backend.focuses).toEqual([])
ws.close()
})
/** The daemon's Unix socket beside the TCP port: the pair brain's frames are taken only over the socket. */
async function unixWorld(backend: FakeBackend, extra: Partial<LocalWsServerOptions> = {}) {
const dir = mkdtempSync('/tmp/hsock-')
const socketPath = join(dir, 'daemon.sock')
const unix = await listenLocalSocket((_req, res) => { res.statusCode = 404; res.end() }, socketPath)
const tcp = await start(backend, { localSocketServer: unix.server, ...extra })
const open = async (url: string, select: Record<string, unknown>): Promise<WebSocket> => {
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { localProtocolVersion: 1, ...select } }))
await connected
return ws
}
const cleanup = async (): Promise<void> => {
await local?.close()
local = null
await unix.close()
rmSync(dir, { recursive: true, force: true })
}
return { unix: `ws+unix://${socketPath}:/api/local-ws`, tcp, open, cleanup }
}
it('answers daemon_act UNSUPPORTED when there is no pair brain, rather than passing it on', async () => {
const backend = new FakeBackend()
const w = await unixWorld(backend)
try {
const ws = await w.open(w.unix, { machineId })
const result = onceMessage(ws)
ws.send(JSON.stringify({ type: 'daemon_act', payload: { requestId: 'r1', id: 'need:x', choice: 'y' } }))
expect(await result).toEqual({ type: 'daemon_act_result', payload: { requestId: 'r1', id: 'need:x', ok: false, error: 'UNSUPPORTED' } })
expect(backend.frames).toEqual([])
ws.close()
} finally {
await w.cleanup()
}
})
it('takes hn\'s product_observe over the owner\'s socket from a window here, and never passes it on', async () => {
const backend = new FakeBackend(), relayed: Frame[] = []
const relayPool = {
acquire: async (_id: string, _env: string, _select: Frame, sink: LocalClientSink) => {
sink.sendFrame({ type: 'connected', payload: { machineId: 'remote', e2ee: false } })
return { send: async (frame: Frame) => { relayed.push(frame) }, sendBinary: async () => {}, detach: () => {} }
},
acquireIsolated: async () => { throw new Error('unused') }, invalidate: () => {},
}
const w = await unixWorld(backend, { autonomousEnv: 'test', relayPool: relayPool as unknown as NonNullable<LocalWsServerOptions['relayPool']> })
try {
const observe = { type: 'product_observe', payload: { flow: 'viewer_open', outcome: 'ok', durationMs: 12 } }
const hn = await w.open(w.unix, { machineId, client: 'tui' })
const hnId = backend.connId
const others = [await w.open(w.tcp, { machineId, client: 'tui' }), await w.open(w.unix, { machineId, tool: true }),
await w.open(w.unix, { machineId: 'remote', client: 'tui' })]
// Each connection's frames are handled in order: its marker arriving means its observation was handled.
for (const [i, ws] of [hn, ...others].entries()) {
ws.send(JSON.stringify(observe))
ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: `after-${i}` } }))
}
await vi.waitFor(() => expect([...backend.frames, ...relayed].map(f => (f.payload as { requestId?: string }).requestId).sort())
.toEqual(['after-0', 'after-1', 'after-2', 'after-3']))
expect(backend.observed).toEqual([[hnId, observe.payload]])
expect([...backend.frames, ...relayed].some(f => f.type === 'product_observe')).toBe(false)
for (const ws of [hn, ...others]) ws.close()
} finally {
await w.cleanup()
}
})
it('carries the window\'s answer about a spoken task, and keeps it off the wire', async () => {
const backend = new FakeBackend()
const replies: Array<{ voiceId: string; reply: unknown }> = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onVoiceRouteReply: (voiceId, reply) => replies.push({ voiceId, reply }),
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
ws.send(JSON.stringify({ type: 'voice_route_reply', payload: { voiceId: 'v1', state: 'taken' } }))
ws.send(JSON.stringify({ type: 'voice_route_reply', payload: { voiceId: 'v1', state: 'sent', agentId: 'a7' } }))
ws.send(JSON.stringify({ type: 'voice_route_reply', payload: { voiceId: 'v2', state: 'cancelled' } }))
// Neither of these is an answer: one names no request, the other a state this side cannot read.
// Guessing at either would settle a spoken turn on something nobody said.
ws.send(JSON.stringify({ type: 'voice_route_reply', payload: { state: 'sent', agentId: 'a9' } }))
ws.send(JSON.stringify({ type: 'voice_route_reply', payload: { voiceId: 'v3', state: 'maybe' } }))
await new Promise((resolve) => setTimeout(resolve, 20))
expect(replies).toEqual([
{ voiceId: 'v1', reply: { t: 'taken' } },
{ voiceId: 'v1', reply: { t: 'sent', agentId: 'a7' } },
{ voiceId: 'v2', reply: { t: 'cancelled' } },
])
// It describes a hand at this desk. The machine has no use for it.
expect(backend.frames).toEqual([])
ws.close()
})
it('answers a routed task on the id it was asked with, and sends nothing', async () => {
const backend = new FakeBackend()
const asked: string[] = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onRouteTask: async (text) => {
asked.push(text)
return {
agentId: 'a1', machineId: 'm-local', name: 'auth-api', confidence: 0.86, reason: 'name matches',
weighed: 4, machines: 2, via: 'model',
candidates: [{ agentId: 'a1', machineId: 'm-local', name: 'auth-api', machine: 'this computer', engine: 'claude', recent: 'token rotation', confidence: 0.86 }],
}
},
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
const answered = onceMessage(ws)
ws.send(JSON.stringify({ type: 'route_task', payload: { requestId: 'q-7', text: ' fix the retry ' } }))
const reply = await answered // onceMessage already parses
// The requestId comes back UNTOUCHED — it is the window's own rpc id, and the only thing tying this
// answer to the spinner it is holding open.
expect(reply.type).toBe('route_result')
expect(reply.payload).toMatchObject({ requestId: 'q-7', agentId: 'a1', machineId: 'm-local', name: 'auth-api', confidence: 0.86 })
expect(asked).toEqual(['fix the retry'])
// Asking is not sending. Nothing reached the machine.
expect(backend.frames.map((frame) => frame.type)).toEqual([])
ws.close()
})
it('still answers when there is nothing to answer with', async () => {
// The window holds a spinner on the id it asked with, so silence is the one reply it cannot recover
// from — an empty task and a router that throws must both come back as frames.
const backend = new FakeBackend()
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onRouteTask: async () => { throw new Error('router unavailable') },
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
const blank = onceMessage(ws)
ws.send(JSON.stringify({ type: 'route_task', payload: { requestId: 'q-empty', text: ' ' } }))
expect((await blank).payload).toMatchObject({ requestId: 'q-empty', agentId: '', reason: 'empty task' })
const failed = onceMessage(ws)
ws.send(JSON.stringify({ type: 'route_task', payload: { requestId: 'q-throw', text: 'anything' } }))
expect((await failed).payload).toMatchObject({ requestId: 'q-throw', agentId: '', reason: 'router unavailable' })
ws.close()
})
it('delivers a committed route, and keeps the frame off the wire', async () => {
const backend = new FakeBackend()
const sent: Array<{ agentId: string; text: string }> = []
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onRouteSend: async (agentId, text) => {
sent.push({ agentId, text })
return { ok: true as const }
},
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
const delivered = onceMessage(ws)
ws.send(JSON.stringify({ type: 'route_send', payload: { requestId: 's-1', agentId: 'a2', text: 'do the thing' } }))
expect((await delivered).payload).toMatchObject({ requestId: 's-1', ok: true })
// The half-formed one is dropped rather than delivered to whoever sorts first — and it is REFUSED
// out loud, because the window is waiting on this id either way.
const refused = onceMessage(ws)
ws.send(JSON.stringify({ type: 'route_send', payload: { requestId: 's-2', agentId: '', text: 'nobody' } }))
expect((await refused).payload).toMatchObject({ requestId: 's-2', ok: false })
expect(sent).toEqual([{ agentId: 'a2', text: 'do the thing' }])
expect(backend.frames.map((frame) => frame.type)).toEqual([])
ws.close()
})
it('says so when the agent could not be delivered to', async () => {
// The remote leg carries no ack of its own: a machine that has gone deaf takes the turn and nothing
// comes back. With the palette closing silently on a confident route, that is a task that vanishes
// without a mark anywhere — so the refusal has to travel.
const backend = new FakeBackend()
server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
local = attachLocalWsServer(server, {
machineId,
backend,
onRouteSend: async () => ({ ok: false as const, machine: 'mac-mini', reason: 'the last request to it did not come back' }),
})
await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
const answered = onceMessage(ws)
ws.send(JSON.stringify({ type: 'route_send', payload: { requestId: 's-3', agentId: 'a9', text: 'work' } }))
expect((await answered).payload).toMatchObject({
requestId: 's-3', ok: false, machine: 'mac-mini', reason: 'the last request to it did not come back',
})
ws.close()
})
it('does not require a credential on the loopback transport', async () => {
const url = await start(new FakeBackend())
const ws = new WebSocket(url, ['legacy-client-label'])
await onceOpen(ws)
ws.close()
})
it('takes the core\'s own services by their token, whatever machine id they name', async () => {
// A signed-in core serves under its account's machine id; its services name this computer's.
const accepted: string[] = []
const receiveBinary = vi.fn()
let buffered: (() => number) | undefined
const services = {
accept: (service: string, token: string, sink: { buffered(): number }, _close: (code: number, reason: string) => void, welcome: () => void) => {
if (token !== 'boot-token') return null
accepted.push(service)
buffered = sink.buffered
welcome()
return { receive: vi.fn(), receiveBinary, closed: vi.fn() }
},
}
const url = await start(new FakeBackend(), { services })
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({
type: 'machine_select',
payload: { machineId: 'this-computer-id', localProtocolVersion: 1, role: 'service', service: 'search', token: 'boot-token' },
}))
await expect(connected).resolves.toMatchObject({ type: 'connected', payload: { machineId, service: 'search' } })
expect(accepted).toEqual(['search'])
// A service that carries terminals (the gateway) sends bytes on its link, and the core can ask how many
// of its own wait on the socket to it.
ws.send(Uint8Array.of(1, 2, 3))
await vi.waitFor(() => expect(receiveBinary).toHaveBeenCalledWith(new Uint8Array([1, 2, 3])))
expect(buffered?.()).toBe(0)
ws.close()
// The token is the check: a wrong one is refused, whichever machine id it names.
for (const named of [machineId, 'this-computer-id']) {
const wrong = new WebSocket(url)
await onceOpen(wrong)
const closed = new Promise<number>((resolve) => wrong.once('close', resolve))
wrong.send(JSON.stringify({
type: 'machine_select',
payload: { machineId: named, localProtocolVersion: 1, role: 'service', service: 'search', token: 'guessed' },
}))
await expect(closed).resolves.toBe(4401)
}
expect(accepted).toEqual(['search'])
})
it('carries a large remote agent list on an authenticated service link without dropping it', async () => {
const receive = vi.fn(), closed = vi.fn()
const url = await start(new FakeBackend(), { services: {
accept: (_service, token, _sink, _close, welcome) => {
if (token !== 'boot-token') return null
welcome()
return { receive, receiveBinary: vi.fn(), closed }
},
} })
const ws = new WebSocket(url)
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: {
machineId, localProtocolVersion: 1, role: 'service', service: 'gateway', token: 'boot-token',
} }))
await connected
const frame = { type: 'service_notice', payload: { kind: 'windowFrame', id: 'remote-window',
frame: { type: 'agents_list_result', payload: { agents: [{ id: 'remote-agent', name: 'a'.repeat(1024 * 1024) }] } },
} }
ws.send(JSON.stringify(frame))
await vi.waitFor(() => expect(receive).toHaveBeenCalledWith(frame))
ws.send(JSON.stringify({ type: 'service_notice', payload: { kind: 'status', connected: true } }))
await vi.waitFor(() => expect(receive).toHaveBeenCalledTimes(2))
expect(closed).not.toHaveBeenCalled()
ws.close()
})
it('keeps the smaller JSON limit for desktop clients even if a frame claims to be a service', async () => {
const backend = new FakeBackend()
const ws = new WebSocket(await start(backend))
await onceOpen(ws)
const connected = onceMessage(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
await connected
const closed = new Promise<number>((resolve) => ws.once('close', resolve))
ws.send(JSON.stringify({ type: 'service_notice', payload: { role: 'service', data: 'a'.repeat(512 * 1024) } }))
await expect(closed).resolves.toBe(4400)
expect(backend.frames).toEqual([])
})
it('rejects browser origins and machine-id mismatches', async () => {
const url = await start(new FakeBackend())
const browser = new WebSocket(url, { origin: 'https://example.com' })
const error = await new Promise<Error>((resolve) => browser.once('error', resolve))
expect(error.message).toContain('403')
const ws = new WebSocket(url)
await onceOpen(ws)
const closed = new Promise<number>((resolve) => ws.once('close', resolve))
ws.send(JSON.stringify({
type: 'machine_select',
payload: { machineId: 'other-machine', localProtocolVersion: 1 },
}))
await expect(closed).resolves.toBe(4403)
})
})