opencode-usage-report 0.1.0

package/src/normalize.ts

@@ -0,0 +1,75 @@
+import type { UsageWindow, WindowKind } from "./types.js";
+
+/** Accepts a number or a numeric string; anything else (including NaN/Infinity) yields null. */
+export function toNumber(v: unknown): number | null {
+  if (typeof v === "number") {
+    return Number.isFinite(v) ? v : null;
+  }
+  if (typeof v === "string") {
+    const trimmed = v.trim();
+    if (trimmed === "") return null;
+    const n = Number(trimmed);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+/**
+ * Accepts an ISO date string, epoch seconds (< 1e12) or epoch milliseconds (>= 1e12).
+ * Returns a normalized ISO-8601 string, or null when the value cannot be parsed.
+ */
+export function toISODate(v: unknown): string | null {
+  if (v === null || v === undefined) return null;
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) return null;
+    const ms = v < 1e12 ? v * 1000 : v;
+    const d = new Date(ms);
+    return Number.isNaN(d.getTime()) ? null : d.toISOString();
+  }
+  if (typeof v === "string") {
+    if (v.trim() === "") return null;
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d.toISOString();
+  }
+  return null;
+}
+
+/** Returns the first non-null/undefined value of obj[keys]; non-plain-object input yields undefined. */
+export function pick(obj: unknown, ...keys: string[]): unknown {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) return undefined;
+  const record = obj as Record<string, unknown>;
+  for (const key of keys) {
+    const value = record[key];
+    if (value !== null && value !== undefined) return value;
+  }
+  return undefined;
+}
+
+/** Converts a 0-1 ratio into a 0-100 percent, clamped to [0,100] and rounded to 1 decimal. */
+export function ratioToPercent(ratio: number): number {
+  const rounded = Math.round(ratio * 1000) / 10;
+  return Math.min(100, Math.max(0, rounded));
+}
+
+/** Builds a window from tolerant count fields, deriving usedPercent only when used and a positive limit are known. */
+export function windowFromCounts(
+  kind: WindowKind,
+  label: string,
+  detail: { limit?: unknown; used?: unknown; remaining?: unknown; reset?: unknown },
+): UsageWindow {
+  const used = toNumber(detail.used);
+  const limit = toNumber(detail.limit);
+  const remaining = toNumber(detail.remaining);
+  const usedPercent =
+    used !== null && limit !== null && limit > 0 ? Math.round((used / limit) * 100) : null;
+  return {
+    kind,
+    label,
+    usedPercent,
+    used,
+    limit,
+    remaining,
+    resetsAt: toISODate(detail.reset),
+    status: "ok",
+  };
+}

package/src/paths.ts

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Resolves the opencode data home: $OPENCODE_DATA_HOME if set, else ~/.local/share/opencode. */
+export function dataHome(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.OPENCODE_DATA_HOME;
+  if (typeof override === "string" && override.trim() !== "") return override;
+  return join(homedir(), ".local", "share", "opencode");
+}
+
+/** <data-home>/usage-report */
+export function pluginStateDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(dataHome(env), "usage-report");
+}
+
+/** <data-home>/opencode.db */
+export function dbPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(dataHome(env), "opencode.db");
+}

package/src/providers/index.ts

@@ -0,0 +1,5 @@
+import type { ProviderAdapter } from "../types.js";
+import { kimiAdapter } from "./kimi.js";
+import { opencodeGoAdapter } from "./opencode-go.js";
+export const adapters: ProviderAdapter[] = [kimiAdapter, opencodeGoAdapter];
+export function getAdapter(id: string): ProviderAdapter | undefined { return adapters.find(a => a.id === id); }

package/src/providers/kimi.ts

