@bastani/atomic 0.9.21-alpha.1 → 0.9.21-alpha.2

package/dist/core/model-routing-constraints.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-routing-constraints.js","sourceRoot":"","sources":["../../src/core/model-routing-constraints.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Api, Model } from \"@bastani/pi-ai\";\nimport { type Static, Type } from \"typebox\";\nimport { Compile } from \"typebox/compile\";\n\nexport const ModelConstraintsSchema = Type.Object(\n\t{\n\t\tallowedModels: Type.Optional(\n\t\t\tType.Array(Type.String({ minLength: 1 }), {\n\t\t\t\tdescription: \"Exact provider/model IDs; omitted uses the full available catalog.\",\n\t\t\t}),\n\t\t),\n\t\tmaxInputCost: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tminimum: 0,\n\t\t\t\tdescription:\n\t\t\t\t\t\"Maximum catalog input rate in USD per million tokens, including pricing tiers; not total task spending.\",\n\t\t\t}),\n\t\t),\n\t\tmaxOutputCost: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tminimum: 0,\n\t\t\t\tdescription:\n\t\t\t\t\t\"Maximum catalog output rate in USD per million tokens, including pricing tiers; not total task spending.\",\n\t\t\t}),\n\t\t),\n\t\tminContextWindow: Type.Optional(\n\t\t\tType.Number({ minimum: 0, description: \"Minimum catalog context window in tokens.\" }),\n\t\t),\n\t\trequiredInputs: Type.Optional(\n\t\t\tType.Array(Type.Unsafe<\"text\" | \"image\">(Type.String({ enum: [\"text\", \"image\"] }))),\n\t\t),\n\t\tallowedEfforts: Type.Optional(\n\t\t\tType.Array(\n\t\t\t\tType.Union([\n\t\t\t\t\tType.String({ enum: [\"off\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\"] }),\n\t\t\t\t\tType.Null(),\n\t\t\t\t]),\n\t\t\t),\n\t\t),\n\t},\n\t{\n\t\tadditionalProperties: false,\n\t\tdescription:\n\t\t\t\"Hard constraints for auto selection and execution fallback. Applicable definition and call constraints must all hold; concrete model calls keep existing behavior.\",\n\t},\n);\nexport type ModelConstraints = Static<typeof ModelConstraintsSchema>;\nconst validator = Compile(ModelConstraintsSchema);\nexport function parseModelConstraints(value: unknown): ModelConstraints | undefined {\n\tif (value === undefined) return undefined;\n\tif (\n\t\t!validator.Check(value) ||\n\t\t[value.maxInputCost, value.maxOutputCost, value.minContextWindow].some(\n\t\t\t(n) => n !== undefined && !Number.isFinite(n),\n\t\t)\n\t) {\n\t\tthrow new Error(\"Invalid modelConstraints: use known fields and finite nonnegative numeric limits.\");\n\t}\n\treturn value;\n}\nexport type ModelRouterOutput = {\n\treadonly model: string;\n\treadonly effort: string | null;\n\t/** Ranked alternatives, excluding the primary. Absent on legacy recorded selections. */\n\treadonly fallbacks?: readonly { readonly model: string; readonly effort: string | null }[];\n};\n/** Every applicable declaration must hold; a caller never widens a definition restriction. */\nexport function eligiblePair(\n\tmodel: Model<Api>,\n\tpair: ModelRouterOutput,\n\tconstraints: readonly ModelConstraints[],\n): boolean {\n\treturn constraints.every(\n\t\t(c) =>\n\t\t\t(c.allowedModels === undefined || c.allowedModels.includes(pair.model)) &&\n\t\t\t(c.allowedEfforts === undefined || c.allowedEfforts.some((e) => e === pair.effort)) &&\n\t\t\t(c.maxInputCost === undefined ||\n\t\t\t\t[model.cost, ...(model.cost.tiers ?? [])].every((rate) => rate.input <= c.maxInputCost!)) &&\n\t\t\t(c.maxOutputCost === undefined ||\n\t\t\t\t[model.cost, ...(model.cost.tiers ?? [])].every((rate) => rate.output <= c.maxOutputCost!)) &&\n\t\t\t(c.minContextWindow === undefined || model.contextWindow >= c.minContextWindow) &&\n\t\t\t(c.requiredInputs === undefined || c.requiredInputs.every((input) => model.input.includes(input))),\n\t);\n}\n"]}
+{"version":3,"file":"model-routing-constraints.js","sourceRoot":"","sources":["../../src/core/model-routing-constraints.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Api, Model } from \"@bastani/pi-ai\";\nimport { type Static, Type } from \"typebox\";\nimport { Compile } from \"typebox/compile\";\n\nexport const ModelConstraintsSchema = Type.Object(\n\t{\n\t\tallowedModels: Type.Optional(\n\t\t\tType.Array(Type.String({ minLength: 1 }), {\n\t\t\t\tdescription:\n\t\t\t\t\t\"Exact provider/model IDs; omitted uses the full available catalog. With model 'auto', these are the candidates the router chooses between (as many as fit one routing request, roughly 100), so list the models that suit the task. Prefer the user's subscription models (for example ChatGPT/Codex, GitHub Copilot, a Claude subscription, or a coding or token plan) over pay-per-token API models, unless the user asked for API models or has no subscription models.\",\n\t\t\t}),\n\t\t),\n\t\tallowedProviders: Type.Optional(\n\t\t\tType.Array(Type.String({ minLength: 1 }), {\n\t\t\t\tdescription:\n\t\t\t\t\t'Provider IDs whose models may be used, for example [\"openai-codex\", \"github-copilot\"]. Setting this or excludedProviders replaces the user\\'s modelRouting provider settings for this call, so set them only when the user asks to use or avoid specific providers.',\n\t\t\t}),\n\t\t),\n\t\texcludedProviders: Type.Optional(\n\t\t\tType.Array(Type.String({ minLength: 1 }), {\n\t\t\t\tdescription:\n\t\t\t\t\t'Provider IDs whose models are never used, for example [\"openrouter\"]. Setting this or allowedProviders replaces the user\\'s modelRouting provider settings for this call, so set them only when the user asks.',\n\t\t\t}),\n\t\t),\n\t\tmaxInputCost: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tminimum: 0,\n\t\t\t\tdescription:\n\t\t\t\t\t\"Maximum catalog input rate in USD per million tokens, including pricing tiers; not total task spending.\",\n\t\t\t}),\n\t\t),\n\t\tmaxOutputCost: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tminimum: 0,\n\t\t\t\tdescription:\n\t\t\t\t\t\"Maximum catalog output rate in USD per million tokens, including pricing tiers; not total task spending.\",\n\t\t\t}),\n\t\t),\n\t\tminContextWindow: Type.Optional(\n\t\t\tType.Number({ minimum: 0, description: \"Minimum catalog context window in tokens.\" }),\n\t\t),\n\t\trequiredInputs: Type.Optional(\n\t\t\tType.Array(Type.Unsafe<\"text\" | \"image\">(Type.String({ enum: [\"text\", \"image\"] }))),\n\t\t),\n\t\tallowedEfforts: Type.Optional(\n\t\t\tType.Array(\n\t\t\t\tType.Union([\n\t\t\t\t\tType.String({ enum: [\"off\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\"] }),\n\t\t\t\t\tType.Null(),\n\t\t\t\t]),\n\t\t\t),\n\t\t),\n\t},\n\t{\n\t\tadditionalProperties: false,\n\t\tdescription:\n\t\t\t\"Hard constraints for auto selection and execution fallback. Applicable definition and call constraints must all hold; concrete model calls keep existing behavior.\",\n\t},\n);\nexport type ModelConstraints = Static<typeof ModelConstraintsSchema>;\nconst validator = Compile(ModelConstraintsSchema);\nexport function parseModelConstraints(value: unknown): ModelConstraints | undefined {\n\tif (value === undefined) return undefined;\n\tif (\n\t\t!validator.Check(value) ||\n\t\t[value.maxInputCost, value.maxOutputCost, value.minContextWindow].some(\n\t\t\t(n) => n !== undefined && !Number.isFinite(n),\n\t\t)\n\t) {\n\t\tthrow new Error(\"Invalid modelConstraints: use known fields and finite nonnegative numeric limits.\");\n\t}\n\treturn value;\n}\nexport type ModelRouterOutput = {\n\treadonly model: string;\n\treadonly effort: string | null;\n\t/** Ranked alternatives, excluding the primary. Absent on legacy recorded selections. */\n\treadonly fallbacks?: readonly { readonly model: string; readonly effort: string | null }[];\n};\n/** Whether a constraint sets its own provider list. */\nexport function setsProviders(constraints: ModelConstraints | undefined): boolean {\n\treturn constraints?.allowedProviders !== undefined || constraints?.excludedProviders !== undefined;\n}\n\n/** Every applicable declaration must hold; a caller never widens a definition restriction. */\nexport function eligiblePair(\n\tmodel: Model<Api>,\n\tpair: ModelRouterOutput,\n\tconstraints: readonly ModelConstraints[],\n): boolean {\n\treturn constraints.every(\n\t\t(c) =>\n\t\t\t(c.allowedModels === undefined || c.allowedModels.includes(pair.model)) &&\n\t\t\t(c.allowedProviders === undefined || c.allowedProviders.includes(model.provider)) &&\n\t\t\t!c.excludedProviders?.includes(model.provider) &&\n\t\t\t(c.allowedEfforts === undefined || c.allowedEfforts.some((e) => e === pair.effort)) &&\n\t\t\t(c.maxInputCost === undefined ||\n\t\t\t\t[model.cost, ...(model.cost.tiers ?? [])].every((rate) => rate.input <= c.maxInputCost!)) &&\n\t\t\t(c.maxOutputCost === undefined ||\n\t\t\t\t[model.cost, ...(model.cost.tiers ?? [])].every((rate) => rate.output <= c.maxOutputCost!)) &&\n\t\t\t(c.minContextWindow === undefined || model.contextWindow >= c.minContextWindow) &&\n\t\t\t(c.requiredInputs === undefined || c.requiredInputs.every((input) => model.input.includes(input))),\n\t);\n}\n"]}

