muonroi-cli 1.3.4 → 1.4.1

package/dist/src/mcp/smart-filter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Smart MCP server filtering.
+ *
+ * MCP tool schemas are the single largest variable contributor to per-turn
+ * input tokens — a live probe ("Reply with one word: PONG", session
+ * 8a87aa060c6a) carried 53 tool schemas (~21K input tokens) for a turn that
+ * used zero tools. ~36 of those came from MCP servers that the turn could not
+ * possibly need.
+ *
+ * The original inline filter (message-processor.ts) only skipped browser/vision
+ * servers when the message had no browser signal. This generalises that same
+ * proven pattern to a small category→signal table: an OPTIONAL category is
+ * dropped only when its signal is absent from the user's current message.
+ *
+ * Safety: builtin tools are never touched here, and only servers whose id
+ * matches a known optional category are ever dropped — domain servers
+ * (filesystem, muonroi-tools, harness, …) always pass through. A false
+ * positive (signal matched when not strictly needed) merely keeps a server,
+ * costing tokens but never breaking capability; the regexes are deliberately
+ * broad so the failure mode is "kept", not "wrongly dropped".
+ *
+ * Disable entirely with MUONROI_DISABLE_SMART_MCP=1 (handled by the caller,
+ * passed in as `disabled`).
+ */
+/**
+ * Drop filesystem-MCP read/write/edit tools that duplicate a present builtin.
+ * Scoped to the `mcp_filesystem__` prefix so non-filesystem MCP tools (and the
+ * filesystem server's NON-duplicate tools — directory_tree, search_files,
+ * get_file_info, …) are never touched. Returns the filtered set plus the list
+ * of dropped names so the caller can log it (no silent capability removal).
+ * Override with MUONROI_KEEP_REDUNDANT_FS_MCP=1.
+ */
+export declare function dropRedundantFsMcpTools<T extends Record<string, unknown>>(mcpTools: T, builtinToolNames: ReadonlySet<string>): {
+    tools: T;
+    dropped: string[];
+};
+export interface SmartFilterOptions {
+    /** When true, smart filtering is bypassed and every server passes through. */
+    disabled?: boolean;
+}
+/**
+ * Filter a list of MCP servers down to those plausibly relevant to the user's
+ * current message. Only `.id` is read; the generic keeps the caller's concrete
+ * server type intact.
+ */
+export declare function filterMcpServersByMessage<T extends {
+    id: string;
+}>(servers: T[], userMessage: string, opts?: SmartFilterOptions): T[];

package/dist/src/mcp/smart-filter.js