@@ -0,0 +1,198 @@
+import type {
+  AdapterResult,
+  Credential,
+  FetchOptions,
+  ProviderAdapter,
+  UsageWindow,
+} from "../types.js";
+import { AdapterError } from "../types.js";
+import { pick, ratioToPercent, toISODate, toNumber, windowFromCounts } from "../normalize.js";
+import { redact } from "../auth.js";
+
+const VERSION = "0.1.0";
+const ENDPOINT = "https://api.kimi.com/coding/v1/usages";
+
+function request(cred: Credential, opts: FetchOptions): Promise<Response> {
+  return fetch(ENDPOINT, {
+    method: "GET",
+    headers: {
+      Authorization: "Bearer " + cred.key,
+      Accept: "application/json",
+      "User-Agent": "opencode-usage-report/" + VERSION,
+    },
+    signal: AbortSignal.timeout(opts.timeoutMs),
+  });
+}
+
+/** One retry on network throw or 5xx; 4xx and 2xx return immediately. */
+async function fetchWithRetry(cred: Credential, opts: FetchOptions): Promise<Response> {
+  let lastError: unknown = null;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const res = await request(cred, opts);
+      if (res.status >= 500) {
+        lastError = new Error(`HTTP ${res.status}`);
+        continue;
+      }
+      return res;
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  const detail = lastError instanceof Error ? lastError.message : String(lastError);
+  throw new AdapterError("network", redact(`Kimi API network error: ${detail}`, cred.key));
+}
+
+function findLimitDetail(limits: unknown, durationMinutes: number): unknown {
+  if (!Array.isArray(limits)) return undefined;
+  for (const entry of limits) {
+    const window = pick(entry, "window");
+    const duration = toNumber(pick(window, "duration"));
+    const unit = pick(window, "timeUnit", "time_unit");
+    if (duration === durationMinutes && unit === "TIME_UNIT_MINUTE") {
+      return pick(entry, "detail");
+    }
+  }
+  return undefined;
+}
+
+function ratioWindow(
+  kind: UsageWindow["kind"],
+  label: string,
+  value: unknown,
+): UsageWindow {
+  const ratio = toNumber(pick(value, "used_ratio", "usedRatio"));
+  return {
+    kind,
+    label,
+    usedPercent: ratio !== null ? ratioToPercent(ratio) : null,
+    used: null,
+    limit: null,
+    remaining: null,
+    resetsAt: toISODate(pick(value, "reset_time", "resetTime", "resetAt", "resetsAt")),
+    status: "ok",
+  };
+}
+
+function detailWindow(kind: UsageWindow["kind"], label: string, detail: unknown): UsageWindow {
+  return windowFromCounts(kind, label, {
+    limit: pick(detail, "limit"),
+    used: pick(detail, "used"),
+    remaining: pick(detail, "remaining"),
+    reset: pick(detail, "resetTime", "reset_time", "resetAt", "resetsAt"),
+  });
+}
+
+function parse(body: Record<string, unknown>, cred: Credential): AdapterResult {
+  const windows: UsageWindow[] = [];
+  const extras: Record<string, string> = {};
+
+  const usages = pick(body, "usages");
+  const usage = pick(body, "usage");
+  const limits = pick(body, "limits");
+
+  // Count-based windows are authoritative; the `usages.limit_5h/limit_7d`
+  // ratios are legacy fields the live API returns as stale zeros even while
+  // real usage accrues, so they are only a fallback when counts are missing.
+  const detail5h = findLimitDetail(limits, 300);
+  if (detail5h !== undefined) {
+    windows.push(detailWindow("5h", "5-hour", detail5h));
+  } else {
+    const limit5h = pick(usages, "limit_5h");
+    if (limit5h !== undefined) windows.push(ratioWindow("5h", "5-hour", limit5h));
+  }
+
+  if (usage !== undefined) {
+    windows.push(detailWindow("weekly", "Weekly", usage));
+  } else {
+    const limit7d = pick(usages, "limit_7d");
+    if (limit7d !== undefined) windows.push(ratioWindow("weekly", "Weekly", limit7d));
+  }
+
+  const level = pick(pick(body, "user"), "membership");
+  const membershipLevel = pick(level, "level");
+  if (membershipLevel !== undefined) extras["Plan"] = String(membershipLevel);
+
+  const wallet = pick(body, "booster_wallet");
+
+  // `balance` is a wallet descriptor object on the live API; only render scalar values.
+  const balance = pick(wallet, "balance");
+  if (typeof balance === "string" || typeof balance === "number") {
+    extras["Booster wallet"] = String(balance);
+  }
+
+  const monthlyUsed = pick(wallet, "monthlyUsed", "monthly_used");
+  const currency = pick(monthlyUsed, "currency");
+  const priceInCents = toNumber(pick(monthlyUsed, "priceInCents", "price_in_cents"));
+  if (
+    (typeof currency === "string" || typeof currency === "number") &&
+    String(currency) !== "" &&
+    priceInCents !== null
+  ) {
+    extras["Booster used this month"] = `$${(priceInCents / 100).toFixed(2)} ${String(currency)}`;
+  }
+
+  const totalQuota = pick(body, "totalQuota", "total_quota");
+  const quotaUsed = toNumber(pick(totalQuota, "used"));
+  if (totalQuota !== undefined && quotaUsed !== null && quotaUsed > 0) {
+    windows.push({
+      kind: "monthly",
+      label: "Monthly",
+      usedPercent: null,
+      used: quotaUsed,
+      limit: toNumber(pick(totalQuota, "limit")),
+      remaining: toNumber(pick(totalQuota, "remaining")),
+      resetsAt: toISODate(pick(totalQuota, "resetTime", "reset_time", "resetAt", "resetsAt")),
+      status: "frozen",
+    });
+  }
+
+  if (windows.length === 0) {
+    throw new AdapterError(
+      "bad-response",
+      redact("Kimi API response contained no usage windows", cred.key),
+    );
+  }
+
+  return { windows, extras };
+}
+
+export const kimiAdapter: ProviderAdapter = {
+  id: "kimi-for-coding",
+  displayName: "Kimi Code",
+  async fetch(cred: Credential, opts: FetchOptions): Promise<AdapterResult> {
+    const res = await fetchWithRetry(cred, opts);
+
+    if (res.status === 401) {
+      throw new AdapterError("auth", redact("invalid Kimi API key", cred.key));
+    }
+    if (res.status === 429) {
+      throw new AdapterError("rate-limited", redact("Kimi API rate limit exceeded", cred.key));
+    }
+    if (res.status < 200 || res.status >= 300) {
+      throw new AdapterError(
+        "bad-response",
+        redact(`Kimi API returned HTTP ${res.status}`, cred.key),
+      );
+    }
+
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      throw new AdapterError(
+        "bad-response",
+        redact("Kimi API returned a non-JSON response", cred.key),
+      );
+    }
+
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+      throw new AdapterError(
+        "bad-response",
+        redact("Kimi API returned an unexpected response shape", cred.key),
+      );
+    }
+
+    return parse(body as Record<string, unknown>, cred);
+  },
+};