package/dist/core/model-routing-debug.d.ts

@@ -0,0 +1,9 @@
+/** Set to `1` to print automatic model routing fallbacks and failures. */
+export declare const MODEL_ROUTING_DEBUG_ENV = "ATOMIC_MODEL_ROUTING_DEBUG";
+export declare function isModelRoutingDebugEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Routing fallbacks are recoverable and already recorded in routing metadata, so
+ * they stay out of the terminal and agent context unless routing debugging is on.
+ */
+export declare function reportModelRoutingDebug(message: string, env?: NodeJS.ProcessEnv): void;
+//# sourceMappingURL=model-routing-debug.d.ts.map

package/dist/core/model-routing-debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-debug.d.ts","sourceRoot":"","sources":["../../src/core/model-routing-debug.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAEpE,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAExF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAEnG"}

package/dist/core/model-routing-debug.js

@@ -0,0 +1,14 @@
+/** Set to `1` to print automatic model routing fallbacks and failures. */
+export const MODEL_ROUTING_DEBUG_ENV = "ATOMIC_MODEL_ROUTING_DEBUG";
+export function isModelRoutingDebugEnabled(env = process.env) {
+    return env[MODEL_ROUTING_DEBUG_ENV] === "1";
+}
+/**
+ * Routing fallbacks are recoverable and already recorded in routing metadata, so
+ * they stay out of the terminal and agent context unless routing debugging is on.
+ */
+export function reportModelRoutingDebug(message, env = process.env) {
+    if (isModelRoutingDebugEnabled(env))
+        console.warn(message);
+}
+//# sourceMappingURL=model-routing-debug.js.map

package/dist/core/model-routing-debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-debug.js","sourceRoot":"","sources":["../../src/core/model-routing-debug.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,CAAC,MAAM,uBAAuB,GAAG,4BAA4B,CAAC;AAEpE,MAAM,UAAU,0BAA0B,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC9E,OAAO,GAAG,CAAC,uBAAuB,CAAC,KAAK,GAAG,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC5F,IAAI,0BAA0B,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC","sourcesContent":["/** Set to `1` to print automatic model routing fallbacks and failures. */\nexport const MODEL_ROUTING_DEBUG_ENV = \"ATOMIC_MODEL_ROUTING_DEBUG\";\n\nexport function isModelRoutingDebugEnabled(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn env[MODEL_ROUTING_DEBUG_ENV] === \"1\";\n}\n\n/**\n * Routing fallbacks are recoverable and already recorded in routing metadata, so\n * they stay out of the terminal and agent context unless routing debugging is on.\n */\nexport function reportModelRoutingDebug(message: string, env: NodeJS.ProcessEnv = process.env): void {\n\tif (isModelRoutingDebugEnabled(env)) console.warn(message);\n}\n"]}

package/dist/core/model-routing-evals.d.ts

