feat: add Freebuff provider and fix dompurify security vulnerabilities

- Add Freebuff provider integration (executor, registry, OAuth, usage tracking) - Upgrade monaco-editor to ^0.56.0 - Add dompurify ^3.4.13 with override to fix security vulnerabilities - Add Freebuff provider icon and test files
2026-08-06 00:30:06 +08:00
parent 15223724c3
commit 8343d54bf2
8 changed files with 1586 additions and 1 deletions
@@ -0,0 +1,588 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import freebuff from "../../src/lib/oauth/providers/freebuff.js";
+
+// Mock proxyAwareFetch so session/run/chat flows never hit the network.
+const fetchMock = vi.fn();
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: (...args) => fetchMock(...args),
+}));
+
+import { FreebuffExecutor, __test__ } from "../../open-sse/executors/freebuff.js";
+
+const {
+  ensureSession,
+  requestSession,
+  startRun,
+  resetSessionCache,
+  rootAgentIdForModel,
+  injectFreebuffMarker,
+  FREEBUFF_SYSTEM_MARKER,
+} = __test__;
+
+const CONFIG = {
+  baseUrl: "https://freebuff.com",
+  loginCodePath: "/api/auth/cli/code",
+  loginStatusPath: "/api/auth/cli/status",
+};
+
+function jsonResponse(data, { ok = true, status = 200 } = {}) {
+  return {
+    ok,
+    status,
+    json: async () => data,
+    text: async () => JSON.stringify(data),
+  };
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+beforeEach(() => {
+  fetchMock.mockReset();
+  resetSessionCache();
+});
+
+describe("freebuff oauth flow", () => {
+  it("requestDeviceCode posts a fingerprint to the freebuff.com login host and surfaces the login URL", async () => {
+    const loginUrl = "https://freebuff.com/login?auth_code=AbCd-123";
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          fingerprintId: "fp-1",
+          fingerprintHash: "hash-1",
+          loginUrl,
+          expiresAt: Date.now() + 60000,
+        }),
+      }),
+    );
+    const out = await freebuff.requestDeviceCode(CONFIG);
+    expect(out.verification_uri_complete).toBe(loginUrl);
+    expect(out.user_code).toBe("AbCd-123");
+    expect(out.interval).toBe(5);
+    expect(out.expires_in).toBe(60);
+    // The server echoes the request host into loginUrl — it must be freebuff.com,
+    // not www.codebuff.com, to match the official CLI's login link.
+    const [url] = global.fetch.mock.calls[0];
+    expect(url.startsWith("https://freebuff.com/api/auth/cli/code")).toBe(true);
+    const payload = JSON.parse(out.device_code);
+    expect(payload.fingerprintId).toBe("fp-1");
+    expect(payload.fingerprintHash).toBe("hash-1");
+  });
+
+  it("requestDeviceCode falls back to oauthTimeoutMs when the server omits expiresAt", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          fingerprintId: "fp-1",
+          fingerprintHash: "hash-1",
+          loginUrl: "https://freebuff.com/login?auth_code=Ab",
+          // no expiresAt — must NOT collapse to the 60s floor
+        }),
+      }),
+    );
+    const out = await freebuff.requestDeviceCode(CONFIG);
+    expect(out.expires_in).toBe(300);
+  });
+
+  it("requestDeviceCode leaves user_code empty when loginUrl has no auth_code", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          fingerprintId: "fp-1",
+          fingerprintHash: "hash-1",
+          loginUrl: "https://freebuff.com/login",
+          expiresAt: Date.now() + 60000,
+        }),
+      }),
+    );
+    const out = await freebuff.requestDeviceCode(CONFIG);
+    expect(out.user_code).toBe("");
+  });
+
+  it("requestDeviceCode clamps expires_in to oauthTimeoutMs", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          fingerprintId: "fp-1",
+          fingerprintHash: "hash-1",
+          loginUrl: "https://freebuff.com/login?auth_code=Ab",
+          // server-side codes live ~1h; the modal deadline must stay at 5 min
+          expiresAt: Date.now() + 3600000,
+        }),
+      }),
+    );
+    const out = await freebuff.requestDeviceCode(CONFIG);
+    expect(out.expires_in).toBe(300);
+  });
+
+  it("pollToken keeps polling on 401 pending (GET with query params)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 401,
+        json: async () => ({ error: "Authentication failed" }),
+      }),
+    );
+    const res = await freebuff.pollToken(
+      CONFIG,
+      JSON.stringify({ fingerprintId: "fp-1", fingerprintHash: "h", expiresAt: 123 }),
+    );
+    expect(res.ok).toBe(true);
+    expect(res.data.error).toBe("authorization_pending");
+    const [url, opts] = global.fetch.mock.calls[0];
+    expect(url).toContain("https://freebuff.com/api/auth/cli/status?");
+    expect(url).toContain("fingerprintId=fp-1");
+    expect(opts.method).toBe("GET");
+  });
+
+  it("pollToken returns the authToken on success", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          user: { id: "u1", email: "a@b.c", name: "A", authToken: "tok-123", fingerprintId: "fp-1" },
+        }),
+      }),
+    );
+    const res = await freebuff.pollToken(
+      CONFIG,
+      JSON.stringify({ fingerprintId: "fp-1", fingerprintHash: "h", expiresAt: 123 }),
+    );
+    expect(res.data.access_token).toBe("tok-123");
+  });
+
+  it("mapTokens stores accessToken + identity", () => {
+    const t = freebuff.mapTokens({
+      access_token: "tok",
+      email: "a@b.c",
+      name: "A",
+      id: "u1",
+      fingerprintId: "fp",
+    });
+    expect(t.accessToken).toBe("tok");
+    expect(t.email).toBe("a@b.c");
+    expect(t.displayName).toBe("A");
+    expect(t.refreshToken).toBeNull();
+    expect(t.providerSpecificData.fingerprintId).toBe("fp");
+    expect(t.providerSpecificData.authMethod).toBe("device_code");
+  });
+});
+
+describe("freebuff executor wire shape", () => {
+  it("injects codebuff_metadata at TOP LEVEL (mirrors the CLI, not nested under codebuff)", () => {
+    const ex = new FreebuffExecutor();
+    const body = { model: "deepseek/deepseek-v4-flash", messages: [{ role: "user", content: "hi" }] };
+    const out = ex.transformRequest(body.model, body, true, {
+      providerSpecificData: { fingerprintId: "fp-1" },
+    });
+    // Top-level keys — the backend rejects the nested shape with
+    // "No runId found in request body".
+    expect(out.codebuff_metadata.cost_mode).toBe("free");
+    expect(out.codebuff_metadata.client_id).toBe("fp-1");
+    // run_id is the registered runId and is attached by execute(), not here.
+    expect(out.codebuff_metadata.run_id).toBeUndefined();
+    expect(out.codebuff).toBeUndefined();
+    expect(out.provider.allow_fallbacks).toBe(false);
+    // Free-tier marker is prepended so the first message opens with the CLI root prompt.
+    expect(out.messages[0].content).toBe(FREEBUFF_SYSTEM_MARKER);
+  });
+
+  it("buildUrl targets the Codebuff chat completions endpoint (www.codebuff.com)", () => {
+    const ex = new FreebuffExecutor();
+    expect(ex.buildUrl()).toBe("https://www.codebuff.com/api/v1/chat/completions");
+  });
+});
+
+describe("freebuff session pre-flight", () => {
+  it("claims a session via POST /session with x-freebuff-model and caches it per token+model", async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse({
+        status: "active",
+        instanceId: "inst-1",
+        model: "deepseek/deepseek-v4-flash",
+        expiresAt: new Date(Date.now() + 3600000).toISOString(),
+      }),
+    );
+    const first = await ensureSession("tok-1", "deepseek/deepseek-v4-flash", null);
+    expect(first).toEqual({ instanceId: "inst-1", status: "active" });
+
+    const [url, opts] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://www.codebuff.com/api/v1/freebuff/session");
+    expect(opts.method).toBe("POST");
+    expect(opts.headers["x-freebuff-model"]).toBe("deepseek/deepseek-v4-flash");
+    expect(opts.headers.Authorization).toBe("Bearer tok-1");
+
+    // Second call for the same token+model hits the cache — no new claim.
+    await ensureSession("tok-1", "deepseek/deepseek-v4-flash", null);
+    expect(fetchMock.mock.calls.length).toBe(1);
+
+    // Different model → separate claim.
+    fetchMock.mockResolvedValue(
+      jsonResponse({ status: "active", instanceId: "inst-2", expiresAt: new Date(Date.now() + 3600000).toISOString() }),
+    );
+    await ensureSession("tok-1", "minimax/minimax-m3", null);
+    expect(fetchMock.mock.calls.length).toBe(2);
+  });
+
+  it("treats status none as no-session-needed (instanceId null)", async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ status: "none", accessTier: "full" }));
+    const res = await ensureSession("tok-1", "deepseek/deepseek-v4-flash", null);
+    expect(res).toEqual({ instanceId: null, status: "none" });
+  });
+
+  it("throws a friendly error on rate_limited", async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse({ status: "rate_limited", message: "4 of 6 sessions used today" }),
+    );
+    await expect(ensureSession("tok-1", "deepseek/deepseek-v4-flash", null)).rejects.toThrow(
+      /session limit reached/i,
+    );
+  });
+
+  it("throws a friendly error on country_blocked", async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ status: "country_blocked" }));
+    await expect(ensureSession("tok-1", "deepseek/deepseek-v4-flash", null)).rejects.toThrow(
+      /not available in your region/i,
+    );
+  });
+
+  it("throws a 401 re-login error when the session endpoint rejects the token", async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ error: "unauthorized" }, { status: 401, ok: false }));
+    await expect(requestSession("tok-expired", "deepseek/deepseek-v4-flash", null)).rejects.toThrow(/re-login/i);
+  });
+});
+
+describe("freebuff free-tier system marker", () => {
+  it("prepends the canonical marker when the first message is a system prompt", () => {
+    const out = injectFreebuffMarker({
+      messages: [{ role: "system", content: "You are a helpful assistant." }, { role: "user", content: "hi" }],
+    });
+    expect(out.messages[0].content).toBe(`${FREEBUFF_SYSTEM_MARKER}\n\nYou are a helpful assistant.`);
+    expect(out.messages[1].role).toBe("user");
+  });
+
+  it("inserts a marker system message when the first message is not a system prompt", () => {
+    const out = injectFreebuffMarker({ messages: [{ role: "user", content: "hi" }] });
+    expect(out.messages[0]).toEqual({ role: "system", content: FREEBUFF_SYSTEM_MARKER });
+    expect(out.messages[1]).toEqual({ role: "user", content: "hi" });
+  });
+
+  it("is idempotent when the first system message already opens with the marker", () => {
+    const messages = [{ role: "system", content: FREEBUFF_SYSTEM_MARKER }];
+    const out = injectFreebuffMarker({ messages });
+    expect(out.messages).toBe(messages);
+  });
+
+  it("inserts a marker system message when the first system content is a block array", () => {
+    const out = injectFreebuffMarker({
+      messages: [{ role: "system", content: [{ type: "text", text: "hi" }] }, { role: "user", content: "x" }],
+    });
+    expect(out.messages[0]).toEqual({ role: "system", content: FREEBUFF_SYSTEM_MARKER });
+    expect(out.messages[1].content).toEqual([{ type: "text", text: "hi" }]);
+    expect(out.messages[2].content).toBe("x");
+  });
+});
+
+describe("freebuff run registration", () => {
+  it("maps freebuff models to their root free agent ids", () => {
+    expect(rootAgentIdForModel("deepseek/deepseek-v4-flash")).toBe("base2-free-deepseek-flash");
+    expect(rootAgentIdForModel("deepseek/deepseek-v4-pro")).toBe("base2-free-deepseek");
+    expect(rootAgentIdForModel("mimo/mimo-v2.5")).toBe("base2-free-mimo");
+    expect(rootAgentIdForModel("minimax/minimax-m3")).toBe("base2-free-minimax-m3");
+    expect(rootAgentIdForModel("openai/gpt-5.6-luna")).toBe("base2-free-luna");
+    expect(rootAgentIdForModel("some/unknown-model")).toBe("base2-free");
+  });
+
+  it("registers a run via POST /agent-runs and returns the runId", async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ runId: "run-abc" }));
+    const runId = await startRun("tok-1", "deepseek/deepseek-v4-flash", null);
+    expect(runId).toBe("run-abc");
+
+    const [url, opts] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://www.codebuff.com/api/v1/agent-runs");
+    expect(opts.method).toBe("POST");
+    expect(opts.headers.Authorization).toBe("Bearer tok-1");
+    const payload = JSON.parse(opts.body);
+    expect(payload.action).toBe("START");
+    expect(payload.agentId).toBe("base2-free-deepseek-flash");
+    expect(payload.ancestorRunIds).toEqual([]);
+  });
+
+  it("throws when the run start fails", async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ error: "bad" }, { status: 500, ok: false }));
+    await expect(startRun("tok-1", "deepseek/deepseek-v4-flash", null)).rejects.toThrow(/run start failed/i);
+  });
+
+  it("retries transient network errors on run registration", async () => {
+    fetchMock.mockImplementation(async (url) => {
+      if (url.includes("/agent-runs")) {
+        const calls = fetchMock.mock.calls.filter(([u]) => u.includes("/agent-runs")).length;
+        if (calls === 1) throw new Error("fetch failed (cause: ECONNRESET)");
+        return jsonResponse({ runId: "run-retried" });
+      }
+      throw new Error("unexpected url");
+    });
+    const runId = await startRun("tok-1", "deepseek/deepseek-v4-flash", null);
+    expect(runId).toBe("run-retried");
+  });
+});
+
+describe("freebuff executor execute", () => {
+  const CHAT_URL = "https://www.codebuff.com/api/v1/chat/completions";
+  const SESSION_URL = "https://www.codebuff.com/api/v1/freebuff/session";
+  const RUN_URL = "https://www.codebuff.com/api/v1/agent-runs";
+  const MODEL = "deepseek/deepseek-v4-flash";
+  const credentials = { accessToken: "tok-1", providerSpecificData: { fingerprintId: "fp-1" } };
+
+  // Default happy-path backend: session active, run registered, chat 200.
+  const happyPath = () => {
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) {
+        return jsonResponse({ status: "active", instanceId: "inst-1", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      }
+      if (url === RUN_URL) {
+        return jsonResponse({ runId: "run-1" });
+      }
+      return jsonResponse({ choices: [{ message: { content: "hi" } }] });
+    });
+  };
+
+  it("sends the registered runId + session instance id on the chat request", async () => {
+    happyPath();
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    const { response } = await ex.execute({ model: MODEL, body, stream: false, credentials, log: null });
+
+    expect(response.status).toBe(200);
+    const chatCall = fetchMock.mock.calls.find(([u]) => u === CHAT_URL);
+    expect(chatCall).toBeTruthy();
+    const sent = JSON.parse(chatCall[1].body);
+    expect(sent.codebuff_metadata.run_id).toBe("run-1");
+    expect(sent.codebuff_metadata.freebuff_instance_id).toBe("inst-1");
+    expect(sent.codebuff_metadata.trace_session_id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+    expect(sent.codebuff_metadata.cost_mode).toBe("free");
+    expect(sent.codebuff_metadata.client_id).toBe("fp-1");
+    expect(sent.codebuff).toBeUndefined();
+    // Free-tier marker present at position 0 of the request body.
+    expect(sent.messages[0].content.startsWith("You are Buffy,")).toBe(true);
+  });
+
+  it("retries exactly once on 428 with a fresh session AND a fresh run", async () => {
+    let chatHits = 0;
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) {
+        return jsonResponse({ status: "active", instanceId: "inst-2", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      }
+      if (url === RUN_URL) {
+        return jsonResponse({ runId: "run-2" });
+      }
+      chatHits += 1;
+      if (chatHits === 1) return jsonResponse({ error: "waiting_room_required" }, { status: 428, ok: false });
+      return jsonResponse({ choices: [{ message: { content: "hi" } }] });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    const { response } = await ex.execute({ model: MODEL, body, stream: false, credentials, log: null });
+
+    expect(response.status).toBe(200);
+    expect(chatHits).toBe(2);
+    // Session was claimed twice (initial + forced re-claim).
+    expect(fetchMock.mock.calls.filter(([u]) => u === SESSION_URL).length).toBe(2);
+    // Runs: START #1, FINISH(cancelled) #1 (abandoned on 428), START #2,
+    // FINISH(completed) #2.
+    const runCalls = fetchMock.mock.calls.filter(([u]) => u === RUN_URL);
+    expect(runCalls.length).toBe(4);
+    const runActions = runCalls.map((c) => JSON.parse(c[1].body).action);
+    expect(runActions.filter((a) => a === "START").length).toBe(2);
+    expect(runActions.filter((a) => a === "FINISH").length).toBe(2);
+    const finishPayload = JSON.parse(runCalls[runCalls.length - 1][1].body);
+    expect(finishPayload.status).toBe("completed");
+    // The retried chat request carried the re-claimed session + fresh run.
+    const lastChat = fetchMock.mock.calls.filter(([u]) => u === CHAT_URL).pop();
+    const sent = JSON.parse(lastChat[1].body);
+    expect(sent.codebuff_metadata.run_id).toBe("run-2");
+    expect(sent.codebuff_metadata.freebuff_instance_id).toBe("inst-2");
+  });
+
+  it("re-claims the session on 409 session_superseded and retries once", async () => {
+    let chatHits = 0;
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) return jsonResponse({ status: "active", instanceId: "inst-2", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      if (url === RUN_URL) return jsonResponse({ runId: "run-2" });
+      chatHits += 1;
+      if (chatHits === 1) {
+        return jsonResponse({ error: "session_superseded", message: "Another instance took over" }, { status: 409, ok: false });
+      }
+      return jsonResponse({ choices: [{ message: { content: "hi" } }] });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    const { response } = await ex.execute({ model: MODEL, body, stream: false, credentials, log: null });
+
+    expect(response.status).toBe(200);
+    expect(chatHits).toBe(2);
+    // Session re-claimed (initial + forced) and runs restarted.
+    expect(fetchMock.mock.calls.filter(([u]) => u === SESSION_URL).length).toBe(2);
+    const runCalls = fetchMock.mock.calls.filter(([u]) => u === RUN_URL);
+    expect(runCalls.filter((c) => JSON.parse(c[1].body).action === "START").length).toBe(2);
+  });
+
+  it("re-claims the session on 410 session_expired and retries once", async () => {
+    let chatHits = 0;
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) return jsonResponse({ status: "active", instanceId: "inst-2", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      if (url === RUN_URL) return jsonResponse({ runId: "run-2" });
+      chatHits += 1;
+      if (chatHits === 1) return jsonResponse({ error: "session_expired" }, { status: 410, ok: false });
+      return jsonResponse({ choices: [{ message: { content: "hi" } }] });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    const { response } = await ex.execute({ model: MODEL, body, stream: false, credentials, log: null });
+    expect(response.status).toBe(200);
+    expect(chatHits).toBe(2);
+  });
+
+  it("throws a 401 re-login error when the chat endpoint rejects the token", async () => {
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) return jsonResponse({ status: "active", instanceId: "inst-1", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      if (url === RUN_URL) return jsonResponse({ runId: "run-1" });
+      return jsonResponse({ error: "unauthorized" }, { status: 401, ok: false });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    await expect(
+      ex.execute({ model: MODEL, body, stream: false, credentials, log: null }),
+    ).rejects.toThrow(/re-login/i);
+  });
+
+  it("throws when no access token is present", async () => {
+    const ex = new FreebuffExecutor();
+    await expect(
+      ex.execute({ model: MODEL, body: { messages: [] }, stream: false, credentials: {}, log: null }),
+    ).rejects.toThrow(/no access token/i);
+  });
+
+  it("finishes the run as failed when the chat upstream errors", async () => {
+    // 400 (not in the 429/502/503 retry set) so the test stays fast and mirrors
+    // the real upstream rejection.
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) return jsonResponse({ status: "active", instanceId: "inst-1", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      if (url === RUN_URL) return jsonResponse({ runId: "run-1" });
+      return jsonResponse({ error: "upstream boom" }, { status: 400, ok: false });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    const { response } = await ex.execute({ model: MODEL, body, stream: false, credentials, log: null });
+
+    expect(response.status).toBe(400);
+    const runCalls = fetchMock.mock.calls.filter(([u]) => u === RUN_URL);
+    expect(runCalls.length).toBe(2); // START + FINISH
+    const finishPayload = JSON.parse(runCalls[1][1].body);
+    expect(finishPayload.action).toBe("FINISH");
+    expect(finishPayload.status).toBe("failed");
+  });
+
+  it("finishes the run as failed when execute throws mid-flight", async () => {
+    // AbortError (caller/stream abort) is never retried, keeping this test fast.
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) return jsonResponse({ status: "active", instanceId: "inst-1", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      if (url === RUN_URL) return jsonResponse({ runId: "run-1" });
+      throw Object.assign(new Error("aborted"), { name: "AbortError" });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    await expect(
+      ex.execute({ model: MODEL, body, stream: false, credentials, log: null }),
+    ).rejects.toThrow(/aborted/);
+
+    const runCalls = fetchMock.mock.calls.filter(([u]) => u === RUN_URL);
+    expect(runCalls.length).toBe(2); // START + FINISH(failed) from the finally block
+    const finishPayload = JSON.parse(runCalls[1][1].body);
+    expect(finishPayload.action).toBe("FINISH");
+    expect(finishPayload.status).toBe("failed");
+  });
+
+  it("retries the chat POST on a transient fetch-level network error", async () => {
+    let chatHits = 0;
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) return jsonResponse({ status: "active", instanceId: "inst-1", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      if (url === RUN_URL) return jsonResponse({ runId: "run-1" });
+      chatHits += 1;
+      if (chatHits === 1) throw new Error("fetch failed (cause: ECONNRESET)");
+      return jsonResponse({ choices: [{ message: { content: "hi" } }] });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    const { response } = await ex.execute({ model: MODEL, body, stream: false, credentials, log: null });
+
+    expect(response.status).toBe(200);
+    expect(chatHits).toBe(2);
+    // Run FINISHed exactly once (completed) — no double-FINISH from the retry.
+    const runCalls = fetchMock.mock.calls.filter(([u]) => u === RUN_URL);
+    expect(runCalls.length).toBe(2); // START + FINISH(completed)
+    expect(JSON.parse(runCalls[1][1].body).status).toBe("completed");
+  });
+
+  it("does not double-FINISH the abandoned run when the re-claim fails", async () => {
+    let chatHits = 0;
+    let runStartCount = 0;
+    fetchMock.mockImplementation(async (url) => {
+      if (url === SESSION_URL) return jsonResponse({ status: "active", instanceId: "inst-2", expiresAt: new Date(Date.now() + 3600000).toISOString() });
+      if (url === RUN_URL) {
+        // First START succeeds (run-1). Every later call fails with the
+        // transient ECONNRESET: the fire-and-forget FINISH swallows it, and
+        // the re-claim START propagates after its 3 network-retry attempts.
+        if (runStartCount === 0) {
+          runStartCount += 1;
+          return jsonResponse({ runId: "run-1" });
+        }
+        throw new Error("fetch failed (cause: ECONNRESET)");
+      }
+      chatHits += 1;
+      if (chatHits === 1) return jsonResponse({ error: "session_superseded" }, { status: 409, ok: false });
+      return jsonResponse({ choices: [{ message: { content: "hi" } }] });
+    });
+
+    const ex = new FreebuffExecutor();
+    const body = { model: MODEL, messages: [{ role: "user", content: "hi" }] };
+    // The re-claim failure rethrows the raw upstream error (the log line above
+    // it carries the "session re-claim failed" context).
+    await expect(
+      ex.execute({ model: MODEL, body, stream: false, credentials, log: null }),
+    ).rejects.toThrow(/fetch failed \(cause: ECONNRESET\)/);
+
+    // run-1 was FINISH'd exactly once, as "cancelled" — the failed re-claim
+    // must NOT trigger a second (rejected by the server) FINISH.
+    const runCalls = fetchMock.mock.calls.filter(([u]) => u === RUN_URL);
+    const finishes = runCalls.filter(([, o]) => JSON.parse(o.body).action === "FINISH");
+    expect(finishes.length).toBe(1);
+    expect(JSON.parse(finishes[0][1].body).status).toBe("cancelled");
+  });
+});
@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../../open-sse/utils/proxyFetch.js", () => ({
+  proxyAwareFetch: vi.fn(),
+}));
+
+import { proxyAwareFetch } from "../../open-sse/utils/proxyFetch.js";
+import { getUsageForProvider } from "../../open-sse/services/usage.js";
+import { PROVIDERS } from "../../open-sse/providers/index.js";
+import { USAGE_SUPPORTED_PROVIDERS } from "../../src/shared/constants/providers.js";
+import { parseQuotaData } from "../../src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.js";
+
+const SESSION_URL = "https://www.codebuff.com/api/v1/freebuff/session";
+
+function jsonResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const PRE_JOIN = {
+  status: "none",
+  accessTier: "limited",
+  rateLimitsByModel: {
+    "deepseek/deepseek-v4-flash": {
+      limit: 6,
+      recentCount: 4.1,
+      period: "pacific_day",
+      resetTimeZone: "America/Los_Angeles",
+      resetAt: "2026-08-06T07:00:00.000Z",
+      entitlementBreakdown: { base: 6, referral: 0, streak: 0 },
+    },
+    "openai/gpt-5.6-luna": {
+      limit: 6,
+      recentCount: 1,
+      period: "pacific_day",
+      resetTimeZone: "America/Los_Angeles",
+      resetAt: "2026-08-06T07:00:00.000Z",
+    },
+  },
+};
+
+describe("freebuff registry usage flag", () => {
+  it("exposes the session endpoint as transport.usage url", () => {
+    const cfg = PROVIDERS["freebuff"];
+    expect(cfg.usage?.url).toBe(SESSION_URL);
+  });
+
+  it("is listed in USAGE_SUPPORTED_PROVIDERS (features.usage)", () => {
+    expect(USAGE_SUPPORTED_PROVIDERS).toContain("freebuff");
+  });
+});
+
+describe("getUsageForProvider(freebuff)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("GETs the session endpoint and normalizes per-model session quotas", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(jsonResponse(PRE_JOIN));
+
+    const usage = await getUsageForProvider({
+      provider: "freebuff",
+      accessToken: "tok-1",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.plan).toBe("Freebuff (Limited)");
+    expect(usage.quotas["deepseek/deepseek-v4-flash"]).toMatchObject({
+      used: 4.1,
+      total: 6,
+      resetAt: "2026-08-06T07:00:00.000Z",
+      recurring: true,
+      unlimited: false,
+      displayName: "DeepSeek V4 Flash",
+    });
+    expect(usage.quotas["openai/gpt-5.6-luna"]).toMatchObject({
+      used: 1,
+      total: 6,
+      displayName: "GPT-5.6 Luna",
+    });
+
+    // Quota reads MUST be GET (a POST would claim a session and burn quota).
+    const [url, opts] = proxyAwareFetch.mock.calls[0];
+    expect(url).toBe(SESSION_URL);
+    expect(opts.method).toBe("GET");
+    expect(opts.headers.Authorization).toBe("Bearer tok-1");
+  });
+
+  it("folds the active session's own rateLimit into the shared map", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      jsonResponse({
+        status: "active",
+        accessTier: "full",
+        instanceId: "inst-1",
+        model: "deepseek/deepseek-v4-pro",
+        expiresAt: new Date(Date.now() + 3600000).toISOString(),
+        rateLimit: {
+          limit: 6,
+          recentCount: 2.4,
+          period: "pacific_day",
+          resetAt: "2026-08-06T07:00:00.000Z",
+        },
+        rateLimitsByModel: {},
+      }),
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "freebuff",
+      accessToken: "tok-1",
+    });
+
+    expect(usage.plan).toBe("Freebuff");
+    expect(usage.quotas["deepseek/deepseek-v4-pro"]).toMatchObject({
+      used: 2.4,
+      total: 6,
+      displayName: "DeepSeek V4 Pro",
+    });
+  });
+
+  it("surfaces a re-login message on 401", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(jsonResponse({ error: "unauthorized" }, 401));
+
+    const usage = await getUsageForProvider({
+      provider: "freebuff",
+      accessToken: "expired",
+    });
+
+    expect(usage.message).toMatch(/expired|re-login/i);
+    expect(usage.quotas).toBeUndefined();
+  });
+
+  it("surfaces a region message on 403 country_blocked (not a re-login hint)", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(
+      jsonResponse({ status: "country_blocked", countryCode: "XX" }, 403),
+    );
+
+    const usage = await getUsageForProvider({
+      provider: "freebuff",
+      accessToken: "tok-1",
+    });
+
+    expect(usage.message).toMatch(/not available in your region/i);
+  });
+
+  it("treats 404 (no session row) as pre-join with no quota", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(jsonResponse({}, 404));
+
+    const usage = await getUsageForProvider({
+      provider: "freebuff",
+      accessToken: "tok-1",
+    });
+
+    expect(usage.message).toMatch(/no session quota/i);
+  });
+
+  it("returns a message when the session response carries no quota map", async () => {
+    proxyAwareFetch.mockResolvedValueOnce(jsonResponse({ status: "none", accessTier: "full" }));
+
+    const usage = await getUsageForProvider({
+      provider: "freebuff",
+      accessToken: "tok-1",
+    });
+
+    expect(usage.plan).toBe("Freebuff");
+    expect(usage.message).toMatch(/no session quota/i);
+  });
+
+  it("does not throw when the session fetch fails", async () => {
+    proxyAwareFetch.mockRejectedValueOnce(new Error("network down"));
+
+    const usage = await getUsageForProvider({
+      provider: "freebuff",
+      accessToken: "tok-1",
+    });
+
+    expect(usage.message).toMatch(/usage error/i);
+  });
+});
+
+describe("parseQuotaData(freebuff)", () => {
+  it("uses displayName for the row label and keeps modelKey for ordering", () => {
+    const rows = parseQuotaData("freebuff", {
+      plan: "Freebuff (Limited)",
+      quotas: {
+        "deepseek/deepseek-v4-flash": {
+          used: 4.1,
+          total: 6,
+          resetAt: "2026-08-06T07:00:00.000Z",
+          displayName: "DeepSeek V4 Flash",
+        },
+      },
+    });
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      name: "DeepSeek V4 Flash",
+      modelKey: "deepseek/deepseek-v4-flash",
+      used: 4.1,
+      total: 6,
+    });
+  });
+});