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.

11.7 KB
Raw Blame
import { expect, it, vi } from 'vitest'
import { admission, quotaOf, quotaUnknownReason, readCapabilities, START_REQUIREMENTS, startRequirements, USED_UP_WINDOW } from './capacity.js'
const requirements = { memoryBytes: 100, diskBytes: 200, maxCpuPercent: 80, tools: ['git'], devices: ['/dev/test'], quotaRequired: false }
it('uses the destination filesystem and reports missing tools/devices without executing commands', async () => {
  const deps = { resources: vi.fn(async () => ({ cpuPercent: 25, memoryTotalBytes: 1000, memoryUsedBytes: 300 })),
    disk: vi.fn(async () => ({ freeBytes: 500, volume: 'volume', path: '/fixture/repo' })), tool: vi.fn(async () => ({ status: 'available' as const })), device: vi.fn(async () => true) }
  const capacity = await readCapabilities({ cwd: '/fixture/repo', tools: ['git'], devices: ['/dev/test'] }, deps)
  expect(deps.disk).toHaveBeenCalledWith('/fixture/repo', false)
  // Which engines this daemon launches with a model: a daemon without the field gets the switch after the start.
  expect(capacity).toMatchObject({ ok: true, launchModel: ['claude'] })
  expect(admission(capacity, { installed: true }, quotaOf({}, 'codex', false), requirements)).toMatchObject({ allowed: true, unknown: ['Subscription allowance is unknown for this account.'] })
  deps.disk.mockRejectedValueOnce(new Error('not mounted'))
  const missing = await readCapabilities({ cwd: '/fixture/repo', tools: [], devices: [] }, deps)
  expect(admission(missing, { installed: true }, quotaOf({}, 'codex', false), requirements)).toMatchObject({ allowed: false })
  expect(await readCapabilities({ cwd: '/fixture', tools: ['git; whoami'] }, deps)).toMatchObject({ error: 'INVALID_REQUEST' })
  expect(deps.tool).toHaveBeenCalledTimes(1)
})
it('names a Codex window by its length, so an account with only its weekly window reads as weekly', () => {
  const reading = (rate_limit: unknown) => ({ providers: [{ provider: 'codex', outcome: 'answered', httpStatus: 200, body: { rate_limit } }] })
  expect(quotaOf(reading({ primary_window: { used_percent: 19, reset_at: 9, limit_window_seconds: 604800 }, secondary_window: null }), 'codex', false).windows)
    .toEqual([{ usedPercent: 19, resetsAt: 9, name: 'weekly' }])
  expect(quotaOf(reading({ primary_window: { used_percent: 5, reset_at: 1, limit_window_seconds: 18000 }, secondary_window: { used_percent: 9, reset_at: 2, limit_window_seconds: 604800 } }), 'codex', false).windows)
    .toEqual([{ usedPercent: 5, resetsAt: 1, name: '5-hour' }, { usedPercent: 9, resetsAt: 2, name: 'weekly' }])
  // Two windows of one length keep the first; a length that is not a number falls back to the position.
  expect(quotaOf(reading({ primary_window: { used_percent: 5, limit_window_seconds: 604800 }, secondary_window: { used_percent: 9, limit_window_seconds: 604800 } }), 'codex', false).windows)
    .toEqual([{ usedPercent: 5, resetsAt: null, name: 'weekly' }])
  expect(quotaOf(reading({ primary_window: { used_percent: 5, limit_window_seconds: 'x' } }), 'codex', false).windows)
    .toEqual([{ usedPercent: 5, resetsAt: null, name: '5-hour' }])
})
it('keeps unknown quota distinct from unused quota and honors all limiting windows', () => {
  const input = { providers: [{ provider: 'codex', account: 'opaque', email: '[email protected]', outcome: 'answered', httpStatus: 200,
    body: { rate_limit: { primary_window: { used_percent: 10, reset_at: 1000 }, secondary_window: { used_percent: 100, reset_at: 2000 } } } }] }
  const quota = quotaOf(input, 'codex', false)
  expect(quota).toEqual({ known: true, account: 'opaque', windows: [{ usedPercent: 10, resetsAt: 1000, name: '5-hour' }, { usedPercent: 100, resetsAt: 2000, name: 'weekly' }] })
  expect(quotaOf(input, 'codex', true)).toMatchObject({ known: false, account: null })
  const capacity = { resources: { cpuPercent: 95, memoryTotalBytes: 1000, memoryUsedBytes: 950, projectDiskFreeBytes: 10 }, tools: {}, devices: {} }
  const result = admission(capacity, { installed: true }, quota, requirements)
  expect(result.allowed).toBe(false)
  // CPU, memory, disk, the tool and the device; the used-up weekly window is information (project instructions, phase 4).
  expect(result.reasons).toHaveLength(5)
  expect(result.unknown).toContain(USED_UP_WINDOW)
  expect(admission({}, { installed: true, signedIn: false }, quotaOf({}, 'codex', false), requirements).reasons).not.toContain('The selected agent engine is not signed in on this machine.')
  expect(admission({}, {}, quotaOf({}, 'claude', false), { ...requirements, quotaRequired: true }).reasons).toContain('The requested subscription allowance could not be verified.')
})
it('distinguishes a missing tool from a failed probe and keeps the failure detail', async () => {
  const deps = { resources: vi.fn(async () => ({ cpuPercent: 10, memoryTotalBytes: 1000, memoryUsedBytes: 100 })),
    disk: vi.fn(async () => ({ freeBytes: 500, volume: 'volume', path: '/fixture/repo' })),
    tool: vi.fn(async () => ({ status: 'missing' as const })), device: vi.fn(async () => true) }
  const missing = await readCapabilities({ cwd: '/fixture/repo', tools: ['git'] }, deps)
  expect(admission(missing, { installed: true }, quotaOf({}, 'codex', false), { ...requirements, devices: [] }).reasons)
    .toContain('Required tool missing: git.')

  deps.tool.mockRejectedValueOnce(new Error('interactive shell timed out'))
  const unverified = await readCapabilities({ cwd: '/fixture/repo', tools: ['git'] }, deps)
  expect(unverified.tools).toEqual({})
  expect(unverified.toolProbeErrors).toEqual({ git: 'interactive shell timed out' })
  expect(admission(unverified, { installed: true }, quotaOf({}, 'codex', false), { ...requirements, devices: [] }).reasons)
    .toEqual(expect.arrayContaining([expect.stringMatching(/Required tool not verified: git.*interactive shell timed out/)]))
})
it('says how much memory is free and how much a start needs, in GiB', () => {
  const GiB = 1024 ** 3
  const capacity = { resources: { cpuPercent: 10, memoryTotalBytes: 32 * GiB, memoryUsedBytes: 32 * GiB - 1.85 * GiB, projectDiskFreeBytes: 500 }, tools: { git: true }, devices: {} }
  expect(admission(capacity, { installed: true }, quotaOf({}, 'codex', false), { ...requirements, memoryBytes: 2 * GiB, devices: [] }).reasons)
    .toEqual(['Not enough free memory: 1.8 GiB free, 2 GiB needed.'])
})