@@ -0,0 +1,50 @@
+/** Bounds the evaluation evidence sent with one routing request. */
+export declare const MODEL_SELECTION_EVALS_JSON_BYTES = 14200;
+/** Provider-independent model tokens: `us.anthropic.claude-opus-4-6-v1` and `anthropic/claude-opus-4.6` agree. */
+export declare function modelEvidenceTokens(id: string): string[];
+interface CatalogRow {
+    readonly line: string;
+    readonly section: number;
+    readonly order: number;
+    readonly tokens: readonly string[];
+    readonly releaseDate?: string;
+}
+/** One `## ` section of `evals.md` that holds a model table keyed by `slug`. */
+interface CatalogSection {
+    /** The section heading, its notes and key, the table header and separator. */
+    readonly intro: readonly string[];
+}
+/** `evals.md` parsed once so batch packing can query evidence per candidate cheaply. */
+export interface EvalsCatalog {
+    /** Text before the first table section: title, access date and the shared key. */
+    readonly preamble: readonly string[];
+    readonly sections: readonly CatalogSection[];
+    readonly rows: readonly CatalogRow[];
+    /** The unparsed document when it has no model table. */
+    readonly raw?: string;
+    readonly matches: Map<string, readonly CatalogRow[]>;
+}
+export declare function parseEvalsCatalog(evals: string): EvalsCatalog;
+/**
+ * Rows describing `candidate`: in each section, its own model and variants, or
+ * its base model when that section has none. Sections resolve independently, so
+ * an exact snapshot row in one table does not hide the base model's rows in another.
+ */
+export declare function candidateEvidenceRows(catalog: EvalsCatalog, candidate: string): readonly CatalogRow[];
+/** Latest release date among the candidate's evidence rows, when any row has one. */
+export declare function candidateReleaseDate(catalog: EvalsCatalog, candidate: string): string | undefined;
+/**
+ * The catalog preamble plus, for every section with rows for `candidates`, that
+ * section's heading, key and table header followed by only those rows.
+ * Sections without a matching row are left out. `maxBytes` bounds the
+ * JSON-encoded result; batched routing omits it because its request budget
+ * already decides how many candidates, and so how many rows, one batch holds.
+ */
+export declare function catalogEvidence(catalog: EvalsCatalog, candidates: readonly string[], maxBytes?: number): string;
+/**
+ * Keep the catalog preamble and only the table rows that describe an eligible
+ * candidate model, bounded to the routing evidence budget.
+ */
+export declare function filterModelSelectionEvals(evals: string, candidates: readonly string[]): string;
+export {};
+//# sourceMappingURL=model-routing-evals.d.ts.map

package/dist/core/model-routing-evals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-evals.d.ts","sourceRoot":"","sources":["../../src/core/model-routing-evals.ts"],"names":[],"mappings":"AAEA,oEAAoE;AACpE,eAAO,MAAM,gCAAgC,QAAS,CAAC;AA2CvD,kHAAkH;AAClH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAexD;AA6BD,UAAU,UAAU;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gFAAgF;AAChF,UAAU,cAAc;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IACrC,wDAAwD;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC;CACrD;AAID,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAmC7D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,UAAU,EAAE,CAcrG;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjG;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,QAAQ,SAA2B,GACjC,MAAM,CAeR;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE9F"}

package/dist/core/model-routing-evals.js

