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.

12.7 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from '../../lib/registry.js'
import type { EngineQuestionControl, QuestionControlHost, QuestionStep } from '../../engines/facets/questionControl.js'
import { engineQuestionControlRequests } from '../../engines/worker/questionControlRequests.js'
import { QUESTION_CONTROL_CAPABILITIES, QUESTION_CONTROL_HOST, QUESTION_CONTROL_IN_FLIGHT, QUESTION_CONTROL_WAIT_MS } from '../../engines/worker/questionControlProtocol.js'
import { createQuestionControls } from './questionControls.js'

const denied = { version: 1, error: 'ANSWER_FAILED' }
const row = { number: '2', label: 'Coffee', checked: false }
const step: QuestionStep = { kind: 'select', row, enterSubmits: true }
const deferred = <T>() => { let resolve!: (value: T) => void; const promise = new Promise<T>(r => { resolve = r }); return { promise, resolve } }
function setup(engine: 'claude' | 'codex' = 'claude', isolated = true, connected = true) {
  let session = { agentId: 'agent', sessionId: 'session', engine, active: true, boundAt: 1, tmuxPane: '%1' } as RegisteredSession
  const service = `engine-${engine}`
  let token = ''
  const native: EngineQuestionControl = { apply: vi.fn(async () => true) }
  const deps = {
    handles: () => isolated, resolve: () => session, inline: vi.fn(() => native as EngineQuestionControl | undefined),
    call: vi.fn(async (_service: string, method: string, payload: Record<string, unknown>, _ms: number): Promise<Record<string, unknown>> => {
      if (payload.token) token = payload.token as string
      if (!connected) { controls.connected(service); connected = true }
      return { ...await requests[method]({ ...payload, requestId: 'core-request' }, { owner: true, local: true }), requestId: 'worker-reply' }
    }),
    key: vi.fn(async (_target: string, _key: string, allowed: () => boolean) => allowed()),
    text: vi.fn(async (_target: string, _text: string, allowed: () => boolean) => allowed()),
  }
  const controls = createQuestionControls(deps)
  const request = (action: unknown, extra: Record<string, unknown> = {}, source = service) => controls.answer(source, QUESTION_CONTROL_HOST,
    { version: 1, query: QUESTION_CONTROL_HOST, requestId: 'worker-request', token, action, ...extra })!
  const requests = engineQuestionControlRequests(engine, { load: async () => native, recycle: vi.fn(),
    query: async (query, payload) => ({ ...await controls.answer(service, query, { ...payload, query, requestId: 'worker-request' })!, requestId: 'core-reply' }) })
  if (connected) controls.connected(service)
  return { controls, deps, native, service, request, session: () => session, replace: (value: RegisteredSession) => { session = value }, port: () => controls.forSession(session)! }
}

