orcacompass 0.0.0-stage → 0.1.0

package/dist/placements/sources/artificialanalysis.js

@@ -0,0 +1,133 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cacheDir } from '../../paths.js';
+// Artificial Analysis Data API, free tier (artificialanalysis.ai). The data is licensed to the key's
+// owner for internal use only, so it lives in the user's cache and is never bundled with the package.
+export const AA_URL = 'https://artificialanalysis.ai/api/v2/language/models/free';
+export const AA_KEY_ENV = 'ARTIFICIAL_ANALYSIS_API_KEY';
+const FETCH_TIMEOUT_MS = 15_000;
+// The free tier lists about 700 models in 4 pages; the guard only stops a runaway has_more.
+const MAX_PAGES = 10;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+const finite = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+const positive = (v) => {
+    const n = finite(v);
+    return n !== undefined && n > 0 ? n : undefined;
+};
+/** "Claude Opus 5.5 (Max, Default Fallback)" → "Claude Opus 5.5": the effort lives in the parenthesis. */
+const baseName = (name) => name.replace(/\s*\(.*$/, '').trim();
+function toRow(raw) {
+    const slug = str(raw.slug);
+    const name = str(raw.name);
+    if (!slug || !name)
+        return undefined;
+    const evals = isObject(raw.evaluations) ? raw.evaluations : {};
+    const cost = isObject(raw.artificial_analysis_intelligence_index_cost) ? raw.artificial_analysis_intelligence_index_cost : {};
+    const perTask = isObject(cost.cost_per_task) ? cost.cost_per_task : {};
+    const pricing = isObject(raw.pricing) ? raw.pricing : {};
+    const perf = isObject(raw.performance) ? raw.performance : {};
+    const creator = isObject(raw.model_creator) ? str(raw.model_creator.name) : undefined;
+    return {
+        slug, name, base: baseName(name), creator: creator ?? '', date: str(raw.release_date) ?? '',
+        intelligence: finite(evals.artificial_analysis_intelligence_index),
+        engineering: finite(evals.artificial_analysis_engineering_index),
+        costPerTask: positive(perTask.total_cost),
+        in: positive(pricing.price_1m_input_tokens),
+        out: positive(pricing.price_1m_output_tokens),
+        tokensPerSecond: positive(perf.median_output_tokens_per_second),
+    };
+}
+const rowCapability = (r) => (r.engineering === undefined ? r.intelligence : (r.intelligence + r.engineering) / 2);
+/**
+ * Trims API pages (or their `data` arrays) to one Benchmark per model: the effort variant with the highest
+ * capability represents the model, and every variant's slug is kept for matching. Unscored models are dropped.
+ */
+export function toBenchmarks(pages) {
+    const groups = new Map();
+    for (const page of pages) {
+        const data = Array.isArray(page) ? page : isObject(page) && Array.isArray(page.data) ? page.data : [];
+        for (const raw of data) {
+            const row = isObject(raw) ? toRow(raw) : undefined;
+            if (!row)
+                continue;
+            const key = `${row.creator}\u0000${row.base}`;
+            groups.set(key, [...(groups.get(key) ?? []), row]);
+        }
+    }
+    const benchmarks = [];
+    for (const rows of groups.values()) {
+        const scored = rows.filter((r) => r.intelligence !== undefined);
+        if (scored.length === 0)
+            continue;
+        const best = scored.sort((a, b) => rowCapability(b) - rowCapability(a))[0];
+        const b = { slug: best.slug, slugs: rows.map((r) => r.slug), name: best.base, creator: best.creator, date: best.date, intelligence: best.intelligence };
+        if (best.engineering !== undefined)
+            b.engineering = best.engineering;
+        if (best.costPerTask !== undefined)
+            b.costPerTask = best.costPerTask;
+        if (best.in !== undefined)
+            b.in = best.in;
+        if (best.out !== undefined)
+            b.out = best.out;
+        if (best.tokensPerSecond !== undefined)
+            b.tokensPerSecond = best.tokensPerSecond;
+        benchmarks.push(b);
+    }
+    return benchmarks;
+}
+/** Fetches every page with the user's key and trims it; throws on HTTP errors or an empty result. */
+export async function fetchBenchmarks(key, fetchImpl = fetch) {
+    const pages = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const res = await fetchImpl(`${AA_URL}?page=${page}`, { headers: { 'x-api-key': key }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!res.ok)
+            throw new Error(`artificialanalysis.ai: HTTP ${res.status}`);
+        const body = await res.json();
+        pages.push(body);
+        if (!(isObject(body) && isObject(body.pagination) && body.pagination.has_more === true))
+            break;
+    }
+    const benchmarks = toBenchmarks(pages);
+    if (benchmarks.length === 0)
+        throw new Error('artificialanalysis.ai: no benchmarked models');
+    return benchmarks;
+}
+async function readStored(path) {
+    try {
+        const data = JSON.parse(await readFile(path, 'utf8'));
+        if (isObject(data) && typeof data.fetchedAt === 'number' && Array.isArray(data.benchmarks)) {
+            return { fetchedAt: data.fetchedAt, benchmarks: data.benchmarks };
+        }
+    }
+    catch {
+        // missing or unreadable: treated as absent
+    }
+    return undefined;
+}
+/** Fresh cache → network with the key (then cache it) → stale cache; undefined without a key and a cache. */
+export async function loadBenchmarks(opts) {
+    const now = opts.now ?? Date.now();
+    const cacheFile = join(cacheDir(), 'artificialanalysis.json');
+    const cached = await readStored(cacheFile);
+    if (cached && !opts.refresh && now - cached.fetchedAt < opts.ttlHours * 3_600_000) {
+        return { ...cached, source: 'cache' };
+    }
+    if (opts.key) {
+        try {
+            const benchmarks = await fetchBenchmarks(opts.key, opts.fetchImpl);
+            try {
+                await mkdir(cacheDir(), { recursive: true });
+                await writeFile(cacheFile, JSON.stringify({ fetchedAt: now, benchmarks }));
+            }
+            catch {
+                // an unwritable cache only costs a refetch next time
+            }
+            return { benchmarks, source: 'network', fetchedAt: now };
+        }
+        catch {
+            // fall through to the stale cache
+        }
+    }
+    return cached && { ...cached, source: 'cache' };
+}

package/dist/placements/sources/modelindex.js

@@ -0,0 +1,84 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cacheDir } from '../../paths.js';
+// The Model Index (themodelindex.org), CC BY 4.0: capability scores and OpenRouter prices.
+export const MODEL_INDEX_URL = 'https://themodelindex.org/data/models.json';
+const FETCH_TIMEOUT_MS = 10_000;
+// Same relative path from src/placements/sources/ (Vitest) and dist/placements/sources/ (built).
+const SNAPSHOT_URL = new URL('../../../data/modelindex-snapshot.json', import.meta.url);
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+const finite = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+function toRating(raw) {
+    const id = str(raw.id);
+    const score = isObject(raw.index) ? finite(raw.index.score) : undefined;
+    const api = isObject(raw.api) ? raw.api : {};
+    const out = finite(api.out);
+    if (!id || score === undefined || out === undefined || out <= 0)
+        return undefined;
+    const r = { id, name: str(raw.name) ?? id, date: str(raw.date) ?? '', score, out };
+    const orId = str(api.or_id);
+    if (orId)
+        r.orId = orId;
+    const hf = str(api.hf);
+    if (hf)
+        r.hf = hf;
+    if (typeof raw.open === 'boolean')
+        r.open = raw.open;
+    return r;
+}
+/** Trims a Model Index models.json payload to scored entries with a positive output price. */
+export function toRatings(raw) {
+    if (!isObject(raw) || !Array.isArray(raw.models))
+        return [];
+    return raw.models.flatMap((m) => (isObject(m) ? (toRating(m) ?? []) : []));
+}
+/** Fetches and trims the Model Index; throws on network/HTTP errors or an empty result. */
+export async function fetchRatings(fetchImpl = fetch) {
+    const res = await fetchImpl(MODEL_INDEX_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!res.ok)
+        throw new Error(`themodelindex.org: HTTP ${res.status}`);
+    const ratings = toRatings(await res.json());
+    if (ratings.length === 0)
+        throw new Error('themodelindex.org: no rated models');
+    return ratings;
+}
+async function readStored(path) {
+    try {
+        const data = JSON.parse(await readFile(path, 'utf8'));
+        if (isObject(data) && typeof data.fetchedAt === 'number' && Array.isArray(data.ratings)) {
+            return { fetchedAt: data.fetchedAt, ratings: data.ratings };
+        }
+    }
+    catch {
+        // missing or unreadable: treated as absent
+    }
+    return undefined;
+}
+/** Fresh cache → network (then cache it) → stale cache → bundled snapshot; undefined when all fail. */
+export async function loadRatings(opts) {
+    const now = opts.now ?? Date.now();
+    const cacheFile = join(cacheDir(), 'modelindex.json');
+    const cached = await readStored(cacheFile);
+    if (cached && !opts.refresh && now - cached.fetchedAt < opts.ttlHours * 3_600_000) {
+        return { ...cached, source: 'cache' };
+    }
+    try {
+        const ratings = await fetchRatings(opts.fetchImpl);
+        try {
+            await mkdir(cacheDir(), { recursive: true });
+            await writeFile(cacheFile, JSON.stringify({ fetchedAt: now, ratings }));
+        }
+        catch {
+            // an unwritable cache only costs a refetch next time
+        }
+        return { ratings, source: 'network', fetchedAt: now };
+    }
+    catch {
+        if (cached)
+            return { ...cached, source: 'cache' };
+    }
+    // No scores only disables score placement; routing by the family table still works.
+    const snapshot = await readStored(SNAPSHOT_URL);
+    return snapshot && { ...snapshot, source: 'snapshot' };
+}