@@ -0,0 +1,190 @@
+import { jsonBytes, truncateToBytes } from "./model-routing-bytes.js";
+/** Bounds the evaluation evidence sent with one routing request. */
+export const MODEL_SELECTION_EVALS_JSON_BYTES = 14_200;
+const VENDOR_OR_REGION_PREFIX = /^(?:[a-z][a-z-]*\.)+/u;
+const SNAPSHOT_TOKEN = /^\d{4}$/u;
+const DEPLOYMENT_TOKENS = new Set([
+    "fast",
+    "highspeed",
+    "ultraspeed",
+    "lightning",
+    "beta",
+    "exp",
+    "free",
+    "it",
+    "instruct",
+    "contributor",
+]);
+const ROW_EDITION_TOKENS = new Set(["preview", "instruct", "it"]);
+const VARIANT_TOKENS = new Set([
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+    "adaptive",
+    "thinking",
+    "reasoning",
+    "non",
+    "effort",
+    "preview",
+]);
+const CLAUDE_FAMILIES = new Set(["opus", "sonnet", "haiku", "fable"]);
+/** Artificial Analysis names older Claude models `claude-4-5-sonnet`; catalogs use `claude-sonnet-4-5`. */
+function canonicalClaudeOrder(tokens) {
+    if (tokens[0] !== "claude" || !CLAUDE_FAMILIES.has(tokens[1] ?? ""))
+        return tokens;
+    const versionEnd = tokens.findIndex((token, index) => index > 1 && !/^\d+$/u.test(token));
+    const end = versionEnd < 0 ? tokens.length : versionEnd;
+    if (end === 2)
+        return tokens;
+    return ["claude", ...tokens.slice(2, end), tokens[1], ...tokens.slice(end)];
+}
+/** Provider-independent model tokens: `us.anthropic.claude-opus-4-6-v1` and `anthropic/claude-opus-4.6` agree. */
+export function modelEvidenceTokens(id) {
+    const normalized = id.trim().toLowerCase();
+    const model = normalized
+        .slice(normalized.lastIndexOf("/") + 1)
+        .replace(/^~/u, "")
+        .replace(VENDOR_OR_REGION_PREFIX, "")
+        .replace(/(?<=[a-z])-\d+:\d+$/u, "")
+        .replace(/:[a-z0-9]+$/u, "")
+        .replace(/-v\d+$/u, "")
+        .replace(/-\d{8}$/u, "");
+    const tokens = model
+        .split(/[-._]/u)
+        .filter(Boolean)
+        .map((token) => (token === "thinking" ? "reasoning" : token));
+    return canonicalClaudeOrder(tokens);
+}
+/** True when `slug` is the candidate model or one of its effort, edition or snapshot variants. */
+function slugMatchesCandidate(slug, candidate) {
+    if (slug.length < candidate.length || candidate.some((token, index) => slug[index] !== token))
+        return false;
+    return slug
+        .slice(candidate.length)
+        .every((token) => VARIANT_TOKENS.has(token) || ROW_EDITION_TOKENS.has(token) || SNAPSHOT_TOKEN.test(token));
+}
+/**
+ * The candidate's own tokens first, then the same model without trailing
+ * deployment, reasoning-mode or snapshot suffixes (`gpt-5.4-fast`,
+ * `grok-4.20-reasoning`, `qwen3.8-max-0902`). A fallback applies only when the
+ * more specific form matched no row, so a model that is itself named `-fast`
+ * keeps its own evidence.
+ */
+function candidateForms(tokens) {
+    const forms = [[...tokens]];
+    let current = [...tokens];
+    while (current.length > 1) {
+        const last = current[current.length - 1];
+        if (!DEPLOYMENT_TOKENS.has(last) && !VARIANT_TOKENS.has(last) && !SNAPSHOT_TOKEN.test(last))
+            break;
+        current = current.slice(0, -1);
+        forms.push(current);
+    }
+    return forms;
+}
+const TABLE_HEADER = /^\|\s*slug\s*\|/u;
+export function parseEvalsCatalog(evals) {
+    const lines = evals.split("\n");
+    const headers = lines.flatMap((line, index) => (TABLE_HEADER.test(line) ? [index] : []));
+    if (headers.length === 0)
+        return { preamble: [], sections: [], rows: [], raw: evals, matches: new Map() };
+    const sections = [];
+    const rows = [];
+    let preambleEnd = 0;
+    let previousTableEnd = 0;
+    for (const [section, headerIndex] of headers.entries()) {
+        let start = headerIndex;
+        for (let index = headerIndex - 1; index >= previousTableEnd; index--)
+            if (lines[index].startsWith("## ")) {
+                start = index;
+                break;
+            }
+        if (section === 0)
+            preambleEnd = start;
+        sections.push({ intro: lines.slice(start, headerIndex + 2) });
+        const header = lines[headerIndex].split("|").map((cell) => cell.trim());
+        const releaseColumn = header.indexOf("Release date");
+        let index = headerIndex + 2;
+        for (; index < lines.length && lines[index].startsWith("|"); index++) {
+            const cells = lines[index].split("|").map((cell) => cell.trim());
+            if (!cells[1])
+                continue;
+            const release = releaseColumn > 0 ? cells[releaseColumn] : undefined;
+            rows.push({
+                line: lines[index],
+                section,
+                order: rows.length,
+                tokens: modelEvidenceTokens(cells[1]),
+                ...(release && /^\d{4}-\d{2}-\d{2}$/u.test(release) ? { releaseDate: release } : {}),
+            });
+        }
+        previousTableEnd = index;
+    }
+    return { preamble: lines.slice(0, preambleEnd), sections, rows, matches: new Map() };
+}
+/**
+ * Rows describing `candidate`: in each section, its own model and variants, or
+ * its base model when that section has none. Sections resolve independently, so
+ * an exact snapshot row in one table does not hide the base model's rows in another.
+ */
+export function candidateEvidenceRows(catalog, candidate) {
+    const cached = catalog.matches.get(candidate);
+    if (cached)
+        return cached;
+    const forms = candidateForms(modelEvidenceTokens(candidate));
+    const matches = catalog.sections.flatMap((_, section) => {
+        const sectionRows = catalog.rows.filter((row) => row.section === section);
+        for (const form of forms) {
+            const found = sectionRows.filter((row) => slugMatchesCandidate(row.tokens, form));
+            if (found.length > 0)
+                return found;
+        }
+        return [];
+    });
+    catalog.matches.set(candidate, matches);
+    return matches;
+}
+/** Latest release date among the candidate's evidence rows, when any row has one. */
+export function candidateReleaseDate(catalog, candidate) {
+    const dates = candidateEvidenceRows(catalog, candidate).flatMap((row) => (row.releaseDate ? [row.releaseDate] : []));
+    return dates.length ? dates.sort().at(-1) : undefined;
+}
+/**
+ * The catalog preamble plus, for every section with rows for `candidates`, that
+ * section's heading, key and table header followed by only those rows.
+ * Sections without a matching row are left out. `maxBytes` bounds the
+ * JSON-encoded result; batched routing omits it because its request budget
+ * already decides how many candidates, and so how many rows, one batch holds.
+ */
+export function catalogEvidence(catalog, candidates, maxBytes = Number.POSITIVE_INFINITY) {
+    if (catalog.raw !== undefined)
+        return truncateToBytes(catalog.raw, maxBytes);
+    const selected = new Set();
+    for (const candidate of new Set(candidates))
+        for (const row of candidateEvidenceRows(catalog, candidate))
+            selected.add(row.order);
+    const kept = catalog.rows.filter((row) => selected.has(row.order));
+    const parts = [...catalog.preamble];
+    for (const [index, section] of catalog.sections.entries()) {
+        const sectionRows = kept.filter((row) => row.section === index);
+        if (index > 0 && sectionRows.length === 0)
+            continue;
+        if (index > 0 && parts.at(-1) !== "")
+            parts.push("");
+        parts.push(...section.intro, ...sectionRows.map((row) => row.line));
+    }
+    const filtered = parts.join("\n");
+    return jsonBytes(filtered) <= maxBytes ? filtered : truncateToBytes(filtered, maxBytes);
+}
+/**
+ * Keep the catalog preamble and only the table rows that describe an eligible
+ * candidate model, bounded to the routing evidence budget.
+ */
+export function filterModelSelectionEvals(evals, candidates) {
+    return catalogEvidence(parseEvalsCatalog(evals), candidates, MODEL_SELECTION_EVALS_JSON_BYTES);
+}
+//# sourceMappingURL=model-routing-evals.js.map

