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.

13.8 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import type { ContributedMachine } from './machines.js'
import { createSuperTab, type Conversation, type SuperTabState } from './model.js'
import { RELAYED_QUOTA, reviewCapacityNotice } from './reviewCapacity.js'

// Overnight 2026-10-30, 12 pull requests waited hours for a review while every Codex Reviewer was out of weekly quota, and
// nobody was told until people noticed in the morning (Tony: "don't let the workflow get stuck"). The notice speaks only when
// no new agent of either engine can start on any machine the project may use: once per cause, in the project chat, tagging
// who can fix it. No policy, quality or rules (project instructions, phase 4): a machine counts when the project may use it.

const NOW = 10_000_000
const HOUR = 3_600_000

type Window = { name: string; usedPercent: number }
/** An engine's reading on a machine: its windows, `unknown` when it cannot be read, or signed out. */
type Reading = Window[] | 'unknown' | { signedOut: Window[] }
function machine(id: string, name: string, contributorId: string, engines: { claude?: Reading; codex?: Reading },
  extra: Partial<ContributedMachine> = {}): ContributedMachine {
  const names = (['claude', 'codex'] as const).filter(e => engines[e] !== undefined)
  const windows = (r: Reading) => (Array.isArray(r) ? r : r === 'unknown' ? [] : r.signedOut).map(w => ({ ...w, resetsAt: null as string | null }))
  return { machineId: id, name, contributorId, membershipGeneration: 'g', generation: 'g1', cwd: '/swarm', scope: 'swarm', engines: names,
    maxAgents: 4, paused: false, ...extra,
    observation: { generation: 'g1', receivedAt: NOW - 1000, sessionKind: 'computer',
      resources: { cpuPercent: null, memoryTotalBytes: null, memoryUsedBytes: null, diskFreeBytes: null, diskTotalBytes: null, projectDiskFreeBytes: null,
        deviceType: null, chip: null, os: null, gpuPercent: null },
      tools: {}, runningHarnessIds: [], stoppedHarnessIds: [],
      readiness: { engines: names.map(e => ({ engine: e, installed: true, signedIn: !(typeof engines[e] === 'object' && !Array.isArray(engines[e])) })) },
      quotas: names.map(e => ({ engine: e, known: engines[e] !== 'unknown', windows: windows(engines[e]!) })),
      ...extra.observation } as ContributedMachine['observation'] }
}
const out = [{ name: 'weekly', usedPercent: 100 }]
const low = [{ name: 'weekly', usedPercent: 85 }]
const plenty = [{ name: '5-hour', usedPercent: 10 }, { name: 'weekly', usedPercent: 15 }]
const both = (w: Reading) => ({ claude: w, codex: w })

/** A Swarm whose project has a build group [built] on [engine] and machines [machines]; Ken's project, Tony a teammate. */
function swarm(machines: ContributedMachine[], engine = 'claude', visibility: 'public' | 'private' = 'public') {
  const state: SuperTabState = createSuperTab('tab', 'Pilot', { id: 'ken', email: '[email protected]' }, 'prod')
  state.people.push({ id: 'tony', email: '[email protected]', role: 'collaborator', generation: 'gt' }, { id: 'huy', email: '[email protected]', role: 'collaborator', generation: 'gh' })
  state.projects![0]!.visibility = visibility
  state.machines = machines
  const built: Conversation = { id: 'built', number: 7, title: 'Offline edits', leadId: null, agentIds: [], archived: false, brief: 'Build it.', checks: [], lastMessageSequence: 0,
    assignment: { id: 'a1', agentId: 'builder', status: 'review', configuration: { engine, model: 'claude-opus-4-7', effort: 'high' }, result: null } } as unknown as Conversation
  state.conversations.push(built)
  return { state, built, project: state.projects![0]! }
}
const anyMachine = () => true
const notice = (state: SuperTabState, group: Conversation, teamOk: (machineId: string, contributorId: string) => boolean = anyMachine, now = NOW) =>
  reviewCapacityNotice(state, group, now, teamOk)

