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.

21.7 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from '../../lib/registry.js'
import type { DiscoveredTerminalAgent } from '../../lib/terminalAgentDiscovery.js'
import type { TerminalBackend } from '../../lib/terminalBackend.js'
import { bypassPermissionActive, permissionModeFromArgv } from '../../lib/processTable.js'
import { createDiscoveryHandlers, type DiscoveryDeps } from './discovery.js'

// The pane's backend, asked what became of an unconfirmed start's pane.
const paneState = vi.fn<TerminalBackend['paneState']>(async () => 'gone')
const paneBackend = { paneState } as unknown as TerminalBackend

const row = (over: Partial<RegisteredSession> = {}): RegisteredSession =>
  ({ agentId: 'a1', sessionId: 's1', engine: 'claude', active: true, ...over }) as RegisteredSession
const seen = (over: Partial<DiscoveredTerminalAgent> = {}): DiscoveredTerminalAgent => ({
  engine: 'claude',
  cwd: '/work',
  runtimes: [{ backend: 'tmux', paneId: '%0' }],
  primaryRuntimeKey: 'tmux:%0',
  processIdentity: { pid: 42, startMarker: 'now' },
  args: 'claude',
  ...over,
}) as unknown as DiscoveredTerminalAgent

function setup(over: Partial<DiscoveryDeps> = {}) {
  const rows = new Map<string, RegisteredSession>()
  let restoreDegraded: (agentId: string) => boolean = () => false
  const deps: DiscoveryDeps = {
    registry: {
      byRuntimeEngine: vi.fn(() => undefined),
      openProcessAgent: vi.fn(() => null),
      adoptEngine: vi.fn(() => row()),
      updateRuntimes: vi.fn(),
      updateProcessIdentity: vi.fn(),
      setBypassPermission: vi.fn(),
      setPermissionMode: vi.fn(),
      setCodexHome: vi.fn(),
      setHermesHome: vi.fn(),
      setDsh: vi.fn(),
      byAgent: vi.fn((agentId: string) => rows.get(agentId)),
      setLaunch: vi.fn(),
      setActive: vi.fn(),
      terminalAvailable: vi.fn(() => false),
      setTerminalAvailable: vi.fn(),
    } as unknown as DiscoveryDeps['registry'],
    attachDsh: vi.fn(),
    forgetSession: vi.fn(),
    announceSession: vi.fn(),
    bindObservedAgent: vi.fn(async () => {}),
    syncRecapPool: vi.fn(),
    attachSession: vi.fn(async () => true),
    invalidateTerminalControl: vi.fn(),
    input: { forget: vi.fn() },
    deviceInput: { forget: vi.fn() },
    questionWatcher: { stop: vi.fn() },
    stopHeartbeat: vi.fn(),
    retainExitedSession: vi.fn(),
    stoppedAgents: { finishResume: vi.fn() },
    restoreDegraded: (agentId) => restoreDegraded(agentId),
    terminals: { backendFor: vi.fn(() => paneBackend) },
    ...over,
  }
  return { deps, rows, handlers: createDiscoveryHandlers(deps), degrade: (only?: string) => { restoreDegraded = (agentId) => only === undefined || agentId === only } }
}

const settle = () => new Promise((done) => setTimeout(done, 0))
const grid = (name: string) => ({ grid: name, baseUrl: `http://${name}.local`, model: 'm' })

