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.

11.4 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest'
import { GuestHelperError, guestUserFor, type GuestAccounts, type SharedFolder } from '../lib/guestAccounts.js'
import type { GuestHelperState } from '../lib/guestHelperInstall.js'
import { createGuestLaunches } from './guestLaunches.js'

const KIM = guestUserFor('[email protected]')
const LEE = guestUserFor('[email protected]')
const OLD = guestUserFor('[email protected]')

// Never a real OS account or helper: each is a fake the test controls.
function setup(over: {
  state?: GuestHelperState; ensure?: GuestAccounts['ensureGuest']
  folders?: SharedFolder[]; share?: GuestAccounts['shareFolders']; guests?: string[]
} = {}) {
  const accounts = {
    ensureGuest: over.ensure ?? vi.fn(async () => ({ user: KIM, home: `/g/${KIM}`, workspace: `/g/${KIM}/work` })),
    installGuestEngine: vi.fn(), removeGuest: vi.fn(), runCommand: vi.fn(),
    shareFolders: vi.fn(over.share ?? (async () => {})),
    guests: vi.fn(() => over.guests ?? []),
  }
  const lines: string[] = []
  const helperState = vi.fn(async () => over.state ?? 'ready')
  const launches = createGuestLaunches({ accounts: accounts as GuestAccounts, helperState, lang: 'en_GB.UTF-8',
    helperPath: '/opt/helper', folders: () => over.folders ?? [], log: (line) => { lines.push(line) } })
  return { launches, accounts, lines, helperState }
}

const flush = () => new Promise((resolve) => setTimeout(resolve, 0))
const input = { email: '[email protected]', engine: 'claude', bypassPermission: true }

