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.

18.4 KB
Raw Blame
// The fleet service: the machine list kept fresh, the lane to the other machines, the router every
// turn goes through, and ⌘K's two requests answered from it — with the dial nowhere in sight.
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'

import { env } from '../config/env.js'
import type { DeviceLinkOpts } from '../device/deviceLink.js'
import type { MachineListCache } from '../device/machineList.js'
import type { RegisteredSession } from '../lib/registry.js'
import { routeVoiceTask, type RouteDecision, type RouterAgent } from '../lib/voiceRouter.js'
import { fakeCore } from '../testing/fakeCore.js'
import { FAIL, type BackendNotice, type CoreApi } from '../core/api.js'
import { FLEET_FALLBACKS, startFleet, type Fleet, type FleetDeps } from './fleet.js'

// The lane is a cloud socket and the pinned keys a file under the data folder: neither in a test.
const lane = vi.hoisted(() => ({
  opts: null as DeviceLinkOpts | null,
  frames: null as ((frame: Record<string, unknown>) => void) | null,
  stop: vi.fn(),
  rpc: vi.fn(async (_type: string): Promise<Record<string, unknown>> => ({})),
  sendSealed: vi.fn(async () => {}),
  online: vi.fn(async () => {}),
  attach: vi.fn(async (_machineId: string) => {}),
  release: vi.fn(),
  peers: new Map<string, { pub: string }>(),
}))
vi.mock('../device/deviceLink.js', () => ({
  SESSION_GONE: 'E2EE_SESSION_GONE',
  DeviceLink: class {
    selectedMachine = ''
    constructor(opts: DeviceLinkOpts) { lane.opts = opts }
    onFrame(cb: (frame: Record<string, unknown>) => void) { lane.frames = cb; return () => {} }
    onUndelivered() { return () => {} }
    onAlive() { return () => {} }
    onGone() { return () => {} }
    stop() { lane.stop() }
    rpc(type: string) { return lane.rpc(type) }
    sendSealed(...args: unknown[]) { return lane.sendSealed(...(args as [])) }
    online() { return lane.online() }
    attach(machineId: string) { return lane.attach(machineId) }
    release() { lane.release() }
    resetSession() { return false }
  },
}))
vi.mock('../lib/e2ee/machinePeers.js', () => ({
  MachinePeerStore: class { get(machineId: string) { return lane.peers.get(machineId) ?? null } },
}))
vi.mock('../lib/voiceRouter.js', () => ({ routeVoiceTask: vi.fn() }))

const route = vi.mocked(routeVoiceTask)

const session = (agentId: string, registeredAt = 1, engine = 'claude') =>
  ({ agentId, registeredAt, engine, sessionId: `s-${agentId}` }) as unknown as RegisteredSession

type Row = { machineId: string; name: string; state: 'ready' | 'offline' | 'unknown' | 'needs-link'; authMode: 'remote'; local: boolean }
const THIS: Row = { machineId: 'mine', name: 'This one', state: 'ready', authMode: 'remote', local: true }
const OTHER: Row = { machineId: 'other', name: 'office-imac', state: 'ready', authMode: 'remote', local: false }

function machinesOf(rows: Row[] = [THIS, OTHER]) {
  return {
    list: vi.fn(() => ({ machines: rows, source: 'backend' as const })),
    find: vi.fn((machineId: string) => rows.find((row) => row.machineId === machineId)),
    adopt: vi.fn(() => true),
    refresh: vi.fn(async () => {}),
    applyLive: vi.fn(() => false),
  }
}

/** This computer as the core names it: its ids, its name and its account's environment. */
function coreOf(over: { machineId?: () => string } = {}, core: CoreApi = fakeCore()): CoreApi {
  return {
    ...core,
    machine: { id: over.machineId ?? (() => 'mine'), computerId: () => 'computer-1', name: () => 'MacbookPro.local' },
    account: { ...core.account, environment: () => 'test-env' },
  }
}

function setup(over: Partial<FleetDeps> & { machineId?: () => string } = {}, base = fakeCore()) {
  const machines = machinesOf()
  const { machineId, ...rest } = over
  const core = coreOf({ machineId }, base)
  const deps: FleetDeps = {
    machines: machines as unknown as MachineListCache,
    desk: () => [],
    ...rest,
  }
  const { fleet, router } = startFleet(core, deps)
  return { router, fleet: fleet as Fleet, deps, machines, core }
}

