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.

8.5 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { mkdtempSync, rmSync } from 'fs'
import { homedir, tmpdir } from 'os'
import { join } from 'path'
import type { TerminalCreateResult, TmuxRuntimeRef } from './terminalTypes.js'
import { createAndRegisterPane } from './createAgentPane.js'

let dataDir = ''

// Mirrors lib/registry.spec.ts's loadRegistryModule(): a fresh registry module per test, backed by
// its own temp state dir, so pre-seeded runtimeIndex collisions never leak between tests.
async function loadRegistryModule() {
  vi.resetModules()
  process.env.ADAPTER_DATA_DIR = dataDir
  process.env.CLAUDE_PROJECTS_DIR = dataDir
  process.env.CODEX_HOME = dataDir
  process.env.CURSOR_HOME = dataDir
  return import('./registry.js')
}

const succeeded = (paneId: string): TerminalCreateResult<TmuxRuntimeRef> =>
  ({ state: 'succeeded', dispatch: 'executed', runtime: { backend: 'tmux', paneId } })

/** `results[N]` is what `create()` answers on its (N+1)th call; the last entry repeats past that. */
function fakeTmux(results: Array<TerminalCreateResult<TmuxRuntimeRef>>) {
  let call = 0
  return {
    create: vi.fn(async () => results[Math.min(call++, results.length - 1)]!),
    kill: vi.fn(async () => ({ state: 'succeeded' as const, dispatch: 'executed' as const })),
  }
}

