openmerit 0.1.2 → 0.1.4

package/dist/diagnostics.js

@@ -0,0 +1,227 @@
+/** Read-only diagnostics plus a provider-free self-test for first-run support. */
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { LocalJsonlEventSink, meritEvent } from "./integrations.js";
+import { piExecutable, availablePiRoutes } from "./pi-trials.js";
+import { DEFAULT_POLICY, loadPolicy, providerAllowed } from "./policy.js";
+import { buildRecommendation } from "./recommend.js";
+import { applyRouteOverrides, modelRoute, routeCatalog, routeKey, routeLabel } from "./routes.js";
+import { validatePiProviderExtensions } from "./pi-config.js";
+import { appendJsonl, paths, readJsonReport, readJsonlReport, writeJson, } from "./store.js";
+function check(id, status, message, details) {
+    return { id, status, message, ...(details?.length ? { details } : {}) };
+}
+function packageSources(output) {
+    return [...new Set(output.split("\n").filter((line) => /^ {2}\S/.test(line)).map((line) => line.trim())
+            .filter((line) => /openmerit/i.test(line) && /^(npm:|git:|https?:|\.?\.?\/|\/)/.test(line)))];
+}
+function safePackageSource(source) {
+    if (source.startsWith("npm:/"))
+        return `npm:local/${basename(source)}`;
+    if (source.startsWith("/"))
+        return `local:${basename(source)}`;
+    return source;
+}
+/** No credentials, prompts, or trace contents are included in this report. */
+export function collectDoctorReport() {
+    const checks = [];
+    const executable = piExecutable();
+    const versionResult = spawnSync(executable, ["--version"], { encoding: "utf8" });
+    const piVersion = versionResult.status === 0 ? versionResult.stdout.trim() : null;
+    checks.push(piVersion
+        ? check("pi", "pass", `Pi detected (${piVersion})`)
+        : check("pi", "fail", "Pi is not executable"));
+    let policy = DEFAULT_POLICY;
+    try {
+        policy = loadPolicy(paths.policy());
+        checks.push(check("policy", "pass", `Policy is valid (v${policy.version}, ${policy.mode})`));
+    }
+    catch (error) {
+        checks.push(check("policy", "fail", `Policy is invalid: ${error.message}`));
+    }
+    const extensions = validatePiProviderExtensions(policy.pi.provider_extensions);
+    const safeExtensionErrors = extensions.errors.map((message) => {
+        const configured = policy.pi.provider_extensions.find((file) => message.startsWith(`${file}:`));
+        return configured ? message.replace(configured, `local:${basename(configured)}`) : message;
+    });
+    let isolatedExtensionRoutes = null;
+    let extensionLoadError = null;
+    if (!safeExtensionErrors.length && policy.pi.provider_extensions.length && piVersion) {
+        try {
+            isolatedExtensionRoutes = availablePiRoutes(undefined, extensions.valid);
+        }
+        catch {
+            extensionLoadError = "Pi could not load the allowlisted provider extensions in isolated mode";
+        }
+    }
+    checks.push(safeExtensionErrors.length || extensionLoadError
+        ? check("provider-extensions", "fail", "One or more allowlisted Pi provider extensions are unavailable", [...safeExtensionErrors, ...(extensionLoadError ? [extensionLoadError] : [])])
+        : check("provider-extensions", "pass", policy.pi.provider_extensions.length
+            ? `${policy.pi.provider_extensions.length} explicit Pi provider extension${policy.pi.provider_extensions.length === 1 ? " loads" : "s load"} in isolated mode`
+            : "No Pi provider extensions are allowlisted"));
+    const stateRead = readJsonReport(paths.harnessState(), {});
+    checks.push(!stateRead.valid
+        ? check("harness-state", "fail", "harness-state.json is malformed; start Pi to replace it atomically")
+        : stateRead.exists
+            ? check("harness-state", "pass", "Pi extension state snapshot is readable")
+            : check("harness-state", "warn", "No Pi extension state yet; start Pi once with OpenMerit installed"));
+    let routes = stateRead.value.routes ?? [];
+    const liveSnapshot = routes.length > 0;
+    if (!routes.length && piVersion) {
+        try {
+            routes = isolatedExtensionRoutes ?? availablePiRoutes(undefined, extensions.valid);
+        }
+        catch { /* the check below explains it */ }
+    }
+    routes = applyRouteOverrides(routes, policy.route_overrides);
+    const visibleRouteKeys = new Set(routes.map(routeKey));
+    routes = routes.filter((route) => providerAllowed(policy, route.meritId, route.provider));
+    const unusedOverrides = Object.keys(policy.route_overrides).filter((key) => !visibleRouteKeys.has(key));
+    checks.push(unusedOverrides.length
+        ? check("route-overrides", "warn", `${unusedOverrides.length} route metadata override${unusedOverrides.length === 1 ? " does" : "s do"} not match a visible route`, unusedOverrides)
+        : check("route-overrides", "pass", `${Object.keys(policy.route_overrides).length} route metadata override${Object.keys(policy.route_overrides).length === 1 ? "" : "s"} applied or ready`));
+    const priced = routes.filter((route) => !!route.cost);
+    checks.push(routes.length >= 2
+        ? check("routes", "pass", `${routes.length} Pi model routes are visible`, routes.slice(0, 8).map((route) => `${routeLabel(route)}${route.cost ? "" : " (price unknown)"}`))
+        : check("routes", "fail", `Only ${routes.length} policy-eligible Pi route${routes.length === 1 ? " is" : "s are"} visible; at least two are required`));
+    checks.push(liveSnapshot
+        ? priced.length >= 2
+            ? check("pricing", "pass", `${priced.length} eligible routes expose pricing`)
+            : check("pricing", "warn", "Fewer than two eligible routes expose pricing; unknown-price routes cannot auto-apply")
+        : check("pricing", "warn", "Route prices are unavailable until the extension reports a live Pi snapshot"));
+    const session = stateRead.value.sessionFile;
+    checks.push(!session
+        ? check("session", "warn", "No active saved Pi session is reported yet")
+        : existsSync(session)
+            ? check("session", "pass", "The reported Pi session file is readable")
+            : check("session", "warn", "The reported Pi session file no longer exists"));
+    if (piVersion) {
+        const listed = spawnSync(executable, ["list"], { encoding: "utf8" });
+        const sources = listed.status === 0 ? packageSources(listed.stdout) : [];
+        const safeSources = sources.map(safePackageSource);
+        checks.push(sources.length > 1
+            ? check("installation", "fail", "OpenMerit is installed from multiple Pi package sources", safeSources)
+            : sources.length === 1
+                ? check("installation", "pass", `One Pi package source is installed`, safeSources)
+                : check("installation", "warn", "OpenMerit is not listed as an installed Pi package; use `pi install npm:openmerit`"));
+    }
+    const jsonlFiles = [
+        ["recommendations.jsonl", paths.recommendations()],
+        ["trials.jsonl", paths.trials()],
+        ["traces/observations.jsonl", paths.observations()],
+        ["events.jsonl", paths.events()],
+    ];
+    const malformed = jsonlFiles.flatMap(([label, file]) => {
+        const invalid = readJsonlReport(file).invalidLines;
+        return invalid.length ? [`${label}: lines ${invalid.join(", ")}`] : [];
+    });
+    checks.push(malformed.length
+        ? check("jsonl", "warn", "Malformed JSONL lines were skipped; valid later records remain readable", malformed)
+        : check("jsonl", "pass", "Append-only JSONL state is readable"));
+    const ledger = readJsonReport(paths.ledger(), { date: "", trials: 0, usd: 0 });
+    checks.push(ledger.valid
+        ? check("ledger", "pass", "Trial-spend ledger is readable")
+        : check("ledger", "fail", "Trial-spend ledger is malformed; spending remains disabled until repaired"));
+    let openRouter = false;
+    try {
+        const env = process.env.OPENROUTER_API_KEY;
+        if (env?.trim())
+            openRouter = true;
+        else if (existsSync(paths.envFile()))
+            openRouter = /^\s*OPENROUTER_API_KEY\s*=\s*\S+/m
+                .test(readFileSync(paths.envFile(), "utf8"));
+    }
+    catch { /* optional */ }
+    checks.push(check("openrouter-enrichment", "pass", openRouter ? "Optional OpenRouter enrichment is configured" : "Optional OpenRouter enrichment is not configured"));
+    const activeRoute = stateRead.value.currentRoute ? routeLabel(stateRead.value.currentRoute) : null;
+    return {
+        schemaVersion: 1,
+        ok: !checks.some((item) => item.status === "fail"),
+        checks,
+        summary: { piVersion, routeCount: routes.length, pricedRouteCount: priced.length, activeRoute },
+    };
+}
+export function renderDiagnosticReport(report) {
+    const icon = { pass: "PASS", warn: "WARN", fail: "FAIL" };
+    return report.checks.flatMap((item) => [
+        `${icon[item.status].padEnd(4)} ${item.id.padEnd(22)} ${item.message}`,
+        ...(item.details ?? []).map((detail) => `       - ${detail}`),
+    ]).join("\n");
+}
+/** Exercise core state, routing, recommendation, and event paths without provider calls. */
+export function runOfflineVerify() {
+    const previousHome = process.env.OPENMERIT_HOME;
+    const root = mkdtempSync(join(tmpdir(), "openmerit-verify-"));
+    const checks = [];
+    try {
+        process.env.OPENMERIT_HOME = root;
+        const active = modelRoute("native", "model-a", {
+            input: ["text"], cost: { input: 1, output: 2 }, contextWindow: 8192, maxTokens: 4096,
+        });
+        const candidate = modelRoute("local", "model-b", {
+            input: ["text"], cost: { input: 0.2, output: 0.4 }, contextWindow: 8192, maxTokens: 4096,
+        });
+        writeJson(paths.harnessState(), { schemaVersion: 1, currentRoute: active, routes: [active, candidate] });
+        const state = readJsonReport(paths.harnessState(), {});
+        checks.push(state.valid && state.value.routes?.length === 2
+            ? check("atomic-json", "pass", "Atomic JSON state round-trip passed")
+            : check("atomic-json", "fail", "Atomic JSON state round-trip failed"));
+        const entries = routeCatalog([active, candidate]);
+        const point = (route, score) => {
+            const entry = entries.get(routeKey(route));
+            return { schemaVersion: 1, model: route.meritId, route, score, price: entry.price,
+                priceKnown: entry.priceKnown, ts: new Date().toISOString(), source: "pi_trial" };
+        };
+        const recommendation = buildRecommendation("verify-task", "offline verification", active.meritId, [point(active, 0.6), point(candidate, 0.9)], DEFAULT_POLICY, "/verify/session.jsonl", active);
+        checks.push(recommendation?.recommended.route?.provider === "local" &&
+            recommendation.policy.reasons.length > 0
+            ? check("provider-neutral", "pass", "Exact provider routes and policy reasons survive recommendation")
+            : check("provider-neutral", "fail", "Provider route or policy evidence was lost"));
+        const configured = applyRouteOverrides([modelRoute("custom", "model-c")], {
+            "custom:model-c": { cost: { input: 0, output: 0 }, context_window: 4096,
+                max_tokens: 1024, input: ["text"] },
+        })[0];
+        const providerExtension = join(root, "custom-provider.ts");
+        writeFileSync(providerExtension, "export default function provider() {}\n");
+        const extension = validatePiProviderExtensions([providerExtension]);
+        checks.push(configured.cost?.input === 0 && configured.contextWindow === 4096 && extension.valid.length === 1
+            ? check("custom-routes", "pass", "Exact route metadata and allowlisted provider extensions validate")
+            : check("custom-routes", "fail", "Custom route or provider-extension configuration failed"));
+        if (recommendation)
+            appendJsonl(paths.recommendations(), recommendation);
+        appendJsonl(paths.recommendations(), { schemaVersion: 0, id: "legacy", status: "dismissed" });
+        appendFileSync(paths.recommendations(), "{interrupted");
+        const history = readJsonlReport(paths.recommendations());
+        checks.push(history.records.length === 2 && history.invalidLines.length === 1
+            ? check("jsonl-recovery", "pass", "Valid records survive legacy and interrupted JSONL lines")
+            : check("jsonl-recovery", "fail", "JSONL recovery did not preserve valid history"));
+        const sink = new LocalJsonlEventSink();
+        if (recommendation)
+            sink.emit(meritEvent("recommendation.created", recommendation));
+        const events = readJsonlReport(paths.events());
+        checks.push(events.records.length === 1
+            ? check("events", "pass", "Versioned neutral event sink round-trip passed")
+            : check("events", "fail", "Neutral event sink round-trip failed"));
+        checks.push(loadPolicy(paths.policy()).mode === "recommend"
+            ? check("compatibility", "pass", "Missing 0.1.x policy fields normalize to safe defaults")
+            : check("compatibility", "fail", "Policy defaults are unsafe"));
+    }
+    catch (error) {
+        checks.push(check("verify", "fail", error.message));
+    }
+    finally {
+        if (previousHome === undefined)
+            delete process.env.OPENMERIT_HOME;
+        else
+            process.env.OPENMERIT_HOME = previousHome;
+        rmSync(root, { recursive: true, force: true });
+    }
+    return {
+        schemaVersion: 1,
+        ok: !checks.some((item) => item.status === "fail"),
+        checks,
+        summary: { piVersion: null, routeCount: 2, pricedRouteCount: 2, activeRoute: "native/model-a via native" },
+    };
+}