package/dist/placements/sources/modelsdev.js

@@ -0,0 +1,113 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseEffort } from '../../routing/effort.js';
+import { cacheDir } from '../../paths.js';
+export const MODELS_DEV_URL = 'https://models.dev/api.json';
+/** Lookup priority: the first provider wins when two share a model id. */
+export const PROVIDERS = ['anthropic', 'openai', 'google', 'xai'];
+const FETCH_TIMEOUT_MS = 10_000;
+// Same relative path from src/placements/sources/ (Vitest) and dist/placements/sources/ (built).
+const SNAPSHOT_URL = new URL('../../../data/models-snapshot.json', import.meta.url);
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+function toEfforts(options) {
+    if (!Array.isArray(options))
+        return undefined;
+    const opt = options.find((o) => isObject(o) && o.type === 'effort');
+    if (!isObject(opt) || !Array.isArray(opt.values))
+        return undefined;
+    const efforts = [];
+    for (const v of opt.values) {
+        const e = typeof v === 'string' ? parseEffort(v) : undefined;
+        if (e && !efforts.includes(e))
+            efforts.push(e);
+    }
+    return efforts.length > 0 ? efforts : undefined;
+}
+function toMeta(key, raw, provider) {
+    const id = str(raw.id) ?? key;
+    const meta = { id, provider, name: str(raw.name) ?? id };
+    const family = str(raw.family);
+    if (family)
+        meta.family = family;
+    const releaseDate = str(raw.release_date);
+    if (releaseDate)
+        meta.releaseDate = releaseDate;
+    const output = isObject(raw.cost) ? raw.cost.output : undefined;
+    if (typeof output === 'number' && Number.isFinite(output))
+        meta.outputCost = output;
+    const efforts = toEfforts(raw.reasoning_options);
+    if (efforts)
+        meta.efforts = efforts;
+    return meta;
+}
+/** Trims a Models.dev api.json payload down to the providers and fields we route on. */
+export function toModelIndex(raw) {
+    const index = {};
+    if (!isObject(raw))
+        return index;
+    for (const provider of PROVIDERS) {
+        const p = raw[provider];
+        if (!isObject(p) || !isObject(p.models))
+            continue;
+        for (const [key, m] of Object.entries(p.models)) {
+            if (!isObject(m))
+                continue;
+            const meta = toMeta(key, m, provider);
+            if (!(meta.id in index))
+                index[meta.id] = meta;
+        }
+    }
+    return index;
+}
+/** Fetches and trims Models.dev; throws on network/HTTP errors or an empty result. */
+export async function fetchModelIndex(fetchImpl = fetch) {
+    const res = await fetchImpl(MODELS_DEV_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!res.ok)
+        throw new Error(`models.dev: HTTP ${res.status}`);
+    const index = toModelIndex(await res.json());
+    if (Object.keys(index).length === 0)
+        throw new Error('models.dev: no models for known providers');
+    return index;
+}
+async function readStored(path) {
+    try {
+        const data = JSON.parse(await readFile(path, 'utf8'));
+        if (isObject(data) && typeof data.fetchedAt === 'number' && isObject(data.index)) {
+            return { fetchedAt: data.fetchedAt, index: data.index };
+        }
+    }
+    catch {
+        // missing or unreadable: treated as absent
+    }
+    return undefined;
+}
+/** Fresh cache → network (then cache it) → stale cache → bundled snapshot. */
+export async function loadCatalog(opts) {
+    const now = opts.now ?? Date.now();
+    const cacheFile = join(cacheDir(), 'modelsdev.json');
+    const cached = await readStored(cacheFile);
+    if (cached && !opts.refresh && now - cached.fetchedAt < opts.ttlHours * 3_600_000) {
+        return { ...cached, source: 'cache' };
+    }
+    try {
+        const index = await fetchModelIndex(opts.fetchImpl);
+        try {
+            await mkdir(cacheDir(), { recursive: true });
+            await writeFile(cacheFile, JSON.stringify({ fetchedAt: now, index }));
+        }
+        catch {
+            // an unwritable cache only costs a refetch next time
+        }
+        return { index, source: 'network', fetchedAt: now };
+    }
+    catch {
+        if (cached)
+            return { ...cached, source: 'cache' };
+    }
+    const snapshot = await readStored(SNAPSHOT_URL);
+    if (!snapshot)
+        throw new Error(`bundled Models.dev snapshot missing or invalid: ${fileURLToPath(SNAPSHOT_URL)}`);
+    return { ...snapshot, source: 'snapshot' };
+}