describe('the notice that new agents cannot start', () => {
  it('says when no machine the project may use can start either engine', () => {
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), machine('tony-mac', 'MacBook Pro 19', 'tony', both(out)),
      machine('huy-mac', 'Huy personal Mac', 'huy', both(plenty))])
    // Huy's machine has quota, but the project may not use it (machines.ts teamWorkCheck): it is not counted.
    const mayUse = (machineId: string) => machineId !== 'huy-mac'
    expect(notice(state, built, mayUse)).toMatchObject({ source: { kind: 'review-capacity', engine: 'any', cause: 'out' }, mentions: ['ken', 'tony'] })
    expect(notice(state, built, mayUse)).toBeNull()
    const usable = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), machine('tony-mac', 'MacBook Pro 19', 'tony', { claude: out, codex: plenty })])
    expect(notice(usable.state, usable.built)).toBeNull()
  })

  it('says nothing for a Claude build while Codex is out everywhere but Claude can start (Ken, 2026-10-30)', () => {
    // The morning of 10-30: every Codex out of weekly quota, Claude fine. Claude can start, so nobody is told.
    const { state, built, project } = swarm([machine('studio', 'Mac Studio', 'ken', { claude: plenty, codex: out }),
      machine('tony-mac', 'MacBook Pro 19', 'tony', { claude: plenty, codex: out })])
    expect(notice(state, built)).toBeNull()
    expect(project.reviewCapacity).toBeUndefined()
  })

  it('says once in the project chat that no agent of either engine can start, naming each machine and tagging its owner', () => {
    const { state, built, project } = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), machine('huy-mac', 'MacBookPro2021', 'huy', both({ signedOut: plenty })),
      machine('tony-mac', 'MacBook Pro 19', 'tony', { claude: out, codex: [{ name: '5-hour', usedPercent: 100 }, { name: 'weekly', usedPercent: 40 }] })])
    const first = notice(state, built)
    expect(first).toMatchObject({ conversationId: project.leadConversationId, mentions: ['ken', 'huy', 'tony'], source: { kind: 'review-capacity', engine: 'any', cause: 'out' } })
    expect(first!.text).toBe('No new agent can start: no machine this project may use can run Claude Code or Codex now '
      + '(Mac Studio: out of quota; MacBookPro2021: signed out; MacBook Pro 19: out of quota). @ken15 @huy @tony can fix it.')
    // A person's own numbers are never shown to the others.
    expect(first!.text).not.toMatch(/\d+ ?%/)
    expect(notice(state, built, anyMachine, NOW + HOUR)).toBeNull()
  })

  it('takes each machine at its best engine: one engine usable anywhere is enough', () => {
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', { claude: out, codex: plenty })])
    expect(notice(state, built)).toBeNull()
    const codexOnly = swarm([machine('studio', 'Mac Studio', 'ken', { codex: plenty }), machine('tony-mac', 'MacBook Pro 19', 'tony', { claude: out })])
    expect(notice(codexOnly.state, codexOnly.built)).toBeNull()
  })

  it('counts a paused machine as unable to start an agent, as the route does', () => {
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', both(plenty), { paused: true })])
    expect(notice(state, built)!.text).toContain('(Mac Studio: paused)')
  })

  it('warns once when every machine is close to running out of weekly quota, and again when it runs out', () => {
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', { claude: low, codex: out }), machine('tony-mac', 'MacBook Pro 19', 'tony', both(out))])
    const warned = notice(state, built)
    expect(warned).toMatchObject({ mentions: ['ken', 'tony'], source: { kind: 'review-capacity', engine: 'any', cause: 'low' } })
    expect(warned!.text).toBe('Quota for new agents is close to running out on every machine this project may use '
      + '(Mac Studio: close to running out; MacBook Pro 19: out of quota). @ken15 @tony can fix it.')
    expect(notice(state, built)).toBeNull()
    state.machines![0]!.observation!.quotas[0]!.windows[0]!.usedPercent = 100
    expect(notice(state, built)).toMatchObject({ source: { cause: 'out' } })
    expect(notice(state, built)).toBeNull()
  })

  it('says nothing while one machine has quota, and once it recovers, says it again the next time it runs out', () => {
    const { state, built, project } = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), machine('tony-mac', 'MacBook Pro 19', 'tony', { codex: plenty })])
    expect(notice(state, built)).toBeNull()
    state.machines![1]!.observation!.quotas[0]!.windows = out.map(w => ({ ...w, resetsAt: null }))
    expect(notice(state, built)).toMatchObject({ source: { cause: 'out' } })
    expect(project.reviewCapacity).toEqual({ any: 'out' })
    state.machines![0]!.observation!.quotas[0]!.windows = plenty.map(w => ({ ...w, resetsAt: null }))
    expect(notice(state, built)).toBeNull()
    expect(project.reviewCapacity).toBeUndefined()
    state.machines![0]!.observation!.quotas[0]!.windows = out.map(w => ({ ...w, resetsAt: null }))
    expect(notice(state, built)).toMatchObject({ source: { cause: 'out' } })
  })

  it('writes the project only when what it said changes, and drops a marker kept per engine before 2026-10-30', () => {
    const { state, built, project } = swarm([machine('studio', 'Mac Studio', 'ken', both(out))])
    project.reviewCapacity = { codex: 'out' }
    // An old server's marker says nothing of this rule, so the shortage is told once more, and the old key goes.
    expect(notice(state, built)).toMatchObject({ source: { cause: 'out' } })
    expect(project.reviewCapacity).toEqual({ any: 'out' })
    const kept = project.reviewCapacity
    expect(notice(state, built)).toBeNull()
    expect(project.reviewCapacity).toBe(kept)
  })

  it('counts a quota it cannot read as usable, as starts do, and says nothing with no machine for agents at all', () => {
    const unread = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), machine('x', 'Unread', 'tony', { codex: 'unknown' })])
    expect(notice(unread.state, unread.built)).toBeNull()
    const { state, built } = swarm([])
    expect(notice(state, built)).toBeNull()
  })

  it('reads a Team account\'s quota from its Mac when the account spends that subscription through the relay', () => {
    const mac = machine('tony-mac', 'MacBook Pro 19', 'tony', { codex: out })
    const team = machine('tony-team', 'MacBook Pro 19', 'tony', { codex: 'unknown' }, { hostMachineId: 'tony-mac' })
    team.observation!.quotaReasons = { codex: RELAYED_QUOTA }
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), mac, team])
    // The Mac is named once: the account is that Mac.
    expect(notice(state, built)!.text).toContain('(Mac Studio: out of quota; MacBook Pro 19: out of quota)')
    // Unknown for another reason, the account stays usable, as a start there is.
    team.observation!.quotaReasons = { codex: 'The allowance reader on this machine did not answer.' }
    const again = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), mac, team])
    expect(notice(again.state, again.built)).toBeNull()
  })

  it('says nothing while a used-up window resets inside the start window', () => {
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', { codex: out })])
    state.machines![0]!.observation!.quotas[0]!.windows[0]!.resetsAt = new Date(NOW + 10 * 60_000).toISOString()
    expect(notice(state, built)).toBeNull()
    state.machines![0]!.observation!.quotas[0]!.windows[0]!.resetsAt = new Date(NOW + 3 * 24 * HOUR).toISOString()
    expect(notice(state, built)).toMatchObject({ source: { cause: 'out' } })
  })

  it('counts an offline machine as unavailable, and leaves out machines this project may not use', () => {
    const offline = machine('tony-mac', 'MacBook Pro 19', 'tony', both(plenty))
    offline.observation!.receivedAt = NOW - HOUR
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), offline, machine('personal', 'Personal Mac', 'huy', both(plenty))])
    // Huy's personal machine takes no other person's project (machines.ts teamWorkCheck): left out altogether.
    const said = notice(state, built, (id, contributorId) => id !== 'personal' && contributorId !== 'huy')
    expect(said!.text).toContain('(Mac Studio: out of quota; MacBook Pro 19: offline)')
    expect(said!.mentions).toEqual(['ken', 'tony'])
  })

  it('tags only people who read the project, and names no machine of someone who does not', () => {
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), machine('tony-mac', 'Tony private Mac', 'tony', both(out))], 'claude', 'private')
    const said = notice(state, built)
    expect(said!.mentions).toEqual(['ken'])
    expect(said!.text).not.toContain('tony')
    expect(said!.text).not.toContain('Tony private Mac')
    expect(said!.text).toContain('(Mac Studio: out of quota; another machine: out of quota)')
  })

  it('neither counts nor names a Buddy-only machine, which is its person\'s alone', () => {
    const buddy = machine('buddy', 'Huy private laptop', 'huy', both(plenty), { buddyOnly: true })
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', both(out)), buddy])
    const said = notice(state, built)
    expect(said).toMatchObject({ mentions: ['ken'], source: { cause: 'out' } })
    expect(said!.text).not.toContain('Huy private laptop')
  })

  it('judges a Codex build and a grid build the same way, and says nothing for a group with no build', () => {
    const codex = swarm([machine('studio', 'Mac Studio', 'ken', { claude: plenty, codex: out })], 'codex')
    expect(notice(codex.state, codex.built)).toBeNull()
    const grid = swarm([machine('studio', 'Mac Studio', 'ken', both(out))])
    grid.state.agents.push({ id: 'builder', name: 'Builder', gridModel: 'moonshotai/kimi-k3' } as never)
    expect(notice(grid.state, grid.built)).toMatchObject({ source: { cause: 'out' } })
    const { state, built } = swarm([machine('studio', 'Mac Studio', 'ken', both(out))])
    expect(notice(state, { ...built, assignment: null })).toBeNull()
  })
})