describe('discovery', () => {
  beforeEach(() => {
    vi.spyOn(console, 'log').mockImplementation(() => {})
    paneState.mockReset().mockResolvedValue('gone')
  })
  afterEach(() => vi.restoreAllMocks())

  describe('a process no row owns', () => {
    it('opens an agent for it, announces it and binds its session', async () => {
      const run = setup()
      const opened = row({ agentId: 'new' })
      vi.mocked(run.deps.registry.openProcessAgent).mockReturnValue({ entry: opened, isNew: true, evicted: null } as never)
      await run.handlers.onDiscovered(seen())
      expect(run.deps.registry.openProcessAgent).toHaveBeenCalledWith(expect.objectContaining({ engine: 'claude', primaryRuntimeKey: 'tmux:%0' }))
      expect(run.deps.announceSession).toHaveBeenCalledWith(opened)
      expect(run.deps.bindObservedAgent).toHaveBeenCalled()
      expect(run.deps.attachDsh).not.toHaveBeenCalled()
    })

    it('attaches its DSH, forgets the agent it evicted from the pane, and re-announces a launch still starting', async () => {
      const run = setup()
      const opened = row({ agentId: 'a2', dsh: 'blender' } as Partial<RegisteredSession>)
      vi.mocked(run.deps.registry.byRuntimeEngine).mockReturnValue(row({ launch: { state: 'starting' } } as Partial<RegisteredSession>))
      vi.mocked(run.deps.registry.openProcessAgent).mockReturnValue({ entry: opened, isNew: false, evicted: row({ agentId: 'old', sessionId: '' }) } as never)
      await run.handlers.onDiscovered(seen())
      expect(run.deps.attachDsh).toHaveBeenCalledWith(opened)
      expect(run.deps.forgetSession).toHaveBeenCalledWith('old', { force: true, agentId: 'old' })
      expect(run.deps.announceSession).toHaveBeenCalledWith(opened)
      vi.mocked(run.deps.registry.openProcessAgent).mockReturnValue({ entry: row(), isNew: false, evicted: row({ agentId: 'old', sessionId: 'old-s' }) } as never)
      vi.mocked(run.deps.registry.byRuntimeEngine).mockReturnValue(row({ launch: { state: 'ready' } } as Partial<RegisteredSession>))
      await run.handlers.onDiscovered(seen())
      expect(run.deps.forgetSession).toHaveBeenLastCalledWith('old-s', { force: true, agentId: 'old' })
      expect(run.deps.announceSession).toHaveBeenCalledTimes(1)
    })

    it('does nothing when the registry opens nothing', async () => {
      const run = setup()
      await run.handlers.onDiscovered(seen())
      expect(run.deps.bindObservedAgent).not.toHaveBeenCalled()
    })
  })

  describe('a row\'s own process', () => {
    it('updates the row from the live process, filling only what it does not know', async () => {
      const run = setup()
      const observed = seen({ args: 'claude --dangerously-skip-permissions', codexHome: '/codex', hermesHome: '/hermes', dsh: 'blender' } as Partial<DiscoveredTerminalAgent>)
      run.rows.set('a1', row({ dsh: 'blender' } as Partial<RegisteredSession>))
      await run.handlers.onObserved(observed, row())
      expect(run.deps.registry.updateRuntimes).toHaveBeenCalledWith('a1', observed.runtimes, 'tmux:%0')
      expect(run.deps.registry.updateProcessIdentity).toHaveBeenCalledWith('a1', observed.processIdentity, undefined, undefined)
      expect(run.deps.registry.setBypassPermission).toHaveBeenCalledWith('a1', bypassPermissionActive('claude', observed.args))
      const mode = permissionModeFromArgv('claude', observed.args)
      expect(vi.mocked(run.deps.registry.setPermissionMode).mock.calls).toEqual(mode ? [['a1', mode]] : [])
      expect(run.deps.registry.setCodexHome).toHaveBeenCalledWith('a1', '/codex')
      expect(run.deps.registry.setHermesHome).toHaveBeenCalledWith('a1', '/hermes')
      expect(run.deps.registry.setDsh).toHaveBeenCalledWith('a1', 'blender')
      expect(run.deps.attachDsh).toHaveBeenCalled()
      expect(run.deps.bindObservedAgent).toHaveBeenCalledWith(observed)
      // A row that knows them already keeps its own.
      const known = setup()
      await known.handlers.onObserved(observed, row({ permissionMode: 'plan', codexHome: '/mine', hermesHome: '/mine', dsh: 'mine' } as Partial<RegisteredSession>))
      for (const setter of ['setPermissionMode', 'setCodexHome', 'setHermesHome', 'setDsh'] as const) {
        expect(known.deps.registry[setter], setter).not.toHaveBeenCalled()
      }
    })

    it('learns the permission mode from the command line when the row has none', async () => {
      const run = setup()
      await run.handlers.onObserved(seen({ engine: 'codex', args: 'codex --dangerously-bypass-approvals-and-sandbox' } as Partial<DiscoveredTerminalAgent>), row({ engine: 'codex' } as Partial<RegisteredSession>))
      const mode = permissionModeFromArgv('codex', 'codex --dangerously-bypass-approvals-and-sandbox')
      expect(vi.mocked(run.deps.registry.setPermissionMode).mock.calls).toEqual(mode ? [['a1', mode]] : [])
      expect(mode, 'this fixture must name a mode').not.toBeNull()
    })

    // Swarm v3 (task #4215): a Swarm agent's mode is the one its person chose, or none. An agent Harness once started in
    // full mode still runs with that flag until it relaunches; read back, the relaunch would skip permissions again.
    it('never reads a Swarm agent\'s permissions off its process', async () => {
      const run = setup()
      const swarm = row({ swarmSkill: { role: 'coordinator', key: 'swarm-lead' } } as Partial<RegisteredSession>)
      await run.handlers.onObserved(seen({ args: 'claude --dangerously-skip-permissions' } as Partial<DiscoveredTerminalAgent>), swarm)
      expect(run.deps.registry.setPermissionMode).not.toHaveBeenCalled()
      expect(run.deps.registry.setBypassPermission).not.toHaveBeenCalled()
    })

    it('reads a Buddy launched in full mode back as full, never as an older Buddy\'s mode (task #2832)', () => {
      expect(permissionModeFromArgv('codex', 'codex --dangerously-bypass-approvals-and-sandbox -c tui.fullscreen_transcript=false')).toBe('full')
      expect(permissionModeFromArgv('claude', 'claude --dangerously-skip-permissions')).toBe('full')
      expect(permissionModeFromArgv('codex', 'codex --sandbox read-only')).toBe('readOnly')
    })

    it('adopts the engine someone typed into a terminal, and announces it', async () => {
      const log = vi.spyOn(console, 'log').mockImplementation(() => {})
      const run = setup()
      const adopted = row({ engine: 'claude', sessionId: '' })
      run.rows.set('a1', adopted)
      await run.handlers.onObserved(seen(), row({ engine: 'terminal' } as Partial<RegisteredSession>))
      expect(run.deps.registry.adoptEngine).toHaveBeenCalledWith('a1', 'claude', expect.anything())
      expect(run.deps.syncRecapPool).toHaveBeenCalled()
      expect(run.deps.announceSession).toHaveBeenCalledWith(adopted)
      expect(String(log.mock.calls[0][0])).toContain('terminal → claude')
    })

    it('wakes a dormant row and attaches it in the background, or puts it back to sleep if its pane is gone', async () => {
      const error = vi.spyOn(console, 'error').mockImplementation(() => {})
      const run = setup()
      const awake = row()
      run.rows.set('a1', awake)
      await run.handlers.onObserved(seen(), row({ active: false }))
      await settle()
      expect(run.deps.attachSession).toHaveBeenCalledWith(awake)
      expect(run.deps.announceSession).toHaveBeenCalledWith(awake)
      vi.mocked(run.deps.attachSession).mockResolvedValueOnce(false)
      await run.handlers.onObserved(seen(), row({ active: false }))
      await settle()
      expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', false)
      vi.mocked(run.deps.attachSession).mockRejectedValueOnce(new Error('store locked')).mockRejectedValueOnce('worse')
      await run.handlers.onObserved(seen(), row({ active: false }))
      await run.handlers.onObserved(seen(), row({ active: false }))
      await settle()
      expect(error.mock.calls.map((call) => call[1])).toEqual(['store locked', 'worse'])
      // Gone from the registry by then: nothing to wake.
      run.rows.clear()
      await run.handlers.onObserved(seen(), row({ active: false }))
      expect(run.deps.attachSession).toHaveBeenCalledTimes(4)
    })

    it('marks a launch ready once its process runs, and wakes it', async () => {
      const run = setup()
      run.rows.set('a1', row())
      await run.handlers.onObserved(seen(), row({ launch: { state: 'starting' } } as Partial<RegisteredSession>))
      expect(run.deps.registry.setLaunch).toHaveBeenCalledWith('a1', { state: 'ready' })
      expect(run.deps.attachSession).toHaveBeenCalled()
      await run.handlers.onObserved(seen(), row({ launch: { state: 'ready' } } as Partial<RegisteredSession>))
      expect(run.deps.registry.setLaunch).toHaveBeenCalledTimes(1)
    })

    it.each(['held', 'removed', 'rebound'] as const)('cannot retire or announce an attachment whose binding became %s', async state => {
      const run = setup(), awake = row()
      run.rows.set('a1', awake)
      vi.mocked(run.deps.attachSession).mockImplementationOnce(async () => {
        if (state === 'held') awake.identityHold = 'waiting for native evidence'
        if (state === 'removed') run.rows.clear()
        if (state === 'rebound') awake.sessionId = 'replacement'
        return false
      })
      await run.handlers.onObserved(seen(), row({ active: false }))
      await settle()
      expect(run.deps.registry.setActive).not.toHaveBeenCalled()
      expect(run.deps.announceSession).not.toHaveBeenCalled()
    })

    it('announces an awake agent whose grid moved, and nothing when it did not or could not be read', async () => {
      const run = setup()
      run.rows.set('a1', row())
      await run.handlers.onObserved(seen({ grid: grid('g1') } as Partial<DiscoveredTerminalAgent>), row({ grid: grid('g1') } as Partial<RegisteredSession>))
      await run.handlers.onObserved(seen(), row())
      expect(run.deps.announceSession).not.toHaveBeenCalled()
      await run.handlers.onObserved(seen({ grid: grid('g2') } as Partial<DiscoveredTerminalAgent>), row())
      expect(run.deps.announceSession).toHaveBeenCalledTimes(1)
      run.rows.clear()
      await run.handlers.onObserved(seen({ grid: grid('g3') } as Partial<DiscoveredTerminalAgent>), row())
      expect(run.deps.announceSession).toHaveBeenCalledTimes(1)
    })
  })

  describe('a row whose engine exited', () => {
    it('keeps its conversation, letting go of input, questions and the heartbeat', async () => {
      const run = setup()
      const exited = row({ resumeOnly: true } as Partial<RegisteredSession>)
      await run.handlers.onDormant(exited, 'engine exited')
      expect(run.deps.invalidateTerminalControl).toHaveBeenCalledWith('a1')
      expect(run.deps.input.forget).toHaveBeenCalledWith('a1')
      expect(run.deps.deviceInput.forget).toHaveBeenCalledWith('a1')
      expect(run.deps.questionWatcher.stop).toHaveBeenCalledWith('s1')
      expect(run.deps.stopHeartbeat).toHaveBeenCalledWith('s1')
      expect(run.deps.retainExitedSession).toHaveBeenCalledWith(exited, true)
      expect(run.deps.stoppedAgents.finishResume).toHaveBeenCalledWith('a1')
    })

    it('keeps the conversation of an agent that was not a resume, with nothing to finish', async () => {
      const run = setup()
      await run.handlers.onDormant(row(), 'engine exited')
      expect(run.deps.retainExitedSession).toHaveBeenCalledWith(row(), true)
      expect(run.deps.stoppedAgents.finishResume).not.toHaveBeenCalled()
    })

    it('leaves a dormant row alone, and puts a launch that is still starting to sleep instead', async () => {
      const run = setup()
      await run.handlers.onDormant(row({ active: false }), 'x')
      expect(run.deps.invalidateTerminalControl).not.toHaveBeenCalled()
      const starting = row({ sessionId: '', launch: { state: 'starting' } } as Partial<RegisteredSession>)
      await run.handlers.onDormant(starting, 'no process yet')
      expect(run.deps.questionWatcher.stop).not.toHaveBeenCalled()
      expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', false)
      expect(run.deps.announceSession).toHaveBeenCalledWith(starting)
      expect(run.deps.retainExitedSession).not.toHaveBeenCalled()
    })

    it('holds a failed resume while its pane may still be about to launch the engine', async () => {
      const run = setup()
      const failed = row({ resumeOnly: true, tmuxPane: '%0', runtimes: [{ backend: 'tmux', paneId: '%0' }], launch: { state: 'failed' } } as Partial<RegisteredSession>)
      await run.handlers.onDormant(failed, 'x') // the pane is gone: the reconciler's to remove
      // tmux could not be asked, as when the daemon's event loop was held: no news either way.
      paneState.mockResolvedValueOnce('unknown')
      await run.handlers.onDormant(failed, 'x')
      paneState.mockResolvedValueOnce({ dead: false, engineExit: null } as never)
      await run.handlers.onDormant(failed, 'x') // a live shell, no engine exit
      expect(run.deps.retainExitedSession).not.toHaveBeenCalled()
      paneState.mockResolvedValueOnce({ dead: true, engineExit: null } as never)
      await run.handlers.onDormant(failed, 'pane died')
      paneState.mockResolvedValueOnce({ dead: false, engineExit: 1 } as never)
      await run.handlers.onDormant(failed, 'engine exited 1')
      expect(run.deps.retainExitedSession).toHaveBeenCalledTimes(2)
      expect(run.deps.terminals.backendFor).toHaveBeenCalledWith({ backend: 'tmux', paneId: '%0' })
      expect(paneState).toHaveBeenCalledWith({ backend: 'tmux', paneId: '%0' })
    })

    it('asks a failed resume\'s own backend about its pane, never tmux about a ptyhost pane\'s id', async () => {
      const run = setup({ terminals: { backendFor: vi.fn(() => undefined) } })
      const pty = { backend: 'ptyhost' as const, instance: 'p1', paneId: '%0' }
      await run.handlers.onDormant(row({ resumeOnly: true, tmuxPane: '%0', runtimes: [pty], launch: { state: 'failed' } } as Partial<RegisteredSession>), 'x')
      expect(run.deps.terminals.backendFor).toHaveBeenCalledExactlyOnceWith(pty)
      expect(paneState).not.toHaveBeenCalled()
      expect(run.deps.retainExitedSession).not.toHaveBeenCalled()
    })

    it('holds a failed resume whose pane no configured backend can read', async () => {
      const run = setup({ terminals: { backendFor: vi.fn(() => undefined) } })
      await run.handlers.onDormant(row({ resumeOnly: true, tmuxPane: '%0', runtimes: [{ backend: 'tmux', paneId: '%0' }], launch: { state: 'failed' } } as Partial<RegisteredSession>), 'x')
      expect(run.deps.retainExitedSession).not.toHaveBeenCalled()
      expect(paneState).not.toHaveBeenCalled()
    })
  })

  it('removes a row whose pane is gone, unless restore never ran this boot', () => {
    const run = setup()
    run.handlers.onRemoved(row(), 'pane gone')
    expect(run.deps.forgetSession).toHaveBeenCalledWith('a1', { force: true })
    run.degrade()
    run.handlers.onRemoved(row(), 'pane gone')
    expect(run.deps.forgetSession).toHaveBeenCalledTimes(1)
    expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', false)
    expect(run.deps.announceSession).toHaveBeenCalled()
  })

  it('keeps only the rows restore could not look at, and retires any other whose pane is gone', () => {
    // One row restore could not survey (a `ps` that timed out at boot) used to stop every pane closed
    // outside the app from being retired, for as long as the core ran.
    const run = setup()
    run.degrade('a2')
    run.handlers.onRemoved(row(), 'pane gone')
    expect(run.deps.forgetSession).toHaveBeenCalledWith('a1', { force: true })
    run.handlers.onRemoved({ ...row(), agentId: 'a2' }, 'pane gone')
    expect(run.deps.forgetSession).toHaveBeenCalledTimes(1)
    expect(run.deps.registry.setActive).toHaveBeenCalledWith('a2', false)
  })

  it('never archives a held conversation when its waiting shell or engine is absent', async () => {
    const run = setup()
    const held = row({ launch: { state: 'held', service: 'store', detail: 'Waiting for preparation.' } })
    await run.handlers.onDormant(held, 'two engine misses')
    run.handlers.onRemoved(held, 'two missing-pane scans')
    expect(run.deps.retainExitedSession).not.toHaveBeenCalled()
    expect(run.deps.forgetSession).not.toHaveBeenCalled()
    expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', false)
    expect(run.deps.announceSession).toHaveBeenCalledWith(held)
  })

  it('records whether a row\'s terminal is available, announcing it when it becomes so', () => {
    const run = setup()
    run.handlers.onTerminalAvailability(row(), true)
    expect(run.deps.registry.setTerminalAvailable).toHaveBeenCalledWith('a1', true)
    expect(run.deps.announceSession).toHaveBeenCalledTimes(1)
    vi.mocked(run.deps.registry.terminalAvailable).mockReturnValue(true)
    run.handlers.onTerminalAvailability(row(), true)
    run.handlers.onTerminalAvailability(row(), false)
    expect(run.deps.announceSession).toHaveBeenCalledTimes(1)
  })

  describe('a shell row whose pane is live', () => {
    const shell = (over: Partial<RegisteredSession> = {}) => row({ engine: 'terminal', active: false, ...over } as Partial<RegisteredSession>)

    // A shell has no engine process, so no observation ever reactivates it after the core's start marks every row dormant:
    // its live pane, on whichever pty host serves it, is the only evidence there is.
    it('is active again, and announced as such', () => {
      const run = setup()
      const dormant = shell()
      run.rows.set(dormant.agentId, dormant)
      vi.mocked(run.deps.registry.terminalAvailable).mockReturnValue(true)
      run.handlers.onTerminalAvailability(dormant, true)
      expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', true)
      expect(run.deps.announceSession).toHaveBeenCalledTimes(1)
    })

    it('is left alone when already active, held or failed, or when its pane is not live', () => {
      const run = setup()
      for (const over of [{ active: true }, { launch: { state: 'held' } }, { launch: { state: 'failed' } }]) {
        const r = shell(over as Partial<RegisteredSession>)
        run.rows.set(r.agentId, r)
        run.handlers.onTerminalAvailability(r, true)
      }
      run.handlers.onTerminalAvailability(shell(), false)
      expect(run.deps.registry.setActive).not.toHaveBeenCalled()
    })

    it('is not reactivated for an engine row, which its process observation owns', () => {
      const run = setup()
      const engine = row({ active: false })
      run.rows.set(engine.agentId, engine)
      run.handlers.onTerminalAvailability(engine, true)
      expect(run.deps.registry.setActive).not.toHaveBeenCalled()
    })
  })
})

it('cannot promote an unadmitted external waiting pane into a live engine', async () => {
  const test = setup()
  const pending = row({ active: false, sessionId: '', externalResume: { phase: 'waiting' } as RegisteredSession['externalResume'] })
  test.rows.set(pending.agentId, pending)
  await test.handlers.onObserved(seen(), pending)
  expect(test.deps.registry.updateRuntimes).not.toHaveBeenCalled()
  expect(test.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()
  expect(test.deps.registry.setLaunch).not.toHaveBeenCalled()
  expect(test.deps.bindObservedAgent).not.toHaveBeenCalled()
})