paseo-smart-session 1.2.1

package/server/settings.ts

@@ -0,0 +1,225 @@
+/**
+ * Plugin settings, on disk next to the data.
+ *
+ * Paseo has no plugin-settings API, so preferences are our own file — the same
+ * approach paseo-defer takes.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { dataDir } from "./store.ts";
+import { DEFAULT_THRESHOLDS, normalizeThresholds, type Thresholds } from "../shared/thresholds.ts";
+
+export interface Settings {
+  /**
+   * The master switch: whether Smart Compact runs at all.
+   *
+   * Off means the `Stop` hook never asks, the pill is not drawn, and a queued
+   * compaction is not delivered. It is the one control that has to be
+   * unambiguous, because everything else here only qualifies it.
+   *
+   * On by default. It was safe to make it so once the plugin lost the ability to
+   * compact a session that had not asked: the worst it can now do is put a
+   * question to an agent that ignores it.
+   */
+  readonly enabled: boolean;
+  /**
+   * When a context counts as too full, per window size.
+   *
+   * The `Stop` hook asks at the `compact` band of whichever profile applies, so a
+   * 1M session is asked at 300k rather than being left to drift to 850k.
+   */
+  readonly thresholds: Thresholds;
+  /** A state file older than this is treated as not describing the current work. */
+  readonly freshStateMinutes: number;
+  /**
+   * Whether every agent's composer carries the smart-compact pill.
+   *
+   * On by default. Enrolment is otherwise invisible — it is a file on disk — and a
+   * governor you cannot see the state of is one you stop trusting.
+   */
+  readonly showPill: boolean;
+  /**
+   * Whether a session that checkpoints is enrolled without being asked.
+   *
+   * This is the on-by-default-or-opt-in choice. On, an agent that has used the
+   * checkpoint tool has shown it knows this system exists, and that is taken as
+   * consent. Off, nothing is inferred and a session is governed only when someone
+   * presses its pill. An explicit answer outranks either way round.
+   */
+  readonly autoEnrol: boolean;
+  /**
+   * Whether the plugin keeps its hooks registered in Claude Code for us.
+   *
+   * On by default, because the `Stop` hook is the only thing that ever asks a
+   * session to compact itself: without it this plugin records and shows charts and
+   * otherwise does nothing, which is a worse failure than an unexpected write —
+   * it looks like it is working. Off removes every entry it added.
+   *
+   * See `server/install.ts` for what it will and will not touch.
+   */
+  readonly installHooks: boolean;
+}
+
+export const DEFAULT_SETTINGS: Settings = {
+  enabled: true,
+  thresholds: DEFAULT_THRESHOLDS,
+  freshStateMinutes: 30,
+  showPill: true,
+  autoEnrol: true,
+  installHooks: true,
+};
+
+const filePath = () => join(dataDir(), "settings.json");
+
+let cached: Settings | null = null;
+
+export async function readSettings(): Promise<Settings> {
+  if (cached !== null) return cached;
+  try {
+    const raw = JSON.parse(await readFile(filePath(), "utf8")) as Partial<Settings>;
+    cached = {
+      // Absent in every file written before v0.3. Those installs had `autopilot`,
+      // which meant "compact without being asked" and no longer exists; the
+      // feature they are upgrading into can only ask, so it starts on.
+      enabled: raw.enabled !== false,
+      thresholds: normalizeThresholds(raw.thresholds),
+      freshStateMinutes: clamp(raw.freshStateMinutes ?? DEFAULT_SETTINGS.freshStateMinutes, 1, 24 * 60),
+      showPill: raw.showPill !== false,
+      autoEnrol: raw.autoEnrol !== false,
+      installHooks: raw.installHooks !== false,
+    };
+  } catch {
+    cached = DEFAULT_SETTINGS;
+  }
+  return cached;
+}
+
+export async function writeSettings(patch: Partial<Settings>): Promise<Settings> {
+  const next: Settings = { ...(await readSettings()), ...patch };
+  const settings: Settings = {
+    enabled: next.enabled !== false,
+    thresholds: normalizeThresholds(next.thresholds),
+    freshStateMinutes: clamp(next.freshStateMinutes, 1, 24 * 60),
+    showPill: next.showPill !== false,
+    autoEnrol: next.autoEnrol !== false,
+    installHooks: next.installHooks !== false,
+  };
+  await mkdir(dataDir(), { recursive: true });
+  const target = filePath();
+  const temp = `${target}.${randomUUID()}.tmp`;
+  await writeFile(temp, JSON.stringify(settings, null, 2), "utf8");
+  await rename(temp, target);
+  cached = settings;
+  return settings;
+}
+
+export function clearSettingsCache(): void {
+  cached = null;
+}
+
+function clamp(value: number, low: number, high: number): number {
+  if (!Number.isFinite(value)) return low;
+  return Math.min(high, Math.max(low, value));
+}
+
+/** Where an agent's durable task state lives; mirrors the agent-facing tool. */
+export function statePathFor(agentId: string): string {
+  return join(dataDir(), "state", `${agentId}.md`);
+}
+
+
+/**
+ * Whether the governor may speak to one agent, and who decided.
+ *
+ * Implicit by default: an agent that has written a state file has used the
+ * checkpoint tool, and so knows this system exists. One that has not is never
+ * spoken to, however full it gets. `autoEnrol` turns that inference off entirely,
+ * which is the difference between on-by-default and opt-in. A person can override
+ * either way — that is what the pill on the composer writes — and an explicit
+ * answer always outranks the inferred one.
+ */
+export interface AgentEnrolment {
+  readonly agentId: string;
+  readonly enrolled: boolean;
+  /** True when a person said so, false when it was inferred from a state file. */
+  readonly explicit: boolean;
+}
+
+const overridesPath = () => join(dataDir(), "enrolment.json");
+
+/** One writer at a time: a toggle is read-modify-write over a shared file. */
+let tail: Promise<unknown> = Promise.resolve();
+
+function serialize<T>(work: () => Promise<T>): Promise<T> {
+  const next = tail.then(work, work);
+  tail = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  return next;
+}
+
+async function readOverrides(): Promise<Record<string, boolean>> {
+  try {
+    const raw = JSON.parse(await readFile(overridesPath(), "utf8")) as Record<string, unknown>;
+    const overrides: Record<string, boolean> = {};
+    for (const [agentId, value] of Object.entries(raw)) {
+      if (typeof value === "boolean") overrides[agentId] = value;
+    }
+    return overrides;
+  } catch {
+    // No file, or one we cannot read: nobody has overridden anything.
+    return {};
+  }
+}
+
+async function agentsWithState(): Promise<string[]> {
+  try {
+    const names = await readdir(join(dataDir(), "state"));
+    return names.filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -".md".length));
+  } catch {
+    return [];
+  }
+}
+
+/** Sets, or reverses, one agent's enrolment by hand. */
+export function setEnrolled(agentId: string, enrolled: boolean): Promise<AgentEnrolment> {
+  return serialize(async () => {
+    const overrides = await readOverrides();
+    overrides[agentId] = enrolled;
+    await mkdir(dataDir(), { recursive: true });
+    const target = overridesPath();
+    const temp = `${target}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(overrides, null, 2), "utf8");
+    await rename(temp, target);
+    return { agentId, enrolled, explicit: true };
+  });
+}
+
+/**
+ * Every agent this plugin has an opinion about.
+ *
+ * An agent absent from this list is simply not enrolled: it has never checkpointed
+ * and nobody has asked for it.
+ */
+export async function listEnrolment(): Promise<AgentEnrolment[]> {
+  const { autoEnrol } = await readSettings();
+  const resolved = new Map<string, AgentEnrolment>();
+  if (autoEnrol) {
+    for (const agentId of await agentsWithState()) {
+      resolved.set(agentId, { agentId, enrolled: true, explicit: false });
+    }
+  }
+  for (const [agentId, enrolled] of Object.entries(await readOverrides())) {
+    resolved.set(agentId, { agentId, enrolled, explicit: true });
+  }
+  return [...resolved.values()];
+}
+
+/** How many agents the governor would speak to. */
+export async function countEnrolled(): Promise<number> {
+  return (await listEnrolment()).filter((agent) => agent.enrolled).length;
+}

package/server/spend.ts

@@ -0,0 +1,137 @@
+/**
+ * Rolling the raw hourly buckets into the few shapes a person actually reads.
+ *
+ * Aggregation happens here rather than in the client because the raw index is over
+ * a thousand buckets and a panel needs about forty numbers.
+ */
+
+import { readSpend, scanSpend, type SpendBucket } from "./backfill.ts";
+
+/** Tokens that cost something. Cache reads are excluded — they are the cheap part. */
+function billable(bucket: SpendBucket): number {
+  return bucket.input + bucket.cacheWrite + bucket.output;
+}
+
+export interface DayPoint {
+  readonly day: string;
+  readonly tokens: number;
+  readonly messages: number;
+}
+
+export interface HeatCell {
+  /** 0 = Sunday, matching Date#getDay. */
+  readonly weekday: number;
+  readonly hour: number;
+  readonly tokens: number;
+}
+
+export interface NamedTotal {
+  readonly name: string;
+  readonly tokens: number;
+}
+
+export interface SpendSummary {
+  readonly byDay: DayPoint[];
+  readonly heatmap: HeatCell[];
+  readonly byProject: NamedTotal[];
+  readonly byModel: NamedTotal[];
+  readonly totalTokens: number;
+  readonly subagentTokens: number;
+  /** Share of input tokens served from cache — the biggest single cost lever. */
+  readonly cacheHitPct: number;
+  readonly firstHour: string | null;
+  readonly lastHour: string | null;
+  readonly bucketCount: number;
+}
+
+const EMPTY: SpendSummary = {
+  byDay: [],
+  heatmap: [],
+  byProject: [],
+  byModel: [],
+  totalTokens: 0,
+  subagentTokens: 0,
+  cacheHitPct: 0,
+  firstHour: null,
+  lastHour: null,
+  bucketCount: 0,
+};
+
+/**
+ * `rescan` walks the transcripts for anything new first. It is incremental — each
+ * file is read only from where the last scan stopped — so a re-scan of 600MB of
+ * history costs about a tenth of a second.
+ */
+export async function summarizeSpend(options: { days?: number; rescan?: boolean } = {}): Promise<SpendSummary> {
+  const days = options.days ?? 30;
+  const sinceMs = Date.now() - days * 24 * 60 * 60 * 1000;
+  if (options.rescan === true) await scanSpend();
+  return rollup(await readSpend(sinceMs));
+}
+
+/** The pure half: buckets in, the shapes a panel reads out. */
+export function rollup(buckets: readonly SpendBucket[]): SpendSummary {
+  if (buckets.length === 0) return EMPTY;
+
+  const byDay = new Map<string, { tokens: number; messages: number }>();
+  const heat = new Map<string, number>();
+  const byProject = new Map<string, number>();
+  const byModel = new Map<string, number>();
+
+  let totalTokens = 0;
+  let subagentTokens = 0;
+  let cacheRead = 0;
+  let freshInput = 0;
+  let firstHour: string | null = null;
+  let lastHour: string | null = null;
+
+  for (const bucket of buckets) {
+    const tokens = billable(bucket);
+    totalTokens += tokens;
+    if (bucket.sidechain) subagentTokens += tokens;
+    cacheRead += bucket.cacheRead;
+    freshInput += bucket.input + bucket.cacheWrite;
+
+    if (firstHour === null || bucket.hour < firstHour) firstHour = bucket.hour;
+    if (lastHour === null || bucket.hour > lastHour) lastHour = bucket.hour;
+
+    const day = bucket.hour.slice(0, 10);
+    const dayTotal = byDay.get(day) ?? { tokens: 0, messages: 0 };
+    dayTotal.tokens += tokens;
+    dayTotal.messages += bucket.messages;
+    byDay.set(day, dayTotal);
+
+    // The hour string is UTC; the question "when do I work hardest" is about local
+    // time, so it is converted before bucketing.
+    const local = new Date(`${bucket.hour}:00:00Z`);
+    const key = `${local.getDay()}|${local.getHours()}`;
+    heat.set(key, (heat.get(key) ?? 0) + tokens);
+
+    byProject.set(bucket.project, (byProject.get(bucket.project) ?? 0) + tokens);
+    byModel.set(bucket.model, (byModel.get(bucket.model) ?? 0) + tokens);
+  }
+
+  const named = (map: Map<string, number>): NamedTotal[] =>
+    [...map.entries()]
+      .map(([name, tokens]) => ({ name, tokens }))
+      .sort((a, b) => b.tokens - a.tokens)
+      .slice(0, 8);
+
+  return {
+    byDay: [...byDay.entries()]
+      .map(([day, totals]) => ({ day, ...totals }))
+      .sort((a, b) => a.day.localeCompare(b.day)),
+    heatmap: [...heat.entries()].map(([key, tokens]) => {
+      const [weekday, hour] = key.split("|");
+      return { weekday: Number(weekday), hour: Number(hour), tokens };
+    }),
+    byProject: named(byProject),
+    byModel: named(byModel),
+    totalTokens,
+    subagentTokens,
+    cacheHitPct: cacheRead + freshInput === 0 ? 0 : (cacheRead / (cacheRead + freshInput)) * 100,
+    firstHour,
+    lastHour,
+    bucketCount: buckets.length,
+  };
+}

package/server/store.ts

@@ -0,0 +1,201 @@
+/**
+ * Append-only logs under `$PASEO_HOME/plugin-data/smart-session/`.
+ *
+ * Plan-usage history exists nowhere else — not in Claude Code, not in Paseo — so
+ * these files are the only copy. That shapes every choice here: append rather than
+ * rewrite, one line per observation, never rewrite a line once written, and read
+ * back defensively so one corrupt line cannot cost a month of history.
+ */
+
+import { existsSync, readdirSync, renameSync, rmdirSync } from "node:fs";
+import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { UsageSample } from "../shared/usage.ts";
+
+const DATA_DIRECTORY = "smart-session";
+const LEGACY_DATA_DIRECTORY = "super-session";
+const migratedHomes = new Set<string>();
+
+/**
+ * Move the pre-v0.2 data directory before any new file is opened.
+ *
+ * The two directories are siblings on the same filesystem, so rename is atomic.
+ * An empty destination can be left behind by an eager hook and is safe to remove;
+ * a non-empty destination is never merged because guessing between two histories
+ * would risk duplicating or overwriting the only plan-usage record.
+ */
+export function migrateLegacyData(home: string): void {
+  const parent = join(home, "plugin-data");
+  const legacy = join(parent, LEGACY_DATA_DIRECTORY);
+  const current = join(parent, DATA_DIRECTORY);
+  if (!existsSync(legacy)) return;
+
+  try {
+    if (existsSync(current)) {
+      if (readdirSync(current).length > 0) {
+        console.error(
+          `[smart-session] both ${legacy} and ${current} contain data; leaving both untouched`,
+        );
+        return;
+      }
+      rmdirSync(current);
+    }
+    renameSync(legacy, current);
+    console.log(`[smart-session] migrated plugin data from ${legacy} to ${current}`);
+  } catch (error) {
+    console.error(`[smart-session] could not migrate ${legacy} to ${current}`, String(error));
+  }
+}
+
+export function dataDir(): string {
+  const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+  if (!migratedHomes.has(home)) {
+    migrateLegacyData(home);
+    migratedHomes.add(home);
+  }
+  // A fixed folder name, deliberately decoupled from the install id: a second
+  // install under `--id something-else` must not start a second history.
+  return join(home, "plugin-data", DATA_DIRECTORY);
+}
+
+/** A per-agent context-window reading. */
+export interface ContextSample {
+  readonly at: string;
+  readonly agentId: string;
+  readonly usedTokens: number;
+  readonly maxTokens: number;
+  readonly costUsd: number | null;
+  readonly provider: string;
+  readonly model: string | null;
+  readonly status: string;
+  readonly title: string | null;
+}
+
+type LogKind = "usage" | "context";
+
+/** Monthly files: small enough to read whole, coarse enough to stay few. */
+function logPath(kind: LogKind, at: string): string {
+  return join(dataDir(), `${kind}-${at.slice(0, 7)}.jsonl`);
+}
+
+/**
+ * One writer at a time.
+ *
+ * The poll tick, the file watcher and any RPC handler share one process, and two
+ * concurrent appends can interleave a partial line.
+ */
+let tail: Promise<unknown> = Promise.resolve();
+
+function serialize<T>(work: () => Promise<T>): Promise<T> {
+  const next = tail.then(work, work);
+  // Keep the chain alive even when a caller rejects.
+  tail = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  return next;
+}
+
+async function append(kind: LogKind, at: string, row: unknown): Promise<void> {
+  await serialize(async () => {
+    await mkdir(dataDir(), { recursive: true });
+    await appendFile(logPath(kind, at), `${JSON.stringify(row)}\n`, "utf8");
+  });
+}
+
+export async function appendUsage(sample: UsageSample): Promise<void> {
+  await append("usage", sample.at, sample);
+}
+
+export async function appendContext(sample: ContextSample): Promise<void> {
+  await append("context", sample.at, sample);
+}
+
+/**
+ * Reads a log back.
+ *
+ * A truncated last line (a crash mid-append) or a line from a future schema is
+ * skipped rather than thrown on: partial history beats no history, and this is the
+ * only copy.
+ */
+async function readLog<T>(kind: LogKind, sinceMs: number | null): Promise<T[]> {
+  let names: string[];
+  try {
+    names = (await readdir(dataDir())).filter((name) => name.startsWith(`${kind}-`) && name.endsWith(".jsonl"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      console.error("[smart-session] could not list the data directory", String(error));
+    }
+    return [];
+  }
+  names.sort();
+
+  if (sinceMs !== null) {
+    // Month files are named by their month, so anything older than the month
+    // containing `since` cannot hold a row we want.
+    const floor = `${kind}-${new Date(sinceMs).toISOString().slice(0, 7)}.jsonl`;
+    // eslint-disable-next-line no-param-reassign
+    names = names.filter((name) => name >= floor);
+  }
+
+  const rows: T[] = [];
+  let skipped = 0;
+  for (const name of names) {
+    let raw: string;
+    try {
+      raw = await readFile(join(dataDir(), name), "utf8");
+    } catch (error) {
+      console.error(`[smart-session] could not read ${name}`, String(error));
+      continue;
+    }
+    for (const line of raw.split("\n")) {
+      if (line === "") continue;
+      try {
+        rows.push(JSON.parse(line) as T);
+      } catch {
+        skipped += 1;
+      }
+    }
+  }
+  if (skipped > 0) console.error(`[smart-session] skipped ${skipped} unparseable line(s)`);
+  return rows;
+}
+
+export async function readUsage(options: { sinceMs?: number } = {}): Promise<UsageSample[]> {
+  const since = options.sinceMs ?? null;
+  const rows = await readLog<UsageSample>("usage", since);
+  return since === null ? rows : rows.filter((row) => Date.parse(row.at) >= since);
+}
+
+export async function readContext(options: { sinceMs?: number } = {}): Promise<ContextSample[]> {
+  const since = options.sinceMs ?? null;
+  const rows = await readLog<ContextSample>("context", since);
+  return since === null ? rows : rows.filter((row) => Date.parse(row.at) >= since);
+}
+
+/**
+ * The newest usage reading on record, for the freshness gate.
+ *
+ * Held in memory after the first read: the gate runs on every tick, and re-reading
+ * a month of history sixty times an hour to answer it would be absurd.
+ */
+let newestCache: { value: UsageSample | null } | null = null;
+
+export async function newestUsage(): Promise<UsageSample | null> {
+  if (newestCache !== null) return newestCache.value;
+  const rows = await readUsage({ sinceMs: Date.now() - 45 * 24 * 60 * 60 * 1000 });
+  const newest = rows.length === 0 ? null : rows[rows.length - 1]!;
+  newestCache = { value: newest };
+  return newest;
+}
+
+export function noteNewestUsage(sample: UsageSample): void {
+  newestCache = { value: sample };
+}
+
+/** Drops in-memory state so a reload starts clean. */
+export function clearCaches(): void {
+  newestCache = null;
+}

package/server/upstream.ts

@@ -0,0 +1,117 @@
+/**
+ * Fetching plan usage from Anthropic directly.
+ *
+ * Paseo's own reading is honest but bounded: the daemon serves it from a 5-minute
+ * cache, `forceRefresh` is not reachable over the wire, and nothing refreshes on a
+ * timer — the value only moves when a client happens to ask after the TTL expired.
+ * Claude Code's on-disk cache is worse: it only refreshes when a session refreshes
+ * it, and has been measured 14 hours behind, understating a weekly window by 7
+ * points.
+ *
+ * Since the whole point of this store is a history that is actually true, it asks
+ * upstream itself. Same endpoint, same credentials, same headers Paseo uses — read
+ * only, and no more often than a session would ask on its own.
+ */
+
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const OAUTH_BETA = "oauth-2025-04-20";
+const KEYCHAIN_SERVICE = "Claude Code-credentials";
+const KEYCHAIN_TIMEOUT_MS = 2_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+
+export type UpstreamResult =
+  | { readonly kind: "ok"; readonly body: unknown }
+  | { readonly kind: "needs-auth" }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/**
+ * The OAuth access token, from the file Claude Code writes or from the keychain.
+ *
+ * Read-only in both cases: the Claude CLI owns refreshing this, and a plugin that
+ * tried to would race it. The token is never logged, never stored, and never leaves
+ * this function's return value.
+ */
+async function readAccessToken(): Promise<string | null> {
+  const home = process.env.CLAUDE_HOME ?? join(homedir(), ".claude");
+  try {
+    const raw = JSON.parse(await readFile(join(home, ".credentials.json"), "utf8")) as {
+      claudeAiOauth?: { accessToken?: string };
+    };
+    const token = raw.claudeAiOauth?.accessToken;
+    if (typeof token === "string" && token !== "") return token;
+  } catch {
+    // Expected on machines where the credentials live only in the keychain.
+  }
+
+  if (process.platform !== "darwin") return null;
+
+  // The account name varies by how the CLI stored it, so try the specific lookups
+  // before the bare one.
+  const user = process.env.USER;
+  const accounts = [
+    ...(user !== undefined && /^[a-zA-Z0-9._-]+$/.test(user) ? [user] : []),
+    "claude-code-user",
+  ];
+  const attempts: string[][] = [
+    ...accounts.map((account) => ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account, "-w"]),
+    ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"],
+  ];
+
+  for (const args of attempts) {
+    try {
+      const { stdout } = await execFileAsync("security", args, { timeout: KEYCHAIN_TIMEOUT_MS });
+      const parsed = JSON.parse(stdout.trim()) as { claudeAiOauth?: { accessToken?: string } };
+      const token = parsed.claudeAiOauth?.accessToken;
+      if (typeof token === "string" && token !== "") return token;
+    } catch {
+      // Try the next spelling.
+    }
+  }
+  return null;
+}
+
+/**
+ * One usage reading, straight from the source.
+ *
+ * A 401/403 is reported as `needs-auth` rather than as an error: the credentials
+ * expired, which is a thing the user fixes, not a fault worth retrying against.
+ */
+export async function fetchUpstreamUsage(): Promise<UpstreamResult> {
+  const token = await readAccessToken();
+  if (token === null) return { kind: "unavailable", reason: "no Claude credentials on this machine" };
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  let response: Response;
+  try {
+    response = await fetch(USAGE_URL, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        "anthropic-beta": OAUTH_BETA,
+      },
+      signal: controller.signal,
+    });
+  } catch (error) {
+    return { kind: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  if (response.status === 401 || response.status === 403) return { kind: "needs-auth" };
+  if (!response.ok) return { kind: "unavailable", reason: `usage API returned ${response.status}` };
+
+  try {
+    return { kind: "ok", body: (await response.json()) as unknown };
+  } catch (error) {
+    return { kind: "unavailable", reason: `unreadable usage response: ${String(error)}` };
+  }
+}