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, describe, expect, it, vi } from 'vitest'
import type { BackendSocket } from './backendSocket.js'
import type { RemoteClient } from './core/api.js'
import { dispatchDown, gatewayOf, relaySocket, upstreamOf } from './testing/relaySocket.js'
// A guest: a session trusted only because this machine is shared with its account. Its own space, nothing
// of the owner's (docs/plans/2026-10-19-guest-machine-sharing-plan.md, core/guestPolicy.ts).
describe('a guest session', () => {
const sockets: BackendSocket[] = []
afterEach(async () => { for (const s of sockets.splice(0)) await s.stop(); vi.restoreAllMocks() })
const sealed = (type: string, payload: Record<string, unknown> = {}) => ({ type, payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } }, clear: { type, payload: { requestId: 'one', ...payload } } })
/** A relayed `web` session from `remote`: the owner's own app, or `guest`'s. */
function session(guest?: string, sharedWith = guest) {
const socket = relaySocket('fixture')
sockets.push(socket)
const gw = gatewayOf(socket)
vi.spyOn(gw.e2ee, 'hasSession').mockReturnValue(true)
vi.spyOn(gw.e2ee, 'sessionRole').mockReturnValue('web')
vi.spyOn(gw.e2ee, 'sessionIdentity').mockReturnValue('identity')
vi.spyOn(gw.e2ee, 'pairedPeers').mockReturnValue([{ identityPub: 'identity', label: 'Mac · kim', pairedAt: 1, role: 'web',
...(guest !== undefined ? { shared: true as const, ...(sharedWith ? { sharedWith } : {}) } : {}) }])
const client: RemoteClient = { role: 'web', label: null, identity: 'identity', direct: false, accountOwner: guest === undefined,
...(guest !== undefined ? { guest } : {}) }
;(socket as unknown as { remoteClients: Map<string, RemoteClient> }).remoteClients.set('remote', client)
const replies = vi.spyOn(gw, 'reply').mockImplementation(() => {})
const ask = async (type: string, payload: Record<string, unknown> = {}) => {
const frame = sealed(type, payload)
vi.spyOn(gw.e2ee, 'unwrapDown').mockReturnValue(frame.clear)
await dispatchDown(socket, { type: frame.type, payload: frame.payload }, 'remote')
}
const answered = () => replies.mock.calls.map(([, type, , payload]) => ({ type, payload: payload as Record<string, unknown> }))
return { socket, gw, ask, answered }
}
it('is refused what is not its own, and the service never hears it', async () => {
const { socket, ask, answered } = session('[email protected]')
const routed = vi.fn(() => true)
socket.serviceRouter = routed
await ask('shell', { op: 'open' })
await ask('fs_list_dir', { path: '/Users/owner' })
expect(routed).not.toHaveBeenCalled()
expect(answered()).toEqual([
{ type: 'shell', payload: expect.objectContaining({ error: 'GUEST_NOT_ALLOWED' }) },
{ type: 'fs_list_dir', payload: expect.objectContaining({ error: 'GUEST_NOT_ALLOWED' }) },
])
})
it('may ask what is allowed, as no owner, saying whose guest it is', async () => {
const { socket, ask } = session('[email protected]')
const askers: unknown[] = []
socket.serviceRouter = (_type, _payload, asker, reply) => { askers.push(asker); reply({ ok: true }); return true }
await ask('guest_folders')
expect(askers).toEqual([expect.objectContaining({ owner: false, guest: '[email protected]' })])
})
it('never hears the owner\'s plan allowances: the usage service is not asked', async () => {
const { socket, ask, answered } = session('[email protected]')
const routed = vi.fn(() => true)
socket.serviceRouter = routed
await ask('usage_read')
expect(routed).not.toHaveBeenCalled()
expect(answered()).toEqual([{ type: 'usage_read', payload: expect.objectContaining({ error: 'GUEST_NOT_ALLOWED' }) }])
})
it('lists only its own harnesses, and opens only their terminals', async () => {
const { socket, ask, answered } = session('[email protected]')
const lists: unknown[] = []
socket.agentsProvider = async (_payload, _role, reply, guest) => { lists.push(guest); reply({ agents: [] }) }
socket.agentGuest = (agentId) => (agentId === 'mine' ? '[email protected]' : null)
const opened = vi.fn(async () => true)
;(socket as unknown as { terminalStreams: unknown }).terminalStreams = { handleFrame: opened, stop: vi.fn() }
await ask('agents_list')
expect(lists).toEqual(['[email protected]'])
await ask('terminal_open', { agentId: 'owners' })
expect(opened).not.toHaveBeenCalled()
expect(answered().at(-1)).toEqual({ type: 'terminal_open', payload: expect.objectContaining({ error: 'NOT_YOUR_HARNESS' }) })
await ask('terminal_open', { agentId: 'mine' })
expect(opened).toHaveBeenCalledWith('remote', 'terminal_open', expect.objectContaining({ agentId: 'mine' }))
})
it('the owner\'s own app is still the owner', async () => {
const { socket, ask } = session()
const lists: unknown[] = []
const askers: unknown[] = []
socket.agentsProvider = async (_payload, _role, reply, guest) => { lists.push(guest); reply({ agents: [] }) }
socket.serviceRouter = (type, _payload, asker, reply) => { if (type !== 'shell') return false; askers.push(asker); reply({ ok: true }); return true }
await ask('agents_list')
await ask('shell')
expect(lists).toEqual([undefined])
expect(askers).toEqual([expect.objectContaining({ owner: true })])
})
// A guest starts its own agents on its own sign-in: it needs which engines are installed, never whether the owner
// is signed in to each or when the owner last used it (#4259, from #4216's security review).
it('learns which engines are installed, and nothing of the owner\'s sign-in or last use', async () => {
const probe = async (guest?: string) => {
const { socket, ask, answered } = session(guest)
const reads: unknown[] = []
socket.engineProbeProvider = async (_engines, options) => {
reads.push(options?.accounts === true)
return options?.accounts
? [{ engine: 'claude', installed: true, command: 'claude', installable: false, signedIn: true, lastUsedAt: 1_794_000_000_000 }]
: [{ engine: 'claude', installed: true, command: 'claude', installable: false }]
}
await ask('engines_probe', { engines: ['claude'] })
await vi.waitFor(() => expect(answered().some((a) => a.type === 'engines_probe')).toBe(true))
const reply = answered().find((a) => a.type === 'engines_probe')!.payload as { engines: Array<Record<string, unknown>> }
return { readAccounts: reads, entry: reply.engines[0] }
}
const guest = await probe('[email protected]')
expect(guest.readAccounts).toEqual([false])
expect(guest.entry).toMatchObject({ engine: 'claude', installed: true })
expect(guest.entry).not.toHaveProperty('signedIn')
expect(guest.entry).not.toHaveProperty('lastUsedAt')
// The owner's own app still opens its New Harness box on the agent the owner uses.
const owner = await probe()
expect(owner.readAccounts).toEqual([true])
expect(owner.entry).toMatchObject({ signedIn: true, lastUsedAt: 1_794_000_000_000 })
})
it('manages none of the machine\'s pairings, and joins no trust group: the gateway refuses it', async () => {
const { ask, answered } = session('[email protected]')
await ask('e2ee_pairings_list')
await ask('e2ee_pairing_unpair', { identityPub: 'owner-phone' })
await ask('group_sync')
expect(answered().map((a) => a.payload)).toEqual([
expect.objectContaining({ error: 'GUEST_NOT_ALLOWED' }), expect.objectContaining({ error: 'GUEST_NOT_ALLOWED' }), expect.objectContaining({ error: 'GUEST_NOT_ALLOWED' }),
])
})
it('a share recorded before its account was is still a guest, which owns nothing', async () => {
const { socket, ask, answered } = session('', '')
socket.agentGuest = () => ''
await ask('terminal_open', { agentId: 'any' })
await ask('e2ee_pairings_list')
expect(answered().map((a) => a.payload)).toEqual([
expect.objectContaining({ error: 'NOT_YOUR_HARNESS' }), expect.objectContaining({ error: 'GUEST_NOT_ALLOWED' }),
])
})
it('the gateway sends a guest\'s event to the group, and sealed to each of that guest\'s sessions', () => {
const { gw, socket } = session('[email protected]')
vi.spyOn(gw.e2ee, 'guestSessions').mockImplementation((email) => (email === '[email protected]' ? ['g1', 'g2', 'gone'] : []))
vi.spyOn(gw.e2ee, 'wrapFor').mockImplementation((connId, frame) => (connId === 'gone' ? null : { ...frame, payload: { sealedFor: connId } }))
const queue = upstreamOf(socket).queue
const before = queue.length
gw.broadcast({ type: 'turn_started', agentId: 'mine', payload: {} }, '[email protected]')
gw.broadcast({ type: 'turn_started', agentId: 'owners', payload: {} })
const sent = queue.slice(before).map((q) => q.msg as { targetConnId?: string; frame: { payload: unknown } })
expect(sent.map((m) => m.targetConnId ?? 'group')).toEqual(['group', 'g1', 'g2', 'group'])
expect(sent[1].frame.payload).toEqual({ sealedFor: 'g1' })
})
it('hears its own harnesses\' events sealed for it alone; the owner\'s go to the group only', () => {
const { socket, gw } = session('[email protected]')
socket.agentGuest = (agentId) => (agentId === 'mine' ? '[email protected]' : null)
const broadcast = vi.spyOn(gw, 'broadcast')
socket.send({ type: 'agent_synced', payload: { agent: { id: 'mine' } } })
socket.send({ type: 'turn_started', agentId: 'mine', payload: {} })
socket.send({ type: 'agent_deleted', payload: { agentId: 'mine' } })
socket.send({ type: 'agent_synced', payload: { agent: { id: 'owners' } } })
socket.send({ type: 'machines_changed', payload: {} })
expect(broadcast.mock.calls.map(([frame, guest]) => [frame.type, guest])).toEqual([
['agent_synced', '[email protected]'], ['turn_started', '[email protected]'], ['agent_deleted', '[email protected]'],
['agent_synced', undefined], ['machines_changed', undefined],
])
})
it('hears a question about its own harness sent to the apps away from this desk; the owner\'s goes to the group only', () => {
const { socket, gw } = session('[email protected]')
socket.agentGuest = (agentId) => (agentId === 'mine' ? '[email protected]' : null)
const broadcast = vi.spyOn(gw, 'broadcast')
socket.sendRemote({ type: 'commander_question', agentId: 'mine', payload: { requestId: 'q1' } })
socket.sendRemote({ type: 'commander_question', agentId: 'owners', payload: { requestId: 'q2' } })
expect(broadcast.mock.calls.map(([frame, guest]) => [(frame.payload as { requestId?: unknown }).requestId, guest]))
.toEqual([['q1', '[email protected]'], ['q2', undefined]])
})
})