package/dist/core/model-routing-evals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-evals.js","sourceRoot":"","sources":["../../src/core/model-routing-evals.ts"],"names":[],"mappings":"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","sourcesContent":["import { jsonBytes, truncateToBytes } from \"./model-routing-bytes.js\";\n\n/** Bounds the evaluation evidence sent with one routing request. */\nexport const MODEL_SELECTION_EVALS_JSON_BYTES = 14_200;\n\nconst VENDOR_OR_REGION_PREFIX = /^(?:[a-z][a-z-]*\\.)+/u;\nconst SNAPSHOT_TOKEN = /^\\d{4}$/u;\nconst DEPLOYMENT_TOKENS = new Set([\n\t\"fast\",\n\t\"highspeed\",\n\t\"ultraspeed\",\n\t\"lightning\",\n\t\"beta\",\n\t\"exp\",\n\t\"free\",\n\t\"it\",\n\t\"instruct\",\n\t\"contributor\",\n]);\nconst ROW_EDITION_TOKENS = new Set([\"preview\", \"instruct\", \"it\"]);\nconst VARIANT_TOKENS = new Set([\n\t\"off\",\n\t\"minimal\",\n\t\"low\",\n\t\"medium\",\n\t\"high\",\n\t\"xhigh\",\n\t\"max\",\n\t\"adaptive\",\n\t\"thinking\",\n\t\"reasoning\",\n\t\"non\",\n\t\"effort\",\n\t\"preview\",\n]);\nconst CLAUDE_FAMILIES = new Set([\"opus\", \"sonnet\", \"haiku\", \"fable\"]);\n\n/** Artificial Analysis names older Claude models `claude-4-5-sonnet`; catalogs use `claude-sonnet-4-5`. */\nfunction canonicalClaudeOrder(tokens: string[]): string[] {\n\tif (tokens[0] !== \"claude\" || !CLAUDE_FAMILIES.has(tokens[1] ?? \"\")) return tokens;\n\tconst versionEnd = tokens.findIndex((token, index) => index > 1 && !/^\\d+$/u.test(token));\n\tconst end = versionEnd < 0 ? tokens.length : versionEnd;\n\tif (end === 2) return tokens;\n\treturn [\"claude\", ...tokens.slice(2, end), tokens[1]!, ...tokens.slice(end)];\n}\n\n/** Provider-independent model tokens: `us.anthropic.claude-opus-4-6-v1` and `anthropic/claude-opus-4.6` agree. */\nexport function modelEvidenceTokens(id: string): string[] {\n\tconst normalized = id.trim().toLowerCase();\n\tconst model = normalized\n\t\t.slice(normalized.lastIndexOf(\"/\") + 1)\n\t\t.replace(/^~/u, \"\")\n\t\t.replace(VENDOR_OR_REGION_PREFIX, \"\")\n\t\t.replace(/(?<=[a-z])-\\d+:\\d+$/u, \"\")\n\t\t.replace(/:[a-z0-9]+$/u, \"\")\n\t\t.replace(/-v\\d+$/u, \"\")\n\t\t.replace(/-\\d{8}$/u, \"\");\n\tconst tokens = model\n\t\t.split(/[-._]/u)\n\t\t.filter(Boolean)\n\t\t.map((token) => (token === \"thinking\" ? \"reasoning\" : token));\n\treturn canonicalClaudeOrder(tokens);\n}\n\n/** True when `slug` is the candidate model or one of its effort, edition or snapshot variants. */\nfunction slugMatchesCandidate(slug: readonly string[], candidate: readonly string[]): boolean {\n\tif (slug.length < candidate.length || candidate.some((token, index) => slug[index] !== token)) return false;\n\treturn slug\n\t\t.slice(candidate.length)\n\t\t.every((token) => VARIANT_TOKENS.has(token) || ROW_EDITION_TOKENS.has(token) || SNAPSHOT_TOKEN.test(token));\n}\n\n/**\n * The candidate's own tokens first, then the same model without trailing\n * deployment, reasoning-mode or snapshot suffixes (`gpt-5.4-fast`,\n * `grok-4.20-reasoning`, `qwen3.8-max-0902`). A fallback applies only when the\n * more specific form matched no row, so a model that is itself named `-fast`\n * keeps its own evidence.\n */\nfunction candidateForms(tokens: readonly string[]): string[][] {\n\tconst forms = [[...tokens]];\n\tlet current = [...tokens];\n\twhile (current.length > 1) {\n\t\tconst last = current[current.length - 1]!;\n\t\tif (!DEPLOYMENT_TOKENS.has(last) && !VARIANT_TOKENS.has(last) && !SNAPSHOT_TOKEN.test(last)) break;\n\t\tcurrent = current.slice(0, -1);\n\t\tforms.push(current);\n\t}\n\treturn forms;\n}\n\ninterface CatalogRow {\n\treadonly line: string;\n\treadonly section: number;\n\treadonly order: number;\n\treadonly tokens: readonly string[];\n\treadonly releaseDate?: string;\n}\n\n/** One `## ` section of `evals.md` that holds a model table keyed by `slug`. */\ninterface CatalogSection {\n\t/** The section heading, its notes and key, the table header and separator. */\n\treadonly intro: readonly string[];\n}\n\n/** `evals.md` parsed once so batch packing can query evidence per candidate cheaply. */\nexport interface EvalsCatalog {\n\t/** Text before the first table section: title, access date and the shared key. */\n\treadonly preamble: readonly string[];\n\treadonly sections: readonly CatalogSection[];\n\treadonly rows: readonly CatalogRow[];\n\t/** The unparsed document when it has no model table. */\n\treadonly raw?: string;\n\treadonly matches: Map<string, readonly CatalogRow[]>;\n}\n\nconst TABLE_HEADER = /^\\|\\s*slug\\s*\\|/u;\n\nexport function parseEvalsCatalog(evals: string): EvalsCatalog {\n\tconst lines = evals.split(\"\\n\");\n\tconst headers = lines.flatMap((line, index) => (TABLE_HEADER.test(line) ? [index] : []));\n\tif (headers.length === 0) return { preamble: [], sections: [], rows: [], raw: evals, matches: new Map() };\n\tconst sections: CatalogSection[] = [];\n\tconst rows: CatalogRow[] = [];\n\tlet preambleEnd = 0;\n\tlet previousTableEnd = 0;\n\tfor (const [section, headerIndex] of headers.entries()) {\n\t\tlet start = headerIndex;\n\t\tfor (let index = headerIndex - 1; index >= previousTableEnd; index--)\n\t\t\tif (lines[index]!.startsWith(\"## \")) {\n\t\t\t\tstart = index;\n\t\t\t\tbreak;\n\t\t\t}\n\t\tif (section === 0) preambleEnd = start;\n\t\tsections.push({ intro: lines.slice(start, headerIndex + 2) });\n\t\tconst header = lines[headerIndex]!.split(\"|\").map((cell) => cell.trim());\n\t\tconst releaseColumn = header.indexOf(\"Release date\");\n\t\tlet index = headerIndex + 2;\n\t\tfor (; index < lines.length && lines[index]!.startsWith(\"|\"); index++) {\n\t\t\tconst cells = lines[index]!.split(\"|\").map((cell) => cell.trim());\n\t\t\tif (!cells[1]) continue;\n\t\t\tconst release = releaseColumn > 0 ? cells[releaseColumn] : undefined;\n\t\t\trows.push({\n\t\t\t\tline: lines[index]!,\n\t\t\t\tsection,\n\t\t\t\torder: rows.length,\n\t\t\t\ttokens: modelEvidenceTokens(cells[1]),\n\t\t\t\t...(release && /^\\d{4}-\\d{2}-\\d{2}$/u.test(release) ? { releaseDate: release } : {}),\n\t\t\t});\n\t\t}\n\t\tpreviousTableEnd = index;\n\t}\n\treturn { preamble: lines.slice(0, preambleEnd), sections, rows, matches: new Map() };\n}\n\n/**\n * Rows describing `candidate`: in each section, its own model and variants, or\n * its base model when that section has none. Sections resolve independently, so\n * an exact snapshot row in one table does not hide the base model's rows in another.\n */\nexport function candidateEvidenceRows(catalog: EvalsCatalog, candidate: string): readonly CatalogRow[] {\n\tconst cached = catalog.matches.get(candidate);\n\tif (cached) return cached;\n\tconst forms = candidateForms(modelEvidenceTokens(candidate));\n\tconst matches = catalog.sections.flatMap((_, section) => {\n\t\tconst sectionRows = catalog.rows.filter((row) => row.section === section);\n\t\tfor (const form of forms) {\n\t\t\tconst found = sectionRows.filter((row) => slugMatchesCandidate(row.tokens, form));\n\t\t\tif (found.length > 0) return found;\n\t\t}\n\t\treturn [];\n\t});\n\tcatalog.matches.set(candidate, matches);\n\treturn matches;\n}\n\n/** Latest release date among the candidate's evidence rows, when any row has one. */\nexport function candidateReleaseDate(catalog: EvalsCatalog, candidate: string): string | undefined {\n\tconst dates = candidateEvidenceRows(catalog, candidate).flatMap((row) => (row.releaseDate ? [row.releaseDate] : []));\n\treturn dates.length ? dates.sort().at(-1) : undefined;\n}\n\n/**\n * The catalog preamble plus, for every section with rows for `candidates`, that\n * section's heading, key and table header followed by only those rows.\n * Sections without a matching row are left out. `maxBytes` bounds the\n * JSON-encoded result; batched routing omits it because its request budget\n * already decides how many candidates, and so how many rows, one batch holds.\n */\nexport function catalogEvidence(\n\tcatalog: EvalsCatalog,\n\tcandidates: readonly string[],\n\tmaxBytes = Number.POSITIVE_INFINITY,\n): string {\n\tif (catalog.raw !== undefined) return truncateToBytes(catalog.raw, maxBytes);\n\tconst selected = new Set<number>();\n\tfor (const candidate of new Set(candidates))\n\t\tfor (const row of candidateEvidenceRows(catalog, candidate)) selected.add(row.order);\n\tconst kept = catalog.rows.filter((row) => selected.has(row.order));\n\tconst parts = [...catalog.preamble];\n\tfor (const [index, section] of catalog.sections.entries()) {\n\t\tconst sectionRows = kept.filter((row) => row.section === index);\n\t\tif (index > 0 && sectionRows.length === 0) continue;\n\t\tif (index > 0 && parts.at(-1) !== \"\") parts.push(\"\");\n\t\tparts.push(...section.intro, ...sectionRows.map((row) => row.line));\n\t}\n\tconst filtered = parts.join(\"\\n\");\n\treturn jsonBytes(filtered) <= maxBytes ? filtered : truncateToBytes(filtered, maxBytes);\n}\n\n/**\n * Keep the catalog preamble and only the table rows that describe an eligible\n * candidate model, bounded to the routing evidence budget.\n */\nexport function filterModelSelectionEvals(evals: string, candidates: readonly string[]): string {\n\treturn catalogEvidence(parseEvalsCatalog(evals), candidates, MODEL_SELECTION_EVALS_JSON_BYTES);\n}\n"]}

