The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsindex 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.tsindex 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 = 1000const 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.tsindex 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.tsindex 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 constconst CODEX = { engine: 'codex', model: 'default', effort: 'default', quality: 3, cost: 2 } as constconst 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.tsindex 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: Commconst { minutes, spend: base } = SIZES[a.size], runMs = minutes * 60_000const 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.tsindex 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.tsindex 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') : []