const decision = (over: Partial<RouteDecision> = {}): RouteDecision =>
  ({ agentId: 'a1', confidence: 1, reason: 'only agent in machine', needNewAgent: false, via: 'only-agent', ...over })

let log: ReturnType<typeof vi.spyOn>
beforeEach(() => {
  lane.peers = new Map([['other', { pub: 'pinned' }]])
  log = vi.spyOn(console, 'log').mockImplementation(() => {})
})
afterEach(() => {
  vi.useRealTimers()
  vi.restoreAllMocks()
  route.mockReset()
  lane.stop.mockReset()
  lane.rpc.mockReset().mockResolvedValue({})
  lane.sendSealed.mockReset()
})

describe('the machine list', () => {
  // Spec 2026-11-02-poll-cost Part 4.4: read every 60 s by every daemon with a dial, almost always unchanged.
  it('the fleet\'s machine list is served for 45 s and refreshed on machines_changed, every 5 minutes until the fleet stops', () => {
    vi.useFakeTimers()
    const base = fakeCore()
    let told: ((notice: BackendNotice) => void) | undefined
    const unsubscribe = vi.fn()
    vi.mocked(base.account.onNotice).mockImplementation((listener) => { told = listener; return unsubscribe })
    const { fleet, machines } = setup({}, base)
    expect(machines.refresh.mock.calls).toEqual([[{ maxAgeMs: 45_000 }]])
    vi.advanceTimersByTime(299_999)
    expect(machines.refresh).toHaveBeenCalledTimes(1)
    vi.advanceTimersByTime(1)
    expect(machines.refresh.mock.calls).toEqual([[{ maxAgeMs: 45_000 }], [{ maxAgeMs: 45_000 }]])
    // A machine added, renamed or removed: read now, whatever the list's age. Who uses a harness here is not the list.
    told!({ type: 'machines_changed', reason: 'renamed' })
    told!({ type: 'machines_changed', reason: 'harness_shares' })
    told!({ type: 'desk_changed', revision: 0 })
    expect(machines.refresh.mock.calls.slice(2)).toEqual([[{ maxAgeMs: 0 }]])
    fleet.stop()
    expect(lane.stop).toHaveBeenCalled()
    expect(unsubscribe).toHaveBeenCalledOnce()
    vi.advanceTimersByTime(600_000)
    expect(machines.refresh).toHaveBeenCalledTimes(3)
  })
})

