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.

Owner rules replace Jev in Swarm routing (#1586)

0xken15975ff323d4da
diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.ts
index 6cb7cbb85..a539cc23d 100644
--- a/backend/integration/superTabs.test.ts
+++ b/backend/integration/superTabs.test.ts
@@ -776,6 +776,24 @@ describe('Super Tabs on a real Mongo replica set', () => {
await expect(store.read({ ...owner, autonomousEnv: 'stag' }, tab)).rejects.toMatchObject({ code: 'NOT_FOUND' })
})
+ it('lets the Lead record a rule only by quoting a message the owner wrote in this tab', async () => {
+ const { tab, lead } = await fixture()
+ await invite(tab)
+ const said = (await run(tab, message('Never use Haiku.'))).result.messageId as string
+ const other = (await run(tab, message('Use Haiku.'), peer)).result.messageId as string
+ const rule = (messageId: string): Command => ({ type: 'rule.set', rule: { kind: 'forbidModel', model: 'haiku' }, text: 'Never use Haiku.',
+ askedIn: { conversationId: 'lead', messageId } })
+ await expect(run(tab, rule(other), host, lead)).rejects.toMatchObject({ code: 'OWNER_MESSAGE_REQUIRED' })
+ await expect(run(tab, rule('missing'), host, lead)).rejects.toMatchObject({ code: 'OWNER_MESSAGE_REQUIRED' })
+ await run(tab, rule(said), host, lead)
+ const state = (await store.read(owner, tab)).state
+ expect(state.rules).toEqual([expect.objectContaining({ text: 'Never use Haiku.', askedBy: owner.sub, askedIn: { conversationId: 'lead', messageId: said } })])
+ // One message may ask for several rules, but the owner's "Rule added" row is not the owner asking.
+ await run(tab, { ...rule(said), rule: { kind: 'minEffort', effort: 'high' } } as Command, host, lead)
+ expect((await store.read(owner, tab)).state.rules).toHaveLength(2)
+ const ownRow = await run(tab, { type: 'rule.set', rule: { kind: 'preferIdle' }, text: 'Reuse idle agents.' })
+ await expect(run(tab, rule(ownRow.result.messageId as string), host, lead)).rejects.toMatchObject({ code: 'OWNER_MESSAGE_REQUIRED' })
+ })
it('closes the replying agent\'s own deliveries of a message as answered, and nobody else\'s', async () => {
const { tab, lead } = await fixture()
const helper = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index a419fe254..fec0b59af 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -3,6 +3,7 @@ import { applyCommand, commandSchema, PAIR_CHAIN_LIMIT, type Command, type Comma
import { machineSlots } from './machines.js'
import { activeWork, agentRole, createSuperTab, visibleState, type Actor, type AgentConfiguration } from './model.js'
import type { RouteDecision } from './routeRecord.js'
+import { agentTarget, broken } from './rules.js'
const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }
const peer: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'peer', email: '[email protected]' }
@@ -1162,3 +1163,173 @@ describe('Reviewer role', () => {
expect(f.state.agents.find(a => a.id === reviewer)).not.toHaveProperty('workDecision')
})
})
+
+describe('the owner\'s rules', () => {
+ const asked = { askedIn: { conversationId: 'lead', messageId: 'm1' } }
+ const said = (patch: Record<string, unknown> = {}) => ({ askedIn: { author: { kind: 'person', id: 'owner', name: owner.email, membershipGeneration: 'tab' },
+ source: false, createdAt: 1000, ...patch } }) as Partial<CommandContext>
+ const ownerSaid = said()
+ const quoting = (messageId: string) => ({ askedIn: { conversationId: 'lead', messageId } })
+ const set = (rule: Record<string, unknown>, text = 'No Haiku.') => ({ type: 'rule.set', rule, text } as Command)
+ const startBy = (f: ReturnType<typeof routed>, actor: Actor, patch: Record<string, unknown> = {}) => f.run({ type: 'agent.start', request: { conversationId: 'lead', machineId: 'machine',
+ engine: 'claude', model: 'opus', effort: 'high', name: 'Builder', cwd: '/repo', worktree: true,
+ requirements: { memoryBytes: 1, diskBytes: 1, maxCpuPercent: 80, tools: [], devices: [], quotaRequired: false }, ...patch }, ...via } as Command, actor, { contribution: f.contribution, ...decisionIn() })
+
+ it('lets the owner set, list and remove rules, and records who asked', () => {
+ const f = routed()
+ const added = f.run(set({ kind: 'forbidModel', model: 'haiku' }))
+ expect(f.state.rules).toEqual([{ id: added.result.ruleId, rule: { kind: 'forbidModel', model: 'haiku' }, text: 'No Haiku.', askedBy: 'owner', askedIn: null,
+ addedBy: 'person:owner', createdAt: new Date(1000).toISOString() }])
+ expect(added.messages[0]).toMatchObject({ conversationId: 'lead', text: 'Rule added: No Haiku.', source: { kind: 'rule' } })
+ // Everyone in the Swarm reads the rules with the tab.
+ expect(visibleState(f.state, f.leadActor).rules).toHaveLength(1)
+ // A second list of machines replaces the first.
+ f.run(set({ kind: 'machines', machineIds: ['m1'] }, 'Only m1.'))
+ f.run(set({ kind: 'machines', machineIds: ['m2'] }, 'Only m2.'))
+ expect(f.state.rules!.map(r => r.text)).toEqual(['No Haiku.', 'Only m2.'])
+ expect(f.run({ type: 'rule.remove', ruleId: added.result.ruleId as string }).messages[0]!.text).toBe('Rule removed: No Haiku.')
+ f.run({ type: 'rule.remove', ruleId: f.state.rules![0]!.id })
+ expect(f.state).not.toHaveProperty('rules')
+ expect(() => f.run({ type: 'rule.remove', ruleId: 'gone' })).toThrow('no such rule')
+ for (let i = 0; i < 50; i++) f.run(set({ kind: 'preferIdle' }, `Rule ${i}.`))
+ expect(() => f.run(set({ kind: 'preferIdle' }))).toThrow('50 rules')
+ expect(() => f.run(set({ kind: 'minEffort', effort: 'huge' }))).toThrow()
+ })
+ it('lets the Lead change rules only by quoting the owner\'s message, and nobody else', () => {
+ const f = routed()
+ const added = f.run({ ...set({ kind: 'forbidModel', model: 'haiku' }), ...asked } as Command, f.leadActor, ownerSaid)
+ expect(f.state.rules![0]).toMatchObject({ askedBy: 'owner', askedIn: asked.askedIn, addedBy: `agent:${f.lead}` })
+ const relay = (messageId: string, context: Partial<CommandContext>) => f.run({ ...set({ kind: 'preferIdle' }), ...quoting(messageId) } as Command, f.leadActor, context)
+ expect(() => f.run(set({ kind: 'preferIdle' }), f.leadActor, ownerSaid)).toThrow('quote a chat message the owner wrote')
+ expect(() => relay('m2', {})).toThrow('quote a chat message the owner wrote')
+ for (const author of [{ kind: 'person', id: 'peer' }, { kind: 'agent', id: 'owner' }]) {
+ expect(() => relay('m2', said({ author }))).toThrow('quote a chat message the owner wrote')
+ }
+ // The owner's own system rows ("Rule added", warnings) and a message older than a day do not count.
+ expect(() => relay('m2', said({ source: true }))).toThrow('quote a chat message the owner wrote')
+ expect(() => relay('m2', said({ createdAt: 1000 - 24 * 3_600_000 - 1 }))).toThrow('quote a chat message the owner wrote')
+ // One message may ask for several rules.
+ expect(relay('m1', ownerSaid).result.ruleId).toBeTruthy()
+ expect(relay('m2', said({ createdAt: 1000 - 24 * 3_600_000 })).result.ruleId).toBeTruthy()
+ expect(() => f.run({ ...set({ kind: 'preferIdle' }), ...asked } as Command, f.workerActor, ownerSaid)).toThrow('Only the Swarm owner')
+ f.invite()
+ expect(() => f.run(set({ kind: 'preferIdle' }), peer)).toThrow('Only the Swarm owner')
+ expect(() => f.run({ type: 'rule.remove', ruleId: added.result.ruleId as string }, peer)).toThrow('Only the Swarm owner')
+ f.run({ type: 'rule.remove', ruleId: added.result.ruleId as string, ...asked }, f.leadActor, ownerSaid)
+ expect(f.state.rules!.map(r => r.text)).toEqual(['No Haiku.', 'No Haiku.'])
+ })
+ it('refuses an agent\'s start that breaks a hard rule, whatever reason it gives', () => {
+ const f = routed()
+ expect(startBy(f, f.leadActor).result.startId).toBeTruthy()
+ f.run(set({ kind: 'forbidModel', model: 'OPUS' }, 'No Opus.'))
+ expect(() => startBy(f, f.leadActor)).toThrow('The owner\'s rule "No Opus." rules out Claude opus. Route again.')
+ expect(startBy(f, f.leadActor, { model: 'sonnet' }).result.startId).toBeTruthy()
+ f.run(set({ kind: 'minEffort', engine: 'claude', effort: 'high' }, 'High effort.'))
+ expect(() => startBy(f, f.leadActor, { model: 'sonnet', effort: 'medium' })).toThrow('rules out Claude at medium effort')
+ expect(() => startBy(f, f.leadActor, { model: 'sonnet', effort: undefined })).toThrow('rules out Claude at an unnamed effort')
+ expect(startBy(f, f.leadActor, { model: 'sonnet', effort: 'max' }).result.startId).toBeTruthy()
+ f.run(set({ kind: 'machines', machineIds: ['elsewhere'] }, 'Only elsewhere.'))
+ expect(() => startBy(f, f.leadActor, { model: 'sonnet' })).toThrow('rules out this machine')
+ })
+ it('lets a person through with a warning the group sees', () => {
+ const f = routed()
+ f.run(set({ kind: 'forbidModel', model: 'opus' }, 'No Opus.'))
+ const effects = startBy(f, owner)
+ expect(effects.result).toMatchObject({ startId: expect.any(String), warnings: ['The owner\'s rule "No Opus." rules out Claude opus.'] })
+ expect(effects.messages).toEqual(expect.arrayContaining([expect.objectContaining({ conversationId: 'lead',
+ text: 'owner started Builder anyway. The owner\'s rule "No Opus." rules out Claude opus.', source: { kind: 'rule' } })]))
+ })
+ it('refuses an agent\'s assignment of a worker that breaks a hard rule, with the effort it was launched with', () => {
+ const f = routed()
+ f.define('lead')
+ f.run(set({ kind: 'forbidModel', engine: 'codex', model: 'test' }, 'No test model.'))
+ expect(() => f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, ...via }, f.leadActor, decisionIn())).toThrow('rules out Codex test-model')
+ const effects = f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker })
+ expect(effects.result.warnings).toEqual(['The owner\'s rule "No test model." rules out Codex test-model.'])
+ expect(effects.messages.map(m => m.text)).toContain('owner assigned worker anyway. The owner\'s rule "No test model." rules out Codex test-model.')
+ // An agent that reports `auto` is held to the effort its start asked for.
+ const worker = f.state.agents.find(a => a.id === f.worker)!
+ worker.configuration.effort = 'auto'
+ const rule = [{ id: 'r', rule: { kind: 'minEffort', effort: 'high' } as const, text: 'High.', askedBy: 'owner', askedIn: null, addedBy: 'person:owner', createdAt: '' }]
+ expect(broken(rule, agentTarget(f.state, worker))).toContain('an unnamed effort')
+ f.state.starts = [{ harnessId: worker.harnessId, request: { machineId: worker.machineId, effort: 'xhigh' } } as never]
+ expect(broken(rule, agentTarget(f.state, worker))).toBeNull()
+ })
+ it('refuses a recorded pick that breaks a hard rule, but not a ruled-out candidate that was not picked', () => {
+ const f = routed()
+ const route = (decision: unknown) => f.run({ type: 'route.record', conversationId: 'lead', decision } as Command, f.leadActor, { recentRoutes: 0 })
+ f.run(set({ kind: 'forbidModel', model: 'sonnet' }, 'No Sonnet.'))
+ expect(route(record()).result.routeDecisionId).toBeTruthy()
+ expect(() => route(record({ pick: 'c1' }))).toThrow('The owner\'s rule "No Sonnet." rules out Claude sonnet.')
+ // A member pick is judged by what the member runs now.
+ const member = record({ candidates: [candidate('c0', { kind: 'member', agentId: f.worker, machineId: 'host', engine: 'codex', model: 'other' })] })
+ f.run(set({ kind: 'forbidModel', model: 'test-model' }, 'No test model.'))
+ expect(() => route(member)).toThrow('rules out Codex test-model')
+ })
+ it('lets a person override to a ruled-out candidate with a warning', () => {
+ const f = routed()
+ f.run(set({ kind: 'forbidModel', model: 'sonnet' }, 'No Sonnet.'))
+ const open = { id: 'd1', conversationId: 'lead', record: record(), final: null, override: null, assignmentId: null, outcome: null } as unknown as RouteDecision
+ const effects = f.run({ type: 'route.override', decisionId: 'd1', candidateId: 'c1', reason: 'Because.' }, owner, { routeDecision: open })
+ expect(effects.result.warnings).toEqual(['The owner\'s rule "No Sonnet." rules out Claude sonnet.'])
+ })
+})
+
+describe('the owner\'s rules, after review', () => {
+ const set = (rule: Record<string, unknown>, text = 'Rule.') => ({ type: 'rule.set', rule, text } as Command)
+ const request = (patch: Record<string, unknown> = {}) => ({ conversationId: 'lead', machineId: 'machine', engine: 'claude', model: 'opus', effort: 'high', name: 'Builder',
+ cwd: '/repo', worktree: true, requirements: { memoryBytes: 1, diskBytes: 1, maxCpuPercent: 80, tools: [], devices: [], quotaRequired: false }, ...patch })
+ it('checks an agent joining or leading a group, and never one leaving it', () => {
+ const f = routed(), group = f.group()
+ f.run(set({ kind: 'forbidModel', model: 'test-model' }, 'No test model.'))
+ expect(() => f.run({ type: 'conversation.agent', conversationId: 'lead', agentId: f.worker, present: true, lead: false }, f.leadActor))
+ .toThrow('The owner\'s rule "No test model." rules out Codex test-model. Route again.')
+ const byHand = f.run({ type: 'conversation.agent', conversationId: group, agentId: f.worker, present: true, lead: true })
+ expect(byHand.result.warnings).toEqual(['The owner\'s rule "No test model." rules out Codex test-model.'])
+ expect(byHand.messages[0]).toMatchObject({ text: 'owner added worker anyway. The owner\'s rule "No test model." rules out Codex test-model.' })
+ expect(f.run({ type: 'conversation.agent', conversationId: 'lead', agentId: f.worker, present: false, lead: false }, f.leadActor).messages).toEqual([])
+ })
+ it('does not launch a start recorded before a rule, unless a person chose it', () => {
+ const f = routed()
+ const startId = f.run({ type: 'agent.start', request: request(), ...via } as Command, f.leadActor, { contribution: f.contribution, ...decisionIn() }).result.startId as string
+ f.run(set({ kind: 'minEffort', effort: 'max' }, 'Max effort.'))
+ expect(() => f.run({ type: 'agent.startDispatch', startId }, f.leadActor, { contribution: f.contribution }))
+ .toThrow('The owner\'s rule "Max effort." rules out Claude at high effort. This start was not launched. Route again.')
+ const chosen = decisionIn().routeDecision
+ f.run({ type: 'agent.startDispatch', startId }, f.leadActor, { contribution: f.contribution, routeDecision: { ...chosen, override: { by: 'person', actorKey: 'person:owner', candidateId: 'c0', reason: 'r' } } })
+ expect(f.state.starts!.find(s => s.id === startId)!.dispatched).toBe(true)
+ // A person's own start is launched; the warning was given when it was asked for.
+ const own = f.run({ type: 'agent.start', request: request() } as Command, owner, { contribution: f.contribution }).result.startId as string
+ expect(f.run({ type: 'agent.startDispatch', startId: own }, owner, { contribution: f.contribution }).messages).toEqual([])
+ })
+ it('lets the Lead carry out a person\'s override to a ruled-out candidate, and nothing else', () => {
+ const f = routed()
+ f.run(set({ kind: 'forbidModel', model: 'sonnet' }, 'No Sonnet.'))
+ const decision = { ...decisionIn().routeDecision, override: { by: 'person', actorKey: 'person:owner', candidateId: 'c1', reason: 'Opus is busy.' } } as RouteDecision
+ const sonnet = request({ model: 'sonnet' })
+ const effects = f.run({ type: 'agent.start', request: sonnet, routeDecisionId: 'd1' } as Command, f.leadActor, { contribution: f.contribution, routeDecision: decision })
+ expect(effects.result.warnings).toEqual(['The owner\'s rule "No Sonnet." rules out Claude sonnet.'])
+ // Without the person's choice the same start is refused, and a reason of the Lead's own does not get past it.
+ expect(() => f.run({ type: 'agent.start', request: sonnet, ...via } as Command, f.leadActor, { contribution: f.contribution, ...decisionIn() })).toThrow('Route again')
+ // The person chose sonnet; the Lead starting something else that breaks a rule is still refused.
+ f.run(set({ kind: 'forbidModel', model: 'opus' }, 'No Opus.'))
+ expect(() => f.run({ type: 'agent.start', request: request(), routeDecisionId: 'd1', overrideReason: 'Mine.' } as Command, f.leadActor, { contribution: f.contribution, routeDecision: decision })).toThrow('No Opus.')
+ // An assignment that carries out the person's choice of a member goes through too.
+ f.define('lead')
+ const member = { ...decision, record: record({ candidates: [candidate('c0'), candidate('c1', { kind: 'member', agentId: f.worker, machineId: 'host', engine: 'codex', model: 'test-model' })] }) } as unknown as RouteDecision
+ f.run(set({ kind: 'forbidModel', model: 'test' }, 'No test model.'))
+ expect(f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, routeDecisionId: 'd1' }, f.leadActor, { routeDecision: member }).result.warnings).toHaveLength(1)
+ })
+ it('matches a model as the owner named it: an alias for a full id, and never an unknown default', () => {
+ const rule = (model: string) => [{ id: 'r', rule: { kind: 'forbidModel', model } as const, text: 'R.', askedBy: 'owner', askedIn: null, addedBy: 'person:owner', createdAt: '' }]
+ const target = (model: string | null) => ({ machineId: 'm', engine: 'claude', model, effort: 'high' })
+ expect(broken(rule('claude-haiku-4-5'), target('haiku'))).toContain('R.')
+ expect(broken(rule('haiku'), target('claude-haiku-4-5'))).toContain('R.')
+ expect(broken(rule('claude-haiku-4-5'), target('sonnet'))).toBeNull()
+ expect(broken(rule('claude-haiku-4-5'), target('claude-haiku-3'))).toBeNull()
+ for (const model of ['def', 'default']) {
+ expect(broken(rule(model), target('default'))).toBeNull()
+ expect(broken(rule(model), target(null))).toBeNull()
+ }
+ })
+})
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 0acee3b42..257dc61d9 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -8,6 +8,7 @@ import {
} from './model.js'
import { routeRecordSchema, routeTitle, startedAs, type RouteCandidate, type RouteDecision, type RouteFinal, type RouteOverride } from './routeRecord.js'
import { routingOverrideSchema } from './routingPolicy.js'
+import { agentTarget, askedInSchema, broken, MAX_RULES, RULE_MESSAGE_MS, ruleSchema, ruleTextSchema, startTarget, type RunTarget } from './rules.js'
import { MAX_ATTACHMENTS, type Attachment } from './attachments.js'
import { agentProjectId, deleteProject, groupProject, inviteLanding, manageProject, mutableProjects, projectMembers, projectOf, readAgent, readConversation, readProject, sameProject } from './projects.js'
@@ -58,6 +59,8 @@ export const commandSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('tab.project'), machineId: id, project }).strict(),
z.object({ type: z.literal('tab.pause'), paused: z.boolean() }).strict(),
z.object({ type: z.literal('tab.routingPolicy'), policy: routingOverrideSchema.nullable() }).strict(),
+ z.object({ type: z.literal('rule.set'), rule: ruleSchema, text: ruleTextSchema, askedIn: askedInSchema.optional() }).strict(),
+ z.object({ type: z.literal('rule.remove'), ruleId: id, askedIn: askedInSchema.optional() }).strict(),
z.object({ type: z.literal('project.create'), name: title, visibility: z.enum(['public', 'private']), brief: z.string().trim().max(8000).default('') }).strict(),
z.object({ type: z.literal('project.rename'), projectId: id, name: title }).strict(),
z.object({ type: z.literal('project.delete'), projectId: id }).strict(),
@@ -112,6 +115,8 @@ export interface CommandContext {
contribution?: { machineOwnerId: string; contributorId: string; hostGrant?: string | null }
/** Loaded from this tab and conversation by the store. */
reply?: { id: string; conversationId: string; author: Author }
+ /** The message a Lead quotes as the owner's request for a rule change, loaded from this tab by the store. */
+ askedIn?: { author: Author; source: boolean; createdAt: number }
/** The newest messages of this conversation before the one being sent, newest first, loaded by the store for `message.send`. */
recent?: { author: Author; recipients: string[] }[]
/** A host's receipt, not an elapsed lease, proves that an assignment stopped. */
@@ -169,6 +174,7 @@ export function authorizeCommandAccess(state: SuperTabState, actor: Actor, comma
if ('projectId' in command && command.projectId) readProject(state, actor, command.projectId)
if ('agentId' in command) readAgent(state, actor, command.agentId)
if (command.type === 'agent.start') readConversation(state, actor, command.request.conversationId)
+ if ((command.type === 'rule.set' || command.type === 'rule.remove') && command.askedIn) readConversation(state, actor, command.askedIn.conversationId)
if ('startId' in command && command.type !== 'route.modelResult') {
const start = state.starts?.find(s => s.id === command.startId) ?? fail('NOT_FOUND', 'This agent start is unavailable.', 404)
readConversation(state, actor, start.request.conversationId)
@@ -237,6 +243,31 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
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)
}
+ /** Rows the system writes for rules; a Lead cannot quote one as the owner asking. Names, not emails, in the text. */
+ const RULE_ROW = { kind: 'rule' }
+ const who = sender.kind === 'person' ? sender.name.split('@')[0]! : sender.name
+ /** A hard rule refuses an agent, unless it carries out what a person chose by hand. A person is not blocked: the
+ * command goes through and the group is told. */
+ const ruled = (target: RunTarget, conversationId: string, done: string, personChose = false) => {
+ const why = broken(state.rules, target)
+ if (!why) return
+ if (actor.kind === 'agent' && !personChose) fail('RULE_BROKEN', `${why} Route again.`, 403)
+ result.warnings = [why]
+ effects.messages.push({ id: stableId(operationId, 'rule'), conversationId, author: sender, text: `${done} anyway. ${why}`, replyTo: null, recipients: [], source: RULE_ROW })
+ }
+ /** Only the owner changes rules, or the tab's Lead quoting a chat message the owner wrote in the last day (review of
+ * #1586: any owner row, a rule row included, could otherwise be quoted at any time). One message may ask for several rules. */
+ const ruleChange = (askedIn: { conversationId: string; messageId: string } | undefined) => {
+ if (actor.kind === 'person' && actor.userId === state.ownerId) return
+ if (actor.kind !== 'agent' || conversation(state, 'lead').leadId !== actor.agentId) {
+ fail('OWNER_REQUIRED', 'Only the Swarm owner, or the Lead passing on the owner\'s request, changes rules.', 403)
+ }
+ const asked = askedIn && context.askedIn
+ if (!asked || asked.author.kind !== 'person' || asked.author.id !== state.ownerId || asked.source
+ || context.now - asked.createdAt > RULE_MESSAGE_MS) {
+ fail('OWNER_MESSAGE_REQUIRED', 'Only the Swarm owner sets rules; quote a chat message the owner wrote in the last day asking for this change.', 403)
+ }
+ }
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.')
@@ -390,6 +421,25 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
if (command.policy && Object.keys(command.policy).length) state.routingPolicy = command.policy
else delete state.routingPolicy
break
+ case 'rule.set': {
+ ruleChange(command.askedIn)
+ // There is one machines list; a new one replaces it.
+ const rules = (state.rules ?? []).filter(r => command.rule.kind !== 'machines' || r.rule.kind !== 'machines')
+ if (rules.length >= MAX_RULES) fail('RULES_FULL', `This Swarm has ${MAX_RULES} rules. Remove one first.`)
+ state.rules = [...rules, { id: operationId, rule: command.rule, text: command.text, askedBy: state.ownerId,
+ askedIn: command.askedIn ?? null, addedBy: actorKey(actor), createdAt: new Date(context.now).toISOString() }]
+ result.ruleId = operationId
+ message('lead', `Rule added: ${command.text}`, [], null, RULE_ROW)
+ break
+ }
+ case 'rule.remove': {
+ ruleChange(command.askedIn)
+ const rule = state.rules?.find(r => r.id === command.ruleId) ?? fail('NOT_FOUND', 'This Swarm has no such rule.', 404)
+ state.rules = state.rules!.filter(r => r.id !== rule.id)
+ if (!state.rules.length) delete state.rules
+ message('lead', `Rule removed: ${rule.text}`, [], null, RULE_ROW)
+ break
+ }
case 'conversation.create': {
const brief = command.task ? renderWorkTask(command.task) : command.brief ?? ''
const project = readProject(state, actor, command.projectId ??
@@ -500,6 +550,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
contributorId: contributor.id, membershipGeneration: contributor.generation, machineOwnerId: grant.machineOwnerId,
hostGrant: grant.hostGrant ?? null, request: command.request, harnessId: null, dispatched: false, error: null })
result.startId = operationId
+ let personChose = false
if (command.routeDecisionId) {
const r = command.request
const model = r.model ?? 'default', effort = r.effort ?? 'default'
@@ -508,7 +559,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
() => ({ kind: 'new', startId: operationId, machineId: r.machineId, engine: r.engine, model, effort }), command.overrideReason)
if (override) message(r.conversationId, `Lead started ${r.name} instead of ${expected.title}. Reason: ${override.reason}`, [], null,
{ kind: 'route-override', decisionId: decision.id, by: 'lead' })
+ personChose = !override && decision.override?.by === 'person'
}
+ ruled(startTarget(command.request), command.request.conversationId, `${who} started ${command.request.name}`, personChose)
break
}
case 'agent.startDispatch':
@@ -521,6 +574,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
controls(state, actor, start.request.conversationId)
if (command.type === 'agent.startDispatch') {
if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')
+ // A start recorded before a rule was added is not launched past it, unless a person asked for it by hand.
+ const why = actor.kind === 'agent' && !(start.routeDecisionId && context.routeDecision?.override?.by === 'person') && broken(state.rules, startTarget(start.request))
+ if (why) fail('RULE_BROKEN', `${why} This start was not launched. Route again.`, 403)
requireWorkerDecisions(state, actor, open(state, start.request.conversationId))
const grant = context.contribution ?? fail('HOST_REQUIRED', 'The original machine grant is unavailable.', 403)
if (grant.machineOwnerId !== start.machineOwnerId || (grant.hostGrant ?? null) !== start.hostGrant) {
@@ -670,6 +726,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
group.agentIds = group.agentIds.filter(id => id !== command.agentId)
if (group.leadId === command.agentId) group.leadId = null
} else {
+ ruled(agentTarget(state, member), group.id, `${who} added ${member.name}`)
if (!group.agentIds.includes(command.agentId)) group.agentIds.push(command.agentId)
// Adding a Reviewer to a group reuses it, as assigning work reuses a Builder.
if (reviewer) delete member.workDecision
@@ -762,6 +819,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
const chosen = command.decision.candidates.find(c => c.id === command.decision.pick)!
const member = chosen.kind === 'member' ? state.agents.find(a => a.id === chosen.agentId) : undefined
if (member) assignable(conversation(state, command.conversationId), member)
+ // Only the pick is checked, so an older CLI that still lists a ruled-out candidate records an allowed pick.
+ ruled(member ? agentTarget(state, member) : chosen, command.conversationId, `${who} routed to ${chosen.title}`)
requireWorkerDecisions(state, actor, open(state, command.conversationId), chosen.kind === 'member' ? chosen.agentId : undefined)
if ((context.recentRoutes ?? 0) >= 30) fail('RATE_LIMITED', 'This Super Tab routed 30 tasks in the last hour. Wait before routing again.', 429)
const decision = command.decision
@@ -799,6 +858,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
const chosen = decision.record.candidates.find(c => c.id === command.candidateId) ?? fail('NOT_FOUND', 'Choose one of this decision’s candidates.', 404)
if (chosen.id === current) fail('ALREADY_CHOSEN', 'That candidate is already the choice.')
if (chosen.kind === 'member' && !state.agents.some(a => a.id === chosen.agentId)) fail('CANDIDATE_UNAVAILABLE', 'That agent left this Super Tab. Choose another.')
+ ruled(chosen.kind === 'member' ? agentTarget(state, agent(state, chosen.agentId!)) : chosen, decision.conversationId, `${who} chose ${chosen.title}`)
effects.routeDecisions.push({ op: 'override', id: decision.id, override: { by: 'person', actorKey: actorKey(actor), candidateId: chosen.id, reason: command.reason } })
const lead = conversation(state, decision.conversationId).leadId
message(decision.conversationId,
@@ -851,7 +911,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
execution: { machineId: worker.machineId, harnessId: worker.harnessId, machineOwnerId: worker.machineOwnerId }, result: null }
group.checks.forEach(c => { c.evidence = null; c.passedBy = null })
result.assignmentId = operationId
- let routeNote: { decisionId: string; text: string } | null = null
+ let routeNote: { decisionId: string; text: string } | null = null, personChose = false
if (command.routeDecisionId) {
const started = (d: RouteDecision) => d.final?.kind === 'new' &&
!!state.starts?.some(s => s.id === (d.final as { startId: string }).startId && s.harnessId === worker.harnessId && s.request.machineId === worker.machineId)
@@ -861,7 +921,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
startedAs(c, d.final)),
d => started(d) ? d.final! : { kind: 'member', agentId: worker.id, machineId: worker.machineId }, command.overrideReason, operationId)
if (override) routeNote = { decisionId: decision.id, text: `Lead assigned ${worker.name} instead of ${expected.title}. Reason: ${override.reason}` }
+ personChose = !override && decision.override?.by === 'person'
}
+ ruled(agentTarget(state, worker), group.id, `${who} assigned ${worker.name}`, personChose)
message(group.id, `${group.brief}\n\nAcceptance checks:\n${group.checks.map(c => `- ${c.description}`).join('\n')}`, [worker.id])
if (routeNote) effects.messages.push({ id: stableId(operationId, 'route-override'), conversationId: group.id, author: sender,
text: routeNote.text, replyTo: null, recipients: [], source: { kind: 'route-override', decisionId: routeNote.decisionId, by: 'lead' } })
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index dba5caa4a..6c9e38e87 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -133,6 +133,8 @@ export interface SuperTabState {
environment: string
/** Fields this tab overrides from its owner's account routing policy (routingPolicy.ts). */
routingPolicy?: import('./routingPolicy.js').RoutingOverride
+ /** The owner's routing rules (rules.ts); absent until the first is set. */
+ rules?: import('./rules.js').SwarmRule[]
/** Owner-only sharing configuration; visibleState always removes it. */
sharing?: import('./sharing.js').SwarmSharing
paused: boolean
diff --git a/backend/src/superTabs/rules.ts b/backend/src/superTabs/rules.ts
new file mode 100644
index 000000000..6378c6bfd
--- /dev/null
+++ b/backend/src/superTabs/rules.ts
@@ -0,0 +1,74 @@
+/** The Swarm owner's routing rules (docs/plans/2026-10-22-swarm-rules-routing.md). Hard rules bind agents: the backend
+ * refuses an agent's start, assignment or recorded pick that breaks one, and lets a person through with a warning.
+ * Soft rules only rank candidates in the CLI's route. They replaced Jev in routing after the Lead overrode its pick about
+ * half the time on 2026-10-22 (Haiku, a stopping agent, low effort) because it did not know the owner's rules. */
+import { z } from 'zod'
+import type { Agent, SuperTabState } from './model.js'
+
+const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
+const engine = z.enum(['claude', 'codex'])
+const EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
+export const ruleSchema = z.discriminatedUnion('kind', [
+ z.object({ kind: z.literal('forbidModel'), engine: engine.optional(), model: z.string().trim().min(1).max(200) }).strict(),
+ z.object({ kind: z.literal('machines'), machineIds: z.array(id).min(1).max(50) }).strict(),
+ z.object({ kind: z.literal('minEffort'), engine: engine.optional(), effort: z.enum(EFFORTS) }).strict(),
+ z.object({ kind: z.literal('preferEngine'), taskKind: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/).nullable(), engine }).strict(),
+ z.object({ kind: z.literal('preferIdle') }).strict(),
+])
+export const ruleTextSchema = z.string().trim().min(1).max(200)
+export const askedInSchema = z.object({ conversationId: id, messageId: id }).strict()
+export const MAX_RULES = 50
+/** How long an owner's message can back the rule changes the Lead passes on. */
+export const RULE_MESSAGE_MS = 24 * 3_600_000
+
+export interface SwarmRule {
+ id: string
+ rule: z.infer<typeof ruleSchema>
+ /** The owner's words, shown when the rules are listed and quoted when one refuses. */
+ text: string
+ askedBy: string
+ /** The owner's message a Lead relayed; null when the owner set the rule. */
+ askedIn: z.infer<typeof askedInSchema> | null
+ addedBy: string
+ createdAt: string
+}
+/** What would run: a start request, an agent's configuration, or a routed pick. Null when not known. */
+export interface RunTarget { machineId: string; engine: string; model: string | null; effort: string | null }
+
+const ENGINE: Record<string, string> = { claude: 'Claude', codex: 'Codex' }
+/** `default` and `auto` say nothing about the effort, so they never meet a minimum. */
+const rank = (effort: string | null) => EFFORTS.indexOf((effort ?? '') as typeof EFFORTS[number])
+const FAMILY = /haiku|sonnet|opus|fable/
+/** A rule names a model as the owner said it: `haiku` matches every Haiku id, and `claude-haiku-4-5` also matches a start
+ * that asks for the `haiku` alias. `default` is not known, so nothing matches it. */
+export function modelMatches(ruleModel: string, model: string | null): boolean {
+ const rule = ruleModel.toLowerCase(), target = (model ?? 'default').toLowerCase()
+ return target !== 'default' && (target.includes(rule) || (FAMILY.exec(target)?.[0] === target && FAMILY.exec(rule)?.[0] === target))
+}
+
+/** Why a hard rule rules the target out, or null when none does. */
+export function broken(rules: SwarmRule[] | undefined, target: RunTarget): string | null {
+ for (const { rule, text } of rules ?? []) {
+ const engineName = ENGINE[target.engine] ?? target.engine
+ const out = rule.kind === 'forbidModel' ? (!rule.engine || rule.engine === target.engine)
+ && modelMatches(rule.model, target.model) && `${engineName} ${target.model}`
+ : rule.kind === 'machines' ? !rule.machineIds.includes(target.machineId) && 'this machine'
+ : rule.kind === 'minEffort' ? (!rule.engine || rule.engine === target.engine) && rank(target.effort) < rank(rule.effort)
+ && `${engineName} at ${target.effort && rank(target.effort) >= 0 ? `${target.effort} effort` : 'an unnamed effort'}`
+ : false
+ if (out) return `The owner's rule "${text}" rules out ${out}.`
+ }
+ return null
+}
+
+export const startTarget = (request: { machineId: string; engine: string; model?: string; effort?: string }): RunTarget =>
+ ({ machineId: request.machineId, engine: request.engine, model: request.model ?? null, effort: request.effort ?? null })
+
+/** A started agent was launched with `--effort`, which Claude never reports back, so its configuration may say `auto`; its
+ * start record still holds what it was launched with (manual run 2026-10-19). */
+export function agentTarget(state: SuperTabState, worker: Agent): RunTarget {
+ const reported = worker.configuration.effort
+ const launched = state.starts?.find(s => s.harnessId === worker.harnessId && s.request.machineId === worker.machineId)?.request.effort
+ return { machineId: worker.machineId, engine: worker.configuration.engine, model: worker.configuration.model,
+ effort: reported && reported !== 'auto' ? reported : launched ?? reported }
+}
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index daef9afcb..2d8f36f29 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -399,6 +399,10 @@ export class SuperTabStore {
const reply = await tx.superTabMessage.findFirst({ where: { id: command.replyTo, tabId, conversationId: command.conversationId } })
if (reply) context.reply = { id: reply.id, conversationId: reply.conversationId, author: reply.author as unknown as Author }
}
+ if ((command.type === 'rule.set' || command.type === 'rule.remove') && command.askedIn) {
+ const asked = await tx.superTabMessage.findFirst({ where: { id: command.askedIn.messageId, tabId, conversationId: command.askedIn.conversationId } })
+ if (asked) context.askedIn = { author: asked.author as unknown as Author, source: !!asked.source, createdAt: asked.createdAt.getTime() }
+ }
if (command.type === 'message.send' && actor.kind === 'agent') {
const recent = await tx.superTabMessage.findMany({ where: { tabId, conversationId: command.conversationId },
orderBy: { sequence: 'desc' }, take: PAIR_CHAIN_LIMIT, select: { author: true, recipientIds: true } })
@@ -415,6 +419,9 @@ export class SuperTabStore {
const decisionId = command.type === 'route.override' || command.type === 'route.modelResult' ? command.decisionId
: command.type === 'work.assign' || command.type === 'agent.start' ? command.routeDecisionId : undefined
if (decisionId) context.routeDecision = await readDecision(tx, tabId, decisionId) ?? fail('NOT_FOUND', 'This routing decision is unavailable.', 404)
+ // A dispatch reads its start's decision only to see whether a person chose this start by hand (rules.ts).
+ const dispatched = command.type === 'agent.startDispatch' ? original.starts?.find(s => s.id === command.startId)?.routeDecisionId : undefined
+ if (dispatched) context.routeDecision = await readDecision(tx, tabId, dispatched) ?? undefined
const effects = applyCommand(original, actor, command, context)
if (command.type === 'agent.add' || command.type === 'agent.started') {
const target = agent(effects.state, effects.result.agentId as string)
diff --git a/cli/src/superTabs/route.spec.ts b/cli/src/superTabs/route.spec.ts
index c1634ee95..3a4cec7e6 100644
--- a/cli/src/superTabs/route.spec.ts
+++ b/cli/src/superTabs/route.spec.ts
@@ -1,7 +1,8 @@
// cli/src/superTabs/route.spec.ts
-import { createHash } from 'node:crypto'
import { describe, expect, it } from 'vitest'
-import { choose, contextSize, decide, floorFor, jevQuestion, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, scrub, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type TaskFolder } from './route.js'
+import { breaks, choose, decide, floorFor, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'
+
+const object = (v: unknown) => v as Record<string, unknown>
const policy: Policy = { version: 1, floor: { low: 1, medium: 2, high: 3 }, quotaReserve: 10, notes: 'Frontend prefers Claude.', models: [
{ engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3, enabled: true },
@@ -192,52 +193,28 @@ describe('strength, fit and effective cost', () => {
})
})
-const base = { title: 'T', brief: '', checks: [] as string[], messages: [] as Array<{ from: string; text: string }> | null, folder: null as TaskFolder | null,
- attempts: [] as Array<{ agent: string; outcome: string; result?: string }>, recent: [] as Array<{ title: string; via: string; outcome: string | null }> | null }
const frame = (patch: Partial<MemberFrame> = {}): MemberFrame => ({ title: 'Fix auth', project: 'api', cwd: '/w/api', root: '/w/api', remote: 'github.com/acme/api', branch: 'feat/auth', updatedAt: 1_000_000 - 2 * 3_600_000, ...patch })
const folder = (patch: Partial<TaskFolder> = {}): TaskFolder => ({ cwd: '/w/api', kind: 'git', name: 'api', root: '/w/api', remote: 'github.com/acme/api', ...patch })
-describe('Jev context and verdict', () => {
+describe('verdict and record', () => {
const choice = () => { const r = choose([probe({ kind: 'member', agentId: 'a1', name: 'Multiply', activity: 'idle' }), probe({ machineName: 'mac' })], policy, a()); if ('error' in r) throw new Error('x'); return r }
- it('builds at most four string keys within the hosted limits, with no email', () => {
- const q = jevQuestion({ ...base, title: 'Build', brief: 'b'.repeat(5000), checks: ['Tests pass', 'Docs updated'], attempts: [{ agent: 'Builder', outcome: 'stopped' }] }, a(), policy, choice())
- expect(Object.keys(q.state)).toEqual(['task', 'lead', 'policy', 'history'])
- expect(Object.values(q.state).every(v => typeof v === 'string')).toBe(true)
- expect(Object.values(q.state).join('').length).toBeLessThanOrEqual(17_000)
- expect(q.state.task.length).toBeLessThan(5000)
- expect(q.state.history).toContain('Builder: stopped')
- expect(q.state.policy).toContain('Frontend prefers Claude.')
- expect(Object.keys(q.questions.who.criteria)).toEqual(['c0', 'c1'])
- expect(Object.values(q.questions.who.criteria).every(v => v.length <= 640)).toBe(true)
- expect(q.questions.who.instructions.length).toBeLessThanOrEqual(1500)
- expect(JSON.stringify(q)).not.toMatch(/@/)
- })
- it('takes a sure Jev pick, falls back to order when unsure or unavailable, and skips Jev for one candidate', () => {
- const c = choice()
- expect(decide(c, { choice: 'c1', probabilities: { c0: 0.2, c1: 0.8 } }, null)).toMatchObject({ via: 'jev', p: 0.8, pick: { id: 'c1' } })
- expect(decide(c, { choice: 'c1', probabilities: { c0: 0.45, c1: 0.55 } }, null)).toMatchObject({ via: 'order', fallback: 'unsure', pick: { id: 'c0' }, why: expect.stringContaining('Jev unsure') })
- expect(decide(c, undefined, 'BUSY')).toMatchObject({ via: 'order', fallback: 'unavailable', pick: { id: 'c0' }, why: expect.stringContaining('Jev unavailable') })
- const one = choose([probe()], policy, a()); if ('error' in one) throw new Error('x')
- expect(decide(one, undefined, null)).toMatchObject({ via: 'only', p: null })
- })
- it('broken Jev answers fall back to order', () => {
- const c = choice()
- expect(decide(c, { choice: 'c9', probabilities: { c0: 0.1, c9: 0.9 } }, null).via).toBe('order')
- expect(decide(c, { choice: 'c1', probabilities: { c1: 0.9 } }, null).via).toBe('order')
+ it('takes the first in the fixed order, and says when it was the only candidate', () => {
+ expect(decide(choice())).toEqual({ pick: choice().shown[0], via: 'order', p: null, why: "First by the owner's rules and the policy order." })
+ expect(decide(ok(choose([probe()], policy, a())))).toMatchObject({ via: 'only', p: null })
})
it('produces a record the backend schema accepts', () => {
- const c = choice(), v = decide(c, { choice: 'c1', probabilities: { c0: 0.2, c1: 0.8 } }, null)
+ const c = choice(), v = decide(c)
const v1 = { assessment: { difficulty: 'medium', risk: 'low', why: 'API change.' },
candidates: c.shown.map(s => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,
engine: s.engine, model: s.model, effort: s.effort, quality: s.quality, cost: s.cost, title: s.title, label: s.label })),
- excluded: [], floor: 2, notes: true, pick: 'c1', via: 'jev', p: 0.8, belowFloor: false, why: v.why }
+ excluded: [], floor: 2, notes: true, pick: 'c0', via: 'order', p: null, belowFloor: false, why: v.why }
expect(recordOf(c, v, a(), policy)).toEqual({ ...v1, assessment: { ...v1.assessment, size: 'medium' },
candidates: v1.candidates.map(x => ({ ...x, fit: { status: 'unknown', coverage: null, effectiveCost: 2, expiring: 0, spend: { '5-hour': 30, weekly: 4 }, account: 'm1:claude' } })) })
// For a backend from before sizes and fit.
- expect(recordOf(c, v, a(), policy, undefined, true)).toEqual(v1)
- // The policy order says which fallback decided; the other routes carry none.
- const order = decide(c, undefined, 'BUSY')
- expect(recordOf(c, order, a(), policy)).toMatchObject({ via: 'order', fallback: 'unavailable', why: order.why })
+ expect(recordOf(c, v, a(), policy, true)).toEqual(v1)
+ // The task's kind is not recorded, so the record's schema is unchanged.
+ expect(recordOf(c, v, a({ kind: 'ui' }), policy)).toMatchObject({ assessment: { difficulty: 'medium', risk: 'low', why: 'API change.', size: 'medium' } })
+ expect(object(recordOf(c, v, a({ kind: 'ui' }), policy).assessment)).not.toHaveProperty('kind')
})
})
@@ -288,7 +265,7 @@ describe('edges', () => {
expect(ok(choose([probe({ known: false, quota: unknownQuota })], policy, a())).shown[0].label).toContain('quota unknown')
expect(ok(choose([probe({ quota: { known: true, leftPercent: 50, resetsAt: 0 } })], policy, a())).shown[0].label).toContain('resets in 1m')
})
- it('tells Jev how far away a reset is, because Jev does not know the time', () => {
+ it('tells how far away a reset is, which reads the same whenever the log is opened', () => {
const label = (resetsAt: number) => ok(choose([probe({ quota: { known: true, leftPercent: 50, resetsAt } })], policy, a(), 1_000_000)).shown[0].label
expect(label(1_000_000 + 30 * 60_000)).toContain('quota 50% left, resets in 30m')
expect(label(1_000_000 + 2 * 3_600_000)).toContain('resets in 2h')
@@ -310,22 +287,6 @@ describe('edges', () => {
expect(ok(choose([probe({ machineName: 'b' }), probe({ kind: 'member', agentId: 'a1', name: 'M' })], policy, a())).shown[0].kind).toBe('member')
expect(ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'M' }), probe({ machineName: 'b' })], policy, a())).shown[0].kind).toBe('member')
})
- it('tells Jev about tools, devices, an empty history, a missed floor and absent notes', () => {
- const r = ok(choose([probe({ quality: 1 })], policy, a({ difficulty: 'high' })))
- const q = jevQuestion({ ...base, title: 'T' }, a({ needs: { tools: ['git', 'node'], devices: ['cam'] } }), { ...policy, notes: '' }, r)
- expect(q.state.lead).toContain('tools: git, node; devices: cam')
- expect(q.state.policy).toContain('no candidate meets it')
- expect(q.state.policy).toContain('Notes: none')
- expect(q.state.history).toContain('No earlier attempts in this group.')
- })
- it('ends the Lead\'s reason with exactly one period, whatever the Lead ended it with', () => {
- const r = ok(choose([probe({ quality: 3 })], policy, a()))
- const lead = (why: string) => jevQuestion({ ...base, title: 'T' }, a({ why }), policy, r).state.lead
- for (const why of ['Add one function', 'Add one function.', 'Add one function...']) expect(lead(why)).toContain('Why: Add one function. Task folder')
- // A question or an exclamation is already a full stop.
- expect(lead('Is it safe?')).toContain('Why: Is it safe? Task folder')
- expect(lead('Do it now!')).toContain('Why: Do it now! Task folder')
- })
it('keeps a floor-meeting candidate even when it is low on quota or unknown', () => {
const low = { known: true, leftPercent: 5, resetsAt: null }
const r = ok(choose([probe({ quality: 1 }), probe({ quality: 3, machineName: 'mac', quota: low })], policy, a({ difficulty: 'high' })))
@@ -339,7 +300,7 @@ describe('edges', () => {
const long = 'x'.repeat(900)
const r = ok(choose([probe({ kind: 'member', agentId: 'a_1-B', name: long, machineId: 'm-1_X' }), probe({ machineName: long })], policy, a()))
const rec = recordOf({ ...r, excluded: Array.from({ length: 250 }, () => ({ title: long.slice(0, 160), reason: long })) },
- decide(r, undefined, long), a(), { ...policy, notes: '' }) as { candidates: Array<Record<string, string>>; excluded: Array<{ reason: string }>; why: string; notes: boolean; p: number | null }
+ decide(r), a(), { ...policy, notes: '' }) as { candidates: Array<Record<string, string>>; excluded: Array<{ reason: string }>; why: string; notes: boolean; p: number | null }
expect(rec.candidates.every(c => /^c\d{1,2}$/.test(c.id) && c.title.length <= 160 && c.label.length <= 640 && /^[A-Za-z0-9_-]+$/.test(c.machineId))).toBe(true)
expect(rec.excluded).toHaveLength(200)
expect(rec.excluded.every(e => e.reason.length <= 500)).toBe(true)
@@ -349,67 +310,12 @@ describe('edges', () => {
})
})
-// Every fake secret is built here from pieces, so that no source line holds a whole key shape (GitHub push protection
-// refuses those, even in a test).
-const fake = (...parts: string[]) => parts.join('')
-const AWS_ID = fake('AKIA', 'IOSFODNN7', 'EXAMPLE')
-const AWS_SECRET = fake('wJalrXUtnFEMI/', 'K7MDENG/', 'bPxRfiCYEXAMPLEKEY')
-// Random-looking 40-character base64 keys that keep a `/` inside (a leading one is not a key shape): the same twelve every run.
-const slashedKeys = Array.from({ length: 400 }, (_, i) => createHash('sha256').update(String(i)).digest('base64').slice(0, 40))
- .filter(key => key.slice(1, -1).includes('/')).slice(0, 12)
-
-describe('scrub', () => {
- it('replaces emails and each token shape, and leaves ordinary text alone', () => {
- const text = [
- 'mail [email protected] now', fake('key sk-', 'proj-', 'abcdefghijklmnop1234'), fake('gh ghp', '_abcdefghijklmnopqrstuvwx'), fake('slack xox', 'b-1234567890-abcdef'),
- fake('aws AKIA', 'ABCDEFGHIJKLMNOP'), fake('auth Bear', 'er eyJ', 'hbGciOi.abc-def_ghi'), `hex ${'a1'.repeat(16)}`, `b64 ${'Zm9vYmFy0'.repeat(5)}==`, 'plain words and /usr/bin/node stay',
- ].join('\n')
- const out = scrub(text)
- expect(out).not.toMatch(/@|sk-|ghp_|xoxb|AKIA|Bearer|a1a1a1|Zm9v/)
- expect(out.match(/\[email\]/g)).toHaveLength(1)
- expect(out.match(/\[secret\]/g)!.length).toBeGreaterThanOrEqual(7)
- expect(out).toContain('plain words and /usr/bin/node stay')
- expect(scrub('commit abc1234 at v1.2.3')).toBe('commit abc1234 at v1.2.3')
- })
- it('keeps paths, URLs, branch names, UUIDs and file names, and still catches real keys', () => {
- for (const keep of [
- 'docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md', 'https://github.com/autonomous-ai/openharness/pull/1424',
- '0xken15/feat/super-tab-jev-context-v2', '/Users/nqhieu84/harnesses/worktrees/openharness/routing-v1', '3f2b8c1e-9a4d-4e57-8b1a-6c0d2e9f7a31',
- 'feature/Add-OAuth2-Flow-For-Mobile-Clients-2026-10',
- ]) expect(scrub(`see ${keep} now`)).toBe(`see ${keep} now`)
- // A key is judged on its own, even inside a path or after an equals sign.
- for (const key of [
- fake('sk-', 'proj-', 'AbCdEf0123456789abcdefGH'), fake('ghp', '_AbCdEf0123456789abcdefghijklmn'), AWS_ID, fake('xox', 'b-123456789012-abcdefABCDEF'),
- fake('eyJ', 'hbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.', 'eyJ', 'zdWIiOiIxMjM0NTY3ODkwIn0.', 'dBjftJeZ4CVPmB92K27', 'uhbUJU1p1rwW1gFWFOEjXk'),
- fake('wJalrXUtnFEMIK7MDENG', 'bPxRfiCYEXAMPLEKEY12='),
- fake('Zm9vYmFyQmF6UXV4', 'MTIzNDU2Nzg5MEFiQ2RF', 'ZkdoSWpLbE1u'), fake('Ab3_dEf-9GhI1jKl_', 'MnO5pQr-StU7vWx_YzA2bCd4'), fake('e3b0c44298fc1c14', '9afbf4c8996fb924', '27ae41e4'),
- ]) {
- expect(scrub(`k ${key} z`)).toBe('k [secret] z')
- expect(scrub(`path/${key}/end`)).toContain('[secret]')
- }
- // Standard base64 keys keep their `/`: AWS's documented example secret key, and a fixed sample of random 40-character keys.
- expect(scrub(`secret ${AWS_SECRET} here`)).toBe('secret [secret] here')
- expect(scrub(`AWS_SECRET_ACCESS_KEY=${AWS_SECRET}`)).toBe('AWS_SECRET_ACCESS_KEY=[secret]')
- expect(slashedKeys).toHaveLength(12)
- for (const key of slashedKeys) {
- expect(scrub(`k ${key} z`)).toBe('k [secret] z')
- expect(scrub(`"${key}"`)).toBe('"[secret]"')
- }
- // A relative path of plain words is not a key, even with a digit and a capital in it.
- expect(scrub('see src/superTabs/RouteCommand/specHelpers/Util2/fixtures now')).toBe('see src/superTabs/RouteCommand/specHelpers/Util2/fixtures now')
- // Bearer needs a token-like value, and its spelling.
- expect(scrub('Bearer is a word, and bearer token too')).toBe('Bearer is a word, and bearer token too')
- expect(scrub(fake('Authorization: Bear', 'er abcdefghij', '0123456789klmn'))).toBe('Authorization: [secret]')
- })
-})
-
-describe('the context Jev is given', () => {
+describe('candidate labels', () => {
const now = 1_000_000
const members = (patch: Partial<Probe> = {}) => ok(choose([
probe({ kind: 'member', agentId: 'a1', name: 'Multiply', activity: 'idle', frame: frame(), repo: 'same', earlier: [{ group: 'API', outcome: 'done' }], ...patch }),
probe({ machineName: 'mac', load: { agents: 3, freeMemoryBytes: 6.5e9, hasFolder: true } }),
], policy, a(), now))
- const ask = (patch: Record<string, unknown> = {}, choice = members()) => jevQuestion({ ...base, ...patch }, a({ needs: { tools: [], devices: [], cwd: '/w/api' } }), policy, choice)
it('tells what a member is doing, where, and whether it is the task\'s repository', () => {
const label = members().shown.find(s => s.kind === 'member')!.label
@@ -460,104 +366,6 @@ describe('the context Jev is given', () => {
const label = ok(choose([probe({ quota })], policy, a(), now)).shown[0].label
expect(label).toContain('quota 5-hour 40% left (resets in 2h), weekly 90% left (resets in 5 days), window 75% left')
})
- it('names the task folder and its repository in the Lead\'s assessment', () => {
- expect(ask({ folder: folder() }).state.lead).toContain('Task folder: api (git repository api)')
- expect(ask({ folder: folder({ cwd: '/w/notes', kind: 'none', name: null, root: null }) }).state.lead).toContain('Task folder: notes (not a git repository)')
- expect(ask({ folder: folder({ kind: 'unknown', name: null }) }).state.lead).toContain('Task folder: api (repository unknown)')
- expect(ask({ folder: folder({ cwd: '/', name: null }) }).state.lead).toContain('Task folder: / (git repository )')
- expect(ask({ folder: folder({ kind: 'missing', name: null, root: null, remote: null }) }).state.lead).toContain('Task folder: api (not on the Lead\'s machine)')
- expect(ask({ folder: null }).state.lead).toContain('Task folder: not stated')
- expect(ask({ folder: folder() }).state.lead).not.toContain('/w/')
- })
- it('gives the last messages as a role-tagged transcript, newest last, and marks missing or empty ones', () => {
- const messages = Array.from({ length: 4 }, (_, i) => ({ from: i % 2 ? 'Lead' : 'person', text: `m${i}` }))
- expect(ask({ messages }).state.task).toContain('Recent messages:\nperson: m0\nLead: m1\nperson: m2\nLead: m3')
- expect(ask({ messages: [] }).state.task).toContain('Recent messages: none')
- expect(ask({ messages: null }).state.task).toContain('Recent messages: unknown')
- expect(ask({ messages: [], noneInLatest: true }).state.task).toContain('Recent messages: none in the latest 100 messages')
- expect(ask({ messages: [{ from: 'Multiply', text: 'x' }] }).state.task).toContain('Multiply: x')
- })
- it('tells the policy: the cost scale and why the floor is what it is', () => {
- const policyText = (assessment: Assessment, p = policy) => { const c = ok(choose([probe({ quality: 3 })], p, assessment, now)); return jevQuestion(base, assessment, p, c).state.policy }
- expect(policyText(a({ difficulty: 'high', risk: 'low' }))).toContain('Quality floor: 3 (difficulty high needs quality 3).')
- expect(policyText(a({ difficulty: 'medium', risk: 'high' }))).toContain('Quality floor: 3 (difficulty medium needs quality 2, plus 1 for high risk).')
- expect(policyText(a({ difficulty: 'high', risk: 'high' }))).toContain('Quality floor: 3 (difficulty high needs quality 3, plus 1 for high risk, at most 3).')
- expect(policyText(a())).toContain('Cost is relative: cost 3 is about 3 times cost 1.')
- })
- it('lists all attempts in the group with their outcome and a cut result, and the last routing decisions', () => {
- const q = ask({ attempts: [{ agent: 'Multiply', outcome: 'stopped', result: 'r'.repeat(300) }, { agent: 'New agent (claude opus)', outcome: 'done' }],
- recent: [{ title: 'Multiply · Claude sonnet medium · remote-1', via: 'jev', outcome: 'stopped' }, { title: 'New agent · Codex', via: 'order', outcome: null }] })
- expect(q.state.history).toContain(`- Multiply: stopped — ${'r'.repeat(199)}…`)
- expect(q.state.history).toContain('- New agent (claude opus): done')
- expect(q.state.history).toContain('- Multiply · Claude sonnet medium · remote-1 (jev): stopped')
- expect(q.state.history).toContain('- New agent · Codex (order): open')
- expect(ask({ recent: [{ title: 'Pick', outcome: 'done' }] }).state.history).toContain('- Pick: done')
- expect(ask({ recent: null }).state.history).toContain('Recent routing in this Super Tab: unknown')
- expect(ask({ recent: [] }).state.history).toContain('Recent routing in this Super Tab: none')
- })
- it('keeps the newest of too many messages and attempts, with a mark for what was dropped', () => {
- const words = (i: number) => `msg${i} ${'lorem ipsum '.repeat(40)}`.slice(0, 500).padEnd(500, '.')
- const messages = Array.from({ length: 10 }, (_, i) => ({ from: 'person', text: words(i) }))
- const task = ask({ messages }).state.task
- const part = task.slice(task.indexOf('Recent messages:'))
- expect(part.length).toBeLessThanOrEqual('Recent messages:\n'.length + 3500)
- expect(part).toContain('…\n')
- expect(part.endsWith(words(9))).toBe(true)
- expect(part).not.toContain('msg0')
- const attempts = Array.from({ length: 60 }, (_, i) => ({ agent: `Agent${i}`, outcome: 'stopped', result: 'x'.repeat(200) }))
- const history = ask({ attempts }).state.history
- expect(history).toContain('Agent59')
- expect(history).not.toContain('Agent0:')
- expect(history).toMatch(/…/)
- })
- it('scrubs emails and secrets everywhere, so no @ or token reaches Jev', () => {
- const dirty = fake('ping [email protected] with sk-', 'abcdefghijklmnopqrstu and Bear', 'er abcdef.ghijklmnop.qrstuvwxyz and ghp', '_abcdefghijklmnopqrstuvw')
- const choice = ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'Multiply', frame: frame({ title: dirty, branch: '[email protected]' }), repo: 'same', earlier: [{ group: dirty, outcome: 'done' }] }),
- probe({ machineName: 'mac' })], policy, a(), now))
- const q = jevQuestion({ ...base, title: dirty, brief: dirty, checks: [dirty], messages: [{ from: 'person', text: dirty }],
- attempts: [{ agent: 'Multiply', outcome: 'stopped', result: dirty }], recent: [{ title: dirty, via: 'jev', outcome: null }] },
- a({ why: dirty, needs: { tools: [], devices: [], cwd: '/w/[email protected]' } }), { ...policy, notes: dirty }, choice)
- const all = JSON.stringify(q)
- expect(all).not.toMatch(/@|sk-abc|ghp_|Bearer/)
- expect(all).toContain('[email]')
- expect(all).toContain('[secret]')
- })
- it('stays within every hosted limit and its own budget at the worst case', () => {
- const long = (c: string, n: number) => c.repeat(n)
- const probes = Array.from({ length: 12 }, (_, i) => probe({ kind: 'member', agentId: `a${i}`, name: long('N', 80), machineName: long('M', 80), model: long('o', 200), activity: 'idle',
- frame: frame({ title: long('T', 300), project: long('P', 300), branch: long('Q', 300) }), repo: 'same',
- earlier: Array.from({ length: 9 }, () => ({ group: long('G', 90), outcome: 'stopped' })),
- quota: { known: true, leftPercent: 50, resetsAt: now + 1e9, windows: [{ name: '5-hour', leftPercent: 50, resetsAt: now + 3_600_000 }, { name: 'weekly', leftPercent: 70, resetsAt: now + 5 * 86_400_000 }] } }))
- const choice = ok(choose(probes, { ...policy, notes: long('n', 3000) }, a(), now))
- const q = jevQuestion({ title: long('t', 500), brief: long('k', 9000), checks: Array.from({ length: 30 }, () => long('q', 200)),
- messages: Array.from({ length: 10 }, () => ({ from: long('X', 90), text: long('m', 2000) })), folder: folder({ cwd: `/${long('z', 300)}`, name: long('r', 300) }),
- attempts: Array.from({ length: 40 }, () => ({ agent: long('Y', 90), outcome: 'stopped', result: long('x', 900) })),
- recent: Array.from({ length: 5 }, () => ({ title: long('R', 200), via: 'jev', outcome: 'stopped' })) },
- a({ why: long('w', 300), needs: { tools: Array.from({ length: 20 }, () => long('t', 80)), devices: Array.from({ length: 20 }, () => long('/z', 40)), cwd: `/${long('z', 300)}` } }),
- { ...policy, notes: long('n', 3000) }, choice)
- expect(Object.keys(q.state)).toEqual(['task', 'lead', 'policy', 'history'])
- const limit = { task: 7000, lead: 1000, policy: 1000, history: 6000 } as const
- for (const key of Object.keys(limit) as Array<keyof typeof limit>) {
- expect(q.state[key].length).toBeLessThanOrEqual(limit[key])
- // Whole messages and attempts are kept or dropped, so a part may end up to one line short of its budget.
- expect(q.state[key].length).toBeGreaterThan(limit[key] - 700)
- }
- expect(Object.values(q.state).reduce((sum, v) => sum + v.length, 0)).toBeLessThanOrEqual(15_000)
- const labels = Object.values(q.questions.who.criteria)
- expect(labels).toHaveLength(12)
- expect(labels.every(l => l.length <= 640)).toBe(true)
- expect(labels.some(l => l.endsWith('…'))).toBe(true)
- expect(q.questions.who.instructions.length).toBeLessThanOrEqual(1500)
- expect(contextSize(q)).toBe(Object.values(q.state).reduce((sum, v) => sum + v.length, 0) + labels.reduce((sum, l) => sum + l.length, 0) + q.questions.who.instructions.length)
- // The parts that matter stay: the end of the messages and the task's own budgets.
- expect(q.state.task).toContain('Brief: ' + long('k', 100))
- expect(q.state.task).toContain('Recent messages:')
- })
- it('records the size of the context and what was missing, only when given', () => {
- const c = members(), v = decide(c, undefined, 'BUSY')
- expect(recordOf(c, v, a(), policy, { chars: 5000, missing: ['messages'] })).toMatchObject({ context: { chars: 5000, missing: ['messages'] } })
- expect(recordOf(c, v, a(), policy)).not.toHaveProperty('context')
- })
})
describe('repoMatch', () => {
@@ -585,3 +393,71 @@ describe('repoMatch', () => {
expect(repoMatch(missing, frame({ remote: null, root: '/w/web', cwd: '/w/web' }), true)).toBe('different')
})
})
+
+describe('the owner\'s rules', () => {
+ const rule = (r: SwarmRule['rule'], text = 'Rule.'): SwarmRule => ({ rule: r, text })
+ const titles = (r: ReturnType<typeof choose>) => ok(r).shown.map(s => s.title)
+ const haiku = probe({ machineName: 'cheap', model: 'haiku', effort: 'auto', quality: 2, cost: 1 })
+ const sonnet = probe({ machineName: 'mac' })
+ it('leaves out a candidate that breaks a hard rule, with the owner\'s words as the reason', () => {
+ const r = ok(choose([haiku, sonnet], policy, a(), NOW, [], [rule({ kind: 'forbidModel', model: 'HAIKU' }, 'No Haiku.')]))
+ expect(r.shown.map(s => s.machineName)).toEqual(['mac'])
+ expect(r.excluded).toEqual([{ title: 'New agent · Claude haiku auto · cheap', reason: 'Breaks the owner\'s rule: No Haiku.' }])
+ // A full model id is caught too, a rule for another engine is not, and `default` is never matched.
+ expect(breaks([rule({ kind: 'forbidModel', model: 'haiku' })], { machineId: 'm', engine: 'claude', model: 'claude-haiku-4-5', effort: 'high' })).toContain('Rule.')
+ expect(breaks([rule({ kind: 'forbidModel', engine: 'codex', model: 'haiku' })], { machineId: 'm', engine: 'claude', model: 'haiku', effort: 'high' })).toBeNull()
+ // `default` is not known, so nothing matches it; a rule naming a full id matches the alias a start asks for.
+ expect(breaks([rule({ kind: 'forbidModel', model: 'def' })], { machineId: 'm', engine: 'codex', model: 'default', effort: 'high' })).toBeNull()
+ expect(breaks([rule({ kind: 'forbidModel', model: 'claude-haiku-4-5' })], { machineId: 'm', engine: 'claude', model: 'haiku', effort: 'high' })).toContain('Rule.')
+ expect(breaks([rule({ kind: 'forbidModel', model: 'claude-haiku-4-5' })], { machineId: 'm', engine: 'claude', model: 'sonnet', effort: 'high' })).toBeNull()
+ })
+ it('keeps agents to the owner\'s machines', () => {
+ const r = choose([sonnet, probe({ machineId: 'm2', machineName: 'other' })], policy, a(), NOW, [], [rule({ kind: 'machines', machineIds: ['m2'] })])
+ expect(titles(r)).toEqual(['New agent · Claude sonnet medium · other'])
+ // When nobody is left, the Lead is told why each one was left out.
+ expect(choose([sonnet], policy, a(), NOW, [], [rule({ kind: 'machines', machineIds: ['m9'] }, 'Only m9.')]))
+ .toEqual({ error: 'NO_CANDIDATE', excluded: [{ title: 'New agent · Claude sonnet medium · mac', reason: 'Breaks the owner\'s rule: Only m9.' }] })
+ })
+ it('holds a minimum effort, and lifts a new agent whose effort the engine chooses to that minimum', () => {
+ const codex = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'default', quality: 3, cost: 2 })
+ const member = probe({ kind: 'member', agentId: 'a1', name: 'Low', effort: 'low' })
+ const unknown = probe({ kind: 'member', agentId: 'a2', name: 'Auto', effort: 'auto' })
+ const r = ok(choose([codex, member, unknown, sonnet], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'high' }, 'High effort.')]))
+ expect(r.shown.map(s => s.title)).toEqual(['New agent · Codex default high · box'])
+ expect(r.excluded.map(e => e.title)).toEqual(['Low · Claude sonnet low · remote-1', 'Auto · Claude sonnet auto · remote-1', 'New agent · Claude sonnet medium · mac'])
+ // The highest minimum that applies to the engine wins; one for another engine is ignored.
+ const two = ok(choose([codex], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'medium' }), rule({ kind: 'minEffort', engine: 'codex', effort: 'xhigh' }), rule({ kind: 'minEffort', engine: 'claude', effort: 'max' })]))
+ expect(two.shown[0].effort).toBe('xhigh')
+ // A lifted row that equals another on the same machine is shown once.
+ const high = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'high', quality: 3, cost: 2 })
+ expect(ok(choose([codex, high], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'high' })])).shown.map(s => s.title)).toEqual(['New agent · Codex default high · box'])
+ const auto = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'auto', quality: 3, cost: 2 })
+ expect(ok(choose([codex, auto], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'high' })])).shown).toHaveLength(1)
+ // Without a minimum, nothing is lifted.
+ expect(ok(choose([codex], policy, a(), NOW, [], [rule({ kind: 'minEffort', engine: 'claude', effort: 'high' })])).shown[0].effort).toBe('default')
+ })
+ it('ranks by the preferred engine for the task\'s kind, before cost, without changing who is shown', () => {
+ const codex = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'default', quality: 2, cost: 3 })
+ const plain = ok(choose([codex, sonnet], policy, a(), NOW))
+ expect(plain.shown.map(s => s.engine)).toEqual(['claude', 'codex'])
+ const rules = [rule({ kind: 'preferEngine', taskKind: 'ui', engine: 'codex' }), rule({ kind: 'preferEngine', taskKind: null, engine: 'claude' })]
+ expect(ok(choose([codex, sonnet], policy, a({ kind: 'ui' }), NOW, [], rules)).shown.map(s => s.engine)).toEqual(['codex', 'claude'])
+ // Another kind falls to the rule for every task.
+ expect(ok(choose([sonnet, codex], policy, a({ kind: 'docs' }), NOW, [], rules)).shown.map(s => s.engine)).toEqual(['claude', 'codex'])
+ expect(ok(choose([codex, sonnet], policy, a(), NOW, [], [rules[0]])).shown).toHaveLength(plain.shown.length)
+ })
+ it('puts idle members first, then the least busy machine, when the owner prefers idle agents', () => {
+ const member = probe({ kind: 'member', agentId: 'a1', name: 'Idle', cost: 3, quality: 2 })
+ const busy = probe({ machineName: 'busy', cost: 1, load: { agents: 5, freeMemoryBytes: null, hasFolder: null } })
+ const quiet = probe({ machineName: 'quiet', cost: 2, load: { agents: 1, freeMemoryBytes: null, hasFolder: null } })
+ const unread = probe({ machineName: 'unread', cost: 1 })
+ expect(titles(choose([busy, member, quiet, unread], policy, a(), NOW))[0]).toBe('New agent · Claude sonnet medium · busy')
+ expect(titles(choose([busy, member, quiet, unread], policy, a(), NOW, [], [rule({ kind: 'preferIdle' })])).map(t => t.split(' · ')[0] === 'Idle' ? 'Idle' : t.split(' · ')[2]))
+ .toEqual(['Idle', 'quiet', 'busy', 'unread'])
+ })
+ it('parses the task\'s kind', () => {
+ expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x', kind: 'ui' })).toMatchObject({ kind: 'ui' })
+ expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x', kind: 'UI work' })).toContain('kind')
+ expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x' })).not.toHaveProperty('kind')
+ })
+})
diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.ts
index db6ec4c12..a519079aa 100644
--- a/cli/src/superTabs/route.ts
+++ b/cli/src/superTabs/route.ts
@@ -1,16 +1,23 @@
/** Super Tab routing v1, the pure half (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md), ordered by
* strength, quota fit and effective cost since phase 1 (docs/plans/2026-10-21-swarm-routing-phase1.md).
- * The system removes what cannot run the task, Jev chooses among the rest with the full context, and a
- * fixed policy order decides when Jev is unsure or unavailable. Jev's acceptance rule is the voice
- * router's (`jevPick`), tuned on the owner's desk on 2026-10-10. */
-import { basename, isAbsolute } from 'node:path'
-import type { JevChoice, JevChoiceAnswer } from '../lib/jev/jevClient.js'
+ * The system removes what cannot run the task or breaks one of the owner's hard rules, and the first in a fixed order
+ * (the owner's soft rules, then the policy order) is the pick (docs/plans/2026-10-22-swarm-rules-routing.md). Jev chose
+ * among the candidates until 2026-10-22, when the Lead overrode it about half the time because it did not know the rules. */
+import { isAbsolute } from 'node:path'
import { claudeAliasForModel } from '../engines/claude/runtimeProfile.js'
-import { jevPick } from '../lib/routeDecide.js'
export type Level = 'low' | 'medium' | 'high'
export type Size = 'small' | 'medium' | 'large'
-export interface Assessment { difficulty: Level; risk: Level; size: Size; why: string; needs: { tools: string[]; devices: string[]; cwd?: string } }
+/** `kind` is a word the Lead may give (`ui`, `docs`) for the owner's preferred-engine rules; a review group's is `review`. */
+export interface Assessment { difficulty: Level; risk: Level; size: Size; why: string; kind?: string; needs: { tools: string[]; devices: string[]; cwd?: string } }
+/** The owner's rules as the backend keeps them (backend/src/superTabs/rules.ts); only the rule and its words are read here. */
+export type Rule =
+ | { kind: 'forbidModel'; engine?: string; model: string }
+ | { kind: 'machines'; machineIds: string[] }
+ | { kind: 'minEffort'; engine?: string; effort: string }
+ | { kind: 'preferEngine'; taskKind: string | null; engine: string }
+ | { kind: 'preferIdle' }
+export interface SwarmRule { rule: Rule; text: string }
export interface PolicyModel { engine: 'claude' | 'codex'; model: string; effort: string; quality: number; cost: number; enabled: boolean }
export interface Policy { version: 1; models: PolicyModel[]; floor: Record<Level, number>; quotaReserve: number; notes: string }
/** One usage window, named by the reader (`5-hour`, `weekly`); `leftPercent` is what remains of it. */
@@ -44,7 +51,7 @@ export interface Commitment { account: string; spend: Partial<Record<Window, num
export interface Shown extends Probe { id: string; title: string; label: string; fit: Fit }
/** `short` is set when no candidate is expected to cover the task, to tell the Lead. */
export interface Choice { shown: Shown[]; excluded: Array<{ title: string; reason: string }>; floor: number; belowFloor: boolean; short?: string }
-export interface Verdict { pick: Shown; via: 'jev' | 'order' | 'only'; p: number | null; why: string; fallback?: 'unsure' | 'unavailable' }
+export interface Verdict { pick: Shown; via: 'order' | 'only'; p: null; why: string }
const LEVELS: Level[] = ['low', 'medium', 'high']
/** Run time and spend per window by task size, for a policy row of cost 2 (owner's table, 2026-10-21); not in the policy yet. */
@@ -58,37 +65,40 @@ const MAX_SHOWN = 12
const ENGINE = { claude: 'Claude', codex: 'Codex' } as const
const cut = (text: string, max: number) => text.length <= max ? text : `${text.slice(0, max - 1)}…`
-/** Jev is a hosted model, so nothing that identifies a person or opens an account goes to it. Emails and the common
- * key shapes are replaced before any text is cut, so a cut never leaves half a key behind. A long hex run is taken
- * for a key even when it is a commit id: a lost id costs less than a leaked key. */
-const SECRETS = [
- /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}/g, /\bgh[pousr]_[A-Za-z0-9]{20,}/g, /\bxox[a-z]-[A-Za-z0-9-]{10,}/g, /\bAKIA[0-9A-Z]{16}\b/g,
- /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/g, /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g, /\b[0-9a-fA-F]{32,}\b/g,
-]
-/** A base64 or base64url key, as opposed to a path, a URL or a branch name that is just as long: it has all three of
- * upper case, lower case and digits, and no words joined by hyphens. `/` and `.` end a run, so a long path is judged by
- * its segments and a JWT by its parts. */
-const keyLike = (run: string) => /[A-Z]/.test(run) && /[a-z]/.test(run) && /\d/.test(run) && !/[A-Z]?[a-z]{3,}-[A-Z]?[a-z]{3,}/.test(run)
-/** Standard base64 uses `/`, which also separates path pieces. A whole token (not a path from the root, no dot) is a key
- * when it looks like one and none of its pieces is a plain word, which a relative path would have. */
-const plainWord = (piece: string) => /^[A-Z]?[a-z]{5,}$/.test(piece)
-const slashedKey = (token: string) => /^[A-Za-z0-9+/]{32,}={0,2}$/.test(token) && token.includes('/') && keyLike(token) && !token.split('/').some(plainWord)
-export function scrub(text: string): string {
- const plain = SECRETS.reduce((t, pattern) => t.replace(pattern, '[secret]'), text.replace(/[^\s@<>()"',;]+@[^\s@<>()"',;]+/g, '[email]'))
- return plain.replace(/[^\s"'=:,;()<>]+/g, token => slashedKey(token) ? '[secret]' : token)
- .replace(/[A-Za-z0-9+_=-]{32,}/g, run => keyLike(run) ? '[secret]' : run)
+const EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+/** `default` and `auto` say nothing about the effort, so they never meet a minimum. */
+const rank = (effort: string) => EFFORTS.indexOf(effort)
+const applies = (rule: { engine?: string }, engine: string) => !rule.engine || rule.engine === engine
+const FAMILY = /haiku|sonnet|opus|fable/
+/** The backend's `modelMatches`: `haiku` matches every Haiku id, `claude-haiku-4-5` also the `haiku` alias, and nothing
+ * matches `default`, which is not known. */
+function modelMatches(ruleModel: string, model: string): boolean {
+ const rule = ruleModel.toLowerCase(), target = model.toLowerCase()
+ return target !== 'default' && (target.includes(rule) || (FAMILY.exec(target)?.[0] === target && FAMILY.exec(rule)?.[0] === target))
}
-const fit = (text: string, max: number) => cut(scrub(text), max)
-/** The newest lines that fit, for logs where the end matters most; a leading mark says older ones were dropped. */
-function newest(lines: string[], max: number): string {
- if (lines.join('\n').length <= max) return lines.join('\n')
- let kept = ''
- for (let i = lines.length - 1; i >= 0; i--) {
- const next = kept ? `${lines[i]}\n${kept}` : lines[i]
- if (next.length > max - 2) break
- kept = next
- }
- return `…\n${kept}`
+
+/** The backend's check (backend/src/superTabs/rules.ts `broken`), so a pick shown here is never refused when it is
+ * started, assigned or recorded. */
+export function breaks(rules: SwarmRule[], p: { machineId: string; engine: string; model: string; effort: string }): string | null {
+ const out = rules.find(({ rule }) => rule.kind === 'forbidModel' ? applies(rule, p.engine) && modelMatches(rule.model, p.model)
+ : rule.kind === 'machines' ? !rule.machineIds.includes(p.machineId)
+ : rule.kind === 'minEffort' && applies(rule, p.engine) && rank(p.effort) < rank(rule.effort))
+ return out ? `Breaks the owner's rule: ${out.text}` : null
+}
+/** A new agent whose policy row leaves the effort to the engine starts at the owner's minimum instead (Lead, 2026-10-22), so
+ * a minimum does not rule out the Codex `default` row. */
+function lifted(rules: SwarmRule[], p: Probe): Probe {
+ if (p.kind !== 'new' || rank(p.effort) >= 0) return p
+ const least = Math.max(-1, ...rules.flatMap(({ rule }) => rule.kind === 'minEffort' && applies(rule, p.engine) ? [rank(rule.effort)] : []))
+ return least < 0 ? p : { ...p, effort: EFFORTS[least] }
+}
+/** The soft rules for this task: the engine preferred for its kind (a rule for the kind before one for every task), and
+ * whether idle agents come first. */
+interface Soft { engine: string | null; idle: boolean }
+function softOf(rules: SwarmRule[], kind: string | undefined): Soft {
+ const prefer = rules.flatMap(({ rule }) => rule.kind === 'preferEngine' ? [rule] : [])
+ const engine = (prefer.find(r => kind && r.taskKind === kind) ?? prefer.find(r => r.taskKind === null))?.engine ?? null
+ return { engine, idle: rules.some(r => r.rule.kind === 'preferIdle') }
}
export function parseAssessment(value: unknown): Assessment | string {
@@ -104,7 +114,9 @@ export function parseAssessment(value: unknown): Assessment | string {
const list = (x: unknown) => Array.isArray(x) && x.every(i => typeof i === 'string') ? x as string[] : []
const cwd = needs.cwd
if (cwd !== undefined && (typeof cwd !== 'string' || !isAbsolute(cwd))) return 'needs.cwd must be an absolute path.'
- return { difficulty: v.difficulty as Level, risk: v.risk as Level, size: size as Size, why, needs: { tools: list(needs.tools), devices: list(needs.devices), ...(cwd ? { cwd } : {}) } }
+ if (v.kind !== undefined && (typeof v.kind !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(v.kind))) return 'Set kind to one lowercase word, such as ui or docs.'
+ return { difficulty: v.difficulty as Level, risk: v.risk as Level, size: size as Size, why, ...(v.kind ? { kind: v.kind as string } : {}),
+ needs: { tools: list(needs.tools), devices: list(needs.devices), ...(cwd ? { cwd } : {}) } }
}
export const floorFor = (policy: Policy, a: Assessment): number => Math.min(3, policy.floor[a.difficulty] + (a.risk === 'high' ? 1 : 0))
@@ -151,7 +163,7 @@ export function rateFor(policy: Policy, engine: string, model: string | null, ef
}
const titleOf = (p: Probe) => cut(`${p.kind === 'member' ? p.name ?? 'Member' : 'New agent'} · ${ENGINE[p.engine]} ${p.model} ${p.effort} · ${p.machineName}`, 160)
-/** Jev does not know the time, so a reset or a last activity is told as how far away it is. */
+/** A reset or a last activity is told as how far away it is, which reads the same whenever the log is opened. */
function span(ms: number): string {
if (ms < 3_600_000) return `${Math.max(1, Math.round(ms / 60_000))}m`
// Under ten hours, half an hour decides whether a task fits before the reset, so it keeps its minutes (4h30).
@@ -177,8 +189,8 @@ function memberText(p: Probe, now: number): string[] {
const f = p.frame
const repo = p.repo ? [p.repo === 'unknown' ? 'repo unknown' : `${p.repo} repo`] : []
if (!f) return [...repo, 'activity unknown']
- const where = [f.project && fit(f.project, 40), f.branch && `branch ${fit(f.branch, 40)}`].filter(Boolean).join(', ')
- return [...repo, ...(f.title ? [`on "${fit(f.title, 80)}"`] : []), ...(where ? [f.project ? `in ${where}` : where] : []),
+ const where = [f.project && cut(f.project, 40), f.branch && `branch ${cut(f.branch, 40)}`].filter(Boolean).join(', ')
+ return [...repo, ...(f.title ? [`on "${cut(f.title, 80)}"`] : []), ...(where ? [f.project ? `in ${where}` : where] : []),
f.updatedAt === null ? 'last active unknown' : `last active ${span(Math.max(0, now - f.updatedAt))} ago`]
}
function machineText(load: MachineLoad): string[] {
@@ -186,15 +198,15 @@ function machineText(load: MachineLoad): string[] {
load.agents === null ? 'agents running unknown' : `${load.agents} ${load.agents === 1 ? 'agent' : 'agents'} running`,
load.freeMemoryBytes === null ? 'free memory unknown' : `${bytes(load.freeMemoryBytes)} memory free`]
}
-/** The most telling parts come first and the least last, because the hosted limit cuts the end. */
-const labelOf = (p: Probe & Sized, now: number) => fit([
- p.kind === 'member' ? `Member ${fit(p.name ?? '', 40)}`.trim() : 'New agent', `${ENGINE[p.engine]} ${p.model} ${p.effort}`, `quality ${p.quality}, cost ${p.cost}`,
- p.text, fit(p.machineName, 40), p.activity, ...(p.kind === 'member' ? memberText(p, now) : p.load ? machineText(p.load) : []),
- ...(p.earlier?.length ? [`earlier here: ${p.earlier.slice(0, 3).map(e => `${fit(e.group, 40)} ${e.outcome}`).join('; ')}`] : []), quotaText(p.quota, now),
+/** The most telling parts come first and the least last, because the log's limit cuts the end. */
+const labelOf = (p: Probe & Sized, now: number) => cut([
+ p.kind === 'member' ? `Member ${cut(p.name ?? '', 40)}`.trim() : 'New agent', `${ENGINE[p.engine]} ${p.model} ${p.effort}`, `quality ${p.quality}, cost ${p.cost}`,
+ p.text, cut(p.machineName, 40), p.activity, ...(p.kind === 'member' ? memberText(p, now) : p.load ? machineText(p.load) : []),
+ ...(p.earlier?.length ? [`earlier here: ${p.earlier.slice(0, 3).map(e => `${cut(e.group, 40)} ${e.outcome}`).join('; ')}`] : []), quotaText(p.quota, now),
].join(' · '), 640)
interface Measured { name: Window; usable: number; needed: number; resetsIn: number | null }
-/** A probe's fit, its tightest window (the one that runs out first) and the sentence Jev reads. */
+/** A probe's fit, its tightest window (the one that runs out first) and the sentence the log keeps. */
interface Sized { fit: Fit; tight: Measured | null; text: string }
const pct = (n: number) => `${Math.round(n)}%`
const round = (n: number) => Math.round(n * 100) / 100
@@ -232,20 +244,29 @@ const WAY = ['right away', 'about a quarter of the way in', 'about halfway', 'ab
const runsOut = (w: Measured) => `The ${w.name} window is expected to run out ${WAY[Math.round(Math.max(0, w.usable / w.needed) * 4)]}${w.resetsIn === null ? '' : `; resets in ${span(w.resetsIn)}`}.`
const UNREAD = 'Its quota could not be read in full, and another candidate\'s quota fits this task.'
-/** The fixed policy order: cheaper in effect, stronger, more room on the tightest window, an idle member in the task's
- * repository before a new agent, then by title. */
-function compare(x: Probe & Sized, y: Probe & Sized): number {
+/** The fixed order: the owner's preferred engine, an idle member before a new agent and a less busy machine first when the
+ * owner prefers idle agents; then the policy order: cheaper in effect, stronger, more room on the tightest window, an idle
+ * member in the task's repository before a new agent, then by title. */
+function compare(x: Probe & Sized, y: Probe & Sized, soft: Soft): number {
const placed = (p: Probe) => p.kind === 'member' && (p.repo ?? 'same') === 'same' ? 0 : 1
- return x.fit.effectiveCost - y.fit.effectiveCost
+ const preferred = (p: Probe) => soft.engine && p.engine !== soft.engine ? 1 : 0
+ const fresh = (p: Probe) => soft.idle && p.kind === 'new' ? 1 : 0
+ const busy = (p: Probe) => soft.idle && p.kind === 'new' ? p.load?.agents ?? 1000 : 0
+ return preferred(x) - preferred(y) || fresh(x) - fresh(y) || busy(x) - busy(y)
+ || x.fit.effectiveCost - y.fit.effectiveCost
|| y.quality - x.quality
|| (y.tight?.usable ?? -Infinity) - (x.tight?.usable ?? -Infinity)
|| placed(x) - placed(y)
|| titleOf(x).localeCompare(titleOf(y))
}
-export function choose(probes: Probe[], policy: Policy, a: Assessment, now: number = Date.now(), open: Commitment[] = []): Choice | { error: 'NO_CANDIDATE'; excluded: Array<{ title: string; reason: string }> } {
- const excluded = probes.filter(p => p.refusals.length).map(p => ({ title: titleOf(p), reason: p.refusals.join(' ') }))
- const viable = probes.filter(p => !p.refusals.length)
+export function choose(probes: Probe[], policy: Policy, a: Assessment, now: number = Date.now(), open: Commitment[] = [], rules: SwarmRule[] = []): Choice | { error: 'NO_CANDIDATE'; excluded: Array<{ title: string; reason: string }> } {
+ // A lifted row can equal another row on the same machine (Codex `default` lifted to high beside Codex high); one is kept.
+ const raised = probes.map(p => lifted(rules, p)), key = (p: Probe) => `${p.kind}\0${p.machineId}\0${p.engine}\0${p.model}\0${p.effort}`
+ const ruled = raised.filter((p, i) => p === probes[i] || !raised.some((q, j) => j !== i && key(q) === key(p) && (q === probes[j] || j < i)))
+ .map(p => { const why = breaks(rules, p); return why ? { ...p, refusals: [...p.refusals, why] } : p })
+ const excluded = ruled.filter(p => p.refusals.length).map(p => ({ title: titleOf(p), reason: p.refusals.join(' ') }))
+ const viable = ruled.filter(p => !p.refusals.length)
if (!viable.length) return { error: 'NO_CANDIDATE', excluded }
const floor = floorFor(policy, a)
const meeting = viable.filter(p => p.quality >= floor)
@@ -257,87 +278,28 @@ export function choose(probes: Probe[], policy: Policy, a: Assessment, now: numb
const status = (['fits', 'unknown', 'short'] as const).find(s => sized.some(p => p.fit.status === s))!
excluded.push(...sized.filter(p => p.fit.status !== status).map(p => ({ title: titleOf(p), reason: p.fit.status === 'unknown' ? UNREAD : runsOut(p.tight!) })))
// When every candidate is short, the one expected to get furthest goes first.
- const set = sized.filter(p => p.fit.status === status).sort((x, y) => status === 'short' ? y.fit.coverage! - x.fit.coverage! || compare(x, y) : compare(x, y))
+ const soft = softOf(rules, a.kind)
+ const set = sized.filter(p => p.fit.status === status).sort((x, y) => status === 'short' ? y.fit.coverage! - x.fit.coverage! || compare(x, y, soft) : compare(x, y, soft))
const shown = set.slice(0, MAX_SHOWN).map(({ tight, text, ...p }, i) => ({ ...p, id: `c${i}`, title: titleOf(p), label: labelOf({ ...p, tight, text }, now) }))
const first = set[0].tight!
return { shown, excluded, floor, belowFloor: !meeting.length, ...(status === 'short'
? { short: `No candidate is expected to cover this task; its ${first.name} quota is expected to run out partway${first.resetsIn === null ? '' : ` and resets in ${span(first.resetsIn)}`}.` } : {}) }
}
-const INSTRUCTIONS = cut([
- 'Choose the candidate that should do this task.',
- 'The Lead assessed its difficulty and risk; every candidate shown meets the quality floor unless the policy says none does.',
- 'The list is already ordered by strength for the difficulty, fit and effective cost. Keep the first unless the task, its history or the policy notes give a clear reason otherwise.',
- 'A member marked "same repo" already has the task\'s code open, which saves a start; prefer it over an equal candidate.',
- 'A candidate that already failed or stopped on this task is a worse choice. A member that is idle in the Super Tab saves a start.',
- 'Unknown means the information could not be read; it is not a bad sign.',
-].join(' '), 1500)
-
-const folderText = (f: TaskFolder | null) => !f ? 'not stated'
- : `${fit(basename(f.cwd) || f.cwd, 80)} (${f.kind === 'git' ? `git repository ${fit(f.name ?? '', 80)}` : f.kind === 'none' ? 'not a git repository'
- : f.kind === 'missing' ? 'not on the Lead\'s machine' : 'repository unknown'})`
-
-export interface JevInput {
- title: string; brief: string; checks: string[]
- /** The last messages as `person`, `Lead` or an agent's name; null when they could not be read. */
- messages: Array<{ from: string; text: string }> | null
- /** True when the latest page of the group held only log rows (routing notes, transcripts), so "none" would mislead. */
- noneInLatest?: boolean
- folder: TaskFolder | null; attempts: Attempt[]
- /** The Super Tab's latest routing decisions; null when they could not be read. */
- recent: RecentRoute[] | null
-}
-
-/** The hosted route allows 4 keys and 17,000 characters of state. Each key has its own budget so that one long
- * brief cannot push out the messages or the history. */
-export function jevQuestion(input: JevInput, a: Assessment, policy: Policy, choice: Choice) {
- const messages = input.messages === null ? 'Recent messages: unknown' : input.messages.length
- ? `Recent messages:\n${newest(input.messages.map(m => `${fit(m.from, 40)}: ${fit(m.text, 600)}`), 3500)}` : `Recent messages: none${input.noneInLatest ? ' in the latest 100 messages' : ''}`
- const base = policy.floor[a.difficulty]
- const risk = a.risk === 'high' ? `, plus 1 for high risk${base + 1 > 3 ? ', at most 3' : ''}` : ''
- const floor = `Quality floor: ${choice.floor} (difficulty ${a.difficulty} needs quality ${base}${risk})${choice.belowFloor ? '; no candidate meets it, so all are shown' : ''}. `
- + 'Cost is relative: cost 3 is about 3 times cost 1. Notes: '
- const attempts = input.attempts.length
- ? `Attempts in this group:\n${newest(input.attempts.map(t => `- ${fit(t.agent, 60)}: ${fit(t.outcome, 20)}${t.result ? ` — ${fit(t.result, 200)}` : ''}`), 4700)}` : 'No earlier attempts in this group.'
- const recent = input.recent === null ? 'Recent routing in this Super Tab: unknown' : input.recent.length
- ? `Recent routing in this Super Tab:\n${input.recent.map(r => `- ${fit(r.title, 200)}${r.via ? ` (${fit(r.via, 20)})` : ''}: ${r.outcome ? fit(r.outcome, 20) : 'open'}`).join('\n')}` : 'Recent routing in this Super Tab: none'
- const state = {
- task: fit(`Group: ${fit(input.title, 160)}\nBrief: ${fit(input.brief, 2000)}\nChecks:\n${fit(input.checks.map(c => `- ${c}`).join('\n'), 1000)}\n${messages}`, 7000),
- lead: fit(`Difficulty: ${a.difficulty}. Risk: ${a.risk}. Why: ${/[!?]$/.test(a.why) ? a.why : `${a.why.replace(/\.+$/, '')}.`} Task folder: ${folderText(input.folder)}. Needs tools: ${a.needs.tools.join(', ') || 'none'}; devices: ${a.needs.devices.join(', ') || 'none'}.`, 1000),
- policy: fit(`${floor}${policy.notes || 'none'}`, 1000),
- history: fit(`${attempts}\n\n${recent}`, 6000),
- }
- const questions: Record<string, JevChoice> = {
- who: { type: 'choice', instructions: INSTRUCTIONS, criteria: Object.fromEntries(choice.shown.map(s => [s.id, s.label])) },
- }
- return { state, questions }
-}
-
-/** How many characters Jev was given in all, for the decision log. */
-export const contextSize = (q: ReturnType<typeof jevQuestion>): number =>
- Object.values(q.state).reduce((sum, v) => sum + v.length, 0) + Object.values(q.questions.who.criteria).reduce((sum, v) => sum + v.length, 0) + q.questions.who.instructions.length
-
-export function decide(choice: Choice, answer: JevChoiceAnswer | undefined, unavailable: string | null): Verdict {
- const first = choice.shown[0]
- if (choice.shown.length === 1) return { pick: first, via: 'only', p: null, why: 'Only candidate that can run this task.' }
- const picked = unavailable ? undefined : jevPick(answer, choice.shown.map(s => s.id), true)
- if (picked) {
- const pick = choice.shown.find(s => s.id === picked)!
- return { pick, via: 'jev', p: answer!.probabilities[picked], why: `Jev chose ${pick.title}.` }
- }
- const reason = unavailable ? `Jev unavailable (${unavailable})` : 'Jev unsure'
- return { pick: first, via: 'order', p: null, why: `${reason}; first in the policy order.`, fallback: unavailable ? 'unavailable' : 'unsure' }
+export function decide(choice: Choice): Verdict {
+ const pick = choice.shown[0]
+ return choice.shown.length === 1 ? { pick, via: 'only', p: null, why: 'Only candidate that can run this task.' }
+ : { pick, via: 'order', p: null, why: "First by the owner's rules and the policy order." }
}
/** `v1` leaves out size and fit, for a backend from before phase 1, whose strict schema refuses them. */
-export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, policy: Policy, context?: { chars: number; missing: string[] }, v1 = false): Record<string, unknown> {
+export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, policy: Policy, v1 = false): Record<string, unknown> {
return {
assessment: { difficulty: a.difficulty, risk: a.risk, why: a.why, ...(v1 ? {} : { size: a.size }) },
candidates: choice.shown.map(s => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,
engine: s.engine, model: s.model, effort: s.effort, quality: s.quality, cost: s.cost, title: s.title, label: s.label, ...(v1 ? {} : { fit: s.fit }) })),
excluded: choice.excluded.slice(0, 200).map(e => ({ title: e.title, reason: cut(e.reason, 500) })),
floor: choice.floor, notes: policy.notes.length > 0,
- pick: verdict.pick.id, via: verdict.via, ...(verdict.fallback ? { fallback: verdict.fallback } : {}), p: verdict.p, belowFloor: choice.belowFloor, why: cut(verdict.why, 300),
- ...(context ? { context } : {}),
+ pick: verdict.pick.id, via: verdict.via, p: verdict.p, belowFloor: choice.belowFloor, why: cut(verdict.why, 300),
}
}
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index 7d952f031..f8fafc7f2 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -40,16 +40,10 @@ function daemon(machineId: string, options: { agents?: string[]; frames?: Record
}
}
type Answer = Record<string, unknown>
-function scoped(answers: { jev?: Answer; record?: Answer; tab?: unknown; context?: Answer; history?: Answer; historyHangs?: boolean; jevThrows?: boolean; recordThrows?: boolean } = {}) {
+function scoped(answers: { record?: Answer; tab?: unknown; context?: Answer; history?: Answer; historyHangs?: boolean; recordThrows?: boolean } = {}) {
return vi.fn(async (payload: Record<string, any>): Promise<Record<string, unknown>> => {
if (payload.action === 'routeContext') return answers.context ?? { ok: true, value: { agentId: 'lead', tab: answers.tab ?? tab(), policy: { policy, warnings: ['w'] }, machines: [{ machineId: 'm1', name: 'remote-1' }, { machineId: 'm2', name: 'mac' }] } }
- if (payload.action === 'routeHistory') return answers.historyHangs ? new Promise(() => {}) : answers.history ?? { ok: true, value: { messages: [], decisions: [], attempts: [] } }
- if (payload.action === 'routeJev') {
- if (answers.jevThrows) throw new Error('socket closed')
- // Jev answers over every candidate it was shown, as the real client's answers do.
- const ids = Object.keys(payload.questions.who.criteria)
- return answers.jev ?? { ok: true, value: { answers: { who: { choice: 'c1', probabilities: Object.fromEntries(ids.map(id => [id, id === 'c1' ? 0.9 : 0.1 / (ids.length - 1)])) } } } }
- }
+ if (payload.action === 'routeHistory') return answers.historyHangs ? new Promise(() => {}) : answers.history ?? { ok: true, value: { decisions: [], attempts: [] } }
if (payload.action === 'command') {
if (answers.recordThrows) throw new Error('socket closed')
return answers.record ?? { ok: true, value: { result: { routeDecisionId: 'd1' } } }
@@ -61,13 +55,16 @@ const where = { port: 1, dataDir: '/nonexistent', machineId: 'm1' }
const input = { tabId: 'tab', conversationId: 'g1', assessment: { difficulty: 'medium', risk: 'low', why: 'Endpoint.' } }
const opener = (make: (id: string) => ReturnType<typeof daemon> = id => daemon(id, { agents: id === 'm1' ? ['h1'] : [] })) => vi.fn(async (_w: unknown, id = '') => make(id)) as unknown as typeof openDaemon & Mock
const recorded = (s: ReturnType<typeof scoped>) => s.mock.calls.find(c => c[0].action === 'command')![0]
-const jevCall = (s: ReturnType<typeof scoped>) => s.mock.calls.find(c => c[0].action === 'routeJev')![0]
+/** Each candidate's line, as the route log keeps it. */
+const labels = (s: ReturnType<typeof scoped>) => (recorded(s).command.decision.candidates as Array<{ label: string }>).map(c => c.label)
describe('routeTask', () => {
- it('collects members and new agents, asks Jev, records and returns the pick', async () => {
+ it('collects members and new agents, records and returns the first in the order, and never asks Jev', async () => {
const s = scoped()
const result = await routeTask(input, s, where as never, opener(), () => 'op')
- expect(result).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'jev', pick: { id: 'c1' }, warnings: ['w'] })
+ expect(result).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'order', p: null, pick: { id: 'c0' }, warnings: ['w'] })
+ expect(s.mock.calls.map(c => c[0].action)).toEqual(['routeContext', 'routeHistory', 'command'])
+ expect(recorded(s).command.decision).not.toHaveProperty('context')
const record = recorded(s)
expect(record).toMatchObject({ operationId: 'route-op', command: { type: 'route.record', conversationId: 'g1' } })
// The idle Lead is not a candidate (neither the group's nor the tab's); the idle member Multiply is.
@@ -84,11 +81,25 @@ describe('routeTask', () => {
expect(offered.length).toBeGreaterThan(0)
expect(offered.some(c => /^(Lead|Multiply) ·/.test(c))).toBe(false)
})
+ it('does not offer a member that is already working on a task', async () => {
+ const s = scoped({ tab: tab({ id: 'x', agentId: 'a1', status: 'working' }) })
+ await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['h1'] })))
+ expect((recorded(s).command.decision.candidates as Array<{ title: string }>).some(c => c.title.startsWith('Multiply'))).toBe(false)
+ })
+ it('leaves out what breaks the owner\'s rules in the tab, and ignores a rule it cannot read', async () => {
+ const ruled = tab(); (ruled.state as Record<string, unknown>).rules = [{ id: 'r1', rule: { kind: 'forbidModel', model: 'sonnet' }, text: 'No Sonnet.' }, { id: 'r2', text: 7 }]
+ const s = scoped({ tab: ruled })
+ const result = await routeTask(input, s, where as never, opener(), () => 'op')
+ expect(result).toMatchObject({ ok: true, pick: { model: 'opus' }, belowFloor: false })
+ const decision = recorded(s).command.decision
+ expect(decision.candidates.every((c: { model: string }) => c.model === 'opus')).toBe(true)
+ expect(decision.excluded).toEqual(expect.arrayContaining([{ title: 'Multiply · Claude sonnet medium · remote-1', reason: 'Breaks the owner\'s rule: No Sonnet.' }]))
+ })
it('offers a Reviewer only for a review group, and starts a new one as a Reviewer', async () => {
const offered = async (reviewer: boolean, reviewGroup: boolean) => {
const t = tab(); t.state.agents = agents.map(a => a.id === 'a1' && reviewer ? { ...a, role: 'reviewer' } : a)
if (reviewGroup) (t.state.conversations[1] as Record<string, unknown>).reviewOf = 'g0'
- const s = scoped({ tab: t, jev: { ok: true, value: { unavailable: 'BUSY' } } })
+ const s = scoped({ tab: t })
const result = await routeTask(input, s, where as never, opener(), () => 'op')
const titles = (recorded(s).command.decision.candidates as Array<{ title: string }>).map(c => c.title)
return { member: titles.some(c => c.startsWith('Multiply')), next: String(result.next) }
@@ -101,11 +112,11 @@ describe('routeTask', () => {
expect((await offered(false, false)).next).not.toContain('"role"')
})
it('tells the Lead how to assign a member or start a new agent with the decision', async () => {
- const member = await routeTask(input, scoped({ jev: { ok: true, value: { unavailable: 'BUSY' } } }), where as never, opener(), () => 'op')
+ const member = await routeTask(input, scoped(), where as never, opener(), () => 'op')
// Cheapest first: the member on sonnet.
expect(member).toMatchObject({ pick: { kind: 'member', agentId: 'a1' } })
expect(member.next).toContain('"type":"work.assign","conversationId":"g1","agentId":"a1","routeDecisionId":"d1"')
- const fresh = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped({ jev: { ok: true, value: { unavailable: 'BUSY' } } }), where as never, opener(), () => 'op')
+ const fresh = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped(), where as never, opener(), () => 'op')
expect(fresh).toMatchObject({ pick: { kind: 'new', engine: 'claude', model: 'opus', effort: 'high' } })
expect(fresh.next).toContain('"engine":"claude","model":"opus","effort":"high","routeDecisionId":"d1"')
// Without a branch the agent starts from the default one, and the hint says how to choose another.
@@ -203,7 +214,7 @@ describe('routeTask', () => {
})
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 never
- const options = { tab: plain, record: { error: 'BACKEND_UNAVAILABLE' }, jev: { ok: true, value: { unavailable: 'BUSY' } } }
+ const options = { tab: plain, record: { error: 'BACKEND_UNAVAILABLE' } }
const easy = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'low' } }, scoped(options), where as never, opener())
expect(easy).toMatchObject({ unrecorded: true, pick: { kind: 'member', title: 'Member · Claude default default · remote-1' } })
expect(easy.next).not.toContain('routeDecisionId')
@@ -217,13 +228,6 @@ describe('routeTask', () => {
expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ error: 'LEAD_REQUIRED' })
expect(open).not.toHaveBeenCalled()
})
- it('returns a Jev-stage refusal as the result instead of falling back to the policy order', async () => {
- for (const error of ['RATE_LIMITED', 'LEAD_REQUIRED']) {
- const s = scoped({ jev: { error, detail: 'no', status: 429 } })
- expect(await routeTask(input, s, where as never, opener())).toMatchObject({ error })
- expect(s.mock.calls.some(c => c[0].action === 'command')).toBe(false)
- }
- })
it('returns a record refusal as an error, and only a transport failure as unrecorded', async () => {
expect(await routeTask(input, scoped({ record: { error: 'RATE_LIMITED', detail: 'slow down', status: 429 } }), where as never, opener()))
.toMatchObject({ error: 'RATE_LIMITED' })
@@ -253,7 +257,7 @@ describe('routeTask', () => {
})
it('prefers a member whose capacity is known over one on a machine that cannot be read', async () => {
const two = tab(); two.state.agents = [...agents, { id: 'a2', name: 'Collab', machineId: 'theirs', harnessId: 'h2', configuration: { engine: 'claude', model: 'sonnet', effort: 'medium' } }] as never
- const s = scoped({ tab: two, jev: { ok: true, value: { unavailable: 'BUSY' } } })
+ const s = scoped({ tab: two })
const open = vi.fn(async (_w: unknown, id: string) => id === 'theirs' ? Promise.reject(new Error('not yours')) : daemon(id, { agents: id === 'm1' ? ['h1'] : [] })) as never
// theirs is not in the account's list, m1 is; the unknown collaborator member is shown only as a fallback.
const result = await routeTask(input, s, where as never, open)
@@ -281,7 +285,7 @@ describe('routeTask', () => {
{ id: 'a3', name: 'Sonnet hand', machineId: 'm1', harnessId: 'h3', configuration: { engine: 'claude', model: 'claude-sonnet-4-5[1m]', effort: 'medium' } },
{ id: 'a4', name: 'Codex hand', machineId: 'm1', harnessId: 'h4', configuration: { engine: 'codex', model: 'gpt-5.5', effort: 'high' } },
agents[1]] as never
- const s = scoped({ tab: working, jev: { ok: true, value: { unavailable: 'BUSY' } } })
+ const s = scoped({ tab: working })
const open = opener(id => daemon(id, { agents: id === 'm1' ? ['h1', 'h3', 'h4'] : [], usage: { providers: [] }, engines: [{ engine: 'claude', installed: true, signedIn: true }, { engine: 'codex', installed: true, signedIn: true }] }))
await routeTask(input, s, where as never, open)
const rated = Object.fromEntries((recorded(s).command.decision.candidates as Array<{ title: string; quality: number; cost: number }>)
@@ -311,29 +315,19 @@ describe('routeTask', () => {
expect(v1.command.decision.assessment).not.toHaveProperty('size')
expect(v1.command.decision.candidates.some((c: object) => 'fit' in c)).toBe(false)
})
- it('falls back to the policy order when Jev is unavailable, and still routes when recording fails', async () => {
- const result = await routeTask(input, scoped({ jev: { ok: true, value: { unavailable: 'BUSY' } }, record: { error: 'BACKEND_UNAVAILABLE' } }), where as never, opener())
+ it('still routes when recording fails or the connection is lost', async () => {
+ const result = await routeTask(input, scoped({ record: { error: 'BACKEND_UNAVAILABLE' } }), where as never, opener())
expect(result).toMatchObject({ ok: true, via: 'order', unrecorded: true })
expect(result).not.toHaveProperty('routeDecisionId')
- })
- it('treats a failed Jev answer or a lost connection as Jev unavailable and still routes', async () => {
- const failed = await routeTask(input, scoped({ jev: { error: 'AGENT_UNAVAILABLE' } }), where as never, opener())
- expect(failed).toMatchObject({ ok: true, via: 'order' })
- expect(failed.why).toContain('UNAVAILABLE')
- const lost = await routeTask(input, scoped({ jevThrows: true, recordThrows: true }), where as never, opener())
+ const lost = await routeTask(input, scoped({ recordThrows: true }), where as never, opener())
expect(lost).toMatchObject({ ok: true, via: 'order', unrecorded: true })
- const noAnswer = await routeTask(input, scoped({ jev: { ok: true, value: { answers: {} } } }), where as never, opener())
- expect(noAnswer).toMatchObject({ ok: true, via: 'order' })
- const s = scoped(); await routeTask(input, s, where as never, opener())
- expect(jevCall(s).conversationId).toBe('g1')
})
- it('does not ask Jev when only one candidate can run the task', async () => {
+ it('says when the pick was the only candidate that can run the task', async () => {
const s = scoped()
// Only the member's machine answers, and its engine is not installed for a new agent.
const open = vi.fn(async (_w: unknown, id: string) => id === 'm1'
? daemon(id, { agents: ['h1'], engines: [{ engine: 'claude', installed: false }] }) as never : Promise.reject(new Error('gone')))
expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ ok: true, via: 'only', pick: { agentId: 'a1' } })
- expect(s.mock.calls.filter(c => c[0].action === 'routeJev')).toHaveLength(0)
})
it('refuses an invalid assessment, an unknown group and a failed context read', async () => {
const open = vi.fn()
@@ -363,19 +357,6 @@ describe('routeTask', () => {
await routeTask(input, t, where as never, opener(id => daemon(id, { listFails: true })))
expect(recorded(t).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ reason: 'Its terminal is not running.' })]))
})
- it('gives the history of a group whose last attempt ended', async () => {
- for (const [assignment, line] of [
- [{ id: 'x', agentId: 'a1', status: 'stopped', result: 'Tests failed.' }, 'Multiply: stopped — Tests failed.'],
- [{ id: 'x', agentId: 'gone', status: 'done' }, 'An agent: done'],
- ] as const) {
- const s = scoped({ tab: tab(assignment) })
- await routeTask(input, s, where as never, opener())
- expect(jevCall(s).state.history).toContain(`- ${line}`)
- }
- const s = scoped({ tab: tab({ id: 'x', agentId: 'a1', status: 'working' }) })
- await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['h1'] })))
- expect(jevCall(s).state.history).toContain('No earlier attempts in this group.')
- })
it('keeps a group without brief or checks routable', async () => {
const odd = tab(); const group = odd.state.conversations[1] as Record<string, unknown>
delete group.brief; group.title = undefined; group.checks = [{}]
@@ -416,7 +397,7 @@ describe('routeTask', () => {
})
})
-describe('the context routeTask gives Jev', () => {
+describe('what the route log says about each candidate', () => {
const git = (patch: Record<string, unknown> = {}) => ({ kind: 'git', name: 'api', cwd: '/w/api', root: '/w/api', remote: 'github.com/acme/api', branch: 'main', ...patch })
/** The Lead's machine, as the folder reader sees it: the folder is there (unless said otherwise) and the SCM describes it. */
const describeGit = (found: unknown = git(), isDirectory = true) => ({ describe: vi.fn(async () => found) as unknown as typeof describeScmProject & Mock, isDirectory: vi.fn(async () => isDirectory) })
@@ -428,26 +409,20 @@ describe('the context routeTask gives Jev', () => {
const world = (extra: Record<string, unknown> = {}, assignment: unknown = null) => {
const { tab: given, ...past } = extra
return { context: { ok: true, value: { agentId: 'lead', tab: given ?? tab(assignment), policy: { policy, warnings: [] }, machines: [{ machineId: 'm1', name: 'remote-1' }, { machineId: 'm2', name: 'mac' }] } },
- history: { ok: true, value: { messages: [{ from: 'person', text: 'Please add the endpoint.' }, { from: 'Lead', text: 'On it.' }], decisions: [], attempts: [], ...past } } }
+ history: { ok: true, value: { decisions: [], attempts: [], ...past } } }
}
- const labels = (s: ReturnType<typeof scoped>) => Object.values(jevCall(s).questions.who.criteria as Record<string, string>)
const memberLabel = (s: ReturnType<typeof scoped>) => labels(s).find(l => l.startsWith('Member Multiply'))!
const newLabel = (s: ReturnType<typeof scoped>) => labels(s).find(l => l.startsWith('New agent'))!
- it('reads the messages, the task folder, the member frames and the machines, and gives Jev what each says', async () => {
+ it('reads the task folder, the member frames and the machines, and labels each candidate with what they say', async () => {
const s = scoped(world())
const make = (id: string) => daemon(id, { agents: id === 'm1' ? ['h1', 'x', 'y'] : ['z'], frames: { h1: frame() } })
const describeRepo = describeGit()
await routeTask(withCwd, s, where as never, opener(make), () => 'op', describeRepo)
expect(describeRepo.describe).toHaveBeenCalledWith('/w/api')
expect(describeRepo.isDirectory).toHaveBeenCalledWith('/w/api')
- expect(jevCall(s).state.task).toContain('Recent messages:\nperson: Please add the endpoint.\nLead: On it.')
- expect(jevCall(s).state.lead).toContain('Task folder: api (git repository api)')
expect(memberLabel(s)).toContain('same repo · on "Fix auth" · in api, branch feat/auth · last active 2h ago')
expect(labels(s).some(l => /^New agent.*remote-1.*has the task folder · 3 agents running · 7\.0 GB memory free/.test(l))).toBe(true)
- expect(recorded(s).command.decision.context).toEqual({ chars: expect.any(Number), missing: [] })
- expect(recorded(s).command.decision.context.chars).toBeGreaterThan(1000)
- expect(recorded(s).command.decision.context.chars).toBeLessThan(17_000 + 31 * 640)
})
it('marks a member in another repository, and one it cannot compare', async () => {
const other = frame({ project: git({ name: 'web', remote: 'github.com/acme/web', root: '/w/web', cwd: '/w/web' }) })
@@ -460,7 +435,6 @@ describe('the context routeTask gives Jev', () => {
const u = scoped(world())
await routeTask(input, u, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: frame() } })), () => 'op')
expect(memberLabel(u)).not.toMatch(/repo/)
- expect(u.mock.calls.find(c => c[0].action === 'command')![0].command.decision.context.missing).toEqual([])
})
it('compares a member on another machine by remote only, and uses the branch the frame\'s project reports', async () => {
const two = tab(); two.state.agents = [{ ...agents[0], machineId: 'm2' }, agents[1]] as never
@@ -475,20 +449,14 @@ describe('the context routeTask gives Jev', () => {
await routeTask(withCwd, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: { title: 5, updatedAt: 'later', project: null } } })), () => 'op', describeGit({ kind: 'none', cwd: '/w/api', root: null, remote: null, name: 'api', branch: null }))
expect(memberLabel(s)).toMatch(/repo unknown · last active unknown/)
expect(memberLabel(s)).not.toMatch(/on "|branch/)
- expect(jevCall(s).state.lead).toContain('Task folder: api (not a git repository)')
})
- it('tells Jev what the group and the Super Tab have tried: ended attempts from the state and the log, and the last five decisions', async () => {
+ it('labels a member with its earlier work in this Super Tab, from the state and the log', async () => {
const decision = (id: string, conversationId: string, patch: Record<string, unknown> = {}) => ({ id, conversationId, title: `Pick ${id}`, via: 'jev', outcome: 'stopped', assignmentId: `as-${id}`,
createdAt: '2026-10-19T10:00:00Z', final: { kind: 'new', engine: 'claude', model: 'opus' }, ...patch })
const decisions = [{ ...decision('d7', 'g1', { outcome: null, assignmentId: null, final: null }), via: undefined }, decision('d6', 'g1', { outcome: 'done', assignmentId: 'x', final: { kind: 'member', agentId: 'a1' } }), decision('d5', 'g1'),
decision('d4', 'other', { final: { kind: 'member', agentId: 'a1' }, outcome: 'done' }), decision('d3', 'g1', { final: null }), decision('d2', 'lead'), decision('d1', 'g1', { outcome: 'superseded' }), decision('d0', 'g1', { final: { kind: 'member', agentId: 'gone' } })]
const s = scoped(world({ decisions }, { id: 'x', agentId: 'a1', status: 'done', result: 'Shipped.' }))
await routeTask(input, s, where as never, opener())
- const history = jevCall(s).state.history as string
- // Oldest first: the log's attempt by an agent the tab no longer has, its stopped new-agent attempt, then the member's finished one with the result its assignment holds.
- expect(history).toMatch(/Attempts in this group:\n- An agent: stopped\n- New agent \(claude opus\): stopped\n- Multiply: done — Shipped\./)
- expect(history).toContain('Recent routing in this Super Tab:\n- Pick d7: open\n- Pick d6 (jev): done\n- Pick d5 (jev): stopped\n- Pick d4 (jev): done\n- Pick d3 (jev): stopped')
- expect(history).not.toContain('Pick d2')
// Multiply's earlier work in this Super Tab: the finished assignment (also in the log), and the log's one in a group this tab no longer has.
expect(memberLabel(s)).toContain('earlier here: API done; another group done')
})
@@ -513,52 +481,33 @@ describe('the context routeTask gives Jev', () => {
await routeTask(input, s, where as never, opener())
expect(memberLabel(s)).toContain('Claude opus high')
})
- it('keeps a stopped attempt in the history and in the member\'s earlier work after the group was defined again', async () => {
+ it('keeps a stopped attempt in the member\'s earlier work after the group was defined again', async () => {
// `work.define` took the stopped assignment out of the state and no decision of the log names it (a person assigned it).
// A row without an id names no assignment and is left out.
const attempts = [{ agentId: 'a1', status: 'done' }, { id: 'as-2', agentId: 'a1', status: 'done', result: 'Shipped.' }, { id: 'as-1', agentId: 'a1', status: 'stopped', result: 'Tests failed.' }]
const s = scoped(world({ attempts }))
await routeTask(input, s, where as never, opener())
- expect(jevCall(s).state.history).toContain('Attempts in this group:\n- Multiply: stopped — Tests failed.\n- Multiply: done — Shipped.')
expect(memberLabel(s)).toContain('earlier here: API done; API stopped')
})
- it('orders the group\'s attempts oldest first, a person\'s assignment before a routed one, and keeps the newest for the member', async () => {
+ it('orders the member\'s attempts oldest first, a person\'s assignment before a routed one', async () => {
// as-1 was assigned by a person (no decision); as-2 was routed. The log alone would list as-2 first.
const decision = { id: 'd2', conversationId: 'g1', title: 'Pick', via: 'jev', outcome: 'done', assignmentId: 'as-2', createdAt: '2026-10-19T11:00:00Z', final: { kind: 'member', agentId: 'a1' } }
const attempts = [{ id: 'as-2', agentId: 'a1', status: 'done', result: 'Second.', createdAt: '2026-10-19T11:00:00Z' }, { id: 'as-1', agentId: 'a1', status: 'stopped', result: 'First.', createdAt: '2026-10-19T10:00:00Z' }]
const s = scoped(world({ decisions: [decision], attempts }, { id: 'as-3', agentId: 'a1', status: 'stopped', result: 'Third.' }))
await routeTask(input, s, where as never, opener())
- expect(jevCall(s).state.history).toContain('Attempts in this group:\n- Multiply: stopped — First.\n- Multiply: done — Second.\n- Multiply: stopped — Third.')
expect(memberLabel(s)).toContain('earlier here: API stopped; API done; API stopped')
// Without the attempts read the log's order stays.
const old = scoped(world({ decisions: [decision], attempts: undefined, attemptsUnreadable: true }, { id: 'as-3', agentId: 'a1', status: 'stopped', result: 'Third.' }))
await routeTask(input, old, where as never, opener())
- expect(jevCall(old).state.history).toContain('Attempts in this group:\n- Multiply: done\n- Multiply: stopped — Third.')
+ expect(memberLabel(old)).toContain('earlier here: API stopped; API done')
})
it('lists an attempt once when the log and the attempts both know it', async () => {
const decision = { id: 'd5', conversationId: 'g1', title: 'Pick', via: 'jev', outcome: 'stopped', assignmentId: 'as-1', createdAt: '2026-10-19T10:00:00Z', final: { kind: 'new', engine: 'claude', model: 'opus' } }
const s = scoped(world({ decisions: [decision], attempts: [{ id: 'as-1', agentId: 'gone', status: 'stopped', result: 'Out of memory.' }] }, { id: 'as-2', agentId: 'a1', status: 'done', result: 'Shipped.' }))
await routeTask(input, s, where as never, opener())
- const history = jevCall(s).state.history as string
- // The log names the started agent; the attempt gives the result.
- expect(history).toContain('Attempts in this group:\n- New agent (claude opus): stopped — Out of memory.\n- Multiply: done — Shipped.')
- expect(history.match(/Out of memory/g)).toHaveLength(1)
expect(memberLabel(s)).toContain('earlier here: API done')
})
- it('cuts an attempt\'s result to 200 characters and scrubs it', async () => {
- const result = `Key sk-${'a1'.repeat(20)} sent to [email protected]. ${'x'.repeat(400)}`
- const s = scoped(world({ attempts: [{ id: 'as-1', agentId: 'a1', status: 'stopped', result }] }))
- await routeTask(input, s, where as never, opener())
- const line = (jevCall(s).state.history as string).split('\n').find(l => l.startsWith('- Multiply: stopped'))!
- expect(line).toContain('[secret] sent to [email]')
- expect(line).not.toMatch(/@|sk-/)
- expect(line.length).toBeLessThanOrEqual('- Multiply: stopped — '.length + 200)
- })
- it('keeps the log\'s name for a started agent whose assignment names an agent the tab no longer has', async () => {
- const decision = { id: 'd5', conversationId: 'g1', title: 'Pick', via: 'jev', outcome: 'stopped', assignmentId: 'as-5', createdAt: '2026-10-19T10:00:00Z', final: { kind: 'new', engine: 'claude', model: 'opus' } }
- const s = scoped(world({ decisions: [decision] }, { id: 'as-5', agentId: 'gone', status: 'stopped', result: 'Out of memory.' }))
- await routeTask(input, s, where as never, opener())
- expect(jevCall(s).state.history).toContain('- New agent (claude opus): stopped — Out of memory.')
+ it('finds nothing to admit on a machine that reports no capacity', async () => {
// A machine that reports no capacity measured nothing, so nothing there can be admitted; the route says so.
expect(await routeTask(withCwd, scoped(world()), where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], capacity: {} })), () => 'op', describeGit())).toMatchObject({ error: 'NO_CANDIDATE' })
})
@@ -571,41 +520,29 @@ describe('the context routeTask gives Jev', () => {
expect(memberLabel(s)).toContain('earlier here: Group 4 stopped; Group 3 stopped; Group 2 stopped')
expect(memberLabel(s)).not.toContain('Group 1')
})
- it('still routes when a source cannot be read, and lists each one in the decision', async () => {
+ it('still routes when a source cannot be read', async () => {
const run = async (extra: Record<string, unknown>, options: Record<string, unknown> = {}, describeRepo: ReturnType<typeof describeGit> = describeGit()) => {
const s = scoped(world(extra))
const answer = await routeTask(withCwd, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: frame() }, ...options })), () => 'op', describeRepo)
expect(answer).toMatchObject({ ok: true })
- return { s, missing: recorded(s).command.decision.context.missing as string[] }
+ return s
}
- expect((await run({})).missing).toEqual([])
- const noMessages = await run({ messages: undefined, messagesUnreadable: true })
- expect(jevCall(noMessages.s).state.task).toContain('Recent messages: unknown')
- expect(noMessages.missing).toEqual(['messages'])
- // An older backend (404) and a failed read both leave the attempts out: today's history, and a note in the decision.
- const noAttempts = await run({ attempts: undefined, attemptsUnreadable: true })
- expect(jevCall(noAttempts.s).state.history).toContain('No earlier attempts in this group.')
- expect(noAttempts.missing).toEqual(['attempts'])
- const noLog = await run({ decisions: undefined, decisionsUnreadable: true })
- expect(jevCall(noLog.s).state.history).toContain('Recent routing in this Super Tab: unknown')
- expect(noLog.missing).toEqual(['route log'])
+ expect(memberLabel(await run({}))).toContain('same repo')
+ // An older backend (404) and a failed read both leave the attempts and the log out.
+ expect(memberLabel(await run({ attempts: undefined, attemptsUnreadable: true }))).toContain('same repo')
+ expect(memberLabel(await run({ decisions: undefined, decisionsUnreadable: true }))).toContain('same repo')
for (const failing of [vi.fn(async () => { throw new Error('git') }), vi.fn(async () => null)]) {
- const noFolder = await run({}, {}, { ...describeGit(), describe: failing as never })
- expect(jevCall(noFolder.s).state.lead).toContain('Task folder: api (repository unknown)')
- expect(memberLabel(noFolder.s)).toContain('repo unknown')
- expect(noFolder.missing).toEqual(['task folder'])
+ expect(memberLabel(await run({}, {}, { ...describeGit(), describe: failing as never }))).toContain('repo unknown')
}
// A folder read that never answers does not hold the route: it is given up after three seconds.
vi.useFakeTimers()
try {
const pending = run({}, {}, { ...describeGit(), describe: vi.fn(() => new Promise(() => {})) as never })
await vi.advanceTimersByTimeAsync(3000)
- expect((await pending).missing).toEqual(['task folder'])
+ expect(memberLabel(await pending)).toContain('repo unknown')
} finally { vi.useRealTimers() }
// Without the agent list there is no machine load; the members there cannot run, so only new agents are shown.
- const noList = await run({}, { listFails: true })
- expect(noList.missing).toEqual(['machine load'])
- expect(newLabel(noList.s)).toContain('agents running unknown')
+ expect(newLabel(await run({}, { listFails: true }))).toContain('agents running unknown')
})
it('finds a member in the task\'s folder when the Lead\'s machine does not have it', async () => {
const two = tab(); two.state.agents = [{ ...agents[0], machineId: 'm2' }, agents[1]] as never
@@ -614,26 +551,25 @@ describe('the context routeTask gives Jev', () => {
const reader = describeGit(git(), false)
await routeTask(withCwd, s, where as never, opener(id => daemon(id, { agents: id === 'm2' ? ['h1'] : [], frames: { h1: there } })), () => 'op', reader)
expect(memberLabel(s)).toContain('same repo')
- expect(jevCall(s).state.lead).toContain('Task folder: api (not on the Lead\'s machine)')
expect(reader.describe).not.toHaveBeenCalled()
- expect(recorded(s).command.decision.context.missing).toEqual(['task folder'])
})
it('says a folder is unknown, not missing, when it cannot be told apart from a refusal', async () => {
for (const code of ['EACCES', 'ENOTDIR']) {
const s = scoped(world())
await routeTask(withCwd, s, where as never, opener(), () => 'op', { describe: vi.fn() as never, isDirectory: async () => { throw Object.assign(new Error(code), { code }) } })
- expect(jevCall(s).state.lead).toContain('Task folder: api (repository unknown)')
- expect(recorded(s).command.decision.context.missing).toEqual(['task folder'])
+ expect(memberLabel(s)).toContain('repo unknown')
}
})
it('reads the task folder on this machine when no reader is given', async () => {
const dir = await mkdtemp(join(tmpdir(), 'route-folder-'))
try {
await writeFile(join(dir, 'file'), 'x')
- for (const [cwd, folder] of [[dir, 'not a git repository'], [join(dir, 'absent'), 'not on the Lead\'s machine'], [join(dir, 'file', 'inside'), 'repository unknown']] as const) {
+ // A member standing in the folder is in it when the folder is there or absent here; a broken path says nothing.
+ for (const [cwd, repo] of [[dir, 'same repo'], [join(dir, 'absent'), 'same repo'], [join(dir, 'file', 'inside'), 'repo unknown']] as const) {
const s = scoped(world())
- await routeTask({ ...input, assessment: { ...input.assessment, needs: { cwd } } }, s, where as never, opener(), () => 'op')
- expect(jevCall(s).state.lead).toContain(folder)
+ const there = frame({ project: { name: 'x', cwd, root: null, remote: null } })
+ await routeTask({ ...input, assessment: { ...input.assessment, needs: { cwd } } }, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: there } })), () => 'op')
+ expect(memberLabel(s)).toContain(repo)
}
} finally { await rm(dir, { recursive: true, force: true }) }
})
@@ -647,11 +583,9 @@ describe('the context routeTask gives Jev', () => {
// Both context reads are still waiting, and the machines have already been opened.
expect(s.mock.calls.some(c => c[0].action === 'routeHistory')).toBe(true)
expect(open).toHaveBeenCalled()
- expect(s.mock.calls.some(c => c[0].action === 'routeJev')).toBe(false)
await vi.advanceTimersByTimeAsync(3000)
expect(await pending).toMatchObject({ ok: true })
} finally { vi.useRealTimers() }
- expect(recorded(s).command.decision.context.missing).toEqual(expect.arrayContaining(['messages', 'route log', 'attempts', 'task folder']))
})
it('lists a member whose machine cannot be opened as one whose activity is unknown', async () => {
const two = tab(); two.state.agents = [...agents, { id: 'a2', name: 'Collab', machineId: 'theirs', harnessId: 'h2', configuration: { engine: 'claude', model: 'sonnet', effort: 'medium' } }] as never
@@ -659,14 +593,6 @@ describe('the context routeTask gives Jev', () => {
const open = vi.fn(async (_w: unknown, id: string) => id === 'theirs' ? Promise.reject(new Error('not yours')) : daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: frame() }, usage: { providers: [] } })) as never
await routeTask(input, s, where as never, open)
expect(labels(s).find(l => l.startsWith('Member Collab'))).toContain('activity unknown')
- expect(recorded(s).command.decision.context.missing).toEqual(['member activity'])
- })
- it('records no context when Jev was not asked', async () => {
- const s = scoped(world())
- const open = vi.fn(async (_w: unknown, id: string) => id === 'm1'
- ? daemon(id, { agents: ['h1'], engines: [{ engine: 'claude', installed: false }] }) as never : Promise.reject(new Error('gone')))
- expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ via: 'only' })
- expect(recorded(s).command.decision).not.toHaveProperty('context')
})
})
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index 3b17c138d..f48346ac4 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -1,15 +1,15 @@
/** `harness super-tab route GROUP JSON`: the Lead's routing step (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md).
- * Reads the tab, the effective policy and the account's machines; probes each machine once per engine with
- * the same admission `start` uses; then orders, asks Jev, and records the decision in the tab. */
+ * Reads the tab, its rules, the effective policy and the account's machines; probes each machine once per engine with
+ * the same admission `start` uses; then filters and orders by the rules (docs/plans/2026-10-22-swarm-rules-routing.md)
+ * and records the decision in the tab. */
import { randomUUID } from 'node:crypto'
import { openDaemon, type Daemon, type Where } from '../agentClient/daemon.js'
import { startRequirements } from './capacity.js'
import { inspectCapacity, type ScopedRequest } from './start.js'
import { ENDED_WORK, object, within } from './wire.js'
-import { choose, contextSize, decide, jevQuestion, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Attempt, type Commitment, type MemberFrame, type Policy, type Probe, type TaskFolder } from './route.js'
+import { choose, decide, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'
import { stat } from 'node:fs/promises'
import { describeScmProject } from '../scm/scmProjects.js'
-import type { JevChoiceAnswer } from '../lib/jev/jevClient.js'
type Json = Record<string, unknown>
const ENGINES = ['claude', 'codex']
@@ -51,27 +51,24 @@ function withLaunchEffort(member: Json, starts: Json[]): Json {
}
const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
-/** Work that ended in this Super Tab, oldest first: the log's decisions, the group's attempts and each group's last
- * assignment, joined by assignment id. The log knows which agent a decision started; the attempts are every earlier
- * assignment of this group, also those `work.define` took out of the state (a person's assignment has no decision);
- * the state knows the agent and the result of each group's last one. */
-interface Ended { assignmentId: string; groupId: string; group: string; agentId: string | null; agent: string; outcome: string; result?: string }
-function endedWork(conversations: Json[], agents: Json[], decisions: Json[] | null, attempts: Json[] | null, attemptsGroup: string): Ended[] {
+/** Work that ended in this Super Tab, oldest first, for each member's earlier work: the log's decisions, the group's
+ * attempts and each group's last assignment, joined by assignment id. The log knows which agent a decision started; the
+ * attempts are every earlier assignment of this group, also those `work.define` took out of the state (a person's
+ * assignment has no decision); the state knows the agent of each group's last one. */
+interface Ended { assignmentId: string; group: string; agentId: string | null; outcome: string }
+function endedWork(conversations: Json[], decisions: Json[] | null, attempts: Json[] | null, attemptsGroup: string): Ended[] {
const titleOf = (id: unknown) => String(conversations.find(c => c.id === id)?.title ?? 'another group')
- const nameOf = (id: unknown) => text(agents.find(a => a.id === id)?.name)
const ended: Ended[] = [...(decisions ?? [])].reverse().flatMap(d => {
const final = object(d.final)
return typeof d.assignmentId === 'string' && ENDED_WORK.includes(String(d.outcome)) && final.kind
- ? [{ assignmentId: d.assignmentId, groupId: String(d.conversationId), group: titleOf(d.conversationId), outcome: String(d.outcome),
- agentId: final.kind === 'member' ? String(final.agentId) : null,
- agent: final.kind === 'member' ? nameOf(final.agentId) ?? 'An agent' : `New agent (${String(final.engine)} ${String(final.model)})` }]
+ ? [{ assignmentId: d.assignmentId, group: titleOf(d.conversationId), outcome: String(d.outcome), agentId: final.kind === 'member' ? String(final.agentId) : null }]
: []
})
- // The assignment's own record wins on agent and outcome; a started agent the tab no longer has keeps the log's name.
+ // The assignment's own record wins on the agent: a started agent is a member by then.
const join = (assignment: Json, groupId: string) => {
- const result = text(assignment.result) ?? undefined, known = ended.find(e => e.assignmentId === assignment.id)
- if (known) return Object.assign(known, { agentId: String(assignment.agentId), agent: nameOf(assignment.agentId) ?? known.agent, result })
- const added: Ended = { assignmentId: String(assignment.id), groupId, group: titleOf(groupId), agentId: String(assignment.agentId), agent: nameOf(assignment.agentId) ?? 'An agent', outcome: String(assignment.status), result }
+ const known = ended.find(e => e.assignmentId === assignment.id)
+ if (known) return Object.assign(known, { agentId: String(assignment.agentId) })
+ const added: Ended = { assignmentId: String(assignment.id), group: titleOf(groupId), agentId: String(assignment.agentId), outcome: String(assignment.status) }
ended.push(added)
return added
}
@@ -102,8 +99,9 @@ export async function routeTask(input: { tabId: string; conversationId: string;
return { error: 'AGENT_UNAVAILABLE', detail: error instanceof Error ? error.message : 'The request to the machine failed.' }
}
}
- const assessment = parseAssessment(input.assessment)
- if (typeof assessment === 'string') return { error: 'INVALID_REQUEST', detail: assessment }
+ const parsed = parseAssessment(input.assessment)
+ if (typeof parsed === 'string') return { error: 'INVALID_REQUEST', detail: parsed }
+ let assessment = parsed
const cwd = assessment.needs.cwd
const context = await scoped({ action: 'routeContext' })
if (context.error || context.ok !== true) return context
@@ -120,6 +118,9 @@ export async function routeTask(input: { tabId: string; conversationId: string;
...conversations.filter(c => active(c.assignment)).map(c => String(object(c.assignment).agentId))])
// A review group is assigned only to a Reviewer, and a Reviewer nothing else.
const review = typeof group.reviewOf === 'string'
+ if (review) assessment = { ...assessment, kind: 'review' }
+ // A backend from before rules keeps none, so routing there is the policy order alone.
+ const rules = list(state.rules).filter(r => r.rule && typeof r.text === 'string') as unknown as SwarmRule[]
const members = agents.filter(a => !busy.has(String(a.id)) && (a.role === 'reviewer') === review && ENGINES.includes(String(object(a.configuration).engine))).map(a => withLaunchEffort(a, list(state.starts)))
// 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
@@ -157,38 +158,19 @@ export async function routeTask(input: { tabId: string; conversationId: string;
const folder: TaskFolder | null = !cwd ? null : read ?? { cwd, kind: 'unknown', name: null, root: null, remote: null }
const past = object(history?.ok === true ? history.value : {})
const decisions = Array.isArray(past.decisions) ? list(past.decisions) : null
- const messages = Array.isArray(past.messages) ? list(past.messages).map(m => ({ from: String(m.from), text: String(m.text) })) : null
const attempts = Array.isArray(past.attempts) ? list(past.attempts) : null
- const ended = endedWork(conversations, agents, decisions, attempts, input.conversationId)
+ const ended = endedWork(conversations, decisions, attempts, input.conversationId)
const probes = probed.flat().map(p => p.kind === 'member' ? { ...p, repo: repoMatch(folder, p.frame ?? null, p.machineId === where.machineId),
earlier: ended.filter(e => e.agentId === p.agentId).reverse().slice(0, 3).map(e => ({ group: e.group, outcome: e.outcome })) } : p)
// Picks started or assigned and still at work hold part of their account's quota; the log, and so this, is per Swarm.
const working = (decisions ?? []).filter(d => d.final && d.outcome === null && typeof d.account === 'string')
.map(d => ({ account: d.account, spend: object(d.spend), size: d.size, createdAt: Date.parse(String(d.createdAt)) }) as Commitment)
- const choice = choose(probes, policy, assessment, Date.now(), working)
+ const choice = choose(probes, policy, assessment, Date.now(), working, rules)
if ('error' in choice) return choice
- // What Jev could not be told, for the decision log: pick quality can later be compared with how complete this was.
- const missing = [...(messages ? [] : ['messages']), ...(decisions ? [] : ['route log']), ...(attempts ? [] : ['attempts']), ...(folder && ['unknown', 'missing'].includes(folder.kind) ? ['task folder'] : []),
- ...(choice.shown.some(s => s.kind === 'member' && !s.frame) ? ['member activity'] : []),
- ...(choice.shown.some(s => s.kind === 'new' && (s.load!.agents === null || s.load!.freeMemoryBytes === null)) ? ['machine load'] : [])]
-
- let answer: JevChoiceAnswer | undefined, unavailable: string | null = null, question: ReturnType<typeof jevQuestion> | undefined
- if (choice.shown.length > 1) {
- const checks = list(group.checks).map(c => String(c.description ?? ''))
- // Every attempt in this group that ended: a worker that stopped on this task is a worse choice.
- const attempts: Attempt[] = ended.filter(e => e.groupId === input.conversationId).map(e => ({ agent: e.agent, outcome: e.outcome, ...(e.result ? { result: e.result } : {}) }))
- const recent = decisions?.slice(0, 5).map(d => ({ title: String(d.title), ...(typeof d.via === 'string' ? { via: d.via } : {}), outcome: text(d.outcome) })) ?? null
- question = jevQuestion({ title: String(group.title ?? ''), brief: String(group.brief ?? ''), checks, messages, noneInLatest: past.noneInLatest === true, folder, attempts, recent }, assessment, policy, choice)
- const reply = await scoped({ action: 'routeJev', conversationId: input.conversationId, ...question })
- if (typeof reply.error === 'string' && !TRANSPORT.has(reply.error)) return reply
- const jev = object(reply.value)
- if (reply.ok !== true || typeof jev.unavailable === 'string') unavailable = typeof jev.unavailable === 'string' ? jev.unavailable : 'UNAVAILABLE'
- else answer = object(jev.answers).who as JevChoiceAnswer | undefined
- }
- const verdict = decide(choice, answer, unavailable)
+ const verdict = decide(choice)
const operationId = `route-${newId()}`
const record = (v1: boolean) => scoped({ action: 'command', operationId,
- command: { type: 'route.record', conversationId: input.conversationId, decision: recordOf(choice, verdict, assessment, policy, question && { chars: contextSize(question), missing }, v1) } })
+ command: { type: 'route.record', conversationId: input.conversationId, decision: recordOf(choice, verdict, assessment, policy, v1) } })
let recorded = await record(false)
// A backend from before phase 1 refuses the new fields as invalid; the decision is still worth keeping in the shape it knows.
if (recorded.error === 'VALIDATION_ERROR') recorded = await record(true)
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 2ac620d3d..2c1e89228 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -4,14 +4,9 @@ import { fakeCore } from '../testing/fakeCore.js'
import type { CoreApi } from '../core/api.js'
import { superTabService } from './service.js'
import { SuperTabHostError, type SuperTabHost } from './host.js'
-import { createJevDecide, type JevDecide } from '../lib/jev/jevClient.js'
-
-// The real client would read the developer's OpenRouter key; the account backend is the only part under test.
-vi.mock('../lib/jev/jevClient.js', async importOriginal => ({ ...await importOriginal<typeof import('../lib/jev/jevClient.js')>(), createJevDecide: vi.fn() }))
-const createJev = vi.mocked(createJevDecide)
const owner = { local: true, owner: true }, visitor = { local: false, owner: false }
-function setup(options: { jev?: () => JevDecide; prepareContribution?: typeof import('./contribution.js').prepareContribution } = {}) {
+function setup(options: { prepareContribution?: typeof import('./contribution.js').prepareContribution } = {}) {
const agentId = createHash('sha256').update(JSON.stringify(['machine-1', 'native'])).digest('hex').slice(0, 24)
const agent = { id: agentId, machineId: 'machine-1', harnessId: 'native' }
const call = vi.fn<CoreApi['account']['backend']>(async () => ({ status: 200, body: { success: true, data: { state: { agents: [agent] } } } }))
@@ -259,7 +254,7 @@ it('returns the routing context to a verified contribution', async () => {
machines: [{ machineId: 'm1', name: 'remote-1', status: 'online' }, { machineId: 'm2', name: 'shared', status: 'online' }] } })
expect(t.call).toHaveBeenCalledWith('GET', `/api/super-tabs/tab/routing-policy?asAgentId=${t.agentId}`, undefined)
})
-describe('routeHistory for Jev', () => {
+describe('routeHistory', () => {
const contextOf = (t: ReturnType<typeof setup>, read: (path: string) => Promise<unknown>, lead?: string) => {
const state = { agents: [{ ...t.agent, name: 'Boss' }, { id: 'a2', name: 'Multiply' }, { id: 'a3', name: 'Reader' }], conversations: [{ id: 'g1', leadId: lead ?? t.agentId }] }
vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => {
@@ -270,38 +265,16 @@ describe('routeHistory for Jev', () => {
return t.ask({ action: 'routeHistory', tabId: 'tab', harnessId: 'native', conversationId: 'g1' }, owner) as Promise<{ value: Record<string, unknown> }>
}
const ok = (data: unknown) => ({ status: 200, body: { success: true, data } })
- it('gives the last ten group messages with a role instead of an author, and never an agent transcript or a routing note', async () => {
+ it('reads only the route log and the attempts, never the group\'s messages, which only Jev read', async () => {
const t = setup()
- const person = (text: string) => ({ author: { kind: 'person', id: 'u1', name: '[email protected]' }, text })
- const rows = [
- ...Array.from({ length: 8 }, (_, i) => person(`early ${i}`)),
- { author: { kind: 'agent', id: t.agentId, name: 'Boss' }, text: 'Lead says' },
- { author: { kind: 'agent', id: 'a2', name: 'Multiply' }, text: 'Worker says', source: null },
- { author: { kind: 'agent', id: 'a2', name: 'Multiply' }, text: 'TRANSCRIPT', source: { kind: 'native', phase: 'answer' } },
- { author: { kind: 'agent', id: t.agentId, name: 'Boss' }, text: 'Routed to X', source: { kind: 'route', decisionId: 'd' } },
- { author: { kind: 'agent', id: 'gone', name: 'Gone' }, text: 'x'.repeat(1500) },
- { author: { kind: 'agent', id: 'a3', name: 'Reader' }, text: 'last' },
- ]
- const { value } = await contextOf(t, async path => path.includes('/messages') ? ok({ messages: rows }) : ok([]))
- const messages = value.messages as Array<{ from: string; text: string }>
- expect(messages.map(m => m.from)).toEqual([...Array(6).fill('person'), 'Lead', 'Multiply', 'agent', 'Reader'])
- expect(messages[0].text).toBe('early 2')
- expect(messages[8].text).toBe('x'.repeat(1000))
- expect(JSON.stringify(value.messages)).not.toMatch(/@|TRANSCRIPT|Routed to/)
- expect(value).not.toHaveProperty('messagesUnreadable')
- expect(vi.mocked(t.core.account.backend)).toHaveBeenCalledWith('GET', `/api/super-tabs/tab/conversations/g1/messages?asAgentId=${t.agentId}`, undefined)
- })
- it('says the latest page held only log rows, instead of saying nothing was said', async () => {
- const only = [{ author: { kind: 'agent', id: 'a2', name: 'Multiply' }, text: 'T', source: { kind: 'native' } }]
- const { value } = await contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: only }) : ok([]))
- expect(value).toMatchObject({ messages: [], noneInLatest: true })
- const empty = await contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: [] }) : ok([]))
- expect(empty.value).toEqual({ messages: [], decisions: [], attempts: [] })
+ const { value } = await contextOf(t, async () => ok([]))
+ expect(value).toEqual({ decisions: [], attempts: [] })
+ expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('GET', expect.stringContaining('/messages'), undefined)
})
it('is for the Lead of the group only, like the route', async () => {
const t = setup()
expect(await contextOf(t, async () => ok([]), 'someone-else')).toMatchObject({ error: 'LEAD_REQUIRED', status: 403 })
- expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('GET', expect.stringContaining('/messages'), undefined)
+ expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('GET', expect.stringContaining('/route-decisions'), undefined)
})
it('gives the latest routing decisions in brief, newest first, without their records', async () => {
const t = setup()
@@ -334,7 +307,7 @@ describe('routeHistory for Jev', () => {
expect(person).toMatchObject({ title: 'Pick', account: 'k0', spend: { '5-hour': 30, weekly: 4 } })
expect(lead).not.toHaveProperty('account')
})
- it('gives every attempt of the group, newest first, with only what Jev needs and no more than fifty', async () => {
+ it('gives every attempt of the group, newest first, with only what the route needs and no more than fifty', async () => {
const t = setup()
const row = (i: number) => ({ id: `as${i}`, agentId: i % 2 ? 'a2' : 'gone', status: 'stopped', result: i === 0 ? 'Tests failed.' : i === 2 ? 'y'.repeat(900) : null, createdAt: '2026-10-19T10:00:00Z',
conversationId: 'g1', execution: { harnessId: 'secret' } })
@@ -351,30 +324,27 @@ describe('routeHistory for Jev', () => {
it('marks the attempts unreadable when an older backend answers 404 or the read fails or hangs', async () => {
const without = (path: string) => path.includes('/messages') ? ok({ messages: [] }) : ok([])
const old = await contextOf(setup(), async path => path.includes('/attempts') ? { status: 404, body: { success: false, error: { code: 'NOT_FOUND' } } } : without(path))
- expect(old.value).toMatchObject({ messages: [], decisions: [], attemptsUnreadable: true })
+ expect(old.value).toMatchObject({ decisions: [], attemptsUnreadable: true })
expect(old.value).not.toHaveProperty('attempts')
const failed = await contextOf(setup(), async path => path.includes('/attempts') ? Promise.reject(new Error('down')) : without(path))
- expect(failed.value).toMatchObject({ attemptsUnreadable: true, messages: [] })
+ expect(failed.value).toMatchObject({ attemptsUnreadable: true, decisions: [] })
const odd = await contextOf(setup(), async path => path.includes('/attempts') ? ok({ attempts: 'no' }) : without(path))
expect(odd.value).toMatchObject({ attemptsUnreadable: true })
vi.useFakeTimers()
try {
const slow = contextOf(setup(), async path => path.includes('/attempts') ? new Promise(() => {}) : without(path))
await vi.advanceTimersByTimeAsync(3000)
- expect((await slow).value).toMatchObject({ messages: [], decisions: [], attemptsUnreadable: true })
+ expect((await slow).value).toMatchObject({ decisions: [], attemptsUnreadable: true })
} finally { vi.useRealTimers() }
})
- it('marks each source it could not read on its own, and never waits longer than three seconds for one', async () => {
- const failed = await contextOf(setup(), async path => path.includes('/messages') ? Promise.reject(new Error('down')) : ok([]))
- expect(failed.value).toMatchObject({ messagesUnreadable: true, decisions: [] })
- expect(failed.value).not.toHaveProperty('decisionsUnreadable')
- const odd = await contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: 'no' }) : { status: 503, body: { error: 'SERVICE_UNAVAILABLE' } })
- expect(odd.value).toMatchObject({ messagesUnreadable: true, decisionsUnreadable: true })
+ it('marks the route log unreadable on its own, and never waits longer than three seconds for it', async () => {
+ const odd = await contextOf(setup(), async path => path.includes('/attempts') ? ok([]) : { status: 503, body: { error: 'SERVICE_UNAVAILABLE' } })
+ expect(odd.value).toEqual({ decisionsUnreadable: true, attempts: [] })
vi.useFakeTimers()
try {
- const slow = contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: [] }) : new Promise(() => {}))
+ const slow = contextOf(setup(), async path => path.includes('/attempts') ? ok([]) : new Promise(() => {}))
await vi.advanceTimersByTimeAsync(3000)
- expect((await slow).value).toMatchObject({ messages: [], decisionsUnreadable: true })
+ expect((await slow).value).toEqual({ decisionsUnreadable: true, attempts: [] })
} finally { vi.useRealTimers() }
})
})
@@ -390,59 +360,10 @@ it('says the machine list could not be read, instead of offering none', async ()
t.core.account.machines = vi.fn(async () => ({ status: 200, body: { data: { machines: [{ machineId: 'm1', name: 'remote-1', status: 'online' }] } } }))
expect((await t.ask({ action: 'routeContext', tabId: 'tab', harnessId: 'native' }, owner) as { value: object }).value).not.toHaveProperty('machinesUnreadable')
})
-const routing = (t: ReturnType<typeof setup>, decisions: unknown[] = [], leadId?: string) => vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => path.includes('/route-decisions')
- ? { status: 200, body: { success: true, data: decisions } }
- : { status: 200, body: { success: true, data: { state: { agents: [t.agent], conversations: [{ id: 'g1', leadId: leadId ?? t.agentId }] } } } })
-it('asks Jev with a three-second limit and reports unavailability instead of failing', async () => {
- const answer = { who: { choice: 'c1', probabilities: { c0: 0.2, c1: 0.8 } } }
- const decide = vi.fn<JevDecide>(async () => answer)
- const t = setup({ jev: () => decide }); routing(t)
- expect(await t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: { task: 't' }, questions: { who: {} } }, owner))
- .toEqual({ ok: true, value: { answers: answer } })
- expect(decide.mock.calls[0][2]).toBeInstanceOf(AbortSignal)
- const ask = (extra: object = {}) => t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: {}, questions: {}, ...extra }, owner)
- decide.mockRejectedValueOnce(Object.assign(new Error('busy'), { code: 'BUSY' }))
- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'BUSY' } })
- decide.mockRejectedValueOnce(new DOMException('The operation timed out.', 'TimeoutError'))
- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'TIMEOUT' } })
- decide.mockRejectedValueOnce(new DOMException('Aborted', 'AbortError'))
- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'TIMEOUT' } })
- decide.mockRejectedValueOnce(new Error('boom'))
- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'UNAVAILABLE' } })
- decide.mockRejectedValueOnce('odd')
- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'UNAVAILABLE' } })
-})
-it('builds Jev from the account backend when no override is given', async () => {
+it('no longer asks Jev: the daemon has no routeJev action', async () => {
const t = setup()
- const hosted = { who: { choice: 'c0', probabilities: { c0: 1 } } }
- vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => path === '/api/route/jev'
- ? { status: 200, body: { data: { answers: hosted } } }
- : path.includes('/route-decisions') ? { status: 200, body: { success: true, data: [] } }
- : { status: 200, body: { success: true, data: { state: { agents: [t.agent], conversations: [{ id: 'g1', leadId: t.agentId }] } } } })
- createJev.mockImplementationOnce(options => (async () => {
- const reply = await options!.backend!('POST', '/api/route/jev', {})
- return (reply.body.data as { answers: Record<string, never> }).answers
- }) as JevDecide)
- const service = superTabService(t.core, { host: () => ({ machineId: 'machine-1', start: vi.fn(), stop: vi.fn() }) as unknown as SuperTabHost })
- expect(await service.requests.super_tabs({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: {}, questions: {} }, owner))
- .toEqual({ ok: true, value: { answers: hosted } })
-})
-it('refuses routing to anyone but the group Lead, and past 30 decisions in the rolling hour, before asking Jev', async () => {
- const decide = vi.fn<JevDecide>(async () => ({}))
- const t = setup({ jev: () => decide })
- const ask = (conversationId: string) => t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId, state: {}, questions: {} }, owner)
- routing(t, [], 'someone-else')
- expect(await ask('g1')).toMatchObject({ error: 'LEAD_REQUIRED', status: 403 })
- routing(t)
- expect(await ask('missing')).toMatchObject({ error: 'LEAD_REQUIRED' })
- const recent = (n: number, age = 1000) => Array.from({ length: n }, () => ({ createdAt: new Date(Date.now() - age).toISOString() }))
- routing(t, recent(30))
- expect(await ask('g1')).toMatchObject({ error: 'RATE_LIMITED', status: 429 })
- routing(t, [...recent(29), ...recent(50, 61 * 60_000)])
- expect(await ask('g1')).toMatchObject({ ok: true })
- routing(t, { not: 'a list' } as never)
- expect(await ask('g1')).toMatchObject({ ok: true })
- expect(decide).toHaveBeenCalledTimes(2)
+ expect(await t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: {}, questions: {} }, owner)).not.toMatchObject({ ok: true })
+ expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('POST', '/api/route/jev', expect.anything())
})
it('prepares machines only for their owner and clears setup receipts on disconnect', async () => {
@@ -534,6 +455,19 @@ it('teaches agents to say when their work needs a person or is stuck', async ()
expect(help.help.command).toContain('needs_human')
})
+it('says a server from before rules does not support them, and passes a malformed rule\'s refusal through', async () => {
+ const t = setup()
+ const refuse = (message: string) => t.call.mockImplementation(async (...args: unknown[]) => args[0] === 'POST'
+ ? { status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message } } } as never
+ : { status: 200, body: { success: true, data: { state: { agents: [t.agent] } } } })
+ const send = (command: object) => t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'rule', command }, owner)
+ refuse("command.type: Invalid discriminator value. Expected 'machine.contribute'")
+ expect(await send({ type: 'rule.set', rule: { kind: 'preferIdle' }, text: 'Idle first.' })).toEqual({ error: 'RULES_UNSUPPORTED', detail: 'This Swarm\'s server does not support rules yet.' })
+ expect(await send({ type: 'rule.remove', ruleId: 'r' })).toMatchObject({ error: 'RULES_UNSUPPORTED' })
+ refuse('command.rule.effort: Invalid option')
+ expect(await send({ type: 'rule.set', rule: { kind: 'minEffort', effort: 'huge' }, text: 'x' })).not.toMatchObject({ error: 'RULES_UNSUPPORTED' })
+})
+
it('documents finished worker decisions and explains an older backend without release support', async () => {
const t = setup()
const help = (await t.ask({ action: 'help' }, owner)).help as { commands: unknown[]; release: string }
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 33a76b3ba..3e9065a75 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -4,7 +4,6 @@ import { createHash } from 'node:crypto'
import type { CoreApi, ServiceRequests, SuperTabsPort } from '../core/api.js'
import { backend, swarmRoleFor, hostJournalFile, identifier, object, SuperTabHost, SuperTabHostError } from './host.js'
import { within } from './wire.js'
-import { createJevDecide, type JevDecide } from '../lib/jev/jevClient.js'
import { machineChoices } from '../lib/newCommand.js'
import { START_REQUIREMENTS } from './capacity.js'
import { CapacityReservations, type ReservationBook } from './reservations.js'
@@ -13,18 +12,18 @@ import { messageIdOf } from './attach.js'
import { cardId, SwarmCards } from './cards.js'
const HELP = {
- status: 'Read the shared tab roster and work.',
+ status: 'Read the shared tab roster and work. Its rules are the owner\'s routing rules, each in the owner\'s own words.',
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 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. Set role "reviewer" to start a Reviewer; leave role out for a Builder. The role is kept for the session. A Reviewer runs on claude or codex and is assigned only review groups (conversation.create with reviewOf naming the group it reviews); a review group is assigned only to a Reviewer. Add the Reviewer to the reviewed group with conversation.agent so it is told when that work is ready for review and can pass its independent check. Start one with a routeDecisionId like any agent.',
release: 'When a Builder 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 you start an agent or assign work to another agent, choose who does it. Work you do yourself is not routed. 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.',
+ route: 'route GROUP JSON: before you start an agent or assign work to another agent, choose who does it. Work you do yourself is not routed. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","kind":"optional word such as ui or docs","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. Candidates that break the owner\'s hard rules are left out; soft rules (a preferred engine for the kind, idle agents first) rank the rest. 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' },
- command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves.',
+ command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves. rule.set and rule.remove change the owner\'s routing rules: only the owner does, or the Lead passing on the owner\'s request, with askedIn naming the owner\'s message. A start, assignment or route that breaks a hard rule (forbidModel, machines, minEffort) is refused for agents; preferEngine and preferIdle only rank.',
commands: [
{ type: 'project.report', projectId: 'PROJECT', throughRevision: 123, text: 'What changed, what is blocked, and what comes next. Use null when nothing merits repeating.' },
{ type: 'project.repository', projectId: 'PROJECT', repositoryUrl: 'https://github.com/OWNER/REPOSITORY' },
@@ -35,6 +34,12 @@ const HELP = {
{ type: 'work.define', conversationId: 'GROUP', task: { goal: 'What to deliver', changes: 'What changes', constraints: 'What must stay true', owns: ['Paths or code areas'] }, checks: [{ description: 'Observable acceptance evidence', independent: false }] },
{ type: 'work.cancel', conversationId: 'GROUP', assignmentId: 'ATTEMPT', reason: 'Lead or tab owner only: why the task is cancelled, in one short sentence' },
{ type: 'agent.release', agentId: 'AGENT', decision: 'keep|stop' },
+ { type: 'rule.set', rule: { kind: 'forbidModel', model: 'haiku' }, text: 'The owner\'s words: No Haiku.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
+ { type: 'rule.set', rule: { kind: 'minEffort', effort: 'high' }, text: 'At least high effort.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
+ { type: 'rule.set', rule: { kind: 'machines', machineIds: ['MACHINE'] }, text: 'Only these machines.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
+ { type: 'rule.set', rule: { kind: 'preferEngine', taskKind: 'ui', engine: 'codex' }, text: 'Codex for UI work.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
+ { type: 'rule.set', rule: { kind: 'preferIdle' }, text: 'Reuse idle agents first.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
+ { type: 'rule.remove', ruleId: 'RULE', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
{ type: 'work.assign', conversationId: 'GROUP', agentId: 'AGENT', routeDecisionId: 'DECISION' },
{ type: 'work.status', conversationId: 'GROUP', assignmentId: 'ATTEMPT', status: 'working', result: null },
// Both reach the Lead and alert the Harness Pro on the machine running the agent until the status moves on.
@@ -84,8 +89,6 @@ export interface SuperTabServiceOptions {
capacity?: typeof readCapabilities
host?: (core: CoreApi, machineId: string) => SuperTabHost
reservations?: (core: CoreApi, machineId: string) => ReservationBook
- /** Jev for `route`; Harness's hosted key through the backend when the person has no key of their own. */
- jev?: (core: CoreApi) => JevDecide
/** The Swarm cards' reader (superTabs/cards.ts), for a spec. */
cards?: (core: CoreApi, machineId: string) => SwarmCards
}
@@ -201,27 +204,17 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
machines: readable ? machineChoices(object(object(machines.body).data), null).filter(m => !m.toAdd).map(m => ({ machineId: m.machineId, name: m.label, status: m.status })) : [],
...(readable ? {} : { machinesUnreadable: true }) } }
}
- // What Jev reads besides the candidates. Apart from `routeContext` so the Lead reads it while it probes the
- // machines; the group's Lead only, like the route itself.
+ // The route log and the group's attempts, for the quota open picks hold and what members did before. Apart from
+ // `routeContext` so the Lead reads it while it probes the machines; the group's Lead only, like the route itself.
if (payload.action === 'routeHistory') {
const group = list(state.conversations).find(c => c.id === payload.conversationId)
if (!group || group.leadId !== agentId) return { error: 'LEAD_REQUIRED', detail: 'The coordinating Lead of this group owns routing.', status: 403 }
- const [written, logged, tried] = await Promise.all([
- within(backend(core, 'GET', `${path}/conversations/${payload.conversationId}/messages?${identity}`)),
+ const [logged, tried] = await Promise.all([
within(backend(core, 'GET', `${path}/route-decisions?${identity}`)),
// An older backend has no such route: its 404 is unreadable like any other failure.
within(backend(core, 'GET', `${path}/conversations/${payload.conversationId}/attempts?${identity}`)),
])
- // Jev reads the group's talk as roles: an email is a person's name here, so it never leaves this step.
- // Native rows are an agent's own transcript and route rows are the log's, so only the talk is kept.
- const rows = Array.isArray(object(written).messages) ? list(object(written).messages) : null
- const messages = rows?.filter(m => !m.source).slice(-10).map(m => {
- const by = object(m.author)
- return { from: by.kind === 'person' ? 'person' : by.id === group.leadId ? 'Lead' : String(list(state.agents).find(a => a.id === by.id)?.name ?? 'agent'),
- text: String(m.text ?? '').slice(0, 1000) }
- })
- // The log's records carry every candidate's line; Jev needs only who was picked and how it went. The route also
- // needs the account and expected spend of what actually runs, which an open pick still holds: after an override
+ // The log's records carry every candidate's line; the route needs only who was picked and how it went, and the account and expected spend of what actually runs, which an open pick still holds: after an override
// that is the person's chosen candidate, and a Lead's own choice outside the list has no known account.
const decisions = Array.isArray(logged) ? logged.slice(0, 50).map(object).map(d => {
const record = object(d.record), final = object(d.final), candidates = list(record.candidates), pick = candidates.find(c => c.id === record.pick)
@@ -233,28 +226,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
}) : null
// Every attempt the group had, also the ones `work.define` took out of the state; the server already cut the results.
const attempts = Array.isArray(tried) ? tried.slice(0, 50).map(object).map(a => ({ id: a.id, agentId: a.agentId, status: a.status, result: typeof a.result === 'string' ? a.result.slice(0, 500) : null, createdAt: a.createdAt ?? null })) : null
- return { ok: true, value: { ...(messages ? { messages, ...(rows!.length && !messages.length ? { noneInLatest: true } : {}) } : { messagesUnreadable: true }),
- ...(decisions ? { decisions } : { decisionsUnreadable: true }), ...(attempts ? { attempts } : { attemptsUnreadable: true }) } }
- }
- if (payload.action === 'routeJev') {
- // Jev costs money and the decision is the Lead's, so both rules are checked before it is asked.
- const group = Array.isArray(state.conversations) ? state.conversations.map(object).find(c => c.id === payload.conversationId) : undefined
- if (!group || group.leadId !== agentId) return { error: 'LEAD_REQUIRED', detail: 'The coordinating Lead of this group owns routing.', status: 403 }
- const decisions = await backend(core, 'GET', `${path}/route-decisions?${identity}`)
- const hourAgo = Date.now() - 60 * 60_000
- if ((Array.isArray(decisions) ? decisions : []).filter(d => Date.parse(String(object(d).createdAt)) >= hourAgo).length >= 30) {
- return { error: 'RATE_LIMITED', detail: 'This Super Tab routed 30 tasks in the last hour. Wait before routing again.', status: 429 }
- }
- const decide = (options.jev ?? (api => createJevDecide({ backend: (m, p, b) => api.account.backend(m, p, b) })))(core)
- try {
- // Routing never waits on Jev beyond three seconds; the policy order decides instead.
- return { ok: true, value: { answers: await decide(payload.state, object(payload.questions) as never, AbortSignal.timeout(3000)) } }
- } catch (error) {
- // A timeout is a DOMException whose `code` is a number; Jev's own refusals carry a string code.
- const name = error instanceof Error ? error.name : ''
- const code = error && typeof error === 'object' && 'code' in error && typeof error.code === 'string' ? error.code : null
- return { ok: true, value: { unavailable: name === 'TimeoutError' || name === 'AbortError' ? 'TIMEOUT' : code ?? 'UNAVAILABLE' } }
- }
+ return { ok: true, value: { ...(decisions ? { decisions } : { decisionsUnreadable: true }), ...(attempts ? { attempts } : { attemptsUnreadable: true }) } }
}
if (payload.action === 'messages' && identifier(payload.conversationId)) {
const page = await backend(core, 'GET', `${path}/conversations/${payload.conversationId}/messages?${identity}`)
@@ -281,6 +253,10 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
if (command.type === 'agent.release' && error instanceof SuperTabHostError && error.status === 400 && ['VALIDATION_ERROR', 'INVALID_REQUEST'].includes(error.code)) {
return { error: 'RELEASE_UNSUPPORTED', detail: 'This backend does not support releasing Builders yet. Update the backend and try again.' }
}
+ // A backend from before rules does not know the command type at all; a malformed rule is the Lead's to fix.
+ if (['rule.set', 'rule.remove'].includes(String(command.type)) && error instanceof SuperTabHostError && error.status === 400 && /discriminator/i.test(error.message)) {
+ return { error: 'RULES_UNSUPPORTED', detail: 'This Swarm\'s server does not support rules yet.' }
+ }
if (!['conversation.create', 'work.define'].includes(String(command.type)) || !command.task || !(error instanceof SuperTabHostError)) throw error
const oldSchema = error.status === 400 && error.code === 'VALIDATION_ERROR'
&& /^(?:command: )?Unrecognized (?:key: "task"|key\(s\) in object: 'task')$/.test(error.message)
diff --git a/docs/plans/2026-10-22-swarm-rules-routing.md b/docs/plans/2026-10-22-swarm-rules-routing.md
new file mode 100644
index 000000000..2847cec64
--- /dev/null
+++ b/docs/plans/2026-10-22-swarm-rules-routing.md
@@ -0,0 +1,224 @@
+# Swarm rules replace Jev in routing
+
+Date: 2026-10-22. Status: approved by the Lead on 2026-10-22 and implemented.
+
+## Why
+
+On 2026-10-22 the Lead overrode Jev's pick about half the time: Haiku, a stopping agent on an offline
+machine, low effort. Jev does not know the owner's rules, so asking it is a step the Lead then undoes.
+The rules also lived only in the Lead's head. They move into the Swarm. The system enforces the hard
+ones and ranks candidates by the soft ones, and routing stops asking a hosted model.
+
+## Rules
+
+A rule is stored in the Swarm's state (`SuperTabState.rules`, at most 50 rules):
+
+```ts
+interface Rule {
+ id: string // the operation id of the command that added it
+ rule:
+ | { kind: 'forbidModel'; engine?: 'claude' | 'codex'; model: string } // hard
+ | { kind: 'machines'; machineIds: string[] } // hard
+ | { kind: 'minEffort'; engine?: 'claude' | 'codex'; effort: Effort } // hard
+ | { kind: 'preferEngine'; taskKind: string | null; engine: 'claude' | 'codex' } // soft
+ | { kind: 'preferIdle' } // soft
+ text: string // the owner's words, 1–200 characters, e.g. "No Haiku, ever."
+ askedBy: string // the owner's user id
+ askedIn: { conversationId: string; messageId: string } | null // the owner's message, when a Lead relays it
+ addedBy: string // actorKey of whoever sent the command (owner or Lead)
+ createdAt: string
+}
+type Effort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+```
+
+The meaning of each rule:
+
+- **forbidModel** (hard): no agent may run a model whose id contains `model`, compared case-insensitively.
+ This catches the short name and the full id (`haiku` matches `haiku` and `claude-haiku-4-5`). A rule
+ naming a full id also matches a start that asks for that family's alias (`claude-haiku-4-5` matches
+ `haiku`). A model of `default` matches nothing, because the actual model is not known.
+- **machines** (hard): agents run only on the listed machines. There is at most one such rule; adding
+ another replaces it.
+- **minEffort** (hard): the effort is at least `effort`, in the order
+ minimal < low < medium < high < xhigh < max. An unknown effort (`default`, `auto`) does not meet it.
+ A member's `auto` is first resolved from its start record, as `withLaunchEffort` does today. A
+ new-agent candidate whose policy row says `default` or `auto` is not dropped: it is lifted to the
+ minimum, and the start it suggests names that effort.
+- **preferEngine** (soft): for tasks of `taskKind`, or for every task when it is null, candidates on
+ `engine` rank first. A task's kind is a new optional `kind` word in the route JSON
+ (`"kind":"ui"`). A review group's kind is always `review`.
+- **preferIdle** (soft): an idle member ranks before a new agent. Among new agents, a machine with fewer
+ running agents ranks first.
+
+Routing already removes an offline machine, a stopping agent (it is busy or refused) and an exhausted
+quota. Those stay as they are and are not rules.
+
+## Who changes rules
+
+Two new commands go through the existing `command` path:
+
+```json
+{"type":"rule.set","rule":{"kind":"forbidModel","model":"haiku"},"text":"No Haiku.","askedIn":{"conversationId":"…","messageId":"…"}}
+{"type":"rule.remove","ruleId":"…","askedIn":{"conversationId":"…","messageId":"…"}}
+```
+
+- A person may change rules only if they are the Swarm owner, and they omit `askedIn`.
+- An agent may change rules only if it is the tab's Lead (the `controls(state, actor)` check that
+ `tab.rename` uses), and it must pass `askedIn`. The backend reads that message, the way it reads
+ `replyTo` for `message.send`. The message must meet three conditions:
+ - its author is the owner, as a person;
+ - it is a plain chat message: no system row, such as the owner's own "Rule added" row or a warning;
+ - it is at most a day old.
+
+ Otherwise the change is refused with "Only the Swarm owner sets rules; quote a chat message the owner
+ wrote in the last day asking for this change." This was added in the review of #1586. One owner
+ message may ask for several rules, so the Lead may quote it for each of them.
+- Everyone else is refused with `OWNER_REQUIRED`: "Only the Swarm owner, or the Lead passing on the
+ owner's request, changes rules."
+- Each change posts one row in the lead group ("Rule added: No Haiku."), so the change can be seen
+ without any UI. The row has no email in it; who asked is kept on the rule.
+- **Listing:** the rules are part of the tab state that `status` already returns, with each rule's
+ `text`. When asked, the Lead lists them in the owner's own words. No new command is added.
+
+## Backend enforcement (hard rules)
+
+The check is one pure function, `broken(rules, { machineId, engine, model, effort })`, in
+`backend/src/superTabs/rules.ts`. It returns the sentence for the first broken rule, or null. The CLI
+has the same check (`breaks` in `route.ts`), so a pick it offers is never refused later. It is called by:
+
+- **agent.start**, with the request's machine, engine, model and effort;
+- **work.assign**, with the worker's machine and configuration (effort resolved from its start record
+ when it reports `auto`);
+- **conversation.agent** when an agent joins or leads a group (leaving is never checked);
+- **agent.startDispatch**, so a start recorded before a rule was added is not launched past it. An agent's
+ dispatch is refused, and the start stays unlaunched;
+- **route.record**, with the pick (a new-agent candidate's fields, or the member's current
+ configuration). Other candidates in the record are not checked, so an older CLI that lists a
+ forbidden candidate can still record a decision when its pick is allowed.
+
+An **agent** that breaks a rule is refused with `RULE_BROKEN` and one plain sentence, for example:
+`The owner's rule "No Haiku." rules out Claude haiku. Route again.` An `overrideReason` does not get
+past a hard rule.
+
+A **person** is not blocked. The command goes through, its result carries `warnings`, and the group gets
+one row (a rule row, with a name rather than an email): `ken started Builder anyway. The owner's rule
+"No Haiku." rules out Claude haiku.` A person's `route.override` to a candidate that breaks a rule works
+the same way.
+
+The person's choice carries through. When the Lead then starts or assigns exactly the candidate the person
+chose, it is let through with the same warning; anything else the Lead does is still refused. The same
+applies to dispatching such a start.
+
+Agents that were already running when a rule was added keep running. Routing just stops offering them,
+and new assignments to them are refused.
+
+Soft rules are not enforced by the backend.
+
+## CLI routing (`cli/src/superTabs/route.ts`, `routeCommand.ts`, `service.ts`)
+
+`choose()` goes through these steps:
+
+1. **Refusals** (unchanged).
+2. **Hard rules**: a candidate that breaks a rule moves to `excluded` with the reason
+ `Breaks the owner's rule: …`. If nobody is left, the result is `NO_CANDIDATE`, and the excluded
+ list says why.
+3. **Quality floor, strength for hard tasks, quota fit groups** (unchanged).
+4. **Fixed order**: preferred engine for the kind (soft), then idle member before new agent (soft), then
+ today's order (effective cost, quality, room on the tightest window, member in the same repository,
+ title).
+
+`decide()` keeps the first candidate. The verdict is `only` when there is one candidate and `order`
+otherwise, with no `fallback`.
+
+Removed:
+
+- `routeJev` (the daemon action) and the `jev` option in `service.ts`;
+- the group-messages read in `routeHistory`, which only Jev used;
+- `jevQuestion`, `contextSize`, `INSTRUCTIONS`, `folderText`, `JevInput`, the `jevPick` import and the
+ record's `context` field;
+- `scrub`, which existed so that nothing identifying reached the hosted model. Labels now go only to
+ the Swarm's own log, which its members can already read.
+
+Kept:
+
+- the decision log (`route.record`), and labels and fit in it;
+- the commitments read from the log;
+- the rule from #1555 that an agent's start or assign needs a routeDecisionId;
+- the 30-per-hour limit;
+- `jevClient`, `jevPick` and the backend `jevRoute`, which the voice router, recaps and devices
+ still use.
+
+The route reads its rules from the tab state that `routeContext` already returns. No new daemon action
+or backend read is needed.
+
+CLI help (`HELP` in `service.ts`):
+
+- `route` gains the optional `kind` and the sentence "Candidates that break the owner's hard rules
+ are left out; soft rules rank."
+- `command` gains `rule.set` and `rule.remove`, including that `askedIn` is the owner's message.
+- `status` notes that `rules` lists them.
+
+## Mixing versions
+
+| | Old backend (no rules) | New backend |
+|---|---|---|
+| **Old CLI** | today | It still asks Jev. The record is refused only when the pick breaks a hard rule, with a sentence asking the Lead to update or route again. Start and assign are enforced. |
+| **New CLI** | No rules in the state, so routing is today's minus Jev. `rule.set` and `rule.remove` are refused by the strict schema, and the CLI reports "This Swarm's server does not support rules yet." | full |
+
+The record keeps today's schema. `via: 'jev'` stays valid in it for old CLIs, and nothing new is added to
+it, so the CLI's existing v1 retry is unchanged. A new CLI with a daemon that has not restarted still
+works, because it no longer calls `routeJev`.
+
+With no rules, the result is today's order, minus Jev's three-second call and minus the overrides Jev
+caused.
+
+## Tests
+
+The tests are unit tests only. They never touch port 18473, `~/.harness`, `~/.claude`, `~/.codex` or
+real tmux.
+
+- `backend/src/superTabs/commands.test.ts`:
+ - set, list and remove by the owner;
+ - set and remove by the Lead with an owner message;
+ - refused for the Lead without one, for the Lead quoting a non-owner message, for a collaborator, and
+ for a non-Lead agent;
+ - `agent.start`, `work.assign` and `route.record` refused for an agent that breaks each hard rule
+ kind;
+ - a person passes with a warning row;
+ - `overrideReason` does not bypass a rule;
+ - with no rules, today's behaviour (the existing suite is unchanged).
+- `backend/integration/superTabs.test.ts`: on a real database, the Lead records a rule only by quoting a
+ message the owner wrote in the tab.
+- `route.spec.ts`:
+ - each hard rule moves candidates to excluded;
+ - a lifted effort for a `default` row under minEffort;
+ - each soft rule changes only the order, never the set;
+ - with no rules, the same order as today.
+- `routeCommand.spec.ts` and `service.spec.ts`:
+ - no Jev call is made (the injected `request` never sees `routeJev`, and service options have no
+ `jev`);
+ - the rules come from the tab state;
+ - a hard rule leaves only allowed picks.
+
+Commands, recorded in the PR:
+
+- `cd backend && npm run typecheck && npx vitest run src/superTabs src/routes/superTabs && npm run test:super-tabs`
+- `cd cli && npm run typecheck && npx vitest run src/superTabs src/lib/routeDecide src/lib/jev src/architecture.spec.ts && npm run test:super-tabs`
+ (`test:super-tabs` holds `route.ts` and `routeCommand.ts` at 100%). No `src/core` or `src/services` file changes,
+ so `test:core` does not apply.
+
+## Lead skill wording (proposed, not applied)
+
+> Routing follows the owner's rules. When the owner states a lasting rule in chat ("never Haiku",
+> "only these machines", "at least high effort", "prefer Codex for UI", "reuse idle agents"),
+> record it with `rule.set` and quote the owner's message in `askedIn`. Remove it with `rule.remove`
+> when asked. When asked what the rules are, read `rules` in `status` and answer in the owner's
+> words. The backend refuses starts and assignments that break a hard rule, so route again
+> instead of overriding.
+
+## Open questions for the Lead
+
+1. **Lifting a `default`/`auto` effort to the minimum** instead of dropping the candidate. This keeps
+ Codex's `default` row usable under "at least high". Proposed: lift.
+2. **Recording `kind`.** It is not recorded in the decision log, which keeps the record schema
+ unchanged. Proposed: not recorded.