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
Require an agent to route before it starts or assigns work (#1555)
0xken15ce642dbdf3bc
diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 9cf511cc6..24ca132e9 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -84,7 +84,7 @@ describe('five-part task persistence', () => {const row = (await store.read(owner, tab)).state.conversations.find(c => c.id === group)!expect(row.task).toEqual(task)expect(row.brief).toContain('Goal:\nKeep drafts')- await run(tab, { type: 'work.assign', conversationId: group, agentId: worker }, host, lead)+ await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })const messages = (await store.messages(owner, tab, group, {})).messagesconst delivered = messages.at(-1)!.textfor (const part of ['Goal:', 'Changes:', 'Constraints:', 'Owns:', 'Acceptance checks:', ...Object.values(task).flat(), checks[0]!.description]) expect(delivered).toContain(part)@@ -1152,7 +1152,11 @@ describe('Super Tabs on a real Mongo replica set', () => {const helper = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId, harnessId: randomUUID(), name: 'Helper', configuration: config, lead: false })).result.agentId as stringconst 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 decision = { assessment: { difficulty: 'low', risk: 'low', why: 'Docs.' },+ candidates: [{ id: 'c0', kind: 'new', machineId: 'test-host', engine: 'claude', model: 'haiku', effort: 'auto', quality: 1, cost: 1, title: 'New agent', label: 'New agent' }],+ excluded: [], floor: 1, notes: false, pick: 'c0', via: 'only', p: null, belowFloor: false, why: 'Only candidate.' }+ const routeDecisionId = (await run(tab, { type: 'route.record', conversationId: 'lead', decision } as Command, host, lead)).result.routeDecisionId as string+ const operationId = randomUUID(), command: Command = { type: 'agent.start', request, routeDecisionId, overrideReason: 'The helper machine has the repository.' }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.diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex 66bd2f6ae..b2110baa3 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -456,7 +456,7 @@ it('starts only in the chosen conversation, captures authority, and never assignconst contribution = { machineOwnerId: 'target-owner', contributorId: 'owner', hostGrant: 'grant-1' }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 string+ const startId = f.run({ type: 'agent.start', request, ...via }, actor, { contribution, ...decisionIn(group) }).result.startId as stringexpect(f.state.starts![0]).toMatchObject({ request, hostGrant: 'grant-1', dispatched: false })expect(f.state.agents).toHaveLength(1)expect(f.state.conversations).toHaveLength(2)@@ -468,7 +468,7 @@ it('starts only in the chosen conversation, captures authority, and never assignexpect(f.state.conversations[1]).toMatchObject({ agentIds: [lead, worker], assignment: null })expect(f.state.conversations[0]!.agentIds).toEqual([lead])f.run({ type: 'tab.pause', paused: true })- expect(() => f.run({ type: 'agent.start', request }, actor, { contribution })).toThrow('paused')+ expect(() => f.run({ type: 'agent.start', request, ...via }, actor, { contribution, ...decisionIn(group) })).toThrow('paused')})describe('agent.start on the Swarm\'s listed machines', () => {@@ -479,7 +479,7 @@ describe('agent.start on the Swarm\'s listed machines', () => {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 }))+ expect(() => f.run({ type: 'agent.start', request: request(group, 'account-vm'), ...via }, actor, { contribution: grant, ...decisionIn(group) })).toThrow(expect.objectContaining({ code: 'MACHINE_NOT_LISTED', status: 403, message: 'Add this machine to the Swarm first.' }))expect(f.state.starts ?? []).toEqual([])})@@ -490,7 +490,8 @@ describe('agent.start on the Swarm\'s listed machines', () => {const lead = f.run({ type: 'agent.add', conversationId: 'lead', machineId: 'lead-machine', harnessId: 'lead', name: 'Lead',configuration: { ...config, engine }, lead: true }, owner, { contribution: { machineOwnerId: 'host-owner', contributorId: 'owner' } }).result.agentId as stringconst actor: Actor = { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' }- f.run({ type: 'agent.start', request: request(f.group(), 'lead-machine') }, actor, { contribution: grant })+ const group = f.group()+ f.run({ type: 'agent.start', request: request(group, 'lead-machine'), ...via }, actor, { contribution: grant, ...decisionIn(group) })expect(f.state.starts).toHaveLength(1)})@@ -499,7 +500,7 @@ describe('agent.start on the Swarm\'s listed machines', () => {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 })+ f.run({ type: 'agent.start', request: request(group, 'contributed'), ...via }, actor, { contribution: grant, ...decisionIn(group) })expect(f.state.starts).toHaveLength(1)})@@ -532,6 +533,9 @@ const candidate = (id: string, patch: Record<string, unknown> = {}) => ({ id, kiconst record = (patch: Record<string, unknown> = {}) => ({ assessment: { difficulty: 'high', risk: 'low', why: 'Schema change.' },candidates: [candidate('c0'), candidate('c1', { model: 'sonnet', quality: 2, cost: 2 })], excluded: [], floor: 3, notes: false,pick: 'c0', via: 'jev', p: 0.82, belowFloor: false, why: 'Highest quality within quota.', ...patch })+/** What an agent passes to start or assign: a routing decision of `conversationId`. Its pick differs from the call, so it carries a reason. */+const via = { routeDecisionId: 'd1', overrideReason: 'Test.' }+const decisionIn = (conversationId = 'lead') => ({ routeDecision: { id: 'd1', conversationId, record: record(), final: null, override: null, assignmentId: null, outcome: null } as unknown as RouteDecision })/** The base fixture plus a coordinating Lead and a worker, both on one host. */function routed() {const f = fixture()@@ -684,7 +688,7 @@ describe('decisions linked to work', () => {it('refuses a second link while the first assignment of the decision is still running', () => {const f = routed()f.define('lead')- const running = f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker }, f.leadActor)+ const running = f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, ...via }, f.leadActor, decisionIn())const assignmentId = running.result.assignmentId as stringconst request = { conversationId: 'lead', machineId: 'machine', engine: 'claude', model: 'opus', effort: 'high', name: 'Builder', cwd: '/repo', worktree: false,requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }@@ -756,6 +760,28 @@ describe('decisions linked to work', () => {})})+describe('agents route before they start or assign', () => {+ const request = { conversationId: 'lead', machineId: 'machine', engine: 'claude', model: 'opus', effort: 'high', name: 'Builder', cwd: '/repo', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }+ const refused = expect.objectContaining({ code: 'ROUTE_REQUIRED', status: 400, message: expect.stringContaining('Route this task first') })++ it('refuses a Lead\'s start and assignment without a routing decision, and records nothing', () => {+ const f = routed()+ f.define('lead')+ expect(() => f.run({ type: 'agent.start', request }, f.leadActor, { contribution: f.contribution })).toThrow(refused)+ expect(() => f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker }, f.leadActor)).toThrow(refused)+ expect(f.state.starts ?? []).toEqual([])+ expect(f.state.conversations.find(c => c.id === 'lead')!.assignment ?? null).toBeNull()+ })++ it('lets a person start and assign by hand, without routing', () => {+ const f = routed()+ f.define('lead')+ expect(f.run({ type: 'agent.start', request }, owner, { contribution: f.contribution }).result.startId).toBeTruthy()+ expect(f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker }, owner).result.assignmentId).toBeTruthy()+ })+})+it('assigns stable workgroup numbers through old snapshots, rename, archive and new groups', () => {const f = fixture(), first = f.group(), second = f.group()expect(f.state.conversations.map(c => c.number)).toEqual([undefined, 1, 2])@@ -829,8 +855,8 @@ describe('message attachments', () => {const { f, group, worker, other, leadActor } = finished()expect(visibleState(f.state, owner).agents.find(a => a.id === worker)).toHaveProperty('workDecision', 'awaiting')f.run({ type: 'work.define', conversationId: group, brief: 'Next task', checks: [{ description: 'Done', independent: false }] })- expect(() => f.run({ type: 'work.assign', conversationId: group, agentId: other }, leadActor)).toThrow('reuse, keep or stop')- f.run({ type: 'work.assign', conversationId: group, agentId: worker }, leadActor)+ expect(() => f.run({ type: 'work.assign', conversationId: group, agentId: other, ...via }, leadActor, decisionIn(group))).toThrow('reuse, keep or stop')+ f.run({ type: 'work.assign', conversationId: group, agentId: worker, ...via }, leadActor, decisionIn(group))expect(f.state.agents.find(a => a.id === worker)).not.toHaveProperty('workDecision')expect(() => f.run({ type: 'agent.release', agentId: worker, decision: 'stop' } as Command, leadActor)).toThrow('active work')})@@ -841,9 +867,9 @@ describe('message attachments', () => {f.run(release, leadActor)expect(f.state.agents.find(a => a.id === worker)).toHaveProperty('workDecision', 'keep')f.run({ ...release, decision: 'stop' } as Command)- expect(() => f.run({ type: 'work.assign', conversationId: group, agentId: worker }, leadActor)).toThrow('stopping')+ expect(() => f.run({ type: 'work.assign', conversationId: group, agentId: worker, ...via }, leadActor, decisionIn(group))).toThrow('stopping')expect(() => f.run(release, leadActor)).toThrow('stopping')- f.run({ type: 'work.assign', conversationId: group, agentId: other }, leadActor)+ f.run({ type: 'work.assign', conversationId: group, agentId: other, ...via }, leadActor, decisionIn(group))})it('allows only the execution host of a requested stop to acknowledge removal', () => {const { f, worker, other, leadActor, workerActor } = finished()@@ -867,10 +893,10 @@ it('blocks routing and starts until a finished worker is kept or stopped', () =>const request = { conversationId: group, machineId: 'machine', engine: 'claude', name: 'Builder', cwd: '/repo', worktree: false,requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }expect(() => f.run(route, f.leadActor)).toThrow('reuse, keep or stop')- expect(() => f.run({ type: 'agent.start', request }, f.leadActor, { contribution: f.contribution })).toThrow('reuse, keep or stop')+ expect(() => f.run({ type: 'agent.start', request, ...via }, f.leadActor, { contribution: f.contribution, ...decisionIn(group) })).toThrow('reuse, keep or stop')f.run({ type: 'agent.release', agentId: f.worker, decision: 'keep' }, f.leadActor)expect(f.run(route, f.leadActor).routeDecisions).toHaveLength(1)- expect(f.run({ type: 'agent.start', request }, f.leadActor, { contribution: f.contribution }).result.startId).toBeTruthy()+ expect(f.run({ type: 'agent.start', request, ...via }, f.leadActor, { contribution: f.contribution, ...decisionIn(group) }).result.startId).toBeTruthy()})it('requires the exact stop request for host acknowledgement and prevents promotion while stopping', () => {diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 05082176a..b8bb675ef 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -219,6 +219,10 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma...(attachments?.length ? { attachments } : {}) })result.messageId = operationId}+ /** An agent starts or assigns only what the route chose; a person may still do either by hand. */+ const routed = (routeDecisionId?: string) => {+ if (actor.kind === 'agent' && !routeDecisionId) fail('ROUTE_REQUIRED', 'Route this task first, then start or assign the pick with its routeDecisionId.', 400)+ }const openDecision = (): RouteDecision => {const decision = context.routeDecision ?? fail('NOT_FOUND', 'This routing decision is unavailable.', 404)if (decision.outcome) fail('ROUTE_CLOSED', 'This routing decision is no longer open. Route the task again.')@@ -436,6 +440,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma}case 'agent.start': {controls(state, actor, command.request.conversationId)+ routed(command.routeDecisionId)requireWorkerDecisions(state, actor, 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@@ -772,6 +777,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commafail('START_PENDING', 'Wait for the host to finish this agent’s launch and model selection.')}controls(state, actor, command.conversationId)+ routed(command.routeDecisionId)const group = open(state, command.conversationId)if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')if (activeWork(group)) fail('WORK_ACTIVE', 'The current assignment must finish or be reconciled before reassignment.')diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.tsindex 898a418f4..719c7c9ff 100644--- a/cli/src/superTabs/service.ts+++ b/cli/src/superTabs/service.ts@@ -19,7 +19,7 @@ const HELP = {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. With worktree true, the agent starts from the repository\'s default branch, fetched first, unless you set branchRef (refs/heads/BRANCH, or refs/remotes/origin/BRANCH to fetch it first) to start from another branch, such as the one this work builds on.',release: 'When a worker finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. Reuse assigns new work; agent.release records keep or requests stop. Wait for the execution host to confirm a stop. A person can withdraw a stuck stop; the session cannot receive new work in that Swarm. Its native capacity stays reserved until its host confirms stopping. Other Swarms wait up to two minutes for an in-flight close, then may reuse it.',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","size":"small|medium|large","why":"one sentence","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason.',+ route: 'route GROUP JSON: before starting or assigning work, choose who does it. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason. An agent\'s start or work.assign without a routeDecisionId is refused, so route first; a person can still start and assign by hand.',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.',startRequest: { conversationId: 'GROUP', machineId: 'MACHINE', engine: 'codex', name: 'Builder', cwd: '/absolute/repo/on/that/machine', worktree: true, branchRef: 'refs/remotes/origin/BASE_BRANCH', requirements: START_REQUIREMENTS,model: 'opus', effort: 'high', routeDecisionId: 'DECISION' },