// Ken's MacBook Pro showed no Claude allowance while Claude agents ran there (2026-10-28). Every way the reading can fail
// now says why, in words that name no account, token or plan.
it('says why an allowance is unknown, for each way its reading fails', () => {
  const reply = (claude: Record<string, unknown>) => ({ providers: [{ provider: 'claude', account: null, source: 'cli', ...claude }] })
  expect(quotaUnknownReason({}, 'claude')).toBe('The allowance reader on this machine did not answer.')
  expect(quotaUnknownReason({ error: 'USAGE_READ_FAILED' }, 'claude')).toBe('The allowance reader on this machine did not answer.')
  expect(quotaUnknownReason(reply({ outcome: 'signedOut' }), 'claude')).toBe('No subscription sign-in is stored on this machine.')
  // The CLI's own report says why there is none (services/usage.ts): that sentence is the reason.
  const notYet = 'Claude Code has not reported its allowance on this machine yet: it does after its first reply in a session Harness started.'
  expect(quotaUnknownReason(reply({ outcome: 'unreachable', message: notYet }), 'claude')).toBe(notYet)
  expect(quotaUnknownReason(reply({ outcome: 'unreachable', message: '' }), 'claude')).toBe('Anthropic could not be reached.')
  expect(quotaUnknownReason(reply({ outcome: 'unreachable' }), 'claude')).toBe('Anthropic could not be reached.')
  expect(quotaUnknownReason(reply({ outcome: 'answered', httpStatus: 429, body: { error: {} } }), 'claude'))
    .toBe('Anthropic is limiting how often the allowance can be read.')
  expect(quotaUnknownReason(reply({ outcome: 'answered', httpStatus: 503 }), 'claude')).toBe('Anthropic answered with an error (HTTP 503).')
  expect(quotaUnknownReason(reply({ outcome: 'answered', httpStatus: 200, body: { five_hour: null } }), 'claude'))
    .toBe('Anthropic answered without usage windows.')
  expect(quotaUnknownReason({ providers: [{ provider: 'codex', outcome: 'unreachable' }] }, 'codex')).toBe('OpenAI could not be reached.')
  expect(quotaUnknownReason({ providers: [{ provider: 'codex', outcome: 'unreachable', message: 'Codex did not answer when asked for its allowance on this machine.' }] }, 'codex'))
    .toBe('Codex did not answer when asked for its allowance on this machine.')
  expect(quotaUnknownReason({ providers: [{ provider: 'codex', outcome: 'signedOut' }] }, 'codex')).toBe('No subscription sign-in is stored on this machine.')
  // Nothing reads a stored sign-in any more, so nothing says one was refused or has expired.
  for (const said of [quotaUnknownReason(reply({ outcome: 'answered', httpStatus: 401 }), 'claude'),
    quotaUnknownReason(reply({ outcome: 'answered', httpStatus: 403 }), 'claude'),
    quotaUnknownReason(reply({ outcome: 'signedOut', message: 'Claude session expired — run claude to sign in again' }), 'claude')]) {
    expect(said).not.toMatch(/stored sign-in|expired/)
  }
  // A readable allowance has no reason.
  expect(quotaUnknownReason(reply({ outcome: 'answered', httpStatus: 200, body: { five_hour: { utilization: 5 } } }), 'claude')).toBeNull()
})
it('admits a Product Manager, Buddy or template start on a busy CPU, as a routed Builder start, while memory, disk and pressure still refuse (Diego, 10-30)', () => {
  const GiB = 1024 ** 3
  // What the backend sends for a PM and a Buddy (leadStart.ts LEAD_REQUIREMENTS, buddies.ts BUDDY_REQUIREMENTS).
  const pmOrBuddy = { memoryBytes: 2 * GiB, diskBytes: GiB, maxCpuPercent: 100, tools: ['git'], devices: [], quotaRequired: false }
  const busy = { resources: { cpuPercent: 91.4, memoryTotalBytes: 32 * GiB, memoryUsedBytes: 16 * GiB, projectDiskFreeBytes: 100 * GiB }, tools: { git: true }, devices: {} }
  for (const wanted of [pmOrBuddy, START_REQUIREMENTS, startRequirements({ tools: [], devices: [] })]) {
    expect(admission(busy, { installed: true }, quotaOf({}, 'claude', false), wanted)).toMatchObject({ allowed: true, reasons: [] })
    // An unknown CPU reading does not refuse either; memory, disk and critical pressure still do.
    expect(admission({ ...busy, resources: { ...busy.resources, cpuPercent: null } }, { installed: true }, quotaOf({}, 'claude', false), wanted).allowed).toBe(true)
    expect(admission({ ...busy, resources: { ...busy.resources, memoryUsedBytes: 31 * GiB } }, { installed: true }, quotaOf({}, 'claude', false), wanted).reasons)
      .toEqual([expect.stringMatching(/memory/i)])
    expect(admission({ ...busy, resources: { ...busy.resources, projectDiskFreeBytes: 1 } }, { installed: true }, quotaOf({}, 'claude', false), wanted).reasons)
      .toEqual([expect.stringMatching(/Project disk space/)])
    expect(admission({ ...busy, resources: { ...busy.resources, memoryPressure: 'critical' } }, { installed: true }, quotaOf({}, 'claude', false), wanted).reasons)
      .toEqual(['The machine reports critical memory pressure.'])
  }
})

// Project instructions, phase 4: quota is information, not a gate. A start on a used-up account goes ahead and waits for
// the reset there; the admission says so.
it('starts on a used-up account and says so', () => {
  const used = quotaOf({ providers: [{ provider: 'claude', outcome: 'answered', httpStatus: 200, body: { five_hour: { utilization: 100 } } }] }, 'claude', false)
  const fine = { resources: { cpuPercent: 10, memoryTotalBytes: 1000, memoryUsedBytes: 100, projectDiskFreeBytes: 500 }, tools: {}, devices: {} }
  const result = admission(fine, { installed: true }, used, { ...requirements, tools: [], devices: [] })
  expect(result).toMatchObject({ allowed: true, reasons: [] })
  expect(result.unknown).toContain(USED_UP_WINDOW)
  expect(USED_UP_WINDOW).toMatch(/used-up usage window/)
})