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
Swarm: the Lead starts agents only on the Swarm's listed machines (#1489)
0xken15cbb783f2a61d
diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 33031fb5e..fce6f905a 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -970,6 +970,22 @@ describe('Super Tabs on a real Mongo replica set', () => {expect(response.statusCode).toBe(200)})+ it('returns the receipt of a recorded agent start after its machine stops being listed', async () => {+ const { tab, lead } = await fixture()+ const machineId = `second-${randomUUID()}`+ await db.machine.create({ data: { machineId, userId: host.sub, apiKey: 'fixture-only', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ await db.machineShare.create({ data: { machineId, ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })+ const helper = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId, harnessId: randomUUID(), name: 'Helper', configuration: config, lead: false })).result.agentId as string+ const request = { conversationId: 'lead', machineId, engine: 'codex', name: 'Builder', cwd: '/work', worktree: true,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }+ const operationId = randomUUID(), command: Command = { type: 'agent.start', request }+ const first = await run(tab, command, host, lead, operationId)+ await run(tab, { type: 'agent.remove', agentId: helper })+ // A new start on the machine is refused now, but the recorded one keeps its receipt.+ await expect(run(tab, command, host, lead)).rejects.toMatchObject({ code: 'MACHINE_NOT_LISTED' })+ expect((await run(tab, command, host, lead, operationId)).result.startId).toBe(first.result.startId)+ })+it('corrects the log to the model that ran when the routed switch failed, and reads the times of one decision', async () => {const { tab, lead } = await fixture()const decision = { assessment: { difficulty: 'low', risk: 'low', why: 'Docs.' },diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex da2d6f182..02f869c8c 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -201,7 +201,7 @@ it('starts only in the chosen conversation, captures authority, and never assignconst f = fixture(), lead = f.add('lead', 'owner', 'lead', true), group = f.group()const actor: Actor = { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' }const contribution = { machineOwnerId: 'target-owner', contributorId: 'owner', hostGrant: 'grant-1' }- const request = { conversationId: group, machineId: 'target', engine: 'claude', name: 'Builder', cwd: '/repo', worktree: true,+ const request = { conversationId: group, machineId: 'host', engine: 'claude', name: 'Builder', cwd: '/repo', worktree: true,requirements: { memoryBytes: 100, diskBytes: 200, maxCpuPercent: 80, tools: ['git'], devices: [], quotaRequired: false } }const startId = f.run({ type: 'agent.start', request }, actor, { contribution }).result.startId as stringexpect(f.state.starts![0]).toMatchObject({ request, hostGrant: 'grant-1', dispatched: false })@@ -218,6 +218,42 @@ it('starts only in the chosen conversation, captures authority, and never assignexpect(() => f.run({ type: 'agent.start', request }, actor, { contribution })).toThrow('paused')})+describe('agent.start on the Swarm\'s listed machines', () => {+ const request = (group: string, machineId: string) => ({ conversationId: group, machineId, engine: 'claude', name: 'Builder', cwd: '/repo', worktree: true,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } })+ const grant = { machineOwnerId: 'target-owner', contributorId: 'owner' }++ it('refuses an agent\'s start on a machine nobody listed, and records nothing', () => {+ const f = fixture(), lead = f.add('lead', 'owner', 'lead', true), group = f.group()+ const actor: Actor = { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' }+ expect(() => f.run({ type: 'agent.start', request: request(group, 'account-vm') }, actor, { contribution: grant }))+ .toThrow(expect.objectContaining({ code: 'MACHINE_NOT_LISTED', status: 403, message: 'Add this machine to the Swarm first.' }))+ expect(f.state.starts ?? []).toEqual([])+ })++ it('lets an agent start on the Lead\'s own machine, where an agent of the Swarm runs', () => {+ const f = fixture(), lead = f.add('lead', 'owner', 'lead', true), group = f.group()+ const actor: Actor = { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' }+ f.run({ type: 'agent.start', request: request(group, 'host') }, actor, { contribution: grant })+ expect(f.state.starts).toHaveLength(1)+ })++ it('lets an agent start on a contributed machine', () => {+ const f = fixture(), lead = f.add('lead', 'owner', 'lead', true), group = f.group()+ const actor: Actor = { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' }+ f.state.machines = [{ machineId: 'contributed', name: 'Mini', contributorId: 'owner', membershipGeneration: f.state.people[0]!.generation, generation: 'g1',+ cwd: '/repo', engines: ['claude'], maxAgents: 2, paused: false, observation: { receivedAt: 1000 } } as never]+ f.run({ type: 'agent.start', request: request(group, 'contributed') }, actor, { contribution: grant })+ expect(f.state.starts).toHaveLength(1)+ })++ it('keeps a person\'s start on a machine of their own, before anything is listed', () => {+ const f = fixture(), group = f.group()+ f.run({ type: 'agent.start', request: request(group, 'my-laptop') }, owner, { contribution: grant })+ expect(f.state.starts).toHaveLength(1)+ })+})+describe('tab.routingPolicy', () => {it('lets only the owner set or clear the tab override', () => {const f = fixture()@@ -244,6 +280,9 @@ const record = (patch: Record<string, unknown> = {}) => ({ assessment: { difficufunction routed() {const f = fixture()const lead = f.add('lead', 'owner', 'lead', true), worker = f.add('worker')+ // An agent runs on 'machine', so the Swarm lists it and a start there is allowed.+ f.run({ type: 'agent.add', conversationId: 'lead', machineId: 'machine', harnessId: 'remote', name: 'Remote', configuration: config, lead: false },+ owner, { contribution: { machineOwnerId: 'host-owner', contributorId: 'owner' } })const agentActor = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: 'host-owner' })const define = (group: string) => f.run({ type: 'work.define', conversationId: group, brief: 'Build it.', checks: [{ description: 'Tests pass.', independent: false }] })/** Records a completed native start for an agent, as the decision's `new` final refers to it. */diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 75df0ab8d..70eac2564 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -397,6 +397,11 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commacontrols(state, actor, command.request.conversationId)open(state, command.request.conversationId)if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')+ // The Lead's account has machines the Swarm never prepared (no clone of the project), so a Lead may start only where the+ // Swarm already lists a machine: a contributed one, or one an agent of the Swarm runs on. A person's start may name any+ // machine of theirs, because the first Lead is created before anything is listed.+ if (actor.kind === 'agent' && !state.machines?.some(m => m.machineId === command.request.machineId)+ && !state.agents.some(a => a.machineId === command.request.machineId)) fail('MACHINE_NOT_LISTED', 'Add this machine to the Swarm first.', 403)const grant = context.contribution ?? fail('HOST_REQUIRED', 'Choose a machine shared with the contributor.', 403)const contributor = person(state, grant.contributorId)if (contributor.role === 'viewer') fail('READ_ONLY', 'A viewer cannot start agents.', 403)diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.tsindex 75c064996..ba49fd1ec 100644--- a/cli/src/superTabs/routeCommand.spec.ts+++ b/cli/src/superTabs/routeCommand.spec.ts@@ -15,6 +15,8 @@ const policy = { version: 1, floor: { low: 1, medium: 2, high: 3 }, quotaReserveconst agents = [{ id: 'a1', name: 'Multiply', machineId: 'm1', harnessId: 'h1', configuration: { engine: 'claude', model: 'sonnet', effort: 'medium' } },{ id: 'lead', name: 'Lead', machineId: 'm1', harnessId: 'hl', configuration: { engine: 'claude', model: 'opus', effort: 'high' } },+ // An engine the route does not offer: it only puts m2 in the Swarm's Machines list, as a person adding the machine does.+ { id: 'a2', name: 'Elsewhere', machineId: 'm2', harnessId: 'h2', configuration: { engine: 'pi', model: 'default', effort: 'default' } },]const conversations = (assignment: unknown = null) => [{ id: 'lead', title: 'Lead', leadId: 'lead', agentIds: ['lead', 'a1'], archived: false, brief: '', checks: [], assignment: null },@@ -132,6 +134,54 @@ describe('routeTask', () => {const fine = await routeTask(input, scoped(), where as never, opener(), () => 'op')expect(fine.warnings).toEqual(['w'])})+ it('considers only the account machines the Swarm lists, and always the Lead\'s own', async () => {+ const context = { ok: true, value: { agentId: 'lead', tab: tab(), policy: { policy }, machines: [{ machineId: 'm1', name: 'remote-1' }, { machineId: 'm2', name: 'mac' }, { machineId: 'm9', name: 'vm' }] } }+ const s = scoped({ context }), open = opener()+ await routeTask(input, s, where as never, open, () => 'op')+ // m9 is the account's but not in the Swarm's list: it is neither probed nor a candidate nor an exclusion.+ expect(open.mock.calls.map(c => c[1]).sort()).toEqual(['m1', 'm2'])+ const decision = recorded(s).command.decision+ expect([...decision.candidates, ...decision.excluded].some((c: { title: string }) => c.title.includes('vm'))).toBe(false)+ expect(decision.candidates.some((c: { machineId?: string; title: string }) => c.title.includes('mac'))).toBe(true)+ })+ it('offers new agents on the Lead\'s own machine when the account list could not be read', async () => {+ const context = { ok: true, value: { agentId: 'lead', tab: tab(), policy: { policy }, machines: [], machinesUnreadable: true } }+ const s = scoped({ context }), open = opener()+ await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, s, where as never, open, () => 'op')+ expect(open.mock.calls.map(c => c[1])).toEqual(['m1'])+ expect(recorded(s).command.decision.candidates.some((c: { title: string }) => c.title.startsWith('New agent') && c.title.includes('m1'))).toBe(true)+ })+ it('says a listed machine without the project folder needs it cloned, not that its disk could not be verified', async () => {+ const needs = { cwd: '/repo/api' }+ const noFolder = { ok: true, resources: { memoryTotalBytes: 8e9, memoryUsedBytes: 1e9, cpuPercent: 10 }, tools: {}, devices: {} }+ const s = scoped()+ await routeTask({ ...input, assessment: { ...input.assessment, needs } }, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], capacity: id === 'm1' ? { ...noFolder, tools: { git: true } } : noFolder })), () => 'op')+ const excluded = recorded(s).command.decision.excluded as Array<{ title: string; reason: string }>+ const reasonOf = (machine: string) => excluded.filter(e => e.title.includes(machine)).map(e => e.reason)+ expect(reasonOf('mac').some(r => r.includes('This machine does not have the project folder. Add it to the Swarm so it can clone the project.'))).toBe(true)+ expect(reasonOf('mac').some(r => /Project disk space/.test(r))).toBe(false)+ // Its other reasons stay.+ expect(reasonOf('mac').some(r => /Required tool unavailable: git/.test(r))).toBe(true)+ // The Lead's own machine keeps the plain reason: its folder was named by the Lead itself.+ expect(reasonOf('remote-1').some(r => r.includes('Project disk space could not be verified.'))).toBe(true)+ })+ it('offers a listed machine whose capacity read measured the project folder', async () => {+ const s = scoped()+ await routeTask({ ...input, assessment: { ...input.assessment, needs: { cwd: '/repo/api' } } }, s, where as never,+ opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], capacity: { ok: true, resources: { memoryTotalBytes: 8e9, memoryUsedBytes: 1e9, cpuPercent: 10, projectDiskFreeBytes: 1e11 }, tools: { git: true }, devices: {} } })), () => 'op')+ expect(recorded(s).command.decision.candidates.some((c: { title: string }) => c.title.startsWith('New agent') && c.title.includes('mac'))).toBe(true)+ })+ it('keeps "could not be verified" on a listed machine whose capacity read failed, because a failed read says nothing about the folder', async () => {+ const s = scoped()+ await routeTask({ ...input, assessment: { ...input.assessment, needs: { cwd: '/repo/api' } } }, s, where as never,+ opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], ...(id === 'm2' ? { capacity: { ok: false, error: 'UNSUPPORTED' } } : {}) })), () => 'op')+ const reasons = (recorded(s).command.decision.excluded as Array<{ title: string; reason: string }>).filter(e => e.title.includes('mac')).map(e => e.reason)+ expect(reasons.length).toBeGreaterThan(0)+ for (const reason of reasons) {+ expect(reason).toContain('Project disk space could not be verified.')+ expect(reason).not.toContain('does not have the project folder')+ }+ })it('names a member that has no name, model or effort of its own, and leaves the decision blank when it is unrecorded', async () => {const plain = tab(); plain.state.agents = [{ id: 'a1', machineId: 'm1', harnessId: 'h1', configuration: { engine: 'claude' } }, agents[1]] as neverconst options = { tab: plain, record: { error: 'BACKEND_UNAVAILABLE' }, jev: { ok: true, value: { unavailable: 'BUSY' } } }diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.tsindex e8cbf5267..b7a5fb749 100644--- a/cli/src/superTabs/routeCommand.ts+++ b/cli/src/superTabs/routeCommand.ts@@ -17,6 +17,8 @@ const ENGINES = ['claude', 'codex']// validation) is the answer and must reach the Lead.const TRANSPORT = new Set(['AGENT_UNAVAILABLE', 'SUPER_TAB_UNAVAILABLE', 'BACKEND_UNAVAILABLE', 'BACKEND_TIMEOUT', 'BACKEND_UNREACHABLE'])const MACHINES_UNREADABLE = "The account's machine list could not be read; only known machines were considered."+const DISK_UNVERIFIED = 'Project disk space could not be verified.'+const NO_PROJECT_FOLDER = 'This machine does not have the project folder. Add it to the Swarm so it can clone the project.'const OFFLINE = 'Machine is offline or unreachable.'const UNKNOWN_QUOTA: Probe['quota'] = { known: false, leftPercent: null, resetsAt: null }const UNKNOWN_LOAD: NonNullable<Probe['load']> = { agents: null, freeMemoryBytes: null, hasFolder: null }@@ -117,10 +119,14 @@ export async function routeTask(input: { tabId: string; conversationId: string;const busy = new Set([String(group.leadId), String(conversations.find(c => c.id === 'lead')?.leadId),...conversations.filter(c => active(c.assignment)).map(c => String(object(c.assignment).agentId))])const members = agents.filter(a => !busy.has(String(a.id)) && ENGINES.includes(String(object(a.configuration).engine))).map(a => withLaunchEffort(a, list(state.starts)))- // The account's machines can start a new agent. A member may run on a machine only its collaborator can- // open; the Lead tries that machine too, but a member there is unknown, never offline.+ // A new agent starts only on a machine in the Swarm's Machines list (the backend refuses any other): a contributed machine, or+ // one an agent of the Swarm runs on. The Lead runs here, so its own machine is always listed. Of the account's machines+ // only those count; the rest were never prepared with the project and would only be excluded for a missing folder+ // (production, 2026-10-21). A member may run on a machine only its collaborator can open; the Lead tries that machine+ // too, but a member there is unknown, never offline.+ const swarmMachines = new Set([where.machineId, ...list(state.machines).map(m => String(m.machineId)), ...agents.map(a => String(a.machineId))])const machines = new Map<string, { name: string; status: string; account: boolean; pool?: Json }>()- for (const m of list(value.machines)) machines.set(String(m.machineId), { name: String(m.name), status: String(m.status ?? 'unknown'), account: true })+ for (const m of list(value.machines)) if (swarmMachines.has(String(m.machineId))) machines.set(String(m.machineId), { name: String(m.name), status: String(m.status ?? 'unknown'), account: true })// The Lead's own machine is the account's even when the list could not be read.if (!machines.has(where.machineId)) machines.set(where.machineId, { name: where.machineId, status: 'unknown', account: true })for (const m of members) if (!machines.has(String(m.machineId))) machines.set(String(m.machineId), { name: String(m.machineId), status: 'unknown', account: false })@@ -267,7 +273,11 @@ async function probeMachine(machineId: string, { name: machineName, status, accoconst load = { agents: Array.isArray(listed.agents) ? frames.length : null,freeMemoryBytes: finite(resources.memoryTotalBytes) && finite(resources.memoryUsedBytes) ? resources.memoryTotalBytes - resources.memoryUsedBytes : null,hasFolder: a.needs.cwd ? finite(resources.projectDiskFreeBytes) : null }- probes.push(newProbe(m, inspected.allowed ? [] : inspected.reasons, quotaOf2(inspected.quota), inspected.unknown.length === 0 && inspected.quota.known, load))+ // A machine listed only because an agent runs there may never have cloned the project. When its capacity read succeeded but+ // could not measure the named folder's disk, a missing folder is the likely cause; a failed or unsupported read says nothing.+ const noFolder = !!a.needs.cwd && machineId !== where.machineId && object(inspected.capacity).ok === true && !finite(resources.projectDiskFreeBytes)+ const reasons = noFolder ? inspected.reasons.map(r => r === DISK_UNVERIFIED ? NO_PROJECT_FOLDER : r) : inspected.reasons+ probes.push(newProbe(m, inspected.allowed ? [] : reasons, quotaOf2(inspected.quota), inspected.unknown.length === 0 && inspected.quota.known, load))}return probes} finally { target.close() }diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.tsindex 37d2f6460..76699f2c1 100644--- a/cli/src/superTabs/service.spec.ts+++ b/cli/src/superTabs/service.spec.ts@@ -56,6 +56,12 @@ it('documents how a lead shares its project repository for other machines', asynconst answer = await t.ask({ action: 'help' }, owner) as { help: { commands: Array<Record<string, unknown>> } }expect(answer.help.commands).toContainEqual({ type: 'project.repository', projectId: 'PROJECT', repositoryUrl: 'https://github.com/OWNER/REPOSITORY' })})+it('tells the Lead that start works only on a machine in the Swarm\'s Machines list', async () => {+ const t = setup()+ const answer = await t.ask({ action: 'help' }, owner) as { help: { start: string } }+ expect(answer.help.start).toContain('create one agent in a conversation on a machine in this Swarm\'s Machines list; to use another machine, a person adds it to the Swarm first.')+ expect(answer.help.start).toContain('Repeat exactly after an interruption')+})it('resolves a native caller to its exact contribution and rechecks it before every agent command', async () => {const t = setup()expect(await t.ask({ action: 'status', tabId: 'tab', harnessId: 'native' }, owner)).toMatchObject({ ok: true })diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.tsindex 4aa04f608..974efa038 100644--- a/cli/src/superTabs/service.ts+++ b/cli/src/superTabs/service.ts@@ -16,7 +16,7 @@ const HELP = {messages: 'messages GROUP: read recent messages in a conversation.',message: 'message GROUP MESSAGE_ID: read one exact message, including an earlier question or result referenced by a reply.',post: 'post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]...: reply in that conversation. Use a unique ID per message and reuse it after an interrupted request. Answer a message once, with --reply-to its ID. --attach sends a file (a screenshot, a log; up to 10 files of 10 MB each), and TEXT may then be empty.',- start: 'start OPERATION_ID JSON: create one agent in a conversation on a machine you can access. Repeat exactly after an interruption; it follows the same native creation receipt. It does not assign work.',+ start: 'start OPERATION_ID JSON: create one agent in a conversation on a machine in this Swarm\'s Machines list; to use another machine, a person adds it to the Swarm first. Repeat exactly after an interruption; it follows the same native creation receipt. It does not assign work.',resume: 'resume START_ID: finish a pending start without creating another agent.',route: 'route GROUP JSON: before starting or assigning work, choose who does it. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","why":"one sentence","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason.',capacity: 'capacity MACHINE_ID JSON: inspect machine, engine and quota headroom. JSON uses the start request fields below. Unknown allowances are not reported as free tokens.',diff --git a/docs/swarms.md b/docs/swarms.mdindex 2ad51a88e..b998514ec 100644--- a/docs/swarms.md+++ b/docs/swarms.md@@ -51,6 +51,12 @@ tries the other transport (HTTPS or SSH) once. For a private repository, everycontributing owner needs access to it on that machine, either through`gh auth login` and `gh auth setup-git` or through an SSH key.+The lead starts new agents only on the Swarm's listed machines: every+contributed machine, plus every machine an agent of the Swarm already runs on+(the lead's own machine is always one of them). To make another machine+available, a person adds it to the Swarm under Machines; the host then clones+the project there.+Ordinary guest machine sharing does not authorize Swarm controls under theowner's account. The owner contributes the machine or an agent. The lead'srouting policy still determines eligible engines, capacity and model choices.