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
/** Cheap first (Scholes's goals, piece 4; Ken, 2026-10-29): a small, low-risk build goes to a cheap model on the Swarm's grid
* (Kimi K3, DeepSeek v4.1) before Opus or Astra, and steps up to them once that attempt fails. Reviews and security work never
* run on the grid. A route plug-in (route.ts RoutePlugin): it notes and leaves out grid candidates only, each with a reason
* people read, and leaves every subscription candidate and member as it was. Since task #2901 its note is never the order:
* the project's Routing instructions weigh it.
*
* Since project instructions (#2414) the server no longer steps a task up, and only the server knew a grid attempt's first
* review failed. So the step-up is read from what the route already sees: a grid model takes only a task's first attempt
* (Lead, 2026-10-31), and any earlier assignment, start or routed pick for the task means the next route leaves the grid out.
* That works with today's backend; a step-up the backend records on the task (`stepUp`) is read too, for its reason. */
import type { Assessment, RoutePlugin } from './route.js'
import type { PluginMaker } from './routePlugins.js'
type Json = Record<string, unknown>
const object = (v: unknown): Json => v && typeof v === 'object' && !Array.isArray(v) ? v as Json : {}
const list = (v: unknown) => Array.isArray(v) ? v.map(object) : []
const text = (v: unknown) => typeof v === 'string' && v.trim() ? v.trim() : null
/** A review task: one linked to the work it reviews. */
const isReview = (group: Json) => typeof group.reviewOf === 'string' && !!group.reviewOf
/** The plug-in's name, which starts each of its reasons on a candidate ("Cheap first: …"). */
export const CHEAP_FIRST = 'Cheap first'
/** How many owned paths a task may name and still be small enough for a grid model to try first (Lead, 2026-10-31: "a few
* owned files"). Every routed task names owned code and checks, so their presence says nothing on its own. */
export const MAX_OWNED = 3
/** The least strength a grid model needs to be tried first: the catalog's named grid rows (Kimi K3, DeepSeek v4.1) are 2; an
* unnamed grid model (a small local one) is 1 and is never noted as the cheap first choice. */
const CHEAP_STRENGTH = 2
/** Kinds of work a grid model never takes, as the routing agent names them (route.ts Assessment.kind). */
const SECURITY_KINDS = new Set(['security', 'auth', 'privacy', 'secrets', 'crypto', 'permissions'])
/** The only kinds of work a grid model may take, as the routing agent names them. Anything else, and a task with no kind, gets
* no grid model: a security task routed as low risk with no kind must never reach one (Ken's rule; Lead, 10-31: fail closed).
* Adding a kind here is the one place to widen it. */
export const GRID_KINDS: readonly string[] = ['docs', 'tests', 'fixtures', 'copy', 'refactor']
export const GRID_FIRST = 'A small, low-risk build: the cheap first choice is a model on the Swarm\'s grid. If its review fails or the attempt is lost, the next route steps up to a strong model.'
export const NEVER_REVIEWS = 'A review never runs on a model on the Swarm\'s grid: reviews need a strong model.'
export const NEVER_SECURITY = 'Security-sensitive work (a security kind or high risk) never runs on a model on the Swarm\'s grid.'
/** The kinds as people read them: "docs, tests, fixtures, copy or refactor". */
const KINDS_TEXT = `${GRID_KINDS.slice(0, -1).join(', ')} or ${GRID_KINDS.at(-1)}`
export const GRID_KINDS_ONLY = `A model on the Swarm's grid takes only work whose kind is ${KINDS_TEXT}; this task names no such kind.`
/** What the route's help tells every routing agent (service.ts HELP.route), from the same constants the plug-ins apply, so a
* Lead knows which kind to give for the cheap choice (review of #2422: help that called kind optional got it rarely). */
export const ROUTE_KIND_HELP = `one word for the kind of work; a model on the Swarm's grid is offered only for kind ${KINDS_TEXT}`
export const CHEAP_FIRST_HELP = `Cheap first: small, low-risk work (risk and difficulty low, 1 to ${MAX_OWNED} owned paths) of kind ${KINDS_TEXT} notes a model on the Swarm's grid as the cheap first choice. `
+ 'A model on the grid is never offered, even when named, for a review, security work (a security kind or high risk), work of any other kind or with no kind, or a task\'s second attempt.'
export const FIRST_ATTEMPT_ONLY = 'A model on the Swarm\'s grid takes only a task\'s first attempt, so this one steps up.'
export const EARLIER_UNREADABLE = 'Its earlier attempts could not be read, so it is not taken for a first attempt.'
const NAMED = 'A person named this model, so it is offered.'
/** What the plug-in needs of the task, read before the route (RoutePlugin: pure and synchronous). `earlier`: why this is not
* the task's first attempt, or null when it is. */
export interface CheapTask { review: boolean; owned: number; earlier: string | null }
/** What the route reads of [group]: whether it is a review (a task linked to the work it reviews), how many owned paths it
* names, and any earlier attempt at it. [history] is the route's read of the log and the group's attempts (service.ts
* routeHistory), null when it failed: an attempt it cannot rule out counts as one, so a grid model is never sent back to a
* task that already failed on it because a read timed out. */
export function cheapTaskOf(group: Json, state: Json, history: { decisions: unknown[] | null; attempts: unknown[] | null } | null): CheapTask {
const id = group.id, owns = object(group.task).owns
const starts = list(state.starts)
const harnessOf = new Map(list(state.agents).map(agent => [agent.id, agent.harnessId]))
/** The grid model an agent was started on, if it was. */
const gridOf = (agentId: unknown) => {
const harness = harnessOf.get(agentId)
return harness ? text(object(starts.find(s => s.harnessId === harness)?.request).gridModel) : null
}
const assignment = object(group.assignment), lost = object(group.lostAttempt)
const mine = starts.filter(s => object(s.request).conversationId === id)
const decisions = list(history?.decisions).filter(d => d.conversationId === id && d.final && typeof d.final === 'object')
const attempts = list(history?.attempts).filter(a => typeof a.id === 'string')
const agentIds = [assignment.agentId, lost.agentId, ...attempts.map(a => a.agentId)]
const any = !!text(assignment.id) || !!text(lost.id) || mine.length > 0 || decisions.length > 0 || attempts.length > 0
const onGrid = mine.map(s => text(object(s.request).gridModel)).find(Boolean) ?? agentIds.map(gridOf).find(Boolean)
const stepped = text(object(group.stepUp).reason)
const earlier = stepped ?? (onGrid ? `Its earlier attempt ran on ${onGrid} on the Swarm's grid.` : any ? 'It had an earlier attempt.'
: !history || !history.decisions || !history.attempts ? EARLIER_UNREADABLE : null)
return { review: isReview(group), owned: Array.isArray(owns) ? owns.filter(o => typeof o === 'string').length : 0, earlier }
}
/** Why the task is one a grid model never takes: a review (a task linked to the work it reviews, or kind `review`), security
* work (a security kind, or high risk), or work whose kind is not on [GRID_KINDS], a missing kind included. */
function forbidden(review: boolean, a: Pick<Assessment, 'kind' | 'risk'>): string | null {
if (review || a.kind === 'review') return NEVER_REVIEWS
if (a.risk === 'high' || (a.kind && SECURITY_KINDS.has(a.kind))) return NEVER_SECURITY
if (!a.kind || !GRID_KINDS.includes(a.kind)) return GRID_KINDS_ONLY
return null
}
/** The guard's name, which starts its reasons ("Grid limits: …"). */
export const GRID_LIMITS = 'Grid limits'
/** Ken's rule, "never route reviews to cheap or local models", and the same for security work: a grid candidate is left out of
* either, and of any work whose kind is not on [GRID_KINDS], even one a person names. The route itself has no such filter (project instructions, #2414), so this plug-in is the
* only place it lives. It is made from nothing but the task's own row, so it is ready at once and never depends on a read
* that could be late (Lead, 10-31). */
export function gridLimits(review: boolean): RoutePlugin {
return {
name: GRID_LIMITS,
adjust(candidate, { assessment }) {
const why = candidate.gridModel ? forbidden(review, assessment) : null
return why ? { refuse: true, reason: why } : null
},
}
}
/** Cheap first for one task, beside [gridLimits]: a grid candidate is left out of any attempt after the first unless a person
* named it, and noted as the cheap first choice for a small, low-risk build it is strong enough for, to be tried before Opus
* and Astra. Its strength leans above the catalog's strongest, which since task #2901 moves nothing. A review or security
* task is the guard's, so this says nothing of it. */
export function cheapFirst(task: CheapTask): RoutePlugin {
return {
name: CHEAP_FIRST,
adjust(candidate, { assessment: a, catalog }) {
if (!candidate.gridModel || forbidden(task.review, a)) return null
if (task.earlier) {
const why = `${FIRST_ATTEMPT_ONLY} ${task.earlier}`
return a.model || a.local ? { reason: `${why} ${NAMED}` } : { refuse: true, reason: why }
}
const small = a.risk === 'low' && a.difficulty === 'low' && task.owned > 0 && task.owned <= MAX_OWNED
if (!small || candidate.quality < CHEAP_STRENGTH) return null
const top = Math.max(CHEAP_STRENGTH, ...catalog.models.map(m => m.strength))
return { strength: top + 1 - CHEAP_STRENGTH, reason: GRID_FIRST }
},
}
}
/** The task's row in the tab the route read, or only its id when the tab does not list it. */
const groupIn = (read: Record<string, unknown>, conversationId: string) => {
const state = object(object(read.tab).state)
return { state, group: list(state.conversations).find(c => c.id === conversationId) ?? { id: conversationId } }
}
/** Makes [gridLimits] from the tab the route already read: no read of its own and nothing to wait for. */
export const GRID_LIMITS_MAKER: PluginMaker = {
name: GRID_LIMITS,
make: async ({ conversationId, read }) => gridLimits(isReview(groupIn(read, conversationId).group)),
}
/** How long the cheap-first maker waits for the route's history read: under the makers' limit (routePlugins.ts
* MAKER_TIMEOUT_MS), so the first-attempt check is made rather than dropped. A history later than this counts as
* unreadable, so the grid is left out of the attempt. */
export const HISTORY_WAIT_MS = 2000
/** Makes [cheapFirst] from the route's own reads: the task from the tab it read, and the shared history read. It reads
* nothing of its own and never fails: what it cannot read makes it leave the grid out of the attempt. */
export const CHEAP_FIRST_MAKER: PluginMaker = {
name: CHEAP_FIRST,
async make({ conversationId, read, history }) {
const { state, group } = groupIn(read, conversationId)
let timer: NodeJS.Timeout | undefined
const late = new Promise<null>(resolve => { timer = setTimeout(resolve, HISTORY_WAIT_MS, null) })
const past = object(await Promise.race([history.catch(() => null), late]).finally(() => clearTimeout(timer)))
const value = object(past.value)
return cheapFirst(cheapTaskOf(group, state, past.ok !== true ? null
: { decisions: Array.isArray(value.decisions) ? value.decisions : null, attempts: Array.isArray(value.attempts) ? value.attempts : null }))
},
}
/** Piece 4's makers, in order: the guard first, ready at once, then cheap first. */
export const CHEAP_FIRST_MAKERS: readonly PluginMaker[] = [GRID_LIMITS_MAKER, CHEAP_FIRST_MAKER]