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.

13.0 KB
Raw Blame
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { emptyPorts, type TerminalWatchOutput } from '../core/api.js'
import { b64d, b64e, newEphemeral, newIdentity, sign, welcomeSig } from '../lib/e2ee/core.js'
import { encodeRoster, rosterBytes, type Roster } from '../messages/roster.js'
import { RosterStore } from '../messages/rosterStore.js'
import { ConsentStore } from '../messages/consentStore.js'
import { setAgentSettingsForTest, signedOutForTest } from '../testing/agentSettings.js'
import type { RegisteredSession } from '../lib/registry.js'
import { observerContext, recipientHandshake } from '../sharing/crypto.js'
import { fakeCore } from '../testing/fakeCore.js'
import { SHARE_REQUESTS, shareObservers, startSharing, viewerPage, watchStreams } from './sharing.js'
import { observerSource, publishObservers } from '../superTabs/observers.js'

const identity = newIdentity()
const agent = { agentId: 'agent', sessionId: 's', engine: 'codex', active: true } as unknown as RegisteredSession

// HARNESS_SWARM=off: Share's process hands in no Swarm. Its observers then watch nothing, invitations kept as for a host
// that stalled, and a session a roster marked confidential still refuses every share (sharing/swarmMarks.ts).
describe('who a Super Tab lets watch a harness here', () => {
  let dataDir: string
  beforeEach(() => { dataDir = mkdtempSync(join(tmpdir(), 'sharing-observers-')) })
  afterEach(() => { rmSync(dataDir, { recursive: true, force: true }) })
  const core = () => fakeCore({ dataDir, daemon: { command: 'harness', port: 1, machineId: () => 'machine' } })
  const grant = (agentId: string, tab?: string) => ({ agentId, recipientEmail: '[email protected]', ...(tab ? { tab } : {}) }) as never

  it('is the Swarm\'s roster while it is on, and with it off, none of a Super Tab\'s and no confidential session\'s', () => {
    publishObservers(dataDir, 'machine', [{ tabId: 'tab', agent: { harnessId: 'member', machineId: 'machine' }, observers: [{ email: '[email protected]' }] },
      { tabId: 'tab', confidential: true, agent: { harnessId: 'lead', machineId: 'machine' }, observers: [] }], Date.now() + 5_000)
    const on = shareObservers(core(), observerSource)
    expect(on.known()).toEqual([expect.objectContaining({ tab: 'super:tab', agentId: 'member', email: '[email protected]' })])
    expect(on.allows(grant('member', 'super:tab'))).toBe(true)
    expect(on.allows(grant('lead'))).toBe(false)
    expect(on.allows(grant('ordinary'))).toBe(true)
    expect(on.paused(grant('member', 'super:tab'))).toBe(false)
    const off = shareObservers(core())
    expect(off.known()).toBeNull()
    expect(off.allows(grant('member', 'super:tab'))).toBe(false)
    expect(off.allows(grant('lead'))).toBe(false)
    expect(off.allows(grant('ordinary'))).toBe(true)
    expect(off.paused(grant('member', 'super:tab'))).toBe(false)
  })
})