package/dist/core/model-routing-needs.d.ts

@@ -0,0 +1,75 @@
+import { Type } from "typebox";
+/** Kinds of work a routed task can be, each described for the router in plain words. */
+export declare const WORK_KINDS: {
+    readonly computer_use: "Operating desktop or mobile apps through screenshots, clicks and typing";
+    readonly coding: "Writing, changing or debugging code in a repository";
+    readonly code_review: "Reviewing code or systems for defects or security problems";
+    readonly codebase_lookup: "Finding files, definitions or facts in a codebase without changing anything";
+    readonly research: "Reading documents or the web and summarizing findings";
+    readonly business_workflow: "Multi-step work across business tools or APIs";
+    readonly math_science: "Math, physics or scientific computation";
+    readonly writing: "Writing or editing prose, documents or slides";
+};
+export declare const DIFFICULTY_LEVELS: {
+    readonly trivial: "One obvious step";
+    readonly easy: "A few simple steps";
+    readonly moderate: "Several steps with some judgment";
+    readonly hard: "Many dependent steps, debugging or verification";
+    readonly very_hard: "Long work across many tools with frequent recovery";
+};
+export declare const MISTAKE_COST_LEVELS: {
+    readonly negligible: "Easily noticed and redone";
+    readonly low: "Minor rework";
+    readonly moderate: "Wasted time or a confusing result";
+    readonly high: "Broken builds, bad data or wrong conclusions";
+    readonly severe: "Security, money, data loss or production impact";
+};
+export type WorkKind = keyof typeof WORK_KINDS;
+export type Difficulty = keyof typeof DIFFICULTY_LEVELS;
+export type MistakeCost = keyof typeof MISTAKE_COST_LEVELS;
+/** What a caller may state about a task so routing need not infer it. Every field is optional. */
+export interface TaskNeeds {
+    readonly work?: WorkKind;
+    readonly difficulty?: Difficulty;
+    readonly mistakeCost?: MistakeCost;
+    readonly needsImages?: boolean;
+    readonly longContext?: boolean;
+    readonly latencySensitive?: boolean;
+}
+export type ResolvedTaskNeeds = Required<TaskNeeds>;
+/** Tool and stage schema for caller-stated task needs. */
+export declare const TaskNeedsSchema: Type.TObject<{
+    work: Type.TOptional<Type.TUnsafe<"business_workflow" | "code_review" | "codebase_lookup" | "coding" | "computer_use" | "math_science" | "research" | "writing">>;
+    difficulty: Type.TOptional<Type.TUnsafe<"easy" | "hard" | "moderate" | "trivial" | "very_hard">>;
+    mistakeCost: Type.TOptional<Type.TUnsafe<"high" | "low" | "moderate" | "negligible" | "severe">>;
+    needsImages: Type.TOptional<Type.TBoolean>;
+    longContext: Type.TOptional<Type.TBoolean>;
+    latencySensitive: Type.TOptional<Type.TBoolean>;
+}>;
+/** Validate caller-stated needs. Unknown keys and values fail rather than being guessed. */
+export declare function parseTaskNeeds(value: unknown): TaskNeeds | undefined;
+/** Later stated needs win field by field (for example a call over an agent default). */
+export declare function mergeTaskNeeds(...needs: readonly (TaskNeeds | undefined)[]): TaskNeeds | undefined;
+export interface NeedsQuestion {
+    readonly id: "work" | "difficulty" | "mistake_cost" | "needs_images" | "long_context" | "latency_sensitive";
+    readonly instructions: string;
+    readonly criteria: Record<string, string>;
+}
+/** Questions for only the needs the caller did not state, in a fixed order. */
+export declare function missingNeedsQuestions(stated: TaskNeeds | undefined): NeedsQuestion[];
+/**
+ * Combine stated needs with the router's answers keyed by question id. Computer
+ * use always works from screenshots, so it needs image input unless the caller
+ * explicitly said otherwise.
+ */
+export declare function resolveTaskNeeds(stated: TaskNeeds | undefined, answers: Record<string, string>): ResolvedTaskNeeds;
+/** 0 for the easiest or cheapest-to-get-wrong task, 1 for the hardest or costliest. */
+export declare function taskDemand(needs: ResolvedTaskNeeds): number;
+/**
+ * Effort for a model from the task's difficulty, one level lower (never below
+ * `minimal`) when speed matters: the supported level closest to the target,
+ * preferring the lower one on a tie. `null` for models without
+ * configurable reasoning.
+ */
+export declare function effortForDifficulty(efforts: readonly (string | null)[], difficulty: Difficulty, latencySensitive?: boolean): string | null;
+//# sourceMappingURL=model-routing-needs.d.ts.map