package/src/providers/opencode-go.ts

@@ -0,0 +1,153 @@
+import type {
+  AdapterResult,
+  Credential,
+  FetchOptions,
+  ProviderAdapter,
+  UsageWindow,
+  WindowKind,
+  WindowStatus,
+} from "../types.js";
+import { AdapterError } from "../types.js";
+import { toISODate, toNumber } from "../normalize.js";
+import { redact } from "../auth.js";
+
+const VERSION = "0.1.0";
+const USER_AGENT = "opencode-usage-report/" + VERSION;
+const ENDPOINT = "https://opencode.ai/zen/go/v1/usage";
+
+/** Additive options: `sessionId` is optional, so the adapter still satisfies `ProviderAdapter`. */
+export type OpenCodeGoFetchOptions = FetchOptions & { sessionId?: string };
+
+const WINDOWS: Array<{ key: string; kind: WindowKind; label: string }> = [
+  { key: "rolling", kind: "5h", label: "5-hour" },
+  { key: "weekly", kind: "weekly", label: "Weekly" },
+  { key: "monthly", kind: "monthly", label: "Monthly" },
+];
+
+function mapStatus(v: unknown): WindowStatus {
+  return v === "ok" || v === "rate-limited" ? v : "unknown";
+}
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+  return v !== null && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : null;
+}
+
+function buildWindow(kind: WindowKind, label: string, src: unknown): UsageWindow | null {
+  const record = asRecord(src);
+  if (!record) return null;
+  return {
+    kind,
+    label,
+    usedPercent: toNumber(record.percent),
+    used: null,
+    limit: null,
+    remaining: null,
+    resetsAt: toISODate(record.resetsAt),
+    status: mapStatus(record.status),
+  };
+}
+
+/** Reads the body once as text and best-effort parses JSON, so error and success paths share it. */
+async function readBody(res: Response): Promise<{ text: string; json: unknown }> {
+  const text = await res.text().catch(() => "");
+  let json: unknown = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    json = null;
+  }
+  return { text, json };
+}
+
+async function attempt(cred: Credential, opts: OpenCodeGoFetchOptions): Promise<Response> {
+  return fetch(ENDPOINT, {
+    method: "GET",
+    headers: {
+      Authorization: "Bearer " + cred.key,
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+      "x-opencode-session": opts.sessionId ?? "unknown",
+    },
+    signal: AbortSignal.timeout(opts.timeoutMs),
+  });
+}
+
+/** Exactly one retry on a network throw or 5xx; 4xx is returned immediately (never retried). */
+async function request(cred: Credential, opts: OpenCodeGoFetchOptions): Promise<Response> {
+  try {
+    const first = await attempt(cred, opts);
+    if (first.status < 500) return first;
+  } catch {
+    // fall through to the single retry
+  }
+
+  try {
+    return await attempt(cred, opts);
+  } catch (err) {
+    throw new AdapterError(
+      "network",
+      redact(
+        `OpenCode Go request failed: ${err instanceof Error ? err.message : String(err)}`,
+        cred.key,
+      ),
+    );
+  }
+}
+
+async function handleError(res: Response, cred: Credential): Promise<never> {
+  const { text, json } = await readBody(res);
+
+  if (res.status === 401) {
+    throw new AdapterError("auth", redact("invalid OpenCode Go API key", cred.key));
+  }
+  if (res.status === 403) {
+    const record = asRecord(json);
+    const error = record ? asRecord(record.error) : null;
+    if (error && error.type === "EntitlementError") {
+      throw new AdapterError(
+        "no-plan",
+        redact("OpenCode Go subscription not active on this key", cred.key),
+      );
+    }
+    throw new AdapterError(
+      "network",
+      redact("OpenCode Go request blocked (check User-Agent)", cred.key),
+    );
+  }
+  if (res.status === 429) {
+    throw new AdapterError("rate-limited", redact("OpenCode Go rate limit reached", cred.key));
+  }
+  if (res.status >= 500) {
+    throw new AdapterError("network", redact(`OpenCode Go server error ${res.status}`, cred.key));
+  }
+  throw new AdapterError(
+    "bad-response",
+    redact(`OpenCode Go unexpected status ${res.status}: ${text.slice(0, 200)}`, cred.key),
+  );
+}
+
+export const opencodeGoAdapter: ProviderAdapter = {
+  id: "opencode-go",
+  displayName: "OpenCode Go",
+  async fetch(cred: Credential, opts: OpenCodeGoFetchOptions): Promise<AdapterResult> {
+    const res = await request(cred, opts);
+    if (!res.ok) return handleError(res, cred);
+
+    const { json } = await readBody(res);
+    const body = asRecord(json);
+    const usage = body ? asRecord(body.usage) : null;
+    if (!usage) {
+      throw new AdapterError("bad-response", redact("OpenCode Go response missing usage", cred.key));
+    }
+
+    const windows: UsageWindow[] = [];
+    for (const { key, kind, label } of WINDOWS) {
+      const window = buildWindow(kind, label, usage[key]);
+      if (window) windows.push(window);
+    }
+
+    return { windows };
+  },
+};

