refactor(quota): move provider quota logic into adapter layer, add unit tests

- Extract all Anthropic credential/API logic into claude-local/src/server/quota.ts
- Extract all OpenAI/WHAM credential/API logic into codex-local/src/server/quota.ts
- Add optional getQuotaWindows() to ServerAdapterModule in adapter-utils
- Rewrite quota-windows.ts as a 29-line thin aggregator with zero provider knowledge
- Wire getQuotaWindows into adapter registry for claude-local and codex-local
- Add 47 unit tests covering toPercent, secondsToWindowLabel, WHAM normalization,
  readClaudeToken, readCodexToken, fetchClaudeQuota, fetchCodexQuota, fetchWithTimeout
- Add 8 unit tests covering parseDateRange validation and byProvider pro-rata math

Adding a third provider now requires only touching that provider's adapter.

packages/adapter-utils/src/index.ts

@@ -17,6 +17,8 @@ export type {
   HireApprovedPayload,
   HireApprovedHookResult,
   ServerAdapterModule,
+  QuotaWindow,
+  ProviderQuotaResult,
   TranscriptEntry,
   StdoutLineParser,
   CLIAdapterModule,

packages/adapter-utils/src/types.ts

@@ -171,6 +171,33 @@ export interface HireApprovedHookResult {
   detail?: Record<string, unknown>;
 }
 
+// ---------------------------------------------------------------------------
+// Quota window types — used by adapters that can report provider quota/rate-limit state
+// ---------------------------------------------------------------------------
+
+/** a single rate-limit or usage window returned by a provider quota API */
+export interface QuotaWindow {
+  /** human label, e.g. "5h", "7d", "Sonnet 7d", "Credits" */
+  label: string;
+  /** percent of the window already consumed (0-100), null when not reported */
+  usedPercent: number | null;
+  /** iso timestamp when this window resets, null when not reported */
+  resetsAt: string | null;
+  /** free-form value label for credit-style windows, e.g. "$4.20 remaining" */
+  valueLabel: string | null;
+}
+
+/** result for one provider from getQuotaWindows() */
+export interface ProviderQuotaResult {
+  /** provider slug, e.g. "anthropic", "openai" */
+  provider: string;
+  /** true when the fetch succeeded and windows is populated */
+  ok: boolean;
+  /** error message when ok is false */
+  error?: string;
+  windows: QuotaWindow[];
+}
+
 export interface ServerAdapterModule {
   type: string;
   execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
@@ -188,6 +215,12 @@ export interface ServerAdapterModule {
     payload: HireApprovedPayload,
     adapterConfig: Record<string, unknown>,
   ) => Promise<HireApprovedHookResult>;
+  /**
+   * Optional: fetch live provider quota/rate-limit windows for this adapter.
+   * Returns a ProviderQuotaResult so the server can aggregate across adapters
+   * without knowing provider-specific credential paths or API shapes.
+   */
+  getQuotaWindows?: () => Promise<ProviderQuotaResult>;
 }
 
 // ---------------------------------------------------------------------------

packages/adapters/claude-local/src/server/index.ts

@@ -6,6 +6,14 @@ export {
   isClaudeMaxTurnsResult,
   isClaudeUnknownSessionError,
 } from "./parse.js";
+export {
+  getQuotaWindows,
+  readClaudeToken,
+  fetchClaudeQuota,
+  toPercent,
+  fetchWithTimeout,
+  claudeConfigDir,
+} from "./quota.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
 
 function readNonEmptyString(value: unknown): string | null {

packages/adapters/claude-local/src/server/quota.ts

@@ -0,0 +1,117 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { ProviderQuotaResult, QuotaWindow } from "@paperclipai/adapter-utils";
+
+export function claudeConfigDir(): string {
+  const fromEnv = process.env.CLAUDE_CONFIG_DIR;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv.trim();
+  return path.join(os.homedir(), ".claude");
+}
+
+export async function readClaudeToken(): Promise<string | null> {
+  const credPath = path.join(claudeConfigDir(), "credentials.json");
+  let raw: string;
+  try {
+    raw = await fs.readFile(credPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const obj = parsed as Record<string, unknown>;
+  const oauth = obj["claudeAiOauth"];
+  if (typeof oauth !== "object" || oauth === null) return null;
+  const token = (oauth as Record<string, unknown>)["accessToken"];
+  return typeof token === "string" && token.length > 0 ? token : null;
+}
+
+interface AnthropicUsageWindow {
+  utilization?: number | null;
+  resets_at?: string | null;
+}
+
+interface AnthropicUsageResponse {
+  five_hour?: AnthropicUsageWindow | null;
+  seven_day?: AnthropicUsageWindow | null;
+  seven_day_sonnet?: AnthropicUsageWindow | null;
+  seven_day_opus?: AnthropicUsageWindow | null;
+}
+
+/** Convert a 0-1 utilization fraction to a 0-100 integer percent. Returns null for null/undefined input. */
+export function toPercent(utilization: number | null | undefined): number | null {
+  if (utilization == null) return null;
+  // utilization is 0-1 fraction; clamp to 100 in case of floating-point overshoot
+  return Math.min(100, Math.round(utilization * 100));
+}
+
+/** fetch with an abort-based timeout so a hanging provider api doesn't block the response indefinitely */
+export async function fetchWithTimeout(url: string, init: RequestInit, ms = 8000): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchClaudeQuota(token: string): Promise<QuotaWindow[]> {
+  const resp = await fetchWithTimeout("https://api.anthropic.com/api/oauth/usage", {
+    headers: {
+      "Authorization": `Bearer ${token}`,
+      "anthropic-beta": "oauth-2025-04-20",
+    },
+  });
+  if (!resp.ok) throw new Error(`anthropic usage api returned ${resp.status}`);
+  const body = (await resp.json()) as AnthropicUsageResponse;
+  const windows: QuotaWindow[] = [];
+
+  if (body.five_hour != null) {
+    windows.push({
+      label: "5h",
+      usedPercent: toPercent(body.five_hour.utilization),
+      resetsAt: body.five_hour.resets_at ?? null,
+      valueLabel: null,
+    });
+  }
+  if (body.seven_day != null) {
+    windows.push({
+      label: "7d",
+      usedPercent: toPercent(body.seven_day.utilization),
+      resetsAt: body.seven_day.resets_at ?? null,
+      valueLabel: null,
+    });
+  }
+  if (body.seven_day_sonnet != null) {
+    windows.push({
+      label: "Sonnet 7d",
+      usedPercent: toPercent(body.seven_day_sonnet.utilization),
+      resetsAt: body.seven_day_sonnet.resets_at ?? null,
+      valueLabel: null,
+    });
+  }
+  if (body.seven_day_opus != null) {
+    windows.push({
+      label: "Opus 7d",
+      usedPercent: toPercent(body.seven_day_opus.utilization),
+      resetsAt: body.seven_day_opus.resets_at ?? null,
+      valueLabel: null,
+    });
+  }
+  return windows;
+}
+
+export async function getQuotaWindows(): Promise<ProviderQuotaResult> {
+  const token = await readClaudeToken();
+  if (!token) {
+    return { provider: "anthropic", ok: false, error: "no local claude auth token", windows: [] };
+  }
+  const windows = await fetchClaudeQuota(token);
+  return { provider: "anthropic", ok: true, windows };
+}

packages/adapters/codex-local/src/server/index.ts

@@ -1,6 +1,14 @@
 export { execute, ensureCodexSkillsInjected } from "./execute.js";
 export { testEnvironment } from "./test.js";
 export { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
+export {
+  getQuotaWindows,
+  readCodexToken,
+  fetchCodexQuota,
+  secondsToWindowLabel,
+  fetchWithTimeout,
+  codexHomeDir,
+} from "./quota.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
 
 function readNonEmptyString(value: unknown): string | null {

packages/adapters/codex-local/src/server/quota.ts

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { ProviderQuotaResult, QuotaWindow } from "@paperclipai/adapter-utils";
+
+export function codexHomeDir(): string {
+  const fromEnv = process.env.CODEX_HOME;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv.trim();
+  return path.join(os.homedir(), ".codex");
+}
+
+interface CodexAuthFile {
+  accessToken?: string | null;
+  accountId?: string | null;
+}
+
+export async function readCodexToken(): Promise<{ token: string; accountId: string | null } | null> {
+  const authPath = path.join(codexHomeDir(), "auth.json");
+  let raw: string;
+  try {
+    raw = await fs.readFile(authPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const obj = parsed as CodexAuthFile;
+  const token = obj.accessToken;
+  if (typeof token !== "string" || token.length === 0) return null;
+  const accountId =
+    typeof obj.accountId === "string" && obj.accountId.length > 0 ? obj.accountId : null;
+  return { token, accountId };
+}
+
+interface WhamWindow {
+  used_percent?: number | null;
+  limit_window_seconds?: number | null;
+  reset_at?: string | null;
+}
+
+interface WhamCredits {
+  balance?: number | null;
+  unlimited?: boolean | null;
+}
+
+interface WhamUsageResponse {
+  rate_limit?: {
+    primary_window?: WhamWindow | null;
+    secondary_window?: WhamWindow | null;
+  } | null;
+  credits?: WhamCredits | null;
+}
+
+/**
+ * Map a window duration in seconds to a human-readable label.
+ * Falls back to the provided fallback string when seconds is null/undefined.
+ */
+export function secondsToWindowLabel(
+  seconds: number | null | undefined,
+  fallback: string,
+): string {
+  if (seconds == null) return fallback;
+  const hours = seconds / 3600;
+  if (hours < 6) return "5h";
+  if (hours <= 24) return "24h";
+  if (hours <= 168) return "7d";
+  // for windows larger than 7d, show the actual day count rather than silently mislabelling
+  return `${Math.round(hours / 24)}d`;
+}
+
+/** fetch with an abort-based timeout so a hanging provider api doesn't block the response indefinitely */
+export async function fetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  ms = 8000,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchCodexQuota(
+  token: string,
+  accountId: string | null,
+): Promise<QuotaWindow[]> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+  };
+  if (accountId) headers["ChatGPT-Account-Id"] = accountId;
+
+  const resp = await fetchWithTimeout("https://chatgpt.com/backend-api/wham/usage", { headers });
+  if (!resp.ok) throw new Error(`chatgpt wham api returned ${resp.status}`);
+  const body = (await resp.json()) as WhamUsageResponse;
+  const windows: QuotaWindow[] = [];
+
+  const rateLimit = body.rate_limit;
+  if (rateLimit?.primary_window != null) {
+    const w = rateLimit.primary_window;
+    // wham used_percent is 0-100 (confirmed empirically); guard against 0-1 format just in case.
+    // use < 1 (not <= 1) so that 1% usage (rawPct=1) is not misclassified as 100%.
+    const rawPct = w.used_percent ?? null;
+    const usedPercent =
+      rawPct != null ? Math.min(100, Math.round(rawPct < 1 ? rawPct * 100 : rawPct)) : null;
+    windows.push({
+      label: secondsToWindowLabel(w.limit_window_seconds, "Primary"),
+      usedPercent,
+      resetsAt: w.reset_at ?? null,
+      valueLabel: null,
+    });
+  }
+  if (rateLimit?.secondary_window != null) {
+    const w = rateLimit.secondary_window;
+    // wham used_percent is 0-100 (confirmed empirically); guard against 0-1 format just in case.
+    // use < 1 (not <= 1) so that 1% usage (rawPct=1) is not misclassified as 100%.
+    const rawPct = w.used_percent ?? null;
+    const usedPercent =
+      rawPct != null ? Math.min(100, Math.round(rawPct < 1 ? rawPct * 100 : rawPct)) : null;
+    windows.push({
+      label: secondsToWindowLabel(w.limit_window_seconds, "Secondary"),
+      usedPercent,
+      resetsAt: w.reset_at ?? null,
+      valueLabel: null,
+    });
+  }
+  if (body.credits != null && body.credits.unlimited !== true) {
+    const balance = body.credits.balance;
+    const valueLabel = balance != null ? `$${(balance / 100).toFixed(2)} remaining` : "N/A";
+    windows.push({
+      label: "Credits",
+      usedPercent: null,
+      resetsAt: null,
+      valueLabel,
+    });
+  }
+  return windows;
+}
+
+export async function getQuotaWindows(): Promise<ProviderQuotaResult> {
+  const auth = await readCodexToken();
+  if (!auth) {
+    return { provider: "openai", ok: false, error: "no local codex auth token", windows: [] };
+  }
+  const windows = await fetchCodexQuota(auth.token, auth.accountId);
+  return { provider: "openai", ok: true, windows };
+}