@astrosheep/pi-quota 0.5.0

package/src/index.ts

@@ -0,0 +1,24 @@
+import { getAgentDir, SettingsManager } from '@earendil-works/pi-coding-agent';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { createQuotaExtension } from './extension.ts';
+import { loadQuotaAdaptersFromSettings, QuotaConfigError } from './config.ts';
+import type { QuotaAdapter } from './query/types.ts';
+
+export default function (pi: ExtensionAPI): void {
+  let adapters: QuotaAdapter[] = [];
+  try {
+    // Quota provider bindings belong to the user's global Pi settings. Project
+    // settings are intentionally not read here: a project must not redirect a
+    // globally authenticated provider's credential to an account endpoint.
+    const settings = SettingsManager.create(process.cwd(), getAgentDir(), {
+      projectTrusted: false,
+    }).getGlobalSettings() as unknown;
+    adapters = loadQuotaAdaptersFromSettings(settings);
+  } catch {
+    pi.on('session_start', (_event, ctx) => {
+      if (ctx.hasUI) ctx.ui.notify(new QuotaConfigError().message, 'warning');
+    });
+  }
+  // Invalid optional settings never disable the built-in Codex/Kimi/OpenCode Go adapters.
+  createQuotaExtension({ adapters })(pi);
+}

package/src/query/codex.ts