describe('Share, as a service', () => {
  let dataDir: string
  beforeEach(() => { dataDir = mkdtempSync(join(tmpdir(), 'sharing-service-')) })
  afterEach(() => { rmSync(dataDir, { recursive: true, force: true }); signedOutForTest() })

  const start = (over: Parameters<typeof fakeCore>[0] = {}) => {
    const outputs: Array<(viewer: string, output: TerminalWatchOutput) => void> = []
    const watch = { frame: vi.fn(async () => {}), close: vi.fn(async () => {}), onOutput: vi.fn((listener: (viewer: string, output: TerminalWatchOutput) => void) => { outputs.push(listener); return () => {} }) }
    const sent: Array<{ connId: string; type: string; payload: any }> = []
    const viewers = { watch: vi.fn((_id: string, send: (frame: Record<string, unknown>) => void) => { send({ state: 'live' }); return vi.fn() }), stop: vi.fn() }
    const core = fakeCore({
      dataDir,
      terminals: { watch },
      agents: {
        resolve: (id: string) => { if (id === 'explode') throw new Error('the registry could not be read'); return id === 'agent' ? agent : undefined },
        dsh: () => ({ viewerUrl: 'http://127.0.0.1:7/' } as never),
      },
      account: {
        ...over.account,
        observerKey: {
          publicKey: async () => b64e(identity.pub),
          signWelcome: async (machineId, shareId, peer, ephemeral) => b64e(welcomeSig(identity.priv, observerContext(machineId, shareId), b64d(peer), b64d(ephemeral))),
        },
        backend: vi.fn(async () => ({ status: 200, body: {} })),
      },
      clients: { observer: vi.fn((connId: string, type: string, payload: Record<string, unknown>) => { sent.push({ connId, type, payload }); return true }) },
      daemon: { command: 'harness', port: 1, machineId: () => 'machine', autonomousEnv: 'staging' },
    })
    const ports = emptyPorts()
    const requests = startSharing(core, ports, { viewers })
    return { core, ports, port: ports.sharing!, requests, watch, outputs, sent, viewers }
  }

  it('answers its requests, as the socket did, and says Share is unavailable when one fails outright', async () => {
    const { requests, core } = start()
    expect(Object.keys(requests)).toEqual([...SHARE_REQUESTS])
    const asker = { local: true, owner: true }
    const linked = await requests.harness_share_link({ agentId: 'agent', visibility: 'public' }, asker) as { link: { url: string } }
    // The link names the owner's key the gateway holds, and the account's environment.
    expect(linked.link.url).toContain(`key=${encodeURIComponent(b64e(identity.pub))}`)
    expect(linked.link.url).toContain('env=staging')
    expect(core.account.backend).toHaveBeenCalledWith('PUT', expect.stringMatching(/^\/api\/harness-links\//), expect.objectContaining({ visibility: 'public' }))
    vi.mocked(core.account.backend).mockRejectedValueOnce(new Error('offline'))
    expect(await requests.harness_share_list({ agentId: 'nobody' }, asker)).toMatchObject({ error: 'HARNESS_NOT_FOUND' })
    expect(await requests.harness_share_list({ agentId: 'explode' }, asker)).toEqual({ error: 'SHARING_UNAVAILABLE', detail: 'Sharing is temporarily unavailable. Try again.' })
  })

  it('welcomes an observer with a signature the gateway made, and seals what the core\'s streams show it', async () => {
    const { requests, port, watch, outputs, sent, viewers } = start()
    const linked = await requests.harness_share_link({ agentId: 'agent', visibility: 'public' }, { local: true, owner: true }) as { link: { id: string } }
    const ephemeral = newEphemeral()
    await port.observer('observer:ken', 'observer_open', { linkId: linked.link.id, ephemeral: b64e(ephemeral.pub), authorId: 'u1', authorName: 'Ken' })
    const welcome = sent.find((frame) => frame.type === 'observer_welcome')!
    const cipher = recipientHandshake(ephemeral, 'machine', linked.link.id, b64e(identity.pub), welcome.payload)
    await port.observer('observer:ken', 'observer_frame', cipher.seal({ type: 'terminal_open', payload: { agentId: 'agent', requestId: 'r1' } }) as never)
    expect(watch.frame).toHaveBeenCalledWith('observer:ken', 'terminal_open', { agentId: 'agent', requestId: 'r1' })
    for (const listener of outputs) {
      listener('observer:ken', { type: 'terminal_opened', payload: { streamId: 's' } })
      listener('observer:ken', { binary: 'aGk=' })
    }
    const shown = sent.filter((frame) => frame.type === 'observer_frame').map((frame) => cipher.open(frame.payload))
    expect(shown).toEqual([{ type: 'terminal_opened', payload: { streamId: 's' } }, { type: 'observer_binary', payload: { bytes: 'aGk=' } }])
    // Its viewer, captured where Share runs, from the agent's viewer the core shows.
    await port.observer('observer:ken', 'observer_frame', cipher.seal({ type: 'observer_viewer', payload: {} }) as never)
    expect(viewers.watch).toHaveBeenCalledWith('agent', expect.any(Function))
    port.linkDown()
    expect(watch.close).toHaveBeenCalledWith('observer:ken')
    await port.stop()
    expect(viewers.stop).toHaveBeenCalledOnce()
  })

  it('reads its viewers\' pages from the core\'s agents, and starts a pool of its own when given none', async () => {
    const core = fakeCore({ dataDir, agents: { resolve: (id: string) => (id === 'agent' ? agent : undefined), dsh: (session) => (session === agent ? { viewerUrl: 'http://127.0.0.1:7/' } as never : null) } })
    const page = viewerPage(core)
    expect(page('agent')).toBe('http://127.0.0.1:7/')
    expect(page('nobody')).toBeNull()
    const ports = emptyPorts()
    startSharing(core, ports)
    await ports.sharing!.stop()
    expect(viewerPage(fakeCore({ agents: { resolve: () => agent, dsh: () => null } }))('agent')).toBeNull()
  })

  it('derives its observers from the shared tabs Agent Messages holds here, read only, for the account signed in', async () => {
    setAgentSettingsForTest(dataDir, { agentMessages: true })
    const tabOwner = newIdentity(), TAB = 'a1b2c3d4e5f6a1b2c3d4e5f6', dir = join(dataDir, 'agent-messages')
    const file = join(dir, 'shared-tabs.json'), consentFile = join(dir, 'shared-tabs-consent.json')
    let version = 0
    const roster = (members: string[]): Roster => ({ sharedTabId: TAB, version, name: 'app',
      owner: { accountId: 'u-alice', email: '[email protected]', machineId: 'alice-mac', machinePublicKey: b64e(tabOwner.pub) }, leader: null,
      members: ['u-bob', ...members].map((id) => ({ accountId: id, email: `${id.slice(2)}@x.io`, name: id, acceptedAt: '2026-10-15T00:00:00.000Z' })),
      harnesses: [{ accountId: 'u-bob', machineId: 'machine', machinePublicKey: b64e(identity.pub), agentId: 'agent', name: 'api', engine: 'codex' }], invites: [] })
    const hold = (members: string[]) => {
      const rosters = new RosterStore(file)
      rosters.pin(TAB, b64e(tabOwner.pub))
      version++
      const body = encodeRoster(roster(members))
      rosters.offer({ body, signature: b64e(sign(tabOwner.priv, rosterBytes(TAB, version, body))) })
    }
    let account: { accountId: string; email: string } | null = { accountId: 'u-bob', email: '[email protected]' }
    const { requests, core } = start({ account: { identity: async () => account } })
    const asker = { local: true, owner: true }
    const derive = async () => { const answer = await requests.harness_share_rosters({}, asker); for (let i = 0; i < 5; i++) await new Promise((done) => setTimeout(done, 0)); return answer }
    const shared = () => vi.mocked(core.account.backend).mock.calls.filter(([, path]) => path.startsWith('/api/harness-shares/')).map(([method, , body]) => [method, (body as { recipientEmail?: string } | undefined)?.recipientEmail])
    // No shared tab here yet: nothing to grant.
    expect(await derive()).toEqual({ invited: 0, revoked: 0 })
    hold(['u-carol'])
    // Listed by the owner, but never asked for from this machine: nobody watches it.
    expect(await derive()).toEqual({ invited: 0, revoked: 0 })
    new ConsentStore(consentFile).grant(TAB, 'machine', 'agent', true)
    expect(await derive()).toEqual({ invited: 2, revoked: 0 })
    expect(shared()).toEqual([['PUT', '[email protected]'], ['PUT', '[email protected]']])
    // An account the core cannot say, or a file Agent Messages has not finished writing, takes nobody's view away.
    hold([])
    account = null
    expect(await derive()).toEqual({ invited: 0, revoked: 0 })
    account = { accountId: 'u-bob', email: '[email protected]' }
    for (const path of [file, consentFile]) {
      const whole = readFileSync(path, 'utf8')
      writeFileSync(path, '{"tabs":')
      expect(await derive()).toEqual({ invited: 0, revoked: 0 })
      // Only read: the file is neither moved aside nor rewritten, which is the messages process's alone.
      expect(readFileSync(path, 'utf8')).toBe('{"tabs":')
      writeFileSync(path, whole)
    }
    expect(await derive()).toEqual({ invited: 0, revoked: 1 })
    expect(shared().at(-1)).toEqual(['DELETE', undefined])
    // Agent Messages off here: its rosters stop following the tabs, so every derived grant goes.
    setAgentSettingsForTest(dataDir, { agentMessages: false })
    expect(await derive()).toEqual({ invited: 0, revoked: 1 })
    setAgentSettingsForTest(dataDir, { agentMessages: true })
    expect(await derive()).toEqual({ invited: 1, revoked: 0 })
  })

  it('hands the owner the core\'s streams: frames to the core, what each viewer is shown back to it', async () => {
    const outputs: Array<(viewer: string, output: TerminalWatchOutput) => void> = []
    const stopHearing = vi.fn()
    const watch = { frame: vi.fn(async () => {}), close: vi.fn(async () => {}), onOutput: vi.fn((listener: (viewer: string, output: TerminalWatchOutput) => void) => { outputs.push(listener); return stopHearing }) }
    const sendTarget = vi.fn(() => true)
    const streams = watchStreams(watch, { sendTarget })
    expect(await streams.handleFrame('v', 'terminal_ack', {})).toBe(true)
    await streams.closeConnection('v')
    expect(watch.close).toHaveBeenCalledWith('v')
    outputs[0]('v', { binary: 'aGk=' })
    outputs[0]('v', { type: 'terminal_closed', payload: {} })
    expect(sendTarget.mock.calls).toEqual([['v', 'observer_binary', { bytes: 'aGk=' }], ['v', 'terminal_closed', {}]])
    await streams.stop()
    expect(stopHearing).toHaveBeenCalledOnce()
  })
})