describe('a guest\'s harness, as shared machines builds it', () => {
  it('runs as the guest\'s own account, in its workspace, with only the terminal\'s variables', async () => {
    const { launches, accounts, lines } = setup()
    const first = await launches.launch({ ...input, email: ' [email protected] ' })
    expect(accounts.ensureGuest).toHaveBeenCalledWith('[email protected]')
    expect(first).toEqual({ ok: true, workspace: `/g/${KIM}/work`, argv: expect.arrayContaining(['/opt/helper', KIM, 'claude']),
      env: { TERM: 'xterm-256color', COLORTERM: 'truecolor', LANG: 'en_GB.UTF-8' } })
    const second = await launches.launch({ ...input, engine: 'codex', bypassPermission: true, permissionFlags: ['--approve-for-me'], prompt: 'Fix the tests' })
    expect(second.ok && second.argv.slice(-2)).toEqual(['--approve-for-me', 'Fix the tests'])
    expect(second.ok && second.argv.at(-1)).toBe('Fix the tests')
    expect(lines).toEqual([`launch · claude · ${KIM}`, `launch · codex · ${KIM}`])
  })

  it('works with the defaults: no log, the machine\'s helper and LANG, no folders', async () => {
    const shareFolders = vi.fn(async () => {})
    const launches = createGuestLaunches({ accounts: { ensureGuest: async () => ({ user: KIM, home: '/g', workspace: '/g/work' }), shareFolders, guests: () => [KIM] } as unknown as GuestAccounts,
      helperState: async () => 'ready' })
    const launched = await launches.launch({ ...input, bypassPermission: false })
    expect(launched.ok && launched.argv[4]).toBe('/usr/local/libexec/harness/guest-helper')
    expect(launched.ok && launched.env.LANG).toBe('en_US.UTF-8')
    expect(shareFolders).toHaveBeenCalledWith(KIM, [])
    await launches.sync(() => false, [])
  })

  it('on Windows names the guest\'s own host and runs the engine directly, with no owner pane or helper', async () => {
    const launches = createGuestLaunches({
      accounts: { ensureGuest: async () => ({ user: KIM, home: `C:\\Users\\${KIM}`, workspace: `C:\\Users\\${KIM}\\work` }), shareFolders: async () => {}, guests: () => [KIM] } as unknown as GuestAccounts,
      helperState: async () => 'ready', platform: 'win32',
    })
    const launched = await launches.launch(input)
    expect(launched).toEqual({ ok: true, workspace: `C:\\Users\\${KIM}\\work`, argv: ['claude', '--dangerously-skip-permissions'],
      env: {}, guestHostUser: KIM })
    // Every other platform leaves the pane to the owner's backend and the helper.
    expect(await setup().launches.launch(input)).not.toHaveProperty('guestHostUser')
  })

  it('starts nothing for a session whose guest it cannot name, or an engine it does not start for guests', async () => {
    const { launches, accounts } = setup()
    expect(await launches.launch({ ...input, email: ' ' })).toEqual({ ok: false, error: 'NOT_YOUR_HARNESS', detail: expect.any(String) })
    expect(await launches.launch({ ...input, engine: 'opencode' })).toEqual({ ok: false, error: 'GUEST_ENGINE_UNSUPPORTED', detail: expect.stringMatching(/Claude Code or Codex/) })
    expect(accounts.ensureGuest).not.toHaveBeenCalled()
  })

  it('asks the owner to turn guest access on, in words, until the helper is ready', async () => {
    for (const [state, words] of [['missing', /finished turning on sharing/], ['outdated', /after an update/], ['not-authorized', /sharing back on\./]] as const) {
      const { launches } = setup({ state })
      expect(await launches.launch(input)).toEqual({ ok: false, error: 'GUEST_HELPER_REQUIRED', detail: expect.stringMatching(words) })
    }
  })

  it('says what the helper said when the account could not be made', async () => {
    const { launches } = setup({ ensure: async () => { throw new GuestHelperError('GUEST_INVALID', 'not an email') } })
    expect(await launches.launch(input)).toEqual({ ok: false, error: 'GUEST_INVALID', detail: 'not an email' })
    const odd = setup({ ensure: async () => { throw new Error('boom') } })
    expect(await odd.launches.launch(input)).toEqual({ ok: false, error: 'GUEST_HELPER_FAILED', detail: 'The guest helper failed.' })
  })

  describe('the owner\'s shared folders', () => {
    const folders = [{ path: '/Users/dee/code/app', write: true }, { path: '/Users/dee/docs/', write: false }]

    it('are the guest\'s on every harness, which starts in one when the guest asks, and in its workspace otherwise', async () => {
      const { launches, accounts } = setup({ folders })
      const inApp = await launches.launch({ ...input, cwd: '/Users/dee/code/app/src/../src' })
      expect(accounts.shareFolders).toHaveBeenCalledWith(KIM, folders)
      expect(inApp).toMatchObject({ ok: true, workspace: '/Users/dee/code/app/src', argv: expect.arrayContaining(['--cwd', '/Users/dee/code/app/src']) })
      expect(await launches.launch({ ...input, cwd: '/Users/dee/docs' })).toMatchObject({ ok: true, workspace: '/Users/dee/docs' })
      // Not shared, a neighbour that only starts the same, relative, or absent: its workspace.
      for (const cwd of ['/Users/dee/secret', '/Users/dee/code/application', 'code/app', undefined]) {
        expect(await launches.launch({ ...input, ...(cwd ? { cwd } : {}) }), String(cwd)).toMatchObject({ ok: true, workspace: `/g/${KIM}/work` })
      }
    })

    it('a share that failed stops a harness meant for that folder, and no other', async () => {
      const { launches, lines } = setup({ folders, share: async () => { throw new GuestHelperError('GUEST_INVALID', 'no such folder: /Users/dee/docs') } })
      expect(await launches.launch({ ...input, cwd: '/Users/dee/docs' })).toEqual({ ok: false, error: 'GUEST_FOLDER_UNAVAILABLE',
        detail: 'That folder could not be shared with you: no such folder: /Users/dee/docs' })
      expect(await launches.launch(input)).toMatchObject({ ok: true, workspace: `/g/${KIM}/work` })
      expect(lines.filter((l) => l.startsWith('could not share'))).toHaveLength(2)
      const odd = setup({ folders, share: async () => { throw 'helper gone' } })
      expect(await odd.launches.launch({ ...input, cwd: '/Users/dee/docs' })).toMatchObject({ detail: 'That folder could not be shared with you: helper gone' })
    })

    it('are shared one at a time: two shares never read the helper\'s record at once', async () => {
      const order: string[] = []
      let release: () => void = () => {}
      const { launches } = setup({ folders, guests: [KIM, LEE], share: async (user) => {
        order.push(`start ${user}`)
        if (order.length === 1) await new Promise<void>((resolve) => { release = resolve })
        order.push(`end ${user}`)
      } })
      const launched = launches.launch(input)
      await flush()
      const synced = launches.sync(() => true, ['[email protected]', '[email protected]'])
      await flush()
      expect(order).toEqual([`start ${KIM}`])
      release()
      await Promise.all([launched, synced])
      expect(order).toEqual([`start ${KIM}`, `end ${KIM}`, `start ${KIM}`, `end ${KIM}`, `start ${LEE}`, `end ${LEE}`])
    })
  })

  describe('sharing kept true', () => {
    it('gives every guest still named the owner\'s folders, and takes them from every other account', async () => {
      const folders = [{ path: '/Users/dee/docs', write: false }]
      const { launches, accounts, lines } = setup({ folders, guests: [KIM, LEE, OLD] })
      await launches.sync((email) => email !== '[email protected]', ['[email protected]', '[email protected]'])
      expect(accounts.shareFolders.mock.calls).toEqual([[KIM, folders], [LEE, []], [OLD, []]])
      // One that fails is said, and the rest go on.
      accounts.shareFolders.mockRejectedValueOnce(new Error('EPERM')).mockRejectedValueOnce('gone')
      await launches.sync(() => true, ['[email protected]'])
      expect(lines.filter((l) => l.startsWith('could not share'))).toEqual([`could not share folders with ${KIM}: EPERM`, `could not share folders with ${LEE}: gone`])
    })

    it('asks nothing of the helper while there are no guests, or guest access is off', async () => {
      const none = setup({ folders: [{ path: '/x', write: false }] })
      await none.launches.sync(() => true, ['[email protected]'])
      expect(none.helperState).not.toHaveBeenCalled()
      const off = setup({ state: 'missing', guests: [KIM] })
      await off.launches.sync(() => true, ['[email protected]'])
      expect(off.accounts.shareFolders).not.toHaveBeenCalled()
    })
  })

})