@@ -0,0 +1,115 @@
+/**
+ * Smart MCP server filtering.
+ *
+ * MCP tool schemas are the single largest variable contributor to per-turn
+ * input tokens — a live probe ("Reply with one word: PONG", session
+ * 8a87aa060c6a) carried 53 tool schemas (~21K input tokens) for a turn that
+ * used zero tools. ~36 of those came from MCP servers that the turn could not
+ * possibly need.
+ *
+ * The original inline filter (message-processor.ts) only skipped browser/vision
+ * servers when the message had no browser signal. This generalises that same
+ * proven pattern to a small category→signal table: an OPTIONAL category is
+ * dropped only when its signal is absent from the user's current message.
+ *
+ * Safety: builtin tools are never touched here, and only servers whose id
+ * matches a known optional category are ever dropped — domain servers
+ * (filesystem, muonroi-tools, harness, …) always pass through. A false
+ * positive (signal matched when not strictly needed) merely keeps a server,
+ * costing tokens but never breaking capability; the regexes are deliberately
+ * broad so the failure mode is "kept", not "wrongly dropped".
+ *
+ * Disable entirely with MUONROI_DISABLE_SMART_MCP=1 (handled by the caller,
+ * passed in as `disabled`).
+ */
+/** Browser/vision automation servers — only needed when the turn touches a page. */
+const SKIP_WHEN_NO_BROWSER = /playwright|chrome|browser|devtools|vision|figma|canva/i;
+/**
+ * External-lookup servers (docs / URL fetch / web search) — only needed when
+ * the turn reaches for information outside the codebase. Web-search servers
+ * (tavily/exa/brave/serper/perplexity/…) belong to the same category: a pure
+ * code-edit turn never needs them, and each carries 2-3 tool schemas.
+ */
+const SKIP_WHEN_NO_DOCS = /context7|(^|[-_])fetch([-_]|$)|docs|tavily|exa|brave|serper|perplexity|web[-_]?search|websearch/i;
+/** Matches a browser/page-automation intent (kept identical to the legacy inline regex, plus a URL). */
+function hasBrowserSignal(message) {
+    return (/https?:\/\/\S+/i.test(message) ||
+        /\b(screenshot|browser|playwright|chrome|figma|canva|render|webpage|website|url|hyperlink|navigate|click|scrape)\b/i.test(message));
+}
+/**
+ * Matches an external-information intent (docs lookup / URL fetch / web search).
+ * Broad on purpose — bias is keep-not-drop. Web-search intent adds a few
+ * low-collision terms (news/weather/online/internet/"look up") that rarely
+ * appear in a pure code-edit prompt; bare "search" is intentionally excluded
+ * because it collides with "search the codebase" / "add a search feature".
+ */
+function hasDocsSignal(message) {
+    return (/https?:\/\/\S+/i.test(message) ||
+        /\b(docs?|documentation|api|sdk|library|libraries|framework|package|npm|pip|cargo|crate|gem|maven|nuget|install|migrat\w*|changelog|release\s*notes?|reference|usage|fetch|download|http|web|google|search\s+(the\s+)?web|news|weather|headlines|look\s*up|online|internet)\b/i.test(message));
+}
+/**
+ * Filesystem-MCP tool names that 1:1 duplicate a first-class BUILTIN file tool.
+ * The builtin `read_file`/`write_file`/`edit_file` are strictly better (read-
+ * before-write tracking, LSP sync, CRLF-tolerant matching, per-turn dedup +
+ * read-budget wrappers), so exposing the MCP twins on top is pure redundancy.
+ *
+ * Live waste (storyflow_ui explore-flow A/B, grok session f5dfab0ce0ca): the
+ * model re-read the SAME three files via BOTH `read_file` and
+ * `mcp_filesystem__read_text_file` — a 772-line component was read 6× — because
+ * two interchangeable read tools were on offer. Each re-read re-injects the
+ * whole file into context (large input-token leak) on top of ~150 tok/schema.
+ *
+ * Mapping: bare MCP tool name → the builtin that already covers it. We only drop
+ * the MCP tool when that builtin is actually present in the turn's tool set.
+ */
+const FS_MCP_BUILTIN_EQUIVALENT = {
+    read_file: "read_file",
+    read_text_file: "read_file",
+    read_media_file: "read_file",
+    read_multiple_files: "read_file",
+    write_file: "write_file",
+    edit_file: "edit_file",
+};
+/**
+ * Drop filesystem-MCP read/write/edit tools that duplicate a present builtin.
+ * Scoped to the `mcp_filesystem__` prefix so non-filesystem MCP tools (and the
+ * filesystem server's NON-duplicate tools — directory_tree, search_files,
+ * get_file_info, …) are never touched. Returns the filtered set plus the list
+ * of dropped names so the caller can log it (no silent capability removal).
+ * Override with MUONROI_KEEP_REDUNDANT_FS_MCP=1.
+ */
+export function dropRedundantFsMcpTools(mcpTools, builtinToolNames) {
+    if (process.env.MUONROI_KEEP_REDUNDANT_FS_MCP === "1")
+        return { tools: mcpTools, dropped: [] };
+    const out = {};
+    const dropped = [];
+    for (const [name, tool] of Object.entries(mcpTools)) {
+        const m = name.match(/^mcp_filesystem__(.+)$/);
+        const equivalent = m ? FS_MCP_BUILTIN_EQUIVALENT[m[1]] : undefined;
+        if (equivalent && builtinToolNames.has(equivalent)) {
+            dropped.push(name);
+            continue;
+        }
+        out[name] = tool;
+    }
+    return { tools: out, dropped };
+}
+/**
+ * Filter a list of MCP servers down to those plausibly relevant to the user's
+ * current message. Only `.id` is read; the generic keeps the caller's concrete
+ * server type intact.
+ */
+export function filterMcpServersByMessage(servers, userMessage, opts = {}) {
+    if (opts.disabled)
+        return servers;
+    const browser = hasBrowserSignal(userMessage);
+    const docs = hasDocsSignal(userMessage);
+    return servers.filter((s) => {
+        if (!browser && SKIP_WHEN_NO_BROWSER.test(s.id))
+            return false;
+        if (!docs && SKIP_WHEN_NO_DOCS.test(s.id))
+            return false;
+        return true;
+    });
+}
+//# sourceMappingURL=smart-filter.js.map

