@scrylog/cli 0.1.4 → 0.3.0

package/src/usage/clients/codex-app-server.ts

@@ -0,0 +1,354 @@
+import { spawn } from "node:child_process";
+import { whichCommand } from "../../shared/platform";
+import { UsageError } from "../errors";
+import type { CodexOAuthCredentials, CodexUsageSnapshot, RateWindowLegacy } from "../types";
+
+export interface CodexAppServerProcess {
+  write(line: string): void;
+  closeStdin(): void;
+  onStdout(listener: (chunk: Uint8Array) => void): void;
+  onStderr(listener: (chunk: Uint8Array) => void): void;
+  onExit(listener: (code: number | null) => void): void;
+  onError(listener: (error: Error) => void): void;
+  kill(signal: "SIGTERM" | "SIGKILL"): void;
+}
+
+export type CodexAppServerTransport = (
+  executable: string,
+  args: string[],
+) => CodexAppServerProcess;
+
+export interface CodexAppServerOptions {
+  timeoutMs?: number;
+  killGraceMs?: number;
+  maxLineBytes?: number;
+  maxOutputBytes?: number;
+  resolveExecutable?: () => string | null;
+  transport?: CodexAppServerTransport;
+}
+
+const defaultTransport: CodexAppServerTransport = (executable, args) => {
+  const child = spawn(executable, args, {
+    env: process.env,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  return {
+    write: (line) => child.stdin.write(line),
+    closeStdin: () => child.stdin.end(),
+    onStdout: (listener) => child.stdout.on("data", listener),
+    onStderr: (listener) => child.stderr.on("data", listener),
+    onExit: (listener) => child.on("close", listener),
+    onError: (listener) => child.on("error", listener),
+    kill: (signal) => { child.kill(signal); },
+  };
+};
+
+const INITIALIZE_ID = 1;
+const RATE_LIMITS_ID = 2;
+
+export class CodexAppServerClient {
+  private readonly timeoutMs: number;
+  private readonly killGraceMs: number;
+  private readonly maxLineBytes: number;
+  private readonly maxOutputBytes: number;
+  private readonly resolveExecutable: () => string | null;
+  private readonly transport: CodexAppServerTransport;
+  private readonly inFlight = new Map<string, Promise<CodexUsageSnapshot>>();
+
+  constructor(options: CodexAppServerOptions = {}) {
+    this.timeoutMs = options.timeoutMs ?? 10_000;
+    this.killGraceMs = options.killGraceMs ?? 250;
+    this.maxLineBytes = options.maxLineBytes ?? 256 * 1_024;
+    this.maxOutputBytes = options.maxOutputBytes ?? 1_024 * 1_024;
+    this.resolveExecutable = options.resolveExecutable ?? (() => whichCommand("codex"));
+    this.transport = options.transport ?? defaultTransport;
+  }
+
+  async fetch(
+    identity?: Pick<CodexOAuthCredentials, "accountEmail" | "accountId">,
+    options?: { signal?: AbortSignal },
+  ): Promise<CodexUsageSnapshot> {
+    const key = identity?.accountId ?? identity?.accountEmail ?? "default";
+    const existing = this.inFlight.get(key);
+    if (existing) return this.waitForShared(existing, options?.signal);
+
+    const attempt = this.fetchOnce(identity, options).finally(() => this.inFlight.delete(key));
+    this.inFlight.set(key, attempt);
+    return attempt;
+  }
+
+  private async fetchOnce(
+    identity?: Pick<CodexOAuthCredentials, "accountEmail" | "accountId">,
+    options?: { signal?: AbortSignal },
+  ): Promise<CodexUsageSnapshot> {
+    if (options?.signal?.aborted) {
+      throw new UsageError("cancelled", "Codex app-server request cancelled");
+    }
+
+    const executable = this.resolveExecutable();
+    if (!executable) {
+      throw new UsageError("transient", "Codex CLI executable was not found");
+    }
+
+    let processHandle: CodexAppServerProcess;
+    try {
+      processHandle = this.transport(executable, ["-s", "read-only", "-a", "never", "app-server"]);
+    } catch (error) {
+      throw new UsageError(
+        "transient",
+        `Codex app-server failed to start: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    return new Promise<CodexUsageSnapshot>((resolve, reject) => {
+      let buffer = "";
+      let outputBytes = 0;
+      let cleaningUp = false;
+      let completed = false;
+      let result: CodexUsageSnapshot | undefined;
+      let failure: UsageError | undefined;
+
+      const complete = () => {
+        if (completed) return;
+        completed = true;
+        clearTimeout(deadline);
+        clearTimeout(killTimer);
+        options?.signal?.removeEventListener("abort", onAbort);
+        if (failure) reject(failure);
+        else resolve(result!);
+      };
+
+      let killTimer: ReturnType<typeof setTimeout> | undefined;
+      const settle = (nextResult?: CodexUsageSnapshot, nextFailure?: UsageError) => {
+        if (cleaningUp || completed) return;
+        cleaningUp = true;
+        result = nextResult;
+        failure = nextFailure;
+        try { processHandle.closeStdin(); } catch {}
+        try { processHandle.kill("SIGTERM"); } catch {}
+        killTimer = setTimeout(() => {
+          try { processHandle.kill("SIGKILL"); } catch {}
+          complete();
+        }, this.killGraceMs);
+      };
+
+      const onAbort = () => settle(undefined, new UsageError("cancelled", "Codex app-server request cancelled"));
+      const deadline = setTimeout(
+        () => settle(undefined, new UsageError("transient", `Codex app-server timed out after ${this.timeoutMs}ms`)),
+        this.timeoutMs,
+      );
+
+      const send = (message: Record<string, unknown>) => {
+        processHandle.write(`${JSON.stringify(message)}\n`);
+      };
+
+      const handleLine = (line: string) => {
+        if (!line.trim() || cleaningUp) return;
+        let message: Record<string, unknown>;
+        try {
+          message = JSON.parse(line) as Record<string, unknown>;
+        } catch {
+          settle(undefined, new UsageError("invalid-response", "Codex app-server emitted invalid JSON"));
+          return;
+        }
+
+        if (message["id"] === INITIALIZE_ID) {
+          if (message["error"] !== undefined) {
+            settle(undefined, new UsageError("invalid-response", "Codex app-server initialization failed"));
+            return;
+          }
+          send({ jsonrpc: "2.0", method: "initialized", params: {} });
+          send({ jsonrpc: "2.0", id: RATE_LIMITS_ID, method: "account/rateLimits/read", params: {} });
+          return;
+        }
+
+        if (message["id"] === RATE_LIMITS_ID) {
+          if (message["error"] !== undefined) {
+            settle(undefined, new UsageError("invalid-response", "Codex app-server rate-limit request failed"));
+            return;
+          }
+          try {
+            settle(parseRateLimits(message["result"], identity));
+          } catch (error) {
+            settle(undefined, error instanceof UsageError ? error : new UsageError("invalid-response", "Codex app-server returned invalid rate limits"));
+          }
+        }
+      };
+
+      processHandle.onStdout((chunk) => {
+        if (cleaningUp) return;
+        outputBytes += chunk.byteLength;
+        if (outputBytes > this.maxOutputBytes) {
+          settle(undefined, new UsageError("invalid-response", "Codex app-server output exceeded the configured limit"));
+          return;
+        }
+        buffer += Buffer.from(chunk).toString("utf8");
+        let newline = buffer.indexOf("\n");
+        while (newline >= 0) {
+          const line = buffer.slice(0, newline).replace(/\r$/, "");
+          buffer = buffer.slice(newline + 1);
+          if (Buffer.byteLength(line) > this.maxLineBytes) {
+            settle(undefined, new UsageError("invalid-response", "Codex app-server line exceeded the configured limit"));
+            return;
+          }
+          handleLine(line);
+          newline = buffer.indexOf("\n");
+        }
+        if (Buffer.byteLength(buffer) > this.maxLineBytes) {
+          settle(undefined, new UsageError("invalid-response", "Codex app-server line exceeded the configured limit"));
+        }
+      });
+      processHandle.onStderr((chunk) => {
+        if (cleaningUp) return;
+        outputBytes += chunk.byteLength;
+        if (outputBytes > this.maxOutputBytes) {
+          settle(undefined, new UsageError("invalid-response", "Codex app-server output exceeded the configured limit"));
+        }
+      });
+      processHandle.onError((error) => {
+        settle(undefined, new UsageError("transient", `Codex app-server failed to start: ${error.message}`));
+      });
+      processHandle.onExit((code) => {
+        if (cleaningUp) complete();
+        else settle(undefined, new UsageError("transient", `Codex app-server exited before responding${code === null ? "" : ` (${code})`}`));
+      });
+      options?.signal?.addEventListener("abort", onAbort, { once: true });
+
+      send({
+        jsonrpc: "2.0",
+        id: INITIALIZE_ID,
+        method: "initialize",
+        params: {
+          clientInfo: { name: "scrylog", version: "0.1.0" },
+          capabilities: {},
+        },
+      });
+    });
+  }
+
+  private waitForShared(promise: Promise<CodexUsageSnapshot>, signal?: AbortSignal): Promise<CodexUsageSnapshot> {
+    if (!signal) return promise;
+    if (signal.aborted) return Promise.reject(new UsageError("cancelled", "Codex app-server request cancelled"));
+    return new Promise((resolve, reject) => {
+      const abort = () => reject(new UsageError("cancelled", "Codex app-server request cancelled"));
+      signal.addEventListener("abort", abort, { once: true });
+      promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+  }
+}
+
+function parseRateLimits(
+  raw: unknown,
+  identity?: Pick<CodexOAuthCredentials, "accountEmail" | "accountId">,
+): CodexUsageSnapshot {
+  if (!isRecord(raw)) throw new UsageError("invalid-response", "Codex app-server response is missing a result");
+  const limits = pickRecord(raw, "rateLimits", "rate_limits");
+  if (!limits) throw new UsageError("invalid-response", "Codex app-server response is missing rate limits");
+
+  const primaryWindow = parseWindow(pickRecord(limits, "primary", "primaryWindow", "primary_window"));
+  const secondaryWindow = parseWindow(pickRecord(limits, "secondary", "secondaryWindow", "secondary_window"));
+  const creditsRaw = pickRecord(limits, "credits");
+  const creditBalance = creditsRaw
+    ? pickNumber(creditsRaw, "balance") ?? pickNumericString(creditsRaw, "balance")
+    : undefined;
+  const individualLimit = parseIndividualLimit(pickRecord(limits, "individualLimit", "individual_limit"));
+
+  return {
+    source: "cli",
+    planType: pickString(limits, "planType", "plan_type") ?? null,
+    primaryWindow,
+    secondaryWindow,
+    credits: creditsRaw ? {
+      hasCredits: pickBoolean(creditsRaw, "hasCredits", "has_credits") ?? false,
+      unlimited: pickBoolean(creditsRaw, "unlimited") ?? false,
+      balance: creditBalance !== undefined && creditBalance >= 0 ? creditBalance : null,
+    } : null,
+    individualLimit,
+    spendControlPresent: individualLimit !== null,
+    updatedAt: new Date(),
+    accountEmail: pickString(raw, "accountEmail", "account_email") ?? identity?.accountEmail ?? null,
+    accountId: pickString(raw, "accountId", "account_id") ?? identity?.accountId ?? null,
+  };
+}
+
+function parseIndividualLimit(
+  raw: Record<string, unknown> | undefined,
+): NonNullable<CodexUsageSnapshot["individualLimit"]> | null {
+  if (!raw) return null;
+  const used = pickNumber(raw, "used") ?? pickNumericString(raw, "used");
+  const limit = pickNumber(raw, "limit") ?? pickNumericString(raw, "limit");
+  if (used === undefined || limit === undefined || limit <= 0) return null;
+  const resetValue = raw["resetsAt"] ?? raw["resets_at"];
+  const resetsAt = typeof resetValue === "number"
+    ? new Date(resetValue * 1_000)
+    : typeof resetValue === "string" && /^\d+(?:\.\d+)?$/.test(resetValue.trim())
+      ? new Date(Number(resetValue) * 1_000)
+      : typeof resetValue === "string"
+        ? new Date(resetValue)
+        : null;
+  return {
+    used: Math.max(0, used),
+    limit,
+    resetsAt: resetsAt && !Number.isNaN(resetsAt.getTime()) ? resetsAt : null,
+  };
+}
+
+function parseWindow(raw: Record<string, unknown> | undefined): RateWindowLegacy | null {
+  if (!raw) return null;
+  const usedPercent = pickNumber(raw, "usedPercent", "used_percent");
+  if (usedPercent === undefined) return null;
+  const windowMinutes = pickNumber(raw, "windowDurationMins", "windowMinutes", "window_minutes") ?? 300;
+  const resetValue = raw["resetsAt"] ?? raw["resets_at"];
+  const resetsAt = typeof resetValue === "number"
+    ? new Date(resetValue * 1_000)
+    : typeof resetValue === "string"
+      ? new Date(resetValue)
+      : null;
+  const validReset = resetsAt && !Number.isNaN(resetsAt.getTime()) ? resetsAt : null;
+  return {
+    usedPercent: Math.max(0, Math.min(100, usedPercent)),
+    windowMinutes,
+    resetsAt: validReset,
+    resetDescription: validReset ? formatDuration(Math.max(0, validReset.getTime() - Date.now())) : null,
+  };
+}
+
+function formatDuration(ms: number): string {
+  const minutes = Math.floor(ms / 60_000);
+  const hours = Math.floor(minutes / 60);
+  return hours > 0 ? `${hours}h ${minutes % 60}m` : `${minutes}m`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pickRecord(raw: Record<string, unknown>, ...keys: string[]): Record<string, unknown> | undefined {
+  for (const key of keys) if (isRecord(raw[key])) return raw[key];
+  return undefined;
+}
+
+function pickString(raw: Record<string, unknown>, ...keys: string[]): string | undefined {
+  for (const key of keys) if (typeof raw[key] === "string") return raw[key];
+  return undefined;
+}
+
+function pickNumber(raw: Record<string, unknown>, ...keys: string[]): number | undefined {
+  for (const key of keys) if (typeof raw[key] === "number" && Number.isFinite(raw[key])) return raw[key];
+  return undefined;
+}
+
+function pickNumericString(raw: Record<string, unknown>, ...keys: string[]): number | undefined {
+  for (const key of keys) {
+    if (typeof raw[key] !== "string") continue;
+    const value = Number(raw[key]);
+    if (Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+function pickBoolean(raw: Record<string, unknown>, ...keys: string[]): boolean | undefined {
+  for (const key of keys) if (typeof raw[key] === "boolean") return raw[key];
+  return undefined;
+}

package/src/usage/clients/codex-oauth-usage.ts

@@ -1,20 +1,31 @@
 import type { UsageClient } from "../client";
 import type { CodexOAuthCredentials, CodexUsageSnapshot, RateWindowLegacy } from "../types";
-import { AuthenticationError, ScopeError } from "./anthropic-oauth-usage";
+import { UsageError, classifyUsageError } from "../errors";
 
-export { AuthenticationError, ScopeError };
+export class AuthenticationError extends UsageError {
+  constructor(message: string) {
+    super("invalid-credentials", message);
+    this.name = "AuthenticationError";
+  }
+}
 
-export class ParseError extends Error {
+export class ScopeError extends UsageError {
   constructor(message: string) {
-    super(message);
+    super("forbidden", message);
+    this.name = "ScopeError";
+  }
+}
+
+export class ParseError extends UsageError {
+  constructor(message: string) {
+    super("invalid-response", message);
     this.name = "ParseError";
   }
 }
 
 export class CodexOAuthUsageClient implements UsageClient<CodexOAuthCredentials, CodexUsageSnapshot> {
   async fetch(creds: CodexOAuthCredentials, options?: { signal?: AbortSignal }): Promise<CodexUsageSnapshot> {
-    const baseUrl = creds.chatgptBaseUrl ?? "https://chatgpt.com";
-    const url = `${baseUrl}/backend-api/wham/usage`;
+    const url = `${backendApiBaseUrl(creds)}/wham/usage`;
 
     const headers: Record<string, string> = {
       Authorization: `Bearer ${creds.accessToken}`,
@@ -24,11 +35,16 @@ export class CodexOAuthUsageClient implements UsageClient<CodexOAuthCredentials,
       headers["ChatGPT-Account-Id"] = creds.accountId;
     }
 
-    const res = await fetch(url, {
-      method: "GET",
-      headers,
-      signal: options?.signal,
-    });
+    let res: Response;
+    try {
+      res = await fetch(url, {
+        method: "GET",
+        headers,
+        signal: options?.signal,
+      });
+    } catch (error) {
+      throw classifyUsageError(error);
+    }
 
     if (res.status === 401) {
       throw new AuthenticationError("Codex OAuth token expired or invalid");
@@ -40,13 +56,23 @@ export class CodexOAuthUsageClient implements UsageClient<CodexOAuthCredentials,
       }
       throw new ScopeError("Codex OAuth access forbidden");
     }
+    if (res.status === 429) {
+      const retryAfter = Number.parseFloat(res.headers.get("retry-after") ?? "");
+      throw new UsageError("rate-limited", "Codex usage request was rate limited", Number.isFinite(retryAfter) ? retryAfter * 1_000 : undefined);
+    }
     if (!res.ok) {
-      throw new Error(`Codex usage server error: ${res.status}`);
+      throw new UsageError("transient", `Codex usage server error: ${res.status}`);
     }
 
-    const body = (await res.json()) as Record<string, unknown>;
+    let body: Record<string, unknown>;
+    try {
+      body = (await res.json()) as Record<string, unknown>;
+    } catch {
+      throw new ParseError("Codex usage response was not valid JSON");
+    }
 
-    const planType = typeof body["plan_type"] === "string" ? body["plan_type"] : null;
+    const planType = pickString(body, "plan_type", "planType") ?? null;
+    const responseAccountId = pickString(body, "account_id", "accountId") ?? null;
 
     // Handle both rate_limit and rate_limits key names
     const rateLimitKey = typeof body["rate_limit"] === "object" && body["rate_limit"] !== null
@@ -62,14 +88,21 @@ export class CodexOAuthUsageClient implements UsageClient<CodexOAuthCredentials,
 
     const primaryWindow = parseWindow(rateLimit?.["primary_window"] as Record<string, unknown> | undefined);
     const secondaryWindow = parseWindow(rateLimit?.["secondary_window"] as Record<string, unknown> | undefined);
+    const spendControl = pickRecord(body, "spend_control", "spendControl");
+    const individualLimit = parseIndividualLimit(
+      pickRecord(body, "individual_limit", "individualLimit")
+        ?? pickRecord(rateLimit, "individual_limit", "individualLimit")
+        ?? (spendControl ? pickRecord(spendControl, "individual_limit", "individualLimit") : undefined),
+    );
 
     let credits: CodexUsageSnapshot["credits"] = null;
     if (typeof body["credits"] === "object" && body["credits"] !== null) {
       const c = body["credits"] as Record<string, unknown>;
+      const balance = pickFiniteNumber(c, "balance");
       credits = {
         hasCredits: c["has_credits"] === true,
         unlimited: c["unlimited"] === true,
-        balance: typeof c["balance"] === "number" ? c["balance"] : null,
+        balance: balance !== undefined && balance >= 0 ? balance : null,
       };
     }
 
@@ -79,13 +112,61 @@ export class CodexOAuthUsageClient implements UsageClient<CodexOAuthCredentials,
       primaryWindow,
       secondaryWindow,
       credits,
+      individualLimit,
+      spendControlPresent: Object.hasOwn(body, "spend_control") || Object.hasOwn(body, "spendControl"),
       updatedAt: new Date(),
       accountEmail: creds.accountEmail ?? null,
-      accountId: creds.accountId ?? null,
+      accountId: responseAccountId ?? creds.accountId ?? null,
     };
   }
 }
 
+export class CodexMonthlySpendClient {
+  async fetch(
+    creds: CodexOAuthCredentials,
+    accountId: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<NonNullable<CodexUsageSnapshot["individualLimit"]> | null> {
+    const encodedAccountId = encodeURIComponent(accountId);
+    const url = `${backendApiBaseUrl(creds)}/accounts/${encodedAccountId}/spend-controls/current-user/monthly-usage`;
+    let res: Response;
+    try {
+      res = await fetch(url, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${creds.accessToken}`,
+          Accept: "application/json",
+          "ChatGPT-Account-Id": accountId,
+        },
+        signal: options?.signal,
+      });
+    } catch (error) {
+      throw classifyUsageError(error);
+    }
+    if (!res.ok) {
+      throw new UsageError(
+        res.status === 401 ? "invalid-credentials" : res.status === 403 ? "forbidden" : "transient",
+        `Codex monthly spend request failed: ${res.status}`,
+      );
+    }
+
+    let body: Record<string, unknown>;
+    try {
+      body = (await res.json()) as Record<string, unknown>;
+    } catch {
+      throw new ParseError("Codex monthly spend response was not valid JSON");
+    }
+    const effectiveLimit = pickRecord(body, "effective_monthly_limit", "effectiveMonthlyLimit");
+    if (!effectiveLimit) return null;
+    const enforcement = pickString(effectiveLimit, "enforcement_mode", "enforcementMode")?.toLowerCase();
+    if (enforcement && ["none", "off", "disabled", "no_limit"].includes(enforcement)) return null;
+    const used = pickFiniteNumber(body, "current_month_usage", "currentMonthUsage");
+    const limit = pickFiniteNumber(effectiveLimit, "limit");
+    if (used === undefined || limit === undefined || limit <= 0) return null;
+    return { used: Math.max(0, used), limit, resetsAt: null };
+  }
+}
+
 function parseWindow(raw: Record<string, unknown> | undefined): RateWindowLegacy | null {
   if (!raw) return null;
   const usedPercent = typeof raw["used_percent"] === "number" ? raw["used_percent"] : 0;
@@ -103,6 +184,52 @@ function parseWindow(raw: Record<string, unknown> | undefined): RateWindowLegacy
   };
 }
 