describe('createAndRegisterPane', () => {
  beforeEach(() => {
    dataDir = mkdtempSync(join(tmpdir(), 'adapter-registry-'))
  })

  afterEach(() => {
    rmSync(dataDir, { recursive: true, force: true })
    delete process.env.ADAPTER_DATA_DIR
    delete process.env.CLAUDE_PROJECTS_DIR
    delete process.env.CODEX_HOME
    delete process.env.CURSOR_HOME
  })

  it('registers on the first attempt when the pane is unclaimed', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    const tmuxBackend = fakeTmux([succeeded('%1')])

    const result = await createAndRegisterPane({
      tmuxBackend, registry, engine: 'claude', cwd: '/tmp/demo', sessionLabel: 'harness-claude-1', argv: ['claude'],
    })

    expect(result.ok).toBe(true)
    expect(tmuxBackend.create).toHaveBeenCalledTimes(1)
    expect(tmuxBackend.create).toHaveBeenCalledWith(expect.objectContaining({ label: 'harness-claude-1', cwd: homedir() }))
    expect(tmuxBackend.kill).not.toHaveBeenCalled()
  })

  it('starts an explicit-argv terminal in its folder without evaluating its arguments', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    const tmuxBackend = fakeTmux([succeeded('%1')])
    const argv = ['/bin/zsh', '/work/a script', '$(touch injected)', 'a; echo b', '']
    const result = await createAndRegisterPane({
      tmuxBackend, registry, engine: 'terminal', cwd: '/work/project with spaces',
      spawnCwd: '/work/project with spaces', sessionLabel: 'harness-shell-1', argv,
    })
    expect(result.ok).toBe(true)
    expect(tmuxBackend.create).toHaveBeenCalledWith({ label: 'harness-shell-1', cwd: '/work/project with spaces', command: argv })
  })

  it('starts a Windows engine in its workspace with its hand-off, and an explicit folder still wins', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    const tmuxBackend = fakeTmux([succeeded('%1'), succeeded('%2'), succeeded('%3')])
    const afterExit = { command: ['pwsh.exe', '-NoLogo'], env: { HARNESS_ENGINE_COMMAND: 'claude' } }
    await createAndRegisterPane({ tmuxBackend, registry, engine: 'claude', cwd: 'C:\\work', sessionLabel: 'harness-claude-1', argv: ['claude.exe'],
      paneLaunch: { cwd: 'C:\\work', afterExit, clearInherited: ['ANTHROPIC_API_KEY'] } })
    expect(tmuxBackend.create).toHaveBeenLastCalledWith({ label: 'harness-claude-1', cwd: 'C:\\work', command: ['claude.exe'], afterExit, clearInherited: ['ANTHROPIC_API_KEY'] })
    await createAndRegisterPane({ tmuxBackend, registry, engine: 'claude', cwd: '/w', spawnCwd: '/elsewhere', sessionLabel: 'harness-claude-2', argv: ['claude'],
      paneLaunch: { cwd: '/w' } })
    expect(tmuxBackend.create).toHaveBeenLastCalledWith({ label: 'harness-claude-2', cwd: '/elsewhere', command: ['claude'] })
    await createAndRegisterPane({ tmuxBackend, registry, engine: 'claude', cwd: '/w', sessionLabel: 'harness-claude-3', argv: ['claude'], paneLaunch: {} })
    expect(tmuxBackend.create).toHaveBeenLastCalledWith({ label: 'harness-claude-3', cwd: homedir(), command: ['claude'] })
  })

  it('retries past a stale registration collision and succeeds on the next pane', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    // Simulates a stale entry from a previous tmux-server generation already holding %1.
    registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%1' }], cwd: '/tmp/other' })
    const tmuxBackend = fakeTmux([succeeded('%1'), succeeded('%2')])

    const result = await createAndRegisterPane({
      tmuxBackend, registry, engine: 'claude', cwd: '/tmp/demo', sessionLabel: 'harness-claude-1', argv: ['claude'],
    })

    expect(result.ok).toBe(true)
    if (result.ok) expect(result.spawned.runtime.paneId).toBe('%2')
    expect(tmuxBackend.create).toHaveBeenCalledTimes(2)
    expect(tmuxBackend.create).toHaveBeenNthCalledWith(2, expect.objectContaining({ label: 'harness-claude-1-r2' }))
    expect(tmuxBackend.kill).toHaveBeenCalledTimes(1)
    expect(tmuxBackend.kill).toHaveBeenCalledWith({ backend: 'tmux', paneId: '%1' })
  })

  it('gives up with REGISTRATION_FAILED after 3 attempts when every pane collides', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    for (const paneId of ['%1', '%2', '%3']) {
      registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId }], cwd: '/tmp/other' })
    }
    const tmuxBackend = fakeTmux([succeeded('%1'), succeeded('%2'), succeeded('%3')])

    const result = await createAndRegisterPane({
      tmuxBackend, registry, engine: 'claude', cwd: '/tmp/demo', sessionLabel: 'harness-claude-1', argv: ['claude'],
    })

    expect(result.ok).toBe(false)
    if (!result.ok) {
      expect(result.error).toBe('REGISTRATION_FAILED')
      expect(result.detail).toContain('3 attempts')
    }
    expect(tmuxBackend.create).toHaveBeenCalledTimes(3)
    expect(tmuxBackend.kill).toHaveBeenCalledTimes(3)
  })

  it('records the named agent and the requested name on the row it opens', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    const tmuxBackend = fakeTmux([succeeded('%1')])

    const result = await createAndRegisterPane({
      tmuxBackend, registry, engine: 'opencode', cwd: '/home/someone', sessionLabel: 'harness-opencode-1',
      argv: ['opencode', '--agent', 'harness-compute'], agent: 'harness-compute', defaultName: 'Local model',
    })

    expect(result.ok).toBe(true)
    if (!result.ok) return
    expect(result.pending).toMatchObject({ engine: 'opencode', agent: 'harness-compute', defaultName: 'Local model' })
    expect(registry.byAgent(result.pending.agentId)).toMatchObject({ agent: 'harness-compute' })
  })

  it('records which harness here started it, only when another agent did', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    const started = await createAndRegisterPane({
      tmuxBackend: fakeTmux([succeeded('%1')]), registry, engine: 'claude', cwd: '/tmp/demo', sessionLabel: 'harness-claude-1',
      argv: ['claude'], startedBy: 'agent', parentAgentId: 'lead-1',
    })
    expect(started.ok && started.pending).toMatchObject({ startedBy: 'agent', parentAgentId: 'lead-1' })
    const person = await createAndRegisterPane({
      tmuxBackend: fakeTmux([succeeded('%2')]), registry, engine: 'claude', cwd: '/tmp/demo', sessionLabel: 'harness-claude-2',
      argv: ['claude'], parentAgentId: 'lead-1',
    })
    expect(person.ok && person.pending).not.toHaveProperty('parentAgentId')
  })

  it('does not retry a tmux spawn failure', async () => {
    const { registry } = await loadRegistryModule()
    registry.load()
    const openPendingAgent = vi.spyOn(registry, 'openPendingAgent')
    const tmuxBackend = fakeTmux([{ state: 'failed', dispatch: 'not_started', reason: 'tmux is unavailable' }])

    const result = await createAndRegisterPane({
      tmuxBackend, registry, engine: 'claude', cwd: '/tmp/demo', sessionLabel: 'harness-claude-1', argv: ['claude'],
    })

    expect(result.ok).toBe(false)
    if (!result.ok) expect(result.error).toBe('TMUX_UNAVAILABLE')
    expect(tmuxBackend.create).toHaveBeenCalledTimes(1)
    expect(tmuxBackend.kill).not.toHaveBeenCalled()
    expect(openPendingAgent).not.toHaveBeenCalled()
  })
})