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.

16.7 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from '../../lib/registry.js'
import { encodeRuntimeProfile } from '../../engines/kit/runtime.js'
import { RuntimeProfileControlError, type EngineModelControl, type ModelControlHost } from '../../engines/facets/modelControl.js'
import { engineModelControlRequests } from '../../engines/worker/modelControlRequests.js'
import { MODEL_CONTROL_APPLY, MODEL_CONTROL_CAPABILITIES, MODEL_CONTROL_HOST, MODEL_CONTROL_WAIT_MS, MODEL_CONTROL_CHECK_MS } from '../../engines/worker/modelControlProtocol.js'
import { createModelControls } from './modelControls.js'

const state = { model: null, effort: null, cliVersion: null, observedAt: null, mode: 'default' as const }
const denied = { version: 1, error: 'BUSY' }
const catalog = [{ slug: 'next', displayName: 'Next', listed: true, defaultEffort: 'high', efforts: ['high'] }]
const deferred = <T>() => { let resolve!: (value: T) => void; const promise = new Promise<T>(yes => { resolve = yes }); return { promise, resolve } }
function setup(engine: 'claude' | 'codex' = 'claude', isolated = true, connected = true) {
  let session: RegisteredSession | undefined = {
    agentId: 'agent', sessionId: 'session', engine, model: 'old', cliVersion: '1.0.0', cwd: '/tmp', transcriptPath: '/tmp/session',
    active: true, registeredAt: 1, boundAt: 1, tmuxPane: '%1', runtimes: [], primaryRuntimeKey: 'tmux:%1', processIdentity: null,
  } as unknown as RegisteredSession
  const target = { sessionId: 'agent', engine, model: 'next', effort: 'high', id: '' }
  target.id = encodeRuntimeProfile(target)
  const input = { target, current: null, options: [{ id: target.id, displayName: 'Next' }] }
  const check = { stage: 'target' as const, target, state }
  const native: EngineModelControl = { validate: vi.fn(async () => {}), apply: vi.fn(async () => {}) }
  const service = `engine-${engine}`
  let token = ''
  const asks: Record<string, unknown>[] = []
  const deps = {
    handles: () => isolated, inline: vi.fn(() => native as EngineModelControl | undefined), resolve: () => session,
    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
      asks.push(payload)
      if (!connected) { controls.connected(service); connected = true }
      // The real link adds requestId. Keep that metadata in this fixture.
      return { ...await requests[method]({ ...payload, requestId: 'core-request' }, { owner: true, local: true }), requestId: 'routed-reply' }
    }),
    catalog: vi.fn(async () => catalog), capture: vi.fn(async () => 'screen' as string | null),
    text: vi.fn(async (_id: string, _text: string, allowed: () => boolean) => allowed()),
    key: vi.fn(async (_id: string, _key: string, allowed: () => boolean) => allowed()),
    waitForModel: vi.fn(async () => true), waitForProfile: vi.fn(async () => false), confirmEffort: vi.fn(),
  }
  const controls = createModelControls(deps)
  const request = (action: unknown, extra: Record<string, unknown> = {}, source = service) => controls.answer(source, MODEL_CONTROL_HOST,
    { version: 1, token, action, query: MODEL_CONTROL_HOST, requestId: 'worker-query', ...extra })!
  const requests = engineModelControlRequests(engine, { load: async () => native, recycle: vi.fn(),
    query: (query, payload) => controls.answer(service, query, { ...payload, query, requestId: 'worker-query' })! })
  if (connected) controls.connected(service)
  return { controls, deps, target, check, input, native, asks, service, request,
    session: () => session!, replace: (value?: RegisteredSession) => { session = value },
    port: () => controls.forSession(session!)!,
  }
}

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

  it.each(['claude', 'codex'] as const)('routes %s validation and each effect through the real private envelopes', async engine => {
    const s = setup(engine, true, false), p = s.port()
    let owned: ModelControlHost | undefined
    s.native.apply = vi.fn(async (input, host) => {
      owned = host
      expect(input.session).not.toHaveProperty('tmuxPane')
      expect(input.catalog).toEqual(catalog)
      expect(await host.catalog()).toEqual(catalog)
      expect(await host.capture(80)).toBe('screen')
      expect(await host.text('/model next')).toBe(true)
      expect(await host.key('Enter')).toBe(true)
      expect(await host.waitForModel(1200)).toBe(true)
      expect(await host.waitForProfile(8000)).toBe(false)
      await host.confirmEffort('high')
    })
    await p.validate(s.check)
    await p.validate({ ...s.check, stage: 'scope', pane: { idle: true, draft: false, dialog: false, plan: false } })
    await p.apply(s.input)
    expect(s.deps.catalog).toHaveBeenCalledTimes(2) // preflight + the explicit refresh
    expect(s.deps.confirmEffort).toHaveBeenCalledWith('session', 'high')
    expect(s.deps.text).toHaveBeenCalledWith('agent', '/model next', expect.any(Function))
    expect(s.deps.inline).not.toHaveBeenCalled()
    expect(s.deps.call.mock.calls.filter(c => c[1] === MODEL_CONTROL_CAPABILITIES)).toHaveLength(1)
    await expect(owned!.key('Escape')).rejects.toMatchObject({ code: 'BUSY' })
    expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
  })

  it('uses the same revocable broker in explicit inline mode, and leaves other engines alone', async () => {
    const s = setup('claude', false), p = s.port()
    let host!: ModelControlHost
    s.native.apply = vi.fn(async (_input, value) => { host = value; await value.key('Enter') })
    await p.validate(s.check)
    await p.apply(s.input)
    expect(s.deps.call).not.toHaveBeenCalled()
    await expect(host.text('/model late')).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.controls.forSession({ ...s.session(), engine: 'cursor' })).toBeUndefined()
    expect(s.controls.answer(s.service, 'live', {})).toBeNull()
    s.controls.connected('other'); s.controls.disconnected('other')
    s.deps.inline.mockReturnValue(undefined)
    await expect(s.port().validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    await expect(s.port().apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
  })

  it('rejects an inline result after replacement and leaves other engines’ grants intact', async () => {
    const s = setup('claude', false)
    s.native.apply = vi.fn(async (_input, host) => {
      s.controls.disconnected('engine-codex')
      expect(await host.key('Enter')).toBe(true)
    })
    await s.port().apply(s.input)
    s.native.validate = vi.fn(async () => { s.session().boundAt = 2 })
    await expect(s.port().validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
  })

  it('preserves engine refusal codes and contains unexpected exceptions', async () => {
    const s = setup(), p = s.port()
    s.native.validate = vi.fn(async () => { throw new RuntimeProfileControlError('EFFORT_UNSUPPORTED') })
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'EFFORT_UNSUPPORTED' })
    s.deps.call.mockRejectedValueOnce(new Error('broken pipe'))
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    s.deps.call.mockResolvedValueOnce({ version: 1, error: 'UNKNOWN' })
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    s.deps.call.mockResolvedValueOnce({ version: 1, ok: false })
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    s.deps.call.mockResolvedValueOnce({ version: 2, ok: true })
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.deps.inline).not.toHaveBeenCalled()
  })

  it.each(['version', 'modelControl', 'engine'])('rejects an incompatible capability %s without an inline fallback', async field => {
    const s = setup()
    s.deps.call.mockResolvedValueOnce({ version: 1, modelControl: 1, engine: 'claude', [field]: 'wrong' })
    await expect(s.port().validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.native.validate).not.toHaveBeenCalled()
    expect(s.deps.inline).not.toHaveBeenCalled()
  })

  it.each(['capability', 'validation', 'apply'] as const)('rejects unexpected fields in a worker %s reply', async phase => {
    const s = setup(), p = s.port()
    if (phase !== 'capability') await p.validate(s.check)
    s.deps.call.mockResolvedValueOnce({ version: 1, ...(phase === 'capability' ? { modelControl: 1, engine: 'claude' } : { ok: true }), terminal: '%9' })
    await expect(phase === 'apply' ? p.apply(s.input) : p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.deps.inline).not.toHaveBeenCalled()
    expect(s.deps.key).not.toHaveBeenCalled()
  })

  it('fences in-place rebinding during catalog reads and before any request starts', async () => {
    const s = setup(), p = s.port()
    s.deps.catalog.mockImplementationOnce(async () => { s.session().sessionId = 'replacement'; return catalog })
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.native.validate).not.toHaveBeenCalled()
    await expect(p.apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
    s.replace()
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
  })

  it('does not resume UI intent after a worker reconnect or while disconnected', async () => {
    const s = setup(), p = s.port()
    await p.validate(s.check)
    s.controls.disconnected(s.service)
    await expect(p.apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
    s.controls.connected(s.service)
    await expect(p.apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
    await s.port().apply(s.input)
    await expect(p.apply(s.input)).rejects.toMatchObject({ code: 'BUSY' }) // new worker's capability cache cannot rescue an old intent
    s.controls.connected(s.service) // replacement connection, without an observed close
    await expect(p.validate(s.check)).rejects.toMatchObject({ code: 'BUSY' })
  })

  it('rejects invalid snapshots before native interpretation', async () => {
    const s = setup(), p = s.port()
    await expect(p.validate({ ...s.check, target: { ...s.target, model: 'other' } })).rejects.toMatchObject({ code: 'BUSY' })
    await expect(p.apply({ ...s.input, target: { ...s.target, engine: 'codex' } })).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.native.apply).not.toHaveBeenCalled()
    expect(s.native.validate).not.toHaveBeenCalled()
  })

  it('bounds hung startup and refuses overflow without queuing a later UI action', async () => {
    const s = setup()
    s.deps.call.mockImplementation(() => new Promise(() => {}))
    const results = Array.from({ length: 4 }, () => s.port().validate(s.check).catch(e => e.code))
    await expect(s.port().apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
    await vi.advanceTimersByTimeAsync(MODEL_CONTROL_CHECK_MS + 1)
    expect(await Promise.all(results)).toEqual(['BUSY', 'BUSY', 'BUSY', 'BUSY'])
    expect(s.deps.call).toHaveBeenCalledTimes(4)
    expect(s.deps.key).not.toHaveBeenCalled()
  })

  it.each(['timeout', 'disconnect', 'rebind', 'completed'] as const)('revokes delayed terminal validation on %s', async reason => {
    const s = setup(), p = s.port(), dispatched: string[] = [], done = deferred<void>(), started = deferred<void>()
    let permitted!: () => boolean
    s.deps.key.mockImplementation(async (_id, key, allowed) => {
      permitted = allowed; started.resolve()
      await done.promise
      if (allowed()) dispatched.push(key)
      return allowed()
    })
    s.deps.call.mockImplementation(async (_service, method, payload) => {
      if (method === MODEL_CONTROL_CAPABILITIES) return { version: 1, modelControl: 1, engine: 'claude' }
      const answer = s.controls.answer(s.service, MODEL_CONTROL_HOST, { version: 1, token: payload.token, action: { kind: 'key', key: 'Enter' } })!
      if (reason === 'completed') { void answer; return { version: 1, ok: true } }
      await answer
      return { version: 1, ok: true }
    })
    const outcome = p.apply(s.input).then(() => 'ok', e => e.code)
    await started.promise
    if (reason === 'timeout') await vi.advanceTimersByTimeAsync(MODEL_CONTROL_WAIT_MS + 1)
    if (reason === 'disconnect') s.controls.disconnected(s.service)
    if (reason === 'rebind') s.session().processIdentity = { pid: 999, startTime: 'new' } as any
    if (reason === 'completed') await outcome
    expect(permitted()).toBe(false)
    done.resolve()
    expect(await outcome).toBe('BUSY')
    expect(dispatched).toEqual([])
  })

  it('bounds the complete operation even when the worker never answers, then denies its late query', async () => {
    const s = setup(), p = s.port(), entered = deferred<void>()
    await p.validate(s.check)
    let payload: Record<string, unknown> = {}
    s.deps.call.mockImplementation(async (_service, _method, value) => { payload = value; entered.resolve(); return new Promise(() => {}) })
    const result = p.apply(s.input).catch(e => e.code)
    await entered.promise
    await vi.advanceTimersByTimeAsync(MODEL_CONTROL_WAIT_MS + 1)
    expect(await result).toBe('BUSY')
    expect(await s.controls.answer(s.service, MODEL_CONTROL_HOST, { version: 1, token: payload.token, action: { kind: 'key', key: 'Enter' } })).toEqual(denied)
  })

  it('does not grant other services, targets, operations or effects without an active request', async () => {
    const s = setup()
    expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
    s.native.apply = vi.fn(async () => {
      expect(await s.request({ kind: 'key', key: 'Enter' }, {}, 'engine-codex')).toEqual(denied)
      expect(await s.request({ kind: 'key', key: 'Enter' }, { token: 'guess' })).toEqual(denied)
      for (const action of [{ kind: 'key', key: 'C-c' }, { kind: 'text', text: '/model next\nother' }, { kind: 'capture', lines: 101 }, { kind: 'key', key: 'Enter', target: '%9' }]) {
        expect(await s.request(action)).toEqual(denied)
      }
      expect(await s.request({ kind: 'key', key: 'Enter' }, { extra: true })).toEqual(denied)
      expect(s.deps.key).not.toHaveBeenCalled()
      expect(await s.request({ kind: 'confirmEffort', effort: 'ultra' })).toEqual(denied)
      expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
    })
    await expect(s.port().apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.deps.confirmEffort).not.toHaveBeenCalled()
  })

  it.each(['query', 'write'] as const)('limits the %s budget for one granted control', async kind => {
    const s = setup()
    s.native.apply = vi.fn(async () => {
      const action = kind === 'query' ? { kind: 'capture', lines: 100 } : { kind: 'key', key: 'Enter' }
      for (let i = 0; i < (kind === 'query' ? 128 : 32); i++) expect(await s.request(action)).not.toHaveProperty('error')
      expect(await s.request(action)).toEqual(denied)
      expect(await s.request({ kind: 'key', key: 'Escape' })).toEqual(denied)
    })
    await expect(s.port().apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
  })

  it('revokes overlapping host requests before the delayed effect can dispatch', async () => {
    const s = setup(), effect = deferred<void>()
    s.deps.key.mockImplementation(async (_id, _key, allowed) => { await effect.promise; return allowed() })
    s.native.apply = vi.fn(async () => {
      const first = s.request({ kind: 'key', key: 'Enter' })
      expect(await s.request({ kind: 'capture', lines: 10 })).toEqual(denied)
      effect.resolve()
      expect(await first).toEqual(denied)
    })
    await expect(s.port().apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
  })

  it.each(['throw', 'oversize'] as const)('contains a %s from the host and revokes subsequent effects', async kind => {
    const s = setup()
    if (kind === 'throw') s.deps.capture.mockRejectedValueOnce(new Error('gone'))
    else s.deps.capture.mockResolvedValueOnce('x'.repeat(256 * 1024 + 1))
    s.native.apply = vi.fn(async () => {
      expect(await s.request({ kind: 'capture', lines: 10 })).toEqual(denied)
      expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
    })
    await expect(s.port().apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
  })

  it('bounds the aggregate catalog reply even when every entry fits, then revokes the grant', async () => {
    const s = setup()
    s.deps.catalog.mockResolvedValueOnce(Array.from({ length: 512 }, (_, i) => ({
      ...catalog[0], slug: `model-${i}`, displayName: 'x'.repeat(2000), efforts: ['high', 'x'.repeat(2000)],
    })))
    s.native.apply = vi.fn(async () => {
      expect(await s.request({ kind: 'catalog' })).toEqual(denied)
      expect(await s.request({ kind: 'key', key: 'Enter' })).toEqual(denied)
    })
    await expect(s.port().apply(s.input)).rejects.toMatchObject({ code: 'BUSY' })
    expect(s.deps.key).not.toHaveBeenCalled()
  })
})