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
/** What `harness super-tab route` records (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md). */
import { z } from 'zod'
import type { RouteRun } from './costs/attempts.js'
import { JOB_KINDS } from './evidence/jobKind.js'
const level = z.enum(['low', 'medium', 'high'])
const candidateId = z.string().regex(/^c\d{1,2}$/)
const machine = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
const amount = z.number().finite().nonnegative()
/** How the candidate's quota fits the task (phase 1 routing), kept so committed spend and pick quality can be read back. */
const fit = z.object({
status: z.enum(['fits', 'unknown', 'short']),
/** Usable over needed on the tightest window; negative when committed spend already exceeds what is left. */
coverage: z.number().finite().nullable(),
effectiveCost: amount,
expiring: amount,
spend: z.object({ '5-hour': amount.optional(), weekly: amount.optional() }).strict(),
/** The hashed usage key, or `machineId:engine` when the machine reports none. */
account: z.string().min(1).max(200).optional(),
/** The account's weekly window when the route ran (cli route.ts quotaBrief): percent left and reset in epoch ms, null when
* not read. Absent from a CLI from before task #3163. */
left: z.number().finite().min(0).max(100).nullable().optional(),
resetsAt: z.number().finite().nonnegative().nullable().optional(),
}).strict()
export const routeCandidateSchema = z.object({
id: candidateId,
kind: z.enum(['member', 'new']),
agentId: machine.optional(),
machineId: machine,
engine: z.enum(['claude', 'codex']),
model: z.string().min(1).max(200),
effort: z.string().min(1).max(80),
quality: z.number().int().min(1).max(3),
cost: z.number().int().min(1).max(100),
/** Short, for the conversation row: "Multiply · Claude opus high · remote-1". */
title: z.string().trim().min(1).max(160),
/** The criterion line Jev was shown. */
label: z.string().trim().min(1).max(640),
fit: fit.optional(),
/** A new agent on a model served on the Swarm's grid: its model and effort are `default`. */
gridModel: z.string().min(1).max(200).optional(),
gridName: z.string().min(1).max(160).optional(),
}).strict().refine(c => (c.kind === 'member') === !!c.agentId, 'Members name their agent; new agents do not.')
export const routeRecordSchema = z.object({
assessment: z.object({ difficulty: level, risk: level, why: z.string().trim().min(1).max(300),
size: z.enum(['small', 'medium', 'large']).optional(),
/** The job's kind the Lead gave (`ui`, `docs`; `review` for a review), what attempts are compared by (costs/read.ts). */
kind: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/).optional(),
/** A person asked for a local model, or named one (cli superTabs/route.ts Assessment), kept with the decision. */
local: z.literal(true).optional(), model: z.string().trim().min(1).max(200).optional() }).strict(),
/** Every engine on every machine, a new agent and an idle member each (cli superTabs/route.ts RECORD_MAX, Ken 2026-11-03); 12
* before, when the route showed one row a machine. */
candidates: z.array(routeCandidateSchema).min(1).max(64),
excluded: z.array(z.object({ title: z.string().trim().min(1).max(160), reason: z.string().trim().min(1).max(500) }).strict()).max(200),
floor: z.number().int().min(1).max(3),
notes: z.boolean(),
/** The candidate an older CLI ranked first. The route names none since task #2901 (Ken, 2026-11-04): the project's Routing
* instructions choose, and the start or assignment records which candidate it was (RouteFinal.candidateId). */
pick: candidateId.optional(),
/** `instructions`: no pick, the coordinator chooses by the Routing instructions (task #2901). `only` comes with or without one. */
via: z.enum(['jev', 'order', 'only', 'instructions']),
/** Why the policy order decided, when it did: Jev answered without enough confidence, or could not be asked. */
fallback: z.enum(['unsure', 'unavailable']).optional(),
p: z.number().min(0).max(1).nullable(),
belowFloor: z.boolean(),
/** The verdict's own explanation, kept for analysis; the row quotes the Lead's assessment instead. */
why: z.string().trim().min(1).max(300),
/** How much context Jev was given and which sources could not be read, so pick quality can later be compared with completeness. */
context: z.object({ chars: z.number().int().min(0).max(30_000), missing: z.array(z.string().min(1).max(40)).max(10) }).strict().optional(),
/** The step up this attempt was: its task's step up (model.ts Conversation.stepUp), stamped by the server when the route is
* recorded, never taken from the route. */
stepUp: z.object({ attempt: z.number().int().min(2).max(3), reason: z.string().min(1).max(200) }).strict().optional(),
/** Why a review ran on its Builder's own engine, on records from before 2026-10-30, when another engine had to review when it could. Never written since, never taken from the route. */
sameEngine: z.string().min(1).max(300).optional(),
/** The job's kind from the fixed list (evidence/jobKind.ts), written by the server from its group, never taken from the route. */
jobKind: z.enum(JOB_KINDS).optional(),
/** The project instructions' revision the route relied on (`project.instructionsRevision ?? 0` when it was recorded), written
* by the server, never taken from the route. Absent from records before project instructions. */
instructionsRevision: z.number().int().nonnegative().optional(),
}).strict().refine(d => d.pick === undefined || d.candidates.some(c => c.id === d.pick), 'The pick must be one of the candidates.')
.refine(d => new Set(d.candidates.map(c => c.id)).size === d.candidates.length, 'Candidate ids must be unique.')
/** The part of a quota fit every candidate of a record without a pick keeps: what the route history reads of the one that ran,
* and its quota when the route ran (task #3163: with account and spend alone, quota at route time could not be measured), and
* how far that quota covered the task (task #3255). Rows written before keep no status, coverage, % left or reset. */
export type KeptFit = Pick<z.infer<typeof fit>, 'account' | 'spend'> & Partial<Pick<z.infer<typeof fit>, 'status' | 'coverage' | 'left' | 'resetsAt'>>
/** A candidate as a decision keeps it: the pick whole; any other only who and where it is and its title, and with no pick its
* account and spend too (storedRecord). */
export type KeptCandidate = Omit<RouteCandidate, 'quality' | 'cost' | 'label' | 'fit'> & Partial<Pick<RouteCandidate, 'quality' | 'cost' | 'label'>>
& { fit?: RouteCandidate['fit'] | KeptFit }
/** A record as its readers get it back (readRecord): its candidates as kept. */
export type ReadRouteRecord = Omit<RouteRecord, 'candidates'> & { candidates: KeptCandidate[] }
/** A record as stored (routeDecisions.ts): the pick whole, the other candidates as KeptCandidate, and the exclusions kept once
* per reason. On production (2026-11-03) labels were 5.4 KB of a 20.9 KB row and exclusions 8.9 KB, 47 of them sharing ~5
* reasons (task #2488); the 42 candidates of an 11-04 route were still ~18.9 KB, ~8.5 KB of it quota fits (task #2769). Rows
* written before keep `excluded` and no `unavailable`, and every candidate whole. */
export interface StoredRouteRecord extends Omit<ReadRouteRecord, 'excluded'> {
excluded?: RouteRecord['excluded']
unavailable?: Array<{ reason: string; titles: string[] }>
}
/** What a decision keeps of [record]: the pick whole, and of every other candidate only what a reader takes back of one: who
* and where it is (a start or assignment matching it, startedAs; a person choosing it, route.override; its Team-work check) and
* its title (the chat lines, Desktop's Details). Its label, strength, cost and quota fit are read of the pick only: the route
* showed the others when it ran, and the route history takes the account and spend of the pick (cli service.ts routeHistory).
* A record with no pick (task #2901) keeps every candidate's account, spend and quota (status, coverage, % left and reset) instead,
* as any of them may be the one that runs and nobody knows which until the start. Each exclusion reason is kept once, with its
* titles in order. */
function keptFit({ account, spend, status, coverage, left, resetsAt }: z.infer<typeof fit>): KeptFit {
return { ...account ? { account } : {}, spend, status, coverage, ...left !== undefined ? { left } : {}, ...resetsAt !== undefined ? { resetsAt } : {} }
}
export function storedRecord(record: RouteRecord): StoredRouteRecord {
const { excluded, ...rest } = record
const candidates = record.candidates.map(({ label: _label, quality: _quality, cost: _cost, fit, ...c }, i): KeptCandidate =>
record.pick === undefined ? { ...c, ...fit ? { fit: keptFit(fit) } : {} }
: c.id === record.pick ? record.candidates[i]! : c)
const byReason = new Map<string, string[]>()
for (const { title, reason } of excluded) byReason.set(reason, [...byReason.get(reason) ?? [], title])
return { ...rest, candidates, ...byReason.size ? { unavailable: [...byReason].map(([reason, titles]) => ({ reason, titles })) } : { excluded: [] } }
}
/** Either stored form back as readers get a record: `unavailable` expanded into `excluded`, reason by reason in the order each
* first appeared. A record written before this is returned as it is. */
export function readRecord(stored: StoredRouteRecord | RouteRecord): ReadRouteRecord {
if (!('unavailable' in stored) || !stored.unavailable) return stored as ReadRouteRecord
const { unavailable, ...rest } = stored
return { ...rest, excluded: unavailable.flatMap(({ reason, titles }) => titles.map(title => ({ title, reason }))) } as ReadRouteRecord
}
/**
* Whether a started agent is the candidate's: the same machine, engine, and the model and effort that were
* requested. After a failed switch `final` holds what ran, so the request is the one that names the candidate.
*/
export const startedAs = (candidate: KeptCandidate, final: Extract<RouteFinal, { kind: 'new' }>): boolean =>
final.machineId === candidate.machineId && final.engine === candidate.engine &&
(final.requested?.model ?? final.model) === candidate.model && (final.requested?.effort ?? final.effort) === candidate.effort &&
(final.gridModel ?? null) === (candidate.gridModel ?? null) && (final.gridName ?? null) === (candidate.gridName ?? null)
/** Whether a decision's final names this candidate: the same agent, or the same start. */
export const finalMatches = (candidate: KeptCandidate, final: RouteFinal | null): boolean => !!final && (candidate.kind === 'member'
? final.kind === 'member' && final.agentId === candidate.agentId
: final.kind === 'new' && startedAs(candidate, final))
export type RouteCandidate = z.infer<typeof routeCandidateSchema>
export type RouteRecord = z.infer<typeof routeRecordSchema>
/** `candidateId` names the candidate the start or assignment matched when the record has no pick (task #2901): the
* coordinator's own choice by the Routing instructions, which the route history reads back. */
export type RouteFinal =
| { kind: 'member'; agentId: string; machineId: string; candidateId?: string }
/** After a failed model switch, `model` and `effort` are what ran and `requested` is what routing asked for. */
| { kind: 'new'; startId: string; machineId: string; engine: string; model: string; effort: string; requested?: { model: string; effort: string };
gridModel?: string; gridName?: string; candidateId?: string }
export interface RouteOverride { by: 'lead' | 'person'; actorKey: string; candidateId?: string; reason: string }
export interface RouteDecision {
id: string; conversationId: string; record: ReadRouteRecord
final: RouteFinal | null; override: RouteOverride | null; assignmentId: string | null; outcome: string | null
/** Its attempt's run: what it ran on, how it was paid, its session's token totals at start and end (costs/attempts.ts). */
run: RouteRun | null
}
export type RouteDecisionEffect =
| { op: 'create'; id: string; conversationId: string; record: RouteRecord }
| { op: 'override'; id: string; override: RouteOverride }
| { op: 'final'; id: string; final: RouteFinal; override?: RouteOverride; assignmentId?: string }
export const routeTitle = (decision: RouteDecision, candidateId: string): string =>
decision.record.candidates.find(c => c.id === candidateId)?.title ?? 'another candidate'