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.

Swarm routing: API-key engines are metered, route alternatives cover every machine (#1641)

0xken153d3bd7e91bfb
diff --git a/cli/src/superTabs/capacity.ts b/cli/src/superTabs/capacity.ts
index 65049ab1d..ee3c97848 100644
--- a/cli/src/superTabs/capacity.ts
+++ b/cli/src/superTabs/capacity.ts
@@ -86,6 +86,13 @@ export function quotaOf(reply: Json, engine: string, customAccount: boolean) {
}
return { known: windows.length > 0, account: typeof reading?.account === 'string' ? reading.account : null, windows }
}
+/** An engine that runs on an API key or a gateway's base URL has no subscription windows to read: it is metered, not unknown.
+ * `env` is the machine's own, so the host reads its own and a key never leaves it. */
+export function meteredEngine(engine: string, env: NodeJS.ProcessEnv): boolean {
+ const names = engine === 'claude' ? ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY']
+ : engine === 'codex' ? ['OPENAI_BASE_URL', 'OPENAI_API_KEY', 'CODEX_API_KEY'] : []
+ return names.some(name => !!env[name]?.trim())
+}
export function admission(capacity: Json, engine: Json, quota: ReturnType<typeof quotaOf>, requirements: Requirements, customAccount = false) {
const reasons: string[] = [], unknown: string[] = []
const resources = object(capacity.resources), tools = object(capacity.tools), devices = object(capacity.devices), toolProbeErrors = object(capacity.toolProbeErrors)
diff --git a/cli/src/superTabs/machines.spec.ts b/cli/src/superTabs/machines.spec.ts
index 605818b67..aaf8a23d7 100644
--- a/cli/src/superTabs/machines.spec.ts
+++ b/cli/src/superTabs/machines.spec.ts
@@ -4,7 +4,7 @@ import { ContributedMachines } from './machines.js'
import { SuperTabHostError } from './host.js'
import { startAgent } from './start.js'
-function fixture() {
+function fixture(env: NodeJS.ProcessEnv = {}) {
let now = 1000
const core = fakeCore({ dataDir: '/isolated-pool-fixture', agents: {
byAgent: vi.fn(id => id === 'running' ? { agentId: id } as never : undefined),
@@ -20,7 +20,7 @@ function fixture() {
const start = vi.fn(async () => ({ ok: true }))
const prepare = vi.fn(async () => {})
const log = vi.fn()
- const machine = new ContributedMachines(core, 'host', { backend, open, capabilities, start, prepare, log, now: () => now } as never)
+ const machine = new ContributedMachines(core, 'host', { backend, open, capabilities, start, prepare, log, env, now: () => now } as never)
return { machine, pool, core, backend, open, request, close, capabilities, start, prepare, log, advance: () => { now += 16000 }, step: (ms: number) => { now += ms } }
}
@@ -37,6 +37,25 @@ describe('contributed machine executor', () => {
expect(body).toMatchObject({ quotas: [{ engine: 'claude' }] })
expect(f.request).toHaveBeenCalledWith('engines_probe', { engines: ['claude', 'codex'] }, 20_000)
})
+ const signedOut = { providers: [{ provider: 'codex', account: null, outcome: 'signedOut' }] }
+ it('reports an engine run on an API key as metered: known, with no windows', async () => {
+ const f = fixture({ OPENAI_API_KEY: 'sk-or-private' })
+ f.request.mockImplementation(async () => signedOut)
+ await f.machine.tick()
+ const body = f.backend.mock.calls.find(c => c[1] === 'POST')![3]
+ expect(body).toMatchObject({ quotas: [{ engine: 'codex', known: true, windows: [] }] })
+ expect(JSON.stringify(body)).not.toContain('sk-or-private')
+ })
+ it('keeps an unreadable subscription unknown, and a readable one by its windows even beside an API key', async () => {
+ const unknown = fixture()
+ unknown.request.mockImplementation(async () => signedOut)
+ await unknown.machine.tick()
+ expect(unknown.backend.mock.calls.find(c => c[1] === 'POST')![3]).toMatchObject({ quotas: [{ engine: 'codex', known: false, windows: [] }] })
+ const read = fixture({ OPENAI_API_KEY: 'sk-or-private' })
+ await read.machine.tick()
+ const quota = (read.backend.mock.calls.find(c => c[1] === 'POST')![3] as { quotas: Array<{ windows: unknown[] }> }).quotas[0]!
+ expect(quota.windows).toHaveLength(1)
+ })
it('prepares a swarm project before dispatch and durably rejects an unsafe checkout', async () => {
const f = fixture()
Object.assign(f.pool.machine, { scope: 'swarm' })
diff --git a/cli/src/superTabs/machines.ts b/cli/src/superTabs/machines.ts
index 9e4da3762..2f6885f20 100644
--- a/cli/src/superTabs/machines.ts
+++ b/cli/src/superTabs/machines.ts
@@ -2,7 +2,7 @@ import type { CoreApi } from '../core/api.js'
import { openDaemon } from '../agentClient/daemon.js'
import { backend, SuperTabHostError } from './host.js'
import { identifier, object } from './wire.js'
-import { readCapabilities, quotaOf } from './capacity.js'
+import { readCapabilities, quotaOf, meteredEngine } from './capacity.js'
import { startAgent, type ScopedRequest } from './start.js'
import { prepareSwarmProject } from './projectFolder.js'
import { createSwarmCloneTrustRepair } from './cloneTrust.js'
@@ -43,7 +43,7 @@ export class ContributedMachines {
private readonly waiting = new Map<string, string>()
constructor(private readonly core: CoreApi, private readonly machineId: string,
private readonly deps: { backend: typeof backend; open: typeof openDaemon; capabilities: typeof readCapabilities;
- start: typeof startAgent; now: () => number; prepare?: typeof prepareSwarmProject; log?: (message: string) => void } =
+ start: typeof startAgent; now: () => number; prepare?: typeof prepareSwarmProject; log?: (message: string) => void; env?: NodeJS.ProcessEnv } =
{ backend, open: openDaemon, capabilities: readCapabilities, start: startAgent, now: Date.now }) {}
stop() { this.stopped = true }
/** DESKTOP-0TFH0OJ, 2026-10-23: every Claude start there was refused (CLI 0.4.57 took an API-key Claude for one not
@@ -133,7 +133,8 @@ export class ContributedMachines {
gpuPercent: gpus.length ? Math.max(...gpus) : null },
quotas: engines.map(engine => {
const q = quotaOf(readings, engine, false)
- return { engine, known: q.known, windows: q.windows }
+ // Windows that could not be read on an API key are metered: known, with none (route.ts quotaOf2).
+ return { engine, known: q.known || meteredEngine(engine, this.deps.env ?? process.env), windows: q.windows }
}), runningHarnessIds: running, stoppedHarnessIds: stopped,
...(Array.isArray(row.reservations) ? { stoppedReservations: list(row.reservations).filter(r => stopped.includes(String(r.harnessId))
&& identifier(r.harnessId) && identifier(r.generation)).map(r => ({ harnessId: r.harnessId, generation: r.generation })) } : {}) }
diff --git a/cli/src/superTabs/route.spec.ts b/cli/src/superTabs/route.spec.ts
index 3a4cec7e6..8adfb44d9 100644
--- a/cli/src/superTabs/route.spec.ts
+++ b/cli/src/superTabs/route.spec.ts
@@ -113,6 +113,7 @@ describe('strength, fit and effective cost', () => {
const HAIKU = { engine: 'claude', model: 'haiku', effort: 'auto', quality: 1, cost: 1 } as const
const CODEX = { engine: 'codex', model: 'default', effort: 'default', quality: 3, cost: 2 } as const
const on = (row: Partial<Probe>, machine: string, quota: Probe['quota']) => probe({ ...row, machineId: machine, machineName: machine, quota })
+ const unknown = { known: false, leftPercent: null, resetsAt: null }
const route = (probes: Probe[], patch: Partial<Assessment>, now = NOW, open: Commitment[] = []) => ok(choose(probes, defaults, a(patch), now, open))
const picks = (r: ReturnType<typeof route>) => r.shown.map(s => `${s.model} on ${s.machineName}`)
@@ -184,6 +185,31 @@ describe('strength, fit and effective cost', () => {
expect(spent.shown[0].fit).toMatchObject({ status: 'short', effectiveCost: 2 })
expect(spent.short).toBe('No candidate is expected to cover this task; its weekly quota is expected to run out partway and resets in 7 days.')
})
+ it('an engine on an API key is metered: it fits with no window, beside a subscription machine and ranked after it', () => {
+ const metered = quotaOf2({ known: true, windows: [] })
+ expect(metered).toEqual({ known: true, leftPercent: null, resetsAt: null, metered: true })
+ const r = route([on(SONNET, 'key', metered), on(SONNET, 'sub', windows([90, 3 * H], [80, 5 * D], 'S')), on(SONNET, 'unread', unknown)], { difficulty: 'low' })
+ expect(r.shown.map(s => [s.machineName, s.fit.status])).toEqual([['sub', 'fits'], ['key', 'fits']])
+ expect(r.excluded).toEqual([{ title: 'New agent · Claude sonnet medium · unread', reason: 'Its quota could not be read in full, and another candidate\'s quota fits this task.' }])
+ expect(r.shown[1].fit).toEqual({ status: 'fits', coverage: null, effectiveCost: 2, expiring: 0, spend: { '5-hour': 30, weekly: 4 }, account: 'key:claude' })
+ expect(r.shown[1].label).toContain('fits: metered, no usage window to run out')
+ expect(r.shown[1].label).toContain('quota metered')
+ })
+ it('keeps the best row of every machine inside the shown rows, then fills by rank', () => {
+ const full = windows([90, 3 * H], [80, 5 * D], 'S')
+ const crowd = Array.from({ length: 14 }, (_, i) => probe({ kind: 'member', agentId: `m${i}`, name: `Member ${String(i).padStart(2, '0')}`, machineId: 'a', machineName: 'a', quota: full }))
+ const far = on({ ...OPUS }, 'z', windows([90, 3 * H], [80, 5 * D], 'Z'))
+ const r = route([...crowd, far], { difficulty: 'low' })
+ expect(r.shown).toHaveLength(12)
+ // The costlier machine z ranks 15th, behind all of a's rows, yet its best row is shown, in place of a's 12th.
+ expect(r.shown.map(s => s.machineName)).toEqual([...Array(11).fill('a'), 'z'])
+ expect(r.shown.map(s => s.id)).toEqual(Array.from({ length: 12 }, (_, i) => `c${i}`))
+ })
+ it('with more machines than rows shown, keeps the best rows of the best-ranked machines', () => {
+ const many = Array.from({ length: 14 }, (_, i) => on(SONNET, `m${String(i).padStart(2, '0')}`, windows([90 - i, 3 * H], [80, 5 * D], `A${i}`)))
+ const r = route([...many, ...many.map(p => ({ ...p, kind: 'member' as const, agentId: p.machineId, name: 'Extra' }))], { difficulty: 'low' })
+ expect(new Set(r.shown.map(s => s.machineName)).size).toBe(12)
+ })
it('orders the short by how far they get, then by the policy order, and says when no reset is known', () => {
const r = route([on(SONNET, 'b', windows([25, null], [80, null], 'B')), on(SONNET, 'a', windows([25, null], [80, null], 'A')), on(SONNET, 'c', windows([30, null], [80, null], 'C'))], {})
expect(picks(r)).toEqual(['sonnet on c', 'sonnet on a', 'sonnet on b'])
diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.ts
index 159157eb7..fd21aa843 100644
--- a/cli/src/superTabs/route.ts
+++ b/cli/src/superTabs/route.ts
@@ -23,8 +23,9 @@ export interface Policy { version: 1; models: PolicyModel[]; floor: Record<Level
/** One usage window, named by the reader (`5-hour`, `weekly`); `leftPercent` is what remains of it. */
export interface QuotaWindow { name: string | null; leftPercent: number; resetsAt: number | null }
/** `leftPercent` and `resetsAt` are the tightest window's; `windows` is every window. `account` is the reading's hashed
- * account key, which models on one subscription share. */
-export interface Quota { known: boolean; leftPercent: number | null; resetsAt: number | null; windows?: QuotaWindow[]; account?: string }
+ * account key, which models on one subscription share. `metered` is an engine on an API key or gateway: known, with no
+ * usage window to run out. */
+export interface Quota { known: boolean; leftPercent: number | null; resetsAt: number | null; windows?: QuotaWindow[]; account?: string; metered?: true }
/** The task's folder as the Lead's machine sees it. `unknown` means it could not be read, `none` that it is not a repository,
* `missing` that the Lead's machine has no such folder (a member elsewhere may). */
export interface TaskFolder { cwd: string; kind: 'git' | 'none' | 'missing' | 'unknown'; name: string | null; root: string | null; remote: string | null }
@@ -130,7 +131,8 @@ function resetMs(value: unknown): number | null {
}
export function quotaOf2(q: { known: boolean; windows: Array<{ usedPercent: number; resetsAt: unknown; name?: string }>; account?: string | null }): Quota {
const account = q.account ? { account: q.account } : {}
- if (!q.known || !q.windows.length) return { known: false, leftPercent: null, resetsAt: null, ...account }
+ if (!q.known) return { known: false, leftPercent: null, resetsAt: null, ...account }
+ if (!q.windows.length) return { known: true, leftPercent: null, resetsAt: null, metered: true, ...account }
const tightest = q.windows.reduce((x, y) => y.usedPercent > x.usedPercent ? y : x)
return { known: true, leftPercent: Math.max(0, 100 - tightest.usedPercent), resetsAt: resetMs(tightest.resetsAt),
windows: q.windows.map(w => ({ name: w.name ?? null, leftPercent: Math.max(0, 100 - w.usedPercent), resetsAt: resetMs(w.resetsAt) })), ...account }
@@ -177,6 +179,7 @@ function span(ms: number): string {
}
const resetsIn = (resetsAt: number, now: number) => span(Math.max(0, resetsAt - now))
function quotaText(q: Quota, now: number): string {
+ if (q.metered) return 'quota metered'
if (!q.known || q.leftPercent === null) return 'quota unknown'
if (q.windows?.length) {
return `quota ${q.windows.map(w => `${w.name ?? 'window'} ${Math.round(w.leftPercent)}% left${w.resetsAt === null ? '' : ` (resets in ${resetsIn(w.resetsAt, now)})`}`).join(', ')}`
@@ -217,6 +220,7 @@ function sizeUp(p: Probe, policy: Policy, a: Assessment, now: number, open: Comm
const { minutes, spend: base } = SIZES[a.size], runMs = minutes * 60_000
const account = p.quota.account ?? `${p.machineId}:${p.engine}`
const spend = { '5-hour': base['5-hour'] * p.cost / 2, weekly: base.weekly * p.cost / 2 }
+ if (p.quota.metered) return { fit: { status: 'fits', coverage: null, effectiveCost: p.cost, expiring: 0, spend, account }, tight: null, text: 'fits: metered, no usage window to run out' }
// Picks still at work hold what they were expected to spend, less the part of their run time already over.
const committed = (name: Window) => open.filter(c => c.account === account)
.reduce((sum, c) => sum + (c.spend[name] ?? 0) * Math.max(0, 1 - (now - c.createdAt) / (SIZES[c.size].minutes * 60_000)), 0)
@@ -261,6 +265,16 @@ function compare(x: Probe & Sized, y: Probe & Sized, soft: Soft): number {
|| titleOf(x).localeCompare(titleOf(y))
}
+/** The rows shown: each machine's best row first (the best-ranked machines, if there are more than the limit), then the rest by rank,
+ * all in rank order, so the Lead can always choose another machine. */
+function withEveryMachine<T extends { machineId: string }>(ranked: T[]): T[] {
+ const firsts = new Set<T>(), seen = new Set<string>()
+ for (const p of ranked) if (!seen.has(p.machineId)) { seen.add(p.machineId); firsts.add(p) }
+ const keep = new Set([...firsts].slice(0, MAX_SHOWN))
+ for (const p of ranked) if (keep.size < MAX_SHOWN) keep.add(p)
+ return ranked.filter(p => keep.has(p))
+}
+
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}`
@@ -281,7 +295,7 @@ export function choose(probes: Probe[], policy: Policy, a: Assessment, now: numb
// When every candidate is short, the one expected to get furthest goes first.
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 shown = withEveryMachine(set).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)}`}.` } : {}) }
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index 00f7d0777..665855c67 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -733,6 +733,20 @@ describe('routing contributed capacity', () => {
expect((await runPool(p)).answer.ok).toBe(true)
expect((await runPool({ ...p, observation: {} }, true)).answer.ok).not.toBe(true)
})
+ it('lists API-key machines beside a subscription one, and offers the best row of every other machine as an alternative', async () => {
+ const keyed = (machineId: string) => ({ ...healthy(), machineId, name: `Keyed ${machineId}`, observation: { ...healthy().observation, runningHarnessIds: [],
+ quotas: [{ engine: 'claude', known: true, windows: [] }] } })
+ // The subscription machine has two engines, so its two best rows come before any other machine's.
+ const subscription = healthy(), reading = { usedPercent: 20, resetsAt: Date.now() + 5 * 86_400_000 }
+ Object.assign(subscription, { engines: ['claude', 'codex'] })
+ subscription.observation.quotas = ['claude', 'codex'].map(engine => ({ engine, known: true, windows: [{ ...reading, name: '5-hour' }, { ...reading, name: 'weekly' }] }))
+ const enabled = { ...policy, models: policy.models.map(m => ({ ...m, enabled: true })) }
+ const s = scoped({ context: { ok: true, value: { agentId: 'lead', tab: { state: { id: 'tab', agents: [agents[1]], conversations: conversations(), machines: [subscription, keyed('m2'), keyed('m3')] } },
+ policy: { policy: enabled, warnings: [] }, machines: [] } } })
+ const answer = await routeTask(input, s, where, opener())
+ expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm1', engine: 'codex' } })
+ expect((answer.alternatives as Array<{ machineId: string; engine: string }>).map(x => [x.machineId, x.engine])).toEqual([['m1', 'claude'], ['m2', 'claude'], ['m3', 'claude']])
+ })
it('refuses unobserved tools and devices, without probing arbitrary paths on a teammate computer', async () => {
expect((await runPool(healthy(), false, { tools: ['docker'], devices: ['/dev/fixture'] })).answer.ok).not.toBe(true)
})
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index 1c085b542..00d72ad50 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -193,7 +193,7 @@ export async function routeTask(input: { tabId: string; conversationId: string;
return {
ok: true, ...(typeof routeDecisionId === 'string' ? { routeDecisionId } : { unrecorded: true }),
pick: publicOf(verdict.pick), via: verdict.via, p: verdict.p, belowFloor: choice.belowFloor, why: verdict.why,
- alternatives: choice.shown.filter(s => s.id !== verdict.pick.id).slice(0, 2).map(publicOf),
+ alternatives: alternativesTo(verdict.pick, choice.shown).map(publicOf),
warnings: [...(Array.isArray(effective.warnings) ? effective.warnings : []), ...(value.machinesUnreadable === true ? [MACHINES_UNREADABLE] : []),
...(choice.shown.some(p => p.kind === 'member' && p.terminalUnverified) ? ["A member's terminal could not be verified from its machine's snapshot. Check it before assignment."] : []),
...(choice.short ? [choice.short] : [])],
@@ -205,6 +205,12 @@ export async function routeTask(input: { tabId: string; conversationId: string;
}
}
+/** The next two rows, and the best row of every other machine, so the Lead can choose another machine with an overrideReason. */
+function alternativesTo<T extends { id: string; machineId: string }>(pick: T, shown: T[]): T[] {
+ const seen = new Set([pick.machineId])
+ return shown.filter(s => s.id !== pick.id).filter((s, i) => { const best = !seen.has(s.machineId); seen.add(s.machineId); return i < 2 || best })
+}
+
async function probeMachine(machineId: string, { name: machineName, status, account, pool }: { name: string; status: string; account: boolean; pool?: Json },
members: Json[], allModels: Policy['models'], policy: Policy, a: Assessment, where: Where, open: typeof openDaemon): Promise<Probe[]> {
const listedEngines = Array.isArray(pool?.engines) ? pool.engines.filter((engine): engine is string => typeof engine === 'string') : []