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.

15.7 KB
Raw Blame
/**
 * The pane writer lock's edges (core/deviceInput.ts): what happens when the agent goes, the queue fills,
 * a write is cancelled or fails part way, or the pane cannot be read. Each is a write into a person's
 * pane that must either happen once or be said not to have happened.
 */
import { afterEach, describe, expect, it, vi } from 'vitest'
import { AutonomousDeviceInput, type DeviceInputDeps } from './deviceInput.js'
import { inlineSubmission } from '../testing/inlineSubmission.js'
import type { RegisteredSession } from '../lib/registry.js'
import type { TerminalActionResult } from '../lib/terminalTypes.js'

afterEach(() => vi.useRealTimers())

const claude = { agentId: 'agent', engine: 'claude' } as RegisteredSession
const codex = (cliVersion?: string) => ({ agentId: 'agent', engine: 'codex', cliVersion }) as RegisteredSession
const executed: TerminalActionResult = { state: 'succeeded', dispatch: 'executed' }

function lock(overrides: Partial<DeviceInputDeps> = {}) {
  const onDelivery = vi.fn()
  const onInputStatus = vi.fn()
  const device = new AutonomousDeviceInput({
    getSession: () => claude,
    validateRuntime: async () => true, inject: async () => executed, sendKey: async () => true,
    capture: async () => '› ', submission: inlineSubmission, acquireControl: () => () => {}, legacySubmit: vi.fn(), legacyCancel: () => false,
    onDelivery, onInputStatus, ...overrides,
  })
  const states = (deliveryId: string) => onDelivery.mock.calls.map(([event]) => event).filter((event) => event.deliveryId === deliveryId)
    .map((event) => event.reason ? `${event.state}:${event.reason}` : event.state)
  return { device, onDelivery, onInputStatus, states }
}

/** A promise and the hand that settles it. */
function held<T>() {
  let resolve!: (value: T) => void
  let reject!: (error: unknown) => void
  const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no })
  return { promise, resolve, reject }
}