+function parseIndividualLimit(
+  raw: Record<string, unknown> | undefined,
+): NonNullable<CodexUsageSnapshot["individualLimit"]> | null {
+  if (!raw) return null;
+  const used = pickFiniteNumber(raw, "used");
+  const limit = pickFiniteNumber(raw, "limit");
+  if (used === undefined || limit === undefined || limit <= 0) return null;
+  const reset = pickFiniteNumber(raw, "resets_at", "resetsAt", "reset_at");
+  return {
+    used: Math.max(0, used),
+    limit,
+    resetsAt: reset === undefined ? null : new Date(reset * 1_000),
+  };
+}
+
+function backendApiBaseUrl(creds: CodexOAuthCredentials): string {
+  const base = (creds.chatgptBaseUrl ?? "https://chatgpt.com").replace(/\/+$/, "");
+  return base.endsWith("/backend-api") ? base : `${base}/backend-api`;
+}
+
+function pickRecord(raw: Record<string, unknown>, ...keys: string[]): Record<string, unknown> | undefined {
+  for (const key of keys) {
+    const value = raw[key];
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+  }
+  return undefined;
+}
+
+function pickString(raw: Record<string, unknown>, ...keys: string[]): string | undefined {
+  for (const key of keys) if (typeof raw[key] === "string") return raw[key];
+  return undefined;
+}
+
+function pickFiniteNumber(raw: Record<string, unknown>, ...keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = raw[key];
+    const normalized = typeof value === "string" ? value.trim() : value;
+    if (normalized === "") continue;
+    const number = typeof normalized === "number" ? normalized : typeof normalized === "string" ? Number(normalized) : Number.NaN;
+    if (Number.isFinite(number)) return number;
+  }
+  return undefined;
+}
+
 function formatDuration(ms: number): string {
   const seconds = Math.floor(ms / 1000);
   const minutes = Math.floor(seconds / 60);

package/src/usage/clients/opencode-go-api.ts

@@ -0,0 +1,100 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { OpenCodeGoUsageSnapshot } from "../types";
+
+export interface OpenCodeGoUsageApiResponse {
+  usage?: {
+    rolling?: UsageApiWindow;
+    weekly?: UsageApiWindow;
+    monthly?: UsageApiWindow;
+  };
+}
+
+interface UsageApiWindow {
+  status?: string;
+  percent?: number;
+  resetsAt?: string;
+}
+
+export const OPENCODE_API_KEY_ENV = "OPENCODE_API_KEY";
+
+export class OpenCodeGoApiKeyUsageClient {
+  constructor(
+    private readonly usageUrl: string = "https://opencode.ai/zen/go/v1/usage",
+    private readonly authJsonPath: string = join(homedir(), ".local", "share", "opencode", "auth.json"),
+    private readonly env: Record<string, string | undefined> = process.env,
+  ) {}
+
+  async resolveApiKey(): Promise<string | null> {
+    const fromEnv = this.env[OPENCODE_API_KEY_ENV]?.trim();
+    if (fromEnv) return fromEnv;
+    try {
+      const auth = (JSON.parse(await Bun.file(this.authJsonPath).text()) as Record<string, unknown>)["opencode-go"];
+      if (auth && typeof auth === "object") {
+        const apiKey = (auth as Record<string, unknown>)["key"];
+        if (typeof apiKey === "string" && apiKey.trim()) return apiKey.trim();
+      }
+    } catch {
+      // Missing or malformed auth.json simply means no API key available.
+    }
+    return null;
+  }
+
+  async fetch(): Promise<OpenCodeGoUsageSnapshot | null> {
+    const apiKey = await this.resolveApiKey();
+    if (!apiKey) return null;
+
+    let response: Response;
+    try {
+      response = await fetch(this.usageUrl, {
+        headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json", "User-Agent": "scrylog" },
+        redirect: "manual",
+      });
+    } catch {
+      return null;
+    }
+    if (!response.ok) return null;
+
+    let body: OpenCodeGoUsageApiResponse;
+    try {
+      body = (await response.json()) as OpenCodeGoUsageApiResponse;
+    } catch {
+      return null;
+    }
+    const usage = body.usage;
+    if (!usage || typeof usage !== "object") return null;
+
+    const now = new Date();
+    const rolling = parseUsageWindow(usage.rolling, now);
+    const weekly = parseUsageWindow(usage.weekly, now);
+    if (!rolling || !weekly) return null;
+    const monthly = parseUsageWindow(usage.monthly, now);
+
+    return {
+      source: "api",
+      hasMonthlyUsage: monthly !== null,
+      rollingUsagePercent: rolling.percent,
+      weeklyUsagePercent: weekly.percent,
+      monthlyUsagePercent: monthly?.percent ?? 0,
+      rollingResetInSec: rolling.resetInSec,
+      weeklyResetInSec: weekly.resetInSec,
+      monthlyResetInSec: monthly?.resetInSec ?? 0,
+      updatedAt: now,
+      workspaceId: null,
+      workspaceName: null,
+    };
+  }
+}
+
+function parseUsageWindow(raw: UsageApiWindow | undefined, now: Date): { percent: number; resetInSec: number } | null {
+  if (!raw || typeof raw !== "object" || raw.status === "exceeded") return null;
+  if (typeof raw.percent !== "number" || !Number.isFinite(raw.percent)) return null;
+  const percent = Math.max(0, Math.min(100, raw.percent));
+  let resetInSec = 0;
+  if (typeof raw.resetsAt === "string") {
+    const at = Date.parse(raw.resetsAt);
+    if (!Number.isNaN(at)) resetInSec = Math.max(0, Math.round((at - now.getTime()) / 1000));
+  }
+  return { percent, resetInSec };
+}