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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { AuthSessionManager } from '../lib/authSession.js'
import { b64e, newIdentity } from '../lib/e2ee/core.js'
import { ownerHandshake } from './crypto.js'
const state = vi.hoisted(() => ({ sockets: [] as any[], stop: vi.fn(), liveness: undefined as any }))
vi.mock('ws', async () => {
const { EventEmitter } = await import('node:events')
class FakeWebSocket extends EventEmitter {
static OPEN = 1
readyState = 1
send = vi.fn()
terminate = vi.fn(() => { this.readyState = 3; this.emit('close', 1006, Buffer.alloc(0)) })
constructor(...args: unknown[]) { super(); state.sockets.push(this); (this as any).args = args }
}
return { WebSocket: FakeWebSocket }
})
vi.mock('../lib/wsLiveness.js', () => ({ BACKEND_IDLE_DEADLINE_MS: 75_000, watchSocketLiveness: (_ws: unknown, opts: unknown) => { state.liveness = opts; return { stop: state.stop } } }))
import { HarnessShareRelay, SharingEndedError } from './relay.js'
import { VERSION } from '../version.js'
import { SHARE_REQUEST_TYPES, SHARE_RESULT_TYPES } from './protocol.js'
describe('recipient relay', () => {
const identity = newIdentity()
const share = { id: 'share', agentId: 'agent', name: 'Demo', engine: null,
ownerPublicKey: b64e(identity.pub), expiresAt: new Date(Date.now() + 100000).toISOString() }
let relay: HarnessShareRelay
let account: string
let tokens: ReturnType<typeof vi.fn<() => Promise<string>>>
let discover: ReturnType<typeof vi.fn<() => Promise<any[]>>>
let sink: { sendFrame: ReturnType<typeof vi.fn>; sendBinary: ReturnType<typeof vi.fn> }, closed: ReturnType<typeof vi.fn<(code: number, reason: string) => void>>
beforeEach(() => {
vi.useFakeTimers(); state.sockets = []; state.stop.mockReset()
sink = { sendFrame: vi.fn(() => true), sendBinary: vi.fn(() => true) }; closed = vi.fn()
discover = vi.fn(async () => [{ machineId: 'machine', shares: [share] }])
account = 'first'
tokens = vi.fn(async () => 'signed-in-token')
relay = new HarnessShareRelay({ accessToken: tokens } as unknown as AuthSessionManager,
'ws://localhost:1234/', 'prod', discover, () => account)
})
afterEach(() => { relay.close(); vi.useRealTimers() })
async function begin() {
const count = state.sockets.length
const pending = relay.acquire('machine', 'share', sink as never, closed)
// Its socket opens once the share is found: wait for that, however many steps it takes.
for (let i = 0; i < 100 && state.sockets.length === count; i++) await Promise.resolve()
const ws = state.sockets.at(-1)
ws.emit('open')
return { pending, ws }
}
function frame(ws: any, type: string, payload: unknown = {}) { ws.emit('message', Buffer.from(JSON.stringify({ type, payload }))) }
async function ready() {
const { pending, ws } = await begin()
frame(ws, 'observer_connected')
const hello = JSON.parse(ws.send.mock.calls[0][0])
const owner = ownerHandshake(identity, 'machine', 'share', hello.payload.ephemeral)
frame(ws, 'observer_welcome', owner.welcome)
return { session: await pending, ws, owner }
}
it('uses the account token and exact grant, authenticates the owner, and decrypts terminal/viewer output', async () => {
const { session, ws, owner } = await ready()
// It says it is a daemon's relay, and which CLI (WebSocket roadmap Phase 0).
expect(ws.args).toEqual([`ws://localhost:1234/api/observer-ws?share=share&autonomousEnv=prod&client=relay&v=${encodeURIComponent(VERSION)}`,
['signed-in-token'], expect.any(Object)])
expect(sink.sendFrame).toHaveBeenCalledWith({ type: 'connected', payload: { machineId: 'machine', e2ee: false, readOnly: true } })
await session.send({ type: 'terminal_open', payload: { agentId: 'agent' } })
const packet = JSON.parse(ws.send.mock.calls.at(-1)[0])
expect(packet.type).toBe('observer_frame')
expect(owner.cipher.open(packet.payload)).toEqual({ type: 'terminal_open', payload: { agentId: 'agent' } })
frame(ws, 'observer_frame', owner.cipher.seal({ type: 'observer_binary', payload: { bytes: Buffer.from('output').toString('base64') } }))
expect(sink.sendBinary).toHaveBeenCalledWith(Buffer.from('output'))
frame(ws, 'observer_frame', owner.cipher.seal({ type: 'observer_viewer', payload: { state: 'live', data: 'pixels' } }))
expect(sink.sendFrame).toHaveBeenCalledWith({ type: 'observer_viewer', payload: { state: 'live', data: 'pixels' } })
frame(ws, 'unrelated_broadcast')
ws.emit('error', new Error('socket closing'))
frame(ws, 'observer_frame', owner.cipher.seal({ type: 'observer_binary', payload: { bytes: 5 } }))
expect(sink.sendBinary).toHaveBeenCalledTimes(1)
await session.sendBinary({} as never)
session.detach()
expect(state.stop).toHaveBeenCalled(); expect(closed).not.toHaveBeenCalled()
const count = ws.send.mock.calls.length
await session.send({ type: 'terminal_alive' })
expect(ws.send).toHaveBeenCalledTimes(count)
})
it('never forwards the daemon-local device notices a share owner sends', async () => {
const { ws, owner } = await ready()
sink.sendFrame.mockClear()
for (const type of ['device_key_added', 'device_key_removed', 'device_conflict', 'device_keys_changed']) {
frame(ws, 'observer_frame', owner.cipher.seal({ type, payload: { pub: 'x' } }))
}
expect(sink.sendFrame).not.toHaveBeenCalled()
frame(ws, 'observer_frame', owner.cipher.seal({ type: 'observer_viewer', payload: { state: 'live' } }))
expect(sink.sendFrame).toHaveBeenCalledTimes(1)
})
it('refuses unpublished or wrong-machine grants before opening a socket', async () => {
discover.mockResolvedValue([])
await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toBeInstanceOf(SharingEndedError)
discover.mockResolvedValue([{ machineId: 'machine', shares: [] }])
await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toThrow('expired')
expect(state.sockets).toHaveLength(0)
})
it('rejects input, resizing, generic RPCs and grant-management commands on the recipient side', async () => {
const { session, ws } = await ready()
const count = ws.send.mock.calls.length
for (const type of ['terminal_input', 'terminal_resize', 'terminal_paste', 'agent_delete', ...SHARE_REQUEST_TYPES]) {
await session.send({ type, payload: { requestId: type } })
expect(sink.sendFrame).toHaveBeenLastCalledWith({ type: `${type}_result`, payload: { requestId: type, error: 'VIEW_ONLY' } })
}
await session.send({ type: 'unknown' })
expect(ws.send).toHaveBeenCalledTimes(count)
expect(SHARE_RESULT_TYPES).toEqual(new Set([...SHARE_REQUEST_TYPES].map(type => `${type}_result`)))
})
it('distinguishes revocation from owner disconnects and ignores sends after a transport closes', async () => {
const first = await ready()
first.ws.emit('close', 4403, Buffer.from('Access removed'))
expect(closed).toHaveBeenCalledWith(4403, 'Access removed')
first.ws.readyState = 3
await first.session.send({ type: 'terminal_alive' })
const second = await ready()
second.ws.emit('close', 1006, Buffer.alloc(0))
expect(closed).toHaveBeenLastCalledWith(1012, 'Owner disconnected')
const third = await ready()
frame(third.ws, 'observer_closed', { reason: 'Owner disconnected', retry: true })
expect(closed).toHaveBeenLastCalledWith(1012, 'Owner disconnected')
const fourth = await ready()
frame(fourth.ws, 'observer_closed')
expect(closed).toHaveBeenLastCalledWith(4403, 'Sharing ended')
})
it('fails closed on forged identity, malformed frames, and replayed ciphertext', async () => {
const first = await begin()
const rejected = expect(first.pending).rejects.toThrow('identity')
frame(first.ws, 'observer_welcome', { ephemeral: 'forged', signature: 'forged' }); await rejected
const second = await ready()
frame(second.ws, 'observer_frame', { __e2e: {} })
expect(closed).toHaveBeenLastCalledWith(1011, 'Shared harness verification failed')
const third = await ready()
third.ws.emit('message', Buffer.from('not JSON'))
expect(closed).toHaveBeenLastCalledWith(1011, 'The shared harness identity could not be verified.')
const fourth = await ready()
const packet = fourth.owner.cipher.seal({ type: 'terminal_output', payload: {} })
frame(fourth.ws, 'observer_frame', packet); frame(fourth.ws, 'observer_frame', packet)
expect(closed).toHaveBeenLastCalledWith(1011, 'Shared harness verification failed')
})
it('bounds handshake time and releases failures before admission', async () => {
const first = await begin()
const timed = expect(first.pending).rejects.toThrow('not responding')
await vi.advanceTimersByTimeAsync(15_000); await timed
const second = await begin(); const error = expect(second.pending).rejects.toThrow('Could not connect')
second.ws.emit('error', new Error('offline')); await error
const third = await begin(); const revoked = expect(third.pending).rejects.toThrow('Sharing ended')
frame(third.ws, 'observer_closed'); await revoked
const fourth = await begin(); const offline = expect(fourth.pending).rejects.toThrow('offline')
fourth.ws.emit('close', 1006, Buffer.alloc(0)); await offline
})
it('says out loud when the liveness watcher is the one that gave up', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const { pending } = await begin()
pending.catch(() => {}) // afterEach closes the relay, which rejects this handshake
state.liveness.onIdle(80_000)
expect(log).toHaveBeenCalledWith('[sharing] machine no traffic for 80s — terminating')
// A wake can end the socket too, and never reaches onIdle (wsLiveness.ts, the wake branch).
state.liveness.onWake(90_000, true)
expect(log).toHaveBeenCalledWith('[sharing] machine woke after 90s asleep — giving up on the link')
state.liveness.onWake(50_000, false)
expect(log).toHaveBeenCalledWith('[sharing] machine woke after 50s asleep — re-probing')
log.mockRestore()
})
// Every window opened on a shared harness asked the backend for the account's whole list of shares first
// (WebSocket roadmap Phase 1 item 5). The list is kept now; the backend still checks the share on every connect.
describe('the list of shares', () => {
it('is read once for windows opened within a minute', async () => {
(await ready()).session.detach()
await vi.advanceTimersByTimeAsync(59_000);
(await ready()).session.detach()
expect(discover).toHaveBeenCalledOnce()
})
it('is read again after a minute', async () => {
(await ready()).session.detach()
await vi.advanceTimersByTimeAsync(60_000);
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
it('is read again for a share it does not hold, so a new invitation opens at once', async () => {
(await ready()).session.detach()
const invited = { ...share, id: 'invited' }
discover.mockResolvedValue([{ machineId: 'machine', shares: [share, invited] }])
const pending = relay.acquire('machine', 'invited', sink as never, closed)
await vi.advanceTimersByTimeAsync(0)
expect(discover).toHaveBeenCalledTimes(2)
expect(state.sockets.at(-1).args[0]).toContain('share=invited')
pending.catch(() => {})
})
it('is read again for a share it holds that has expired', async () => {
(await ready()).session.detach()
await vi.setSystemTime(new Date(share.expiresAt).getTime() + 1)
discover.mockResolvedValue([])
await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toBeInstanceOf(SharingEndedError)
expect(discover).toHaveBeenCalledTimes(2)
})
// The backend lists the shares it still honours; this computer's clock may run ahead of it.
it('opens a share the backend has just listed, whatever this computer\'s clock says of its expiry', async () => {
await vi.setSystemTime(new Date(share.expiresAt).getTime() + 1)
const { pending } = await begin()
pending.catch(() => {})
expect(state.sockets).toHaveLength(1)
})
it('is read once for windows that open together', async () => {
const first = relay.acquire('machine', 'share', sink as never, closed)
const second = relay.acquire('machine', 'share', sink as never, closed)
first.catch(() => {}); second.catch(() => {})
await vi.advanceTimersByTimeAsync(0)
expect(discover).toHaveBeenCalledOnce()
expect(state.sockets).toHaveLength(2)
})
it.each([
['the owner ended the sharing', (ws: any) => frame(ws, 'observer_closed')],
['the socket closed before the owner answered', (ws: any) => ws.emit('close', 4403, Buffer.from('Sharing ended or invitation expired'))],
['the owner could not be verified', (ws: any) => frame(ws, 'observer_welcome', { ephemeral: 'forged', signature: 'forged' })],
])('is read again after a window failed to open: %s', async (_why, fail) => {
const { pending, ws } = await begin()
const failed = expect(pending).rejects.toThrow()
frame(ws, 'observer_connected')
fail(ws)
await failed;
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
it.each([
['told the sharing ended', (ws: any) => frame(ws, 'observer_closed')],
['closed as no longer shared', (ws: any) => ws.emit('close', 4403, Buffer.from('Access removed'))],
])('is read again after an open window was %s', async (_how, end) => {
const { ws } = await ready()
end(ws);
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
it('is kept when an open window lost its owner for a while', async () => {
const { ws } = await ready()
ws.emit('close', 1006, Buffer.alloc(0));
(await ready()).session.detach()
expect(discover).toHaveBeenCalledOnce()
})
it('is not kept when reading it failed', async () => {
discover.mockRejectedValueOnce(new Error('Shared harnesses are temporarily unavailable.'))
await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toThrow('temporarily unavailable');
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
it('answers nothing once another account signs in', async () => {
(await ready()).session.detach()
account = 'second';
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
it('read for one account is not kept when another signed in meanwhile', async () => {
let answer: ((machines: any[]) => void) | null = null
discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
const pending = relay.acquire('machine', 'share', sink as never, closed)
pending.catch(() => {})
await vi.advanceTimersByTimeAsync(0)
account = 'second'
answer!([{ machineId: 'machine', shares: [share] }])
await vi.advanceTimersByTimeAsync(0);
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
// Review of #2107, finding 1: the list read for one sign-in opened a window with the next sign-in's token.
it('a window whose list was read for another sign-in opens nothing with the new one', async () => {
let answer: ((machines: any[]) => void) | null = null
discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
.mockImplementationOnce(async () => [])
const pending = relay.acquire('machine', 'share', sink as never, closed)
await vi.advanceTimersByTimeAsync(0)
account = 'second'
answer!([{ machineId: 'machine', shares: [share] }])
await expect(pending).rejects.toBeInstanceOf(SharingEndedError)
expect(discover).toHaveBeenCalledTimes(2)
expect(state.sockets).toHaveLength(0)
})
it('a window whose sign-in changed while it fetched its token opens nothing with the new one', async () => {
let tokenAnswer: ((token: string) => void) | null = null
const tokens = vi.fn<() => Promise<string>>(async () => `token-${account}`)
const fenced = new HarnessShareRelay({ accessToken: tokens } as unknown as AuthSessionManager, 'ws://localhost:1234/', 'prod', discover, () => account)
try {
tokens.mockImplementationOnce(() => new Promise(resolve => { tokenAnswer = resolve }))
const pending = fenced.acquire('machine', 'share', sink as never, closed)
await vi.advanceTimersByTimeAsync(0)
expect(tokens).toHaveBeenCalledOnce()
discover.mockResolvedValue([])
account = 'second'
tokenAnswer!('token-first')
await expect(pending).rejects.toBeInstanceOf(SharingEndedError)
expect(state.sockets).toHaveLength(0)
} finally { fenced.close() }
})
// Finding 2: a refresh that failed left the list it was replacing in use.
it('is not used after a refresh of it failed', async () => {
(await ready()).session.detach()
discover.mockRejectedValueOnce(new Error('Shared harnesses are temporarily unavailable.'))
await expect(relay.acquire('machine', 'missing', sink as never, closed)).rejects.toThrow('temporarily unavailable');
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(3)
})
// Re-check of #2107: a window that took its share from the kept list and was waiting for its token still opened
// after another window's refresh failed.
it('a window waiting for its token looks again after another window\'s refresh failed', async () => {
(await ready()).session.detach()
let tokenAnswer: ((token: string) => void) | null = null
tokens.mockImplementationOnce(() => new Promise(resolve => { tokenAnswer = resolve }))
const before = state.sockets.length
const waiting = relay.acquire('machine', 'share', sink as never, closed)
await vi.advanceTimersByTimeAsync(0)
expect(tokenAnswer).not.toBeNull()
discover.mockRejectedValueOnce(new Error('Shared harnesses are temporarily unavailable.'))
.mockResolvedValueOnce([])
await expect(relay.acquire('machine', 'missing', sink as never, closed)).rejects.toThrow('temporarily unavailable')
tokenAnswer!('signed-in-token')
await expect(waiting).rejects.toBeInstanceOf(SharingEndedError)
expect(discover).toHaveBeenCalledTimes(3)
expect(state.sockets).toHaveLength(before)
})
it('a refresh that fails for a sign-in no longer current leaves the current list alone', async () => {
let fail: ((error: Error) => void) | null = null
discover.mockImplementationOnce(() => new Promise((_resolve, reject) => { fail = reject }))
relay.acquire('machine', 'missing', sink as never, closed).catch(() => {})
await vi.advanceTimersByTimeAsync(0)
account = 'second';
(await ready()).session.detach()
fail!(new Error('Shared harnesses are temporarily unavailable.'))
await vi.advanceTimersByTimeAsync(0);
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
// Finding 3: a refresh begun before a revocation brought the revoked list back, and later windows joined it.
it('a refresh begun before a revocation does not bring the list back', async () => {
const { ws } = await ready()
let answer: ((machines: any[]) => void) | null = null
discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
const missing = relay.acquire('machine', 'missing', sink as never, closed)
missing.catch(() => {})
await vi.advanceTimersByTimeAsync(0)
ws.emit('close', 4403, Buffer.from('Sharing ended'))
answer!([{ machineId: 'machine', shares: [share] }])
await vi.advanceTimersByTimeAsync(0);
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(3)
})
it('a window opened after a revocation does not join a refresh begun before it', async () => {
const { ws } = await ready()
discover.mockImplementationOnce(() => new Promise(() => {}))
relay.acquire('machine', 'missing', sink as never, closed).catch(() => {})
await vi.advanceTimersByTimeAsync(0)
ws.emit('close', 4403, Buffer.from('Sharing ended'));
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(3)
})
it('a window whose list was revoked while it was read reads it again', async () => {
const { ws } = await ready()
let answer: ((machines: any[]) => void) | null = null
await vi.advanceTimersByTimeAsync(60_000)
discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
.mockImplementationOnce(async () => [])
const pending = relay.acquire('machine', 'share', sink as never, closed)
await vi.advanceTimersByTimeAsync(0)
const before = state.sockets.length
ws.emit('close', 4403, Buffer.from('Sharing ended'))
answer!([{ machineId: 'machine', shares: [share] }])
await expect(pending).rejects.toBeInstanceOf(SharingEndedError)
expect(discover).toHaveBeenCalledTimes(3)
expect(state.sockets).toHaveLength(before)
})
it('a window whose sign-in keeps changing while it looks gives up after three lookups and opens nothing', async () => {
discover.mockImplementation(async () => { account = `${account}+`; return [{ machineId: 'machine', shares: [share] }] })
await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toThrow('temporarily unavailable')
expect(discover).toHaveBeenCalledTimes(3)
expect(state.sockets).toHaveLength(0)
})
it('being read for one account does not end the read of another when it finishes', async () => {
let first: ((machines: any[]) => void) | null = null
let second: ((machines: any[]) => void) | null = null
discover.mockImplementationOnce(() => new Promise(resolve => { first = resolve }))
.mockImplementationOnce(() => new Promise(resolve => { second = resolve }))
relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
await vi.advanceTimersByTimeAsync(0)
account = 'second'
relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
await vi.advanceTimersByTimeAsync(0)
first!([])
await vi.advanceTimersByTimeAsync(0)
relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
await vi.advanceTimersByTimeAsync(0)
expect(discover).toHaveBeenCalledTimes(2)
second!([{ machineId: 'machine', shares: [share] }])
await vi.advanceTimersByTimeAsync(0)
// All three open on the second sign-in's list: the first looked its share up again once the sign-in changed.
expect(discover).toHaveBeenCalledTimes(2)
expect(state.sockets).toHaveLength(3)
})
it('being read for one account is not shared with a window of another', async () => {
discover.mockImplementationOnce(() => new Promise(() => {}))
relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
await vi.advanceTimersByTimeAsync(0)
account = 'second';
(await ready()).session.detach()
expect(discover).toHaveBeenCalledTimes(2)
})
})
})