package/dist/placements/table.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AGENT_IDS, CLASSIFICATION_SOURCES, TIERS } from '../types.js';
+// The placement table: every model's tiers, computed once from every source and reused until stale.
+export const PLACEMENTS_FILE = 'placements.json';
+export const PLACEMENTS_SCHEMA = 1;
+export const builtWith = (config) => structuredClone({ tierOverrides: config.tierOverrides, cursorAuto: config.cursorAuto, scoreWeight: config.scoreWeight });
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isInt = (v) => Number.isSafeInteger(v) && v >= 0;
+function validSource(v) {
+    return isObj(v) && ['network', 'cache', 'snapshot'].includes(v.source) && isInt(v.fetchedAt) && isInt(v.models);
+}
+/** A launch the router can act on: a flag with a model id, or a variant map (ids may be empty, as for Cursor Auto). */
+function validLaunch(v) {
+    return isObj(v) && ((v.kind === 'flag' && typeof v.model === 'string') || (v.kind === 'variant' && isObj(v.ids)));
+}
+function validModel(v) {
+    if (!isObj(v))
+        return false;
+    return typeof v.agent === 'string' && typeof v.modelId === 'string' && Array.isArray(v.efforts) && validLaunch(v.launch) &&
+        Array.isArray(v.poolNames) && Array.isArray(v.tiers) &&
+        Array.isArray(v.placements) && v.placements.every((p) => isObj(p) && TIERS.includes(p.tier) && CLASSIFICATION_SOURCES.includes(p.source));
+}
+function validAgent(v) {
+    return isObj(v) && typeof v.agent === 'string' && typeof v.installed === 'boolean' && Array.isArray(v.models) && v.models.every(validModel);
+}
+/** The table a file holds, or undefined when it is missing, not JSON, or not the shape this version writes. */
+export function parseTable(text) {
+    if (text === undefined)
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isObj(raw) || raw.schemaVersion !== PLACEMENTS_SCHEMA || typeof raw.version !== 'string' || !isInt(raw.builtAt))
+        return undefined;
+    const b = raw.builtWith;
+    if (!isObj(b) || !isObj(b.tierOverrides) || typeof b.cursorAuto !== 'boolean' || typeof b.scoreWeight !== 'number')
+        return undefined;
+    const s = raw.sources;
+    if (!isObj(s) || !validSource(s.catalog) || (s.scores !== null && !validSource(s.scores)) || (s.benchmarks !== null && !validSource(s.benchmarks)))
+        return undefined;
+    if (!Array.isArray(raw.agents) || !raw.agents.every(validAgent))
+        return undefined;
+    return raw;
+}
+export function readTable(readFile, dir) {
+    const text = readFile(join(dir, PLACEMENTS_FILE));
+    return { table: parseTable(text), present: text !== undefined };
+}
+const canonical = (b) => JSON.stringify({ cursorAuto: b.cursorAuto, scoreWeight: b.scoreWeight, tierOverrides: Object.fromEntries(Object.entries(b.tierOverrides).sort()) });
+/** Why the table must be rebuilt, or undefined when it can be used as is. */
+export function staleness(read, opts) {
+    if (!read.present)
+        return 'missing';
+    if (!read.table)
+        return 'invalid';
+    const t = read.table;
+    if (t.version !== opts.version)
+        return 'version';
+    // A build time in the future (clock set back, hand edit) is as untrustworthy as an old one.
+    if (t.builtAt > opts.now || opts.now - t.builtAt >= opts.ttlHours * 3_600_000)
+        return 'expired';
+    if (canonical(t.builtWith) !== canonical(builtWith(opts.config)))
+        return 'config';
+    if (t.agents.some((a) => !a.installed && AGENT_IDS.includes(a.agent) && opts.onPath.includes(a.agent)))
+        return 'agent-appeared';
+    return undefined;
+}
+/** Writes the file atomically; returns the error message when it could not be written. */
+export function writeTable(table, dir) {
+    const file = join(dir, PLACEMENTS_FILE);
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(temporary, JSON.stringify(table, null, 2) + '\n');
+        renameSync(temporary, file);
+        return undefined;
+    }
+    catch (e) {
+        return e.message;
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch { /* renamed or never written */ }
+    }
+}
+export const tableAge = (table, now) => now - table.builtAt;

