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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
// The router across the owner's machines: which machine an agent is on, and a turn, a stop or an
// answer reaching it there. Every caller (⌘K, the voice route, the dial) goes through one of these.
import { afterEach, describe, expect, it, vi } from 'vitest'
import { FleetError, type FleetMachine, type MachineFleet } from '../cable/machineFleet.js'
import type { ReviewedAnswer } from '../cable/questionInbox.js'
import type { RegisteredSession } from '../lib/registry.js'
import { transcriptActivityAt } from '../lib/transcriptActivity.js'
import { FleetRouter, type FleetLocal } from './fleetRouter.js'
import { DeviceFleet } from '../device/deviceFleet.js'
vi.mock('../lib/transcriptActivity.js', () => ({ transcriptActivityAt: vi.fn(async () => null) }))
const session = (agentId: string, registeredAt: number, engine?: string) =>
({ agentId, registeredAt, engine, sessionId: `s-${agentId}` }) as unknown as RegisteredSession
function localOf(over: Partial<FleetLocal> = {}, sessions: RegisteredSession[] = []): FleetLocal {
return {
machineName: () => 'MacbookPro.local',
machineId: () => 'mine',
computerId: () => 'abc-123',
sessions: () => [...sessions],
displayName: (s) => `name-${s.agentId}`,
desk: () => [],
sendTurn: vi.fn(),
stopTurn: vi.fn(),
answer: vi.fn(),
recent: vi.fn(() => []),
recentAsks: vi.fn(() => []),
log: vi.fn(),
...over,
}
}
const REMOTE: FleetMachine = { machineId: 'other', name: 'office-imac', state: 'ready', authMode: 'remote' }
/** A fleet whose machines and agent lists are scripted. */
function fleetOf(machines: FleetMachine[], byMachine: Record<string, Array<{ id: string; name: string; engine?: string }>> = {}): MachineFleet {
return {
list: async () => ({ machines, source: 'backend' as const }),
online: async () => {},
select: async () => {},
release: vi.fn(),
listAgents: vi.fn(async (machineId: string) => (byMachine[machineId] ?? []) as never),
sendTurn: vi.fn(), stopTurn: vi.fn(), answer: vi.fn(), updateAgent: vi.fn(),
listModels: vi.fn(async () => ['m1']),
recentSummaries: vi.fn(async () => []),
recentAsks: vi.fn(async () => []),
onEvent: () => () => {},
}
}
const flush = () => new Promise((resolve) => setTimeout(resolve, 0))
/** The real fleet over a scripted lane that lists r1; `alive` is a reply of the machine's own under its session. */
function laneOf() {
const rows = [{ ...REMOTE, local: false, agentCount: 1 }]
let heard: (machineId: string) => void = () => {}
const link = {
selectedMachine: '', onFrame: () => () => {}, onUndelivered: () => () => {},
onAlive: (cb: (machineId: string) => void) => { heard = cb; return () => {} }, onGone: () => () => {},
rpc: vi.fn(async (): Promise<Record<string, unknown>> => ({ agents: [{ id: 'r1', name: 'api', engine: 'claude' }] })),
resetSession: vi.fn(() => true), sendSealed: vi.fn(async () => {}),
}
const fleet = new DeviceFleet({ list: { list: () => ({ machines: rows, source: 'backend' as const }), find: (id: string) => rows.find((r) => r.machineId === id) } as never,
link: link as never, hasPeerLink: () => true, log: () => {} })
return { link, fleet, alive: (machineId: string) => heard(machineId) }
}
/** Two reads: the first starts the background refresh, the second reads what it wrote. */
async function settled(router: FleetRouter) {
await router.listAgentsFlat()
await flush()
return router.listAgentsFlat()
}
afterEach(() => { vi.restoreAllMocks() })
describe('this computer', () => {
it('is named by its machine id, or by a placeholder that is not machine-id shaped', () => {
expect(new FleetRouter(localOf()).localId()).toBe('mine')
expect(new FleetRouter(localOf({ machineId: () => '' })).localId()).toBe('cable:abc-123')
})
it('is the only row with no fleet, and the first row with one — never twice', async () => {
expect(await new FleetRouter(localOf()).listMachines()).toEqual({
machines: [{ id: 'mine', name: 'MacbookPro.local', state: 'ready', local: true }], source: 'signed-out',
})
const dupe: FleetMachine = { machineId: 'mine', name: 'renamed', state: 'offline', authMode: 'remote' }
const { machines, source } = await new FleetRouter(localOf(), fleetOf([dupe, REMOTE])).listMachines()
expect(source).toBe('backend')
expect(machines).toEqual([
{ id: 'mine', name: 'MacbookPro.local', state: 'ready', local: true },
{ id: 'other', name: 'office-imac', state: 'ready', local: false },
])
})
it('lists its agents oldest first, ties by id, with the chips their runtime profile names', async () => {
const profiles: Record<string, string | null> = {
b: 'runtime-v1:s-b:claude:opus@high', a: 'runtime-v1:s-a:claude:sonnet', c: 'runtime-v1:s-c:claude:@low',
d: 'runtime-v1:s-d:claude', e: 'something-else', f: null,
}
const router = new FleetRouter(localOf({ runtimeProfile: (s) => profiles[s.agentId] ?? null },
[session('f', 3, 'terminal'), session('b', 1, 'claude'), session('a', 1, 'claude'), session('c', 2), session('d', 2), session('e', 2)]))
const agents = await router.listAgentsFlat()
expect(agents.map((a) => a.id)).toEqual(['a', 'b', 'c', 'd', 'e', 'f'])
expect(agents[0]).toEqual({ id: 'a', name: 'name-a', engine: 'claude', machineId: 'mine', machine: 'MacbookPro.local', model: 'sonnet', effort: undefined })
expect(agents[1]).toMatchObject({ model: 'opus', effort: 'high' })
expect(agents[2]).toMatchObject({ engine: '', model: undefined, effort: 'low' })
for (const plain of agents.slice(3)) expect(plain).not.toHaveProperty('model')
// A shell is a tile, not an agent: the overview's number leaves it out.
expect(router.agentTotal()).toBe(5)
// No profile reader at all: no chips.
const bare = new FleetRouter(localOf({}, [session('a', 1, 'claude')]))
expect((await bare.listAgentsFlat())[0]).not.toHaveProperty('model')
})
})
describe('which machine an agent is on', () => {
it('reads each other machine’s list off to the side, and puts this computer first', async () => {
const third: FleetMachine = { machineId: 'third', name: 'studio', state: 'ready', authMode: 'remote' }
const fleet = fleetOf([REMOTE, third], { other: [{ id: 'r1', name: 'api' }], third: [{ id: 'r2', name: 'ui', engine: 'codex' }] })
const log = vi.fn()
const router = new FleetRouter(localOf({ log }, [session('local-1', 1, 'claude')]), fleet)
const agents = await settled(router)
expect(agents.map((a) => [a.id, a.machineId, a.machine])).toEqual([
['local-1', 'mine', 'MacbookPro.local'], ['r1', 'other', 'office-imac'], ['r2', 'third', 'studio'],
])
expect(router.machineOf('r2')).toBe('third')
expect(router.machineOf('local-1')).toBe('mine')
expect(router.machineOf('ghost')).toBe('')
expect(router.knows('r1')).toBe(true)
expect(router.knows('ghost')).toBe(false)
expect(router.isLocalAgent('local-1')).toBe(true)
expect(router.isLocalAgent('ghost')).toBe(true)
expect(router.isLocalAgent('r1')).toBe(false)
expect(log).toHaveBeenCalledWith('cable: office-imac → 1 agents')
// Asked once a round, not on every read: the list changes when a person starts an agent.
await router.listAgentsFlat()
expect(fleet.listAgents).toHaveBeenCalledTimes(2)
})
it('asks a slow machine once, and logs only when a machine’s count changes', async () => {
let answer: (agents: never) => void = () => {}
const fleet = fleetOf([REMOTE])
fleet.listAgents = vi.fn(() => new Promise<never>((resolve) => { answer = resolve }))
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
await router.listAgentsFlat()
const now = Date.now()
vi.spyOn(Date, 'now').mockReturnValue(now + 6_000)
await router.listAgentsFlat() // past the cadence, but its first answer is still out
expect(fleet.listAgents).toHaveBeenCalledTimes(1)
answer([{ id: 'r1', name: 'api' }] as never)
await flush()
expect(log).toHaveBeenCalledWith('cable: office-imac → 1 agents')
log.mockClear()
vi.spyOn(Date, 'now').mockReturnValue(now + 12_000)
await router.listAgentsFlat()
answer([{ id: 'r1', name: 'api' }] as never)
await flush()
expect(fleet.listAgents).toHaveBeenCalledTimes(2)
expect(log).not.toHaveBeenCalled()
})
it('keeps a machine’s last good list through a failure, and only past the grace drops it, saying so', async () => {
const fleet = fleetOf([REMOTE], { other: [{ id: 'r1', name: 'api' }] })
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
;(fleet.listAgents as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('cloud blip'))
const now = Date.now()
vi.spyOn(Date, 'now').mockReturnValue(now + 6_000)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
vi.spyOn(Date, 'now').mockReturnValue(now + 60_000)
await settled(router)
expect(log).toHaveBeenCalledWith('cable: office-imac dropped off the carousel (cloud blip)')
expect(await router.listAgentsFlat()).toEqual([])
// Already empty: a later failure past the grace has nothing to drop and says nothing.
log.mockClear()
vi.spyOn(Date, 'now').mockReturnValue(now + 120_000)
await settled(router)
expect(log).not.toHaveBeenCalled()
})
// Diego, 10-30: a slow but working Mac's agents left the carousel and turns to them were refused, though its replies
// were arriving, late (15 carousel drops in a day). The real fleet, over a lane whose list times out each time.
it('keeps a slow machine on the carousel, with its session and its turns, while late replies of its own prove it alive', async () => {
const rows = [{ ...REMOTE, local: false, agentCount: 1 }]
let alive: (machineId: string) => void = () => {}
const link = {
selectedMachine: '', onFrame: () => () => {}, onUndelivered: () => () => {},
onAlive: (cb: (machineId: string) => void) => { alive = cb; return () => {} }, onGone: () => () => {},
rpc: vi.fn(async (): Promise<Record<string, unknown>> => ({ agents: [{ id: 'r1', name: 'api', engine: 'claude' }] })),
resetSession: vi.fn(() => true), sendSealed: vi.fn(async () => {}),
}
const fleet = new DeviceFleet({ list: { list: () => ({ machines: rows, source: 'backend' as const }), find: (id: string) => rows.find((r) => r.machineId === id) } as never,
link: link as never, hasPeerLink: () => true, log: () => {} })
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
// Slow from here: every list times out, and the reply to the one before arrives while the next is out.
link.rpc.mockImplementation(async () => { alive('other'); throw new Error('agents_list timed out') })
const now = Date.now()
for (const later of [60_000, 120_000, 180_000]) {
vi.spyOn(Date, 'now').mockReturnValue(now + later)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
}
expect(log).not.toHaveBeenCalledWith(expect.stringContaining('dropped off the carousel'))
expect(link.resetSession).not.toHaveBeenCalled()
expect(router.sendTurn('r1', 'still there?')).toEqual({ ok: true })
expect(link.sendSealed).toHaveBeenCalledWith(expect.objectContaining({ type: 'message', machineId: 'other' }))
// Gone for real: nothing of its own comes back, so its tiles go, its session is thrown away, and the verdict turns
// refuse on is that it did not answer.
link.rpc.mockImplementation(async () => { throw new Error('agents_list timed out') })
for (const later of [240_000, 300_000]) {
vi.spyOn(Date, 'now').mockReturnValue(now + later)
await settled(router)
}
expect(log).toHaveBeenCalledWith('cable: office-imac dropped off the carousel (agents_list timed out)')
expect(link.resetSession).toHaveBeenCalledWith('other')
expect(fleet.reachable('other')).toMatchObject({ ok: false })
})
// #2381's second review: a machine that answers every list with an error answers under its own session too, so the
// rule above kept its last good tiles for ever (before #2381, 30 s). A refusal is an answer, not lateness: its tiles
// keep the same grace, counted from its first refusal after the last good list.
it('drops the tiles of a machine that answers every list with an error, 30 s after its first refusal, and takes them back when it lists again', async () => {
const { link, fleet, alive } = laneOf()
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
link.rpc.mockImplementation(async () => { alive('other'); throw new Error('UNSUPPORTED') })
const now = Date.now()
for (const later of [60_000, 70_000, 85_000]) {
vi.spyOn(Date, 'now').mockReturnValue(now + later)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
}
vi.spyOn(Date, 'now').mockReturnValue(now + 95_000)
await settled(router)
expect(log).toHaveBeenCalledWith('cable: office-imac dropped off the carousel (UNSUPPORTED)')
expect(await router.listAgentsFlat()).toEqual([])
// It answers, so it is up: its session stays, and nothing about it is called unreachable.
expect(link.resetSession).not.toHaveBeenCalled()
expect(fleet.reachable('other')).toMatchObject({ ok: true })
// A good list again: its tiles are back, and a later refusal has its whole grace once more.
link.rpc.mockImplementation(async () => ({ agents: [{ id: 'r1', name: 'api', engine: 'claude' }] }))
vi.spyOn(Date, 'now').mockReturnValue(now + 101_000)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
link.rpc.mockImplementation(async () => { alive('other'); throw new Error('UNSUPPORTED') })
vi.spyOn(Date, 'now').mockReturnValue(now + 200_000)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
})
it('shows a machine whose first list was refused once it lists, with no clock left over from the refusals', async () => {
const { link, fleet, alive } = laneOf()
link.rpc.mockImplementation(async () => { alive('other'); throw new Error('UNSUPPORTED') })
const router = new FleetRouter(localOf(), fleet)
expect(await settled(router)).toEqual([])
const now = Date.now()
vi.spyOn(Date, 'now').mockReturnValue(now + 60_000)
expect(await settled(router)).toEqual([])
link.rpc.mockImplementation(async () => ({ agents: [{ id: 'r1', name: 'api', engine: 'claude' }] }))
vi.spyOn(Date, 'now').mockReturnValue(now + 66_000)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
link.rpc.mockImplementation(async () => { alive('other'); throw new Error('UNSUPPORTED') })
vi.spyOn(Date, 'now').mockReturnValue(now + 72_000)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
})
it('keeps a slow machine whose lists come back good, however late each one is', async () => {
let answer: (res: Record<string, unknown>) => void = () => {}
const { link, fleet } = laneOf()
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
link.rpc.mockImplementation(() => new Promise((resolve) => { answer = resolve }))
const now = Date.now()
for (let round = 1; round <= 4; round++) {
vi.spyOn(Date, 'now').mockReturnValue(now + round * 50_000)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1']) // asked, and still out
vi.spyOn(Date, 'now').mockReturnValue(now + round * 50_000 + 40_000)
expect((await router.listAgentsFlat()).map((a) => a.id)).toEqual(['r1'])
answer({ agents: [{ id: 'r1', name: 'api', engine: 'claude' }] })
await flush()
}
expect(link.rpc).toHaveBeenCalledTimes(5)
expect(log).not.toHaveBeenCalledWith(expect.stringContaining('dropped off the carousel'))
})
it('restarts the refusal clock on each good list', async () => {
const { link, fleet, alive } = laneOf()
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
const refuse = () => link.rpc.mockImplementation(async () => { alive('other'); throw new Error('UNSUPPORTED') })
const list = () => link.rpc.mockImplementation(async () => ({ agents: [{ id: 'r1', name: 'api', engine: 'claude' }] }))
const now = Date.now()
const at = async (later: number) => { vi.spyOn(Date, 'now').mockReturnValue(now + later); return (await settled(router)).map((a) => a.id) }
refuse()
expect(await at(10_000)).toEqual(['r1']) // its first refusal: the clock starts
expect(await at(35_000)).toEqual(['r1'])
list()
expect(await at(41_000)).toEqual(['r1']) // a good list: the clock stops
refuse()
expect(await at(50_000)).toEqual(['r1']) // and starts again here, not at 10 s
expect(await at(75_000)).toEqual(['r1'])
expect(log).not.toHaveBeenCalledWith(expect.stringContaining('dropped off the carousel'))
await at(85_000)
expect(log).toHaveBeenCalledWith('cable: office-imac dropped off the carousel (UNSUPPORTED)')
expect(await router.listAgentsFlat()).toEqual([])
})
it('never puts back the tiles of a machine that went offline, lost its link or left the list while its list was out', async () => {
const cases = [['offline', ['r1'], 'list'], ['needs-link', ['r1'], 'refusal'], ['removed', ['r1'], 'list'], ['removed', ['r1'], 'refusal'],
['offline', [], 'refusal'], ['needs-link', [], 'list']] as const
for (const [gone, first, lands] of cases) {
const machines: FleetMachine[] = [{ ...REMOTE }]
const fleet = fleetOf(machines, { other: first.map((id) => ({ id, name: 'api' })) })
const router = new FleetRouter(localOf(), fleet)
expect((await settled(router)).map((a) => a.id)).toEqual(first)
const out: Array<{ resolve: (agents: never) => void; reject: (err: Error) => void }> = []
;(fleet.listAgents as ReturnType<typeof vi.fn>).mockImplementation(() => new Promise<never>((resolve, reject) => { out.push({ resolve, reject }) }))
const now = Date.now()
vi.spyOn(Date, 'now').mockReturnValue(now + 6_000)
await router.listAgentsFlat()
expect(out).toHaveLength(1)
if (gone === 'removed') machines.length = 0
else machines[0].state = gone
expect(await settled(router)).toEqual([])
// Its answer lands after, a list or a refusal, whether it had tiles or none: it changes nothing the dial now shows.
if (lands === 'list') out[0].resolve([{ id: 'r1', name: 'api' }] as never)
else out[0].reject(new Error('UNSUPPORTED'))
await flush()
expect(await router.listAgentsFlat()).toEqual([])
// Back, ready: its tiles come from a list asked now, never from the one asked before it went.
machines.length = 0
machines.push({ ...REMOTE })
vi.spyOn(Date, 'now').mockReturnValue(now + 12_000)
expect(await router.listAgentsFlat()).toEqual([])
expect(out).toHaveLength(2)
out[1].resolve([{ id: 'r2', name: 'web' }] as never)
await flush()
expect((await router.listAgentsFlat()).map((a) => a.id)).toEqual(['r2'])
vi.restoreAllMocks()
}
})
it('keeps a machine’s agents while the backend cannot be asked, and drops them when the machine says offline', async () => {
const machines: FleetMachine[] = [{ ...REMOTE }]
const fleet = fleetOf(machines, { other: [{ id: 'r1', name: 'api' }] })
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
machines[0].state = 'unknown'
vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 10 * 60_000)
expect((await settled(router)).map((a) => a.id)).toEqual(['r1'])
machines[0].state = 'offline'
expect((await settled(router)).map((a) => a.id)).toEqual([])
expect(log).toHaveBeenCalledWith('cable: office-imac is offline — its 1 agents left the carousel')
// Already empty: nothing more to say.
log.mockClear()
await settled(router)
expect(log).not.toHaveBeenCalled()
})
it('asks nothing of a machine that is not linked', async () => {
const fleet = fleetOf([{ ...REMOTE, state: 'needs-link' }], { other: [{ id: 'r1', name: 'api' }] })
const router = new FleetRouter(localOf(), fleet)
expect(await settled(router)).toEqual([])
expect(fleet.listAgents).not.toHaveBeenCalled()
})
it('holds a tile the window has open after its machine drops out, once, and never resurrects one without a tile', async () => {
const machines: FleetMachine[] = [{ ...REMOTE }]
const desk: string[] = []
const log = vi.fn()
const router = new FleetRouter(localOf({ log, desk: () => desk }), fleetOf(machines, { other: [{ id: 'r1', name: 'api' }, { id: 'r2', name: 'web' }] }))
await settled(router)
desk.push('r1', 'never-listed')
machines[0].state = 'offline'
const agents = await settled(router)
expect(agents.map((a) => a.id)).toEqual(['r1'])
expect(agents[0]).toMatchObject({ name: 'api', machineId: 'other', machine: 'office-imac' })
expect(router.knows('r1')).toBe(true)
expect(router.knows('r2')).toBe(false)
// Still held on the next read, and said only the once.
expect((await router.listAgentsFlat()).map((a) => a.id)).toEqual(['r1'])
expect(log.mock.calls.filter(([line]) => String(line).startsWith('cable: holding'))).toEqual([['cable: holding r1 on the tab — the window has a tile for it']])
// The tile closes: no longer held, and a later hold says so again.
desk.splice(0)
expect(await router.listAgentsFlat()).toEqual([])
desk.push('r1')
await router.listAgentsFlat()
expect(log.mock.calls.filter(([line]) => String(line).startsWith('cable: holding'))).toHaveLength(2)
})
it('routes nothing for an agent listed without a machine, even when the window holds its tile', async () => {
const nameless: FleetMachine = { machineId: '', name: 'ghost-row', state: 'ready', authMode: 'remote' }
const machines = [nameless]
const desk: string[] = []
const router = new FleetRouter(localOf({ desk: () => desk }), fleetOf(machines, { '': [{ id: 'x1', name: 'orphan' }] }))
expect((await settled(router)).map((a) => a.id)).toEqual(['x1'])
expect(router.knows('x1')).toBe(false)
desk.push('x1')
nameless.state = 'offline'
expect((await settled(router)).map((a) => a.id)).toEqual(['x1'])
expect(router.knows('x1')).toBe(false)
})
it('describes an agent it has listed, one it has only heard from, and nothing it has never met', async () => {
const unnamed = { ...REMOTE, name: undefined as unknown as string }
const router = new FleetRouter(localOf({}, [session('a1', 1, 'codex')]), fleetOf([unnamed], { other: [{ id: 'r1', name: 'api' }] }))
// Before any list: a local agent is still this computer's.
expect(router.describe('a1')).toEqual({ name: 'name-a1', engine: 'codex', machine: 'MacbookPro.local' })
await settled(router)
expect(router.describe('r1')).toEqual({ name: 'api', engine: '', machine: '' })
expect(router.describe('ghost')).toBeUndefined()
router.noteAgent('other', 'r9')
router.noteAgent('', 'r8')
router.noteAgent('other', '')
router.noteAgent('elsewhere', 'r7')
expect(router.describe('r9')).toEqual({ name: '', engine: '', machine: '' })
expect(router.describe('r8')).toBeUndefined()
expect(router.describe('r7')).toEqual({ name: '', engine: '', machine: '' })
expect(router.machineOf('r9')).toBe('other')
const named = new FleetRouter(localOf(), fleetOf([REMOTE]))
await named.listAgentsFlat()
named.noteAgent('other', 'r9')
expect(named.describe('r9')).toEqual({ name: '', engine: '', machine: 'office-imac' })
})
})
describe('a turn, delivered and said so', () => {
it('goes to the agent’s own machine, and is remembered as who the person is talking to', async () => {
const fleet = fleetOf([REMOTE], { other: [{ id: 'r1', name: 'api' }] })
const local = localOf({}, [session('local-1', 1, 'claude')])
const router = new FleetRouter(local, fleet)
await settled(router)
expect(router.lastRouted()).toBeUndefined()
expect(router.sendTurn('r1', 'ship it')).toEqual({ ok: true })
expect(fleet.sendTurn).toHaveBeenCalledWith('other', 'r1', 'ship it')
expect(router.lastRouted()).toMatchObject({ agentId: 'r1' })
expect(router.sendTurn('local-1', 'hello')).toEqual({ ok: true })
expect(local.sendTurn).toHaveBeenCalledWith('local-1', 'hello')
expect(router.lastRouted()?.agentId).toBe('local-1')
// Never guessed onto another machine: an id never listed goes to this computer's door.
router.sendTurn('ghost', 'where does this go?')
expect(local.sendTurn).toHaveBeenLastCalledWith('ghost', 'where does this go?')
expect(fleet.sendTurn).toHaveBeenCalledTimes(1)
// An empty id is delivered, but is not a conversation.
router.sendTurn('', 'nobody')
expect(router.lastRouted()?.agentId).toBe('ghost')
})
it('is refused for a machine whose last request did not come back, and never for one never asked', async () => {
const fleet = fleetOf([REMOTE], { other: [{ id: 'r1', name: 'api' }] })
const log = vi.fn()
const router = new FleetRouter(localOf({ log }), fleet)
await settled(router)
fleet.reachable = () => null
expect(router.sendTurn('r1', 'cold start')).toEqual({ ok: true })
fleet.reachable = () => ({ ok: true, at: Date.now() })
expect(router.sendTurn('r1', 'fine')).toEqual({ ok: true })
fleet.reachable = () => ({ ok: false, at: Date.now() - 4_000 })
expect(router.sendTurn('r1', 'deaf')).toEqual({ ok: false, machine: 'office-imac', reason: 'the last request to it did not come back' })
expect(log).toHaveBeenCalledWith('cable: refused a turn for r1 — office-imac last failed 4s ago')
expect(router.lastRouted()?.agentId).toBe('r1')
expect(fleet.sendTurn).toHaveBeenCalledTimes(2)
// Heard from but never listed: the refusal names the machine by its id.
router.noteAgent('abcdef0123456789', 'r9')
expect(router.sendTurn('r9', 'deaf too')).toMatchObject({ ok: false, machine: 'abcdef01' })
})
it('stops, answers and switches models on the agent’s own machine', async () => {
const fleet = fleetOf([REMOTE], { other: [{ id: 'r1', name: 'api' }] })
const updateAgent = vi.fn()
const local = localOf({ updateAgent }, [session('a1', 1, 'claude')])
const router = new FleetRouter(local, fleet)
await settled(router)
router.stopTurn('r1'); router.stopTurn('a1')
expect(fleet.stopTurn).toHaveBeenCalledWith('other', 'r1')
expect(local.stopTurn).toHaveBeenCalledWith('a1')
router.answer('r1', 'q', { k: 'v' }); router.answer('a1', 'q', { k: 'v' })
expect(fleet.answer).toHaveBeenCalledWith('other', 'r1', 'q', { k: 'v' })
expect(local.answer).toHaveBeenCalledWith('a1', 'q', { k: 'v' })
router.updateAgent('r1', 'opus', 'high'); router.updateAgent('a1', 'sonnet')
expect(fleet.updateAgent).toHaveBeenCalledWith('other', 'r1', 'opus', 'high')
expect(updateAgent).toHaveBeenCalledWith('a1', 'sonnet', undefined)
// A daemon with no model switch: nothing happens.
new FleetRouter(localOf()).updateAgent('a1', 'opus')
})
it('times each local agent by its transcript, else its last hook, and skips one with neither', async () => {
vi.mocked(transcriptActivityAt).mockImplementation(async (path) => (path === '/t' ? 500 : null))
const at = (agentId: string, over: object) => ({ ...session(agentId, 1, 'claude'), ...over }) as unknown as RegisteredSession
const router = new FleetRouter(localOf({}, [
at('a1', { transcriptPath: '/t', lastHookAt: 9 }), at('a2', { transcriptPath: null, lastHookAt: 700 }), at('a3', { transcriptPath: null }),
]))
expect([...(await router.activityTimes())]).toEqual([['a1', 500], ['a2', 700]])
})
it('carries the whole answer of a recent turn when it has one', async () => {
const router = new FleetRouter(localOf({ recent: vi.fn(() => [{ recap: 'r', text: 't', fullText: 'all of it' }] as never) }, [session('a1', 1)]))
expect(await router.recentSummaries('a1')).toEqual([{ recap: expect.any(String), text: 't', ask: '', fullText: 'all of it' }])
})
it('reads recaps, questions and models from the agent’s own machine, tidied', async () => {
const fleet = fleetOf([REMOTE], { other: [{ id: 'r1', name: 'api' }] })
fleet.recentSummaries = vi.fn(async () => [{ recap: 'Done.', text: 'Shipped the fix.', ask: 'ship it' }])
fleet.recentAsks = vi.fn(async () => [' ship\n it ', ''])
const local = localOf({
recent: vi.fn(() => [null, {}, { recap: 'Local recap', text: 'body' }, { ask: 'only a question' }] as never),
recentAsks: vi.fn(() => ['what next?', null] as never),
listModels: vi.fn(async () => [{ id: 'opus' }, { id: '' }]),
}, [session('a1', 1, 'claude')])
const router = new FleetRouter(local, fleet)
await settled(router)
expect(await router.recentSummaries('r1')).toEqual([{ recap: expect.any(String), text: 'Shipped the fix.', ask: 'ship it' }])
expect(fleet.recentSummaries).toHaveBeenCalledWith('other', 'r1')
expect(await router.recentSummaries('a1')).toEqual([
{ recap: expect.any(String), text: 'body', ask: '' }, { recap: '', text: '', ask: 'only a question' },
])
expect(local.recent).toHaveBeenCalledWith('a1', 3)
expect(await router.recentAsks('r1')).toEqual(['ship it'])
expect(await router.recentAsks('a1')).toEqual(['what next?'])
expect(await router.listModels('r1')).toEqual(['m1'])
expect(await router.listModels('a1')).toEqual(['opus'])
expect(await new FleetRouter(localOf()).listModels('a1')).toEqual([])
})
})
describe('a fork, on the agent’s own machine', () => {
it('forks a local agent through the daemon, notes the fork here, and says which machine was asked', async () => {
const forkAgent = vi.fn(async () => ({ ok: true as const, agentId: 'a1-fork' }))
const router = new FleetRouter(localOf({ forkAgent }, [session('a1', 1, 'claude')]))
await router.listAgentsFlat()
expect(await router.forkAgent('a1')).toEqual({ result: { ok: true, agentId: 'a1-fork' }, machineId: 'mine', asked: true })
expect(router.machineOf('a1-fork')).toBe('mine')
forkAgent.mockResolvedValueOnce({ ok: false, error: 'BUSY' } as never)
expect(await router.forkAgent('a1')).toEqual({ result: { ok: false, error: 'BUSY' }, machineId: 'mine', asked: true })
})
it('refuses without asking anyone for an agent never listed, or a daemon that cannot fork', async () => {
const router = new FleetRouter(localOf({}, [session('a1', 1, 'claude')]))
await router.listAgentsFlat()
expect(await router.forkAgent('ghost')).toMatchObject({ result: { ok: false, error: 'AGENT_NOT_FOUND' }, machineId: '', asked: false })
expect(await router.forkAgent('a1')).toMatchObject({ result: { ok: false, error: 'UNSUPPORTED' }, machineId: 'mine', asked: false })
// A remote agent heard from, with no fleet to fork it through.
router.noteAgent('other', 'r1')
expect(await router.forkAgent('r1')).toEqual({ result: { ok: false, error: 'UNSUPPORTED_ON_REMOTE' }, machineId: 'other', asked: false })
})
it('forks a remote agent on its machine, and reports the far end’s refusal', async () => {
const fleet = fleetOf([REMOTE], { other: [{ id: 'r1', name: 'api' }, { id: 'r2', name: 'busy' }] })
fleet.forkAgent = vi.fn(async (_m: string, id: string) => { if (id === 'r1') return 'r1-fork'; throw new Error('r2 is in the middle of a turn') })
const router = new FleetRouter(localOf(), fleet)
await settled(router)
expect(await router.forkAgent('r1')).toEqual({ result: { ok: true, agentId: 'r1-fork' }, machineId: 'other', asked: true })
expect(router.machineOf('r1-fork')).toBe('other')
expect((await router.forkAgent('r2')).result).toEqual({ ok: false, error: 'FORK_FAILED', detail: 'r2 is in the middle of a turn' })
})
})
describe('the lane, held while a dial is plugged in', () => {
it('is there only with a fleet, and comes online, selects and lets go through it', async () => {
expect(new FleetRouter(localOf()).hasLane()).toBe(false)
// Nothing to let go of without one.
new FleetRouter(localOf()).release(true)
const fleet = fleetOf([REMOTE])
fleet.online = vi.fn(async () => {})
fleet.select = vi.fn(async () => {})
const router = new FleetRouter(localOf(), fleet)
expect(router.hasLane()).toBe(true)
expect(await router.online()).toEqual({ ok: true })
expect(await router.select('other')).toEqual({ ok: true })
expect(fleet.select).toHaveBeenCalledWith('other')
router.release(true)
router.release()
expect((fleet.release as ReturnType<typeof vi.fn>).mock.calls).toEqual([[true], [undefined]])
})
it('answers a lane that will not open and a refused selection, rather than throwing them', async () => {
const fleet = fleetOf([REMOTE])
fleet.online = vi.fn(async () => { throw new Error('backend unreachable') })
fleet.select = vi.fn(async (machineId: string) => {
if (machineId === 'other') throw new FleetError('NEEDS_LINK', 'Link office-imac to this computer first')
throw new Error('socket closed')
})
const router = new FleetRouter(localOf(), fleet)
expect(await router.online()).toEqual({ ok: false, message: 'backend unreachable' })
expect(await router.select('other')).toEqual({ ok: false, code: 'NEEDS_LINK', message: 'Link office-imac to this computer first' })
expect(await router.select('third')).toEqual({ ok: false, code: 'UNREACHABLE', message: 'socket closed' })
})
it('passes on why the lane would not open, so the dial knows whether to try again', async () => {
const fleet = fleetOf([REMOTE])
const router = new FleetRouter(localOf(), fleet)
fleet.online = vi.fn(async () => { throw Object.assign(new Error('the sign-in could not be refreshed'), { code: 'TOKEN_UNAVAILABLE' }) })
expect(await router.online()).toEqual({ ok: false, message: 'the sign-in could not be refreshed', code: 'TOKEN_UNAVAILABLE' })
fleet.online = vi.fn(async () => { throw Object.assign(new Error('sign in again'), { code: 'SESSION_OVER' }) })
expect(await router.online()).toEqual({ ok: false, message: 'sign in again', code: 'SESSION_OVER' })
// Only a word: anything else on the error stays behind.
fleet.online = vi.fn(async () => { throw Object.assign(new Error('odd'), { code: 42 }) })
expect(await router.online()).toEqual({ ok: false, message: 'odd' })
})
})
describe('an answer reviewed on a device', () => {
const answer: ReviewedAnswer = {
agentId: 'a1', requestId: 'question-1',
questions: [{ key: 'scope', q: 'Which scope?', options: ['File', 'Project'], multi: false }],
answers: { scope: 'File' }, selections: { scope: ['File'] },
}
it('is confirmed by the local terminal, or says it could not be', async () => {
const answerReviewed = vi.fn(async () => true)
const router = new FleetRouter(localOf({ answerReviewed }, [session('a1', 1, 'claude')]))
expect(await router.answerReviewed(answer)).toEqual({ ok: true })
answerReviewed.mockResolvedValue(false)
expect(await router.answerReviewed(answer)).toEqual({ ok: false, error: 'Could not confirm the answer. Check the terminal.' })
expect(await new FleetRouter(localOf()).answerReviewed(answer)).toEqual({ ok: false, error: 'Update Harness to answer this question.' })
})
it('takes spoken free text only for a known local agent that can confirm it', async () => {
const answerReviewed = vi.fn(async () => true)
const fleet = fleetOf([REMOTE], { other: [{ id: 'r1', name: 'api' }] })
const router = new FleetRouter(localOf({ answerReviewed }, [session('a1', 1, 'claude')]), fleet)
await settled(router)
expect(router.canSpeakQuestion('a1')).toBe(true)
expect(router.canSpeakQuestion('r1')).toBe(false)
expect(router.canSpeakQuestion('ghost')).toBe(false)
// A known local agent on a daemon that cannot confirm a reviewed answer.
const unconfirmed = new FleetRouter(localOf({}, [session('a1', 1)]))
await unconfirmed.listAgentsFlat()
expect(unconfirmed.canSpeakQuestion('a1')).toBe(false)
const spoken = { ...answer, freeTextKeys: ['scope'] }
expect(await router.answerReviewed(spoken)).toEqual({ ok: true })
expect(await router.answerReviewed({ ...spoken, agentId: 'r1' })).toEqual({ ok: false, error: 'Use the terminal to type this answer.' })
expect(await router.answerReviewed({ ...answer, freeTextKeys: [] })).toEqual({ ok: true })
})
it('is handed to a remote machine, never to one that is unreachable, and never as a comma-split multi-select', async () => {
const fleet = fleetOf([REMOTE])
const router = new FleetRouter(localOf(), fleet)
router.noteAgent('other', 'r1')
const remote = { ...answer, agentId: 'r1' }
// An older fleet that has only the plain answer.
expect(await router.answerReviewed(remote)).toEqual({ ok: true, pending: true })
expect(fleet.answer).toHaveBeenCalledWith('other', 'r1', 'question-1', { scope: 'File' })
fleet.answerReviewed = vi.fn()
expect(await router.answerReviewed(remote)).toEqual({ ok: true, pending: true })
expect(fleet.answerReviewed).toHaveBeenCalledWith('other', remote)
fleet.reachable = () => ({ ok: false, at: Date.now() })
expect(await router.answerReviewed(remote)).toEqual({ ok: false, error: 'That machine is unavailable. Check its connection.' })
fleet.reachable = () => ({ ok: true, at: Date.now() })
const multi = { ...remote, questions: [{ ...remote.questions[0], multi: true }] }
expect(await router.answerReviewed({ ...multi, selections: { scope: ['CSV, UTF-8'] } })).toEqual({ ok: false, error: 'Use the terminal for this multi-select answer.' })
expect(await router.answerReviewed({ ...multi, selections: {} })).toEqual({ ok: true, pending: true })
expect(await router.answerReviewed({ ...multi, selections: { scope: ['CSV'] } })).toEqual({ ok: true, pending: true })
// No fleet at all: a remote agent heard from cannot be answered.
const alone = new FleetRouter(localOf())
alone.noteAgent('other', 'r1')
expect(await alone.answerReviewed(remote)).toEqual({ ok: false, error: 'That machine is unavailable. Check its connection.' })
})
})