describe('the lane to the other machines', () => {
  it('signs in and seals through the core, holding no credential, reading the pinned keys and this machine’s id fresh', async () => {
    let machineId = ''
    const { router, core } = setup({ machineId: () => machineId })
    const opts = lane.opts!
    expect(opts).toMatchObject({ backendWsBase: env.BACKEND_WS_URL, computerId: 'computer-1', autonomousEnv: 'test-env' })
    // Its tokens are the core's session's, a forced refresh included; its sessions the gateway's.
    expect(await opts.auth.accessToken({ force: true, failedToken: 'old' })).toBe('token')
    expect(core.account.accessToken).toHaveBeenCalledWith({ force: true, failedToken: 'old' })
    expect(opts.seal).toBe(core.account.lane)
    expect(Object.keys(opts)).not.toContain('identity')
    expect(opts.peer('other')).toEqual({ pub: 'pinned' })
    expect(opts.peer('third')).toBeNull()
    lane.peers.set('third', { pub: 'later' })
    expect(opts.peer('third')).toEqual({ pub: 'later' })
    expect(opts.localMachineId()).toBe('')
    // Before this computer has a machine id, its row is named by its computer id.
    expect(router.localId()).toBe('cable:computer-1')
    machineId = 'mine'
    expect(opts.localMachineId()).toBe('mine')
    opts.log('device: connecting')
    expect(log).toHaveBeenCalledWith('[device] device: connecting')
    // A machine with no pinned key is reachable but unreadable, and the wheel says so.
    lane.peers.delete('other')
    expect((await router.listMachines()).machines.find((m) => m.id === 'other')?.state).toBe('needs-link')
    lane.peers.set('other', { pub: 'pinned' })
    expect((await router.listMachines()).machines.find((m) => m.id === 'other')?.state).toBe('ready')
  })

  it('notes which machine a card came from, so a question from an agent never listed is named and routed home', () => {
    const { router } = setup()
    lane.frames!({ type: 'node_status', machineId: 'other', payload: { online: true } })
    expect(router.machineOf('other')).toBe('')
    lane.frames!({ type: 'commander_question', machineId: 'other', agentId: 'r9', payload: { requestId: 'q1', questions: [] } })
    expect(router.machineOf('r9')).toBe('other')
    expect(router.describe('r9')).toEqual({ name: '', engine: '', machine: '' })
  })

  it('reaches another machine’s agents over the lane, and says when it could not', async () => {
    lane.rpc.mockImplementation(async (type: string) => {
      if (type === 'agents_list') return { agents: [{ id: 'r1', name: 'api', engine: 'claude' }] }
      throw new Error('timed out')
    })
    const { router, fleet } = setup()
    await router.listAgentsFlat()
    await new Promise((resolve) => setTimeout(resolve, 0))
    expect((await router.listAgentsFlat()).map((a) => a.id)).toEqual(['r1'])
    expect(log).toHaveBeenCalledWith('[cable] cable: office-imac → 1 agents')
    expect(fleet.sendTurn('r1', 'ship it')).toEqual({ ok: true })
    expect(lane.sendSealed).toHaveBeenCalledWith(expect.objectContaining({ type: 'message', machineId: 'other' }))
    expect(await router.recentSummaries('r1')).toEqual([])
    expect(log).toHaveBeenCalledWith('[device] device: agent_recent r1 failed (timed out)')
  })
})

describe('this computer’s side of every route', () => {
  it('goes through the core’s own doors', async () => {
    const core = fakeCore({
      agents: {
        advertised: vi.fn(() => [session('a1')]),
        displayName: vi.fn(() => 'api'),
        runtimeProfile: vi.fn(() => 'runtime-v1:s-a1:claude:opus@high'),
        fork: vi.fn(async () => ({ ok: true as const, agentId: 'a1-fork' })),
        runtimeModels: vi.fn(async () => [{ id: 'opus', displayName: 'Opus' }]),
      },
      turns: { recent: vi.fn(async () => [{ recap: 'Done', text: 'Done' }]), asks: vi.fn(async () => ['what next?']) },
      questions: { answerReviewed: vi.fn(async () => true) },
    })
    // Asked as the dial asks it: through the port, the router's own answers.
    const { fleet } = setup({ desk: () => ['a1'] }, core)
    expect(await fleet.listAgentsFlat()).toEqual([
      { id: 'a1', name: 'api', engine: 'claude', machineId: 'mine', machine: 'MacbookPro.local', model: 'opus', effort: 'high' },
    ])
    expect(await fleet.activityTimes()).toBeInstanceOf(Map)
    expect(fleet.sendTurn('a1', 'hello')).toEqual({ ok: true })
    expect(core.turns.send).toHaveBeenCalledWith('a1', 'hello')
    expect(fleet.routeSend('a1', 'from cmd-k')).toEqual({ ok: true })
    expect(core.turns.send).toHaveBeenLastCalledWith('a1', 'from cmd-k')
    fleet.stopTurn('a1')
    expect(core.turns.stop).toHaveBeenCalledWith('a1')
    fleet.answer('a1', 'q', { scope: 'File' })
    expect(core.questions.answer).toHaveBeenCalledWith('a1', 'q', { scope: 'File' })
    const reviewed = { agentId: 'a1', requestId: 'q', questions: [], answers: {}, selections: {} }
    expect(await fleet.answerReviewed(reviewed)).toEqual({ ok: true })
    expect(core.questions.answerReviewed).toHaveBeenCalledWith(reviewed)
    expect(await fleet.recentSummaries('a1')).toEqual([{ recap: 'Done', text: 'Done', ask: '' }])
    expect(core.turns.recent).toHaveBeenCalledWith('a1', 3)
    expect(await fleet.recentAsks('a1')).toEqual(['what next?'])
    fleet.updateAgent('a1', 'sonnet', 'low')
    expect(core.agents.setRuntime).toHaveBeenCalledWith('a1', 'sonnet', 'low')
    expect(await fleet.listModels('a1')).toEqual(['opus'])
    expect(await fleet.forkAgent('a1')).toEqual({ result: { ok: true, agentId: 'a1-fork' }, machineId: 'mine', asked: true })
    expect(core.agents.fork).toHaveBeenCalledWith('a1')
  })
})