package/dist/placements/tiers.js

@@ -0,0 +1,136 @@
+import { benchmarkTier, matchBenchmark } from './benchmark.js';
+import { buildScale, combinedScore, matchRating, normalizeModelId, scoreTier } from './score.js';
+import { TIERS } from '../types.js';
+// Families are stable across releases, so new versions get a tier automatically.
+export const FAMILY_TIERS = {
+    'claude-haiku': 'light',
+    'claude-sonnet': 'daily',
+    'claude-opus': 'advanced',
+    'claude-fable': 'frontier',
+    'gpt-luna': 'light',
+    'gpt-terra': 'daily',
+    'gpt-sol': 'advanced',
+    'gpt-astra': 'frontier',
+    'gemini-flash-lite': 'light',
+};
+/** Model lines matched by id, where the family is too broad: Models.dev files Gemini Argon under `gemini` and every Grok under `grok`. */
+export const MODEL_LINE_TIERS = [
+    { pattern: /^gemini(-\d+)+-argon(-|$)/, tier: 'frontier' },
+    // Grok 4.7 to 4.9 and 5+; older releases (4.20 is from early 2026) and Grok Build stay on the score.
+    { pattern: /^grok-(4-[7-9]|[5-9]|\d{2,})(-\d+)*$/, tier: 'advanced' },
+];
+/** Model Index ids of a table family: claude-opus-5-5 for claude-opus, gpt-6-1-sol for gpt-sol. */
+function familyPattern(family) {
+    const m = /^(claude|gpt)-([a-z]+)$/.exec(family);
+    if (!m)
+        return undefined;
+    return m[1] === 'claude' ? new RegExp(`^claude-${m[2]}(-\\d+)+$`) : new RegExp(`^gpt(-\\d+)+-${m[2]}$`);
+}
+/** Claude and GPT families: the ladder's own vendors, preferred over other vendors when usage ties. */
+export function isLadderVendor(family) {
+    return family !== undefined && familyPattern(family) !== undefined;
+}
+/** The newest Model Index entry of each Claude/GPT table family, with the family's tier. */
+export function findAnchors(ratings) {
+    const anchors = [];
+    for (const [family, tier] of Object.entries(FAMILY_TIERS)) {
+        const pattern = familyPattern(family);
+        const newest = pattern && ratings.filter((r) => pattern.test(r.id)).sort((a, b) => (a.date < b.date ? 1 : -1))[0];
+        if (newest)
+            anchors.push({ tier, rating: newest });
+    }
+    return anchors;
+}
+/** The score scale calibrated on the family table, or undefined when the data cannot support one. */
+export function scoreScale(ratings, weight) {
+    return ratings ? buildScale(findAnchors(ratings), weight, ratings) : undefined;
+}
+const fixed = (n) => n.toFixed(2);
+function byScore(modelId, scale) {
+    const r = matchRating(modelId, scale.ratings);
+    if (!r)
+        return undefined;
+    const c = combinedScore(scale, r);
+    const detail = `capability score (Model Index ${r.score}, $${r.out}/M → ${fixed(c)}; cuts ${scale.cuts.map(fixed).join('/')})`;
+    return { tier: scoreTier(scale, c), source: 'score', detail };
+}
+function byOverride(modelId, meta, config) {
+    const { tierOverrides } = config;
+    if (Object.hasOwn(tierOverrides, modelId))
+        return { tier: tierOverrides[modelId], source: 'override' };
+    const family = meta?.family;
+    if (family !== undefined && Object.hasOwn(tierOverrides, family))
+        return { tier: tierOverrides[family], source: 'override' };
+    return undefined;
+}
+/** The built-in model lines, then the family table. */
+function byTable(modelId, meta) {
+    const line = MODEL_LINE_TIERS.find((l) => l.pattern.test(normalizeModelId(modelId)));
+    if (line)
+        return { tier: line.tier, source: 'family' };
+    const family = meta?.family;
+    if (family !== undefined && Object.hasOwn(FAMILY_TIERS, family))
+        return { tier: FAMILY_TIERS[family], source: 'family' };
+    return undefined;
+}
+/** Override by id, override by family, built-in model line, built-in family map, then capability score. Undefined when nothing applies. */
+export function classifyModel(modelId, meta, config, scale) {
+    return byOverride(modelId, meta, config) ?? byTable(modelId, meta) ?? (scale ? byScore(modelId, scale) : undefined);
+}
+// Providers describe each model's place in their lineup in a few words; the strongest claim wins.
+const LINEUP_WORDS = [
+    ['frontier', /frontier|toughest|most demanding|most capable|most intelligent|hardest/],
+    ['light', /\bfast(est)?\b|quick|affordable|easier|cheapest|lightweight|\bsmall/],
+    ['advanced', /complex|workhorse|demanding/],
+    ['daily', /simpler|everyday|efficient|balanced|straightforward|general/],
+];
+/** The tier a provider's own description places a model in, or undefined when it says nothing usable. */
+export function lineupTier(description) {
+    const text = description?.toLowerCase() ?? '';
+    return LINEUP_WORDS.find(([, words]) => words.test(text))?.[0];
+}
+/** Tiers of Cursor's `auto` (Cost mode): Cursor picks a cheap model, so never Advanced or Frontier. */
+export const CURSOR_AUTO_TIERS = ['light', 'daily'];
+/** Cursor's `auto`, routed by the cursorAuto rule rather than a user override. */
+export function isCursorAuto(model, config) {
+    return config.cursorAuto && model.agent === 'cursor' && model.modelId === 'auto' && !Object.hasOwn(config.tierOverrides, 'auto');
+}
+const quoted = (s) => `the provider's lineup ("${s}")`;
+/**
+ * Every tier a discovered model is routed in. Overrides and Cursor Auto win; then the model's home tier (the
+ * provider's lineup words, else the family table) and its benchmark tier span a range, and it is routed in
+ * every tier between them. One signal alone places it in one tier; with neither, the capability score does.
+ */
+export function classifyLaunch(model, config, scales = {}) {
+    if (isCursorAuto(model, config))
+        return CURSOR_AUTO_TIERS.map((tier) => ({ tier, source: 'auto' }));
+    const override = byOverride(model.modelId, model.meta, config);
+    if (override)
+        return [override];
+    const lineup = lineupTier(model.lineup);
+    const home = lineup
+        ? { tier: lineup, source: 'lineup', detail: quoted(model.lineup) }
+        : byTable(model.modelId, model.meta);
+    const matched = scales.benchmark && matchBenchmark(model.modelId, scales.benchmark.benchmarks);
+    const bench = matched && scales.benchmark ? benchmarkTier(scales.benchmark, matched) : undefined;
+    if (!bench) {
+        if (home)
+            return [home];
+        const score = scales.score && byScore(model.modelId, scales.score);
+        return score ? [score] : [];
+    }
+    if (!home)
+        return [{ tier: bench.tier, source: 'benchmark', detail: bench.detail }];
+    const homeWords = home.source === 'lineup' ? quoted(model.lineup) : 'the family table';
+    if (home.tier === bench.tier)
+        return [{ ...home, detail: `${homeWords}, confirmed by ${bench.detail}` }];
+    const lo = Math.min(TIERS.indexOf(home.tier), TIERS.indexOf(bench.tier));
+    const hi = Math.max(TIERS.indexOf(home.tier), TIERS.indexOf(bench.tier));
+    return TIERS.slice(lo, hi + 1).map((tier) => {
+        if (tier === home.tier)
+            return { tier, source: home.source, detail: `${homeWords}; benchmarks place it ${bench.tier} (${bench.detail.slice('benchmarks ('.length)}` };
+        if (tier === bench.tier)
+            return { tier, source: 'benchmark', detail: `${bench.detail}; ${homeWords} places it ${home.tier}` };
+        return { tier, source: 'benchmark', detail: `between ${homeWords.replace(/ \(".*"\)$/, '')} (${home.tier}) and benchmarks (${bench.tier})` };
+    });
+}