describe('the pane writer lock, at its edges', () => {
  it('refuses a turn for an agent that is gone, and a queue that is full by count or by size', async () => {
    const gone = lock({ getSession: () => undefined })
    gone.device.submit('agent', 'hello', 'd0')
    expect(gone.states('d0')).toEqual(['rejected:agent_gone'])

    // The pane never comes free, so every turn waits in the queue.
    const busy = lock({ acquireControl: () => null })
    for (let i = 1; i <= 9; i++) busy.device.submit('agent', `turn ${i}`, `d${i}`)
    expect(busy.states('d8')).toEqual(['queued'])
    expect(busy.states('d9')).toEqual(['rejected:queue_full'])
    const big = lock({ acquireControl: () => null })
    big.device.submit('agent', 'x'.repeat(20 * 1024), 'b1')
    big.device.submit('agent', 'y'.repeat(5 * 1024), 'b2')
    expect(big.states('b2')).toEqual(['rejected:queue_full'])
    busy.device.forget('agent')
    big.device.forget('agent')
  })

  it('lets a queued turn expire, and forgets an agent that went while its turn waited', async () => {
    vi.useFakeTimers()
    let session: RegisteredSession | undefined = claude
    let free = false
    const f = lock({ getSession: () => session, acquireControl: () => free ? () => {} : null })
    f.device.submit('agent', 'old', 'old')
    await vi.advanceTimersByTimeAsync(6 * 60_000)
    f.device.submit('agent', 'new', 'new')
    expect(f.states('old')).toEqual(['queued', 'rejected:queue_expired'])
    session = undefined
    free = true
    await vi.advanceTimersByTimeAsync(200)
    expect(f.states('new')).toEqual(['queued', 'rejected:agent_gone'])
  })

  it('waits for a write already in the pane, then writes', async () => {
    vi.useFakeTimers()
    const f = lock()
    const legacy = held<void>()
    const writing = f.device.legacyWrite('agent', () => legacy.promise)
    f.device.submit('agent', 'after the window', 'd1')
    await vi.advanceTimersByTimeAsync(150)
    expect(f.states('d1')).toEqual(['queued'])
    legacy.resolve()
    await writing
    await vi.advanceTimersByTimeAsync(150)
    expect(f.states('d1')).toEqual(['queued', 'delivered'])
    f.device.forget('agent')
  })

  it('refuses before it writes when the agent cannot be checked, or the turn was cancelled meanwhile', async () => {
    const dead = lock({ validateRuntime: async () => false })
    dead.device.submit('agent', 'hello', 'd1')
    await vi.waitFor(() => expect(dead.states('d1')).toEqual(['queued', 'rejected:runtime_gone_pre_paste']))

    const validating = held<boolean>()
    const cancelled = lock({ validateRuntime: () => validating.promise })
    cancelled.device.submit('agent', 'hello', 'd2')
    // Cancelled while it is checked: it is the active write, not yet dispatched, so it can still be withdrawn.
    expect(cancelled.device.cancelDelivery('d2')).toBe(true)
    validating.resolve(true)
    await vi.waitFor(() => expect(cancelled.states('d2')).toEqual(['queued', 'rejected:cancelled']))
    expect(cancelled.device.cancelDelivery('nothing')).toBe(false)

    const asking = held<boolean>()
    let looking = false
    const waiting = lock({ isAwaitingUser: () => { looking = true; return asking.promise } })
    waiting.device.submit('agent', 'hello', 'd3')
    await vi.waitFor(() => expect(looking).toBe(true))
    expect(waiting.device.cancelDelivery('d3')).toBe(true)
    asking.resolve(false)
    await vi.waitFor(() => expect(waiting.states('d3')).toEqual(['queued', 'rejected:cancelled']))

    // A throw while checking, before anything was written, is a refusal too.
    const thrown = lock({ validateRuntime: async () => { throw new Error('ps failed') } })
    thrown.device.submit('agent', 'hello', 'd4')
    await vi.waitFor(() => expect(thrown.states('d4')).toEqual(['queued', 'rejected:runtime_gone_pre_paste']))
  })

  it('writes a turn into a busy Codex as steering on 0.106 and later, and as plain input before it', async () => {
    for (const [version, mode] of [['0.105.2', 'native_input'], [undefined, 'native_input'], ['1.0.0', 'steering']] as const) {
      const f = lock({ getSession: () => codex(version) })
      f.device.onTurnStarted('agent', 'already working')
      f.device.submit('agent', 'and this', 'd1')
      await vi.waitFor(() => expect(f.onInputStatus).toHaveBeenCalledWith(expect.objectContaining({ deliveryId: 'd1', mode, phase: 'submitted' })))
      f.device.forget('agent')
    }
  })

  it('writes a busy Claude Code turn into its own queue, and never claims steering for an engine retargeted after it was queued', async () => {
    for (const [engine, mode] of [['claude', 'native_queue'], ['commandcode', 'native_input'], ['codex', 'steering']] as const) {
      // Queued for a native engine; the registry row changes in place before it is typed.
      const session = codex('0.200.0')
      const f = lock({ getSession: () => session, validateRuntime: async () => { session.engine = engine; return true } })
      f.device.onTurnStarted('agent', 'already working')
      f.device.submit('agent', 'and this', 'd1')
      await vi.waitFor(() => expect(f.onInputStatus).toHaveBeenCalledWith(expect.objectContaining({ deliveryId: 'd1', mode, phase: 'submitted' })))
      f.device.forget('agent')
    }
  })

  it('reads the composer through the engine\'s worker, and takes no reading as an unreadable pane', async () => {
    vi.useFakeTimers()
    const sendKey = vi.fn(async () => true)
    // The draft is still there as the worker reads it: the one evidence-backed Enter.
    const pending = lock({ sendKey, submission: { ...inlineSubmission, read: async () => ({ draft: true, composer: true, nativeDraft: 'pending' }) } })
    pending.device.submit('agent', 'hello', 'd1')
    await vi.advanceTimersByTimeAsync(1_600)
    expect(sendKey).toHaveBeenCalledWith('agent', 'Enter')
    pending.device.forget('agent')
    for (const read of [async () => null, async () => { throw new Error('worker gone') }]) {
      sendKey.mockClear()
      const f = lock({ sendKey, submission: { ...inlineSubmission, read } })
      f.device.submit('agent', 'hello', 'd2')
      await vi.advanceTimersByTimeAsync(20_000)
      expect(sendKey).not.toHaveBeenCalled()
      expect(f.onInputStatus).toHaveBeenLastCalledWith(expect.objectContaining({ deliveryId: 'd2', phase: 'unconfirmed' }))
      f.device.forget('agent')
    }
    // The agent gone by the time the pane was read: nothing to read it for.
    let present = true
    const read = vi.fn(async () => ({ draft: false, composer: true, nativeDraft: 'clear' as const }))
    const gone = lock({ sendKey, getSession: () => present ? claude : undefined, submission: { ...inlineSubmission, read }, capture: async () => { present = false; return '› ' } })
    gone.device.submit('agent', 'hello', 'd3')
    await vi.advanceTimersByTimeAsync(1_600)
    expect(read).not.toHaveBeenCalled()
    gone.device.forget('agent')
  })

  it('drops a reading that comes back after the write was settled', async () => {
    const reading = held<{ draft: boolean; composer: boolean; nativeDraft: 'pending' } | null>()
    const sendKey = vi.fn(async () => true)
    const f = lock({ sendKey, submission: { ...inlineSubmission, read: () => reading.promise } })
    f.device.submit('agent', 'hello', 'd1')
    await vi.waitFor(() => expect(f.states('d1')).toEqual(['queued', 'delivered']))
    f.device.onTurnStarted('agent', 'hello')
    reading.resolve({ draft: true, composer: true, nativeDraft: 'pending' })
    await vi.waitFor(() => expect(f.states('d1')).toEqual(['queued', 'delivered', 'started']))
    await new Promise(resolve => setTimeout(resolve, 0))
    expect(sendKey).not.toHaveBeenCalled()
    f.device.forget('agent')
  })

  it('finishes a write whose turn began while it was being typed', async () => {
    const typing = held<TerminalActionResult>()
    const f = lock({ inject: () => typing.promise })
    f.device.submit('agent', 'hello', 'd1')
    await vi.waitFor(() => expect(f.onInputStatus).toHaveBeenCalledTimes(1))
    f.device.onTurnStarted('agent', 'hello')
    typing.resolve(executed)
    await vi.waitFor(() => expect(f.states('d1')).toEqual(['queued', 'started']))
    // The next turn is not held behind it.
    f.device.submit('agent', 'next', 'd2')
    await vi.waitFor(() => expect(f.states('d2')).toContain('delivered'))
    f.device.forget('agent')
  })

  it('says a write that failed after typing began is unknown, and looks again', async () => {
    vi.useFakeTimers()
    const f = lock({ inject: async () => { throw new Error('tmux went away') }, capture: async () => null })
    f.device.submit('agent', 'hello', 'd1')
    await vi.advanceTimersByTimeAsync(0)
    expect(f.states('d1')).toEqual(['queued', 'unknown:dispatch_ambiguous'])
    // It looks at the pane again: unreadable, it keeps looking, then says it could not confirm.
    await vi.advanceTimersByTimeAsync(20_000)
    expect(f.onInputStatus).toHaveBeenLastCalledWith(expect.objectContaining({ deliveryId: 'd1', phase: 'unconfirmed' }))
    f.device.forget('agent')

    // A write that failed but whose turn started is simply finished.
    const late = lock({ inject: async () => { late.device.onTurnStarted('agent', 'hello'); throw new Error('late') } })
    late.device.submit('agent', 'hello', 'd2')
    await vi.advanceTimersByTimeAsync(0)
    expect(late.states('d2')).toEqual(['queued', 'started'])

    // Forgotten while it was being written: nothing more is said about it.
    const typing = held<TerminalActionResult>()
    const forgotten = lock({ inject: () => typing.promise })
    forgotten.device.submit('agent', 'hello', 'd3')
    await vi.advanceTimersByTimeAsync(0)
    forgotten.device.forget('agent')
    typing.reject(new Error('gone'))
    await vi.advanceTimersByTimeAsync(0)
    expect(forgotten.states('d3')).toEqual(['queued', 'unknown:agent_gone'])
  })

  it('keeps reading a pane that cannot be read, and gives up saying so', async () => {
    vi.useFakeTimers()
    const f = lock({ capture: async () => { throw new Error('capture failed') } })
    f.device.submit('agent', 'hello', 'd1')
    await vi.advanceTimersByTimeAsync(0)
    expect(f.states('d1')).toEqual(['queued', 'delivered', 'unknown:dispatch_ambiguous'])
    await vi.advanceTimersByTimeAsync(20_000)
    expect(f.onInputStatus).toHaveBeenLastCalledWith(expect.objectContaining({ deliveryId: 'd1', phase: 'unconfirmed' }))
    f.device.forget('agent')

    // Forgotten while its pane was being read: the read's answer is not acted on.
    const reading = held<string | null>()
    const gone = lock({ capture: () => reading.promise })
    gone.device.submit('agent', 'hello', 'd2')
    await vi.advanceTimersByTimeAsync(0)
    gone.device.forget('agent')
    reading.resolve('› hello')
    await vi.advanceTimersByTimeAsync(0)
    expect(gone.states('d2')).toEqual(['queued', 'delivered', 'unknown:agent_gone'])

    // A read that fails after the turn started says nothing more.
    const failing = held<string | null>()
    const started = lock({ capture: () => failing.promise })
    started.device.submit('agent', 'hello', 'd3')
    await vi.advanceTimersByTimeAsync(0)
    started.device.onTurnStarted('agent', 'hello')
    failing.reject(new Error('late'))
    await vi.advanceTimersByTimeAsync(0)
    expect(started.states('d3')).toEqual(['queued', 'delivered', 'started'])
  })

  it('does not press Enter again while a question holds the pane', async () => {
    vi.useFakeTimers()
    const sendKey = vi.fn(async () => true)
    let asking = false
    const f = lock({ capture: async () => '› hello', sendKey, isAwaitingUser: async () => asking })
    f.device.submit('agent', 'hello', 'd1')
    await vi.advanceTimersByTimeAsync(0)
    asking = true
    await vi.advanceTimersByTimeAsync(1_600)
    expect(sendKey).not.toHaveBeenCalled()
    f.device.forget('agent')

    // Forgotten while the question was being looked for.
    const looking = held<boolean>()
    let first = true
    const g = lock({ capture: async () => '› hello', sendKey, isAwaitingUser: () => first ? (first = false, Promise.resolve(false)) : looking.promise })
    g.device.submit('agent', 'hello', 'd2')
    await vi.advanceTimersByTimeAsync(1_600)
    g.device.forget('agent')
    looking.resolve(false)
    await vi.advanceTimersByTimeAsync(0)
    expect(sendKey).not.toHaveBeenCalled()
  })

  it('stops looking at a write once its turn starts', async () => {
    vi.useFakeTimers()
    const capture = vi.fn(async () => '› hello')
    const f = lock({ capture })
    f.device.submit('agent', 'hello', 'd1')
    await vi.advanceTimersByTimeAsync(0)
    // Still in the composer when looked at: it is looked at again, until the turn starts.
    const looked = capture.mock.calls.length
    f.device.onTurnStarted('agent', 'hello')
    await vi.advanceTimersByTimeAsync(5_000)
    expect(capture.mock.calls.length).toBe(looked)
    expect(f.states('d1')).toEqual(['queued', 'delivered', 'started'])
    f.device.forget('agent')
  })

  it('looks at a write again when its turn ends before it was seen to start', async () => {
    vi.useFakeTimers()
    const capture = vi.fn(async () => '› hello')
    const f = lock({ capture })
    f.device.onTurnStarted('agent', 'something else')
    f.device.submit('agent', 'hello', 'd1')
    await vi.advanceTimersByTimeAsync(0)
    const looked = capture.mock.calls.length
    f.device.onTurnEnded('agent')
    await vi.advanceTimersByTimeAsync(1_600)
    expect(capture.mock.calls.length).toBeGreaterThan(looked)
    f.device.forget('agent')
  })

  it('withdraws a queued turn, and hands any other to the window\'s queue', () => {
    const legacyCancel = vi.fn(() => true)
    const f = lock({ acquireControl: () => null, legacyCancel })
    f.device.submit('agent', 'first', 'd1')
    f.device.submit('agent', 'second', 'd2')
    expect(f.device.cancelDelivery('d2')).toBe(true)
    expect(f.states('d2')).toEqual(['queued', 'rejected:cancelled'])
    expect(f.device.cancelDelivery('elsewhere')).toBe(true)
    expect(legacyCancel).toHaveBeenCalledWith('elsewhere')
    f.device.forget('agent')
  })
})