describe('what the dial asks through the port', () => {
  it('is the router\'s: its machines, what it knows of an agent, the person\'s last turn, and the lane', async () => {
    const core = fakeCore({ agents: { advertised: vi.fn(() => [session('a1')]), displayName: vi.fn(() => 'api') } })
    const { fleet } = setup({}, core)
    const { machines, source } = await fleet.listMachines()
    expect(source).toBe('backend')
    expect(machines.map((m) => m.id)).toEqual(['mine', 'other'])
    await fleet.listAgentsFlat()
    expect(fleet.agentTotal()).toBe(1)
    expect(fleet.describe('a1')).toEqual({ name: 'api', engine: 'claude', machine: 'MacbookPro.local' })
    fleet.noteAgent('other', 'r9')
    expect(fleet.machineOf('r9')).toBe('other')
    expect(fleet.knows('a1')).toBe(true)
    expect(fleet.isLocalAgent('r9')).toBe(false)
    expect(fleet.canSpeakQuestion('a1')).toBe(true)
    expect(fleet.lastRouted()).toBeUndefined()
    fleet.sendTurn('a1', 'hello')
    expect(fleet.lastRouted()).toMatchObject({ agentId: 'a1' })
    // The lane: there while signed in, held for a dial, and let go of.
    expect(fleet.hasLane()).toBe(true)
    expect(await fleet.online()).toEqual({ ok: true })
    expect(await fleet.select('other')).toEqual({ ok: true })
    fleet.release(true)
    expect(lane.release).toHaveBeenCalled()
  })

  it('carries the other machines\' cards to whoever listens, until they stop', () => {
    const { fleet } = setup()
    const heard: unknown[] = []
    const stop = fleet.onEvent((event) => heard.push(event))
    lane.frames!({ type: 'commander_event', machineId: 'other', agentId: 'r1', payload: { kind: 'done' } })
    stop()
    lane.frames!({ type: 'commander_event', machineId: 'other', agentId: 'r1', payload: { kind: 'done' } })
    expect(heard).toEqual([{ machineId: 'other', kind: 'done', agentId: 'r1', text: '', recap: '' }])
  })
})