package/dist/llm.js

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { paths } from "./store.js";
 import { legacyOpenRouterRoute } from "./routes.js";
+import { piProviderExtensionArgs } from "./pi-config.js";
 const OR = "https://openrouter.ai/api/v1";
 /** Load OPENROUTER_API_KEY from env or ~/.openmerit/.env. */
 export function loadKey() {
@@ -123,10 +124,12 @@ function textContent(content) {
 export class PiCliChatClient {
     executable;
     onSpend;
+    providerExtensions;
     id = "pi-cli";
-    constructor(executable = process.env.OPENMERIT_PI_BIN?.trim() || "pi", onSpend) {
+    constructor(executable = process.env.OPENMERIT_PI_BIN?.trim() || "pi", onSpend, providerExtensions = []) {
         this.executable = executable;
         this.onSpend = onSpend;
+        this.providerExtensions = providerExtensions;
     }
     chat(model, prompt, _maxTokens, _temperature) {
         return this.run(model, prompt, []);
@@ -148,7 +151,8 @@ export class PiCliChatClient {
             });
             const child = spawn(this.executable, [
                 "--provider", route.provider, "--model", route.modelId, "--mode", "json", "--offline",
-                "--no-extensions", "--no-tools", "--print", ...imageArgs, prompt,
+                "--no-extensions", ...piProviderExtensionArgs(this.providerExtensions),
+                "--no-tools", "--print", ...imageArgs, prompt,
             ], { cwd: dir, stdio: ["ignore", "pipe", "pipe"] });
             let stdout = "";
             let stderr = "";

package/dist/pi-config.js

@@ -0,0 +1,46 @@
+/** Safe, explicit Pi subprocess configuration. */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { basename, isAbsolute } from "node:path";
+/**
+ * Provider extensions execute as code. Require exact, existing, absolute files
+ * and refuse OpenMerit itself so an isolated trial cannot recursively launch
+ * another merit loop.
+ */
+export function validatePiProviderExtensions(paths) {
+    const valid = [];
+    const errors = [];
+    for (const configured of [...new Set(paths)]) {
+        if (!isAbsolute(configured)) {
+            errors.push(`${configured}: path is not absolute`);
+            continue;
+        }
+        if (!existsSync(configured)) {
+            errors.push(`${configured}: file does not exist`);
+            continue;
+        }
+        let actual = configured;
+        try {
+            actual = realpathSync(configured);
+            if (!statSync(actual).isFile()) {
+                errors.push(`${configured}: path is not a file`);
+                continue;
+            }
+        }
+        catch (error) {
+            errors.push(`${configured}: ${error.message}`);
+            continue;
+        }
+        if (/^openmerit\.[cm]?[jt]s$/i.test(basename(actual))) {
+            errors.push(`${configured}: refusing to load OpenMerit recursively`);
+            continue;
+        }
+        valid.push(actual);
+    }
+    return { valid, errors };
+}
+export function piProviderExtensionArgs(paths) {
+    const checked = validatePiProviderExtensions(paths);
+    if (checked.errors.length)
+        throw new Error(`invalid pi.provider_extensions: ${checked.errors.join("; ")}`);
+    return checked.valid.flatMap((file) => ["--extension", file]);
+}

package/dist/pi-trials.js

@@ -10,6 +10,7 @@ import { paths, readJson } from "./store.js";
 import { sessionFiles, sessionImages, taskInputKey } from "./task-input.js";
 import { legacyOpenRouterRoute, meritModelId, modelRoute, routeKey } from "./routes.js";
 import { directChatClient } from "./llm.js";
+import { piProviderExtensionArgs } from "./pi-config.js";
 function answerText(content) {
     if (typeof content === "string")
         return content;
@@ -20,8 +21,12 @@ function answerText(content) {
 }
 /** Pi-backed harness adapter. Future harnesses can implement the same seam. */
 export class PiHarnessAdapter {
+    providerExtensions;
+    constructor(providerExtensions = []) {
+        this.providerExtensions = providerExtensions;
+    }
     runTask(model, input) {
-        return executePiTask(model, input.task, input.cwd, input.images, input.files);
+        return executePiTask(model, input.task, input.cwd, input.images, input.files, this.providerExtensions);
     }
 }
 const defaultHarness = new PiHarnessAdapter();
@@ -113,7 +118,9 @@ export function recordedActiveTask(task, model, images = [], sessionFile, sessio
     if (!user || !userImages || taskInputKey(answerText(user.content), userImages, sessionFiles(answerText(user.content))) !==
         taskInputKey(task, images, files))
         return null;
-    const matching = assistants.filter((m) => meritModelId(m.provider ?? "openrouter", m.model ?? "") === model);
+    const matching = assistants.filter((m) => typeof model === "string"
+        ? meritModelId(m.provider ?? "openrouter", m.model ?? "") === model
+        : m.provider === model.provider && m.model === model.modelId);
     if (matching.length === 0 || matching.some((m) => m.stopReason === "error"))
         return null;
     const answer = matching.map((m) => answerText(m.content)).filter(Boolean).at(-1) ?? "";
@@ -170,10 +177,10 @@ export function settledActiveTask(snapshot) {
     const files = sessionFiles(task);
     if (!task.trim() || taskInputKey(task, images, files) !== st.settledTaskKey)
         return null;
-    const run = recordedActiveTask(task, st.currentModel, images, st.sessionFile, st.sessionBytes);
+    const route = st.currentRoute ?? legacyOpenRouterRoute(st.currentModel);
+    const run = recordedActiveTask(task, route, images, st.sessionFile, st.sessionBytes);
     if (!run)
         return null;
-    const route = st.currentRoute ?? legacyOpenRouterRoute(st.currentModel);
     const routes = st.routes?.length ? st.routes : [route];
     return { task, images, model: st.currentModel, run, sessionFile: st.sessionFile,
         settledAt: st.settledAt, sessionBytes: st.sessionBytes, cwd: st.cwd ?? process.cwd(), usedTools, files,
@@ -182,19 +189,31 @@ export function settledActiveTask(snapshot) {
 export function piExecutable() {
     return process.env.OPENMERIT_PI_BIN?.trim() || "pi";
 }
+function compactNumber(value) {
+    const match = value.match(/^(\d+(?:\.\d+)?)([KMG])?$/i);
+    if (!match)
+        return undefined;
+    const scale = { K: 1_000, M: 1_000_000, G: 1_000_000_000 }[(match[2] ?? "").toUpperCase()] ?? 1;
+    return Math.round(Number(match[1]) * scale);
+}
 /** Read provider/model routes from pi when no live extension snapshot is available. */
-export function availablePiRoutes(snapshot) {
+export function availablePiRoutes(snapshot, providerExtensions = []) {
     if (snapshot?.length)
         return snapshot;
-    const result = spawnSync(piExecutable(), ["--offline", "--list-models"], { encoding: "utf8" });
+    const result = spawnSync(piExecutable(), ["--offline", "--no-extensions",
+        ...piProviderExtensionArgs(providerExtensions), "--list-models"], { encoding: "utf8" });
     if (result.error || result.status !== 0)
         throw new Error("could not list models from pi");
     const routes = [];
     for (const line of result.stdout.split("\n").slice(1)) {
-        const [provider, id, , , , images] = line.trim().split(/\s+/);
+        const [provider, id, context, maxOut, , images] = line.trim().split(/\s+/);
         if (!provider || !id || id.startsWith("~"))
             continue;
-        routes.push(modelRoute(provider, id, { input: images === "yes" ? ["text", "image"] : ["text"] }));
+        routes.push(modelRoute(provider, id, {
+            input: images === "yes" ? ["text", "image"] : ["text"],
+            contextWindow: compactNumber(context),
+            maxTokens: compactNumber(maxOut),
+        }));
     }
     return routes;
 }
@@ -203,7 +222,7 @@ export function availablePiModels() {
     return new Set(availablePiRoutes().map((route) => route.meritId));
 }
 /** Each invocation is a fresh pi run, so model B does not inherit model A's answer. */
-export async function executePiTask(model, task, cwd = process.cwd(), images = [], files = []) {
+export async function executePiTask(model, task, cwd = process.cwd(), images = [], files = [], providerExtensions = []) {
     const route = typeof model === "string" ? legacyOpenRouterRoute(model) : model;
     const imageDir = images.length ? mkdtempSync(join(tmpdir(), "openmerit-pi-image-")) : null;
     const suffix = {
@@ -234,7 +253,8 @@ export async function executePiTask(model, task, cwd = process.cwd(), images = [
         const traceLines = [];
         const child = spawn(piExecutable(), [
             "--provider", route.provider, "--model", route.modelId, "--mode", "json",
-            "--offline", "--no-extensions", "--approve", ...piTrialToolArgs(),
+            "--offline", "--no-extensions", ...piProviderExtensionArgs(providerExtensions),
+            "--approve", ...piTrialToolArgs(),
             "--print", ...imageArgs, ...fileArgs, candidateTask,
         ], { cwd: workspace, stdio: ["ignore", "pipe", "pipe"] });
         let buffer = "";

package/dist/policy.js

@@ -1,7 +1,7 @@
 /** Policy loading, validation, and the swap gate. */
 import { existsSync, readFileSync } from "node:fs";
 export const DEFAULT_POLICY = {
-    version: 1,
+    version: 2,
     mode: "recommend",
     auto_apply: {
         enabled: false,
@@ -16,10 +16,78 @@ export const DEFAULT_POLICY = {
     judge_model: null,
     strategist_model: null,
     max_usd_per_m: 20.0,
+    route_overrides: {},
+    pi: { provider_extensions: [] },
 };
 function num(v, fallback) {
     return typeof v === "number" && Number.isFinite(v) ? v : fallback;
 }
+function finiteAtLeast(value, min, label) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min)
+        throw new Error(`${label} must be a finite number >= ${min}`);
+    return value;
+}
+function positiveInteger(value, label) {
+    const result = finiteAtLeast(value, 1, label);
+    if (!Number.isInteger(result))
+        throw new Error(`${label} must be an integer`);
+    return result;
+}
+function routeOverrides(value) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("route_overrides must be an object keyed by provider:modelId");
+    const result = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const separator = key.indexOf(":");
+        if (separator <= 0 || separator === key.length - 1)
+            throw new Error(`route override ${key} must use provider:modelId`);
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw new Error(`route override ${key} must be an object`);
+        const input = raw.input;
+        if (input !== undefined && (!Array.isArray(input) || input.length === 0 ||
+            input.some((item) => item !== "text" && item !== "image")))
+            throw new Error(`route override ${key}.input must contain only text or image`);
+        const cost = raw.cost;
+        let normalizedCost;
+        if (cost !== undefined) {
+            if (!cost || typeof cost !== "object" || Array.isArray(cost))
+                throw new Error(`route override ${key}.cost must be an object`);
+            const c = cost;
+            normalizedCost = {
+                input: finiteAtLeast(c.input, 0, `route override ${key}.cost.input`),
+                output: finiteAtLeast(c.output, 0, `route override ${key}.cost.output`),
+                ...(c.cacheRead === undefined ? {} : {
+                    cacheRead: finiteAtLeast(c.cacheRead, 0, `route override ${key}.cost.cacheRead`),
+                }),
+                ...(c.cacheWrite === undefined ? {} : {
+                    cacheWrite: finiteAtLeast(c.cacheWrite, 0, `route override ${key}.cost.cacheWrite`),
+                }),
+            };
+        }
+        const contextWindow = raw.context_window;
+        const maxTokens = raw.max_tokens;
+        result[key] = {
+            ...(normalizedCost ? { cost: normalizedCost } : {}),
+            ...(contextWindow === undefined ? {} : {
+                context_window: positiveInteger(contextWindow, `route override ${key}.context_window`),
+            }),
+            ...(maxTokens === undefined ? {} : {
+                max_tokens: positiveInteger(maxTokens, `route override ${key}.max_tokens`),
+            }),
+            ...(input === undefined ? {} : { input: [...new Set(input)] }),
+        };
+    }
+    return result;
+}
+function providerExtensions(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim()))
+        throw new Error("pi.provider_extensions must be an array of non-empty file paths");
+    return [...new Set(value.map((item) => String(item).trim()))];
+}
 /** Load a policy file, filling defaults for missing keys. Throws on invalid JSON. */
 export function loadPolicy(path) {
     if (!existsSync(path))
@@ -58,6 +126,8 @@ export function loadPolicy(path) {
         judge_model: raw.judge_model ?? null,
         strategist_model: raw.strategist_model ?? null,
         max_usd_per_m: num(raw.max_usd_per_m, d.max_usd_per_m),
+        route_overrides: routeOverrides(raw.route_overrides),
+        pi: { provider_extensions: providerExtensions(raw.pi?.provider_extensions) },
     };
 }
 /** Match either a logical vendor/model id or its concrete route provider. */

package/dist/routes.js

@@ -19,6 +19,21 @@ export function legacyOpenRouterRoute(meritId) {
 export function routeKey(route) {
     return `${route.provider}:${route.modelId}`;
 }
+/** Apply user metadata only to the exact provider route it names. */
+export function applyRouteOverrides(routes, overrides) {
+    return routes.map((route) => {
+        const override = overrides[routeKey(route)];
+        if (!override)
+            return route;
+        return {
+            ...route,
+            ...(override.cost ? { cost: { ...override.cost } } : {}),
+            ...(override.context_window === undefined ? {} : { contextWindow: override.context_window }),
+            ...(override.max_tokens === undefined ? {} : { maxTokens: override.max_tokens }),
+            ...(override.input ? { input: [...override.input] } : {}),
+        };
+    });
+}
 export function pointKey(point) {
     return point.route ? routeKey(point.route) : `openrouter:${point.model}`;
 }