// No owner subscription relay (anh Dee, 2026-11-07, task #4137): nothing is started or minted for a guest, and its engine
// launches on the guest's own sign-in, with none of the relay's variables or Codex provider arguments.
describe('a guest\'s harness on the guest\'s own sign-in', () => {
  const guestAccounts = (workspace: string) =>
    ({ ensureGuest: async () => ({ user: KIM, home: '/g', workspace }), shareFolders: async () => {}, guests: () => [KIM] }) as unknown as GuestAccounts
  const relayFree = (launched: Awaited<ReturnType<ReturnType<typeof createGuestLaunches>['launch']>>) => {
    expect(launched.ok).toBe(true)
    if (!launched.ok) return
    for (const name of ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'HARNESS_RELAY_TOKEN']) {
      expect(launched.env).not.toHaveProperty(name)
      expect(launched.argv).not.toContain(name)
    }
    expect(launched.argv.join(' ')).not.toMatch(/model_provider|harness_owner|127\.0\.0\.1/)
  }

  it('launches Claude Code and Codex with no relay, on every platform', async () => {
    for (const platform of ['darwin', 'linux', 'win32'] as const) {
      const launches = createGuestLaunches({ accounts: guestAccounts('/g/work'), helperState: async () => 'ready', platform })
      for (const engine of ['claude', 'codex']) relayFree(await launches.launch({ ...input, engine }))
    }
  })

  it('on Windows hands the guest\'s host the engine alone', async () => {
    const launches = createGuestLaunches({ accounts: guestAccounts('C:\\g\\work'), helperState: async () => 'ready', platform: 'win32' })
    expect(await launches.launch({ ...input, engine: 'codex' }))
      .toEqual({ ok: true, workspace: 'C:\\g\\work', argv: ['codex', '--dangerously-bypass-approvals-and-sandbox'], env: {}, guestHostUser: KIM })
  })
})