describe('⌘K: which agent a typed task belongs to', () => {
  it('weighs every agent it knows with the person’s own questions, and remembers who they were just talking to', async () => {
    const core = fakeCore({
      agents: { advertised: vi.fn(() => [session('a1'), session('a2', 2, 'codex')]), displayName: vi.fn((s: RegisteredSession) => `name-${s.agentId}`) },
      turns: { asks: vi.fn(async (agentId: string) => (agentId === 'a1' ? ['  fix the\nparser '] : [])) },
    })
    const { fleet } = setup({}, core)
    route.mockResolvedValue(decision({ agentId: 'a2', confidence: 0.8, reason: 'parser work', via: 'claude' }))
    expect(await fleet.routeTask('fix the lexer')).toEqual({
      agentId: 'a2', machineId: 'mine', name: 'name-a2', confidence: 0.8, reason: 'parser work', weighed: 2, machines: 1, via: 'model',
      candidates: [
        { agentId: 'a2', name: 'name-a2', machineId: 'mine', machine: 'MacbookPro.local', engine: 'codex', recent: '', confidence: 0.8 },
        { agentId: 'a1', name: 'name-a1', machineId: 'mine', machine: 'MacbookPro.local', engine: 'claude', recent: '', confidence: 0 },
      ],
    })
    const [text, candidates, signal, timeoutMs, continuity] = route.mock.calls[0]!
    expect(text).toBe('fix the lexer')
    expect(candidates.map((c: RouterAgent) => [c.id, c.prompts])).toEqual([['a1', ['fix the parser']], ['a2', []]])
    expect([signal, timeoutMs, continuity]).toEqual([undefined, 20_000, undefined])
    // A turn ⌘K sent is who the person is talking to, for the next route.
    fleet.sendTurn('a2', 'and the lexer')
    await fleet.routeTask('one more')
    expect(route.mock.calls[1]![4]).toMatchObject({ agentId: 'a2' })
  })

  it('weighs the cloud harnesses too, where the core offers them', async () => {
    const core = fakeCore({
      agents: {
        advertised: vi.fn(() => [session('a1')]),
        cloud: vi.fn(() => [{ ...session('cloud_1', 2, 'fo'), defaultName: 'haircut' } as RegisteredSession]),
        displayName: vi.fn((s: RegisteredSession) => s.agentId),
      },
    })
    const { fleet } = setup({}, core)
    route.mockResolvedValue(decision({ agentId: 'cloud_1', confidence: 0.9, reason: 'errands', via: 'claude' }))
    expect((await fleet.routeTask('book a haircut')).candidates.map((candidate) => [candidate.agentId, candidate.engine])).toEqual([['cloud_1', 'fo'], ['a1', 'claude']])
  })

  it('weighs the first fifteen in rail order and says so; ranks the router’s runners-up first', async () => {
    const sessions = Array.from({ length: 17 }, (_, i) => session(`a${String(i).padStart(2, '0')}`, i))
    const { fleet } = setup({}, fakeCore({ agents: { advertised: vi.fn(() => sessions), displayName: vi.fn((s: RegisteredSession) => s.agentId) } }))
    route.mockResolvedValue(decision({
      agentId: 'a05', confidence: 0.3, reason: 'names', via: 'heuristic-names',
      scores: [{ agentId: 'a09', confidence: 0.2 }, { agentId: 'a05', confidence: 0.3 }, { agentId: 'gone', confidence: 0.1 }],
    }))
    const answer = await fleet.routeTask('something')
    expect(log).toHaveBeenCalledWith('[route] 17 agents · weighing the first 15 (open tiles first)')
    expect(answer.weighed).toBe(15)
    expect(answer.via).toBe('heuristic')
    expect(answer.candidates.map((c) => c.agentId).slice(0, 4)).toEqual(['a05', 'a09', 'a00', 'a01'])
    expect(answer.candidates).toHaveLength(15)
    expect(answer.candidates.map((c) => c.confidence).slice(0, 3)).toEqual([0.3, 0.2, 0])
  })

  it('picks nobody when the router does, and still shows what it weighed', async () => {
    const { fleet, router } = setup()
    // An agent listed with nothing to say about where it lives or what it runs, and a router that wrote
    // its own summary onto the candidate it read.
    vi.spyOn(router, 'listAgentsFlat').mockResolvedValue([{ id: 'x1', name: 'orphan' }])
    route.mockImplementation(async (_text, agents) => {
      agents[0]!.recentSummary = 'y'.repeat(200)
      return { agentId: '', confidence: 0, reason: 'no agents in machine', needNewAgent: true }
    })
    expect(await fleet.routeTask('anything')).toEqual({
      agentId: '', machineId: '', name: '', confidence: 0, reason: 'no agents in machine', weighed: 1, machines: 0, via: 'model',
      candidates: [{ agentId: 'x1', name: 'orphan', machineId: '', machine: '', engine: '', recent: 'y'.repeat(120), confidence: 0 }],
    })
  })
})

describe('the fleet failing', () => {
  it('answers ⌘K with no agent picked and nothing sent, saying why', () => {
    expect(FLEET_FALLBACKS.routeSend).toEqual({ ok: false, machine: '', reason: 'the fleet service is unavailable' })
    expect(FLEET_FALLBACKS.stop).toBeUndefined()
    // No cards, and nothing to stop hearing.
    expect((FLEET_FALLBACKS.onEvent as () => void)()).toBeUndefined()
  })

  it('fails the dial\'s routing rather than making an answer up', () => {
    // The dial routes this computer by itself then (cable/cableHost.ts): a made-up answer read as the
    // fleet's would send a turn nowhere and say it went.
    for (const member of ['agentTotal', 'describe', 'machineOf', 'knows', 'isLocalAgent', 'sendTurn', 'hasLane', 'release'] as const) {
      expect(FLEET_FALLBACKS[member], member).toBe(FAIL)
    }
  })
})