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.

8.6 KB
Raw Blame
/** The routing policy's shape (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md), kept for older clients
 * (project instructions, phase 4). The tab's routing-policy read serves the built-in policy below, made from the model catalog
 * (catalog.ts), so an older CLI reads the catalog's rows as a policy; an owner's saved policy or tab override is accepted,
 * kept nowhere and never read to route. Only the migration (migration/instructions.ts) still reads a saved one, with
 * effectivePolicy, to write its differences into the project's instructions. */
import { z } from 'zod'
import { BENCHMARK_PRIORS } from './benchmarkPriors/data.js'
import { JOB_KINDS, priorLevel, type JobKind, type PriorsTable } from './benchmarkPriors/priors.js'
import { MODEL_CATALOG, type CatalogModel } from './catalog.js'

/** A catalog row as a policy row: its strength is the row's quality, and whether it is offered whether it is enabled. */
const policyRow = (m: CatalogModel) => ({ engine: m.engine, model: m.model, effort: m.effort, quality: m.strength, cost: m.cost, enabled: m.offered })
/** Built-in rows added after owners could save a policy, so saved policies read them too (effectivePolicy): Codex's own
 *  default model named (GPT-6.1 Sol), and GPT-6-Astra at xhigh, as the catalog has them. */
const ADDED_ROWS = MODEL_CATALOG.models.filter(m => m.model === 'gpt-6.1-sol' || m.model === 'gpt-6-astra').map(policyRow)
/** An owner keeps exactly up to 40 rows of their own. A built-in row added on read, or the owner's own version of one (the same
 *  engine and model), never counts against that, or a full policy could no longer be saved once read (reviews of #2271). */
const OWN_MODEL_ROWS = 40
type Named = { engine: string; model: string }
const same = (a: Named, b: Named) => a.engine === b.engine && a.model === b.model
const builtIn = (row: Named) => ADDED_ROWS.some(added => same(added, row))

const quality = z.number().int().min(1).max(3)
const modelRow = z.object({
  engine: z.enum(['claude', 'codex']),
  // `default` keeps the engine's own configured model or effort; no runtime switch is made.
  model: z.string().trim().min(1).max(200),
  effort: z.string().trim().min(1).max(80),
  quality,
  cost: z.number().int().min(1).max(100),
  enabled: z.boolean(),
}).strict()
const models = z.array(modelRow).min(1).max(OWN_MODEL_ROWS + ADDED_ROWS.length)
  .refine(rows => rows.filter(row => !builtIn(row)).length <= OWN_MODEL_ROWS, `At most ${OWN_MODEL_ROWS} rows of your own.`)
const fields = {
  models,
  floor: z.object({ low: quality, medium: quality, high: quality }).strict(),
  quotaReserve: z.number().int().min(0).max(90),
  notes: z.string().trim().max(500),
  /** How strong a model served on the Swarm's grid counts (the Local models add-on): `quality` for any model, `models` for
   * those named, first match first (gridQuality). Optional: policies saved before them still parse, and read the defaults. */
  localModels: z.object({ quality, enabled: z.boolean(),
    models: z.array(z.object({ model: z.string().trim().min(1).max(200), quality }).strict()).max(40).optional() }).strict().optional(),
  /** The owner's own quality for a model and job kind, replacing its benchmark prior (benchmarkPriors/priors.ts): the first row
   * whose every word is in the model's name wins, as in `localModels.models`. Optional: policies saved before it still parse. */
  priorOverrides: z.array(z.object({ model: z.string().trim().min(1).max(200), kind: z.enum(JOB_KINDS), quality }).strict()).max(100).optional(),
}
export const routingPolicySchema = z.object({ version: z.literal(1), ...fields }).strict()
export const routingOverrideSchema = z.object(fields).partial().strict()
/** What a save accepts: the first row for each built-in model rides free, and every further copy counts against the 40, so a
 *  second copy never rides free (review of #2271), yet an owner with two rows of a model that became built-in, such as
 *  Astra at two efforts, still saves (review of #2314). Only saves count them: a policy saved before still reads as saved. */
const extraCopies = (rows: ReadonlyArray<Named>) => ADDED_ROWS.reduce((n, added) => n + Math.max(0, rows.filter(row => same(row, added)).length - 1), 0)
const saved = { ...fields, models: models.refine(rows => rows.filter(row => !builtIn(row)).length + extraCopies(rows) <= OWN_MODEL_ROWS,
  `At most ${OWN_MODEL_ROWS} rows of your own.`) }