package/src/render.ts

@@ -0,0 +1,85 @@
+import type { ProviderReport, UsageWindow } from "./types.js";
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const LABEL_WIDTH = 8;
+const PERCENT_WIDTH = 10;
+const ABSOLUTES_WIDTH = 24;
+
+function formatNumber(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
+/** "14:05" for a same-day reset, "Wed Sep 16" otherwise. */
+export function formatReset(resetsAt: string, now: Date): string | null {
+  const d = new Date(resetsAt);
+  if (Number.isNaN(d.getTime())) return null;
+  const within24h = Math.abs(d.getTime() - now.getTime()) < DAY_MS;
+  if (within24h) {
+    return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+  }
+  return `${WEEKDAYS[d.getDay()]} ${MONTHS[d.getMonth()]} ${d.getDate()}`;
+}
+
+function formatAge(fetchedAt: string, now: Date): string {
+  const then = new Date(fetchedAt).getTime();
+  const minutes = Number.isNaN(then) ? 0 : Math.max(0, Math.floor((now.getTime() - then) / 60000));
+  if (minutes < 60) return `${minutes}m`;
+  return `${Math.floor(minutes / 60)}h`;
+}
+
+function header(report: ProviderReport, now: Date): string {
+  const parts: string[] = [report.source];
+  if (report.stale) {
+    parts.push(`stale ${formatAge(report.fetchedAt, now)} old`);
+  }
+  return `${report.displayName} (${parts.join(", ")})`;
+}
+
+function windowLine(report: ProviderReport, w: UsageWindow, now: Date): string {
+  // Local estimates always carry the `~` marker, even when only absolutes are
+  // known (percent is null): a bare em dash would hide that the row is estimated.
+  const isEstimate = report.source === "local-estimate";
+  const percent =
+    w.usedPercent !== null
+      ? `${isEstimate ? "~" : ""}${w.usedPercent}%`
+      : isEstimate
+        ? "~estimate"
+        : "—";
+  let line = `  ${w.label.padEnd(LABEL_WIDTH)}${percent.padEnd(PERCENT_WIDTH)}`;
+
+  if (w.used !== null && w.limit !== null) {
+    line += `${formatNumber(w.used)} / ${formatNumber(w.limit)} reqs`.padEnd(ABSOLUTES_WIDTH);
+  }
+  if (w.resetsAt !== null) {
+    const reset = formatReset(w.resetsAt, now);
+    if (reset !== null) line += `resets ${reset}`;
+  }
+  return line.trimEnd();
+}
+
+/** Renders provider reports as a human-readable text table (spec §3.8). */
+export function renderText(reports: ProviderReport[], opts?: { now?: Date }): string {
+  const now = opts?.now ?? new Date();
+  const blocks = reports.map((report) => {
+    if (report.source === "error") {
+      return `⚠ ${report.displayName}: ${report.error ?? "unknown error"}`;
+    }
+    const lines = [header(report, now)];
+    for (const w of report.windows) {
+      lines.push(windowLine(report, w, now));
+    }
+    for (const [key, value] of Object.entries(report.extras)) {
+      lines.push(`  ${key}: ${value}`);
+    }
+    return lines.join("\n");
+  });
+  return blocks.join("\n\n");
+}
+
+/** Renders provider reports as pretty-printed JSON. */
+export function renderJson(reports: ProviderReport[]): string {
+  return JSON.stringify(reports, null, 2);
+}

package/src/report.ts

@@ -0,0 +1,161 @@
+import type { PluginOptions, ProviderAdapter, ProviderReport } from "./types.js";
+import { adapters, getAdapter } from "./providers/index.js";
+import { redact, resolveCredential } from "./auth.js";
+import { ensureSessionId, readCache, writeCache } from "./cache.js";
+import type { CacheEntry } from "./cache.js";
+import { localEstimate } from "./fallback.js";
+
+export const DEFAULT_OPTIONS: PluginOptions = {
+  thresholdPercent: 80,
+  cacheTtlSeconds: 120,
+  providers: null,
+  fallback: true,
+};
+
+const FETCH_TIMEOUT_MS = 5000;
+
+export interface CollectReportsOptions {
+  providers?: string[];
+  refresh?: boolean;
+  options?: Partial<PluginOptions>;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Normalizes a provider filter: null/undefined/empty all mean "all providers". */
+function firstNonEmpty(list: string[] | null | undefined): string[] | null {
+  return Array.isArray(list) && list.length > 0 ? list : null;
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function errorReport(provider: string, displayName: string, error: string): ProviderReport {
+  return {
+    provider,
+    displayName,
+    fetchedAt: nowIso(),
+    source: "error",
+    stale: false,
+    windows: [],
+    extras: {},
+    error,
+  };
+}
+
+function cacheReport(
+  provider: string,
+  displayName: string,
+  entry: CacheEntry,
+  stale: boolean,
+  error: string | null,
+): ProviderReport {
+  return {
+    provider,
+    displayName,
+    fetchedAt: entry.fetchedAt,
+    source: "cache",
+    stale,
+    windows: entry.result.windows,
+    extras: entry.result.extras ?? {},
+    error,
+  };
+}
+
+/** Collects one provider: credential -> fresh cache -> live fetch -> stale cache -> local estimate. */
+async function collectOne(
+  id: string,
+  adapter: ProviderAdapter,
+  options: PluginOptions,
+  refresh: boolean,
+  env: NodeJS.ProcessEnv,
+): Promise<ProviderReport> {
+  const cred = resolveCredential(id, { env });
+  if (cred === null) return errorReport(id, adapter.displayName, "no credential found");
+
+  if (!refresh) {
+    const cached = await readCache(id, options.cacheTtlSeconds, env);
+    if (cached !== null && cached.fresh) {
+      return cacheReport(id, adapter.displayName, cached.entry, false, null);
+    }
+  }
+
+  let failure: string;
+  try {
+    const sessionId = await ensureSessionId(env);
+    const fetchOptions = { timeoutMs: FETCH_TIMEOUT_MS, sessionId };
+    const result = await adapter.fetch(cred, fetchOptions);
+    await writeCache(id, result, env);
+    return {
+      provider: id,
+      displayName: adapter.displayName,
+      fetchedAt: nowIso(),
+      source: "api",
+      stale: false,
+      windows: result.windows,
+      extras: result.extras ?? {},
+      error: null,
+    };
+  } catch (err) {
+    failure = redact(err instanceof Error ? err.message : String(err), cred.key);
+  }
+
+  const cached = await readCache(id, options.cacheTtlSeconds, env);
+  if (cached !== null) {
+    return cacheReport(id, adapter.displayName, cached.entry, true, failure);
+  }
+
+  if (options.fallback) {
+    const estimate = await localEstimate(id, env);
+    if (estimate !== null) {
+      return {
+        provider: id,
+        displayName: adapter.displayName,
+        fetchedAt: nowIso(),
+        source: "local-estimate",
+        stale: true,
+        windows: estimate.windows,
+        extras: estimate.extras ?? {},
+        error: failure,
+      };
+    }
+  }
+
+  return errorReport(id, adapter.displayName, failure);
+}
+
+/**
+ * Collects normalized usage reports for the requested providers (default: every
+ * registered adapter). Never throws: each provider is isolated and failures
+ * surface as `source: "error"` rows.
+ */
+export async function collectReports(opts: CollectReportsOptions = {}): Promise<ProviderReport[]> {
+  const options: PluginOptions = { ...DEFAULT_OPTIONS, ...(opts.options ?? {}) };
+  const env = opts.env ?? process.env;
+  const refresh = opts.refresh === true;
+
+  // An empty filter is treated like "no filter": report every registered adapter.
+  const ids =
+    firstNonEmpty(opts.providers) ??
+    firstNonEmpty(options.providers) ??
+    adapters.map((adapter) => adapter.id);
+  const reports: ProviderReport[] = [];
+
+  for (const id of ids) {
+    const adapter = getAdapter(id);
+    if (adapter === undefined) {
+      const known = adapters.map((entry) => entry.id).join(", ");
+      reports.push(errorReport(id, id, `unknown provider '${id}' (known: ${known})`));
+      continue;
+    }
+
+    try {
+      reports.push(await collectOne(id, adapter, options, refresh, env));
+    } catch {
+      // Last-resort isolation: never let one provider break the whole report.
+      reports.push(errorReport(id, adapter.displayName, "internal error while collecting usage"));
+    }
+  }
+
+  return reports;
+}