@cad0p/pi-usage 0.0.0-stage → 0.11.2

package/src/providers/antigravity.js

@@ -0,0 +1,225 @@
+/**
+ * Antigravity (Google AI Pro / Cloud Code) quota from a Pi OAuth access token.
+ *
+ * Endpoint: POST https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary
+ * Body:     { "project": "<cloudaicompanionProject>" }
+ *
+ * The CLI `User-Agent` is mandatory: without it the Cloud Code backend answers
+ * 403 "You do not have a valid license of this product" even for a healthy
+ * token. Verbose but verified.
+ *
+ * Response shape: `groups[].buckets[]` with
+ * `{ bucketId, displayName, window, resetTime, remainingFraction, description }`.
+ *
+ * Google does not rotate this refresh token, but Pi owns the credential and this
+ * project is read-only, so no refresh is performed here either.
+ */
+
+import { buildWindow, clampPercent, degradedResult, displayIdentity, finiteNumber, stringValue, windowFromName } from "../model.js";
+import { requestJson } from "../http.js";
+import { describeOAuthClient, ensureFreshAccessToken } from "./antigravity-oauth.js";
+
+const CLOUD_CODE_BASES = [
+  "https://daily-cloudcode-pa.googleapis.com",
+  "https://cloudcode-pa.googleapis.com",
+];
+const CLI_USER_AGENT =
+  "antigravity/cli/1.1.13 (aidev_client; os_type=linux; arch=amd64; cl=964361259; auth_method=consumer)";
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown> | null}
+ */
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : null;
+}
+
+/**
+ * Resolve a Cloud Code project id through loadCodeAssist.
+ *
+ * @param {string} access
+ * @param {string} base
+ * @param {typeof fetch | undefined} fetchFn
+ * @param {number | undefined} timeoutMs
+ * @returns {Promise<string | null>}
+ */
+async function resolveProjectId(access, base, fetchFn, timeoutMs) {
+  const response = await requestJson(`${base}/v1internal:loadCodeAssist`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${access}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": CLI_USER_AGENT,
+    },
+    body: JSON.stringify({ metadata: { ideType: "ANTIGRAVITY" } }),
+    fetchFn,
+    timeoutMs,
+  });
+  if (!response.ok) return null;
+  const body = record(response.body);
+  const project = body?.cloudaicompanionProject;
+  if (typeof project === "string" && project) return project;
+  const projectRecord = record(project);
+  return stringValue(projectRecord?.id) ?? stringValue(projectRecord?.name);
+}
+
+/**
+ * Short group tag so multi-group accounts read as "Gemini · 5h window" and
+ * "Claude/GPT · 5h window" instead of two identical rows.
+ *
+ * @param {string} groupName
+ * @returns {string}
+ */
+function shortGroup(groupName) {
+  const text = groupName.toLowerCase();
+  if (text.includes("gemini")) return "Gemini";
+  if (text.includes("claude") || text.includes("gpt")) return "Claude/GPT";
+  return groupName.split(/\s+/)[0] || "Models";
+}
+
+/**
+ * @param {Record<string, unknown>} bucket
+ * @param {{ groupName: string, multiGroup: boolean }} context
+ * @param {number} now
+ * @returns {import("../model.js").QuotaWindow | null}
+ */
+function windowFromBucket(bucket, context, now) {
+  const remainingFraction = finiteNumber(bucket.remainingFraction ?? bucket.remaining_fraction);
+  if (remainingFraction === null) return null;
+
+  const windowName = stringValue(bucket.window) ?? stringValue(bucket.bucketId) ?? "";
+  const mapped = windowFromName(windowName.replace(/^[a-z]+-/, ""));
+  const displayName = stringValue(bucket.displayName);
+  const description = stringValue(bucket.description);
+  const tag = context.multiGroup ? `${shortGroup(context.groupName)} · ` : "";
+  // Short, uniform vocabulary so Antigravity's windows read like the other
+  // providers'; the API's own wording is preserved in the note.
+  const kind = mapped.id === "5h" || mapped.id === "weekly" || mapped.id === "monthly" ? mapped.id : mapped.label;
+
+  return buildWindow({
+    id: context.multiGroup ? `${shortGroup(context.groupName).toLowerCase().replace(/[^a-z]+/g, "-")}-${mapped.id}` : mapped.id,
+    label: `${tag}${kind}`,
+    remainingPercent: clampPercent(remainingFraction * 100),
+    resetsAt: stringValue(bucket.resetTime),
+    note: [displayName, description].filter(Boolean).join(" — ") || null,
+    now,
+  });
+}
+
+/**
+ * @param {import("../auth/pi-auth.js").PiCredential} credential
+ * @param {{ now?: number, fetchFn?: typeof fetch, timeoutMs?: number, expiresInMin?: number | null, env?: Record<string, string | undefined>, refresh?: boolean }} [options]
+ * @returns {Promise<import("../model.js").QuotaResult>}
+ */
+export async function fetchQuota(credential, options = {}) {
+  const now = options.now ?? Date.now();
+  const base = {
+    family: "antigravity",
+    label: "Antigravity (Pi)",
+    account: displayIdentity(credential),
+    source: credential.source,
+    sourceKind: credential.sourceKind ?? "pi",
+    expiresInMin: options.expiresInMin ?? null,
+  };
+
+  if (!credential.access && !credential.refresh) {
+    return degradedResult({ ...base, error: "Pi store has no antigravity credential; run /login antigravity in Pi" });
+  }
+
+  const fetchFn = options.fetchFn;
+  const account = { access: credential.access, refresh: credential.refresh, expiresAtMs: credential.expiresAtMs ?? null };
+
+  // In-memory refresh only: Google does not rotate this refresh token, so the
+  // copy Pi stores stays valid and nothing is written back.
+  const freshness = await ensureFreshAccessToken(account, {
+    fetchFn,
+    timeoutMs: options.timeoutMs,
+    now,
+    enabled: options.refresh,
+  });
+  let projectId = credential.projectId ?? null;
+
+  /** @type {string | null} */
+  let lastError = null;
+  let authFailed = false;
+
+  for (const cloudBase of CLOUD_CODE_BASES) {
+    if (!projectId && account.access) {
+      projectId = await resolveProjectId(account.access, cloudBase, fetchFn, options.timeoutMs);
+    }
+    if (!projectId) {
+      lastError = "Antigravity credential has no Cloud Code project id and loadCodeAssist did not return one";
+      continue;
+    }
+    if (!account.access) {
+      lastError = freshness.error
+        ? `Antigravity access token unusable: ${freshness.error}`
+        : "Antigravity access token is missing from the Pi store";
+      continue;
+    }
+
+    const response = await requestJson(`${cloudBase}/v1internal:retrieveUserQuotaSummary`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${account.access}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": CLI_USER_AGENT,
+      },
+      body: JSON.stringify({ project: projectId }),
+      fetchFn,
+      timeoutMs: options.timeoutMs,
+    });
+
+    if (!response.ok) {
+      authFailed = Boolean(response.authError);
+      lastError = response.authError
+        ? "Antigravity token rejected; run /login antigravity in Pi"
+        : `Antigravity quota request failed: ${response.error}`;
+      continue;
+    }
+
+    authFailed = false;
+
+    const body = record(response.body) ?? {};
+    const groups = (Array.isArray(body.groups) ? body.groups : [])
+      .map((rawGroup) => record(rawGroup))
+      .filter((group) => Array.isArray(group?.buckets) && group.buckets.length > 0);
+    const multiGroup = groups.length > 1;
+
+    /** @type {import("../model.js").QuotaWindow[]} */
+    const windows = [];
+    for (const group of groups) {
+      if (!group) continue;
+      const groupName = stringValue(group.displayName) ?? "Models";
+      const buckets = Array.isArray(group.buckets) ? group.buckets : [];
+      for (const rawBucket of buckets) {
+        const bucket = record(rawBucket);
+        if (!bucket) continue;
+        const window = windowFromBucket(bucket, { groupName, multiGroup }, now);
+        if (window) windows.push(window);
+      }
+    }
+
+    if (windows.length === 0) {
+      lastError = "Antigravity quota response contained no buckets (free tier may expose none for this account)";
+      continue;
+    }
+
+    return {
+      ...base,
+      account: projectId ? `${displayIdentity(credential)} · ${projectId.slice(0, 8)}…` : displayIdentity(credential),
+      plan: stringValue(body.paidTier) ?? stringValue(body.currentTier),
+      windows,
+      error: null,
+      ok: true,
+      updatedAt: new Date(now).toISOString(),
+    };
+  }
+
+  const suffix = authFailed ? ` (${describeOAuthClient({ env: options.env })})` : "";
+  return degradedResult({ ...base, error: `${lastError ?? "Antigravity quota unavailable"}${suffix}` });
+}

