Skip to content

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.

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.ts
index 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, {})).messages
const delivered = messages.at(-1)!.text
for (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 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 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.ts
index 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 assign
const 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 string
expect(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 assign
expect(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 string
const 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, ki
const 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 string
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 } }
@@ -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.ts
index 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: Comma
fail('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.ts
index 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' },