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
Add the owner's Lead machine to its Swarm automatically (#1554)
0xken158f243ee2be84
diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 24ca132e9..6cb7cbb85 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -8,13 +8,14 @@ import { MongoMemoryReplSet } from 'mongodb-memory-server-core'import { PrismaClient } from '@prisma/client'import Fastify, { type FastifyInstance } from 'fastify'import type { AuthUser } from '../src/lib/ssoAuth.js'-import { SuperTabStore } from '../src/superTabs/store.js'+import { ABANDONED_START_MS, SuperTabStore } from '../src/superTabs/store.js'import { MemoryAttachmentStore } from '../src/superTabs/attachments.js'import { superTabRoutes } from '../src/routes/superTabs.js'import { errorHandler } from '../src/middlewares/errorHandler.js'import type { Command } from '../src/superTabs/commands.js'import { nextMachineShareGrants } from '../src/lib/machineSharePolicy.js'import { DEFAULT_ROUTING_POLICY } from '../src/superTabs/routingPolicy.js'+import { stableId } from '../src/superTabs/model.js'// A fresh loopback replica set, created here. This suite never reads DATABASE_URL or an existing database.let replica: MongoMemoryReplSet@@ -1528,3 +1529,59 @@ it.each(['finished', 'expired'] as const)('lets another Swarm reuse after the naexpect((await later.execute(owner, other.tab, { operationId: randomUUID(), command: reuse })).result.agentId).toBe(worker)}})++describe('the owner\'s Lead machine joins its Swarm', () => {+ it('adds the machine once, finishes abandoned starts and keeps in-flight ones and existing settings', async () => {+ const machineId = `owner-mac-${randomUUID()}`+ await db.machine.create({ data: { machineId, userId: owner.sub, apiKey: `fixture-${machineId}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ const tab = (await store.create(owner, randomUUID(), 'Own machine')).id+ await run(tab, { type: 'agent.add', conversationId: 'lead', machineId, harnessId: randomUUID(), name: 'Lead', configuration: config, lead: true })+ expect((await store.hostTabs(owner, machineId)).map(r => r.joinSwarm)).toEqual([true])+ const request = { conversationId: 'lead', machineId, engine: 'codex', name: 'Builder', cwd: '/repo', worktree: true,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }+ const start = async () => (await run(tab, { type: 'agent.start', request })).result.startId as string+ const [abandoned, inFlight, dispatched] = [await start(), await start(), await start()]+ await run(tab, { type: 'agent.startDispatch', startId: dispatched })+ const age = (ids: string[]) => db.superTabOperation.updateMany({ where: { id: { in: ids.map(id => stableId(tab, `person:${owner.sub}`, id)) } },+ data: { createdAt: new Date(Date.now() - ABANDONED_START_MS - 1) } })+ await age([abandoned, dispatched])+ const join = { type: 'machine.contribute' as const, machineId, name: 'Ken Mac', cwd: '/swarm', scope: 'swarm' as const, engines: ['codex'], maxAgents: 3, ifMissing: true as const }+ await expect(run(tab, join)).rejects.toMatchObject({ code: 'STARTS_PENDING' })+ const pending = (await store.read(owner, tab)).state.starts!+ expect([abandoned, inFlight, dispatched].map(id => pending.find(s => s.id === id)!.error)).toEqual([null, null, null])+ await run(tab, { type: 'agent.startFailed', startId: inFlight, error: 'Launch refused.' })+ await run(tab, { type: 'agent.started', startId: dispatched, harnessId: randomUUID(), configuration: config })+ await run(tab, join)+ const joined = (await store.read(owner, tab)).state+ expect(joined.starts!.find(s => s.id === abandoned)!.error).toBe('Abandoned before it started.')+ expect(joined.starts!.find(s => s.id === inFlight)!.error).toBe('Launch refused.')+ expect(joined.starts!.find(s => s.id === dispatched)!.error).toBeNull()+ expect((await store.messages(owner, tab, 'lead', {})).messages.at(-1)!.text).toBe('Builder never started and will not start now. Start it again if still needed.')+ const added = joined.machines!.find(m => m.machineId === machineId)!+ expect(added).toMatchObject({ contributorId: owner.sub, maxAgents: 3, scope: 'swarm', cwd: '/swarm' })+ expect((await store.hostTabs(owner, machineId)).map(r => r.joinSwarm)).toEqual([false, false])+ await run(tab, { ...join, maxAgents: 8, cwd: '/elsewhere' })+ expect((await store.read(owner, tab)).state.machines!.find(m => m.machineId === machineId)).toEqual(added)+ })++ it('never adds another account\'s machine', async () => {+ const { tab } = await fixture()+ const invitation = await run(tab, { type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })+ await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)+ expect((await store.hostTabs(host, 'test-host')).filter(r => r.tabId === tab).map(r => r.joinSwarm)).toEqual([false])+ const join = { type: 'machine.contribute' as const, machineId: 'test-host', name: 'Host', cwd: '/swarm', scope: 'swarm' as const, engines: ['codex'], maxAgents: 2, ifMissing: true as const }+ await expect(run(tab, join)).rejects.toMatchObject({ code: 'OWNER_REQUIRED' })+ await expect(run(tab, join, host)).rejects.toMatchObject({ code: 'OWNER_REQUIRED' })+ expect((await store.read(owner, tab)).state.machines ?? []).toEqual([])+ })++ it('never marks the owner\'s machine for a collaborator\'s Lead running on it through a share', async () => {+ const machineId = `owner-shared-${randomUUID()}`+ await db.machine.create({ data: { machineId, userId: owner.sub, apiKey: `fixture-${machineId}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ await db.machineShare.create({ data: { machineId, ownerId: owner.sub, autonomousEnv: 'prod', emails: [peer.email] } })+ const tab = (await store.create(owner, randomUUID(), 'Shared Lead')).id+ await invite(tab)+ await run(tab, { type: 'agent.add', conversationId: 'lead', machineId, harnessId: randomUUID(), name: 'Peer Lead', configuration: config, lead: true }, peer)+ expect((await store.hostTabs(owner, machineId)).map(r => [r.agent.contributorId, r.joinSwarm])).toEqual([[peer.sub, false]])+ })+})diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 6f86766a2..9a9f97471 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -51,7 +51,8 @@ const task = z.object({}).strict()export const commandSchema = z.discriminatedUnion('type', [- z.object({ type: z.literal('machine.contribute'), machineId: id, name: title, cwd: path, scope: z.literal('swarm').optional(), engines: z.array(z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)).min(1).max(32), maxAgents: z.number().int().min(1).max(16) }).strict(),+ z.object({ type: z.literal('machine.contribute'), machineId: id, name: title, cwd: path, scope: z.literal('swarm').optional(), engines: z.array(z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/)).min(1).max(32), maxAgents: z.number().int().min(1).max(16),+ ifMissing: z.literal(true).optional() }).strict(),z.object({ type: z.literal('machine.pause'), machineId: id, paused: z.boolean() }).strict(),z.object({ type: z.literal('tab.rename'), name: title }).strict(),z.object({ type: z.literal('tab.project'), machineId: id, project }).strict(),@@ -123,6 +124,9 @@ export interface CommandContext {recentRoutes?: number/** The decision a command names, read from SuperTabRouteDecision by the store. */routeDecision?: RouteDecision+ /** Starts on the machine being contributed that the store found abandoned: never contributed, never dispatched,+ * and older than ABANDONED_START_MS by their operation receipt. */+ abandonedStartIds?: string[]}/** Messages in a row between the Lead and its worker after which the Lead's message is no longer delivered automatically. */@@ -335,7 +339,22 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaif (actor.kind !== 'person' || context.contribution?.machineOwnerId !== actor.userId) fail('OWNER_REQUIRED', 'Only the machine owner can contribute it.', 403)const contributor = person(state, actor.userId)state.machines ??= []+ // The owner's host adds the machine its Lead runs on by itself (cli/src/superTabs/host.ts). It only fills a gap:+ // on 2026-10-22 Ken's Mac ran the Lead of a Swarm it was never added to, so its starts bypassed the machine's slots.+ if (command.ifMissing) {+ if (actor.userId !== state.ownerId) fail('OWNER_REQUIRED', 'Only the Swarm owner adds a machine automatically.', 403)+ if (state.machines.some(m => m.machineId === command.machineId)) break+ }if (!state.machines.some(m => m.machineId === command.machineId) && state.machines.length >= 32) fail('MACHINES_FULL', 'A Super Tab can have up to 32 contributed machines.')+ // Before a machine was contributed, a Lead's start on it that never dispatched was left pending for good (12 on Ken's+ // Mac that day) and refused every contribution. Those finish as failed; a dispatched or recent start still blocks.+ const abandoned = (state.starts ?? []).filter(s => context.abandonedStartIds?.includes(s.id))+ for (const start of abandoned) start.error = 'Abandoned before it started.'+ // One command records one message, so the Lead's conversation hears it once, whichever groups asked.+ const names = [...new Set(abandoned.map(s => s.request.name))]+ if (names.length && state.conversations.some(c => c.id === 'lead')) {+ message('lead', `${names.join(', ')} never started and will not start now. Start ${names.length > 1 ? 'them' : 'it'} again if still needed.`)+ }if (state.starts?.some(s => s.request.machineId === command.machineId && (!s.harnessId || (s.poolGeneration && !s.poolSettled)) && !s.error)) fail('STARTS_PENDING', 'Reconcile pending starts before changing this contribution.')state.machines = state.machines.filter(m => m.machineId !== command.machineId)state.machines.push({ machineId: command.machineId, name: command.name, cwd: command.cwd, engines: [...new Set(command.engines)], maxAgents: command.maxAgents,diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 7269144c1..e8bf115cb 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -51,6 +51,20 @@ async function transaction<T>(db: PrismaClient, body: (tx: Transaction) => Promi}}+/** A Lead's start dispatches within seconds of being recorded; one still undispatched after this long was given up. */+export const ABANDONED_START_MS = 15 * 60_000++/** Starts on a not-yet-contributed machine that never dispatched, dated by their own operation receipt (starts carry no+ * time of their own). A dispatched start may have a native session coming, so it is never counted. */+async function abandonedStarts(tx: Transaction, tabId: string, state: SuperTabState, machineId: string, now: number) {+ const candidates = (state.starts ?? []).filter(s => s.request.machineId === machineId && !s.poolGeneration && !s.dispatched && !s.harnessId && !s.error)+ if (!candidates.length) return []+ const receipts = await tx.superTabOperation.findMany({ where: { id: { in: candidates.map(s => stableId(tabId, s.actorKey, s.id)) } },+ select: { id: true, createdAt: true } })+ const recorded = new Map(receipts.map(r => [r.id, r.createdAt.getTime()]))+ return candidates.filter(s => (recorded.get(stableId(tabId, s.actorKey, s.id)) ?? 0) <= now - ABANDONED_START_MS).map(s => s.id)+}+/** Persistent coordination. Host adapters own execution and must confirm their local session grants. */export class SuperTabStore {readonly native: SuperTabNativeStore@@ -375,6 +389,7 @@ export class SuperTabStore {if (command.type === 'machine.contribute' || command.type === 'agent.add' || command.type === 'tab.project') {context.contribution = await this.contribution(tx, original, actor, command)}+ if (command.type === 'machine.contribute') context.abandonedStartIds = await abandonedStarts(tx, tabId, original, command.machineId, context.now)if (command.type === 'agent.start') context.contribution = await this.contribution(tx, original, actor, command.request, true)if (command.type === 'agent.started' || command.type === 'agent.startDispatch') {const start = original.starts?.find(s => s.id === command.startId) ?? fail('NOT_FOUND', 'This agent start is unavailable.', 404)@@ -758,7 +773,11 @@ export class SuperTabStore {const waiting = state.conversations.find(c => activeWork(c) && c.assignment!.agentId === target.id &&c.assignment!.execution.machineId === machineId && ['needs_human', 'blocked'].includes(c.assignment!.status))?.assignmentconst attention = waiting ? { assignmentId: waiting.id, status: waiting.status, result: waiting.result?.slice(0, 500) ?? null } : null- result.push({ tabId: row.id, tabName: state.name, revision: row.revision, paused: state.paused, active, attention, agent: target,+ // The owner's own machine runs the owner's own Lead of this Swarm but is not one of its machines: the host adds it+ // (cli/src/superTabs/host.ts). A collaborator's Lead on a machine shared with them must not open it to every member.+ const joinSwarm = state.ownerId === user.sub && target.contributorId === user.sub && !state.machines?.some(m => m.machineId === machineId)+ && state.conversations.some(c => !c.archived && c.leadId === target.id)+ result.push({ tabId: row.id, tabName: state.name, revision: row.revision, paused: state.paused, active, attention, agent: target, joinSwarm,stopRequested: target.workDecision === 'stop' && !state.conversations.some(c => activeWork(c) && c.assignment?.agentId === target.id),observers: people.filter(p => p.id !== user.sub &&canReadAgent(state, { kind: 'person', userId: p.id, email: p.email }, target))diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.tsindex 059d4ec43..0c10a8a54 100644--- a/cli/src/superTabs/host.spec.ts+++ b/cli/src/superTabs/host.spec.ts@@ -824,3 +824,80 @@ it('rechecks authoritative native absence before retrying a lost acknowledgementexpect(t.remove).toHaveBeenCalledOnce()expect(t.close).toHaveBeenLastCalledWith({ agentId: 'harness' })})++describe('adding the machine its own Lead runs on to the Swarm', () => {+ function joining() {+ const dir = mkdtempSync(join(tmpdir(), 'super-tab-join-')); roots.push(dir)+ const agent = { id: 'lead', harnessId: 'harness', machineId: 'machine-1' }+ const rows = [{ tabId: 'own', joinSwarm: true, agent }, { tabId: 'other', joinSwarm: false, agent }, { tabId: 'old', agent }]+ const commands: unknown[] = [], refusals: string[] = []+ let clock = 0+ const call: CoreApi['account']['backend'] = vi.fn(async (method, path, body) => {+ if (path.endsWith('/commands')) {+ commands.push({ path, ...(body as object) })+ const code = refusals.shift()+ if (code) return { status: 409, body: { success: false, error: { code, message: `Refused: ${code}` } } }+ return { status: 200, body: { success: true, data: {} } }+ }+ return { status: 200, body: { success: true, data: path.includes('/hosts/') ? rows : [] } }+ })+ const core = fakeCore({ dataDir: dir, account: { backend: call, machineName: vi.fn(() => 'Ken Mac') } })+ const prepare = vi.fn(async () => ({ ok: true, state: 'ready', cwd: '/data/swarm-projects/own', engines: ['claude', 'codex'], maxAgents: 3, scope: 'swarm' }))+ const log = vi.fn()+ const host = new SuperTabHost(core, 'machine-1', { log, now: () => clock, prepareContribution: prepare }); hosts.push(host)+ /** One roster pass at `at` ms, waiting for the add it may start to finish. */+ const pass = async (at: number) => {+ clock = at+ const tries = prepare.mock.calls.length, heard = commands.length + log.mock.calls.length+ await host.tick()+ if (prepare.mock.calls.length > tries) await vi.waitFor(() => expect(commands.length + log.mock.calls.length).toBeGreaterThan(heard))+ }+ return { core, rows, commands, refusals, prepare, log, pass }+ }++ it('adds it once with the prepared slots and leaves unmarked Swarms alone', async () => {+ const t = joining()+ await t.pass(0)+ expect(t.prepare).toHaveBeenCalledExactlyOnceWith(t.core, { tabId: 'own', scope: 'swarm' })+ expect(t.commands).toEqual([{ path: '/api/super-tabs/own/commands', operationId: expect.any(String), command: { type: 'machine.contribute',+ machineId: 'machine-1', name: 'Ken Mac', cwd: '/data/swarm-projects/own', scope: 'swarm', engines: ['claude', 'codex'], maxAgents: 3, ifMissing: true } }])+ await t.pass(59_000)+ t.rows[0]!.joinSwarm = false+ await t.pass(120_000)+ expect(t.prepare).toHaveBeenCalledTimes(1)+ })++ it('backs off a refusal, doubling up to half an hour, and starts over after an add', async () => {+ const t = joining()+ t.refusals.push(...Array(7).fill('STARTS_PENDING'))+ let at = 0+ const retriesAfter = async (wait: number) => {+ const tries = t.prepare.mock.calls.length+ await t.pass(at + wait - 1)+ expect(t.prepare).toHaveBeenCalledTimes(tries)+ await t.pass(at += wait)+ expect(t.prepare).toHaveBeenCalledTimes(tries + 1)+ }+ await t.pass(at)+ // Seven refusals; the eighth try adds the machine.+ for (const wait of [60_000, 120_000, 240_000, 480_000, 960_000, 1_800_000, 1_800_000]) await retriesAfter(wait)+ expect(t.commands).toHaveLength(8)+ t.refusals.push('STARTS_PENDING')+ await retriesAfter(60_000)+ await retriesAfter(60_000)+ expect(t.log).toHaveBeenCalledWith('Could not add this machine to its Swarm: Refused: STARTS_PENDING')+ })++ it.each(['MACHINES_FULL', 'OWNER_REQUIRED'])('stops after %s until the roster stops asking', async code => {+ const t = joining()+ t.refusals.push(code)+ await t.pass(0)+ await t.pass(24 * 60 * 60_000)+ expect(t.prepare).toHaveBeenCalledTimes(1)+ t.rows[0]!.joinSwarm = false+ await t.pass(24 * 60 * 60_000 + 1)+ t.rows[0]!.joinSwarm = true+ await t.pass(24 * 60 * 60_000 + 2)+ expect(t.prepare).toHaveBeenCalledTimes(2)+ })+})diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.tsindex 96f0641e8..07b7312d4 100644--- a/cli/src/superTabs/host.ts+++ b/cli/src/superTabs/host.ts@@ -11,6 +11,8 @@ import type { CoreApi, TurnDelivery } from '../core/api.js'import { shellQuote } from '../orchestrator/prompts.js'import { noticeReason, WithheldDeliveries } from './withheld.js'import { attentionOf } from './attention.js'+import { prepareContribution } from './contribution.js'+import { hostname } from 'node:os'type Json = Record<string, unknown>export class SuperTabHostError extends Error {@@ -73,9 +75,17 @@ export interface SuperTabHostOptions {log?: (message: string) => voidobservers?: typeof publishObserversattachedFiles?: typeof attachedFiles+ prepareContribution?: typeof prepareContribution}export const hostJournalFile = (dataDir: string, machineId: string) => join(dataDir, 'super-tabs', `host-${machineId}.json`)+/** How long after an add the roster may ask for another (a roster read may predate the add), and the first wait after a+ * failed one. Each try probes every engine's account (about 14 login shells), so the wait doubles up to half an hour:+ * a refusal such as a dispatched start that never reports, or no signed-in engine, can last for days. */+const JOIN_RETRY_MS = 60_000+const JOIN_RETRY_MAX_MS = 30 * 60_000+/** Refusals no retry can change while this host runs: the Swarm has all its machines, or this account does not own it. */+const JOIN_FINAL = new Set(['MACHINES_FULL', 'OWNER_REQUIRED'])/** How long after a pre-#1527 Swarm launch its engine may first bind a session and still be the Swarm's own. */const LEGACY_FIRST_BIND_MS = 120_000const typedId = (entry: Entry) => `team:service:superTabs:${entry.deliveryId}`@@ -107,6 +117,9 @@ export class SuperTabHost {private retentionError: string | null = nullprivate readonly observers: typeof publishObserversprivate readonly attachedFiles: typeof attachedFiles+ private readonly prepareContribution: typeof prepareContribution+ /** Per tab the roster marks, the add in progress or when the next may run. */+ private readonly joins = new Map<string, { running: boolean; failures: number; retryAt: number }>()/** Each delivery's downloaded files, so input held by a busy terminal is not downloaded again on every retry. Only a* complete download is kept: a failed one is tried again before the next delivery of the same message. */private readonly files = new Map<string, string>()@@ -141,6 +154,7 @@ export class SuperTabHost {this.file = hostJournalFile(core.dataDir, machineId)this.observers = options.observers ?? publishObserversthis.attachedFiles = options.attachedFiles ?? attachedFiles+ this.prepareContribution = options.prepareContribution ?? prepareContributionthis.now = options.now ?? Date.nowthis.write = options.write ?? writeJournalthis.log = options.log ?? (message => console.warn(`[super-tabs] ${message}`))@@ -408,6 +422,7 @@ export class SuperTabHost {}this.observers(this.core.dataDir, this.machineId, data, requestedAt + 2500)this.publishAttention(data)+ this.joinSwarms(data)// Runtime observations cannot delay the live input leases. A stale host// observation is fenced by the backend's per-agent configuration version.if (!this.configurationsRunning && this.now() >= this.nextConfigurationsAt) {@@ -468,6 +483,31 @@ export class SuperTabHost {await this.leases()}+ /** The roster marks a Swarm whose Lead runs on this machine of its owner while the machine is not one of the Swarm's+ * (Swarm creation never added it; on 2026-10-22 Ken's Mac ran a Lead outside its own Swarm's machines). The host+ * adds it as the + dialog does (desktop/lib/super_tabs/machines.dart), only if it is still missing, so a person's+ * own contribution is never changed. A slow engine probe never delays deliveries. */+ private joinSwarms(rows: unknown[]): void {+ const marked = new Set(rows.map(object).filter(row => row.joinSwarm === true && identifier(row.tabId)).map(row => row.tabId as string))+ for (const [tabId, join] of this.joins) if (!marked.has(tabId) && !join.running) this.joins.delete(tabId)+ for (const tabId of marked) {+ const join = this.joins.get(tabId) ?? { running: false, failures: 0, retryAt: 0 }+ if (join.running || join.retryAt > this.now()) continue+ join.running = true+ this.joins.set(tabId, join)+ void (async () => {+ const prepared = await this.prepareContribution(this.core, { tabId, scope: 'swarm' })+ await backend(this.core, 'POST', `/api/super-tabs/${tabId}/commands`, { operationId: randomUUID(), command: {+ type: 'machine.contribute', machineId: this.machineId, name: this.core.account.machineName() ?? hostname(),+ cwd: prepared.cwd, scope: 'swarm', engines: prepared.engines, maxAgents: prepared.maxAgents, ifMissing: true } })+ })().then(() => { join.failures = 0; join.retryAt = this.now() + JOIN_RETRY_MS }, error => {+ join.retryAt = error instanceof SuperTabHostError && JOIN_FINAL.has(error.code) ? Infinity+ : this.now() + Math.min(JOIN_RETRY_MAX_MS, JOIN_RETRY_MS * 2 ** join.failures++)+ this.log(`Could not add this machine to its Swarm: ${error instanceof Error ? error.message : String(error)}`)+ }).finally(() => { join.running = false })+ }+ }+/** Hands the core this roster's waits when they changed (or on the first roster). A failed roster read changes* nothing: a network blip does not close an alert. */private publishAttention(rows: unknown[]): void {