cartethyia 2.7.8 → 2.8.0

package/src/providers/integrations/freebuff/freebuff-discovery.ts

@@ -0,0 +1,108 @@
+// Freebuff live model discovery — TypeScript, Freebuff provider.
+//
+// `GET /api/v1/freebuff/models` with catalog protocol 1 + desktop client. The
+// response rows carry `m-<hex>` keys, `legacyDigests`, display names, and an
+// ephemeral handle (`fbm1.*`). Discovery maps rows to ModelDefinitions: a key
+// with a caller-facing virtual name is published under that name (see
+// `freebuff-virtual.ts`), and an unnamed key keeps its raw id. The handle is
+// NOT stored (it is single-fetch ephemeral and re-resolved per dispatch).
+
+import type { ModelDefinition } from "../../provider-model-definition";
+import { defineModel } from "../../provider-model-definition";
+import type { ProviderModelDiscovery } from "../../discovery/discovery-types";
+import {
+  FREEBUFF_API_HOST,
+  FREEBUFF_CATALOG_PROTOCOL_HEADER,
+  FREEBUFF_CATALOG_PROTOCOL_VERSION,
+  FREEBUFF_CHAT_COMPLETIONS_PATH,
+  FREEBUFF_CLIENT_HEADER,
+  FREEBUFF_CLIENT_HEADER_VALUE,
+} from "./freebuff";
+import { FREEBUFF_VIRTUAL_MODELS } from "./freebuff-virtual";
+
+const KNOWN_PREMIUM_KEYS: ReadonlySet<string> = new Set([
+  "m-127314bb39", // DeepSeek V4.1 Flash Fast
+  "m-5a5d0e255e", // GPT-6 Luna
+  "m-ffcbc2bcf3", // Muse Spark 1.3
+  "m-7d6e1b3ae0", // GPT-6.1 Terra
+  "m-5b6a604eb6", // Claude Haiku 5.5 · 100k
+]);
+
+const KNOWN_FREE_KEYS: ReadonlySet<string> = new Set([
+  "m-096e75164d", // DeepSeek Fast
+  "m-8db1ccbba6", // DeepSeek
+  "m-61c26317cc", // DeepSeek Slow
+  "m-9a7e098cc1", // Solar Pro 4
+  "m-69307952f8", // Solar Mini 4
+  "m-0921d81ce7", // Crouton Alpha
+  "m-02244092cb", // Glyph Cluster
+  "m-ddc687c50f", // Nemotron 3.5 Lightning
+]);
+
+/** Virtual id by roster key: a key with a known name publishes under that name. */
+const VIRTUAL_ID_BY_KEY: ReadonlyMap<string, string> = new Map(
+  FREEBUFF_VIRTUAL_MODELS.map((virtual) => [virtual.target, virtual.id]),
+);
+
+/**
+ * Live discovery over the static floor: `GET /api/v1/freebuff/models` answers
+ * with the account's current roster. A failed fetch returns the static roster
+ * (offline fallback) rather than raising.
+ */
+export function freebuffModelDiscovery(): ProviderModelDiscovery {
+  return async ({ credential, fetcher }) => {
+    if (credential.trim().length === 0) return null;
+    const fetchFn = fetcher ?? globalThis.fetch;
+    const res = await fetchFn(`${FREEBUFF_API_HOST}/api/v1/freebuff/models`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${credential.trim()}`,
+        [FREEBUFF_CATALOG_PROTOCOL_HEADER]: FREEBUFF_CATALOG_PROTOCOL_VERSION,
+        [FREEBUFF_CLIENT_HEADER]: FREEBUFF_CLIENT_HEADER_VALUE,
+      },
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) return null;
+    const body: unknown = await res.json().catch(() => null);
+    if (typeof body !== "object" || body === null || !Array.isArray((body as { rows?: unknown }).rows)) return null;
+    const rows = (body as { rows: unknown[] }).rows;
+    const models: ModelDefinition[] = [];
+    for (const row of rows) {
+      if (typeof row !== "object" || row === null) continue;
+      const r = row as Record<string, unknown>;
+      const key = typeof r["key"] === "string" ? r["key"] : undefined;
+      const access = typeof r["access"] === "string" ? r["access"] : undefined;
+      const premium = r["premium"] === true;
+      if (!key) continue;
+      const isPremium = premium || access === "locked" || KNOWN_PREMIUM_KEYS.has(key);
+      const isFree = KNOWN_FREE_KEYS.has(key) || access === "open";
+      // The server publishes the real context window, modality, and reasoning
+      // efforts per row — use them verbatim rather than a hardcoded guess.
+      const ctx = typeof r["contextWindow"] === "number" && r["contextWindow"] > 0 ? r["contextWindow"] : undefined;
+      const multimodal = r["multimodal"] === true;
+      const efforts = Array.isArray(r["efforts"]) && r["efforts"].every((e) => typeof e === "string")
+        ? (r["efforts"] as string[])
+        : undefined;
+      models.push(
+        defineModel({
+          // A known roster key publishes under its caller-facing virtual name;
+          // an unnamed key keeps its raw id (still reachable, never renamed).
+          id: VIRTUAL_ID_BY_KEY.get(key) ?? key,
+          providerId: "freebuff",
+          wireFamily: "chat",
+          endpoint: FREEBUFF_CHAT_COMPLETIONS_PATH,
+          ...(ctx !== undefined ? { ctx } : {}),
+          ...(multimodal ? { vision: true } : {}),
+          reasoning: true,
+          ...(efforts !== undefined ? { reasoningEfforts: efforts } : {}),
+          toolCall: true,
+          ...(isFree ? { free: true, freeTier: true } : {}),
+          ...(isPremium ? { proOnly: true } : {}),
+        }),
+      );
+    }
+    return models.length > 0 ? models : null;
+  };
+}
+
+export { defineModel };

package/src/providers/integrations/freebuff/freebuff-oauth.ts

@@ -0,0 +1,240 @@
+// Freebuff OAuth client — TypeScript, Freebuff provider.
+//
+// Freebuff's login is a code flow, not standard OAuth2:
+//   1. `POST /api/auth/cli/code` with `{fingerprintId}` → `{loginUrl,
+//      fingerprintHash, expiresAt, expiresInMs}`.
+//   2. The operator opens `loginUrl` in a browser and signs in.
+//   3. `GET /api/auth/cli/status?fingerprintId=...&fingerprintHash=...&expiresAt=...`
+//      → `{user:{authToken, id, email, name}}` once signed in.
+//
+// This maps onto the gateway's device-flow shape: `startDeviceAuth` issues the
+// code (verificationUri = loginUrl), and `pollDeviceAuth` polls the status.
+// On success we mint the Ed25519 device key (`POST /api/v1/freebuff/device-keys`)
+// and persist `{accountId, device}` in `auth_state` so dispatch can sign.
+
+import type {
+  OAuthDeviceFlowContext,
+  OAuthDevicePollResult,
+  OAuthDeviceStartResult,
+  OAuthExchangeResult,
+  OAuthImportInput,
+  OAuthLoginClient,
+} from "../../authentication/oauth-flow-store";
+import { isRecord } from "../../../protocol/codecs";
+import { GatewayError } from "../../../protocol/gateway-error";
+import {
+  FREEBUFF_API_HOST,
+  FREEBUFF_CLIENT_HEADER_VALUE,
+  FREEBUFF_MODEL_CATALOG_PATH,
+  FREEBUFF_CATALOG_PROTOCOL_HEADER,
+  FREEBUFF_CATALOG_PROTOCOL_VERSION,
+  FREEBUFF_CLIENT_HEADER,
+  freebuffMintDeviceKey,
+} from "./freebuff";
+
+const CODE_PATH = "/api/auth/cli/code";
+const STATUS_PATH = "/api/auth/cli/status";
+
+interface CodeIssued {
+  readonly loginUrl: string;
+  readonly fingerprintId: string;
+  readonly fingerprintHash: string;
+  readonly expiresAt: string;
+}
+
+export class FreebuffOAuthClient implements OAuthLoginClient {
+  readonly supportsDeviceCode = true;
+  readonly supportsBrowserCode = false;
+  // No operator fields: the device flow issues a code and the account
+  // identity (email/name) comes back in the poll response — asking for an
+  // email up front is both unnecessary and wrong.
+  readonly deviceLoginFields = [] as const;
+  readonly importFields = [
+    {
+      key: "token",
+      label: "Freebuff access token (from the Desktop/CLI login)",
+      placeholder: "Paste the bearer token…",
+      secret: true,
+      required: true,
+    },
+  ] as const;
+
+  private readonly fetchFn: typeof fetch;
+
+  constructor(fetchFn: typeof fetch = globalThis.fetch) {
+    this.fetchFn = fetchFn;
+  }
+
+  async startDeviceAuth(_context?: OAuthDeviceFlowContext): Promise<OAuthDeviceStartResult> {
+    const fingerprintId = crypto.randomUUID();
+    let res: Response;
+    try {
+      res = await this.fetchFn(`${FREEBUFF_API_HOST}${CODE_PATH}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ fingerprintId }),
+        signal: AbortSignal.timeout(15_000),
+      });
+    } catch (error) {
+      // Transient network/timeout failure — retry once on the same route. The
+      // donor's login path does the same (freebuff-proxy: fetchLoginUpstream)
+      // because a single jitter would otherwise bounce the whole login flow.
+      const err = error as { name?: string; code?: string };
+      const transient =
+        err?.name === "AbortError" ||
+        err?.name === "TypeError" ||
+        err?.code === "ECONNRESET" ||
+        err?.code === "ETIMEDOUT" ||
+        err?.code === "ENOTFOUND" ||
+        err?.code === "ECONNREFUSED" ||
+        err?.code === "EPIPE";
+      if (!transient) throw error;
+      res = await this.fetchFn(`${FREEBUFF_API_HOST}${CODE_PATH}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ fingerprintId }),
+        signal: AbortSignal.timeout(15_000),
+      });
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new GatewayError("platform_unavailable", 502, `Freebuff code issue failed (HTTP ${res.status}): ${text.slice(0, 200)} (request {requestId}).`, {}, "upstream");
+    }
+    const body: unknown = await res.json().catch(() => null);
+    if (!isRecord(body)) {
+      throw new GatewayError("platform_unavailable", 502, "Freebuff code issue returned an invalid body (request {requestId}).", {}, "upstream");
+    }
+    const loginUrl = typeof body["loginUrl"] === "string" ? body["loginUrl"] : "";
+    const fingerprintHash = typeof body["fingerprintHash"] === "string" ? body["fingerprintHash"] : "";
+    // The server reports expiresAt as an epoch-millisecond number; keep it as
+    // the raw value so the poll query matches what the donor sends (a string
+    // coercion of a numeric field was silently dropping it, leaving the poll
+    // URL incomplete — the upstream then answers 401 forever).
+    const expiresAtRaw = body["expiresAt"];
+    const expiresAt = typeof expiresAtRaw === "number" ? String(expiresAtRaw) : typeof expiresAtRaw === "string" ? expiresAtRaw : "";
+    if (!loginUrl || !fingerprintHash) {
+      throw new GatewayError("platform_unavailable", 502, "Freebuff code issue returned no login URL (request {requestId}).", {}, "upstream");
+    }
+    const state: CodeIssued = { loginUrl, fingerprintId, fingerprintHash, expiresAt };
+    return {
+      verificationUri: loginUrl,
+      userCode: fingerprintId.slice(0, 8),
+      deviceAuthId: fingerprintId,
+      intervalSeconds: 3,
+      expiresInSeconds: 3600,
+      providerState: JSON.stringify(state),
+    };
+  }
+
+  async pollDeviceAuth(deviceAuthId: string, context?: OAuthDeviceFlowContext): Promise<OAuthDevicePollResult> {
+    let state: CodeIssued;
+    try {
+      state = JSON.parse(context?.providerState ?? "") as CodeIssued;
+    } catch {
+      state = { loginUrl: "", fingerprintId: deviceAuthId, fingerprintHash: "", expiresAt: "" };
+    }
+    const params = new URLSearchParams({
+      fingerprintId: state.fingerprintId || deviceAuthId,
+    });
+    if (state.fingerprintHash) params.set("fingerprintHash", state.fingerprintHash);
+    if (state.expiresAt) params.set("expiresAt", state.expiresAt);
+    let res: Response;
+    try {
+      res = await this.fetchFn(`${FREEBUFF_API_HOST}${STATUS_PATH}?${params.toString()}`, {
+        method: "GET",
+        signal: AbortSignal.timeout(15_000),
+      });
+    } catch {
+      // Transient poll failure — the donor keeps polling through these; a
+      // dropped poll must not kill the flow.
+      return { status: "pending", retryAfterSeconds: 3 };
+    }
+    if (res.status === 401 || res.status === 404) {
+      // 401 is "not authorized yet" — the status endpoint refuses before the
+      // browser sign-in completes. Treat it as pending, never as a failure
+      // (mirrors freebuff-proxy: loginStatus -> 401 => { pending: true }).
+      return { status: "pending", retryAfterSeconds: 3 };
+    }
+    if (!res.ok) {
+      return { status: "pending", retryAfterSeconds: 3 };
+    }
+    const body: unknown = await res.json().catch(() => null);
+    if (!isRecord(body)) return { status: "pending", retryAfterSeconds: 3 };
+    const user = body["user"];
+    if (!isRecord(user)) return { status: "pending", retryAfterSeconds: 3 };
+    const authToken = typeof user["authToken"] === "string" ? user["authToken"] : "";
+    if (!authToken) return { status: "pending", retryAfterSeconds: 3 };
+    const accountId = typeof user["id"] === "string" ? user["id"] : undefined;
+    const email = typeof user["email"] === "string" ? user["email"] : undefined;
+    const name = typeof user["name"] === "string" ? user["name"] : undefined;
+    const device = await freebuffMintDeviceKey(authToken, {
+      fetchFn: this.fetchFn,
+      ...(accountId !== undefined ? { accountId } : {}),
+    });
+    const label = name ?? email;
+    return {
+      status: "complete",
+      result: {
+        access: authToken,
+        refresh: "",
+        expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+        ...(label ? { accountLabel: label } : {}),
+        auth_state: { ...(accountId !== undefined ? { accountId } : {}), device },
+      },
+    };
+  }
+
+  async importCredential(input: OAuthImportInput): Promise<OAuthExchangeResult> {
+    const token = input.fields["token"]?.trim();
+    if (!token) {
+      throw new GatewayError("invalid_request", 400, "Freebuff token is required (request {requestId}).", { providerId: "freebuff" });
+    }
+    // Validate by fetching /me.
+    const res = await this.fetchFn(`${FREEBUFF_API_HOST}/api/v1/me?fields=id,email,name`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+      throw new GatewayError("authentication_failed", 401, "Freebuff token is invalid (request {requestId}).", {}, "upstream");
+    }
+    const body: unknown = await res.json().catch(() => null);
+    const accountId = isRecord(body) && typeof body["id"] === "string" ? body["id"] : undefined;
+    const email = isRecord(body) && typeof body["email"] === "string" ? body["email"] : undefined;
+    const name = isRecord(body) && typeof body["name"] === "string" ? body["name"] : undefined;
+    const device = await freebuffMintDeviceKey(token, {
+      fetchFn: this.fetchFn,
+      ...(accountId !== undefined ? { accountId } : {}),
+    });
+    const label = name ?? email ?? input.accountLabel;
+    return {
+      access: token,
+      refresh: "",
+      expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+      ...(label ? { accountLabel: label } : {}),
+      auth_state: { ...(accountId !== undefined ? { accountId } : {}), device },
+    };
+  }
+}
+
+const client = new FreebuffOAuthClient();
+
+/** Config imported by the registry; device key lives in auth_state. */
+export const freebuffOAuthClient: OAuthLoginClient = client;
+
+// Re-export a helper so the catalog probe and other modules can validate a
+// pasted token without constructing the client.
+export async function freebuffValidateToken(token: string, fetchFn: typeof fetch = globalThis.fetch): Promise<string | undefined> {
+  const res = await fetchFn(`${FREEBUFF_API_HOST}${FREEBUFF_MODEL_CATALOG_PATH}`, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      [FREEBUFF_CATALOG_PROTOCOL_HEADER]: FREEBUFF_CATALOG_PROTOCOL_VERSION,
+      [FREEBUFF_CLIENT_HEADER]: FREEBUFF_CLIENT_HEADER_VALUE,
+    },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) return undefined;
+  const body: unknown = await res.json().catch(() => null);
+  return isRecord(body) && typeof body["fetchId"] === "string" ? body["fetchId"] : undefined;
+}