@@ -0,0 +1,65 @@
+import { bearer, header, officialAuth } from './http.ts';
+import { numeric, object, percent, safeLabel, timestamp, windowLabel } from './parse.ts';
+import { QuotaError } from './types.ts';
+import type { QuotaAdapter, QuotaWindow } from './types.ts';
+
+// Decode only to obtain routing metadata from the same resolved token.
+// This does not verify a JWT; the official server verifies authentication.
+export function codexAccountId(token: string): string | undefined {
+  try {
+    const payload = object(JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8')));
+    const id = object(payload['https://api.openai.com/auth']).chatgpt_account_id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+  } catch { return undefined; }
+}
+
+export function parseCodex(payload: unknown, now: number): QuotaWindow[] {
+  const data = object(payload);
+  const windows: QuotaWindow[] = [];
+  const addDomain = (raw: unknown, domain: string, scope?: string) => {
+    const rate = object(raw);
+    for (const [key, fallback] of [['primary_window', 18000], ['secondary_window', 604800]] as const) {
+      if (rate[key] == null) continue;
+      const window = object(rate[key]);
+      const duration = numeric(window.limit_window_seconds) ?? fallback;
+      if (duration <= 0) throw new QuotaError('schema');
+      const remaining = numeric(window.remaining_percent) ?? numeric(window.percent_left);
+      const used = numeric(window.used_percent);
+      const resetAfter = numeric(window.reset_after_seconds);
+      const resetAt = timestamp(window.reset_at ?? window.reset_time_ms)
+        ?? (resetAfter !== null && resetAfter >= 0 ? now + resetAfter * 1000 : null);
+      windows.push({
+        id: `${domain}/${key}`, label: windowLabel(duration), durationSeconds: duration,
+        remainingPercent: remaining !== null ? percent(remaining) : used !== null ? percent(100 - used) : null,
+        resetAt, ...(scope ? { scope } : {}),
+      });
+    }
+  };
+  addDomain(data.rate_limit, 'shared');
+  if (Array.isArray(data.additional_rate_limits)) {
+    for (const [index, entry] of data.additional_rate_limits.entries()) {
+      const item = object(entry);
+      const name = item.limit_name ?? item.metered_feature;
+      const scope = typeof name === 'string' ? safeLabel(name) : `Model ${index + 1}`;
+      addDomain(item.rate_limit, `additional-${index}`, scope);
+    }
+  }
+  if (windows.length === 0) throw new QuotaError('schema');
+  return windows;
+}
+
+export const codexAdapter: QuotaAdapter = {
+  provider: 'openai-codex', label: 'Codex',
+  async query(context) {
+    const auth = await officialAuth(context, 'https://chatgpt.com');
+    const token = bearer(auth);
+    const account = header(auth, 'chatgpt-account-id') ?? codexAccountId(token);
+    if (!account) throw new QuotaError('unsupported-auth');
+    const data = await context.getJson('https://chatgpt.com/backend-api/wham/usage', {
+      Authorization: `Bearer ${token}`, 'ChatGPT-Account-Id': account,
+      Origin: 'https://chatgpt.com', Referer: 'https://chatgpt.com/',
+    }, context.signal);
+    const now = context.now();
+    return { windows: parseCodex(data, now), fetchedAt: now };
+  },
+};

package/src/query/controller.ts

@@ -0,0 +1,115 @@
+import { AdapterRegistry, validateSnapshot } from './registry.ts';
+import { QuotaError } from './types.ts';
+import type { QueryContext, QuotaState } from './types.ts';
+
+type AuthResolver = QueryContext['getAuth'];
+interface ControllerOptions {
+  registry: AdapterRegistry;
+  getJson: QueryContext['getJson'];
+  onState(state: QuotaState): void;
+  now?: () => number;
+  intervalMs?: number;
+  timeoutMs?: number;
+}
+
+// Waiting is bounded even if a custom adapter or auth resolver ignores abort.
+async function abortable<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  let rejectAbort: () => void = () => {};
+  const aborted = new Promise<never>((_resolve, reject) => {
+    rejectAbort = () => reject(signal.reason);
+    signal.addEventListener('abort', rejectAbort, { once: true });
+  });
+  try { return await Promise.race([work, aborted]); }
+  finally { signal.removeEventListener('abort', rejectAbort); }
+}
+
+export class QuotaController {
+  state: QuotaState = { kind: 'hidden' };
+  private provider?: string;
+  private generation = 0;
+  private request?: { abort: AbortController; promise: Promise<void> };
+  private nextAttempt = 0;
+  private failures = 0;
+  private readonly options: ControllerOptions;
+  private readonly now: () => number;
+  private readonly interval: number;
+  private readonly timeout: number;
+
+  constructor(options: ControllerOptions) {
+    this.options = options;
+    this.now = options.now ?? Date.now;
+    this.interval = options.intervalMs ?? 60000;
+    this.timeout = options.timeoutMs ?? 10000;
+    if (!Number.isFinite(this.interval) || this.interval <= 0
+      || !Number.isFinite(this.timeout) || this.timeout <= 0) throw new Error('Invalid quota timing');
+  }
+
+  private publish(state: QuotaState): void {
+    this.state = state;
+    this.options.onState(state);
+  }
+
+  select(provider: string | undefined): void {
+    this.generation++;
+    this.request?.abort.abort();
+    this.request = undefined;
+    this.provider = provider;
+    this.nextAttempt = 0;
+    this.failures = 0;
+    const adapter = this.options.registry.get(provider);
+    // Clear old values synchronously, before auth resolution or any network I/O.
+    this.publish(adapter
+      ? { kind: 'loading', provider: adapter.provider, label: adapter.label }
+      : { kind: 'hidden' });
+  }
+
+  stop(): void { this.select(undefined); }
+
+  refresh(getAuth: AuthResolver, force = false): Promise<void> {
+    const adapter = this.options.registry.get(this.provider);
+    if (!adapter) return Promise.resolve();
+    if (this.request && !force) return this.request.promise;
+    if (!force && this.now() < this.nextAttempt) return Promise.resolve();
+    if (force) {
+      this.generation++;
+      this.request?.abort.abort();
+      this.request = undefined;
+    }
+    const generation = this.generation;
+    const abort = new AbortController();
+    const active = () => this.generation === generation && this.request?.abort === abort;
+    // Keep the last result visible during refresh; selection already clears it.
+    if (this.state.kind !== 'ready' && this.state.kind !== 'loading') {
+      this.publish({ kind: 'loading', provider: adapter.provider, label: adapter.label });
+    }
+    const deadline = setTimeout(() => abort.abort(new QuotaError('timeout')), this.timeout);
+    const promise = Promise.resolve().then(async () => {
+      try {
+        abort.signal.throwIfAborted();
+        const result = await abortable(adapter.query({
+          provider: adapter.provider, signal: abort.signal, now: this.now,
+          getAuth, getJson: this.options.getJson,
+        }), abort.signal);
+        if (!active()) return;
+        const snapshot = validateSnapshot(result);
+        this.failures = 0;
+        this.nextAttempt = this.now() + this.interval;
+        this.publish({ kind: 'ready', provider: adapter.provider, label: adapter.label, snapshot });
+      } catch (error) {
+        if (!active()) return;
+        const safe = error instanceof QuotaError ? error : new QuotaError('network');
+        this.failures++;
+        const backoff = Math.min(900000, this.interval * 2 ** Math.min(this.failures - 1, 4));
+        this.nextAttempt = this.now() + Math.max(backoff, safe.retryAfterMs ?? 0);
+        // Do not retain a prior account's cached quota after auth changes/errors.
+        this.publish({ kind: 'error', provider: adapter.provider, label: adapter.label, code: safe.code });
+      } finally {
+        clearTimeout(deadline);
+        if (active()) this.request = undefined;
+      }
+    });
+    this.request = { abort, promise };
+    return promise;
+  }
+}

