@tokenbuddy/tokenbuddy 1.0.31 → 1.0.34

package/tests/control-plane-ui-endpoints.test.ts

@@ -6,6 +6,8 @@ import { TokenbuddyDaemon, type DaemonConfig } from "../src/daemon.js";
 import { DEFAULT_INIT_RECOMMENDED_MODELS } from "../src/init-setup.js";
 import type { SellerRegistryDocument } from "../src/seller-catalog.js";
 
+jest.setTimeout(30000);
+
 /**
  * tb-ui v1 (PR-0) 控制平面写端点集成测试。
  *
@@ -87,6 +89,24 @@ describe("TokenbuddyDaemon control-plane UI endpoints (PR-0)", () => {
     return `http://127.0.0.1:${controlPort}${path}`;
   }
 
+  function proxyUrl(path: string): string {
+    return `http://127.0.0.1:${proxyPort}${path}`;
+  }
+
+  async function startJsonServer(handler: http.RequestListener): Promise<{ server: http.Server; url: string }> {
+    const server = http.createServer(handler);
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address() as AddressInfo;
+    return {
+      server,
+      url: `http://127.0.0.1:${address.port}`
+    };
+  }
+
+  async function closeServer(server: http.Server): Promise<void> {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+
   beforeEach(async () => {
     await startDaemon();
   });
@@ -99,8 +119,76 @@ describe("TokenbuddyDaemon control-plane UI endpoints (PR-0)", () => {
     rmDb();
   });
 
+  function markClawtipReady(): void {
+    const store = (daemon as unknown as { tokenStore: { savePayment(input: unknown): void } }).tokenStore;
+    const configsDir = path.join(TEMP_HOME, ".openclaw", "configs");
+    fs.mkdirSync(configsDir, { recursive: true });
+    fs.writeFileSync(path.join(configsDir, "config.json"), "{}", "utf8");
+    store.savePayment({
+      method: "clawtip",
+      enabled: true,
+      isDefault: true,
+      config: {
+        resourceUrl: "https://tb-registry.example.test",
+        walletConfigPresent: true
+      }
+    });
+  }
+
   // ─── ClawTip payment QR endpoints ─────────────────────────────
   describe("ClawTip payment QR endpoints", () => {
+    it("selects a configured payment method as default", async () => {
+      const store = (daemon as unknown as { tokenStore: { savePayment(input: unknown): void; listPayments(): Array<{ method: string; isDefault: boolean }> } }).tokenStore;
+      store.savePayment({
+        method: "clawtip",
+        enabled: false,
+        isDefault: true,
+        config: {
+          walletConfigPresent: false
+        }
+      });
+      store.savePayment({
+        method: "invoice",
+        enabled: true,
+        isDefault: false,
+        config: {
+          walletConfigPresent: true
+        }
+      });
+
+      const res = await fetch(controlUrl("/payments/default"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ method: "invoice" })
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json() as { payments: Array<{ method: string; isDefault: boolean }> };
+      expect(body.payments.find((payment) => payment.method === "invoice")?.isDefault).toBe(true);
+      expect(body.payments.find((payment) => payment.method === "clawtip")?.isDefault).toBe(false);
+      expect(store.listPayments().find((payment) => payment.method === "invoice")?.isDefault).toBe(true);
+    });
+
+    it("rejects selecting an unbound payment method as default", async () => {
+      const store = (daemon as unknown as { tokenStore: { savePayment(input: unknown): void } }).tokenStore;
+      store.savePayment({
+        method: "invoice",
+        enabled: false,
+        isDefault: false,
+        config: {
+          walletConfigPresent: false
+        }
+      });
+
+      const res = await fetch(controlUrl("/payments/default"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ method: "invoice" })
+      });
+      expect(res.status).toBe(400);
+      const body = await res.json() as { error: { code: string } };
+      expect(body.error.code).toBe("payment_default_not_ready");
+    });
+
     it("reflects a renamed wallet config as unbound in /payments", async () => {
       const store = (daemon as unknown as { tokenStore: { savePayment(input: unknown): void } }).tokenStore;
       const configsDir = path.join(TEMP_HOME, ".openclaw", "configs");
@@ -627,6 +715,694 @@ describe("TokenbuddyDaemon control-plane UI endpoints (PR-0)", () => {
     });
   });
 
+  describe("provider mode and provider configs", () => {
+    it("defaults to manual mode and reports auto as locked without payment", async () => {
+      const res = await fetch(controlUrl("/routing/provider-mode"));
+      expect(res.status).toBe(200);
+      const body = await res.json() as {
+        mode: string;
+        manualEnabled: boolean;
+        autoEnabled: boolean;
+        paymentReady: boolean;
+        paymentRequired: boolean;
+        locked: { auto: boolean };
+      };
+      expect(body.mode).toBe("manual");
+      expect(body.manualEnabled).toBe(true);
+      expect(body.autoEnabled).toBe(false);
+      expect(body.paymentReady).toBe(false);
+      expect(body.paymentRequired).toBe(true);
+      expect(body.locked.auto).toBe(true);
+    });
+
+    it("rejects enabling auto mode until a non-mock payment is ready", async () => {
+      const res = await fetch(controlUrl("/routing/provider-mode"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ mode: "auto" })
+      });
+      expect(res.status).toBe(409);
+      const body = await res.json() as { error: { code: string }; bindTarget: string };
+      expect(body.error.code).toBe("payment_required");
+      expect(body.bindTarget).toBe("/overview?bind=clawtip");
+    });
+
+    it("enables auto mode after ClawTip is bound", async () => {
+      markClawtipReady();
+      const res = await fetch(controlUrl("/routing/provider-mode"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ mode: "auto" })
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json() as {
+        applied: boolean;
+        mode: string;
+        manualEnabled: boolean;
+        autoEnabled: boolean;
+        paymentReady: boolean;
+        paymentLabel?: string;
+      };
+      expect(body.applied).toBe(true);
+      expect(body.mode).toBe("auto");
+      expect(body.manualEnabled).toBe(false);
+      expect(body.autoEnabled).toBe(true);
+      expect(body.paymentReady).toBe(true);
+      expect(body.paymentLabel).toBe("ClawTip");
+    });
+
+    it("creates, lists, and deletes manual providers without exposing secret fields", async () => {
+      const createRes = await fetch(controlUrl("/routing/manual-providers"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          id: "local-openai",
+          name: "Local OpenAI",
+          baseUrl: "https://api.openai.example/v1/",
+          apiKeyEnv: "TB_TEST_PROVIDER_OPENAI_KEY",
+          models: ["gpt-4o", "gpt-4o"],
+          supportedProtocols: ["chat_completions"],
+          enabled: true
+        })
+      });
+      expect(createRes.status).toBe(201);
+      const created = await createRes.json() as {
+        provider: { id: string; baseUrl: string; keyRef?: { kind: string; name: string; configured: boolean }; apiKeyEnv?: string };
+      };
+      expect(created.provider.id).toBe("local-openai");
+      expect(created.provider.baseUrl).toBe("https://api.openai.example/v1");
+      expect(created.provider.keyRef).toEqual({
+        kind: "env",
+        name: "TB_TEST_PROVIDER_OPENAI_KEY",
+        configured: false
+      });
+      expect(created.provider.apiKeyEnv).toBeUndefined();
+
+      const listRes = await fetch(controlUrl("/routing/manual-providers"));
+      expect(listRes.status).toBe(200);
+      const listBody = await listRes.json() as { providers: Array<{ id: string; apiKeyEnv?: string }> };
+      expect(listBody.providers.map((provider) => provider.id)).toEqual(["local-openai"]);
+      expect(listBody.providers[0].apiKeyEnv).toBeUndefined();
+
+      const deleteRes = await fetch(controlUrl("/routing/manual-providers/local-openai"), { method: "DELETE" });
+      expect(deleteRes.status).toBe(200);
+      const afterDeleteRes = await fetch(controlUrl("/routing/manual-providers"));
+      const afterDelete = await afterDeleteRes.json() as { providers: unknown[] };
+      expect(afterDelete.providers).toEqual([]);
+    });
+
+    it("rejects manual providers with raw API keys", async () => {
+      const res = await fetch(controlUrl("/routing/manual-providers"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          id: "local-openai",
+          name: "Local OpenAI",
+          baseUrl: "https://api.openai.example/v1",
+          apiKey: "sk-secret",
+          models: ["gpt-4o"]
+        })
+      });
+      expect(res.status).toBe(400);
+      const body = await res.json() as { error: { code: string; message: string } };
+      expect(body.error.code).toBe("manual_provider_create_failed");
+      expect(body.error.message).toMatch(/raw apiKey/);
+      expect(body.error.message).not.toContain("sk-secret");
+    });
+
+    it("probes and creates a local manual provider without exposing the raw API key", async () => {
+      const providerKey = "provider-local-ui-key";
+      const provider = await startJsonServer((req, res) => {
+        expect(req.headers.authorization).toBe(`Bearer ${providerKey}`);
+        if (req.method === "GET" && req.url === "/v1/models") {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({
+            object: "list",
+            data: [
+              { id: "gpt-local-ui", object: "model" },
+              { id: "gpt-local-ui-fast", object: "model" }
+            ]
+          }));
+          return;
+        }
+        if (req.method === "POST" && req.url === "/v1/chat/completions") {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({
+            id: "chatcmpl-local-ui",
+            object: "chat.completion",
+            choices: [{ index: 0, message: { role: "assistant", content: "ok" }, finish_reason: "stop" }],
+            usage: { prompt_tokens: 4, completion_tokens: 3 }
+          }));
+          return;
+        }
+        res.writeHead(404, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "not found" } }));
+      });
+
+      try {
+        const probeRes = await fetch(controlUrl("/routing/manual-providers/probe"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            baseUrl: `${provider.url}/v1`,
+            apiKey: providerKey
+          })
+        });
+        expect(probeRes.status).toBe(200);
+        const probeBody = await probeRes.json() as { modelIds: string[] };
+        expect(probeBody.modelIds).toEqual(["gpt-local-ui", "gpt-local-ui-fast"]);
+
+        const createRes = await fetch(controlUrl("/routing/manual-providers/local"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            id: "local-ui",
+            name: "Local UI",
+            baseUrl: `${provider.url}/v1`,
+            apiKey: providerKey
+          })
+        });
+        expect(createRes.status).toBe(201);
+        const created = await createRes.json() as {
+          provider: { id: string; models: string[]; keyRef?: { kind: string; name: string; configured: boolean }; apiKey?: string };
+        };
+        expect(created.provider).toMatchObject({
+          id: "local-ui",
+          models: ["gpt-local-ui", "gpt-local-ui-fast"],
+          keyRef: { kind: "secret", name: "local:local-ui", configured: true }
+        });
+        expect(created.provider.apiKey).toBeUndefined();
+        expect(JSON.stringify(created)).not.toContain(providerKey);
+
+        const modelsRes = await fetch(proxyUrl("/v1/models"));
+        expect(modelsRes.status).toBe(200);
+        const models = await modelsRes.json() as { data: Array<{ id: string; sellerId: string }> };
+        expect(models.data).toEqual(expect.arrayContaining([
+          expect.objectContaining({ id: "gpt-local-ui", sellerId: "local-ui" })
+        ]));
+
+        const chatRes = await fetch(proxyUrl("/v1/chat/completions"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            model: "gpt-local-ui",
+            messages: [{ role: "user", content: "hello" }]
+          })
+        });
+        expect(chatRes.status).toBe(200);
+      } finally {
+        await closeServer(provider.server);
+      }
+    });
+
+    it("updates a local manual provider using the stored secret", async () => {
+      const providerKey = "provider-local-edit-key";
+      const provider = await startJsonServer((req, res) => {
+        expect(req.headers.authorization).toBe(`Bearer ${providerKey}`);
+        if (req.method === "GET" && req.url === "/v1/models") {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({
+            object: "list",
+            data: [
+              { id: "gpt-local-edited", object: "model" },
+              { id: "gpt-local-edited-fast", object: "model" }
+            ]
+          }));
+          return;
+        }
+        res.writeHead(404, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "not found" } }));
+      });
+
+      try {
+        const createRes = await fetch(controlUrl("/routing/manual-providers/local"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            id: "local-edit",
+            name: "Local Edit",
+            baseUrl: `${provider.url}/v1`,
+            apiKey: providerKey
+          })
+        });
+        expect(createRes.status).toBe(201);
+
+        const updateRes = await fetch(controlUrl("/routing/manual-providers/local/local-edit"), {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            name: "Local Edited",
+            baseUrl: `${provider.url}/v1`
+          })
+        });
+        expect(updateRes.status).toBe(200);
+        const updated = await updateRes.json() as {
+          provider: { id: string; name: string; models: string[]; keyRef?: { kind: string; name: string; configured: boolean }; apiKey?: string };
+        };
+        expect(updated.provider).toMatchObject({
+          id: "local-edit",
+          name: "Local Edited",
+          models: ["gpt-local-edited", "gpt-local-edited-fast"],
+          keyRef: { kind: "secret", name: "local:local-edit", configured: true }
+        });
+        expect(updated.provider.apiKey).toBeUndefined();
+        expect(JSON.stringify(updated)).not.toContain(providerKey);
+      } finally {
+        await closeServer(provider.server);
+      }
+    });
+
+    it("blocks local manual provider creation when model probing fails", async () => {
+      const providerKey = "provider-local-bad-key";
+      const provider = await startJsonServer((_req, res) => {
+        res.writeHead(401, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "unauthorized" } }));
+      });
+
+      try {
+        const createRes = await fetch(controlUrl("/routing/manual-providers/local"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            id: "local-bad",
+            name: "Local Bad",
+            baseUrl: `${provider.url}/v1`,
+            apiKey: providerKey
+          })
+        });
+        expect(createRes.status).toBe(400);
+        const body = await createRes.json() as { error: { code: string; message: string } };
+        expect(body.error.code).toBe("manual_provider_local_create_failed");
+        expect(body.error.message).toContain("authentication failed");
+        expect(body.error.message).not.toContain(providerKey);
+
+        const listRes = await fetch(controlUrl("/routing/manual-providers"));
+        const listBody = await listRes.json() as { providers: unknown[] };
+        expect(listBody.providers).toEqual([]);
+      } finally {
+        await closeServer(provider.server);
+      }
+    });
+
+    it("saves disabled auto provider drafts without payment but gates enabled configs", async () => {
+      const draftRes = await fetch(controlUrl("/routing/auto-provider"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          enabled: false,
+          range: "custom",
+          scorer: "discount",
+          modelIds: ["gpt-4o"],
+          sellerIds: ["tbs-86d81e"]
+        })
+      });
+      expect(draftRes.status).toBe(200);
+      const draft = await draftRes.json() as { config: { enabled: boolean; range: string; maxConcurrentProviders: number }; paymentRequired: boolean };
+      expect(draft.config.enabled).toBe(false);
+      expect(draft.config.range).toBe("custom");
+      expect(draft.config.maxConcurrentProviders).toBe(10);
+      expect(draft.paymentRequired).toBe(true);
+
+      const blockedRes = await fetch(controlUrl("/routing/auto-provider"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          enabled: true,
+          range: "recommended",
+          scorer: "balanced",
+          modelIds: ["gpt-4o"]
+        })
+      });
+      expect(blockedRes.status).toBe(409);
+      const blocked = await blockedRes.json() as { error: { code: string } };
+      expect(blocked.error.code).toBe("payment_required");
+    });
+
+    it("applies enabled auto provider configs to the active routing strategy", async () => {
+      markClawtipReady();
+
+      const emptyCustomRes = await fetch(controlUrl("/routing/auto-provider"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          enabled: true,
+          range: "custom",
+          scorer: "balanced",
+          modelIds: ["gpt-4o"],
+          sellerIds: []
+        })
+      });
+      expect(emptyCustomRes.status).toBe(200);
+      const emptyCustom = await emptyCustomRes.json() as { config: { enabled: boolean; range: string; sellerIds: string[] }; autoEnabled: boolean; strategy?: unknown };
+      expect(emptyCustom.config).toMatchObject({ enabled: false, range: "custom", sellerIds: [] });
+      expect(emptyCustom.autoEnabled).toBe(false);
+      expect(emptyCustom.strategy).toBeUndefined();
+
+      const emptyCustomModeRes = await fetch(controlUrl("/routing/provider-mode"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ mode: "auto" })
+      });
+      expect(emptyCustomModeRes.status).toBe(200);
+      const emptyCustomMode = await emptyCustomModeRes.json() as { autoEnabled: boolean; strategy?: unknown };
+      expect(emptyCustomMode.autoEnabled).toBe(false);
+      expect(emptyCustomMode.strategy).toBeUndefined();
+
+      const recommendedRes = await fetch(controlUrl("/routing/auto-provider"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          enabled: true,
+          range: "recommended",
+          scorer: "speed",
+          modelIds: ["gpt-4o"]
+        })
+      });
+      expect(recommendedRes.status).toBe(200);
+      const recommended = await recommendedRes.json() as { strategy: { mode: string; scorer: string }; mode: string; autoEnabled: boolean };
+      expect(recommended.mode).toBe("auto");
+      expect(recommended.autoEnabled).toBe(true);
+      expect(recommended.strategy).toMatchObject({ mode: "fullAuto", scorer: "speed" });
+
+      const customRes = await fetch(controlUrl("/routing/auto-provider"), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          enabled: true,
+          range: "custom",
+          scorer: "discount",
+          modelIds: ["gpt-4o"],
+          sellerIds: ["tbs-86d81e", "tbs-719577"]
+        })
+      });
+      expect(customRes.status).toBe(200);
+      const custom = await customRes.json() as { strategy: { mode: string; scorer: string; sellerIds?: string[] } };
+      expect(custom.strategy).toMatchObject({
+        mode: "fixedSet",
+        scorer: "discount",
+        sellerIds: ["tbs-86d81e", "tbs-719577"]
+      });
+
+      const strategyRes = await fetch(controlUrl("/routing/strategy"));
+      const strategy = await strategyRes.json() as { strategy: { mode: string; scorer: string; sellerIds?: string[] } };
+      expect(strategy.strategy).toMatchObject({
+        mode: "fixedSet",
+        scorer: "discount",
+        sellerIds: ["tbs-86d81e", "tbs-719577"]
+      });
+    });
+
+    it("routes manual provider requests with ordered fallback and records local observations", async () => {
+      const previousA = process.env.TB_TEST_PROVIDER_A_KEY;
+      const previousB = process.env.TB_TEST_PROVIDER_B_KEY;
+      process.env.TB_TEST_PROVIDER_A_KEY = "provider-a-test-key";
+      process.env.TB_TEST_PROVIDER_B_KEY = "provider-b-test-key";
+
+      const providerA = await startJsonServer((req, res) => {
+        expect(req.headers.authorization).toBe("Bearer provider-a-test-key");
+        res.writeHead(500, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "temporary upstream failure" } }));
+      });
+      const providerB = await startJsonServer((req, res) => {
+        expect(req.headers.authorization).toBe("Bearer provider-b-test-key");
+        let body = "";
+        req.on("data", (chunk) => {
+          body += chunk.toString("utf8");
+        });
+        req.on("end", () => {
+          const parsed = JSON.parse(body) as { model: string };
+          expect(parsed.model).toBe("gpt-manual");
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({
+            id: "chatcmpl-manual",
+            object: "chat.completion",
+            choices: [{ index: 0, message: { role: "assistant", content: "ok" }, finish_reason: "stop" }],
+            usage: { prompt_tokens: 3, completion_tokens: 2 }
+          }));
+        });
+      });
+
+      try {
+        for (const provider of [
+          { id: "local-a", name: "Local A", baseUrl: `${providerA.url}/v1`, apiKeyEnv: "TB_TEST_PROVIDER_A_KEY" },
+          { id: "local-b", name: "Local B", baseUrl: `${providerB.url}/v1`, apiKeyEnv: "TB_TEST_PROVIDER_B_KEY" }
+        ]) {
+          const createRes = await fetch(controlUrl("/routing/manual-providers"), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              ...provider,
+              models: ["gpt-manual"],
+              supportedProtocols: ["chat_completions"],
+              enabled: true
+            })
+          });
+          expect(createRes.status).toBe(201);
+        }
+
+        const modelsRes = await fetch(proxyUrl("/v1/models"));
+        expect(modelsRes.status).toBe(200);
+        const models = await modelsRes.json() as { data: Array<{ id: string; sellerId: string; paymentMethods: string[] }> };
+        expect(models.data.map((model) => [model.id, model.sellerId, model.paymentMethods[0]])).toEqual([
+          ["gpt-manual", "local-a", "provider_key"],
+          ["gpt-manual", "local-b", "provider_key"]
+        ]);
+
+        const response = await fetch(proxyUrl("/v1/chat/completions"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            model: "gpt-manual",
+            messages: [{ role: "user", content: "hello" }]
+          })
+        });
+        expect(response.status).toBe(200);
+        const body = await response.json() as { choices: unknown[] };
+        expect(body.choices.length).toBe(1);
+
+        const purchases = await (await fetch(controlUrl("/ledger/purchases"))).json() as { purchases: unknown[] };
+        expect(purchases.purchases).toEqual([]);
+        const inferences = await (await fetch(controlUrl("/ledger/inferences"))).json() as {
+          inferences: Array<{ sellerKey: string; paymentMethod?: string; priceVersion?: string; routeReason?: string; fallbackCount?: number }>;
+        };
+        expect(inferences.inferences).toHaveLength(1);
+        expect(inferences.inferences[0]).toMatchObject({
+          sellerKey: "local-b",
+          paymentMethod: "provider_key",
+          priceVersion: "local-provider:local-b",
+          routeReason: "manual:fallback:routes_2",
+          fallbackCount: 1
+        });
+
+        const providersRes = await fetch(controlUrl("/routing/manual-providers"));
+        const providersBody = await providersRes.json() as {
+          providers: Array<{ id: string; current?: boolean; lastAccess?: string; status?: string; errorClass?: string }>;
+        };
+        expect(providersBody.providers).toEqual([
+          expect.objectContaining({ id: "local-a", current: false, status: "degraded", errorClass: "upstream_5xx" }),
+          expect.objectContaining({ id: "local-b", current: true, status: "healthy" })
+        ]);
+        expect(providersBody.providers[0].lastAccess).toBeTruthy();
+        expect(providersBody.providers[1].lastAccess).toBeTruthy();
+      } finally {
+        await closeServer(providerA.server);
+        await closeServer(providerB.server);
+        if (previousA === undefined) {
+          delete process.env.TB_TEST_PROVIDER_A_KEY;
+        } else {
+          process.env.TB_TEST_PROVIDER_A_KEY = previousA;
+        }
+        if (previousB === undefined) {
+          delete process.env.TB_TEST_PROVIDER_B_KEY;
+        } else {
+          process.env.TB_TEST_PROVIDER_B_KEY = previousB;
+        }
+      }
+    });
+
+    it("locks manual routing to one provider without falling back", async () => {
+      const previousA = process.env.TB_TEST_PROVIDER_LOCK_A_KEY;
+      const previousB = process.env.TB_TEST_PROVIDER_LOCK_B_KEY;
+      process.env.TB_TEST_PROVIDER_LOCK_A_KEY = "provider-lock-a-key";
+      process.env.TB_TEST_PROVIDER_LOCK_B_KEY = "provider-lock-b-key";
+      let providerBHits = 0;
+
+      const providerA = await startJsonServer((req, res) => {
+        expect(req.headers.authorization).toBe("Bearer provider-lock-a-key");
+        res.writeHead(500, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "locked upstream failed" } }));
+      });
+      const providerB = await startJsonServer((req, res) => {
+        providerBHits += 1;
+        expect(req.headers.authorization).toBe("Bearer provider-lock-b-key");
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({
+          id: "chatcmpl-should-not-use-backup",
+          object: "chat.completion",
+          choices: [{ index: 0, message: { role: "assistant", content: "backup" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 1, completion_tokens: 1 }
+        }));
+      });
+
+      try {
+        for (const provider of [
+          { id: "lock-a", name: "Lock A", baseUrl: `${providerA.url}/v1`, apiKeyEnv: "TB_TEST_PROVIDER_LOCK_A_KEY" },
+          { id: "lock-b", name: "Lock B", baseUrl: `${providerB.url}/v1`, apiKeyEnv: "TB_TEST_PROVIDER_LOCK_B_KEY" }
+        ]) {
+          const createRes = await fetch(controlUrl("/routing/manual-providers"), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              ...provider,
+              models: ["gpt-locked"],
+              supportedProtocols: ["chat_completions"],
+              enabled: true
+            })
+          });
+          expect(createRes.status).toBe(201);
+        }
+
+        const lockRes = await fetch(controlUrl("/routing/manual-providers/routing"), {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ policy: "locked", lockedProviderId: "lock-a" })
+        });
+        expect(lockRes.status).toBe(200);
+        const lockBody = await lockRes.json() as { routing: { policy: string; lockedProviderId?: string } };
+        expect(lockBody.routing).toEqual({ policy: "locked", lockedProviderId: "lock-a" });
+
+        const response = await fetch(proxyUrl("/v1/chat/completions"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            model: "gpt-locked",
+            messages: [{ role: "user", content: "hello" }]
+          })
+        });
+        expect(response.status).toBe(500);
+        expect(providerBHits).toBe(0);
+
+        const providersRes = await fetch(controlUrl("/routing/manual-providers"));
+        const providersBody = await providersRes.json() as {
+          routing: { policy: string; lockedProviderId?: string };
+          providers: Array<{ id: string; current?: boolean; status?: string; errorClass?: string }>;
+        };
+        expect(providersBody.routing).toEqual({ policy: "locked", lockedProviderId: "lock-a" });
+        expect(providersBody.providers).toEqual([
+          expect.objectContaining({ id: "lock-a", current: false, status: "degraded", errorClass: "upstream_5xx" }),
+          expect.objectContaining({ id: "lock-b" })
+        ]);
+
+        const fallbackRes = await fetch(controlUrl("/routing/manual-providers/routing"), {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ policy: "fallback" })
+        });
+        expect(fallbackRes.status).toBe(200);
+        const fallbackBody = await fallbackRes.json() as { routing: { policy: string; lockedProviderId?: string } };
+        expect(fallbackBody.routing).toEqual({ policy: "fallback" });
+      } finally {
+        await closeServer(providerA.server);
+        await closeServer(providerB.server);
+        if (previousA === undefined) {
+          delete process.env.TB_TEST_PROVIDER_LOCK_A_KEY;
+        } else {
+          process.env.TB_TEST_PROVIDER_LOCK_A_KEY = previousA;
+        }
+        if (previousB === undefined) {
+          delete process.env.TB_TEST_PROVIDER_LOCK_B_KEY;
+        } else {
+          process.env.TB_TEST_PROVIDER_LOCK_B_KEY = previousB;
+        }
+      }
+    });
+
+    it("reorders manual provider fallback priority", async () => {
+      const previousA = process.env.TB_TEST_PROVIDER_ORDER_A_KEY;
+      const previousB = process.env.TB_TEST_PROVIDER_ORDER_B_KEY;
+      process.env.TB_TEST_PROVIDER_ORDER_A_KEY = "provider-order-a-key";
+      process.env.TB_TEST_PROVIDER_ORDER_B_KEY = "provider-order-b-key";
+      let providerAHits = 0;
+      let providerBHits = 0;
+
+      const providerA = await startJsonServer((req, res) => {
+        providerAHits += 1;
+        expect(req.headers.authorization).toBe("Bearer provider-order-a-key");
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({
+          id: "chatcmpl-order-a",
+          object: "chat.completion",
+          choices: [{ index: 0, message: { role: "assistant", content: "a" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 1, completion_tokens: 1 }
+        }));
+      });
+      const providerB = await startJsonServer((req, res) => {
+        providerBHits += 1;
+        expect(req.headers.authorization).toBe("Bearer provider-order-b-key");
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({
+          id: "chatcmpl-order-b",
+          object: "chat.completion",
+          choices: [{ index: 0, message: { role: "assistant", content: "b" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 1, completion_tokens: 1 }
+        }));
+      });
+
+      try {
+        for (const provider of [
+          { id: "order-a", name: "Order A", baseUrl: `${providerA.url}/v1`, apiKeyEnv: "TB_TEST_PROVIDER_ORDER_A_KEY" },
+          { id: "order-b", name: "Order B", baseUrl: `${providerB.url}/v1`, apiKeyEnv: "TB_TEST_PROVIDER_ORDER_B_KEY" }
+        ]) {
+          const createRes = await fetch(controlUrl("/routing/manual-providers"), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              ...provider,
+              models: ["gpt-order"],
+              supportedProtocols: ["chat_completions"],
+              enabled: true
+            })
+          });
+          expect(createRes.status).toBe(201);
+        }
+
+        const orderRes = await fetch(controlUrl("/routing/manual-providers/order"), {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ providerIds: ["order-b", "order-a"] })
+        });
+        expect(orderRes.status).toBe(200);
+        const orderBody = await orderRes.json() as { providers: Array<{ id: string }> };
+        expect(orderBody.providers.map((provider) => provider.id)).toEqual(["order-b", "order-a"]);
+
+        const response = await fetch(proxyUrl("/v1/chat/completions"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            model: "gpt-order",
+            messages: [{ role: "user", content: "hello" }]
+          })
+        });
+        expect(response.status).toBe(200);
+        expect(providerBHits).toBe(1);
+        expect(providerAHits).toBe(0);
+      } finally {
+        await closeServer(providerA.server);
+        await closeServer(providerB.server);
+        if (previousA === undefined) {
+          delete process.env.TB_TEST_PROVIDER_ORDER_A_KEY;
+        } else {
+          process.env.TB_TEST_PROVIDER_ORDER_A_KEY = previousA;
+        }
+        if (previousB === undefined) {
+          delete process.env.TB_TEST_PROVIDER_ORDER_B_KEY;
+        } else {
+          process.env.TB_TEST_PROVIDER_ORDER_B_KEY = previousB;
+        }
+      }
+    });
+  });
+
   // ─── GET /routing/strategy ────────────────────────────────────
   describe("GET /routing/strategy", () => {
     it("returns default strategy with source=default when no store value", async () => {