qlogicagent 2.13.4 → 2.13.5

package/dist/cli/handlers/settings-handler.remote-catalog.test.js

@@ -0,0 +1,1247 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { handleSettingsAddKey, handleSettingsCopyKey, handleSettingsRemoveKey, handleSettingsToggleKey, handleSettingsListModels, handleSettingsListProviders, handleSettingsGetKey, handleSettingsGetOverview, handleSettingsValidateKey, } from "./settings-handler.js";
+import { resetLlmrouterCatalogClientCache } from "../../runtime/infra/llmrouter-catalog.js";
+import { resetModelRegistry } from "../../runtime/infra/model-registry.js";
+function rpcContext() {
+    const responses = [];
+    return {
+        responses,
+        sendResponse(id, result, error) {
+            responses.push({ id, result, error });
+        },
+        sendError(id, code, message) {
+            responses.push({ id, error: { code, message } });
+        },
+    };
+}
+function settingsPath(home) {
+    return join(home, "profiles", "oc_local", "settings.json");
+}
+function writeSettings(home, settings) {
+    const file = settingsPath(home);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(settings, null, 2));
+}
+function readSettings(home) {
+    return JSON.parse(readFileSync(settingsPath(home), "utf8"));
+}
+describe("settings remote llmrouter catalog", () => {
+    let home;
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "qlogicagent-catalog-"));
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        resetModelRegistry();
+        resetLlmrouterCatalogClientCache();
+        vi.stubEnv("QLOGIC_LLMROUTER_BASE_URL", "https://router.test");
+        vi.stubEnv("QLOGIC_LLMROUTER_ACCESS_TOKEN", "token-123");
+    });
+    afterEach(() => {
+        vi.unstubAllEnvs();
+        vi.unstubAllGlobals();
+        resetModelRegistry();
+        resetLlmrouterCatalogClientCache();
+        rmSync(home, { recursive: true, force: true });
+    });
+    it("lists providers and models from llmrouter catalog with bearer auth", async () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "llmrouter",
+                    baseUrl: "https://router.test",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-llmrouter", key: "sk-test", weight: 1, enabled: true }],
+                },
+            ],
+            models: [],
+            bindings: {},
+        });
+        const seen = new Map();
+        vi.stubGlobal("fetch", vi.fn(async (input, init) => {
+            const url = String(input);
+            const auth = new Headers(init?.headers).get("authorization");
+            seen.set(url, auth);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "llmrouter",
+                            name: "LLMRouter",
+                            baseUrl: "https://router.test",
+                            transport: "openai-responses",
+                            models: [{ id: "llmrouter-default" }],
+                        },
+                        {
+                            id: "volcengine",
+                            name: "Volcengine",
+                            baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+                            transport: "volcengine-responses",
+                            models: [{ id: "doubao-seedream-4-5-251128" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "doubao-seedream-4-5-251128",
+                            provider: "volcengine",
+                            native_model_id: "doubao-seedream-4-5-251128",
+                            display_name: "Seedream 4.5",
+                            purposes: ["imageGeneration"],
+                            provider_transport: "volcengine-responses",
+                            tool_call: false,
+                            stream_required: false,
+                            reasoning_mode: "none",
+                            media_type: "image",
+                        },
+                    ],
+                });
+            }
+            return new Response("not found", { status: 404 });
+        }));
+        const providersCtx = rpcContext();
+        await handleSettingsListProviders.call(providersCtx, { jsonrpc: "2.0", id: 1, method: "settings.listProviders" });
+        const modelsCtx = rpcContext();
+        await handleSettingsListModels.call(modelsCtx, { jsonrpc: "2.0", id: 2, method: "settings.listModels" });
+        expect(seen.get("https://router.test/ext/model-catalog/providers")).toBe("Bearer token-123");
+        expect(seen.get("https://router.test/ext/model-catalog/models")).toBe("Bearer token-123");
+        expect(providersCtx.responses[0].result.providers).toEqual([
+            {
+                id: "llmrouter",
+                displayName: "LLMRouter",
+                baseUrl: "https://router.test",
+                modelCount: 2,
+            },
+            {
+                id: "volcengine",
+                displayName: "Doubao / Volcengine",
+                baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+                modelCount: 1,
+            },
+        ]);
+        expect(modelsCtx.responses[0].result.models[0]).toMatchObject({
+            id: "llmrouter:doubao-seedream-4-5-251128",
+            provider: "llmrouter",
+            model: "doubao-seedream-4-5-251128",
+            nativeModelId: "doubao-seedream-4-5-251128",
+            displayName: "Seedream 4.5",
+            purposes: ["imageGeneration"],
+            enabled: true,
+            reasoningMode: "none",
+            mediaType: "image",
+            toolCall: false,
+        });
+        expect(modelsCtx.responses[0].result.configuredProviderIds).toEqual(["llmrouter"]);
+    });
+    it("deduplicates the llmrouter entry and collapses technical provider variants by group for settings UI", async () => {
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "llmrouter",
+                            name: "LLMRouter",
+                            baseUrl: "https://router.test",
+                            models: [{ id: "llmrouter-default" }],
+                        },
+                        {
+                            id: "zhipu",
+                            name: "Zhipu GLM",
+                            group: "zhipu",
+                            baseUrl: "https://open.bigmodel.cn/api/anthropic",
+                            models: [{ id: "glm-5.1" }],
+                        },
+                        {
+                            id: "zhipu-openai",
+                            name: "Zhipu GLM OpenAI",
+                            group: "zhipu",
+                            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+                            models: [{ id: "glm-5.1" }],
+                        },
+                        {
+                            id: "zhipu-coding",
+                            name: "Zhipu GLM Coding",
+                            group: "zhipu",
+                            baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4",
+                            models: [{ id: "codegeex-4" }],
+                        },
+                        {
+                            id: "qwen",
+                            name: "Alibaba Qwen (DashScope)",
+                            group: "qwen",
+                            baseUrl: "https://dashscope.aliyuncs.com/apps/anthropic",
+                            models: [{ id: "qwen3.6-plus" }],
+                        },
+                        {
+                            id: "qwen-coding",
+                            name: "Alibaba Qwen (Coding Plan)",
+                            group: "qwen",
+                            baseUrl: "https://coding.dashscope.aliyuncs.com/apps/anthropic",
+                            models: [{ id: "qwen3-coder-plus" }],
+                        },
+                        {
+                            id: "volcengine",
+                            name: "Doubao / Volcengine",
+                            group: "volcengine",
+                            baseUrl: "https://ark.cn-beijing.volces.com/api",
+                            models: [{ id: "doubao-seed-2-0-lite-260428" }],
+                        },
+                        {
+                            id: "volcengine-plan",
+                            name: "Doubao / Volcengine Plan",
+                            group: "volcengine",
+                            baseUrl: "https://ark.cn-beijing.volces.com/api/coding/v3",
+                            models: [{ id: "ark-code-latest" }],
+                        },
+                        {
+                            id: "tei-bge-m3",
+                            name: "BAAI bge-m3 (TEI)",
+                            authType: "none",
+                            apiKeyEnvVars: [],
+                            baseUrl: "http://127.0.0.1:8080",
+                            models: [{ id: "BAAI/bge-m3" }],
+                        },
+                    ],
+                });
+            }
+            return new Response("not found", { status: 404 });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsListProviders.call(ctx, { jsonrpc: "2.0", id: 1, method: "settings.listProviders" });
+        const providers = ctx.responses[0].result.providers;
+        expect(providers.map((provider) => provider.id)).toEqual(["llmrouter", "zhipu", "qwen", "volcengine"]);
+        expect(providers.map((provider) => provider.displayName)).toEqual([
+            "LLMRouter",
+            "Zhipu GLM",
+            "Alibaba Qwen (DashScope)",
+            "Doubao / Volcengine",
+        ]);
+        expect(providers.find((provider) => provider.id === "qwen").variants).toEqual([
+            {
+                id: "qwen",
+                displayName: "常规 DashScope API Key",
+                baseUrl: "https://dashscope.aliyuncs.com/apps/anthropic",
+                modelCount: 1,
+            },
+            {
+                id: "qwen-coding",
+                displayName: "Coding Plan 通道",
+                baseUrl: "https://coding.dashscope.aliyuncs.com/apps/anthropic",
+                modelCount: 1,
+            },
+        ]);
+        expect(providers.find((provider) => provider.id === "volcengine").variants).toEqual([
+            {
+                id: "volcengine",
+                displayName: "常规 Ark API Key",
+                baseUrl: "https://ark.cn-beijing.volces.com/api",
+                modelCount: 1,
+            },
+            {
+                id: "volcengine-plan",
+                displayName: "订阅 / Plan 通道",
+                baseUrl: "https://ark.cn-beijing.volces.com/api/coding/v3",
+                modelCount: 1,
+            },
+        ]);
+    });
+    it("adds a selected Volcengine Plan key without guessing the channel from validation", async () => {
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "volcengine",
+                            name: "Doubao / Volcengine",
+                            group: "volcengine",
+                            baseUrl: "https://ark.cn-beijing.volces.com/api",
+                            models: [{ id: "doubao-seed-2-0-lite-260428" }],
+                        },
+                        {
+                            id: "volcengine-plan",
+                            name: "Doubao / Volcengine Plan",
+                            group: "volcengine",
+                            baseUrl: "https://ark.cn-beijing.volces.com/api/coding/v3",
+                            models: [{ id: "ark-code-latest" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "ark-code-latest",
+                            provider: "volcengine-plan",
+                            native_model_id: "ark-code-latest",
+                            display_name: "Ark Code Latest",
+                            purposes: ["textGeneration"],
+                            provider_transport: "openai-chat",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const addKeyCtx = rpcContext();
+        await handleSettingsAddKey.call(addKeyCtx, {
+            jsonrpc: "2.0",
+            id: 11,
+            method: "settings.addKey",
+            params: { providerId: "volcengine-plan", key: "sk-volcengine-plan" },
+        });
+        expect(addKeyCtx.responses[0].error).toBeUndefined();
+        expect(addKeyCtx.responses[0].result).toMatchObject({
+            ok: true,
+            providerId: "volcengine-plan",
+        });
+        expect(readSettings(home).providers[0]).toMatchObject({
+            providerId: "volcengine-plan",
+            baseUrl: "https://ark.cn-beijing.volces.com/api/coding/v3",
+        });
+    });
+    it("adds a selected Qwen Coding Plan key without guessing the channel from validation", async () => {
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "qwen",
+                            name: "Alibaba Qwen (DashScope)",
+                            group: "qwen",
+                            baseUrl: "https://dashscope.aliyuncs.com/apps/anthropic",
+                            models: [{ id: "qwen3.6-plus" }],
+                        },
+                        {
+                            id: "qwen-coding",
+                            name: "Alibaba Qwen (Coding Plan)",
+                            group: "qwen",
+                            baseUrl: "https://coding.dashscope.aliyuncs.com/apps/anthropic",
+                            models: [{ id: "qwen3-coder-plus" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "qwen3-coder-plus",
+                            provider: "qwen-coding",
+                            native_model_id: "qwen3-coder-plus",
+                            display_name: "Qwen3 Coder Plus",
+                            purposes: ["textGeneration"],
+                            provider_transport: "anthropic-messages",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const addKeyCtx = rpcContext();
+        await handleSettingsAddKey.call(addKeyCtx, {
+            jsonrpc: "2.0",
+            id: 12,
+            method: "settings.addKey",
+            params: { providerId: "qwen-coding", key: "sk-qwen-coding" },
+        });
+        expect(addKeyCtx.responses[0].error).toBeUndefined();
+        expect(addKeyCtx.responses[0].result).toMatchObject({
+            ok: true,
+            providerId: "qwen-coding",
+        });
+        expect(readSettings(home).providers[0]).toMatchObject({
+            providerId: "qwen-coding",
+            baseUrl: "https://coding.dashscope.aliyuncs.com/apps/anthropic",
+        });
+    });
+    it("validates Anthropic transport providers through messages when the models probe is unavailable", async () => {
+        const seen = [];
+        vi.stubGlobal("fetch", vi.fn(async (input, init) => {
+            const url = String(input);
+            const headers = new Headers(init?.headers);
+            seen.push({ url, method: init?.method, xApiKey: headers.get("x-api-key") });
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "qwen-coding",
+                            name: "Alibaba Qwen (Coding Plan)",
+                            group: "qwen",
+                            baseUrl: "https://coding.dashscope.aliyuncs.com/apps/anthropic",
+                            transport: "anthropic-messages",
+                            models: [{ id: "qwen3-coder-plus" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "qwen3-coder-plus",
+                            provider: "qwen-coding",
+                            native_model_id: "qwen3-coder-plus",
+                            display_name: "Qwen3 Coder Plus",
+                            purposes: ["textGeneration"],
+                            provider_transport: "anthropic-messages",
+                        },
+                    ],
+                });
+            }
+            if (url === "https://coding.dashscope.aliyuncs.com/apps/models") {
+                return new Response("not found", { status: 404 });
+            }
+            if (url === "https://coding.dashscope.aliyuncs.com/apps/anthropic/v1/messages") {
+                return Response.json({ id: "msg_probe_ok" });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsAddKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 14,
+            method: "settings.addKey",
+            params: { providerId: "qwen-coding", key: "sk-qwen-coding" },
+        });
+        expect(ctx.responses[0].error).toBeUndefined();
+        expect(ctx.responses[0].result).toMatchObject({ ok: true, providerId: "qwen-coding" });
+        expect(seen).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                url: "https://coding.dashscope.aliyuncs.com/apps/models",
+                method: "GET",
+            }),
+            expect.objectContaining({
+                url: "https://coding.dashscope.aliyuncs.com/apps/anthropic/v1/messages",
+                method: "POST",
+                xApiKey: "sk-qwen-coding",
+            }),
+        ]));
+    });
+    it("rejects Anthropic transport provider keys when the protocol probe rejects authentication", async () => {
+        writeSettings(home, {
+            providers: [],
+            models: [],
+            bindings: {},
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "qwen-coding",
+                            name: "Alibaba Qwen (Coding Plan)",
+                            group: "qwen",
+                            baseUrl: "https://coding.dashscope.aliyuncs.com/apps/anthropic",
+                            transport: "anthropic-messages",
+                            models: [{ id: "qwen3-coder-plus" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://coding.dashscope.aliyuncs.com/apps/models") {
+                return new Response("not found", { status: 404 });
+            }
+            if (url === "https://coding.dashscope.aliyuncs.com/apps/anthropic/v1/messages") {
+                return new Response("unauthorized", { status: 401 });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsAddKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 15,
+            method: "settings.addKey",
+            params: { providerId: "qwen-coding", key: "sk-invalid" },
+        });
+        expect(ctx.responses[0].error).toBeDefined();
+        expect(JSON.stringify(ctx.responses[0].error)).toContain("unauthorized");
+        expect(readSettings(home).providers ?? []).toEqual([]);
+    });
+    it("removes a key from persistent settings and prunes an empty provider", () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "deepseek",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-deepseek", key: "sk-deepseek", weight: 1, enabled: true }],
+                },
+            ],
+            models: [],
+            bindings: {},
+        });
+        const ctx = rpcContext();
+        handleSettingsRemoveKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 16,
+            method: "settings.removeKey",
+            params: { keyId: "key-deepseek" },
+        });
+        expect(ctx.responses[0].error).toBeUndefined();
+        expect(ctx.responses[0].result).toEqual({ ok: true });
+        expect(readSettings(home).providers).toEqual([]);
+    });
+    it("persists key enabled state when toggled", () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "deepseek",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-deepseek", key: "sk-deepseek", weight: 1, enabled: true }],
+                },
+            ],
+            models: [],
+            bindings: {},
+        });
+        const ctx = rpcContext();
+        handleSettingsToggleKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 17,
+            method: "settings.toggleKey",
+            params: { keyId: "key-deepseek", enabled: false },
+        });
+        expect(ctx.responses[0].error).toBeUndefined();
+        expect(ctx.responses[0].result).toEqual({ ok: true });
+        expect(readSettings(home).providers[0].keys[0].enabled).toBe(false);
+    });
+    it("rejects remove and toggle requests for unknown keys", () => {
+        writeSettings(home, {
+            providers: [],
+            models: [],
+            bindings: {},
+        });
+        const removeCtx = rpcContext();
+        handleSettingsRemoveKey.call(removeCtx, {
+            jsonrpc: "2.0",
+            id: 18,
+            method: "settings.removeKey",
+            params: { keyId: "missing-key" },
+        });
+        const toggleCtx = rpcContext();
+        handleSettingsToggleKey.call(toggleCtx, {
+            jsonrpc: "2.0",
+            id: 19,
+            method: "settings.toggleKey",
+            params: { keyId: "missing-key", enabled: false },
+        });
+        expect(removeCtx.responses[0].error).toBeDefined();
+        expect(toggleCtx.responses[0].error).toBeDefined();
+        expect(JSON.stringify(removeCtx.responses[0].error)).toContain("API Key not found");
+        expect(JSON.stringify(toggleCtx.responses[0].error)).toContain("API Key not found");
+    });
+    it("filters model list to providers that have a configured key", async () => {
+        writeSettings(home, {
+            providers: [],
+            models: [],
+            bindings: {},
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "doubao-seedream-4-5-251128",
+                            provider: "volcengine",
+                            native_model_id: "doubao-seedream-4-5-251128",
+                            display_name: "Seedream 4.5",
+                            purposes: ["imageGeneration"],
+                            provider_transport: "volcengine-responses",
+                        },
+                        {
+                            id: "gpt-5.1",
+                            provider: "openai",
+                            native_model_id: "gpt-5.1",
+                            display_name: "GPT-5.1",
+                            purposes: ["textGeneration"],
+                            provider_transport: "openai-responses",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsListModels.call(ctx, { jsonrpc: "2.0", id: 4, method: "settings.listModels" });
+        const result = ctx.responses[0].result;
+        expect(result.models).toHaveLength(0);
+        expect(result.grouped).toEqual({});
+        expect(result.configuredProviderIds).toEqual([]);
+    });
+    it("treats the injected llmrouter inference key as a healthy settings provider key", async () => {
+        vi.stubEnv("QLOGIC_LLMROUTER_INFERENCE_KEY", "sk-qllm-env");
+        writeSettings(home, {
+            providers: [],
+            models: [],
+            bindings: {},
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "deepseek-v4-flash",
+                            public_model: "deepseek-v4-flash",
+                            provider: "deepseek",
+                            native_model_id: "deepseek-v4-flash",
+                            display_name: "DeepSeek V4 Flash",
+                            purposes: ["textGeneration"],
+                            provider_transport: "openai-chat",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const modelsCtx = rpcContext();
+        await handleSettingsListModels.call(modelsCtx, { jsonrpc: "2.0", id: 11, method: "settings.listModels" });
+        expect(modelsCtx.responses[0].result.configuredProviderIds).toEqual(["llmrouter"]);
+        expect(modelsCtx.responses[0].result.models).toEqual([
+            expect.objectContaining({
+                id: "llmrouter:deepseek-v4-flash",
+                provider: "llmrouter",
+                model: "deepseek-v4-flash",
+            }),
+        ]);
+        const overviewCtx = rpcContext();
+        await handleSettingsGetOverview.call(overviewCtx, { jsonrpc: "2.0", id: 12, method: "settings.getOverview" });
+        const overview = overviewCtx.responses[0].result;
+        expect(overview.providers).toEqual([
+            expect.objectContaining({
+                providerId: "llmrouter",
+                healthyKeys: 1,
+                totalKeys: 1,
+                keys: [
+                    expect.objectContaining({
+                        id: "llmrouter-env",
+                        enabled: true,
+                        health: "healthy",
+                    }),
+                ],
+            }),
+        ]);
+        expect(overview.purposes.textGeneration).toMatchObject({
+            bound: true,
+            modelId: "llmrouter:deepseek-v4-flash",
+            available: true,
+        });
+        const keyCtx = rpcContext();
+        await handleSettingsGetKey.call(keyCtx, {
+            jsonrpc: "2.0",
+            id: 13,
+            method: "settings.getKey",
+            params: { keyId: "llmrouter-env" },
+        });
+        expect(keyCtx.responses[0].result.key).toBe("sk-qllm-env");
+    });
+    it("persists local pause and removal for the injected llmrouter inference key", async () => {
+        vi.stubEnv("QLOGIC_LLMROUTER_INFERENCE_KEY", "sk-qllm-env");
+        writeSettings(home, {
+            providers: [],
+            models: [],
+            bindings: {},
+        });
+        const toggleCtx = rpcContext();
+        handleSettingsToggleKey.call(toggleCtx, {
+            jsonrpc: "2.0",
+            id: 14,
+            method: "settings.toggleKey",
+            params: { keyId: "llmrouter-env", enabled: false },
+        });
+        expect(toggleCtx.responses[0].error).toBeUndefined();
+        expect(toggleCtx.responses[0].result).toEqual({ ok: true });
+        expect(readSettings(home).injectedKeys["llmrouter-env"]).toMatchObject({
+            enabled: false,
+        });
+        const removeCtx = rpcContext();
+        handleSettingsRemoveKey.call(removeCtx, {
+            jsonrpc: "2.0",
+            id: 16,
+            method: "settings.removeKey",
+            params: { keyId: "llmrouter-env" },
+        });
+        expect(removeCtx.responses[0].error).toBeUndefined();
+        expect(removeCtx.responses[0].result).toEqual({ ok: true });
+        expect(readSettings(home).injectedKeys["llmrouter-env"]).toMatchObject({
+            enabled: false,
+            removed: true,
+        });
+        const keyCtx = rpcContext();
+        handleSettingsGetKey.call(keyCtx, {
+            jsonrpc: "2.0",
+            id: 17,
+            method: "settings.getKey",
+            params: { keyId: "llmrouter-env" },
+        });
+        expect(keyCtx.responses[0].error).toBeDefined();
+        expect(JSON.stringify(keyCtx.responses[0].error)).toContain("API Key not found");
+    });
+    it("copies a model key through the host system clipboard without returning the secret", async () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "deepseek",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-deepseek", key: "sk-deepseek-secret", weight: 1, enabled: true }],
+                },
+            ],
+            models: [],
+            bindings: {},
+        });
+        const writeClipboard = vi.fn(async () => undefined);
+        const ctx = { ...rpcContext(), writeClipboard };
+        await handleSettingsCopyKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 18,
+            method: "settings.copyKey",
+            params: { keyId: "key-deepseek" },
+        });
+        expect(ctx.responses[0].error).toBeUndefined();
+        expect(ctx.responses[0].result).toEqual({ ok: true });
+        expect(writeClipboard).toHaveBeenCalledWith("sk-deepseek-secret");
+        expect(JSON.stringify(ctx.responses[0])).not.toContain("sk-deepseek-secret");
+    });
+    it("trusts llmrouter catalog visibility instead of hard-coding hidden provider ids", async () => {
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "llmrouter",
+                            name: "LLMRouter",
+                            baseUrl: "https://router.test",
+                            models: [{ id: "llmrouter-default" }],
+                        },
+                        {
+                            id: "openrouter",
+                            name: "OpenRouter",
+                            baseUrl: "https://openrouter.ai/api/v1",
+                            models: [{ id: "openai/gpt-5.1" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://openrouter.ai/api/v1/models") {
+                return Response.json({ data: [{ id: "openai/gpt-5.1" }] });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "openai/gpt-5.1",
+                            provider: "openrouter",
+                            native_model_id: "openai/gpt-5.1",
+                            display_name: "GPT-5.1",
+                            purposes: ["textGeneration"],
+                            provider_transport: "openai-chat",
+                        },
+                    ],
+                });
+            }
+            return new Response("not found", { status: 404 });
+        }));
+        const providersCtx = rpcContext();
+        await handleSettingsListProviders.call(providersCtx, { jsonrpc: "2.0", id: 1, method: "settings.listProviders" });
+        expect(providersCtx.responses[0].result.providers.map((provider) => provider.id)).toEqual([
+            "llmrouter",
+            "openrouter",
+        ]);
+        const addKeyCtx = rpcContext();
+        await handleSettingsAddKey.call(addKeyCtx, {
+            jsonrpc: "2.0",
+            id: 3,
+            method: "settings.addKey",
+            params: { providerId: "openrouter", key: "sk-or-new" },
+        });
+        expect(addKeyCtx.responses[0].error).toBeUndefined();
+        expect(addKeyCtx.responses[0].result).toMatchObject({
+            ok: true,
+            providerId: "openrouter",
+        });
+    });
+    it("keeps multi-purpose video models in every returned purpose group", async () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "llmrouter",
+                    baseUrl: "https://router.test",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-llmrouter", key: "sk-test", weight: 1, enabled: true }],
+                },
+            ],
+            models: [],
+            bindings: {},
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "llmrouter",
+                            name: "LLMRouter",
+                            group: "llmrouter",
+                            baseUrl: "https://router.test",
+                            transport: "openai-responses",
+                            models: [{ id: "llmrouter-default" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "doubao-seedance-2-0-fast",
+                            public_model: "doubao-seedance-2-0-fast",
+                            provider: "volcengine",
+                            native_model_id: "doubao-seedance-2-0-fast-260128",
+                            display_name: "Doubao Seedance 2.0 Fast",
+                            category: "videoGeneration",
+                            purposes: ["videoGeneration", "videoUnderstanding"],
+                            provider_transport: "volcengine-responses",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsListModels.call(ctx, { jsonrpc: "2.0", id: 8, method: "settings.listModels" });
+        const result = ctx.responses[0].result;
+        expect(result.models[0].purposes).toEqual(["videoGeneration", "videoUnderstanding"]);
+        expect(result.grouped.videoGeneration[0].id).toBe("llmrouter:doubao-seedance-2-0-fast");
+        expect(result.grouped.videoUnderstanding[0].id).toBe("llmrouter:doubao-seedance-2-0-fast");
+    });
+    it("keeps configured direct provider models and llmrouter provider models side by side", async () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "zhipu-openai",
+                    baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-zhipu", key: "sk-test", weight: 1, enabled: true }],
+                },
+                {
+                    providerId: "llmrouter",
+                    baseUrl: "https://router.test",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-router", key: "sk-router", weight: 1, enabled: true }],
+                },
+            ],
+            models: [],
+            bindings: {},
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "llmrouter",
+                            name: "LLMRouter",
+                            group: "llmrouter",
+                            baseUrl: "https://router.test",
+                            transport: "openai-responses",
+                            models: [{ id: "llmrouter-default" }],
+                        },
+                        {
+                            id: "zhipu-openai",
+                            name: "Zhipu GLM OpenAI",
+                            group: "zhipu",
+                            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+                            transport: "openai-chat",
+                            models: [{ id: "glm-5.1" }],
+                        },
+                        {
+                            id: "openai",
+                            name: "OpenAI",
+                            group: "openai",
+                            baseUrl: "https://api.openai.com",
+                            transport: "openai-responses",
+                            models: [{ id: "gpt-5.1" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "glm-5.1",
+                            provider: "zhipu-openai",
+                            native_model_id: "glm-5.1",
+                            display_name: "GLM-5.1",
+                            purposes: ["textGeneration"],
+                            provider_transport: "openai-chat",
+                        },
+                        {
+                            id: "gpt-5.1",
+                            provider: "openai",
+                            native_model_id: "gpt-5.1",
+                            display_name: "GPT-5.1",
+                            purposes: ["textGeneration"],
+                            provider_transport: "openai-responses",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsListModels.call(ctx, { jsonrpc: "2.0", id: 5, method: "settings.listModels" });
+        const result = ctx.responses[0].result;
+        expect(result.models).toEqual([
+            expect.objectContaining({ id: "zhipu-openai:glm-5.1", provider: "zhipu-openai", model: "glm-5.1" }),
+            expect.objectContaining({ id: "llmrouter:glm-5.1", provider: "llmrouter", model: "glm-5.1" }),
+            expect.objectContaining({ id: "llmrouter:gpt-5.1", provider: "llmrouter", model: "gpt-5.1" }),
+        ]);
+        expect(result.configuredProviderIds).toEqual(["zhipu-openai", "llmrouter"]);
+    });
+    it("reports catalog unavailable instead of falling back to builtin providers when llmrouter catalog is unavailable", async () => {
+        vi.unstubAllEnvs();
+        const ctx = rpcContext();
+        await handleSettingsListProviders.call(ctx, { jsonrpc: "2.0", id: 1, method: "settings.listProviders" });
+        expect(ctx.responses[0].result).toBeUndefined();
+        expect(JSON.stringify(ctx.responses[0].error)).toContain("llmrouter");
+    });
+    it("rejects adding a direct provider key when the llmrouter catalog is unavailable", async () => {
+        writeSettings(home, {
+            providers: [],
+            models: [],
+            bindings: {},
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return new Response("catalog offline", { status: 503 });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsAddKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 9,
+            method: "settings.addKey",
+            params: { providerId: "deepseek", key: "sk-deepseek-official" },
+        });
+        expect(ctx.responses[0].result).toBeUndefined();
+        expect(JSON.stringify(ctx.responses[0].error)).toContain("llmrouter");
+        expect(readSettings(home).providers ?? []).toEqual([]);
+    });
+    it("rejects a direct provider key when the provider models endpoint rejects it", async () => {
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "deepseek",
+                            name: "DeepSeek",
+                            baseUrl: "https://api.deepseek.com/anthropic",
+                            transport: "anthropic-messages",
+                            models: [{ id: "deepseek-v4-flash" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://api.deepseek.com/models") {
+                return new Response("unauthorized", { status: 401 });
+            }
+            return new Response("not found", { status: 404 });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsAddKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 13,
+            method: "settings.addKey",
+            params: { providerId: "deepseek", key: "sk-invalid" },
+        });
+        expect(ctx.responses[0].error).toBeDefined();
+        expect(JSON.stringify(ctx.responses[0].error)).toContain("unauthorized");
+    });
+    it("validates Anthropic-compatible direct providers with the catalog technical base URL", async () => {
+        const seen = [];
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            seen.push(url);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "deepseek",
+                            name: "DeepSeek",
+                            baseUrl: "https://api.deepseek.com/anthropic",
+                            transport: "anthropic-messages",
+                            models: [{ id: "deepseek-v4-flash" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://api.deepseek.com/models") {
+                return new Response("not found", { status: 404 });
+            }
+            if (url === "https://api.deepseek.com/anthropic/v1/messages") {
+                return Response.json({ id: "msg-ok" });
+            }
+            return new Response("unexpected", { status: 500 });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsValidateKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 14,
+            method: "settings.validateKey",
+            params: {
+                providerId: "deepseek",
+                apiKey: "sk-valid",
+                baseUrl: "https://api.deepseek.com",
+            },
+        });
+        expect(ctx.responses[0].result).toMatchObject({
+            valid: true,
+            url: "https://api.deepseek.com/anthropic/v1/messages",
+        });
+        expect(seen).not.toContain("https://api.deepseek.com/v1/messages");
+    });
+    it("adds an LLMRouter API key using /v1/models only as visibility while preserving catalog metadata", async () => {
+        const seen = new Map();
+        vi.stubGlobal("fetch", vi.fn(async (input, init) => {
+            const url = String(input);
+            const auth = new Headers(init?.headers).get("authorization");
+            seen.set(url, auth);
+            if (url === "https://router.test/ext/model-catalog/providers") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "llmrouter",
+                            name: "LLMRouter",
+                            baseUrl: "https://router.test",
+                            transport: "openai-responses",
+                            models: [{ id: "deepseek-v4-flash" }, { id: "doubao-seedream-4-5" }],
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "deepseek-v4-flash",
+                            public_model: "deepseek-v4-flash",
+                            provider: "deepseek",
+                            native_model_id: "deepseek-v4-flash",
+                            display_name: "DeepSeek V4 Flash",
+                            purposes: ["textGeneration", "smallModel"],
+                            provider_transport: "anthropic-messages",
+                            context_window: 1000000,
+                            max_output: 384000,
+                            tool_call: true,
+                            stream_required: false,
+                            reasoning_mode: "collapsed",
+                            media_type: null,
+                        },
+                        {
+                            id: "doubao-seedream-4-5",
+                            public_model: "doubao-seedream-4-5",
+                            provider: "volcengine",
+                            native_model_id: "doubao-seedream-4-5-251128",
+                            display_name: "Doubao Seedream 4.5",
+                            purposes: ["imageGeneration"],
+                            provider_transport: "volcengine-responses",
+                            tool_call: false,
+                            stream_required: false,
+                            reasoning_mode: "none",
+                            media_type: "image",
+                        },
+                    ],
+                });
+            }
+            if (url === "https://router.test/v1/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "deepseek-v4-flash",
+                            owned_by: "deepseek",
+                        },
+                    ],
+                });
+            }
+            return new Response("not found", { status: 404 });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsAddKey.call(ctx, {
+            jsonrpc: "2.0",
+            id: 10,
+            method: "settings.addKey",
+            params: { providerId: "llmrouter", key: "sk-qllm-user" },
+        });
+        expect(ctx.responses[0].error).toBeUndefined();
+        expect(ctx.responses[0].result).toMatchObject({ ok: true, providerId: "llmrouter" });
+        expect(seen.get("https://router.test/v1/models")).toBe("Bearer sk-qllm-user");
+        expect(seen.get("https://router.test/ext/model-catalog/models")).toBe("Bearer token-123");
+        const saved = readSettings(home);
+        expect(saved.models).toContainEqual({ id: "llmrouter:deepseek-v4-flash", enabled: true });
+        expect(saved.models).not.toContainEqual({ id: "llmrouter:doubao-seedream-4-5", enabled: true });
+        expect(saved.bindings.textGeneration).toBe("llmrouter:deepseek-v4-flash");
+        expect(saved.bindings.imageGeneration).toBeUndefined();
+        const listCtx = rpcContext();
+        await handleSettingsListModels.call(listCtx, { jsonrpc: "2.0", id: 20, method: "settings.listModels" });
+        expect(listCtx.responses[0].result.models).toEqual([
+            expect.objectContaining({
+                id: "llmrouter:deepseek-v4-flash",
+                contextWindow: 1000000,
+                maxOutput: 384000,
+                toolCall: true,
+                streamRequired: false,
+                reasoningMode: "collapsed",
+                mediaType: null,
+            }),
+        ]);
+    });
+    it("keeps public model ids when the catalog includes a native upstream id", async () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "volcengine",
+                    baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-volcengine", key: "sk-test", weight: 1, enabled: true }],
+                },
+            ],
+            models: [{ id: "volcengine:doubao-seedream-4-5", enabled: false }],
+            bindings: { imageGeneration: "volcengine:doubao-seedream-4-5" },
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "doubao-seedream-4-5",
+                            public_model: "doubao-seedream-4-5",
+                            provider: "volcengine",
+                            native_model_id: "doubao-seedream-4-5-251128",
+                            display_name: "Doubao Seedream 4.5",
+                            purposes: ["imageGeneration"],
+                            provider_transport: "volcengine-responses",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsListModels.call(ctx, { jsonrpc: "2.0", id: 3, method: "settings.listModels" });
+        expect(ctx.responses[0].result.models).toEqual([
+            expect.objectContaining({
+                id: "volcengine:doubao-seedream-4-5",
+                model: "doubao-seedream-4-5",
+                nativeModelId: "doubao-seedream-4-5-251128",
+                displayName: "Doubao Seedream 4.5",
+                enabled: false,
+            }),
+        ]);
+        const saved = readSettings(home);
+        expect(saved.models).toEqual([
+            { id: "volcengine:doubao-seedream-4-5", enabled: false },
+            { id: "llmrouter:doubao-seedream-4-5", enabled: true },
+        ]);
+        expect(saved.bindings).toEqual({ imageGeneration: "volcengine:doubao-seedream-4-5" });
+    });
+    it("prunes stale native model ids instead of migrating through a local catalog", async () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "llmrouter",
+                    baseUrl: "https://router.test",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-llmrouter", key: "sk-test", weight: 1, enabled: true }],
+                },
+            ],
+            models: [{ id: "volcengine:doubao-seedream-4-5-251128", enabled: false }],
+            bindings: { imageGeneration: "volcengine:doubao-seedream-4-5-251128" },
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "doubao-seedream-4-5",
+                            public_model: "doubao-seedream-4-5",
+                            provider: "volcengine",
+                            native_model_id: "doubao-seedream-4-5-251128",
+                            display_name: "Doubao Seedream 4.5",
+                            purposes: ["imageGeneration"],
+                            provider_transport: "volcengine-responses",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsListModels.call(ctx, { jsonrpc: "2.0", id: 6, method: "settings.listModels" });
+        const saved = readSettings(home);
+        expect(saved.models).toEqual([
+            { id: "volcengine:doubao-seedream-4-5", enabled: true },
+            { id: "llmrouter:doubao-seedream-4-5", enabled: true },
+        ]);
+        expect(saved.bindings).toEqual({});
+    });
+    it("prunes stale model state that is no longer present in the llmrouter catalog", async () => {
+        writeSettings(home, {
+            providers: [
+                {
+                    providerId: "llmrouter",
+                    baseUrl: "https://router.test",
+                    strategy: "weighted-round-robin",
+                    keys: [{ id: "key-llmrouter", key: "sk-test", weight: 1, enabled: true }],
+                },
+            ],
+            models: [
+                { id: "qwen:qwen3.5-plus", enabled: false },
+                { id: "qwen:stale-models-dev-video-understanding", enabled: true },
+            ],
+            bindings: { videoUnderstanding: "qwen:stale-models-dev-video-understanding" },
+        });
+        vi.stubGlobal("fetch", vi.fn(async (input) => {
+            const url = String(input);
+            if (url === "https://router.test/ext/model-catalog/models") {
+                return Response.json({
+                    data: [
+                        {
+                            id: "qwen3.5-plus",
+                            public_model: "qwen3.5-plus",
+                            provider: "qwen",
+                            native_model_id: "qwen3.5-plus",
+                            display_name: "Qwen3.5 Plus",
+                            purposes: ["textGeneration", "imageUnderstanding"],
+                            provider_transport: "anthropic-messages",
+                        },
+                    ],
+                });
+            }
+            return Response.json({ data: [] });
+        }));
+        const ctx = rpcContext();
+        await handleSettingsListModels.call(ctx, { jsonrpc: "2.0", id: 7, method: "settings.listModels" });
+        const saved = readSettings(home);
+        expect(saved.models).toEqual([
+            { id: "qwen:qwen3.5-plus", enabled: false },
+            { id: "llmrouter:qwen3.5-plus", enabled: true },
+        ]);
+        expect(saved.bindings).toEqual({});
+        expect(JSON.stringify(saved)).not.toContain("stale-models-dev-video-understanding");
+    });
+});