package/src/query/deepseek.ts

@@ -0,0 +1,35 @@
+import { bearer, officialAuth } from './http.ts';
+import { numeric, object } from './parse.ts';
+import { QuotaError } from './types.ts';
+import type { AccountBalance, QuotaAdapter } from './types.ts';
+
+export const DEEPSEEK_ORIGIN = 'https://api.deepseek.com';
+
+// https://api-docs.deepseek.com/api/get-user-balance
+// GET /user/balance (also mounted under /v1/). The sk- key works directly.
+// Amounts arrive as strings in yuan; balance_infos may list several currencies.
+export function parseDeepSeekBalance(payload: unknown): AccountBalance {
+  const body = object(payload);
+  if (!Array.isArray(body.balance_infos) || body.balance_infos.length === 0) throw new QuotaError('schema');
+  for (const entry of body.balance_infos) {
+    const info = object(entry);
+    const remaining = numeric(info.total_balance);
+    if (typeof info.currency !== 'string' || !/^[A-Z]{3}$/.test(info.currency)
+      || remaining === null || remaining < 0) continue;
+    // The endpoint exposes no usage total; only return the actual balance.
+    return { currency: info.currency, remaining };
+  }
+  throw new QuotaError('schema');
+}
+
+export function createDeepSeekAdapter(provider: string): QuotaAdapter {
+  return {
+    provider, label: provider,
+    async query(context) {
+      const auth = await officialAuth(context, DEEPSEEK_ORIGIN);
+      const payload = await context.getJson(`${DEEPSEEK_ORIGIN}/user/balance`,
+        { Authorization: `Bearer ${bearer(auth)}` }, context.signal);
+      return { windows: [], balance: parseDeepSeekBalance(payload), fetchedAt: context.now() };
+    },
+  };
+}

package/src/query/http.ts

