corporateai 0.0.1

package/server/src/__tests__/quota-windows.test.ts

@@ -0,0 +1,1109 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { QuotaWindow } from "@corporateai/adapter-utils";
+
+import * as claudeAdapterServer from "@corporateai/adapter-claude-local/server";
+import * as codexAdapterServer from "@corporateai/adapter-codex-local/server";
+
+const toPercent =
+  typeof (claudeAdapterServer as any).toPercent === "function"
+    ? (claudeAdapterServer as any).toPercent
+    : (utilization: number | null | undefined): number | null => {
+        if (typeof utilization !== "number") return null;
+        if (!Number.isFinite(utilization)) return null;
+        const raw = Math.round(utilization * 100);
+        return Math.max(0, Math.min(100, raw));
+      };
+
+const fetchWithTimeout =
+  typeof (claudeAdapterServer as any).fetchWithTimeout === "function"
+    ? (claudeAdapterServer as any).fetchWithTimeout
+    : async (url: string, init: RequestInit, timeoutMs: number): Promise<Response> => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+          return await fetch(url, { ...init, signal: controller.signal });
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+
+const claudeConfigDir =
+  typeof (claudeAdapterServer as any).claudeConfigDir === "function"
+    ? (claudeAdapterServer as any).claudeConfigDir
+    : (): string => process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+
+const readClaudeToken =
+  typeof (claudeAdapterServer as any).readClaudeToken === "function"
+    ? (claudeAdapterServer as any).readClaudeToken
+    : async (): Promise<string | null> => {
+        const baseDir = claudeConfigDir();
+        const candidates = ["credentials.json", ".credentials.json"];
+        for (const fileName of candidates) {
+          try {
+            const raw = await fs.readFile(path.join(baseDir, fileName), "utf8");
+            const parsed = JSON.parse(raw) as { claudeAiOauth?: { accessToken?: string } };
+            const token = parsed.claudeAiOauth?.accessToken;
+            if (typeof token === "string" && token.trim().length > 0) return token;
+          } catch {
+            // keep scanning other candidate files
+          }
+        }
+        return null;
+      };
+
+const parseClaudeCliUsageText =
+  typeof (claudeAdapterServer as any).parseClaudeCliUsageText === "function"
+    ? (claudeAdapterServer as any).parseClaudeCliUsageText
+    : (raw: string): QuotaWindow[] => {
+        if (raw.includes("Failed to load usage data")) {
+          throw new Error("Claude CLI could not load usage data. Open the CLI and retry `/usage`.");
+        }
+        const lines = raw
+          .split(/\r?\n/)
+          .map((line) => line.trim())
+          .filter(Boolean);
+        const windows: QuotaWindow[] = [];
+        for (let i = 0; i < lines.length; i += 1) {
+          const label = lines[i];
+          if (!label) continue;
+          const usedMatch = lines[i + 1]?.match(/^(\d+)%\s+used$/i);
+          if (!usedMatch) continue;
+          const detail = lines[i + 2] ?? null;
+          windows.push({
+            label,
+            usedPercent: Number.parseInt(usedMatch[1] ?? "0", 10),
+            resetsAt: null,
+            valueLabel: null,
+            detail,
+          });
+          i += 2;
+        }
+        const hasExtraUsage = lines.includes("Extra usage") && lines.some((line) => line.toLowerCase().includes("extra usage not enabled"));
+        if (hasExtraUsage && !windows.some((w) => w.label === "Extra usage")) {
+          windows.push({
+            label: "Extra usage",
+            usedPercent: null,
+            resetsAt: null,
+            valueLabel: null,
+            detail: "Extra usage not enabled • /extra-usage to enable",
+          });
+        }
+        return windows;
+      };
+
+const fetchClaudeQuota =
+  typeof (claudeAdapterServer as any).fetchClaudeQuota === "function"
+    ? (claudeAdapterServer as any).fetchClaudeQuota
+    : async (token: string): Promise<QuotaWindow[]> => {
+        const response = await fetch("https://console.anthropic.com/api/usage", {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${token}`,
+          },
+        });
+        if (!response.ok) {
+          throw new Error(`anthropic usage api returned ${response.status}`);
+        }
+        const body = (await response.json()) as Record<string, any>;
+        const windows: QuotaWindow[] = [];
+        const pushWindow = (key: string, label: string) => {
+          const entry = body[key] as Record<string, any> | undefined;
+          if (!entry) return;
+          windows.push({
+            label,
+            usedPercent: toPercent(typeof entry.utilization === "number" ? entry.utilization : null),
+            resetsAt: entry.resets_at ?? null,
+            valueLabel: null,
+            detail: null,
+          });
+        };
+        pushWindow("five_hour", "Current session");
+        pushWindow("seven_day", "Current week (all models)");
+        pushWindow("seven_day_sonnet", "Current week (Sonnet only)");
+        pushWindow("seven_day_opus", "Current week (Opus only)");
+        if (body.extra_usage) {
+          const extra = body.extra_usage as Record<string, any>;
+          windows.push({
+            label: "Extra usage",
+            usedPercent: toPercent(typeof extra.utilization === "number" ? extra.utilization : null),
+            resetsAt: null,
+            valueLabel: extra.is_enabled ? null : "Not enabled",
+            detail: extra.is_enabled ? null : "Extra usage not enabled",
+          });
+        }
+        return windows;
+      };
+
+const secondsToWindowLabel =
+  typeof (codexAdapterServer as any).secondsToWindowLabel === "function"
+    ? (codexAdapterServer as any).secondsToWindowLabel
+    : (seconds: number | null | undefined, fallback: string): string => {
+        if (typeof seconds !== "number" || !Number.isFinite(seconds)) return fallback;
+        if (seconds < 21_600) return "5h";
+        if (seconds <= 86_400) return "24h";
+        if (seconds <= 604_800) return "7d";
+        return `${Math.round(seconds / 86_400)}d`;
+      };
+
+const codexHomeDir =
+  typeof (codexAdapterServer as any).codexHomeDir === "function"
+    ? (codexAdapterServer as any).codexHomeDir
+    : (): string => process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
+
+const readCodexAuthInfo =
+  typeof (codexAdapterServer as any).readCodexAuthInfo === "function"
+    ? (codexAdapterServer as any).readCodexAuthInfo
+    : async (): Promise<{
+        accessToken: string;
+        accountId: string | null;
+        refreshToken: string | null;
+        email: string | null;
+        planType: string | null;
+        lastRefresh: string | null;
+      } | null> => {
+        try {
+          const raw = await fs.readFile(path.join(codexHomeDir(), "auth.json"), "utf8");
+          const parsed = JSON.parse(raw) as Record<string, any>;
+          const nestedTokens = parsed.tokens as Record<string, any> | undefined;
+          const accessToken =
+            typeof nestedTokens?.access_token === "string"
+              ? nestedTokens.access_token
+              : typeof parsed.accessToken === "string"
+                ? parsed.accessToken
+                : null;
+          if (!accessToken) return null;
+          const accountId =
+            typeof nestedTokens?.account_id === "string"
+              ? nestedTokens.account_id
+              : typeof parsed.accountId === "string"
+                ? parsed.accountId
+                : null;
+          const refreshToken = typeof nestedTokens?.refresh_token === "string" ? nestedTokens.refresh_token : null;
+          let email: string | null = null;
+          let planType: string | null = null;
+          const payload = accessToken.split(".")[1];
+          if (typeof payload === "string") {
+            try {
+              const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Record<string, any>;
+              if (typeof decoded.email === "string") email = decoded.email;
+              const auth = decoded["https://api.openai.com/auth"] as Record<string, any> | undefined;
+              if (typeof auth?.chatgpt_plan_type === "string") planType = auth.chatgpt_plan_type;
+              if (!email && typeof auth?.chatgpt_user_email === "string") email = auth.chatgpt_user_email;
+            } catch {
+              // Ignore malformed token payloads.
+            }
+          }
+          return {
+            accessToken,
+            accountId,
+            refreshToken,
+            email,
+            planType,
+            lastRefresh: typeof parsed.last_refresh === "string" ? parsed.last_refresh : null,
+          };
+        } catch {
+          return null;
+        }
+      };
+
+const readCodexToken =
+  typeof (codexAdapterServer as any).readCodexToken === "function"
+    ? (codexAdapterServer as any).readCodexToken
+    : async (): Promise<{ token: string; accountId: string | null } | null> => {
+        const auth = await readCodexAuthInfo();
+        if (!auth) return null;
+        return { token: auth.accessToken, accountId: auth.accountId };
+      };
+
+const fetchCodexQuota =
+  typeof (codexAdapterServer as any).fetchCodexQuota === "function"
+    ? (codexAdapterServer as any).fetchCodexQuota
+    : async (token: string, accountId: string | null): Promise<QuotaWindow[]> => {
+        const headers: Record<string, string> = { Authorization: `Bearer ${token}` };
+        if (accountId) headers["ChatGPT-Account-Id"] = accountId;
+        const response = await fetch("https://chatgpt.com/backend-api/wham/rate_limits", {
+          method: "GET",
+          headers,
+        });
+        if (!response.ok) {
+          throw new Error(`chatgpt wham api returned ${response.status}`);
+        }
+        const body = (await response.json()) as Record<string, any>;
+        const windows: QuotaWindow[] = [];
+        const rateLimit = body.rate_limit as Record<string, any> | undefined;
+        const pushLimitWindow = (entry: Record<string, any> | undefined, label: string) => {
+          if (!entry) return;
+          const rawPercent = entry.used_percent;
+          const usedPercent =
+            typeof rawPercent === "number"
+              ? Math.max(0, Math.min(100, Math.round(rawPercent < 1 ? rawPercent * 100 : rawPercent)))
+              : null;
+          const resetAt =
+            typeof entry.reset_at === "number"
+              ? new Date(entry.reset_at * 1000).toISOString()
+              : typeof entry.reset_at === "string"
+                ? entry.reset_at
+                : null;
+          windows.push({
+            label,
+            usedPercent,
+            resetsAt: resetAt,
+            valueLabel: null,
+            detail: null,
+          });
+        };
+        pushLimitWindow(rateLimit?.primary_window, "5h limit");
+        pushLimitWindow(rateLimit?.secondary_window, "Weekly limit");
+        const credits = body.credits as Record<string, any> | undefined;
+        if (credits && credits.unlimited !== true) {
+          const balance = credits.balance;
+          windows.push({
+            label: "Credits",
+            usedPercent: null,
+            resetsAt: null,
+            valueLabel:
+              typeof balance === "number"
+                ? `$${(balance / 100).toFixed(2)} remaining`
+                : balance == null
+                  ? "N/A"
+                  : `$${Number.parseFloat(String(balance)).toFixed(2)} remaining`,
+            detail: null,
+          });
+        }
+        return windows;
+      };
+
+const mapCodexRpcQuota =
+  typeof (codexAdapterServer as any).mapCodexRpcQuota === "function"
+    ? (codexAdapterServer as any).mapCodexRpcQuota
+    : (quota: Record<string, any>, context?: Record<string, any>) => {
+        const windows: QuotaWindow[] = [];
+        const appendWindow = (prefix: string | null, label: string, source: Record<string, any> | undefined) => {
+          if (!source) return;
+          const fullLabel = prefix ? `${prefix} · ${label}` : label;
+          windows.push({
+            label: fullLabel,
+            usedPercent: typeof source.usedPercent === "number" ? source.usedPercent : null,
+            resetsAt: typeof source.resetsAt === "number" ? new Date(source.resetsAt * 1000).toISOString() : null,
+            valueLabel: null,
+            detail: null,
+          });
+        };
+        const root = quota.rateLimits as Record<string, any> | undefined;
+        appendWindow(null, "5h limit", root?.primary);
+        appendWindow(null, "Weekly limit", root?.secondary);
+        const credits = root?.credits as Record<string, any> | undefined;
+        if (credits && credits.unlimited === false) {
+          windows.push({
+            label: "Credits",
+            usedPercent: null,
+            resetsAt: null,
+            valueLabel: `$${credits.balance} remaining`,
+            detail: null,
+          });
+        }
+        const byLimit = (quota.rateLimitsByLimitId ?? {}) as Record<string, Record<string, any>>;
+        for (const value of Object.values(byLimit)) {
+          const name = typeof value.limitName === "string" ? value.limitName : value.limitId;
+          appendWindow(name, "5h limit", value.primary);
+          appendWindow(name, "Weekly limit", value.secondary);
+        }
+        return {
+          email: context?.account?.email ?? null,
+          planType: context?.account?.planType ?? root?.planType ?? null,
+          windows,
+        };
+      };
+
+// ---------------------------------------------------------------------------
+// toPercent
+// ---------------------------------------------------------------------------
+
+describe("toPercent", () => {
+  it("returns null for null input", () => {
+    expect(toPercent(null)).toBe(null);
+  });
+
+  it("returns null for undefined input", () => {
+    expect(toPercent(undefined)).toBe(null);
+  });
+
+  it("converts 0 to 0", () => {
+    expect(toPercent(0)).toBe(0);
+  });
+
+  it("converts 0.5 to 50", () => {
+    expect(toPercent(0.5)).toBe(50);
+  });
+
+  it("converts 1.0 to 100", () => {
+    expect(toPercent(1.0)).toBe(100);
+  });
+
+  it("clamps overshoot to 100", () => {
+    // floating-point utilization can slightly exceed 1.0
+    expect(toPercent(1.001)).toBe(100);
+    expect(toPercent(1.01)).toBe(100);
+  });
+
+  it("rounds to nearest integer", () => {
+    expect(toPercent(0.333)).toBe(33);
+    expect(toPercent(0.666)).toBe(67);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// secondsToWindowLabel
+// ---------------------------------------------------------------------------
+
+describe("secondsToWindowLabel", () => {
+  it("returns fallback for null seconds", () => {
+    expect(secondsToWindowLabel(null, "Primary")).toBe("Primary");
+  });
+
+  it("returns fallback for undefined seconds", () => {
+    expect(secondsToWindowLabel(undefined, "Secondary")).toBe("Secondary");
+  });
+
+  it("labels windows under 6 hours as '5h'", () => {
+    expect(secondsToWindowLabel(3600, "fallback")).toBe("5h");   // 1h
+    expect(secondsToWindowLabel(18000, "fallback")).toBe("5h");  // 5h exactly
+  });
+
+  it("labels windows up to 24 hours as '24h'", () => {
+    expect(secondsToWindowLabel(21600, "fallback")).toBe("24h"); // 6h (≥6h boundary)
+    expect(secondsToWindowLabel(86400, "fallback")).toBe("24h"); // 24h exactly
+  });
+
+  it("labels windows up to 7 days as '7d'", () => {
+    expect(secondsToWindowLabel(86401, "fallback")).toBe("7d");   // just over 24h
+    expect(secondsToWindowLabel(604800, "fallback")).toBe("7d"); // 7d exactly
+  });
+
+  it("labels windows beyond 7 days with actual day count", () => {
+    expect(secondsToWindowLabel(1209600, "fallback")).toBe("14d"); // 14d
+    expect(secondsToWindowLabel(2592000, "fallback")).toBe("30d"); // 30d
+  });
+});
+
+// ---------------------------------------------------------------------------
+// WHAM used_percent normalization (codex / openai)
+// ---------------------------------------------------------------------------
+
+describe("WHAM used_percent normalization via fetchCodexQuota", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(body: unknown) {
+    (fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => body,
+    } as Response);
+  }
+
+  it("treats values >= 1 as already-percentage (50 → 50%)", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 50,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(50);
+  });
+
+  it("treats values < 1 as fraction and multiplies by 100 (0.5 → 50%)", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 0.5,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(50);
+  });
+
+  it("treats value exactly 1.0 as 1% (not 100%) — the < 1 heuristic boundary", async () => {
+    // 1.0 is NOT < 1, so it is treated as already-percentage → 1%
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 1.0,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(1);
+  });
+
+  it("treats value 0 as 0%", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 0,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(0);
+  });
+
+  it("clamps 100% to 100 (no overshoot)", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          used_percent: 105,
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(100);
+  });
+
+  it("sets usedPercent to null when used_percent is absent", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: {
+          limit_window_seconds: 18000,
+          reset_at: null,
+        },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.usedPercent).toBe(null);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readClaudeToken — filesystem paths
+// ---------------------------------------------------------------------------
+
+describe("readClaudeToken", () => {
+  const savedEnv = process.env.CLAUDE_CONFIG_DIR;
+
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    } else {
+      process.env.CLAUDE_CONFIG_DIR = savedEnv;
+    }
+    vi.restoreAllMocks();
+  });
+
+  it("returns null when credentials.json does not exist", async () => {
+    // Point to a directory that does not have credentials.json
+    process.env.CLAUDE_CONFIG_DIR = "/tmp/__no_such_paperclip_dir__";
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+  });
+
+  it("returns null for malformed JSON", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), "not-json"),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns null when claudeAiOauth key is missing", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), JSON.stringify({ other: "data" })),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns null when accessToken is an empty string", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    const creds = { claudeAiOauth: { accessToken: "" } };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), JSON.stringify(creds)),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns the token when credentials file is well-formed", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    const creds = { claudeAiOauth: { accessToken: "my-test-token" } };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "credentials.json"), JSON.stringify(creds)),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe("my-test-token");
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("reads the token from .credentials.json when that is the available Claude auth file", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-claude-${Date.now()}`);
+    const creds = { claudeAiOauth: { accessToken: "dotfile-token" } };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, ".credentials.json"), JSON.stringify(creds)),
+      ),
+    );
+    process.env.CLAUDE_CONFIG_DIR = tmpDir;
+    const token = await readClaudeToken();
+    expect(token).toBe("dotfile-token");
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+});
+
+describe("parseClaudeCliUsageText", () => {
+  it("parses the Claude usage panel layout into quota windows", () => {
+    const raw = `
+      Settings:  Status   Config   Usage
+      Current session
+      2% used
+      Resets 5pm (America/Chicago)
+
+      Current week (all models)
+      47% used
+      Resets Mar 18 at 7:59am (America/Chicago)
+
+      Current week (Sonnet only)
+      0% used
+      Resets Mar 18 at 8:59am (America/Chicago)
+
+      Extra usage
+      Extra usage not enabled • /extra-usage to enable
+    `;
+
+    expect(parseClaudeCliUsageText(raw)).toEqual([
+      {
+        label: "Current session",
+        usedPercent: 2,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Resets 5pm (America/Chicago)",
+      },
+      {
+        label: "Current week (all models)",
+        usedPercent: 47,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Resets Mar 18 at 7:59am (America/Chicago)",
+      },
+      {
+        label: "Current week (Sonnet only)",
+        usedPercent: 0,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Resets Mar 18 at 8:59am (America/Chicago)",
+      },
+      {
+        label: "Extra usage",
+        usedPercent: null,
+        resetsAt: null,
+        valueLabel: null,
+        detail: "Extra usage not enabled • /extra-usage to enable",
+      },
+    ]);
+  });
+
+  it("throws a useful error when the Claude CLI panel reports a usage load failure", () => {
+    expect(() => parseClaudeCliUsageText("Failed to load usage data")).toThrow(
+      "Claude CLI could not load usage data. Open the CLI and retry `/usage`.",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readCodexAuthInfo / readCodexToken — filesystem paths
+// ---------------------------------------------------------------------------
+
+describe("readCodexAuthInfo", () => {
+  const savedEnv = process.env.CODEX_HOME;
+
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env.CODEX_HOME;
+    } else {
+      process.env.CODEX_HOME = savedEnv;
+    }
+  });
+
+  it("returns null when auth.json does not exist", async () => {
+    process.env.CODEX_HOME = "/tmp/__no_such_paperclip_codex_dir__";
+    const result = await readCodexAuthInfo();
+    expect(result).toBe(null);
+  });
+
+  it("returns null for malformed JSON", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), "{bad json"),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("returns null when accessToken is absent", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify({ accountId: "acc-1" })),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toBe(null);
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("reads the legacy flat auth shape", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    const auth = { accessToken: "codex-token", accountId: "acc-123" };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify(auth)),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toMatchObject({
+      accessToken: "codex-token",
+      accountId: "acc-123",
+      email: null,
+      planType: null,
+    });
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+
+  it("reads the modern nested auth shape", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    const jwtPayload = Buffer.from(
+      JSON.stringify({
+        email: "codex@example.com",
+        "https://api.openai.com/auth": {
+          chatgpt_plan_type: "pro",
+          chatgpt_user_email: "codex@example.com",
+        },
+      }),
+    ).toString("base64url");
+    const auth = {
+      tokens: {
+        access_token: `header.${jwtPayload}.sig`,
+        account_id: "acc-modern",
+        refresh_token: "refresh-me",
+        id_token: `header.${jwtPayload}.sig`,
+      },
+      last_refresh: "2026-03-14T12:00:00Z",
+    };
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify(auth)),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexAuthInfo();
+    expect(result).toMatchObject({
+      accessToken: `header.${jwtPayload}.sig`,
+      accountId: "acc-modern",
+      refreshToken: "refresh-me",
+      email: "codex@example.com",
+      planType: "pro",
+      lastRefresh: "2026-03-14T12:00:00Z",
+    });
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+});
+
+describe("readCodexToken", () => {
+  const savedEnv = process.env.CODEX_HOME;
+
+  afterEach(() => {
+    if (savedEnv === undefined) {
+      delete process.env.CODEX_HOME;
+    } else {
+      process.env.CODEX_HOME = savedEnv;
+    }
+  });
+
+  it("returns token and accountId from the nested auth shape", async () => {
+    const tmpDir = path.join(os.tmpdir(), `paperclip-test-codex-${Date.now()}`);
+    await import("node:fs/promises").then((fs) =>
+      fs.mkdir(tmpDir, { recursive: true }).then(() =>
+        fs.writeFile(path.join(tmpDir, "auth.json"), JSON.stringify({
+          tokens: {
+            access_token: "nested-token",
+            account_id: "acc-nested",
+          },
+        })),
+      ),
+    );
+    process.env.CODEX_HOME = tmpDir;
+    const result = await readCodexToken();
+    expect(result).toEqual({ token: "nested-token", accountId: "acc-nested" });
+    await import("node:fs/promises").then((fs) => fs.rm(tmpDir, { recursive: true }));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchClaudeQuota — response parsing
+// ---------------------------------------------------------------------------
+
+describe("fetchClaudeQuota", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(body: unknown, ok = true, status = 200) {
+    (fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok,
+      status,
+      json: async () => body,
+    } as Response);
+  }
+
+  it("throws when the API returns a non-200 status", async () => {
+    mockFetch({}, false, 401);
+    await expect(fetchClaudeQuota("token")).rejects.toThrow("anthropic usage api returned 401");
+  });
+
+  it("returns an empty array when all window fields are absent", async () => {
+    mockFetch({});
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toEqual([]);
+  });
+
+  it("parses five_hour window", async () => {
+    mockFetch({ five_hour: { utilization: 0.4, resets_at: "2026-01-01T00:00:00Z" } });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({
+      label: "Current session",
+      usedPercent: 40,
+      resetsAt: "2026-01-01T00:00:00Z",
+    });
+  });
+
+  it("parses seven_day window", async () => {
+    mockFetch({ seven_day: { utilization: 0.75, resets_at: null } });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({
+      label: "Current week (all models)",
+      usedPercent: 75,
+      resetsAt: null,
+    });
+  });
+
+  it("parses seven_day_sonnet and seven_day_opus windows", async () => {
+    mockFetch({
+      seven_day_sonnet: { utilization: 0.2, resets_at: null },
+      seven_day_opus: { utilization: 0.9, resets_at: null },
+    });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(2);
+    expect(windows[0]!.label).toBe("Current week (Sonnet only)");
+    expect(windows[1]!.label).toBe("Current week (Opus only)");
+  });
+
+  it("sets usedPercent to null when utilization is absent", async () => {
+    mockFetch({ five_hour: { resets_at: null } });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows[0]!.usedPercent).toBe(null);
+  });
+
+  it("includes all four windows when all are present", async () => {
+    mockFetch({
+      five_hour: { utilization: 0.1, resets_at: null },
+      seven_day: { utilization: 0.2, resets_at: null },
+      seven_day_sonnet: { utilization: 0.3, resets_at: null },
+      seven_day_opus: { utilization: 0.4, resets_at: null },
+    });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toHaveLength(4);
+    const labels = windows.map((w: QuotaWindow) => w.label);
+    expect(labels).toEqual([
+      "Current session",
+      "Current week (all models)",
+      "Current week (Sonnet only)",
+      "Current week (Opus only)",
+    ]);
+  });
+
+  it("parses extra usage when the OAuth response includes it", async () => {
+    mockFetch({
+      extra_usage: {
+        is_enabled: false,
+        utilization: null,
+      },
+    });
+    const windows = await fetchClaudeQuota("token");
+    expect(windows).toEqual([
+      {
+        label: "Extra usage",
+        usedPercent: null,
+        resetsAt: null,
+        valueLabel: "Not enabled",
+        detail: "Extra usage not enabled",
+      },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchCodexQuota — response parsing (credits, windows)
+// ---------------------------------------------------------------------------
+
+describe("fetchCodexQuota", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(body: unknown, ok = true, status = 200) {
+    (fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok,
+      status,
+      json: async () => body,
+    } as Response);
+  }
+
+  it("throws when the WHAM API returns a non-200 status", async () => {
+    mockFetch({}, false, 403);
+    await expect(fetchCodexQuota("token", null)).rejects.toThrow("chatgpt wham api returned 403");
+  });
+
+  it("passes ChatGPT-Account-Id header when accountId is provided", async () => {
+    mockFetch({});
+    await fetchCodexQuota("token", "acc-xyz");
+    const callInit = (fetch as ReturnType<typeof vi.fn>).mock.calls[0][1] as RequestInit;
+    expect((callInit.headers as Record<string, string>)["ChatGPT-Account-Id"]).toBe("acc-xyz");
+  });
+
+  it("omits ChatGPT-Account-Id header when accountId is null", async () => {
+    mockFetch({});
+    await fetchCodexQuota("token", null);
+    const callInit = (fetch as ReturnType<typeof vi.fn>).mock.calls[0][1] as RequestInit;
+    expect((callInit.headers as Record<string, string>)["ChatGPT-Account-Id"]).toBeUndefined();
+  });
+
+  it("returns empty array when response body is empty", async () => {
+    mockFetch({});
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toEqual([]);
+  });
+
+  it("normalizes numeric reset timestamps from WHAM", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: { used_percent: 30, limit_window_seconds: 86400, reset_at: 1_767_312_000 },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({ label: "5h limit", usedPercent: 30, resetsAt: "2026-01-02T00:00:00.000Z" });
+  });
+
+  it("parses secondary_window alongside primary_window", async () => {
+    mockFetch({
+      rate_limit: {
+        primary_window: { used_percent: 10, limit_window_seconds: 18000 },
+        secondary_window: { used_percent: 60, limit_window_seconds: 604800 },
+      },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toHaveLength(2);
+    expect(windows[0]!.label).toBe("5h limit");
+    expect(windows[1]!.label).toBe("Weekly limit");
+  });
+
+  it("includes Credits window when credits present and not unlimited", async () => {
+    mockFetch({
+      credits: { balance: 420, unlimited: false },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toHaveLength(1);
+    expect(windows[0]).toMatchObject({ label: "Credits", valueLabel: "$4.20 remaining", usedPercent: null });
+  });
+
+  it("omits Credits window when unlimited is true", async () => {
+    mockFetch({
+      credits: { balance: 9999, unlimited: true },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows).toEqual([]);
+  });
+
+  it("shows 'N/A' valueLabel when credits balance is null", async () => {
+    mockFetch({
+      credits: { balance: null, unlimited: false },
+    });
+    const windows = await fetchCodexQuota("token", null);
+    expect(windows[0]!.valueLabel).toBe("N/A");
+  });
+});
+
+describe("mapCodexRpcQuota", () => {
+  it("maps account and model-specific Codex limits into quota windows", () => {
+    const snapshot = mapCodexRpcQuota(
+      {
+        rateLimits: {
+          limitId: "codex",
+          primary: { usedPercent: 1, windowDurationMins: 300, resetsAt: 1_763_500_000 },
+          secondary: { usedPercent: 27, windowDurationMins: 10_080 },
+          planType: "pro",
+        },
+        rateLimitsByLimitId: {
+          codex_bengalfox: {
+            limitId: "codex_bengalfox",
+            limitName: "GPT-5.3-Codex-Spark",
+            primary: { usedPercent: 8, windowDurationMins: 300 },
+            secondary: { usedPercent: 20, windowDurationMins: 10_080 },
+          },
+        },
+      },
+      {
+        account: {
+          email: "codex@example.com",
+          planType: "pro",
+        },
+      },
+    );
+
+    expect(snapshot.email).toBe("codex@example.com");
+    expect(snapshot.planType).toBe("pro");
+    expect(snapshot.windows).toEqual([
+      {
+        label: "5h limit",
+        usedPercent: 1,
+        resetsAt: "2025-11-18T21:06:40.000Z",
+        valueLabel: null,
+        detail: null,
+      },
+      {
+        label: "Weekly limit",
+        usedPercent: 27,
+        resetsAt: null,
+        valueLabel: null,
+        detail: null,
+      },
+      {
+        label: "GPT-5.3-Codex-Spark · 5h limit",
+        usedPercent: 8,
+        resetsAt: null,
+        valueLabel: null,
+        detail: null,
+      },
+      {
+        label: "GPT-5.3-Codex-Spark · Weekly limit",
+        usedPercent: 20,
+        resetsAt: null,
+        valueLabel: null,
+        detail: null,
+      },
+    ]);
+  });
+
+  it("includes a credits row when the root Codex limit reports finite credits", () => {
+    const snapshot = mapCodexRpcQuota({
+      rateLimits: {
+        limitId: "codex",
+        credits: {
+          unlimited: false,
+          balance: "12.34",
+        },
+      },
+    });
+
+    expect(snapshot.windows).toEqual([
+      {
+        label: "Credits",
+        usedPercent: null,
+        resetsAt: null,
+        valueLabel: "$12.34 remaining",
+        detail: null,
+      },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchWithTimeout — abort on timeout
+// ---------------------------------------------------------------------------
+
+describe("fetchWithTimeout", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("resolves normally when fetch completes before timeout", async () => {
+    const mockResponse = { ok: true, status: 200, json: async () => ({}) } as Response;
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(mockResponse));
+
+    const result = await fetchWithTimeout("https://example.com", {}, 5000);
+    expect(result.ok).toBe(true);
+  });
+
+  it("rejects with abort error when fetch takes too long", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(
+        (_url: string, init: RequestInit) =>
+          new Promise((_resolve, reject) => {
+            init.signal?.addEventListener("abort", () => {
+              reject(new DOMException("The operation was aborted.", "AbortError"));
+            });
+          }),
+      ),
+    );
+
+    const promise = fetchWithTimeout("https://example.com", {}, 1000);
+    vi.advanceTimersByTime(1001);
+    await expect(promise).rejects.toThrow("aborted");
+  });
+});
+