package/dist/src/mcp/smoke.test.js

@@ -86,49 +86,49 @@ describe("MCP smoke test — buildMcpToolSet", () => {
     it.skipIf(process.platform === "win32" || !!process.env.CI)("discovers tools from stdio MCP echo stub", async () => {
         // Inline MCP echo server script — handles initialize, notifications/initialized,
         // and tools/list using Content-Length framing per the MCP JSON-RPC spec.
-        const echoServerScript = `
-const { stdin, stdout } = require('process');
-let buf = '';
-stdin.setEncoding('utf8');
-stdin.on('data', (chunk) => {
-  buf += chunk;
-  while (true) {
-    const headerEnd = buf.indexOf('\\r\\n\\r\\n');
-    if (headerEnd === -1) break;
-    const header = buf.slice(0, headerEnd);
-    const match = header.match(/Content-Length:\\s*(\\d+)/i);
-    if (!match) { buf = buf.slice(headerEnd + 4); continue; }
-    const len = parseInt(match[1], 10);
-    const bodyStart = headerEnd + 4;
-    if (buf.length < bodyStart + len) break;
-    const body = buf.slice(bodyStart, bodyStart + len);
-    buf = buf.slice(bodyStart + len);
-    handleMessage(JSON.parse(body));
-  }
-});
-function send(obj) {
-  const s = JSON.stringify(obj);
-  stdout.write('Content-Length: ' + Buffer.byteLength(s) + '\\r\\n\\r\\n' + s);
-}
-function handleMessage(msg) {
-  if (msg.method === 'initialize') {
-    send({ jsonrpc: '2.0', id: msg.id, result: {
-      protocolVersion: '2024-11-05',
-      capabilities: { tools: { listChanged: false } },
-      serverInfo: { name: 'echo-stub', version: '1.0.0' }
-    }});
-  } else if (msg.method === 'notifications/initialized') {
-    // no response needed
-  } else if (msg.method === 'tools/list') {
-    send({ jsonrpc: '2.0', id: msg.id, result: {
-      tools: [{
-        name: 'echo',
-        description: 'Echoes input',
-        inputSchema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] }
-      }]
-    }});
-  }
-}
+        const echoServerScript = `
+const { stdin, stdout } = require('process');
+let buf = '';
+stdin.setEncoding('utf8');
+stdin.on('data', (chunk) => {
+  buf += chunk;
+  while (true) {
+    const headerEnd = buf.indexOf('\\r\\n\\r\\n');
+    if (headerEnd === -1) break;
+    const header = buf.slice(0, headerEnd);
+    const match = header.match(/Content-Length:\\s*(\\d+)/i);
+    if (!match) { buf = buf.slice(headerEnd + 4); continue; }
+    const len = parseInt(match[1], 10);
+    const bodyStart = headerEnd + 4;
+    if (buf.length < bodyStart + len) break;
+    const body = buf.slice(bodyStart, bodyStart + len);
+    buf = buf.slice(bodyStart + len);
+    handleMessage(JSON.parse(body));
+  }
+});
+function send(obj) {
+  const s = JSON.stringify(obj);
+  stdout.write('Content-Length: ' + Buffer.byteLength(s) + '\\r\\n\\r\\n' + s);
+}
+function handleMessage(msg) {
+  if (msg.method === 'initialize') {
+    send({ jsonrpc: '2.0', id: msg.id, result: {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: 'echo-stub', version: '1.0.0' }
+    }});
+  } else if (msg.method === 'notifications/initialized') {
+    // no response needed
+  } else if (msg.method === 'tools/list') {
+    send({ jsonrpc: '2.0', id: msg.id, result: {
+      tools: [{
+        name: 'echo',
+        description: 'Echoes input',
+        inputSchema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] }
+      }]
+    }});
+  }
+}
 `;
         const tmpDir = await mkdtemp(join(tmpdir(), "mcp-echo-stub-"));
         const scriptPath = join(tmpDir, "echo-server.js");
@@ -152,7 +152,7 @@ function handleMessage(msg) {
         finally {
             if (bundle)
                 await bundle.close();
-            await rm(tmpDir, { recursive: true, force: true });
+            await rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
         }
     }, 15000);
 });

package/dist/src/mcp/tools-server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * src/mcp/tools-server.ts
+ *
+ * App-layer stdio MCP server exposing muonroi-cli's self-verify harness as
+ * selfverify.* tools. Async start+poll: selfverify.start returns a runId
+ * immediately; poll with selfverify.status; fetch selfverify.result when done.
+ *
+ * Lives at the app layer (NOT agent-harness-core) so it may import src/self-qa.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { JobManager, type Runner } from "./self-verify-jobs.js";
+export declare function registerSelfVerifyTools(server: McpServer, jm: JobManager): void;
+export declare function createToolsServer(runner?: Runner): McpServer;
+export declare function runToolsMcpServer(): Promise<void>;

package/dist/src/mcp/tools-server.js

@@ -0,0 +1,147 @@
+/**
+ * src/mcp/tools-server.ts
+ *
+ * App-layer stdio MCP server exposing muonroi-cli's self-verify harness as
+ * selfverify.* tools. Async start+poll: selfverify.start returns a runId
+ * immediately; poll with selfverify.status; fetch selfverify.result when done.
+ *
+ * Lives at the app layer (NOT agent-harness-core) so it may import src/self-qa.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { registerEETools } from "./ee-tools.js";
+import { registerForensicsTools } from "./forensics-tools.js";
+import { registerLspTools } from "./lsp-tools.js";
+import { JobManager } from "./self-verify-jobs.js";
+const LOG_TAIL = 40;
+/** Default runner: drives the real self-verify functions in-process. */
+const defaultRunner = {
+    async tier1(opts, log) {
+        // signal intentionally not forwarded: runSelfVerify/runAgenticLoop do not yet
+        // accept an AbortSignal. cancel() marks the job and discards the late result.
+        const { runSelfVerify } = await import("../self-qa/index.js");
+        return runSelfVerify({
+            baseRef: opts.since,
+            maxScenarios: opts.max,
+            emitSpecs: opts.emit,
+            specOutDir: opts.out,
+            log,
+        });
+    },
+    async agentic(opts, log) {
+        // signal intentionally not forwarded: runSelfVerify/runAgenticLoop do not yet
+        // accept an AbortSignal. cancel() marks the job and discards the late result.
+        const { createLLMBrain, runAgenticLoop } = await import("../self-qa/agentic-loop.js");
+        const brain = await createLLMBrain({ modelId: opts.llm });
+        return runAgenticLoop({ goal: opts.goal, brain, maxTurns: opts.turns ?? 20, log });
+    },
+};
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+function fail(error, message) {
+    return {
+        content: [{ type: "text", text: JSON.stringify({ error, message }) }],
+        isError: true,
+    };
+}
+function jobSummary(job) {
+    if (!job.report)
+        return undefined;
+    if (job.kind === "tier1" && "summary" in job.report)
+        return job.report.summary;
+    if (job.kind === "agentic" && "verdict" in job.report)
+        return { verdict: job.report.verdict };
+    return undefined;
+}
+export function registerSelfVerifyTools(server, jm) {
+    server.registerTool("selfverify_start", {
+        description: "Start a self-verify run (mode=tier1 heuristic, or mode=agentic LLM-driven). Returns { runId } immediately; poll selfverify_status, then selfverify_result.",
+        inputSchema: {
+            mode: z.enum(["tier1", "agentic"]),
+            since: z.string().max(200).optional(),
+            max: z.number().int().min(1).max(50).optional(),
+            emit: z.boolean().optional(),
+            out: z.string().max(500).optional(),
+            goal: z.string().max(2000).optional(),
+            llm: z.string().max(200).optional(),
+            turns: z.number().int().min(1).max(50).optional(),
+        },
+    }, async (args) => {
+        if (args.mode === "agentic") {
+            if (!args.goal || !args.llm) {
+                return fail("invalid_args", "agentic mode requires both goal and llm");
+            }
+            const { getModelInfo } = await import("../models/registry.js");
+            if (!getModelInfo(args.llm)) {
+                return fail("unknown_model", `llm '${args.llm}' is not in catalog.json`);
+            }
+            const runId = jm.start({ kind: "agentic", goal: args.goal, llm: args.llm, turns: args.turns });
+            return ok({ runId });
+        }
+        const runId = jm.start({
+            kind: "tier1",
+            since: args.since,
+            max: args.max,
+            emit: args.emit,
+            out: args.out,
+        });
+        return ok({ runId });
+    });
+    server.registerTool("selfverify_status", { description: "Get status + log tail of a self-verify run.", inputSchema: { runId: z.string() } }, async ({ runId }) => {
+        const job = jm.status(runId);
+        if (!job)
+            return fail("not_found", `runId ${runId} not found`);
+        return ok({
+            runId: job.runId,
+            status: job.status,
+            kind: job.kind,
+            startedAt: job.startedAt,
+            finishedAt: job.finishedAt,
+            elapsedMs: (job.finishedAt ?? Date.now()) - job.startedAt,
+            logTail: job.logBuffer.slice(-LOG_TAIL),
+            summary: jobSummary(job) ?? null,
+            error: job.error,
+        });
+    });
+    server.registerTool("selfverify_result", { description: "Fetch the full report of a completed self-verify run.", inputSchema: { runId: z.string() } }, async ({ runId }) => {
+        const job = jm.status(runId);
+        if (!job)
+            return fail("not_found", `runId ${runId} not found`);
+        if (job.status === "running")
+            return fail("still_running", "run not finished; poll selfverify_status first");
+        if (job.status === "error")
+            return fail("run_error", job.error ?? "unknown error");
+        if (job.status === "cancelled")
+            return fail("cancelled", "run was cancelled");
+        // A "done" job always has a report set before status flips, but guard the
+        // MCP text-content contract against JSON.stringify(undefined) regardless.
+        return ok(job.report ?? {});
+    });
+    server.registerTool("selfverify_list", { description: "List recent self-verify runs.", inputSchema: {} }, async () => {
+        return ok(jm.list().map((j) => ({
+            runId: j.runId,
+            kind: j.kind,
+            status: j.status,
+            elapsedMs: (j.finishedAt ?? Date.now()) - j.startedAt,
+        })));
+    });
+    server.registerTool("selfverify_cancel", { description: "Cancel a running self-verify run (best-effort).", inputSchema: { runId: z.string() } }, async ({ runId }) => ok({ cancelled: jm.cancel(runId) }));
+}
+export function createToolsServer(runner = defaultRunner) {
+    const server = new McpServer({ name: "muonroi-tools", version: "0.1.0" });
+    const jm = new JobManager(runner);
+    registerSelfVerifyTools(server, jm);
+    registerEETools(server);
+    registerForensicsTools(server);
+    registerLspTools(server);
+    return server;
+}
+export async function runToolsMcpServer() {
+    const { loadCatalog } = await import("../models/registry.js");
+    await loadCatalog();
+    const server = createToolsServer();
+    await server.connect(new StdioServerTransport());
+}
+//# sourceMappingURL=tools-server.js.map

package/dist/src/models/catalog-client.d.ts

@@ -1,4 +1,12 @@
 import type { ModelInfo } from "../types/index.js";
+export declare function getCatalogUrl(): string;
+/**
+ * Build request headers for the catalog fetch. Attaches the shared API key
+ * (anti-spam) from MUONROI_CATALOG_API_KEY when present. When absent, the
+ * request goes out keyless — fine for a self-hosted catalog with no key set,
+ * and a 401 from a key-protected catalog simply triggers the static fallback.
+ */
+export declare function getCatalogHeaders(): Record<string, string>;
 export interface CatalogModel {
     id: string;
     name: string;
@@ -9,6 +17,7 @@ export interface CatalogModel {
     input_price_per_million: number;
     output_price_per_million: number;
     cached_input_price_per_million?: number;
+    cache_write_price_per_million?: number;
     reasoning: boolean;
     thinking_type?: string | null;
     supports_effort?: boolean;
@@ -17,5 +26,18 @@ export interface CatalogModel {
     default_reasoning_effort?: string | null;
     supports_vision?: boolean;
 }
+/**
+ * Best-effort validation for the REMOTE catalog: a transient bad response must
+ * never break the CLI, so an invalid payload returns null and the caller falls
+ * through to the trusted bundled catalog.
+ */
+export declare function safeValidateCatalog(raw: unknown): CatalogModel[] | null;
+/**
+ * Strict validation for a STATIC (bundled) catalog that is present on disk: a
+ * malformed bundled file is a build defect, not a runtime condition, so we
+ * throw loudly with the validation issues rather than silently skipping it
+ * (which would mask the defect as a confusing "cannot find catalog" later).
+ */
+export declare function validateStaticCatalog(raw: unknown, source: string): CatalogModel[];
 export declare function fetchCatalog(): Promise<CatalogModel[]>;
 export declare function catalogModelToModelInfo(m: CatalogModel): ModelInfo;

package/dist/src/models/catalog-client.js

@@ -2,8 +2,87 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-const CP_CATALOG_URL = "https://cp.muonroi.com/api/v1/models";
+import { z } from "zod";
+// Shared catalog API (services/catalog-api, deployed at catalog.muonroi.com).
+// Overridable for self-hosting / local dev via MUONROI_CATALOG_URL.
+// NOTE: the old default (cp.muonroi.com/api/v1/models) never existed server-side
+// — the control-plane only serves a *rule* catalog — so the remote fetch always
+// 404'd and the CLI silently used the bundled static catalog. This points at the
+// real catalog service.
+const DEFAULT_CATALOG_URL = "https://catalog.muonroi.com/api/v1/models";
+export function getCatalogUrl() {
+    const override = process.env.MUONROI_CATALOG_URL?.trim();
+    return override && override.length > 0 ? override : DEFAULT_CATALOG_URL;
+}
+/**
+ * Build request headers for the catalog fetch. Attaches the shared API key
+ * (anti-spam) from MUONROI_CATALOG_API_KEY when present. When absent, the
+ * request goes out keyless — fine for a self-hosted catalog with no key set,
+ * and a 401 from a key-protected catalog simply triggers the static fallback.
+ */
+export function getCatalogHeaders() {
+    const key = process.env.MUONROI_CATALOG_API_KEY?.trim();
+    return key && key.length > 0 ? { "X-API-Key": key } : {};
+}
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+// ─── Schema validation (catalog drift / corruption guard) ───────────────────
+// The catalog is the single source of truth for model + provider routing. A
+// silently-malformed catalog (truncated remote response, drifted bundled file,
+// hand-edit dropping a required price field) would otherwise poison every
+// tier→model resolution downstream. Validate the SHAPE we actually depend on;
+// unknown future fields are ignored (forward-compatible), not rejected.
+const CatalogModelSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    provider: z.string().min(1),
+    tier: z.string().min(1),
+    context_window: z.number(),
+    max_output_tokens: z.number(),
+    input_price_per_million: z.number(),
+    output_price_per_million: z.number(),
+    cached_input_price_per_million: z.number().optional(),
+    cache_write_price_per_million: z.number().optional(),
+    reasoning: z.boolean(),
+    thinking_type: z.string().nullable().optional(),
+    supports_effort: z.boolean().optional(),
+    description: z.string(),
+    aliases: z.array(z.string()).optional(),
+    default_reasoning_effort: z.string().nullable().optional(),
+    supports_vision: z.boolean().optional(),
+})
+    .loose();
+const CatalogResponseSchema = z.object({
+    version: z.string(),
+    updated_at: z.string(),
+    models: z.array(CatalogModelSchema).min(1),
+});
+/**
+ * Best-effort validation for the REMOTE catalog: a transient bad response must
+ * never break the CLI, so an invalid payload returns null and the caller falls
+ * through to the trusted bundled catalog.
+ */
+export function safeValidateCatalog(raw) {
+    const parsed = CatalogResponseSchema.safeParse(raw);
+    return parsed.success ? parsed.data.models : null;
+}
+/**
+ * Strict validation for a STATIC (bundled) catalog that is present on disk: a
+ * malformed bundled file is a build defect, not a runtime condition, so we
+ * throw loudly with the validation issues rather than silently skipping it
+ * (which would mask the defect as a confusing "cannot find catalog" later).
+ */
+export function validateStaticCatalog(raw, source) {
+    const parsed = CatalogResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .slice(0, 5)
+            .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("; ");
+        throw new Error(`Malformed catalog at ${source}: ${issues}`);
+    }
+    return parsed.data.models;
+}
 let cachedModels = null;
 let cacheTimestamp = 0;
 /**
@@ -42,13 +121,18 @@ export async function fetchCatalog() {
     try {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 3000);
-        const res = await fetch(CP_CATALOG_URL, { signal: controller.signal });
+        const res = await fetch(getCatalogUrl(), { signal: controller.signal, headers: getCatalogHeaders() });
         clearTimeout(timeout);
         if (res.ok) {
-            const data = (await res.json());
-            cachedModels = data.models;
-            cacheTimestamp = Date.now();
-            return cachedModels;
+            const data = await res.json();
+            // Validate the remote payload before trusting it. An invalid/truncated
+            // response falls through to the bundled catalog rather than caching junk.
+            const models = safeValidateCatalog(data);
+            if (models) {
+                cachedModels = models;
+                cacheTimestamp = Date.now();
+                return cachedModels;
+            }
         }
     }
     catch {
@@ -67,14 +151,15 @@ export async function fetchCatalog() {
         // Try createRequire first (works in both bundled and module contexts)
         const viaRequire = tryLoadCatalogViaRequire(dir);
         if (viaRequire) {
-            cachedModels = viaRequire.models;
+            cachedModels = validateStaticCatalog(viaRequire, path.join(dir, "catalog.json"));
             cacheTimestamp = Date.now();
             return cachedModels;
         }
         // Try direct file read (more reliable in edge cases)
-        const viaFS = tryLoadCatalogViaFS(path.join(dir, "catalog.json"));
+        const filePath = path.join(dir, "catalog.json");
+        const viaFS = tryLoadCatalogViaFS(filePath);
         if (viaFS) {
-            cachedModels = viaFS.models;
+            cachedModels = validateStaticCatalog(viaFS, filePath);
             cacheTimestamp = Date.now();
             return cachedModels;
         }
@@ -90,6 +175,7 @@ export function catalogModelToModelInfo(m) {
         inputPrice: m.input_price_per_million,
         outputPrice: m.output_price_per_million,
         cachedInputPrice: m.cached_input_price_per_million,
+        cacheWritePrice: m.cache_write_price_per_million,
         reasoning: m.reasoning,
         description: m.description,
         tier: m.tier,

package/dist/src/models/catalog-gemini.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/models/catalog-gemini.test.js

@@ -0,0 +1,46 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { detectProviderForModel } from "../providers/runtime.js";
+import { getModelInfo, loadCatalog } from "./registry.js";
+/**
+ * Regression guard for the Gemini catalog entries (added 2026-06-04). Model IDs
+ * verified against ai.google.dev/gemini-api/docs/models on that date. Without a
+ * catalog entry a model cannot be selected or routed (Zero-Hardcode Rule), so
+ * these assertions lock in that Gemini is actually usable end-to-end.
+ */
+const GEMINI_IDS = [
+    "gemini-2.5-flash",
+    "gemini-2.5-pro",
+    "gemini-3.5-flash",
+    "gemini-3.1-flash-lite",
+    "gemini-3.1-pro-preview",
+];
+describe("Gemini catalog entries", () => {
+    beforeAll(async () => {
+        await loadCatalog();
+    });
+    it("resolves every Gemini id to the google provider", () => {
+        for (const id of GEMINI_IDS) {
+            const info = getModelInfo(id);
+            expect(info, `catalog missing ${id}`).toBeDefined();
+            expect(info?.provider).toBe("google");
+        }
+    });
+    it("maps gemini ids to the google provider via runtime detection", () => {
+        expect(detectProviderForModel("gemini-2.5-flash")).toBe("google");
+        expect(detectProviderForModel("gemini-3.5-flash")).toBe("google");
+    });
+    it("marks all Gemini models multimodal (vision) and 1M context", () => {
+        for (const id of GEMINI_IDS) {
+            const info = getModelInfo(id);
+            expect(info?.supportsVision, `${id} should support vision`).toBe(true);
+            expect(info?.contextWindow ?? 0, `${id} should be ~1M context`).toBeGreaterThanOrEqual(1_000_000);
+        }
+    });
+    it("covers fast / balanced / premium tiers across the Gemini line", () => {
+        const tiers = new Set(GEMINI_IDS.map((id) => getModelInfo(id)?.tier));
+        expect(tiers.has("fast")).toBe(true);
+        expect(tiers.has("balanced")).toBe(true);
+        expect(tiers.has("premium")).toBe(true);
+    });
+});
+//# sourceMappingURL=catalog-gemini.test.js.map

package/dist/src/models/catalog-url.test.d.ts

@@ -0,0 +1 @@
+export {};