package/src/providers/backoff.js

@@ -0,0 +1,146 @@
+/**
+ * Per-provider backoff for throttled usage endpoints.
+ *
+ * The lesson this encodes: polling Anthropic's usage endpoint once a minute
+ * gets it rate-limited, and the `retry-after` header is not always honest
+ * (`retry in 0s` while still answering 429). Without a persisted backoff, every
+ * process restart resumes hammering and the card stays degraded for longer than
+ * it needs to.
+ *
+ * A throttled family is skipped entirely until its backoff expires; the Moshi
+ * layer then republishes the previous good snapshot, so the card survives.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const DEFAULT_BACKOFF_MS = 5 * 60 * 1000;
+const MAX_BACKOFF_MS = 30 * 60 * 1000;
+
+/**
+ * @param {{ env?: Record<string, string | undefined>, home?: string, path?: string }} [options]
+ * @returns {string}
+ */
+export function resolveBackoffPath(options = {}) {
+  if (options.path) return options.path;
+  const env = options.env ?? process.env;
+  const cacheHome = options.home ? join(options.home, ".cache") : (env.XDG_CACHE_HOME || join(homedir(), ".cache"));
+  return join(cacheHome, "pi-quota", "backoff.json");
+}
+
+/**
+ * @param {{ env?: Record<string, string | undefined>, home?: string, path?: string }} [options]
+ * @returns {Record<string, number>}
+ */
+export function readBackoff(options = {}) {
+  try {
+    const parsed = JSON.parse(readFileSync(resolveBackoffPath(options), "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {Record<string, number>} state
+ * @param {{ env?: Record<string, string | undefined>, home?: string, path?: string }} [options]
+ * @returns {boolean}
+ */
+function writeBackoff(state, options = {}) {
+  const path = resolveBackoffPath(options);
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(state, null, 2), { encoding: "utf-8", mode: 0o600 });
+    try {
+      chmodSync(temporary, 0o600);
+    } catch {
+      // Best-effort in environments where chmod is not supported.
+    }
+    renameSync(temporary, path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} family
+ * @param {{ now?: number, env?: Record<string, string | undefined>, home?: string, path?: string }} [options]
+ * @returns {{ active: boolean, untilMs: number | null, secondsLeft: number | null }}
+ */
+export function backoffState(family, options = {}) {
+  const now = options.now ?? Date.now();
+  const untilMs = readBackoff(options)[family] ?? null;
+  if (untilMs === null || untilMs <= now) {
+    return { active: false, untilMs, secondsLeft: null };
+  }
+  return { active: true, untilMs, secondsLeft: Math.round((untilMs - now) / 1000) };
+}
+
+/**
+ * Record a throttle for a family.
+ *
+ * @param {string} family
+ * @param {{ retryAfterSec?: number | null, now?: number, env?: Record<string, string | undefined>, home?: string, path?: string }} [options]
+ * @returns {{ untilMs: number, seconds: number }}
+ */
+export function recordBackoff(family, options = {}) {
+  const now = options.now ?? Date.now();
+  const retryAfterMs =
+    typeof options.retryAfterSec === "number" && options.retryAfterSec > 0
+      ? options.retryAfterSec * 1000
+      : DEFAULT_BACKOFF_MS;
+  const duration = Math.min(Math.max(retryAfterMs, DEFAULT_BACKOFF_MS), MAX_BACKOFF_MS);
+  const state = readBackoff(options);
+  state[family] = now + duration;
+  writeBackoff(state, options);
+  return { untilMs: state[family], seconds: Math.round(duration / 1000) };
+}
+
+/**
+ * @param {string} family
+ * @param {{ env?: Record<string, string | undefined>, home?: string, path?: string }} [options]
+ * @returns {boolean}
+ */
+export function clearBackoff(family, options = {}) {
+  const state = readBackoff(options);
+  if (!(family in state)) return false;
+  delete state[family];
+  return writeBackoff(state, options);
+}
+
+/**
+ * True when an error is a throttle worth backing off from.
+ *
+ * @param {string | null} error
+ * @returns {boolean}
+ */
+export function isThrottled(error) {
+  return typeof error === "string" && /HTTP 429|rate limited/i.test(error);
+}
+
+/**
+ * True when an error represents an authentication or credential failure rather than
+ * a rate-limiting throttle. Authentication failures supersede throttling because
+ * waiting out a backoff window cannot fix an expired or invalid credential.
+ *
+ * @param {string | null} error
+ * @returns {boolean}
+ */
+export function isAuthFailure(error) {
+  if (!error || typeof error !== "string") return false;
+  return /401|403|unauthorized|forbidden|token expired|sign-in expired|expired or rejected|re-authenticate|invalid_grant|no .*access token/i.test(error);
+}
+
+/**
+ * Extract a retry hint from an error string such as "retry in 212s".
+ *
+ * @param {string | null} error
+ * @returns {number | null}
+ */
+export function retryAfterFromError(error) {
+  const match = typeof error === "string" ? error.match(/retry in (\d+)s/) : null;
+  return match ? Number(match[1]) : null;
+}

package/src/providers/claude.js

@@ -0,0 +1,194 @@
+/**
+ * Claude (Anthropic) quota from a Pi OAuth access token.
+ *
+ * Endpoint: GET https://api.anthropic.com/api/oauth/usage
+ * Required: the OAuth beta header; a plain Bearer token is rejected without it.
+ * Windows: `five_hour` and `seven_day`, each `{ utilization, resets_at }`.
+ *
+ * Two sources feed this provider, and the caller picks one:
+ *
+ *   - Pi's own `anthropic` entry in auth.json;
+ *   - the Claude Code CLI store (`~/.claude/.credentials.json`), which the
+ *     `pi-claude-code-provider` package drives. On a subscription whose usage
+ *     credits are disabled, Pi's own entry can answer HTTP 400 for every request,
+ *     and this is the source that still works.
+ *
+ * Either way no refresh is attempted. Anthropic rotates refresh tokens, so
+ * refreshing here would invalidate the copy the owning tool has stored — and for
+ * Claude Code that tool is the installed CLI, which keeps its own token fresh.
+ */
+
+import { degradedResult, buildWindow, clampPercent, displayIdentity, finiteNumber, parseReset, stringValue } from "../model.js";
+import { requestJson } from "../http.js";
+
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown> | null}
+ */
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : null;
+}
+
+/**
+ * @param {Record<string, unknown>} window
+ * @param {string} id
+ * @param {string} label
+ * @param {string | null} note
+ * @param {number} now
+ * @returns {import("../model.js").QuotaWindow | null}
+ */
+function windowFromObject(window, id, label, note, now) {
+  const used = clampPercent(window.utilization ?? window.percent ?? window.used_percent);
+  if (used === null) return null;
+  const resets = parseReset(window.resets_at, now);
+  return buildWindow({
+    id,
+    label,
+    usedPercent: used,
+    resetsAt: resets.resetsAt,
+    note,
+    now,
+  });
+}
+
+/**
+ * Some accounts report windows only through the newer `limits[]` array.
+ *
+ * @param {unknown} limits
+ * @param {string} id
+ * @param {number} now
+ * @returns {import("../model.js").QuotaWindow | null}
+ */
+function windowFromLimits(limits, id, now) {
+  if (!Array.isArray(limits)) return null;
+  for (const entry of limits) {
+    const limit = record(entry);
+    if (!limit || limit.is_active === false) continue;
+    const kind = `${stringValue(limit.kind) ?? ""} ${stringValue(limit.group) ?? ""}`.toLowerCase();
+    const matches =
+      id === "5h"
+        ? kind.includes("session") || kind.includes("five") || kind.includes("5h")
+        : kind.includes("week") || kind.includes("7d");
+    if (!matches) continue;
+    const used = clampPercent(limit.percent);
+    if (used === null) continue;
+    const resets = parseReset(limit.resets_at, now);
+    return buildWindow({
+      id,
+      label: id === "5h" ? "5h window" : "Weekly window",
+      usedPercent: used,
+      resetsAt: resets.resetsAt,
+      note: stringValue(limit.severity) ? `severity ${stringValue(limit.severity)}` : null,
+      now,
+    });
+  }
+  return null;
+}
+
+/**
+ * Render the extra-usage (overage) figure using the provider's own decimal
+ * scale, so 2908 credits with decimal_places=2 reads as "29.08 USD".
+ *
+ * @param {Record<string, unknown>} extra
+ * @returns {string | null}
+ */
+function formatOverage(extra) {
+  if (extra.is_enabled !== true) return null;
+  const credits = finiteNumber(extra.used_credits);
+  if (credits === null) return null;
+  const decimals = finiteNumber(extra.decimal_places);
+  const amount = decimals === null ? credits : credits / Math.pow(10, decimals);
+  const currency = stringValue(extra.currency);
+  return `extra usage ${amount.toFixed(decimals ?? 0)}${currency ? ` ${currency}` : ""}`;
+}
+
+/**
+ * @param {import("../auth/pi-auth.js").PiCredential} credential
+ * @param {{ now?: number, fetchFn?: typeof fetch, timeoutMs?: number, expiresInMin?: number | null }} [options]
+ * @returns {Promise<import("../model.js").QuotaResult>}
+ */
+export async function fetchQuota(credential, options = {}) {
+  const now = options.now ?? Date.now();
+  const fromClaudeCode = credential.sourceKind === "claude-code";
+  const base = {
+    family: "claude",
+    // The label never changes: it marks the card as ours in Moshi, and which
+    // store was read is reported by `sourceKind` instead, where it is diagnostic.
+    label: credential.label ?? "Claude (Pi)",
+    account: displayIdentity(credential),
+    source: credential.source,
+    sourceKind: credential.sourceKind ?? "pi",
+    expiresInMin: options.expiresInMin ?? null,
+  };
+
+  if (!credential.access) {
+    return degradedResult({
+      ...base,
+      error: fromClaudeCode
+        ? `Claude Code store has no access token; run \`claude\` once to sign in (${credential.source})`
+        : "Pi store has no anthropic access token; run /login anthropic in Pi",
+    });
+  }
+
+  const response = await requestJson(USAGE_URL, {
+    headers: {
+      Authorization: `Bearer ${credential.access}`,
+      "anthropic-version": "2023-06-01",
+      "anthropic-beta": "oauth-2025-04-20",
+    },
+    fetchFn: options.fetchFn,
+    timeoutMs: options.timeoutMs,
+  });
+
+  if (!response.ok) {
+    const error = response.authError
+      ? fromClaudeCode
+        ? "Claude Code token expired or rejected; run `claude` once to refresh it"
+        : "Claude token expired or rejected; use any Claude model in Pi to refresh it"
+      : `Claude usage request failed: ${response.error}`;
+    return degradedResult({ ...base, error });
+  }
+
+  const body = record(response.body) ?? {};
+  const extra = record(body.extra_usage);
+  const overageNote = extra ? formatOverage(extra) : null;
+
+  /** @type {import("../model.js").QuotaWindow[]} */
+  const windows = [];
+  const fiveHour = record(body.five_hour);
+  const sevenDay = record(body.seven_day);
+  const fromFiveHour = fiveHour ? windowFromObject(fiveHour, "5h", "5h window", null, now) : null;
+  const fromSevenDay = sevenDay ? windowFromObject(sevenDay, "weekly", "Weekly window", overageNote, now) : null;
+  if (fromFiveHour) windows.push(fromFiveHour);
+  if (fromSevenDay) windows.push(fromSevenDay);
+  if (!fromFiveHour) {
+    const fallback = windowFromLimits(body.limits, "5h", now);
+    if (fallback) windows.push(fallback);
+  }
+  if (!fromSevenDay) {
+    const fallback = windowFromLimits(body.limits, "weekly", now);
+    if (fallback) windows.push(fallback);
+  }
+
+  if (windows.length === 0) {
+    return degradedResult({
+      ...base,
+      error: "Claude usage response had no recognizable rate-limit windows (API shape may have changed)",
+    });
+  }
+
+  return {
+    ...base,
+    // Claude Code reports the subscription tier it signed in with; Pi's own entry
+    // carries no plan field at all.
+    plan: credential.planType ?? null,
+    windows,
+    error: null,
+    ok: true,
+    updatedAt: new Date(now).toISOString(),
+  };
+}