Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
feat(routing): warn when a routing rule names an unknown provider
Jack Rudenko8a23cf3e890f
diff --git a/packages/cli/src/providers/routing-rules.test.ts b/packages/cli/src/providers/routing-rules.test.tsindex 57b4d1e5..b0d8c01e 100644--- a/packages/cli/src/providers/routing-rules.test.ts+++ b/packages/cli/src/providers/routing-rules.test.ts@@ -8,7 +8,7 @@ import { catalogRouteForProvider } from "./catalog-route-bindings.js";* Run: bun test packages/cli/src/providers/routing-rules.test.ts*/-import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";import {copyFileSync,existsSync,@@ -37,12 +37,19 @@ import {import "./model-discovery-builtins.js";import type { ProviderDefinition } from "./provider-definitions.js";import {+ type ExplainRouteOptions,+ type RouteExplanation,type RoutePlan,buildRoutingChain,+ describeRouteExplanation,+ explainRoute,loadRoutingRules,matchRoutingRule,+ matchRoutingRuleKey,normalizeGlmSlug,route,+ routingRuleProblems,+ toRoutePlan,validateRoutingRulesAgainstProviders,} from "./routing-rules.js";import { clearRuntimeRegistry, registerRuntimeProvider } from "./runtime-providers.js";@@ -56,6 +63,12 @@ const STAGE4_CATALOG_FIXTURE = join("test-fixtures","stage4-default-provider-catalog.json");+const STAGE5_CATALOG_FIXTURE = join(+ import.meta.dir,+ "..",+ "test-fixtures",+ "stage5-explain-route-catalog.json"+);function seedDefaultCatalog(entries: DiskCacheV3["entries"]): () => void {_setCatalogEntriesForTest(entries);return _resetCatalogClient;@@ -1837,6 +1850,741 @@ describe("route() metered-billing notice characterization", () => {});});+// ---------------------------------------------------------------------------+// Stage 5 — explainRoute, derivation, and rule warnings+// ---------------------------------------------------------------------------++describe("matchRoutingRuleKey", () => {+ const rules: RoutingRules = {+ "GLM-5.2": ["glm"],+ "glm-*": ["openrouter"],+ "glm-5-*": ["z-ai"],+ "*": ["openai"],+ };++ test("returns the stored exact key case-insensitively", () => {+ expect(matchRoutingRuleKey("glm-5.2", rules)).toBe("GLM-5.2");+ });++ test("returns the longest matching glob", () => {+ expect(matchRoutingRuleKey("glm-5-fast", rules)).toBe("glm-5-*");+ });++ test("returns the catch-all key when no specific rule matches", () => {+ expect(matchRoutingRuleKey("some-other-model", rules)).toBe("*");+ });++ test("returns null when no rule matches", () => {+ expect(matchRoutingRuleKey("some-other-model", { "glm-*": ["glm"] })).toBeNull();+ });+});++interface Stage5SandboxResult {+ diag: string[];+ consoleErrors: string[];+ problems: Array<{+ scope: "global" | "project";+ pattern: string;+ problem: "multiple-wildcards" | "case-collision" | "unknown-provider";+ entry?: string;+ collidesWith?: string;+ }>;+ localRule: { matchedPattern?: string; ruleScope?: string; description: string };+ globalRule: { matchedPattern?: string; ruleScope?: string; description: string };+ catalogDenied: {+ fallbackWithheld?: string;+ providers: string[];+ };+ membershipFallback: Array<{ provider: string; position: string; outcome: string }>;+}++let cachedStage5SandboxResult: Stage5SandboxResult | undefined;++function stage5SandboxResult(): Stage5SandboxResult {+ if (cachedStage5SandboxResult) return cachedStage5SandboxResult;++ const home = mkdtempSync(join(tmpdir(), "claudish-stage5-explain-"));+ const configDir = join(home, ".claudish");+ const projectDir = join(home, "project");+ mkdirSync(configDir, { recursive: true });+ mkdirSync(projectDir, { recursive: true });+ writeFileSync(+ join(configDir, "config.json"),+ JSON.stringify({+ version: "1.0.0",+ defaultProfile: "default",+ profiles: {},+ routing: {+ "glm-*": ["openrouter"],+ "a**b": ["openrouter"],+ "Kimi-X": ["kimi"],+ "kimi-x": ["kimi"],+ "typo-*": ["typo-one", "sandbox-ep", "together"],+ },+ customEndpoints: {+ "sandbox-ep": {+ kind: "simple",+ url: "https://sandbox-ep.invalid/v1",+ format: "openai",+ apiKey: "stage5-test-key",+ },+ },+ }),+ "utf8"+ );+ writeFileSync(+ join(projectDir, ".claudish.json"),+ JSON.stringify({ routing: { "glm-5*": ["sandbox-ep"], "x*y*z": ["glm"] } }),+ "utf8"+ );+ writeFileSync(+ join(configDir, "probe-models.json"),+ JSON.stringify({+ version: 3,+ generationId: "stage5-test-generation",+ generatedAt: "2026-09-24T00:00:00.000Z",+ providers: { openrouter: "probe-model", openai: "probe-model" },+ unavailable: {},+ }),+ "utf8"+ );++ const routingModuleUrl = new URL("./routing-rules.ts", import.meta.url).href;+ const authorityModuleUrl = new URL("../auth/credentials/authority.ts", import.meta.url).href;+ const loggerModuleUrl = new URL("../logger.ts", import.meta.url).href;+ const script = `+ const rr = await import(${JSON.stringify(routingModuleUrl)});+ const { credentials } = await import(${JSON.stringify(authorityModuleUrl)});+ const { setDiagOutput } = await import(${JSON.stringify(loggerModuleUrl)});+ credentials.isAvailable = async (provider) => provider === "sandbox-ep";+ credentials.describeReadiness = async (provider) => ({+ readiness: provider === "sandbox-ep" ? "present" : "absent",+ });+ credentials.getRequestAuth = async () => ({+ headers: { Authorization: "Bearer stage5-offline" },+ });+ globalThis.fetch = async () => new Response("offline", { status: 503 });++ const diag = [];+ const consoleErrors = [];+ const realConsoleError = console.error;+ setDiagOutput({ write: (message) => diag.push(message), cleanup() {} });+ console.error = (...args) => consoleErrors.push(args.map(String).join(" "));+ let output;+ try {+ const first = await rr.explainRoute("typo-x", {+ cachePath: ${JSON.stringify(STAGE5_CATALOG_FIXTURE)},+ });+ const local = await rr.explainRoute("glm-5.3", {+ cachePath: ${JSON.stringify(STAGE5_CATALOG_FIXTURE)},+ });+ const global = await rr.explainRoute("glm-4.6", {+ cachePath: ${JSON.stringify(STAGE5_CATALOG_FIXTURE)},+ });+ const denied = await rr.explainRoute("cat-denied", {+ rules: {},+ cachePath: ${JSON.stringify(STAGE5_CATALOG_FIXTURE)},+ });+ const membershipFallback = await rr.explainRoute("plan-less", {+ rules: {},+ defaultProvider: "kimi-coding",+ cachePath: ${JSON.stringify(STAGE5_CATALOG_FIXTURE)},+ });+ output = {+ diag,+ consoleErrors,+ problems: first.warnings+ .filter((warning) => warning.type === "rule-problem")+ .map((warning) => warning.problem),+ localRule: {+ matchedPattern: local.matchedPattern,+ ruleScope: local.ruleScope,+ description: rr.describeRouteExplanation(local),+ },+ globalRule: {+ matchedPattern: global.matchedPattern,+ ruleScope: global.ruleScope,+ description: rr.describeRouteExplanation(global),+ },+ catalogDenied: {+ fallbackWithheld: denied.fallbackWithheld,+ providers: denied.candidates.map((candidate) => candidate.provider),+ },+ membershipFallback: membershipFallback.candidates.map((candidate) => ({+ provider: candidate.provider,+ position: candidate.position,+ outcome: candidate.outcome,+ })),+ };+ } finally {+ console.error = realConsoleError;+ setDiagOutput(null);+ }+ process.stdout.write(JSON.stringify(output));+ `;+ const env: Record<string, string> = {+ HOME: home,+ PATH: process.env.PATH ?? "",+ TMPDIR: process.env.TMPDIR ?? tmpdir(),+ CLAUDISH_DISABLE_CATALOG_WARM: "1",+ CLAUDISH_DISABLE_KEYCHAIN: "1",+ CLAUDISH_DISABLE_OP: "1",+ };++ try {+ const result = Bun.spawnSync([process.execPath, "-e", script], {+ cwd: projectDir,+ env,+ stdout: "pipe",+ stderr: "pipe",+ });+ const stdout = result.stdout.toString();+ const stderr = result.stderr.toString();+ if (result.exitCode !== 0) {+ throw new Error(`Stage 5 sandbox failed (${result.exitCode}): ${stderr || stdout}`);+ }+ cachedStage5SandboxResult = JSON.parse(stdout) as Stage5SandboxResult;+ return cachedStage5SandboxResult;+ } finally {+ rmSync(home, { recursive: true, force: true });+ }+}++function stage5RuntimeProvider(name: string): ProviderDefinition {+ return {+ name,+ displayName: name,+ tier: "native",+ transport: "openai",+ baseUrl: `https://${name}.invalid`,+ apiPath: "/v1/chat/completions",+ apiKeyEnvVar: `${name.toUpperCase().replaceAll("-", "_")}_API_KEY`,+ apiKeyDescription: "Offline Stage 5 routing-test key",+ apiKeyUrl: "https://example.invalid/key",+ shortcuts: [],+ legacyPrefixes: [],+ createHandler: {+ kind: "none",+ reason: "virtual",+ note: "Stage 5 test fixture — never builds a handler.",+ },+ isDirectApi: true,+ };+}++describe("explainRoute", () => {+ const realFetch = globalThis.fetch;+ const realIsAvailable = credentials.isAvailable;+ const realDescribeReadiness = credentials.describeReadiness;+ const realGetRequestAuth = credentials.getRequestAuth;+ const antigravityFetcher = getModelDiscoveryFetcher("antigravity");++ let readiness = new Map<string, "present" | "absent" | "failed">();+ let antigravityModels: string[] = [];+ let liveModels = new Map<string, string[]>();+ let previousKeychainGuard: string | undefined;+ let previousOpGuard: string | undefined;++ function setReadiness(values: Record<string, "present" | "absent" | "failed">): void {+ readiness = new Map(Object.entries(values));+ }++ function resetDiscovery(): void {+ invalidateModelDiscovery();+ }++ beforeEach(() => {+ previousKeychainGuard = process.env.CLAUDISH_DISABLE_KEYCHAIN;+ previousOpGuard = process.env.CLAUDISH_DISABLE_OP;+ process.env.CLAUDISH_DISABLE_KEYCHAIN = "1";+ process.env.CLAUDISH_DISABLE_OP = "1";+ readiness = new Map();+ antigravityModels = [];+ liveModels = new Map();+ _resetCatalogClient();+ invalidateModelDiscovery();+ clearRuntimeRegistry();+ registerRuntimeProvider(stage5RuntimeProvider("kept-metered"));+ registerRuntimeProvider(stage5RuntimeProvider("no-cred"));+ registerRuntimeProvider(stage5RuntimeProvider("fallback-no-cred"));+ credentials.isAvailable = async (provider: string) => readiness.get(provider) === "present";+ credentials.describeReadiness = async (provider: string) => ({+ readiness: readiness.get(provider) ?? "absent",+ });+ credentials.getRequestAuth = async () => ({+ headers: { Authorization: "Bearer stage5-offline" },+ });+ registerModelDiscoveryFetcher("antigravity", async () => ({+ kind: "models",+ models: antigravityModels.map((id) => ({ id })),+ }));+ globalThis.fetch = (async (input: string | URL | Request) => {+ const rawUrl =+ typeof input === "string" ? input : input instanceof URL ? input.href : input.url;+ const ids = liveModels.get(new URL(rawUrl).hostname);+ if (!ids) return new Response("offline", { status: 503 });+ return new Response(JSON.stringify({ data: ids.map((id) => ({ id })) }), {+ status: 200,+ headers: { "Content-Type": "application/json" },+ });+ }) as typeof fetch;+ });++ afterEach(() => {+ if (previousKeychainGuard === undefined) delete process.env.CLAUDISH_DISABLE_KEYCHAIN;+ else process.env.CLAUDISH_DISABLE_KEYCHAIN = previousKeychainGuard;+ if (previousOpGuard === undefined) delete process.env.CLAUDISH_DISABLE_OP;+ else process.env.CLAUDISH_DISABLE_OP = previousOpGuard;+ credentials.isAvailable = realIsAvailable;+ credentials.describeReadiness = realDescribeReadiness;+ credentials.getRequestAuth = realGetRequestAuth;+ credentials.invalidate();+ if (antigravityFetcher) {+ registerModelDiscoveryFetcher("antigravity", antigravityFetcher);+ }+ globalThis.fetch = realFetch;+ invalidateModelDiscovery();+ clearRuntimeRegistry();+ _resetCatalogClient();+ setDiagOutput(null);+ });++ test("records every candidate outcome in chain order", async () => {+ setReadiness({ antigravity: "present", "minimax-coding": "failed", "kept-metered": "present" });+ antigravityModels = ["some-other-model"];++ const explanation = await explainRoute("rule-mix", {+ rules: {+ "rule-*": [+ "kimi-coding",+ "antigravity@rule-mix",+ "minimax-coding@rule-mix",+ "kept-metered@rule-mix",+ "no-cred@rule-mix",+ ],+ },+ cachePath: STAGE5_CATALOG_FIXTURE,+ });++ expect(explanation.source).toBe("user-rule");+ expect(explanation.matchedPattern).toBe("rule-*");+ expect(explanation.candidates.map(({ provider, outcome }) => [provider, outcome])).toEqual([+ ["kimi-coding", "excluded-by-membership"],+ ["antigravity", "not-served"],+ ["minimax-coding", "credential-unreadable"],+ ["kept-metered", "kept"],+ ["no-cred", "no-credential"],+ ]);+ expect(explanation.warnings.map((warning) => warning.type)).toEqual([+ "subscription-not-served",+ "subscription-credential-unreadable",+ ]);+ });++ test("records all fallback withholding values and catalog states", async () => {+ const alreadyGathered = await explainRoute("cat-found", {+ rules: {},+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ const absent = await explainRoute("no-such-model-xyz", {+ rules: {},+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ const disabled = await explainRoute("no-such-model-xyz", {+ rules: {},+ defaultProvider: "",+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ const unreadable = await explainRoute("whatever-x", {+ rules: {},+ cachePath: join(import.meta.dir, "missing-stage5-catalog.json"),+ });+ const catalogDenied = stage5SandboxResult().catalogDenied;++ expect({+ catalog: alreadyGathered.catalog,+ withheld: alreadyGathered.fallbackWithheld,+ }).toEqual({ catalog: "found", withheld: "already-gathered" });+ expect(absent.catalog).toBe("absent");+ expect({ catalog: disabled.catalog, withheld: disabled.fallbackWithheld }).toEqual({+ catalog: "absent",+ withheld: "disabled",+ });+ expect({ catalog: unreadable.catalog, withheld: unreadable.fallbackWithheld }).toEqual({+ catalog: "unreadable",+ withheld: "catalog-unreadable",+ });+ expect(catalogDenied).toEqual({+ fallbackWithheld: "catalog-denies",+ providers: ["openai"],+ });+ });++ test("keeps membership exclusion on the fallback position", async () => {+ expect(stage5SandboxResult().membershipFallback).toEqual([+ {+ provider: "kimi-coding",+ position: "fallback",+ outcome: "excluded-by-membership",+ },+ ]);+ });++ test("records every source, explicit via, rule scope, and routed model", async () => {+ setReadiness({ openrouter: "present" });+ const native = await explainRoute("opus", { cachePath: STAGE5_CATALOG_FIXTURE });+ const explicit = await explainRoute("anthropic/claude-opus-5", {+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ const userRule = await explainRoute("rule-mix", {+ rules: { "rule-*": [] },+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ const glm = await explainRoute("glm-5-2", {+ rules: {},+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ const vendorQualified = await explainRoute("openai/gpt-5", {+ rules: {},+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ const sandbox = stage5SandboxResult();++ expect(native).toMatchObject({ source: "native", requestedModel: "opus", routedModel: "opus" });+ expect(native.candidates).toEqual([]);+ expect(describeRouteExplanation(native)).toBe("native · Claude Code's own auth · not probed");+ expect(explicit).toMatchObject({+ source: "explicit",+ via: "vendor-qualified-id",+ requestedModel: "anthropic/claude-opus-5",+ routedModel: "anthropic/claude-opus-5",+ });+ expect(describeRouteExplanation(explicit)).toBe(+ "explicit · OpenRouter · vendor-qualified id sent verbatim"+ );+ expect(userRule).toMatchObject({ source: "user-rule", matchedPattern: "rule-*" });+ expect(glm).toMatchObject({+ source: "catalog",+ requestedModel: "glm-5-2",+ routedModel: "glm-5.2",+ catalog: "found",+ });+ expect(vendorQualified).toMatchObject({+ source: "catalog",+ requestedModel: "openai/gpt-5",+ routedModel: "gpt-5",+ catalog: "found",+ });+ expect(sandbox.localRule).toEqual({+ matchedPattern: "glm-5*",+ ruleScope: "project",+ description: 'user rule "glm-5*" (project)',+ });+ expect(sandbox.globalRule).toEqual({+ matchedPattern: "glm-*",+ ruleScope: "global",+ description: 'user rule "glm-*" (global)',+ });+ });++ test("records every reachable no-route cause", async () => {+ const causes = new Set<string>();+ const record = (explanation: RouteExplanation): void => {+ expect(explanation.outcome.kind).toBe("no-route");+ if (explanation.outcome.kind === "no-route") causes.add(explanation.outcome.cause);+ };++ record(+ await explainRoute("blocked", {+ rules: { blocked: [] },+ cachePath: STAGE5_CATALOG_FIXTURE,+ })+ );+ record(+ await explainRoute("whatever-x", {+ rules: {},+ cachePath: join(import.meta.dir, "missing-stage5-catalog.json"),+ })+ );+ record(+ await explainRoute("no-such-model-xyz", {+ rules: {},+ defaultProvider: "",+ cachePath: STAGE5_CATALOG_FIXTURE,+ })+ );+ record(+ await explainRoute("no-such-model-xyz", {+ rules: {},+ defaultProvider: "fallback-no-cred",+ cachePath: STAGE5_CATALOG_FIXTURE,+ })+ );++ setReadiness({ antigravity: "present" });+ antigravityModels = ["some-other-model"];+ resetDiscovery();+ record(+ await explainRoute("bare-not-served", {+ rules: { "bare-not-served": ["antigravity@bare-not-served"] },+ cachePath: STAGE5_CATALOG_FIXTURE,+ })+ );++ setReadiness({});+ resetDiscovery();+ record(+ await explainRoute("openai@gpt-5", {+ rules: {},+ cachePath: STAGE5_CATALOG_FIXTURE,+ })+ );++ setReadiness({ antigravity: "present" });+ antigravityModels = ["some-other-model"];+ resetDiscovery();+ record(+ await explainRoute("antigravity@explicit-not-served", {+ rules: {},+ cachePath: STAGE5_CATALOG_FIXTURE,+ })+ );++ expect(causes).toEqual(+ new Set([+ "rule-empty",+ "catalog-unreadable",+ "catalog-empty",+ "no-credential",+ "not-served",+ "explicit-no-credential",+ "explicit-not-served",+ ])+ );+ });++ test("an explicit provider@model pins its wire id instead of applying membership", async () => {+ setReadiness({ "kimi-coding": "present" });+ const explanation = await explainRoute("kimi-coding@plan-less", {+ rules: {},+ cachePath: STAGE5_CATALOG_FIXTURE,+ });++ // `explicit-unbuildable` cannot be reached through provider@model: the `@`+ // path deliberately bypasses plan membership because the user pinned a wire+ // id. Membership exclusion only runs for an @-less routing entry.+ expect(explanation.candidates[0]).toMatchObject({+ provider: "kimi-coding",+ wireId: "plan-less",+ outcome: "kept",+ });+ expect(explanation.outcome).toEqual({ kind: "ok" });+ });++ test("drops an uncredentialed fallback and never returns it as a route", async () => {+ const opts: ExplainRouteOptions = {+ rules: {},+ defaultProvider: "fallback-no-cred",+ cachePath: STAGE5_CATALOG_FIXTURE,+ };+ const explanation = await explainRoute("no-such-model-xyz", opts);+ const plan = await route("no-such-model-xyz", opts.rules, opts.defaultProvider, opts.cachePath);++ expect(explanation.candidates).toHaveLength(1);+ expect(explanation.candidates[0]).toMatchObject({+ provider: "fallback-no-cred",+ position: "fallback",+ outcome: "no-credential",+ });+ expect(explanation.outcome).toMatchObject({ kind: "no-route", cause: "no-credential" });+ expect(toRoutePlan(explanation)).toEqual(plan);+ expect(plan.kind).toBe("no-route");+ });++ test("filters a non-kept fallback even when another candidate routes", async () => {+ setReadiness({ openai: "present" });+ liveModels.set("api.openai.com", ["cat-denied"]);+ const opts: ExplainRouteOptions = {+ rules: {},+ defaultProvider: "fallback-no-cred",+ cachePath: STAGE5_CATALOG_FIXTURE,+ };+ const explanation = await explainRoute("cat-denied", opts);+ resetDiscovery();+ const plan = await route("cat-denied", opts.rules, opts.defaultProvider, opts.cachePath);++ expect(+ explanation.candidates.map(({ provider, position, outcome }) => ({+ provider,+ position,+ outcome,+ }))+ ).toEqual([+ { provider: "openai", position: "candidate", outcome: "kept" },+ { provider: "fallback-no-cred", position: "fallback", outcome: "no-credential" },+ ]);+ expect(toRoutePlan(explanation)).toEqual(plan);+ expect(plan).toEqual({+ kind: "ok",+ primary: { provider: "openai", modelSpec: "oai@cat-denied", displayName: "OpenAI" },+ fallbacks: [],+ });+ });++ test("derives route() from explanations over representative targets", async () => {+ const cases: Array<{+ target: string;+ opts: ExplainRouteOptions;+ ready?: Record<string, "present" | "absent" | "failed">;+ antigravity?: string[];+ }> = [+ {+ target: "rule-mix",+ opts: {+ rules: { "rule-mix": ["minimax-coding@rule-mix", "kept-metered@rule-mix"] },+ cachePath: STAGE5_CATALOG_FIXTURE,+ },+ ready: { "minimax-coding": "failed", "kept-metered": "present" },+ },+ {+ target: "no-such-model-xyz",+ opts: {+ rules: {},+ defaultProvider: "fallback-no-cred",+ cachePath: STAGE5_CATALOG_FIXTURE,+ },+ },+ {+ target: "cat-found",+ opts: { rules: {}, cachePath: STAGE5_CATALOG_FIXTURE },+ },+ {+ target: "openai@gpt-5",+ opts: { rules: {}, cachePath: STAGE5_CATALOG_FIXTURE },+ },+ {+ target: "antigravity@explicit-not-served",+ opts: { rules: {}, cachePath: STAGE5_CATALOG_FIXTURE },+ ready: { antigravity: "present" },+ antigravity: ["some-other-model"],+ },+ {+ target: "glm-5-2",+ opts: { rules: {}, cachePath: STAGE5_CATALOG_FIXTURE },+ },+ ];++ for (const testCase of cases) {+ setReadiness(testCase.ready ?? {});+ antigravityModels = testCase.antigravity ?? [];+ resetDiscovery();+ const explanation = await explainRoute(testCase.target, testCase.opts);+ resetDiscovery();+ const notices: string[] = [];+ setDiagOutput({ write: (message) => notices.push(message), cleanup() {} });+ let plan: RoutePlan;+ try {+ plan = await route(+ testCase.target,+ testCase.opts.rules,+ testCase.opts.defaultProvider,+ testCase.opts.cachePath+ );+ } finally {+ setDiagOutput(null);+ }+ expect(toRoutePlan(explanation)).toEqual(plan);+ }+ });++ test("never writes diagnostics or console errors", async () => {+ setReadiness({ "minimax-coding": "failed", "kept-metered": "present" });+ const diagnostics: string[] = [];+ setDiagOutput({ write: (message) => diagnostics.push(message), cleanup() {} });+ const consoleError = spyOn(console, "error").mockImplementation(() => {});+ try {+ await explainRoute("rule-mix", {+ rules: { "rule-mix": ["minimax-coding@rule-mix", "kept-metered@rule-mix"] },+ cachePath: STAGE5_CATALOG_FIXTURE,+ });+ expect(diagnostics).toEqual([]);+ expect(consoleError).not.toHaveBeenCalled();+ } finally {+ consoleError.mockRestore();+ setDiagOutput(null);+ }+ });+});++describe("routing rule warnings", () => {+ test("loadRoutingRules does not print a multiple-wildcard problem", () => {+ const consoleError = spyOn(console, "error").mockImplementation(() => {});+ try {+ expect(loadRoutingRules({ globalRules: { "a**b": ["openrouter"] }, localRules: {} })).toEqual(+ { "a**b": ["openrouter"] }+ );+ expect(consoleError).not.toHaveBeenCalled();+ } finally {+ consoleError.mockRestore();+ }+ });++ test("returns wildcard and case-collision problems with their scopes", () => {+ expect(+ routingRuleProblems({+ globalRules: { "a**b": [], "Kimi-X": [], "kimi-x": [] },+ localRules: { "x*y*z": [] },+ })+ ).toEqual([+ { scope: "global", pattern: "a**b", problem: "multiple-wildcards" },+ {+ scope: "global",+ pattern: "kimi-x",+ problem: "case-collision",+ collidesWith: "Kimi-X",+ },+ { scope: "project", pattern: "x*y*z", problem: "multiple-wildcards" },+ ]);+ });++ test("reports unknown providers but exempts bundled and registered custom endpoints", () => {+ const direct = routingRuleProblems({+ globalRules: { "typo-*": ["typo-one", "together"] },+ localRules: {},+ });+ expect(direct.filter((problem) => problem.problem === "unknown-provider")).toEqual([+ {+ scope: "global",+ pattern: "typo-*",+ problem: "unknown-provider",+ entry: "typo-one",+ },+ ]);++ const sandbox = stage5SandboxResult();+ expect(sandbox.diag).toEqual([]);+ expect(sandbox.consoleErrors).toEqual([]);+ expect(sandbox.problems).toEqual([+ { scope: "global", pattern: "a**b", problem: "multiple-wildcards" },+ {+ scope: "global",+ pattern: "kimi-x",+ problem: "case-collision",+ collidesWith: "Kimi-X",+ },+ {+ scope: "global",+ pattern: "typo-*",+ problem: "unknown-provider",+ entry: "typo-one",+ },+ { scope: "project", pattern: "x*y*z", problem: "multiple-wildcards" },+ ]);+ expect(sandbox.problems.some((problem) => problem.entry === "sandbox-ep")).toBe(false);+ expect(sandbox.problems.some((problem) => problem.entry === "together")).toBe(false);+ });+});+test("no test leaves the keychain guard changed", () => {expect(process.env.CLAUDISH_DISABLE_KEYCHAIN).toBe(keychainGuardAtFileLoad);});diff --git a/packages/cli/src/providers/routing-rules.ts b/packages/cli/src/providers/routing-rules.tsindex d3fdbe7e..4270d0d9 100644--- a/packages/cli/src/providers/routing-rules.ts+++ b/packages/cli/src/providers/routing-rules.ts@@ -15,6 +15,7 @@ import { providerServesModel } from "./model-availability.js";import { AUTO_ROUTE_PROVIDER, PROVIDER_SHORTCUTS } from "./model-parser.js";import { parseModelSpec } from "./model-parser.js";import { type NativeRoute, proxyRouteDecision } from "./native-route.js";+import { PREDEFINED_ENDPOINTS } from "./predefined-catalog.js";import { type RouteTier, getProviderByName } from "./provider-definitions.js";import {type RouteCandidate,@@ -76,39 +77,29 @@ export function loadRoutingRuleSources(): RoutingRuleSources {}/**- * Validate that every provider name a routing rules table references exists in- * `provider-definitions.ts`. Walks each entry, strips the optional `@model`- * suffix, resolves shortcuts (e.g. `or` → `openrouter`), and looks each- * canonical provider up.+ * Validate that every provider name a routing rules table references exists.+ * The `unknown-provider` problems of {@link routingRuleProblems}, thrown.** Throws, so it is for a caller that wants a typo to be loud — a config* validator or a test — never the request path. `loadRoutingRules` deliberately* does not call it: a user whose hand-written rule names a provider claudish- * dropped should get a degraded chain and a warning, not a crash on every- * request.+ * dropped should get a degraded chain and a warning (`routingRuleProblems`), not+ * a crash on every request.** Its subject used to be the shipped table, which is gone. What remains to* check is the USER's rules, which is the only table left.*/export function validateRoutingRulesAgainstProviders(rules: RoutingRules): void {- const unknown: Array<{ rule: string; entry: string; provider: string }> = [];-- for (const ruleKey of Object.keys(rules)) {- const entries = rules[ruleKey] ?? [];- for (const entry of entries) {- const atIdx = entry.indexOf("@");- const providerRaw = atIdx === -1 ? entry : entry.slice(0, atIdx);- const canonical = PROVIDER_SHORTCUTS[providerRaw.toLowerCase()] ?? providerRaw.toLowerCase();- if (!getProviderByName(canonical)) {- unknown.push({ rule: ruleKey, entry, provider: canonical });- }- }- }+ // The scope is not part of the message; the table is checked as one file.+ const unknown = ruleTableProblems(rules, "global").filter(+ (problem) => problem.problem === "unknown-provider"+ );if (unknown.length > 0) {- const lines = unknown.map(- (u) => ` rule "${u.rule}" → entry "${u.entry}" → unknown provider "${u.provider}"`- );+ const lines = unknown.map((u) => {+ const entry = u.entry ?? "";+ return ` rule "${u.pattern}" → entry "${entry}" → unknown provider "${ruleEntryProvider(entry)}"`;+ });throw new Error(`[claudish] routing rules reference unknown providers:\n${lines.join("\n")}`);}}@@ -119,15 +110,23 @@ export interface RoutingRuleProblem {scope: RuleScope;/** The rule key as stored. */pattern: string;- problem: "multiple-wildcards" | "case-collision";+ problem: "multiple-wildcards" | "case-collision" | "unknown-provider";+ /** `unknown-provider` only: the rule entry, as written, that names no provider. */+ entry?: string;/** `case-collision` only: the earlier key in the same file this one collides with. */collidesWith?: string;}/**- * Every problem in the user's two rule files. Pure: it reads nothing and prints+ * Every problem in the user's two rule files. It reads no file and prints* nothing, so a TUI can show the result and the proxy can print it once.*+ * `unknown-provider` asks the provider registry, so the CALLER registers the+ * custom and bundled endpoints first (`ensureEndpointsRegistered`); without that+ * every custom endpoint a rule names reads as a typo. A bundled endpoint is known+ * by its catalog row, since registration skips one whose key is absent: that rule+ * entry is `no-credential` when routed, not a typo.+ ** Each file is checked on its own, as the rules have always been: a key that* collides only with a key in the OTHER file is not reported.*@@ -161,10 +160,34 @@ function ruleTableProblems(rules: RoutingRules, scope: RuleScope): RoutingRulePr} else {seenLower.set(lower, key);}+ for (const entry of rules[key] ?? []) {+ if (!isKnownProvider(ruleEntryProvider(entry))) {+ problems.push({ scope, pattern: key, problem: "unknown-provider", entry });+ }+ }}return problems;}+/**+ * The claudish provider a rule entry names: the part before an optional+ * `@<wire id>`, with a shortcut (`or`) resolved, exactly as `buildRoutingChain`+ * resolves it.+ */+function ruleEntryProvider(entry: RoutingEntry): string {+ const atIdx = entry.indexOf("@");+ const providerRaw = atIdx === -1 ? entry : entry.slice(0, atIdx);+ return PROVIDER_SHORTCUTS[providerRaw.toLowerCase()] ?? providerRaw.toLowerCase();+}++/** A built-in provider, a registered endpoint, or a bundled endpoint's catalog row. */+function isKnownProvider(provider: string): boolean {+ return (+ getProviderByName(provider) !== undefined ||+ PREDEFINED_ENDPOINTS.some((row) => row.name.toLowerCase() === provider)+ );+}+/** One line for a rule problem, without a "[claudish]" prefix (logStderr adds it). */export function describeRoutingRuleProblem(problem: RoutingRuleProblem): string {switch (problem.problem) {@@ -179,6 +202,13 @@ export function describeRoutingRuleProblem(problem: RoutingRuleProblem): string"differ only in case. Matching ignores case, so one silently shadows the other: " +"pick one casing and remove the duplicate.");+ case "unknown-provider": {+ const entry = problem.entry ?? "";+ return (+ `routing rule "${problem.pattern}" (${problem.scope}) names "${entry}", but no ` ++ `provider "${ruleEntryProvider(entry)}" exists, so that entry never routes.`+ );+ }}}@@ -1410,10 +1440,20 @@ function bareRoutingFor(opts: ExplainRouteOptions): BareRouting {// The project file overwrites the global one key by key, so a key the project// file holds is the project's rule.scopeOf: (ruleKey) => (Object.hasOwn(sources.localRules, ruleKey) ? "project" : "global"),- ruleProblems: routingRuleProblems(sources),+ ruleProblems: ruleProblemsAfterRegistration(sources),};}+/**+ * {@link routingRuleProblems} once the custom and bundled endpoints are+ * registered, so a rule naming one is not reported as unknown. Latched, so+ * free after the first call.+ */+function ruleProblemsAfterRegistration(sources: RoutingRuleSources): RoutingRuleProblem[] {+ ensureEndpointsRegistered();+ return routingRuleProblems(sources);+}+/*** The `RoutePlan` an explanation stands for: every `kept` candidate in chain* order, whatever its position, or the no-route verbatim. An uncredentialeddiff --git a/packages/cli/src/proxy-server.ts b/packages/cli/src/proxy-server.tsindex f2e5d877..c61ae166 100644--- a/packages/cli/src/proxy-server.ts+++ b/packages/cli/src/proxy-server.ts@@ -590,7 +590,9 @@ export async function createProxyServer(// Problems in those rules, reported ONCE, here: before Claude Code owns the// terminal, and through logStderr, which the quiet flag and a diagnostics pane// both govern. `loadRoutingRules` prints nothing, because it also runs inside the- // config TUI and the `--probe` TUI (and on every `route()` call).+ // config TUI and the `--probe` TUI (and on every `route()` call). The custom and+ // bundled endpoints were registered above, so a rule naming one is not reported+ // as an unknown provider.for (const problem of routingRuleProblems(routingRuleSources)) {logStderr(`Warning: ${describeRoutingRuleProblem(problem)}`);}diff --git a/packages/cli/src/test-fixtures/stage5-explain-route-catalog.json b/packages/cli/src/test-fixtures/stage5-explain-route-catalog.jsonnew file mode 100644index 00000000..11c728bd--- /dev/null+++ b/packages/cli/src/test-fixtures/stage5-explain-route-catalog.json@@ -0,0 +1,132 @@+{+ "version": 3,+ "lastUpdated": "2026-09-24T00:00:00.000Z",+ "entries": [+ {+ "modelId": "kimi-code-plan-marker",+ "aliases": [],+ "subscriptionPlanIds": ["kimi-code"],+ "aggregators": [+ {+ "sourceProviderId": "moonshotai",+ "sourceCollectorId": "stage5-test",+ "routeStatus": "mapped",+ "route": {+ "routeId": "moonshotai",+ "routeProfileId": "kimi-code-subscription"+ },+ "externalModelId": "k3",+ "confidence": "api_official"+ }+ ]+ },+ {+ "modelId": "rule-mix",+ "aliases": [],+ "subscriptionPlanIds": [],+ "aggregators": []+ },+ {+ "modelId": "cat-found",+ "aliases": [],+ "subscriptionPlanIds": [],+ "aggregators": [+ {+ "sourceProviderId": "openai",+ "sourceCollectorId": "stage5-test",+ "routeStatus": "mapped",+ "route": {+ "routeId": "openai",+ "routeProfileId": "direct-api"+ },+ "externalModelId": "cat-found",+ "confidence": "api_official"+ },+ {+ "sourceProviderId": "openrouter",+ "sourceCollectorId": "stage5-test",+ "routeStatus": "mapped",+ "route": {+ "routeId": "openrouter",+ "routeProfileId": "gateway"+ },+ "externalModelId": "cat-found",+ "confidence": "api_official"+ }+ ]+ },+ {+ "modelId": "cat-denied",+ "aliases": [],+ "subscriptionPlanIds": [],+ "aggregators": [+ {+ "sourceProviderId": "openai",+ "sourceCollectorId": "stage5-test",+ "routeStatus": "mapped",+ "route": {+ "routeId": "openai",+ "routeProfileId": "direct-api"+ },+ "externalModelId": "cat-denied",+ "confidence": "api_official"+ }+ ]+ },+ {+ "modelId": "plan-less",+ "aliases": [],+ "subscriptionPlanIds": [],+ "aggregators": []+ },+ {+ "modelId": "glm-5.2",+ "aliases": [],+ "subscriptionPlanIds": [],+ "aggregators": [+ {+ "sourceProviderId": "openrouter",+ "sourceCollectorId": "stage5-test",+ "routeStatus": "mapped",+ "route": {+ "routeId": "openrouter",+ "routeProfileId": "gateway"+ },+ "externalModelId": "glm-5.2",+ "confidence": "api_official"+ }+ ]+ },+ {+ "modelId": "gpt-5",+ "aliases": [],+ "subscriptionPlanIds": [],+ "aggregators": [+ {+ "sourceProviderId": "openai",+ "sourceCollectorId": "stage5-test",+ "routeStatus": "mapped",+ "route": {+ "routeId": "openai",+ "routeProfileId": "direct-api"+ },+ "externalModelId": "gpt-5",+ "confidence": "api_official"+ }+ ]+ }+ ],+ "models": [],+ "plans": [+ {+ "id": "kimi-code",+ "modelDiscovery": "catalog",+ "routeStatus": "supported",+ "route": {+ "routeId": "moonshotai",+ "routeProfileId": "kimi-code-subscription"+ }+ }+ ],+ "catalogGenerationId": "stage5-explain-route-fixture"+}