describe('question-control authority', () => {
  beforeEach(() => vi.useFakeTimers())
  afterEach(() => vi.useRealTimers())

  it.each(['claude', 'codex'] as const)('routes an approved %s step without giving the worker terminal identity', async engine => {
    const s = setup(engine, true, false), port = s.port()
    let host!: QuestionControlHost
    s.native.apply = vi.fn(async (value, ports) => {
      host = ports
      expect(value).toEqual({ kind: 'text', row, text: 'My answer' })
      expect(value).not.toHaveProperty('session')
      expect(await host.key('2')).toBe(true)
      expect(await host.text('My answer')).toBe(true)
      expect(await host.key('Enter')).toBe(true)
      return true
    })
    expect(await port.apply({ kind: 'text', row, text: 'My answer' })).toBe(true)
    expect(await port.apply({ kind: 'text', row, text: 'My answer' })).toBe(true)
    expect(s.deps.key).toHaveBeenCalledWith('agent', 'Enter', expect.any(Function))
    expect(s.deps.call.mock.calls.filter(c => c[1] === QUESTION_CONTROL_CAPABILITIES)).toHaveLength(1)
    expect(s.deps.inline).not.toHaveBeenCalled()
    await expect(host.key('Enter')).rejects.toThrow()
    expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
  })

  it('uses the grant in explicit inline mode, refuses a missing driver, and leaves other engines alone', async () => {
    const s = setup('claude', false)
    let host!: QuestionControlHost
    s.native.apply = vi.fn(async (_step, value) => { host = value; return value.key('2') })
    expect(await s.port().apply(step)).toBe(true)
    expect(s.deps.call).not.toHaveBeenCalled()
    await expect(host.key('Enter')).rejects.toThrow()
    s.native.apply = vi.fn(async () => false)
    expect(await s.port().apply(step)).toBe(false)
    s.deps.inline.mockReturnValue(undefined)
    expect(await s.port().apply(step)).toBe(false)
    expect(s.controls.forSession({ ...s.session(), engine: 'cursor' })).toBeUndefined()
    expect(s.controls.answer(s.service, 'live', {})).toBeNull()
  })

  it.each(['version', 'engine', 'questionControl', 'extra'])('rejects an incompatible %s capability before any write', async field => {
    const s = setup()
    s.deps.call.mockResolvedValueOnce({ version: 1, engine: 'claude', questionControl: 1, [field]: 'wrong' })
    expect(await s.port().apply(step)).toBe(false)
    expect(s.native.apply).not.toHaveBeenCalled()
    expect(s.deps.inline).not.toHaveBeenCalled()
  })

  it('rejects failed, malformed and unexpected-field completion replies', async () => {
    const s = setup(), port = s.port()
    expect(await port.apply(step)).toBe(true)
    for (const reply of [{ version: 2, ok: true }, { version: 1, ok: true, extra: true }, { version: 1, error: 'ANSWER_FAILED' }, { version: 1, ok: false }]) {
      s.deps.call.mockResolvedValueOnce(reply)
      expect(await port.apply(step)).toBe(false)
    }
    expect(await port.apply({ ...step, terminal: '%9' } as any)).toBe(false)
  })

  it('binds before the first await and never resumes a pre-reconnect answer', async () => {
    const s = setup(), port = s.port()
    expect(await port.apply(step)).toBe(true)
    s.controls.disconnected(s.service); s.controls.connected(s.service)
    expect(await port.apply(step)).toBe(false)
    const fresh = s.port()
    expect(await fresh.apply(step)).toBe(true)
    s.session().sessionId = 'replacement'
    expect(await fresh.apply(step)).toBe(false)
  })

  it('refuses other services and extra authority, and permits only the reviewed text', async () => {
    const s = setup()
    s.native.apply = vi.fn(async () => {
      expect(await s.request({ kind: 'key', key: '2' }, {}, 'engine-codex')).toEqual(denied)
      expect(await s.request({ kind: 'key', key: '2' }, { token: 'guess' })).toEqual(denied)
      expect(await s.request({ kind: 'key', key: '2', target: '%9' })).toEqual(denied)
      expect(await s.request({ kind: 'key', key: '2' }, { extra: true })).toEqual(denied)
      s.controls.disconnected('engine-codex') // another engine cannot revoke this answer
      expect(await s.request({ kind: 'key', key: '2' })).toEqual({ version: 1, value: true })
      expect(await s.request({ kind: 'text', text: 'unreviewed answer' })).toEqual(denied)
      expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
      return true
    })
    expect(await s.port().apply(step)).toBe(false)
    expect(s.deps.text).not.toHaveBeenCalled()
  })

  it('enters the approved text once: the same text again is refused and revokes the step', async () => {
    const s = setup()
    s.native.apply = vi.fn(async () => {
      expect(await s.request({ kind: 'key', key: '2' })).toEqual({ version: 1, value: true })
      expect(await s.request({ kind: 'text', text: 'My answer' })).toEqual({ version: 1, value: true })
      expect(await s.request({ kind: 'text', text: 'My answer' })).toEqual(denied)
      expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
      return true
    })
    expect(await s.port().apply({ kind: 'text', row, text: 'My answer' })).toBe(false)
    expect(s.deps.text).toHaveBeenCalledOnce()
  })

  it('says why a step failed: refused when it typed nothing, uncertain once a write had gone out', async () => {
    const s = setup(), port = s.port()
    expect(await port.apply(step)).toBe(true)
    expect(port.failure!()).toBeUndefined()
    s.native.apply = vi.fn(async () => false)
    expect(await port.apply(step)).toBe(false)
    expect(port.failure!()).toBe('refused')
    s.native.apply = vi.fn(async () => {
      expect(await s.request({ kind: 'key', key: '2' })).toEqual({ version: 1, value: true })
      throw new Error('worker killed after the key')
    })
    expect(await port.apply(step)).toBe(false)
    expect(port.failure!()).toBe('uncertain')
    // A write the terminal refused was still handed to it.
    s.deps.key.mockResolvedValueOnce(false)
    s.native.apply = vi.fn(async () => { await s.request({ kind: 'key', key: '2' }); return true })
    expect(await port.apply(step)).toBe(false)
    expect(port.failure!()).toBe('uncertain')
    // A step refused by the broker before it was admitted typed nothing.
    expect(await port.apply({ kind: 'select', row: { ...row, number: 'C-c' } } as never)).toBe(false)
    expect(port.failure!()).toBe('refused')
  })

  it('refuses a step past its engine\'s capacity as typing nothing', async () => {
    const s = setup(), gate = deferred<boolean>()
    s.native.apply = vi.fn(() => gate.promise)
    const ports = Array.from({ length: QUESTION_CONTROL_IN_FLIGHT }, () => s.port())
    const held = ports.map(port => port.apply(step))
    await vi.waitFor(() => expect(s.native.apply).toHaveBeenCalledTimes(QUESTION_CONTROL_IN_FLIGHT))
    const extra = s.port()
    expect(await extra.apply(step)).toBe(false)
    expect(extra.failure!()).toBe('refused')
    gate.resolve(true)
    expect(await Promise.all(held)).toEqual(Array(QUESTION_CONTROL_IN_FLIGHT).fill(true))
  })

  it('limits a granted step and revokes it after excess keys', async () => {
    const s = setup()
    s.native.apply = vi.fn(async () => {
      for (let i = 0; i < 128; i++) expect(await s.request({ kind: 'key', key: 'Down' })).toHaveProperty('value', true)
      expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
      return true
    })
    expect(await s.port().apply(step)).toBe(false)
  })

  it('refuses the first effect if the registered conversation changed after admission', async () => {
    const s = setup()
    s.native.apply = vi.fn(async () => {
      s.session().sessionId = 'replacement'
      expect(await s.request({ kind: 'key', key: '2' })).toEqual(denied)
      return true
    })
    expect(await s.port().apply(step)).toBe(false)
    expect(s.deps.key).not.toHaveBeenCalled()
  })

  it.each(['failed', 'throw', 'malformed'] as const)('revokes all later keys after a %s terminal write', async failure => {
    const s = setup()
    if (failure === 'failed') s.deps.key.mockResolvedValueOnce(false)
    else if (failure === 'throw') s.deps.key.mockRejectedValueOnce(new Error('gone'))
    else s.deps.key.mockResolvedValueOnce('yes' as any)
    s.native.apply = vi.fn(async () => {
      expect(await s.request({ kind: 'key', key: '2' })).toEqual(failure === 'failed' ? { version: 1, value: false } : denied)
      expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
      return true
    })
    expect(await s.port().apply(step)).toBe(false)
    expect(s.deps.key).toHaveBeenCalledOnce()
  })

  it.each(['disconnect', 'rebind', 'overlap', 'completed', 'timeout'] as const)('revokes queued effects on %s', async reason => {
    const s = setup(), gate = deferred<void>(), entered = deferred<void>(), effects: string[] = []
    let permitted!: () => boolean
    s.deps.key.mockImplementation(async (_target, key, allowed) => {
      permitted = allowed; entered.resolve(); await gate.promise
      if (allowed()) effects.push(key)
      return allowed()
    })
    s.deps.call.mockImplementation(async (_service, method, payload) => {
      if (method === QUESTION_CONTROL_CAPABILITIES) return { version: 1, questionControl: 1, engine: 'claude' }
      const effect = s.controls.answer(s.service, QUESTION_CONTROL_HOST, { version: 1, token: payload.token, action: { kind: 'key', key: 'Enter' } })!
      if (reason === 'completed') { void effect; return { version: 1, ok: true } }
      if (reason === 'overlap') expect(await s.controls.answer(s.service, QUESTION_CONTROL_HOST, { version: 1, token: payload.token, action: { kind: 'key', key: '2' } })).toEqual(denied)
      await effect
      return { version: 1, ok: true }
    })
    const outcome = s.port().apply(step)
    await entered.promise
    if (reason === 'disconnect') s.controls.disconnected(s.service)
    if (reason === 'rebind') s.session().boundAt = 2
    if (reason === 'timeout') await vi.advanceTimersByTimeAsync(QUESTION_CONTROL_WAIT_MS + 1)
    if (reason === 'completed') await outcome
    expect(permitted()).toBe(false)
    gate.resolve()
    expect(await outcome).toBe(false)
    expect(effects).toEqual([])
  })
})