package/dist/routing/effort.js

@@ -0,0 +1,31 @@
+export const EFFORT_LADDER = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+const rank = (e) => EFFORT_LADDER.indexOf(e);
+/** Target if supported, else the nearest lower supported effort, else the lowest higher one. */
+export function snapEffort(target, supported) {
+    if (supported.length === 0)
+        return null;
+    if (supported.includes(target))
+        return target;
+    const sorted = [...supported].sort((a, b) => rank(a) - rank(b));
+    const lower = sorted.filter((e) => rank(e) < rank(target));
+    if (lower.length > 0)
+        return lower[lower.length - 1];
+    return sorted[0];
+}
+/**
+ * Effort per reasoning demand. A starting heuristic, not a measured optimum: `balanced` keeps exceptional
+ * work at high, `quality` allows xhigh for it only, `efficient` saves effort on moderate and high work.
+ * Nothing maps to max; that takes an explicit --effort.
+ */
+export const DEMAND_EFFORT = {
+    efficient: { low: 'low', moderate: 'low', high: 'medium', exceptional: 'high' },
+    balanced: { low: 'low', moderate: 'medium', high: 'high', exceptional: 'high' },
+    quality: { low: 'low', moderate: 'medium', high: 'high', exceptional: 'xhigh' },
+};
+/** Accepts provider spellings such as "extra-high". "ultra" (Codex auto-delegation) is not an effort. */
+export function parseEffort(s) {
+    const v = s.trim().toLowerCase();
+    if (v === 'extra-high' || v === 'extra_high')
+        return 'xhigh';
+    return EFFORT_LADDER.includes(v) ? v : undefined;
+}