@@ -0,0 +1,86 @@
+import { QuotaError } from './types.ts';
+import type { ProviderAuth, QueryContext } from './types.ts';
+
+export function createJsonClient(fetcher: typeof fetch = globalThis.fetch): QueryContext['getJson'] {
+  return async (url, headers, signal) => {
+    try {
+      const response = await fetcher(url, {
+        method: 'GET', headers: { Accept: 'application/json', ...headers },
+        signal, redirect: 'error', // Never forward credentials to a redirected endpoint.
+      });
+      if (!response.ok) {
+        const retry = response.headers.get('retry-after');
+        const seconds = retry && /^\d+(\.\d+)?$/.test(retry) ? Number(retry) : NaN;
+        const delay = Number.isFinite(seconds) ? seconds * 1000
+          : retry ? Date.parse(retry) - Date.now() : NaN;
+        await response.body?.cancel();
+        if (response.status === 401 || response.status === 403) throw new QuotaError('auth');
+        if (response.status === 429) {
+          throw new QuotaError('rate-limit', Number.isFinite(delay) ? Math.max(0, delay) : undefined);
+        }
+        throw new QuotaError('http');
+      }
+      // Quota responses are small. Bound memory and reject unexpected HTML/proxy pages.
+      const reader = response.body?.getReader();
+      if (!reader) throw new QuotaError('schema');
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      try {
+        while (true) {
+          const part = await reader.read();
+          if (part.done) break;
+          size += part.value.length;
+          if (size > 256 * 1024) {
+            await reader.cancel();
+            throw new QuotaError('schema');
+          }
+          chunks.push(part.value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown;
+      } catch {
+        throw new QuotaError('schema');
+      }
+    } catch (error) {
+      if (error instanceof QuotaError) throw error;
+      if (signal.aborted) throw signal.reason;
+      throw new QuotaError('network');
+    }
+  };
+}
+
+export function header(auth: ProviderAuth, name: string): string | undefined {
+  return Object.entries(auth.headers ?? {}).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
+}
+
+export async function officialAuth(context: QueryContext, origin: string): Promise<ProviderAuth> {
+  let auth: ProviderAuth | undefined;
+  try {
+    auth = await context.getAuth(context.provider);
+  } catch {
+    throw new QuotaError('auth');
+  }
+  context.signal.throwIfAborted();
+  if (!auth) throw new QuotaError('auth');
+  if (auth.baseUrl) {
+    let actual: URL;
+    try { actual = new URL(auth.baseUrl); } catch { throw new QuotaError('unsupported-auth'); }
+    if (actual.origin !== origin || actual.username || actual.password) throw new QuotaError('unsupported-auth');
+  }
+  return auth;
+}
+
+export function bearer(auth: ProviderAuth): string {
+  const authorization = header(auth, 'authorization');
+  // A runtime Authorization header overrides apiKey, just as it does for requests.
+  if (authorization !== undefined) {
+    const token = /^Bearer\s+(\S+)$/i.exec(authorization)?.[1];
+    if (!token) throw new QuotaError('unsupported-auth');
+    return token;
+  }
+  if (!auth.apiKey) throw new QuotaError('auth');
+  return auth.apiKey;
+}

package/src/query/kimi.ts

@@ -0,0 +1,53 @@
+import { bearer, officialAuth } from './http.ts';
+import { numeric, object, percent, timestamp, windowLabel } from './parse.ts';
+import { QuotaError } from './types.ts';
+import type { QuotaAdapter, QuotaWindow } from './types.ts';
+
+const units: Record<string, number> = {
+  TIME_UNIT_SECOND: 1, TIME_UNIT_MINUTE: 60, TIME_UNIT_HOUR: 3600, TIME_UNIT_DAY: 86400,
+};
+
+export function parseKimi(payload: unknown): QuotaWindow[] {
+  const data = object(payload);
+  const windows: QuotaWindow[] = [];
+  const add = (raw: unknown, duration: number, id: string) => {
+    const detail = object(raw);
+    const limit = numeric(detail.limit);
+    const used = numeric(detail.used);
+    const remaining = numeric(detail.remaining);
+    // No default for omitted counts: absence is not proof of zero usage.
+    const fraction = limit !== null && limit > 0
+      ? remaining !== null && remaining >= 0 ? remaining / limit
+        : used !== null && used >= 0 ? 1 - used / limit : null
+      : null;
+    windows.push({
+      id, label: windowLabel(duration), durationSeconds: duration,
+      remainingPercent: fraction === null ? null : percent(fraction * 100),
+      resetAt: timestamp(detail.resetTime ?? detail.reset_at),
+    });
+  };
+  if (data.usage != null && typeof data.usage === 'object') add(data.usage, 604800, 'weekly');
+  if (Array.isArray(data.limits)) {
+    for (const [index, raw] of data.limits.entries()) {
+      const entry = object(raw);
+      const window = object(entry.window);
+      const multiplier = typeof window.timeUnit === 'string' ? units[window.timeUnit] : undefined;
+      const duration = numeric(window.duration);
+      if (!entry.detail || !multiplier || duration === null || duration <= 0) continue;
+      add(entry.detail, duration * multiplier, `limit-${index}`);
+    }
+  }
+  if (windows.length === 0) throw new QuotaError('schema');
+  return windows.sort((a, b) => a.durationSeconds - b.durationSeconds);
+}
+
+export const kimiAdapter: QuotaAdapter = {
+  provider: 'kimi-coding', label: 'Kimi',
+  async query(context) {
+    const auth = await officialAuth(context, 'https://api.kimi.com');
+    const data = await context.getJson('https://api.kimi.com/coding/v1/usages', {
+      Authorization: `Bearer ${bearer(auth)}`,
+    }, context.signal);
+    return { windows: parseKimi(data), fetchedAt: context.now() };
+  },
+};

package/src/query/new-api.ts

@@ -0,0 +1,154 @@
+import { bearer } from './http.ts';
+import { numeric, object } from './parse.ts';
+import { QuotaError } from './types.ts';
+import { safeBaseUrl } from './url.ts';
+import type { AccountBalance, QuotaAdapter } from './types.ts';
+
+export interface NewApiOptions {
+  quotaPerUnit?: number;
+  currency?: string;
+  // Console dashboard PAT (个人设置 → 安全设置 → 系统访问令牌). When set,
+  // /api/user/self is queried first for the real account balance.
+  dashboardAccessToken?: string;
+  // Numeric user ID, sent as New-Api-User. Only old new-api forks require it.
+  dashboardUserId?: number;
+}
+
+export function validateNewApiOptions(options: NewApiOptions): { quotaPerUnit: number; currency: string } {
+  const quotaPerUnit = options.quotaPerUnit ?? 500000;
+  const currency = options.currency ?? 'USD';
+  if (!Number.isFinite(quotaPerUnit) || quotaPerUnit <= 0) throw new Error('quotaPerUnit must be a positive number');
+  if (typeof currency !== 'string' || !/^[A-Z]{3}$/.test(currency)) throw new Error('currency must be a three-letter uppercase code');
+  return { quotaPerUnit, currency };
+}
+
+// Billing endpoints live at the deployment root, never under /v1.
+// https://host/v1 -> https://host, https://host/gateway/v1 -> https://host/gateway
+export function newApiRootUrl(baseUrl: string | undefined): string {
+  const url = safeBaseUrl(baseUrl);
+  const path = url.pathname.replace(/\/+$/, '').replace(/\/v\d+(?:beta\d*)?$/i, '');
+  return url.origin + path;
+}
+
+// GET /api/usage/token (new-api >= v0.9.0-alpha.8, PR QuantumNous/new-api#1161):
+// accepts the sk- model key itself (TokenAuth), returns per-token quota in
+// the same unit as /api/user/self quota. Response shell: {code:true,data:{...}}.
+export function parseNewApiTokenUsage(payload: unknown, options: NewApiOptions = {}): AccountBalance | null {
+  const { quotaPerUnit, currency } = validateNewApiOptions(options);
+  const response = object(payload);
+  if (response.code !== true) return null;
+  const data = object(response.data);
+  if (data.object !== 'token_usage') return null;
+  const used = numeric(data.total_used);
+  // Missing fields must not become a made-up zero balance.
+  if (used === null || !Number.isSafeInteger(used) || used < 0) throw new QuotaError('schema');
+  if (data.unlimited_quota === true) {
+    return { currency, remaining: 0, unlimited: true };
+  }
+  const remaining = numeric(data.total_available);
+  if (remaining === null || !Number.isSafeInteger(remaining)) throw new QuotaError('schema');
+  const balance = { currency, remaining: remaining / quotaPerUnit };
+  if (!Number.isFinite(balance.remaining)) throw new QuotaError('schema');
+  return balance;
+}
+
+// GET /api/user/self (UserAuth): the console's own account quota, readable with
+// a dashboard access token (PAT), which sk- keys are not. Old forks also demand
+// a matching New-Api-User header. Response shell: {success:true,data:{...}}.
+export function parseNewApiUserSelf(payload: unknown, options: NewApiOptions = {}): AccountBalance {
+  const { quotaPerUnit, currency } = validateNewApiOptions(options);
+  const response = object(payload);
+  if (response.success !== true) throw new QuotaError('schema');
+  const data = object(response.data);
+  const quota = numeric(data.quota);
+  const usedQuota = numeric(data.used_quota);
+  if (quota === null || usedQuota === null
+    || !Number.isSafeInteger(quota) || !Number.isSafeInteger(usedQuota)
+    || quota < 0 || usedQuota < 0) throw new QuotaError('schema');
+  return { currency, remaining: quota / quotaPerUnit };
+}
+
+// Legacy one-api billing pair, still the only option on older deployments.
+// total_usage is in cents (divide by 100, per one-api issue #1785); most
+// deployments report a fake 1e8 hard limit for unlimited quotas.
+export function parseNewApiBilling(subscription: unknown, usage: unknown, options: NewApiOptions = {}): AccountBalance {
+  const { currency } = validateNewApiOptions(options);
+  const sub = object(subscription);
+  const limit = numeric(sub.hard_limit_usd);
+  const list = object(usage);
+  const totalUsage = numeric(list.total_usage);
+  if (limit === null || !Number.isFinite(limit) || limit < 0
+    || totalUsage === null || !Number.isFinite(totalUsage) || totalUsage < 0) throw new QuotaError('schema');
+  const used = totalUsage / 100;
+  if (limit >= 1e7) return { currency, remaining: 0, unlimited: true };
+  return { currency, remaining: limit - used };
+}
+
+export function createNewApiAdapter(provider: string, options: NewApiOptions = {}): QuotaAdapter {
+  const settings = validateNewApiOptions(options);
+  const { dashboardAccessToken, dashboardUserId } = options;
+  if (dashboardAccessToken !== undefined
+    && (typeof dashboardAccessToken !== 'string' || dashboardAccessToken.trim() === '')) {
+    throw new Error('dashboardAccessToken must be a non-empty string');
+  }
+  if (dashboardUserId !== undefined
+    && (!Number.isSafeInteger(dashboardUserId) || dashboardUserId <= 0)) {
+    throw new Error('dashboardUserId must be a positive integer');
+  }
+  return {
+    provider, label: provider,
+    async query(context) {
+      let auth;
+      try { auth = await context.getAuth(context.provider); }
+      catch { throw new QuotaError('auth'); }
+      context.signal.throwIfAborted();
+      if (!auth) throw new QuotaError('auth');
+      const root = newApiRootUrl(auth.baseUrl);
+      // 0. Console account balance via PAT: the only view of real remaining
+      // account quota. Any failure falls through to the key-native paths.
+      if (dashboardAccessToken !== undefined) {
+        const headers: Record<string, string> = { Authorization: `Bearer ${dashboardAccessToken}` };
+        if (dashboardUserId !== undefined) headers['New-Api-User'] = String(dashboardUserId);
+        try {
+          const payload = await context.getJson(`${root}/api/user/self`, headers, context.signal);
+          return { windows: [], balance: parseNewApiUserSelf(payload, settings), fetchedAt: context.now() };
+        } catch (error) {
+          if (!(error instanceof QuotaError)) throw error;
+        }
+      }
+      const headers = { Authorization: `Bearer ${bearer(auth)}` };
+      // 1. Account billing (one-api legacy): a finite hard limit is the real
+      // account balance. 1e8 means unlimited — then the key quota may still
+      // be finite and more precise.
+      let billingBalance: AccountBalance | null = null;
+      try {
+        const pair = await Promise.all([
+          context.getJson(`${root}/v1/dashboard/billing/subscription`, headers, context.signal),
+          context.getJson(`${root}/v1/dashboard/billing/usage?start_date=2020-01-01&end_date=2100-01-01`, headers, context.signal),
+        ]);
+        const billing = parseNewApiBilling(pair[0], pair[1], settings);
+        if (billing.unlimited !== true) return { windows: [], balance: billing, fetchedAt: context.now() };
+        billingBalance = billing;
+      } catch (error) {
+        // 404: deployment has no billing pair. 401: try the key-native endpoint
+        // below — some deployments accept sk- only there.
+        if (error instanceof QuotaError && (error.code === 'http' || error.code === 'auth')) { /* fall through */ }
+        else throw error;
+      }
+      // 2. Per-token usage (new-api ≥ v0.9.0-alpha.8): native sk- support.
+      try {
+        const payload = await context.getJson(`${root}/api/usage/token/`, headers, context.signal);
+        const parsed = parseNewApiTokenUsage(payload, settings);
+        if (parsed) return { windows: [], balance: parsed, fetchedAt: context.now() };
+      } catch (error) {
+        if (billingBalance && error instanceof QuotaError && error.code === 'http') {
+          return { windows: [], balance: billingBalance, fetchedAt: context.now() };
+        }
+        if (error instanceof QuotaError && error.code === 'auth') throw new QuotaError('account-access');
+        throw error;
+      }
+      if (billingBalance) return { windows: [], balance: billingBalance, fetchedAt: context.now() };
+      throw new QuotaError('schema');
+    },
+  };
+}

package/src/query/opencode-go.ts

@@ -0,0 +1,42 @@
+import { bearer, officialAuth } from './http.ts';
+import { numeric, object, percent, timestamp, windowLabel } from './parse.ts';
+import { QuotaError } from './types.ts';
+import type { QuotaAdapter, QuotaWindow } from './types.ts';
+
+// OpenCode Go (opencode.ai Zen Go plan) is a single official deployment, so the
+// window keys are fixed and undecorated: percent is already "used", and there is
+// no dollar balance — only the console shows money.
+const WINDOWS = [
+  { key: 'rolling', duration: 18000 }, // 5 hours
+  { key: 'weekly', duration: 604800 }, // 7 days
+  { key: 'monthly', duration: 2592000 }, // 30 days
+] as const;
+
+export function parseOpenCodeGo(payload: unknown): QuotaWindow[] {
+  const usage = object(object(payload).usage);
+  const windows: QuotaWindow[] = [];
+  for (const { key, duration } of WINDOWS) {
+    if (usage[key] === undefined) continue;
+    const detail = object(usage[key]);
+    const used = numeric(detail.percent);
+    windows.push({
+      id: key, label: windowLabel(duration), durationSeconds: duration,
+      // Absent or malformed percent stays unknown; never fabricate a window.
+      remainingPercent: used === null ? null : percent(100 - used),
+      resetAt: timestamp(detail.resetsAt),
+    });
+  }
+  if (windows.length === 0) throw new QuotaError('schema');
+  return windows;
+}
+
+export const openCodeGoAdapter: QuotaAdapter = {
+  provider: 'opencode-go', label: 'OpenCode Go',
+  async query(context) {
+    const auth = await officialAuth(context, 'https://opencode.ai');
+    const data = await context.getJson('https://opencode.ai/zen/go/v1/usage', {
+      Authorization: `Bearer ${bearer(auth)}`,
+    }, context.signal);
+    return { windows: parseOpenCodeGo(data), fetchedAt: context.now() };
+  },
+};

package/src/query/parse.ts

@@ -0,0 +1,35 @@
+export function object(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : {};
+}
+
+export function numeric(value: unknown): number | null {
+  if (typeof value !== 'number' && !(typeof value === 'string' && value.trim() !== '')) return null;
+  const result = Number(value);
+  return Number.isFinite(result) ? result : null;
+}
+
+export function percent(value: number): number {
+  return Math.max(0, Math.min(100, value));
+}
+
+export function timestamp(value: unknown): number | null {
+  const number = numeric(value);
+  const parsed = number !== null
+    ? (number < 1e12 ? number * 1000 : number)
+    : typeof value === 'string' ? Date.parse(value) : NaN;
+  return Number.isFinite(parsed) && parsed > 0 && parsed <= 8.64e15 ? parsed : null;
+}
+
+export function windowLabel(seconds: number): string {
+  if (seconds === 604800) return '1w';
+  if (seconds % 86400 === 0) return `${seconds / 86400}d`;
+  if (seconds % 3600 === 0) return `${seconds / 3600}h`;
+  if (seconds % 60 === 0) return `${seconds / 60}m`;
+  return `${seconds}s`;
+}
+
+// API-controlled labels may not inject terminal controls, ANSI, or newlines.
+export function safeLabel(value: string): string {
+  return value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '').slice(0, 64);
+}