package/dist/core/model-routing-needs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-needs.d.ts","sourceRoot":"","sources":["../../src/core/model-routing-needs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,wFAAwF;AACxF,eAAO,MAAM,UAAU;aACtB,YAAY,EAAE,yEAAyE;aACvF,MAAM,EAAE,qDAAqD;aAC7D,WAAW,EAAE,4DAA4D;aACzE,eAAe,EAAE,6EAA6E;aAC9F,QAAQ,EAAE,uDAAuD;aACjE,iBAAiB,EAAE,+CAA+C;aAClE,YAAY,EAAE,yCAAyC;aACvD,OAAO,EAAE,+CAA+C;CAC/C,CAAC;AAEX,eAAO,MAAM,iBAAiB;aAC7B,OAAO,EAAE,kBAAkB;aAC3B,IAAI,EAAE,oBAAoB;aAC1B,QAAQ,EAAE,kCAAkC;aAC5C,IAAI,EAAE,iDAAiD;aACvD,SAAS,EAAE,oDAAoD;CACtD,CAAC;AAEX,eAAO,MAAM,mBAAmB;aAC/B,UAAU,EAAE,2BAA2B;aACvC,GAAG,EAAE,cAAc;aACnB,QAAQ,EAAE,mCAAmC;aAC7C,IAAI,EAAE,8CAA8C;aACpD,MAAM,EAAE,iDAAiD;CAChD,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAC/C,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,iBAAiB,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE3D,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAKpD,0DAA0D;AAC1D,eAAO,MAAM,eAAe;;;;;;;EAoB3B,CAAC;AAcF,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAyBpE;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,GAAG,KAAK,EAAE,SAAS,CAAC,SAAS,GAAG,SAAS,CAAC,EAAE,GAAG,SAAS,GAAG,SAAS,CAGlG;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,GAAG,cAAc,GAAG,mBAAmB,CAAC;IAC5G,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,aAAa,EAAE,CAgDpF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,iBAAiB,CAYlH;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAI3D;AAWD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EACnC,UAAU,EAAE,UAAU,EACtB,gBAAgB,UAAQ,GACtB,MAAM,GAAG,IAAI,CASf"}

package/dist/core/model-routing-needs.js

