Skip to content

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

10.4 KB
Raw Blame
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]])
  })
})