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
import { describe, expect, it, vi } from 'vitest'
import type { AgentFrame } from '../../lib/agentFrame.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { createAgentList, deviceAgentListItem, deviceAgentRow, type AgentListDeps } from './list.js'
/**
* `agents_list`, answered by the core: the frames the socket builds, in one order every surface shares,
* the stopped agents only for a window that asks, a device's rows trimmed to what it draws, and the
* monitor's readings read outside the connection's ordered requests.
*/
const session = (agentId: string, over: Partial<RegisteredSession> = {}) =>
({ agentId, sessionId: `${agentId}-session`, engine: 'claude', ...over }) as RegisteredSession
/** A frame names its agent, its engine and when it was made: what the list sorts and trims by. */
const frame = (s: RegisteredSession, createdAt: string, status = 'active') =>
({ id: s.agentId, name: `${s.agentId} name`, engine: s.engine, createdAt, status, selectedModel: null, userId: 'u' }) as unknown as AgentFrame
function setup(live: RegisteredSession[], saved: RegisteredSession[] = [], over: Partial<AgentListDeps> = {}) {
const created = new Map<string, string>()
const deps: AgentListDeps = {
registry: { advertised: vi.fn(() => live) },
stoppedAgents: { available: vi.fn(() => saved) },
toProject: vi.fn(async (s) => frame(s, created.get(s.agentId) ?? '2026-10-05T10:00:00.000Z')),
toStoppedProject: vi.fn(async (s) => frame(s, created.get(s.agentId) ?? '2026-10-05T10:00:00.000Z', 'stopped')),
harnessResourcesReader: vi.fn(async () => ({ sampledAt: '2026-10-05T12:00:00.000Z', agents: [] })),
harnessStorageReader: vi.fn(async () => new Map()),
monitorActivityProvider: null,
monitorCompletions: { state: vi.fn(() => 'idle' as const) },
...over,
}
const replies: Array<Record<string, any>> = []
const ask = (payload: Record<string, unknown>, role: string | null = 'web') =>
createAgentList(deps).agentsList(payload, () => role, (result) => { replies.push(result) })
return { deps, created, replies, ask }
}
describe('the agents a guest asks for', () => {
// A guest (a session of an account this machine is shared with) sees the harnesses it started and nothing
// of the owner's (docs/plans/2026-10-19-guest-machine-sharing-plan.md).
it('only its own harnesses, oldest first; never the owner\'s, the stopped, the cloud ones or the monitor\'s readings', async () => {
const [mine, also, older, owners, theirs] = [session('mine', { guest: '[email protected]' }), session('also', { guest: '[email protected]' }), session('older', { guest: '[email protected]' }), session('owners'), session('theirs', { guest: '[email protected]' })]
const cloud = vi.fn(() => [])
const { created, replies, deps } = setup([mine, also, older, owners, theirs], [session('saved', { guest: '[email protected]' })], { cloudFrames: cloud })
created.set('older', '2026-10-05T09:00:00.000Z')
await createAgentList(deps).agentsList({ includeStopped: true, monitor: true }, () => 'web', (r) => { replies.push(r) }, '[email protected]')
// Made at the same time, the id breaks the tie.
expect(replies).toEqual([{ agents: [expect.objectContaining({ id: 'older' }), expect.objectContaining({ id: 'also' }), expect.objectContaining({ id: 'mine' })] }])
expect(deps.stoppedAgents.available).not.toHaveBeenCalled()
expect(cloud).not.toHaveBeenCalled()
expect(deps.harnessResourcesReader).not.toHaveBeenCalled()
// A share recorded before its account was: a guest that owns nothing.
replies.length = 0
await createAgentList(deps).agentsList({}, () => 'web', (r) => { replies.push(r) }, '')
expect(replies).toEqual([{ agents: [] }])
})
})
describe('the agents a window asks for', () => {
it('every live agent\'s frame, oldest first, an id breaking a tie, and nothing stopped unless asked for', async () => {
const [a, b, c] = [session('b-agent'), session('a-agent'), session('c-agent')]
const { created, replies, ask, deps } = setup([a, b, c], [session('saved')])
created.set('b-agent', '2026-10-05T10:00:00.000Z')
created.set('a-agent', '2026-10-05T10:00:00.000Z')
created.set('c-agent', '2026-10-05T09:00:00.000Z')
await ask({})
expect(replies).toHaveLength(1)
expect(Object.keys(replies[0])).toEqual(['agents'])
expect(replies[0].agents.map((agent: AgentFrame) => agent.id)).toEqual(['c-agent', 'a-agent', 'b-agent'])
expect(deps.stoppedAgents.available).not.toHaveBeenCalled()
expect(deps.toStoppedProject).not.toHaveBeenCalled()
await ask({ includeStopped: 'yes' })
expect(deps.stoppedAgents.available).not.toHaveBeenCalled()
})
it('the stopped agents a person can resume, when a window asks, beside the live ones', async () => {
const live = [session('live')]
const { created, replies, ask, deps } = setup(live, [session('saved')])
created.set('saved', '2026-10-05T08:00:00.000Z')
await ask({ includeStopped: true })
expect(deps.stoppedAgents.available).toHaveBeenCalledWith(live)
expect(replies[0].agents.map((agent: AgentFrame) => [agent.id, agent.status])).toEqual([['saved', 'stopped'], ['live', 'active']])
})
})
describe('the cloud harnesses', () => {
const cloud = (id: string, createdAt: string, status = 'active') => ({ id, name: id, engine: 'fo', createdAt, status, selectedModel: null, location: 'cloud' }) as never
it('are listed with the rest in the same order, and a stopped one only where stopped agents are asked for', async () => {
const a1 = session('a1')
const { ask, replies } = setup([a1], [], { cloudFrames: () => [cloud('cloud_1', '2026-10-05T09:00:00.000Z'), cloud('cloud_2', '2026-10-05T11:00:00.000Z', 'stopped')] })
await ask({})
expect(replies[0].agents.map((agent: { id: string }) => agent.id)).toEqual(['cloud_1', 'a1'])
await ask({ includeStopped: true })
expect(replies[1].agents.map((agent: { id: string }) => agent.id)).toEqual(['cloud_1', 'a1', 'cloud_2'])
await ask({ includeStopped: true }, 'device')
expect(replies[2].agents).toEqual([{ id: 'cloud_1', name: 'cloud_1', engine: 'fo', selectedModel: null }, { id: 'a1', name: 'a1 name', engine: 'claude', selectedModel: null }])
})
})
describe('the agents a device asks for', () => {
it('only the rows it drives, at most a hundred, each with only what its firmware reads, and never a stopped one', async () => {
const live = [session('shell', { engine: 'terminal' }), ...Array.from({ length: 105 }, (_, i) => session(`agent-${String(i).padStart(3, '0')}`))]
const { replies, ask, deps } = setup(live, [session('saved')])
await ask({ includeStopped: true, monitor: true }, 'device')
expect(deps.stoppedAgents.available).not.toHaveBeenCalled()
expect(deps.harnessResourcesReader).not.toHaveBeenCalled()
expect(replies).toHaveLength(1)
expect(Object.keys(replies[0])).toEqual(['agents'])
expect(replies[0].agents).toHaveLength(100)
expect(replies[0].agents[0]).toStrictEqual({ id: 'agent-000', name: 'agent-000 name', engine: 'claude', selectedModel: null })
expect(replies[0].agents.some((agent: { id: string }) => agent.id === 'shell')).toBe(false)
})
})
describe('the monitor\'s readings', () => {
it('are read after the list is answered for, so they never hold the connection\'s next request', async () => {
let read!: (value: { sampledAt: string; agents: [] }) => void
const { replies, ask } = setup([session('live')], [], {
harnessResourcesReader: vi.fn(() => new Promise<{ sampledAt: string; agents: [] }>((resolve) => { read = resolve })),
})
await ask({ monitor: true })
expect(replies).toEqual([])
read({ sampledAt: '2026-10-05T12:00:00.000Z', agents: [] })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(Object.keys(replies[0])).toEqual(['agents', 'sharedResources', 'sampledAt'])
})
it('each agent\'s activity, processes and storage, in the order they always went out', async () => {
const working = session('working', { processIdentity: { pid: 4242 } as RegisteredSession['processIdentity'] })
const finished = session('finished')
const unread = session('unread')
const saved = session('saved')
const activity: Record<string, 'working' | 'idle'> = { 'working-session': 'working', 'finished-session': 'idle', 'unread-session': 'idle' }
const { created, replies, ask, deps } = setup([working, finished, unread], [saved], {
harnessResourcesReader: vi.fn(async () => ({
sampledAt: '2026-10-05T12:00:00.000Z',
agents: [
{ agentId: 'working', memoryBytes: 123, cpuPercent: 2, processCount: 3, gpuMemoryBytes: 4, gpuPercent: 5,
diskReadBytesPerSecond: 6, diskWriteBytesPerSecond: 7, processes: [{ pid: 4242, parent: 1, memoryBytes: 123, cpuPercent: 2 }] },
{ agentId: 'finished', memoryBytes: 9, cpuPercent: null, processCount: 1 },
{ agentId: 'saved', memoryBytes: 999, cpuPercent: 99, processCount: null },
],
shared: [{ kind: 'codex' as const, agentIds: ['working'], memoryBytes: 1, cpuPercent: 1, processCount: 1 }],
})),
harnessStorageReader: vi.fn(async () => new Map([['working', { workspaceBytes: 10, transcriptBytes: 11 }]]) as never),
monitorActivityProvider: (sessionId) => activity[sessionId],
monitorCompletions: { state: vi.fn((s: RegisteredSession) => (s.agentId === 'finished' ? 'done' as const : 'idle' as const)) },
})
created.set('working', '2026-10-05T09:00:00.000Z')
created.set('finished', '2026-10-05T09:01:00.000Z')
created.set('unread', '2026-10-05T09:02:00.000Z')
created.set('saved', '2026-10-05T09:03:00.000Z')
await ask({ monitor: true, includeStopped: true })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(deps.harnessStorageReader).toHaveBeenCalledWith([working, finished, unread, saved])
const monitor = (id: string) => replies[0].agents.find((agent: AgentFrame) => agent.id === id).monitor
expect(Object.keys(monitor('working'))).toEqual([
'activity', 'activityKnown', 'rssBytes', 'cpu', 'pid', 'sampledAt', 'processCount', 'gpuMemoryBytes', 'gpuPercent',
'diskReadBytesPerSecond', 'diskWriteBytesPerSecond', 'processes', 'workspaceBytes', 'transcriptBytes',
])
expect(monitor('working')).toStrictEqual({
activity: 'working', activityKnown: true, rssBytes: 123, cpu: 2, pid: 4242, sampledAt: '2026-10-05T12:00:00.000Z',
processCount: 3, gpuMemoryBytes: 4, gpuPercent: 5, diskReadBytesPerSecond: 6, diskWriteBytesPerSecond: 7,
processes: [{ pid: 4242, parent: 1, memoryBytes: 123, cpuPercent: 2 }], workspaceBytes: 10, transcriptBytes: 11,
})
// Idle by its turns and questions: how its last turn ended. Counted processes, but no process of its own on record.
expect(monitor('finished')).toMatchObject({ activity: 'done', rssBytes: 9, cpu: null, pid: null, processCount: 1, gpuMemoryBytes: null, processes: [] })
// Nothing read for it at all.
expect(monitor('unread')).toMatchObject({ activity: 'idle', rssBytes: null, cpu: null, pid: null, processCount: null })
// A stopped agent uses nothing, whatever a reading says, and has no turn to report.
expect(monitor('saved')).toMatchObject({ activity: 'idle', rssBytes: 0, cpu: 0, pid: null })
expect(replies[0].sharedResources).toEqual([{ kind: 'codex', agentIds: ['working'], memoryBytes: 1, cpuPercent: 1, processCount: 1 }])
expect(replies[0].sampledAt).toBe('2026-10-05T12:00:00.000Z')
})
it('readings that fail read as none, and an activity no one knows reads from the last turn alone', async () => {
const live = session('live')
const { replies, ask } = setup([live], [], {
harnessResourcesReader: vi.fn(async () => { throw new Error('ps failed') }),
harnessStorageReader: vi.fn(async () => { throw new Error('du failed') }),
monitorCompletions: { state: vi.fn(() => 'failed' as const) },
})
await ask({ monitor: true })
await vi.waitFor(() => expect(replies).toHaveLength(1))
expect(replies[0].sharedResources).toEqual([])
expect(replies[0].sampledAt).toBeNull()
expect(replies[0].agents[0].monitor).toMatchObject({ activity: 'failed', activityKnown: false, rssBytes: null, sampledAt: null })
})
it('a monitor that cannot be put together is answered UNAVAILABLE', async () => {
const { replies, ask } = setup([session('live')], [], {
monitorCompletions: { state: vi.fn(() => { throw new Error('broken') }) },
})
await ask({ monitor: true })
await vi.waitFor(() => expect(replies).toEqual([{ error: 'UNAVAILABLE' }]))
})
})
describe('the device\'s rows', () => {
it('a name the firmware cannot hold is clipped, by characters and by bytes, with an ellipsis', () => {
expect(deviceAgentListItem({ id: 'a', name: 'Short name' }).name).toBe('Short name')
expect(deviceAgentListItem({ id: 'a', name: 'A name far too long for the dial' }).name).toBe('A name far too …')
// Fifteen characters, but more bytes than the firmware's forty: cut where the bytes run out.
expect(deviceAgentListItem({ id: 'a', name: '漢字漢字漢字漢字漢字漢字漢字漢' }).name).toBe('漢字漢字漢字漢字漢字漢字…')
})
it('keeps the id, a process engine and the model profile, and nothing else', () => {
expect(deviceAgentListItem(null)).toStrictEqual({ id: undefined })
expect(deviceAgentListItem({ id: 'a', name: 7, engine: 'terminal', selectedModel: 3, userId: 'secret' })).toStrictEqual({ id: 'a' })
expect(deviceAgentListItem({ id: 'a', engine: 'codex', selectedModel: 'runtime-v1:s:codex:gpt@high' }))
.toStrictEqual({ id: 'a', engine: 'codex', selectedModel: 'runtime-v1:s:codex:gpt@high' })
expect(deviceAgentListItem({ id: 'a', engine: 42, selectedModel: null })).toStrictEqual({ id: 'a', selectedModel: null })
// A cloud agent is driven from the dial too: its question screen answers it.
expect(deviceAgentListItem({ id: 'cloud_1', engine: 'devin-cloud', selectedModel: null })).toStrictEqual({ id: 'cloud_1', engine: 'devin-cloud', selectedModel: null })
})
it('a terminal is no row of a device\'s; anything else is', () => {
expect(deviceAgentRow({ engine: 'terminal' })).toBe(false)
expect(deviceAgentRow({ engine: 'claude' })).toBe(true)
expect(deviceAgentRow(undefined)).toBe(true)
expect(deviceAgentRow({ engine: 5 })).toBe(true)
})
})