export const routingPolicySaveSchema = z.object({ version: z.literal(1), ...saved }).strict()
export const routingOverrideSaveSchema = z.object(saved).partial().strict()
export type RoutingPolicy = z.infer<typeof routingPolicySchema>
export type RoutingOverride = z.infer<typeof routingOverrideSchema>
export type RoutingModel = RoutingPolicy['models'][number]

/** The built-in policy: the catalog's rows and grid ratings, with the floors and reserve an older CLI reads. */
export const DEFAULT_ROUTING_POLICY: RoutingPolicy = {
  version: 1,
  models: MODEL_CATALOG.models.map(policyRow),
  floor: { low: 1, medium: 2, high: 3 },
  quotaReserve: 10,
  notes: '',
  localModels: { quality: MODEL_CATALOG.grid.strength, enabled: true,
    models: MODEL_CATALOG.grid.models.map(row => ({ model: row.model, quality: row.strength })) },
}

/** A saved account policy with a tab override over it, as routing read them before the instructions. Only the migration
 *  reads saved policies now. */
export function effectivePolicy(account: unknown, override: unknown) {
  const warnings: string[] = []
  let policy = DEFAULT_ROUTING_POLICY
  let accountModels: RoutingModel[] = []
  if (account !== null && account !== undefined) {
    const parsed = routingPolicySchema.safeParse(account)
    if (parsed.success) { policy = parsed.data; accountModels = parsed.data.models }
    else warnings.push('The account routing policy is unreadable; the built-in default applies.')
  }
  const overridden: Array<keyof RoutingOverride> = []
  if (override !== null && override !== undefined) {
    const parsed = routingOverrideSchema.safeParse(override)
    if (!parsed.success) warnings.push('This Super Tab routing override is unreadable and was ignored.')
    else {
      policy = { ...policy, ...parsed.data }
      overridden.push(...(Object.keys(parsed.data) as Array<keyof RoutingOverride>))
    }
  }
  // A policy saved before a named row was added has no row for that model, which rated it 1: the row joins it. A row of the
  // owner's own for the model, on or off, stays as it is. A tab override saved without it takes the account's row. Either is
  // on only while its engine's `default` row is: an owner who turned Codex off keeps it off (review of #2271).
  const engineOn = (engine: string) => policy.models.some(m => m.engine === engine && m.model === 'default' && m.enabled)
  const missing = ADDED_ROWS.filter(row => !policy.models.some(m => same(m, row))).map((row): RoutingModel => {
    const from = accountModels.find(m => same(m, row)) ?? row
    return { ...from, enabled: from.enabled && engineOn(row.engine) }
  })
  if (missing.length) policy = { ...policy, models: [...policy.models, ...missing] }
  const local = policy.localModels ?? DEFAULT_ROUTING_POLICY.localModels!
  policy = { ...policy, localModels: { ...local, models: local.models ?? DEFAULT_ROUTING_POLICY.localModels!.models } }
  return { policy, warnings, overridden }
}

/** A name's words for matching: lowercase letters and digits, "4.1" read as "41" (cli superTabs/route.ts `words`). */
const words = (text: string) => text.toLowerCase().split(/[^a-z0-9.]+/).map(w => w.replace(/\./g, '')).filter(Boolean)

/** Where a starting quality came from: the owner's override, or the benchmark table (with the scores it rests on). */
export type Prior = { quality: number; source: 'owner' } | { quality: number; source: 'benchmark'; ratio: number; sources: NonNullable<ReturnType<typeof priorLevel>>['sources'] }

/** The starting quality of a model for a job kind: the owner's override first, else the benchmark prior, else undefined
 * (the model keeps its hand rating). `model` is the id the Swarm runs it as; `label` the grid label. Pure: no records, no network. */
export function priorFor(policy: RoutingPolicy, run: { engine: 'claude' | 'codex' | 'grid'; model: string; label?: string }, kind: JobKind,
  table: PriorsTable = BENCHMARK_PRIORS): Prior | undefined {
  const name = words(`${run.model} ${run.label ?? ''}`).join('')
  const owner = policy.priorOverrides?.find(row => row.kind === kind && words(row.model).every(w => name.includes(w)))
  if (owner) return { quality: owner.quality, source: 'owner' }
  const level = priorLevel(table, run.engine, run.model, kind)
  return level && { quality: level.quality, source: 'benchmark', ratio: level.ratio, sources: level.sources }
}