package/dist/routing/environment.js

@@ -0,0 +1,51 @@
+import { readTextFile } from '../placements/agents/deps.js';
+import { buildPlacements, installedAgents } from '../placements/build.js';
+import { readTable, staleness } from '../placements/table.js';
+import { cacheDir } from '../paths.js';
+import { findExecutable, runCommand } from '../system/run.js';
+import { VERSION } from '../version.js';
+import { readOrcaAgents } from './orca-settings.js';
+import { readOrcaUsage } from './orca-usage.js';
+import { activeRejections } from './rejection.js';
+import { readRejections } from './rejections.js';
+/** The cached table when it is fresh, else a rebuilt one. */
+export async function loadPlacements(config, deps = {}) {
+    const now = deps.now ?? Date.now();
+    const find = deps.find ?? findExecutable;
+    const dir = deps.cacheDir ?? cacheDir();
+    const read = readTable(deps.readFile ?? readTextFile, dir);
+    const onPath = installedAgents({ find, env: deps.env ?? process.env });
+    const why = deps.refresh
+        ? 'refresh'
+        : staleness(read, { now, ttlHours: config.placementsTtlHours, version: deps.version ?? VERSION, config, onPath });
+    if (why === undefined)
+        return { table: read.table, rebuilt: undefined };
+    const built = await buildPlacements(config, { ...deps, now, cacheDir: dir });
+    return { table: built.table, rebuilt: why, ...(built.saveError !== undefined ? { saveError: built.saveError } : {}) };
+}
+export async function gather(config, deps = {}) {
+    const now = deps.now ?? Date.now();
+    const run = deps.run ?? runCommand;
+    const [placements, usage, orcaAgents] = await Promise.all([
+        loadPlacements(config, { ...deps, now }),
+        readOrcaUsage(run),
+        (deps.readOrcaAgents ?? readOrcaAgents)(),
+    ]);
+    const { table } = placements;
+    const rejections = activeRejections(readRejections(deps.readFile ?? readTextFile, deps.cacheDir ?? cacheDir()), now, config.rejectionTtlHours);
+    const env = {
+        now,
+        discoveries: table.agents,
+        usage,
+        orcaAgents,
+        placementsBuiltAt: table.builtAt,
+        catalogSource: table.sources.catalog.source,
+        ...(table.sources.scores ? { scoreSource: table.sources.scores.source } : {}),
+        ...(table.sources.benchmarks ? { benchmarkSource: table.sources.benchmarks.source } : {}),
+        ...(rejections.length > 0 ? { rejections } : {}),
+    };
+    return { env, ...placements };
+}
+export async function gatherEnvironment(config, deps = {}) {
+    return (await gather(config, deps)).env;
+}