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 { fakeCore } from '../testing/fakeCore.js'
import { ContributionPreparations, prepareContribution, prepareTeamContribution, setMachineAgents } from './contribution.js'
import { SuperTabHostError } from './wire.js'
import { mkdtemp, rm, stat } from 'node:fs/promises'
import { homedir, tmpdir } from 'node:os'
import { join } from 'node:path'
import { swarmReply } from './fixtures/read/index.js'
const GiB = 1024 ** 3
function fixture() {
const core = fakeCore()
const state: Record<string, unknown> = { project: { machineId: core.daemon.machineId(), cwd: '/repo', repositoryUrl: 'https://github.com/example/project' } }
const backend = vi.fn(async (_core: unknown, _method: string, path: string) => swarmReply(path, state))
const close = vi.fn()
const request = vi.fn(async () => ({ engines: [
{ engine: 'claude', installed: true, signedIn: true },
{ engine: 'codex', installed: true, signedIn: false },
{ engine: 'pi', installed: true },
{ engine: 'opencode', installed: false },
{ engine: 'terminal', installed: true },
] }))
const open = vi.fn(async () => ({ request, close }))
const prepare = vi.fn(async () => '/clone')
const capacity = vi.fn(async () => ({ ok: true, resources: { memoryTotalBytes: 32 * GiB, memoryUsedBytes: 16 * GiB, projectDiskFreeBytes: 100 * GiB } }))
const deps = { backend, open, prepare, capacity }
const run = () => prepareContribution(core, { tabId: 'tab' }, deps as never)
return { run, state, deps, core, request, close }
}
describe('one-field machine preparation', () => {
// #1726: a whole Swarm is no longer read; its parts are, through the daemon's Swarm reads.
it('reads the Swarm by parts, as the person', async () => {
const f = fixture()
await f.run()
expect(f.deps.backend.mock.calls.map(c => [c[1], c[2]])).toEqual([['GET', '/api/super-tabs/tab/parts']])
})
it('contributes a swarm workspace without asking for a project or cloning one', async () => {
const f = fixture()
const dataDir = await mkdtemp(join(tmpdir(), 'harness-swarm-contribution-'))
try {
delete f.state.project
const core = fakeCore({ dataDir })
const result = await prepareContribution(core, { tabId: 'tab', scope: 'swarm' }, f.deps as never)
const cwd = join(homedir(), 'harnesses', 'swarms', 'tab')
expect(result).toMatchObject({ scope: 'swarm', cwd, engines: ['claude', 'codex'] })
expect((await stat(cwd)).isDirectory()).toBe(true)
expect(f.deps.prepare).not.toHaveBeenCalled()
expect(f.deps.capacity).toHaveBeenCalledWith({ cwd, tools: ['git'], devices: [] })
} finally {
await rm(join(homedir(), 'harnesses', 'swarms', 'tab'), { recursive: true, force: true })
await rm(dataDir, { recursive: true, force: true })
}
})
// A Mac's Harness Team account reads no Swarm as the person (backend lib/teamSession.ts): its Mac's daemon adds it, and it
// prepares its own swarm workspace without that read ("One machine", docs/plans/2026-10-24-swarm-team-account.md).
it('prepares a Harness Team account\'s swarm workspace without reading the Swarm, and only that', async () => {
const f = fixture()
const dataDir = await mkdtemp(join(tmpdir(), 'harness-swarm-contribution-'))
try {
const core = fakeCore({ dataDir })
const team = { ...f.deps, team: () => true }
const result = await prepareContribution(core, { tabId: 'tab', scope: 'swarm' }, team as never)
expect(result).toMatchObject({ scope: 'swarm', cwd: join(homedir(), 'harnesses', 'swarms', 'tab'), engines: ['claude', 'codex'] })
expect(f.deps.backend).not.toHaveBeenCalled()
await expect(prepareContribution(core, { tabId: 'tab' }, team as never)).rejects.toThrow('swarm')
} finally {
await rm(join(homedir(), 'harnesses', 'swarms', 'tab'), { recursive: true, force: true })
await rm(dataDir, { recursive: true, force: true })
}
})
it('uses the lead project on its host and probes all engines without inventing authentication', async () => {
const f = fixture()
expect(await f.run()).toEqual({ ok: true, state: 'ready', cwd: '/repo', engines: ['claude', 'codex'], maxAgents: 8, maxAvailableAgents: 16 })
expect(f.request).toHaveBeenCalledWith('engines_probe', { engines: ['claude', 'codex'], accounts: true }, 20000)
expect(f.deps.prepare).not.toHaveBeenCalled()
expect(f.close).toHaveBeenCalledOnce()
})
it('offers installed Claude and Codex even when the account probe reports no vendor login', async () => {
const f = fixture()
f.request.mockResolvedValueOnce({ engines: [
{ engine: 'claude', installed: true, signedIn: false },
{ engine: 'codex', installed: true, signedIn: false },
{ engine: 'opencode', installed: true, signedIn: true },
{ engine: 'kilo', installed: true, signedIn: true },
] })
expect(await f.run()).toMatchObject({ engines: ['claude', 'codex'] })
})
it.each([
{ totalGiB: 32, usedGiB: 30, maxAgents: 8, maxAvailableAgents: 16 },
{ totalGiB: 16, usedGiB: 15, maxAgents: 4, maxAvailableAgents: 8 },
{ totalGiB: 64, usedGiB: 63, maxAgents: 16, maxAvailableAgents: 32 },
// The Mac Studio: every 2 GB may run an agent, while the starting suggestion stays at today's 16 (Ken, 2026-10-28).
{ totalGiB: 192, usedGiB: 100, maxAgents: 16, maxAvailableAgents: 96 },
// Every machine may offer 4, whatever its RAM; a small one still starts at what it suggested before.
{ totalGiB: 8, usedGiB: 7, maxAgents: 2, maxAvailableAgents: 4 },
{ totalGiB: 2, usedGiB: 1, maxAgents: 1, maxAvailableAgents: 4 },
// The server refuses more than 1024 (backend superTabs/commands.ts).
{ totalGiB: 4096, usedGiB: 1, maxAgents: 16, maxAvailableAgents: 1024 },
])('suggests $maxAgents of $maxAvailableAgents slots from $totalGiB GiB total RAM', async ({ totalGiB, usedGiB, maxAgents, maxAvailableAgents }) => {
const f = fixture()
f.deps.capacity.mockResolvedValueOnce({ ok: true, resources: {
memoryTotalBytes: totalGiB * GiB, memoryUsedBytes: usedGiB * GiB, projectDiskFreeBytes: 100 * GiB,
} })
expect(await f.run()).toMatchObject({ maxAgents, maxAvailableAgents })
})
it('keeps the suggestion when free RAM changes but total RAM does not', async () => {
const f = fixture()
const slots = async (freeBytes: number) => {
f.deps.capacity.mockResolvedValueOnce({ ok: true, resources: { memoryTotalBytes: 32 * GiB, memoryUsedBytes: 32 * GiB - freeBytes, projectDiskFreeBytes: 100 * GiB } })
return (await f.run() as { maxAgents?: number }).maxAgents
}
expect(await slots(5.3 * GiB)).toBe(8)
expect(await slots(GiB)).toBe(8)
expect(await slots(30 * GiB)).toBe(8)
})
it('prepares the repository on another machine and reuses an existing contribution', async () => {
const f = fixture(); (f.state.project as Record<string, unknown>).machineId = 'another'
expect(await f.run()).toMatchObject({ cwd: '/clone' })
expect(f.deps.prepare).toHaveBeenCalledWith({ source: 'remote', repositoryUrl: 'https://github.com/example/project.git', name: 'project' })
f.state.machines = [{ machineId: f.core.daemon.machineId(), cwd: '/existing' }]
expect(await f.run()).toMatchObject({ cwd: '/existing' })
expect(f.deps.prepare).toHaveBeenCalledOnce()
})
it('does not clone paths or credential-bearing URLs from shared metadata', async () => {
const f = fixture()
for (const repositoryUrl of [null, 'file:///private/repo', 'https://[email protected]/example/project', 'ext::command']) {
f.state.project = { machineId: 'other', repositoryUrl }
await expect(f.run()).rejects.toThrow()
}
expect(f.deps.prepare).not.toHaveBeenCalled()
expect(f.deps.open).not.toHaveBeenCalled()
})
it('fails when no installed engine or project disk can be read and closes the connection', async () => {
const f = fixture()
f.request.mockResolvedValueOnce({ engines: [] })
await expect(f.run()).rejects.toThrow('Install Claude Code or Codex')
f.deps.capacity.mockResolvedValueOnce({ error: 'INVALID_REQUEST' } as never)
await expect(f.run()).rejects.toThrow('project folder')
expect(f.close).toHaveBeenCalledTimes(2)
})
it('keeps a slow clone in one bounded receipt and preserves errors for polling', async () => {
let resolve!: (value: Record<string, unknown>) => void
const prepare = vi.fn(() => new Promise<Record<string, unknown>>(r => { resolve = r }))
const jobs = new ContributionPreparations(prepare), input = { operationId: 'setup', tabId: 'tab' }
expect(jobs.read(input)).toMatchObject({ state: 'preparing' })
expect(jobs.read(input)).toMatchObject({ state: 'preparing' })
expect(prepare).toHaveBeenCalledOnce()
expect(jobs.read({ ...input, tabId: 'elsewhere' })).toEqual({ error: 'OPERATION_CONFLICT' })
resolve({ ok: true, state: 'ready', cwd: '/clone' }); await Promise.resolve()
expect(jobs.read(input)).toMatchObject({ state: 'ready', cwd: '/clone' })
jobs.clear(); jobs.read(input); expect(prepare).toHaveBeenCalledTimes(2)
const failed = new ContributionPreparations(async () => { throw new Error('Clone failed') })
failed.read(input); await Promise.resolve()
expect(failed.read(input)).toEqual({ error: 'SETUP_FAILED', detail: 'Clone failed' })
})
it('bounds pending setups and refuses invalid receipt keys', () => {
const jobs = new ContributionPreparations(() => new Promise(() => {}))
expect(jobs.read({ tabId: 'tab' })).toEqual({ error: 'INVALID_REQUEST' })
for (let i = 0; i < 32; i++) jobs.read({ tabId: 'tab', operationId: `setup-${i}` })
expect(jobs.read({ tabId: 'tab', operationId: 'extra' })).toMatchObject({ error: 'SETUP_BUSY' })
})
})
describe('this Mac\'s Harness Team account preparing through the relay', () => {
function relay(answers: Record<string, unknown>[]) {
const core = fakeCore()
const request = vi.fn(async () => answers.shift() ?? { ok: true, state: 'preparing' })
const close = vi.fn()
const open = vi.fn(async () => ({ machineId: 'team-1', request, close }))
let clock = 0
const deps = { open, sleep: vi.fn(async () => { clock += 1_000 }), deadlineMs: 3_000, now: () => clock }
return { core, request, close, open, deps }
}
it('asks the team account\'s own daemon, keeps one receipt while it prepares, and closes the line', async () => {
const r = relay([{ ok: true, state: 'preparing' }, { ok: true, state: 'ready', scope: 'swarm', cwd: '/Users/harnessteam/harnesses/swarms/tab', engines: ['codex'] }])
expect(await prepareTeamContribution(r.core, { tabId: 'tab', machineId: 'team-1' }, r.deps as never)).toMatchObject({ cwd: '/Users/harnessteam/harnesses/swarms/tab' })
expect(r.open).toHaveBeenCalledWith({ dataDir: r.core.dataDir, port: r.core.daemon.port, machineId: r.core.daemon.machineId() }, 'team-1')
const [first, second] = r.request.mock.calls as unknown as [string, Record<string, unknown>][]
expect(first![1]).toMatchObject({ action: 'prepareContribution', tabId: 'tab', scope: 'swarm' })
expect(second![1].operationId).toBe(first![1].operationId)
expect(r.close).toHaveBeenCalledOnce()
})
it('says why it could not, and gives up after its deadline', async () => {
const failed = relay([{ error: 'SETUP_FAILED', detail: 'Install Claude Code or Codex on this machine, then try again.' }])
await expect(prepareTeamContribution(failed.core, { tabId: 'tab', machineId: 'team-1' }, failed.deps as never)).rejects.toThrow('Install Claude Code or Codex')
const slow = relay([])
await expect(prepareTeamContribution(slow.core, { tabId: 'tab', machineId: 'team-1' }, slow.deps as never)).rejects.toThrow('still preparing')
expect(slow.close).toHaveBeenCalledOnce()
})
})
describe('the owner setting how many agents a machine offers, from a terminal', () => {
function owned(totalGiB: number | null, machine: Record<string, unknown> = {}) {
const core = fakeCore()
const state: Record<string, unknown> = { machines: [{ machineId: 'studio', name: 'Mac Studio', contributorId: 'ken', cwd: '/Users/ken/harnesses/swarms/tab', scope: 'swarm',
// A machine added before Swarms ran only Claude Code and Codex lists every engine it had; the server takes only those two.
engines: ['claude', 'codex', 'opencode'], maxAgents: 16, paused: false,
...(totalGiB === null ? {} : { observation: { generation: 'g1', resources: { memoryTotalBytes: totalGiB * GiB, memoryUsedBytes: GiB } } }), ...machine }] }
const sent: Record<string, unknown>[] = []
const backend = vi.fn(async (_core: unknown, method: string, path: string, body?: unknown) => {
if (method === 'GET') return swarmReply(path, state)
sent.push(body as Record<string, unknown>)
return { result: {} }
})
const set = (maxAgents: number) => setMachineAgents(core, { tabId: 'tab', machineId: 'studio', maxAgents }, { backend } as never)
return { set, sent, backend }
}
it('changes only the number, keeping the machine\'s name, folder and engines', async () => {
const f = owned(192)
expect(await f.set(96)).toEqual({ ok: true, machineId: 'studio', maxAgents: 96, maximum: 96 })
expect(f.sent).toHaveLength(1)
expect(f.sent[0]!.command).toEqual({ type: 'machine.contribute', machineId: 'studio', name: 'Mac Studio', cwd: '/Users/ken/harnesses/swarms/tab',
scope: 'swarm', engines: ['claude', 'codex'], maxAgents: 96, agents: 'atMost' })
expect(String(f.sent[0]!.operationId)).toMatch(/^machine-agents-/)
})
it('refuses a number above the machine\'s maximum, and says what the maximum is', async () => {
const big = owned(192)
expect(await big.set(97)).toEqual({ error: 'ABOVE_MACHINE_MAXIMUM', detail: 'Mac Studio can offer at most 96 agents: one for every 2 GB of its memory, and at least 4.' })
const small = owned(8)
expect(await small.set(5)).toMatchObject({ error: 'ABOVE_MACHINE_MAXIMUM', detail: expect.stringContaining('at most 4 agents') })
expect([...big.sent, ...small.sent]).toEqual([])
// Every machine may offer 4, whatever its memory.
expect(await owned(2).set(4)).toMatchObject({ ok: true, maxAgents: 4, maximum: 4 })
})
it('refuses a machine that is not in the Swarm, or whose memory it has not reported', async () => {
const f = owned(192, { machineId: 'other' })
expect(await f.set(8)).toEqual({ error: 'MACHINE_NOT_FOUND', detail: 'This machine is not in this Swarm. Add it from Desktop first.' })
const unread = owned(null)
expect(await unread.set(8)).toEqual({ error: 'MACHINE_MEMORY_UNKNOWN', detail: 'Mac Studio has not reported its memory yet. Try again once it is online.' })
expect([...f.sent, ...unread.sent]).toEqual([])
})
// The server keeps a paused machine paused when its settings are sent again (review of #2084).
it('changes a paused machine\'s number too, sending no pause of its own', async () => {
const f = owned(192, { paused: true })
expect(await f.set(32)).toEqual({ ok: true, machineId: 'studio', maxAgents: 32, maximum: 96 })
expect(f.sent.map(body => body.command)).toEqual([{ type: 'machine.contribute', machineId: 'studio', name: 'Mac Studio', cwd: '/Users/ken/harnesses/swarms/tab',
scope: 'swarm', engines: ['claude', 'codex'], maxAgents: 32, agents: 'atMost' }])
})
it('passes on the server\'s refusal, such as another person\'s machine', async () => {
const f = owned(192)
const read = f.backend.getMockImplementation()!
f.backend.mockImplementation(async (core: unknown, method: string, path: string, body?: unknown) => {
if (method === 'GET') return read(core, method, path, body)
throw new SuperTabHostError('OWNER_REQUIRED', 'Only the machine owner can contribute it.', 403)
})
await expect(f.set(8)).rejects.toMatchObject({ code: 'OWNER_REQUIRED', status: 403 })
})
it('says so when an older server could only take 16', async () => {
const f = owned(192)
f.backend.mockImplementation(async (_core: unknown, method: string, path: string, body?: unknown) => {
if (method === 'GET') return swarmReply(path, { machines: [{ machineId: 'studio', name: 'Mac Studio', cwd: '/w', scope: 'swarm', engines: ['claude'], maxAgents: 2,
observation: { resources: { memoryTotalBytes: 192 * GiB } } }] })
const command = (body as { command: { maxAgents: number } }).command
if (command.maxAgents > 16) throw new SuperTabHostError('VALIDATION_ERROR', 'command.maxAgents: Too big: expected number to be <=16', 400)
f.sent.push(body as Record<string, unknown>)
return { result: {} }
})
expect(await f.set(96)).toEqual({ ok: true, machineId: 'studio', maxAgents: 16, maximum: 96,
notice: 'This Swarm\'s server takes at most 16 agents per machine, so Mac Studio now offers 16. Update the server to offer more.' })
expect(f.sent.map(b => (b.command as { maxAgents: number }).maxAgents)).toEqual([16])
})
})