@@ -0,0 +1,176 @@
+import { Type } from "typebox";
+/** Kinds of work a routed task can be, each described for the router in plain words. */
+export const WORK_KINDS = {
+    computer_use: "Operating desktop or mobile apps through screenshots, clicks and typing",
+    coding: "Writing, changing or debugging code in a repository",
+    code_review: "Reviewing code or systems for defects or security problems",
+    codebase_lookup: "Finding files, definitions or facts in a codebase without changing anything",
+    research: "Reading documents or the web and summarizing findings",
+    business_workflow: "Multi-step work across business tools or APIs",
+    math_science: "Math, physics or scientific computation",
+    writing: "Writing or editing prose, documents or slides",
+};
+export const DIFFICULTY_LEVELS = {
+    trivial: "One obvious step",
+    easy: "A few simple steps",
+    moderate: "Several steps with some judgment",
+    hard: "Many dependent steps, debugging or verification",
+    very_hard: "Long work across many tools with frequent recovery",
+};
+export const MISTAKE_COST_LEVELS = {
+    negligible: "Easily noticed and redone",
+    low: "Minor rework",
+    moderate: "Wasted time or a confusing result",
+    high: "Broken builds, bad data or wrong conclusions",
+    severe: "Security, money, data loss or production impact",
+};
+const enumOf = (values, description) => Type.Unsafe(Type.String({ enum: Object.keys(values), description }));
+/** Tool and stage schema for caller-stated task needs. */
+export const TaskNeedsSchema = Type.Object({
+    work: Type.Optional(enumOf(WORK_KINDS, `Main kind of work: ${Object.keys(WORK_KINDS).join(", ")}.`)),
+    difficulty: Type.Optional(enumOf(DIFFICULTY_LEVELS, "How hard the task is for a capable agent.")),
+    mistakeCost: Type.Optional(enumOf(MISTAKE_COST_LEVELS, "How bad a wrong result would be.")),
+    needsImages: Type.Optional(Type.Boolean({ description: "Whether the agent must read screenshots or images." })),
+    longContext: Type.Optional(Type.Boolean({ description: "Whether the agent must hold a very large codebase or document set in context." })),
+    latencySensitive: Type.Optional(Type.Boolean({
+        description: "Whether a fast answer matters more than extra reasoning, for example quick lookups.",
+    })),
+}, {
+    additionalProperties: false,
+    description: "For model 'auto': what you know about the task. Fill in every field you can judge; routing uses these answers instead of reading the task, and a language model reads the task only for omitted fields.",
+});
+const WORK_KEYS = Object.keys(WORK_KINDS);
+const DIFFICULTY_KEYS = Object.keys(DIFFICULTY_LEVELS);
+const MISTAKE_COST_KEYS = Object.keys(MISTAKE_COST_LEVELS);
+const CHOICE_FIELDS = ["work", "difficulty", "mistakeCost"];
+const BOOLEAN_FIELDS = ["needsImages", "longContext", "latencySensitive"];
+const oneOf = (keys, value, field) => {
+    if (typeof value === "string" && keys.includes(value))
+        return value;
+    throw new Error(`Invalid taskNeeds.${field}: expected one of ${keys.join(", ")}.`);
+};
+/** Validate caller-stated needs. Unknown keys and values fail rather than being guessed. */
+export function parseTaskNeeds(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid taskNeeds: expected an object with work, difficulty, mistakeCost, needsImages, longContext or latencySensitive.");
+    const record = value;
+    for (const key of Object.keys(record))
+        if (![...CHOICE_FIELDS, ...BOOLEAN_FIELDS].includes(key))
+            throw new Error(`Invalid taskNeeds: unknown field ${key}.`);
+    for (const field of BOOLEAN_FIELDS)
+        if (record[field] !== undefined && typeof record[field] !== "boolean")
+            throw new Error(`Invalid taskNeeds.${field}: expected true or false.`);
+    return {
+        ...(record.work !== undefined ? { work: oneOf(WORK_KEYS, record.work, "work") } : {}),
+        ...(record.difficulty !== undefined
+            ? { difficulty: oneOf(DIFFICULTY_KEYS, record.difficulty, "difficulty") }
+            : {}),
+        ...(record.mistakeCost !== undefined
+            ? { mistakeCost: oneOf(MISTAKE_COST_KEYS, record.mistakeCost, "mistakeCost") }
+            : {}),
+        ...Object.fromEntries(BOOLEAN_FIELDS.flatMap((field) => (record[field] === undefined ? [] : [[field, record[field]]]))),
+    };
+}
+/** Later stated needs win field by field (for example a call over an agent default). */
+export function mergeTaskNeeds(...needs) {
+    const merged = Object.assign({}, ...needs.filter((entry) => entry !== undefined));
+    return Object.keys(merged).length ? merged : undefined;
+}
+/** Questions for only the needs the caller did not state, in a fixed order. */
+export function missingNeedsQuestions(stated) {
+    const questions = [];
+    if (!stated?.work)
+        questions.push({
+            id: "work",
+            instructions: "What kind of work is this task mainly?",
+            criteria: { ...WORK_KINDS },
+        });
+    if (!stated?.difficulty)
+        questions.push({
+            id: "difficulty",
+            instructions: "How hard is this task for a capable AI agent to complete correctly?",
+            criteria: { ...DIFFICULTY_LEVELS },
+        });
+    if (!stated?.mistakeCost)
+        questions.push({
+            id: "mistake_cost",
+            instructions: "How bad is it if the agent gets this task wrong?",
+            criteria: { ...MISTAKE_COST_LEVELS },
+        });
+    if (stated?.needsImages === undefined)
+        questions.push({
+            id: "needs_images",
+            instructions: "Does doing this task require the agent to look at screenshots or images?",
+            criteria: {
+                yes: "The agent must read screenshots, images or a GUI",
+                no: "Text and tool output are enough",
+            },
+        });
+    if (stated?.longContext === undefined)
+        questions.push({
+            id: "long_context",
+            instructions: "Must the agent hold a very large codebase, log or document set in context at once?",
+            criteria: {
+                yes: "Hundreds of thousands of tokens of material at once",
+                no: "Ordinary amounts, read piece by piece",
+            },
+        });
+    if (stated?.latencySensitive === undefined)
+        questions.push({
+            id: "latency_sensitive",
+            instructions: "Does a fast answer matter more than extra reasoning?",
+            criteria: {
+                yes: "Speed matters: a quick lookup, an interactive step or many small calls",
+                no: "Quality matters more than speed",
+            },
+        });
+    return questions;
+}
+/**
+ * Combine stated needs with the router's answers keyed by question id. Computer
+ * use always works from screenshots, so it needs image input unless the caller
+ * explicitly said otherwise.
+ */
+export function resolveTaskNeeds(stated, answers) {
+    const work = stated?.work ?? oneOf(WORK_KEYS, answers.work, "work");
+    const yes = (answer, field) => answer !== undefined && oneOf(["yes", "no"], answer, field) === "yes";
+    return {
+        work,
+        difficulty: stated?.difficulty ?? oneOf(DIFFICULTY_KEYS, answers.difficulty, "difficulty"),
+        mistakeCost: stated?.mistakeCost ?? oneOf(MISTAKE_COST_KEYS, answers.mistake_cost, "mistakeCost"),
+        needsImages: stated?.needsImages ?? (work === "computer_use" || yes(answers.needs_images, "needsImages")),
+        longContext: stated?.longContext ?? yes(answers.long_context, "longContext"),
+        latencySensitive: stated?.latencySensitive ?? yes(answers.latency_sensitive, "latencySensitive"),
+    };
+}
+/** 0 for the easiest or cheapest-to-get-wrong task, 1 for the hardest or costliest. */
+export function taskDemand(needs) {
+    const difficulty = DIFFICULTY_KEYS.indexOf(needs.difficulty) / (DIFFICULTY_KEYS.length - 1);
+    const mistake = MISTAKE_COST_KEYS.indexOf(needs.mistakeCost) / (MISTAKE_COST_KEYS.length - 1);
+    return Math.max(difficulty, mistake);
+}
+const EFFORT_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+const EFFORT_FOR_DIFFICULTY = {
+    trivial: "minimal",
+    easy: "low",
+    moderate: "medium",
+    hard: "high",
+    very_hard: "xhigh",
+};
+/**
+ * Effort for a model from the task's difficulty, one level lower (never below
+ * `minimal`) when speed matters: the supported level closest to the target,
+ * preferring the lower one on a tie. `null` for models without
+ * configurable reasoning.
+ */
+export function effortForDifficulty(efforts, difficulty, latencySensitive = false) {
+    const supported = efforts.filter((effort) => effort !== null && EFFORT_ORDER.includes(effort));
+    if (supported.length === 0)
+        return efforts.includes(null) ? null : (efforts[0] ?? null);
+    const target = Math.max(1, EFFORT_ORDER.indexOf(EFFORT_FOR_DIFFICULTY[difficulty]) - (latencySensitive ? 1 : 0));
+    return [...supported].sort((a, b) => Math.abs(EFFORT_ORDER.indexOf(a) - target) - Math.abs(EFFORT_ORDER.indexOf(b) - target) ||
+        EFFORT_ORDER.indexOf(a) - EFFORT_ORDER.indexOf(b))[0];
+}
+//# sourceMappingURL=model-routing-needs.js.map