package/src/providers/integrations/freebuff/freebuff-quota.ts

@@ -0,0 +1,260 @@
+// Freebuff quota collector — TypeScript, Freebuff provider.
+//
+// Freebuff's billing surface is session-scoped: freebucks (balance, daily
+// limit/spent/reset) and per-model rate limits are reported by the session
+// endpoint, not by a static billing API. The collector reads the current
+// session read-only (`GET /api/v1/freebuff/session`) using the account's
+// device identity — it never performs an admission, so a quota refresh cannot
+// spend a session, lock a model purchase, or trip the upstream's gates.
+//
+// Session-active windows: Freebuff locks each purchased session to one model
+// until `expiresAt` (desktopPurchases). The session read returns those
+// purchases, so the collector emits one `session_active` window per purchase,
+// giving the provider-detail page its countdown pill ("Session · <model> ·
+// Expires in Nh Nm").
+//
+// When the account carries no device identity (auth_state), the session read
+// cannot be signed and is skipped; the collector then returns an empty quota
+// rather than manufacturing a probe.
+
+import type { QuotaFetcher } from "../../quota/quota-support";
+import type { ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
+import { isRecord } from "../../../protocol/codecs";
+import {
+  FREEBUFF_API_HOST,
+  FREEBUFF_CLIENT_HEADER,
+  FREEBUFF_CLIENT_HEADER_VALUE,
+  FREEBUFF_INSTALL_ID_HEADER,
+  FREEBUFF_SESSION_PATH,
+  FREEBUFF_ACTING_USER_HEADER,
+  FREEBUFF_ADMISSION_USER_AGENT,
+  freebuffSignRequest,
+} from "./freebuff";
+import type { FreebuffAuthState, FreebuffDeviceIdentity } from "./freebuff";
+import { freebuffVirtualIdFor } from "./freebuff-virtual";
+
+/**
+ * Parses `desktopPurchases` from the session body. Returns the active
+ * purchases (model + expiresAt) carried by the entitlement surface.
+ */
+function parsePurchases(body: Record<string, unknown>): Array<{ model: string; expiresAt: string }> {
+  const purchases = body["desktopPurchases"];
+  if (!Array.isArray(purchases)) return [];
+  const result: Array<{ model: string; expiresAt: string }> = [];
+  for (const raw of purchases) {
+    if (!isRecord(raw)) continue;
+    const model = typeof raw["model"] === "string" ? raw["model"] : undefined;
+    const expiresAt = typeof raw["expiresAt"] === "string" ? raw["expiresAt"] : undefined;
+    if (!model || !expiresAt) continue;
+    // The upstream reports the `m-<hex>` roster key; the catalog publishes the
+    // caller-facing virtual name, so the window must carry the same id a route
+    // candidate does (`filterCandidateQuotaWindows` matches modelIds).
+    result.push({ model: freebuffVirtualIdFor(model) ?? model, expiresAt });
+  }
+  return result;
+}
+
+function buildSessionWindows(purchases: Array<{ model: string; expiresAt: string }>): ProviderQuotaWindow[] {
+  const now = Date.now();
+  const windows: ProviderQuotaWindow[] = [];
+  for (const purchase of purchases) {
+    const expiresMs = new Date(purchase.expiresAt).getTime();
+    if (!Number.isFinite(expiresMs) || expiresMs <= now) continue;
+    const remainingMs = expiresMs - now;
+    const remainingMinutes = Math.max(1, Math.ceil(remainingMs / 60_000));
+    const remainingPercent = Math.min(100, Math.max(0, Math.round((remainingMs / 3_600_000) * 100)));
+    windows.push({
+      kind: "session_active",
+      label: "Session active",
+      accounting: "independent",
+      usedPercent: null,
+      remainingPercent,
+      modelIds: [purchase.model],
+      resetsAt: purchase.expiresAt,
+      remaining: remainingMinutes,
+      recurring: false,
+    });
+  }
+  return windows;
+}
+
+/** Normalizes the stored auth_state into a usable device identity. */
+function resolveDeviceIdentity(authState: unknown): FreebuffDeviceIdentity | undefined {
+  if (!isRecord(authState)) return undefined;
+  const device = authState["device"];
+  if (!isRecord(device)) return undefined;
+  const identity = device as Record<string, unknown>;
+  if (
+    typeof identity["version"] !== "number" ||
+    typeof identity["publicKey"] !== "string" ||
+    typeof identity["privateKey"] !== "string" ||
+    typeof identity["keyId"] !== "string" ||
+    typeof identity["installId"] !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    version: identity["version"] as 1,
+    publicKey: identity["publicKey"] as string,
+    privateKey: identity["privateKey"] as string,
+    keyId: identity["keyId"] as string,
+    installId: identity["installId"] as string,
+  };
+}
+
+function buildSessionHeaders(
+  token: string,
+  device: FreebuffDeviceIdentity,
+  accountId: string | undefined,
+  fetchId: string,
+): Promise<Record<string, string>> {
+  // The session read takes the same device signature as every other desktop
+  // request. The fetchId keeps the signature's payload unique per request.
+  return freebuffSignRequest(device, {
+    method: "GET",
+    path: FREEBUFF_SESSION_PATH,
+    fetchId,
+  }).then((signed) => ({
+    Authorization: `Bearer ${token}`,
+    [FREEBUFF_CLIENT_HEADER]: FREEBUFF_CLIENT_HEADER_VALUE,
+    [FREEBUFF_INSTALL_ID_HEADER]: device.installId,
+    ...(accountId === undefined ? {} : { [FREEBUFF_ACTING_USER_HEADER]: accountId }),
+    "user-agent": FREEBUFF_ADMISSION_USER_AGENT,
+    ...signed,
+  }));
+}
+
+export const fetchFreebuffQuota: QuotaFetcher = async (credential, fetcher, context) => {
+  const token = credential.trim();
+  const fetchFn = fetcher ?? globalThis.fetch;
+  const authState: FreebuffAuthState | undefined = isRecord(context?.auth_state)
+    ? (context.auth_state as FreebuffAuthState)
+    : undefined;
+  const device = resolveDeviceIdentity(authState);
+  if (!device) {
+    return {
+      source: "freebuff",
+      plan: null,
+      windows: [],
+      error: "Freebuff quota check requires the account's device identity (re-login to register one).",
+    };
+  }
+  const accountId =
+    authState !== undefined && typeof authState["accountId"] === "string"
+      ? authState["accountId"]
+      : context?.accountId;
+  const fetchId = crypto.randomUUID();
+  let headers: Record<string, string>;
+  try {
+    headers = await buildSessionHeaders(token, device, accountId, fetchId);
+  } catch (error) {
+    return {
+      source: "freebuff",
+      plan: null,
+      windows: [],
+      error: error instanceof Error ? error.message : "Failed to sign the Freebuff session request",
+    };
+  }
+  let res: Response;
+  try {
+    res = await fetchFn(`${FREEBUFF_API_HOST}${FREEBUFF_SESSION_PATH}`, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (error) {
+    return {
+      source: "freebuff",
+      plan: null,
+      windows: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  const body: unknown = await res.json().catch(() => null);
+  if (!res.ok || !isRecord(body)) {
+    return {
+      source: "freebuff",
+      plan: null,
+      windows: [],
+      error: `Freebuff quota check failed (HTTP ${res.status})`,
+    };
+  }
+  // The session surface carries the entitlement numbers and the active
+  // purchases. A malformed body yields empty windows; never fail the fetch.
+  const windows = buildQuotaWindows(body);
+  const purchases = parsePurchases(body);
+  const sessionWindows = buildSessionWindows(purchases);
+  const plan = typeof body["accessTier"] === "string" ? body["accessTier"] : null;
+  return {
+    source: "freebuff",
+    plan,
+    windows: [...windows, ...sessionWindows],
+    error: null,
+  };
+};
+
+function buildQuotaWindows(body: Record<string, unknown>): ProviderQuotaResult["windows"] {
+  const windows: ProviderQuotaWindow[] = [];
+  const freebucks = body["freebucks"];
+  if (isRecord(freebucks)) {
+    const balance = typeof freebucks["balance"] === "number" ? freebucks["balance"] : null;
+    const daily = freebucks["daily"];
+    if (isRecord(daily)) {
+      const limit = typeof daily["limit"] === "number" ? daily["limit"] : null;
+      const spent = typeof daily["spent"] === "number" ? daily["spent"] : null;
+      const remaining = typeof daily["remaining"] === "number" ? daily["remaining"] : null;
+      const resetAt = typeof daily["resetAt"] === "string" ? daily["resetAt"] : null;
+      windows.push({
+        kind: "freebucks_daily",
+        label: "Freebucks daily",
+        accounting: "pooled",
+        usedPercent: limit && spent !== null ? Math.round((spent / limit) * 100) : null,
+        remainingPercent: limit && remaining !== null ? Math.round((remaining / limit) * 100) : null,
+        resetsAt: resetAt,
+        used: spent,
+        limit,
+        remaining,
+        recurring: true,
+      });
+    }
+    if (balance !== null) {
+      windows.push({
+        kind: "freebucks_balance",
+        label: "Freebucks balance",
+        accounting: "pooled",
+        usedPercent: null,
+        remainingPercent: null,
+        resetsAt: null,
+        remaining: balance,
+      });
+    }
+  }
+  // Rate limits are reported per model in `rateLimitsByModel` (a map keyed by
+  // model id).
+  const rateLimitsByModel = body["rateLimitsByModel"];
+  if (isRecord(rateLimitsByModel)) {
+    for (const [modelId, raw] of Object.entries(rateLimitsByModel)) {
+      if (!isRecord(raw)) continue;
+      const limit = typeof raw["limit"] === "number" ? raw["limit"] : null;
+      const recentCount = typeof raw["recentCount"] === "number" ? raw["recentCount"] : null;
+      const resetAt = typeof raw["resetAt"] === "string" ? raw["resetAt"] : null;
+      if (limit === null) continue;
+      windows.push({
+        kind: "rate_limit",
+        label: "Daily session rate limit",
+        accounting: "independent",
+        // Publish the caller-facing virtual name, matching the catalog and the
+        // routing candidate id (`filterCandidateQuotaWindows`).
+        modelIds: [freebuffVirtualIdFor(modelId) ?? modelId],
+        usedPercent: recentCount !== null && limit > 0 ? Math.round((recentCount / limit) * 100) : null,
+        remainingPercent: recentCount !== null && limit > 0 ? Math.round(((limit - recentCount) / limit) * 100) : null,
+        resetsAt: resetAt,
+        used: recentCount,
+        limit,
+        remaining: recentCount !== null ? limit - recentCount : null,
+        recurring: true,
+      });
+    }
+  }
+  return windows;
+}