@vibe-cafe/vibe-usage 0.10.34 → 0.11.0

package/README.md

@@ -51,11 +51,24 @@ npx @vibe-cafe/vibe-usage reset --local  # Delete this host's data only and re-u
 npx @vibe-cafe/vibe-usage skill         # Install skill for AI coding assistants
 npx @vibe-cafe/vibe-usage skill --remove  # Remove installed skills
 npx @vibe-cafe/vibe-usage status       # Config, detected tools, and what each tool has uploaded so far
+npx @vibe-cafe/vibe-usage quota discover --json  # Detect subscription-quota products locally
+npx @vibe-cafe/vibe-usage quota fetch --product kimi-code --product zcode --product grok --json  # Fetch only selected quotas
 npx @vibe-cafe/vibe-usage help --all   # Full help (plain `help` shows the short version)
 ```
 
 </details>
 
+## Subscription Quotas
+
+The versioned `quota` JSON contract is designed for local desktop clients. `discover` only checks ordinary app, config-directory, and executable presence signals: it does not open credentials or use the network. `fetch` invokes only products explicitly named with `--product`, and one provider failure does not prevent results for the others.
+
+- **Kimi Code** reads the official Kimi CLI OAuth file (`$KIMI_SHARE_DIR/credentials/kimi-code.json`, otherwise `~/.kimi/credentials/kimi-code.json`) and calls `https://api.kimi.com/coding/v1/usages`. When the short-lived access token is close to expiry, it uses Kimi's standard OAuth refresh flow and atomically rotates the official credential with owner-only permissions. Refreshes are serialized across Vibe Usage processes and re-check the file before writing so a concurrent Kimi CLI refresh wins safely.
+- **ZCode / GLM Coding Plan** accepts only a caller-supplied regional key: `BIGMODEL_API_KEY` calls the domestic `https://open.bigmodel.cn/api/monitor/usage/quota/limit`, while the existing `Z_AI_API_KEY` keeps using `https://api.z.ai/api/monitor/usage/quota/limit`. If both are present, the explicitly named BigModel key wins. It does not read ZCode's private OAuth state.
+- **Grok** reads at most the final 2 MiB of the official CLI's ordinary `$GROK_HOME/logs/unified.jsonl` (default `~/.grok/logs/unified.jsonl`). It accepts only the structured `billing: fetched credits config` event and projects the current utilization, period bounds, subscription tier, and event timestamp. It performs no network request, reads no credentials, and never returns or retains other log fields.
+- **Cursor** is detected independently but remains non-fetchable until an official or stable quota protocol is available. Quota monitoring does not read Cursor's login token/database, browser cookies, another app's Keychain, network traffic, or UI.
+
+Quota results are never uploaded or added to incremental sync state. Credential-backed providers may use the disposable cache at `~/.vibe-usage/quota-cache.json`; it contains normalized meters only, is scoped to a one-way hash of the active credential, rejects expired windows, and has a seven-day hard expiry. Grok's local-log result is not cached. No credential is stored in that cache, logs, or command output; the only credential write is Kimi's standard token rotation back to Kimi's own credential file.
+
 ## Supported Tools
 
 | Tool | Data Location |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-cafe/vibe-usage",
-  "version": "0.10.34",
+  "version": "0.11.0",
   "description": "Track your AI coding tool token usage and sync to vibecafe.ai",
   "type": "module",
   "scripts": {

package/src/daemon-service.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { writeFileSync, readFileSync, unlinkSync, mkdirSync, existsSync } from 'node:fs';
-import { join, dirname, win32 as winPath } from 'node:path';
+import { join, win32 as winPath, posix as posixPath } from 'node:path';
 import { homedir, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { success, failure, warn, dim } from './output.js';
@@ -41,8 +41,9 @@ export function isNpxCachePath(binPath) {
  * falls back to pinning the path and warning, as before).
  */
 export function npxLauncher(nodePath, exists = existsSync, os = platform()) {
-  const nodeDir = dirname(nodePath);
-  const npxPath = join(nodeDir, os === 'win32' ? 'npx.cmd' : 'npx');
+  const paths = os === 'win32' ? winPath : posixPath;
+  const nodeDir = paths.dirname(nodePath);
+  const npxPath = paths.join(nodeDir, os === 'win32' ? 'npx.cmd' : 'npx');
   return exists(npxPath) ? { mode: 'npx', npxPath, nodeDir } : null;
 }
 

package/src/index.js

@@ -11,6 +11,7 @@ import {
 import { dim as dimText, failure, hint, smallHeader, warn } from './output.js';
 import { loadState } from './state.js';
 import { fetchAccount } from './api.js';
+import { COLLECTOR_VERSION } from './client-meta.js';
 
 function printSmallHeader() {
   console.log();
@@ -298,6 +299,8 @@ const FULL_HELP = `
     ${BARE} skill         Install skill for AI coding tools
     ${BARE} skill --remove  Remove installed skills
     ${BARE} status       Show config and detected tools
+    ${BARE} quota discover --json  Detect subscription-quota products locally
+    ${BARE} quota fetch --product <id> --json  Fetch only selected subscription quotas
     ${BARE} config show  Show full config as JSON
     ${BARE} config get <key>   Get a config value
     ${BARE} config set <key> <value>  Set a config value
@@ -307,6 +310,7 @@ const FULL_HELP = `
     ${BARE} config roots  Show added data roots as JSON
     ${BARE} help         Show the short help
     ${BARE} help --all   Show this full list
+    ${BARE} --version    Print the installed CLI version
 `;
 
 export async function run(rawArgs) {
@@ -358,6 +362,16 @@ export async function run(rawArgs) {
       await runSummary(args.slice(1));
       break;
     }
+    case 'quota': {
+      const { runQuota } = await import('./quotas/index.js');
+      try {
+        await runQuota(args.slice(1));
+      } catch (error) {
+        console.error(error?.message || String(error));
+        process.exitCode = 1;
+      }
+      break;
+    }
     case 'reset': {
       printSmallHeader();
       if (args.includes('--host')) hint('reset --host 已改名 reset --local，旧写法仍可用');
@@ -399,6 +413,11 @@ export async function run(rawArgs) {
       handleConfig(args.slice(1));
       break;
     }
+    case '--version':
+    case '-v': {
+      console.log(COLLECTOR_VERSION);
+      break;
+    }
     case 'status': {
       await showStatus();
       break;

package/src/parsers/claude-code.js

@@ -384,6 +384,19 @@ export async function parse({ extraRoots = [] } = {}) {
   const roots = getClaudeRoots({
     onWarning: (message) => addWarning(ctx, message),
     extraRoots,
+  }).filter((root) => {
+    // On Windows readdir("file/projects") can return ENOENT rather than
+    // ENOTDIR. Validate the root first so that an invalid store cannot look
+    // like a successful empty scan and allow incremental state to be pruned.
+    try {
+      if (statSync(root).isDirectory()) return true;
+      addWarning(ctx, `Claude Code: cannot read directory ${root}: not a directory`);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') {
+        addWarning(ctx, `Claude Code: cannot read directory ${root}: ${err.message}`);
+      }
+    }
+    return false;
   });
   const projectGroups = collectCandidates(roots, 'projects', ctx);
   const projectSessionIds = new Set();

package/src/quotas/cache.js

@@ -0,0 +1,91 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { normalizeMeter, quotaResult } from './schema.js';
+
+const CACHE_VERSION = 1;
+const MAX_CACHE_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+function cachePath(environment = process.env) {
+  const root = environment.VIBE_USAGE_QUOTA_CACHE_DIR?.trim()
+    || join(homedir(), '.vibe-usage');
+  return join(root, 'quota-cache.json');
+}
+
+function loadDocument(environment) {
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath(environment), 'utf8'));
+    if (!isRecord(parsed) || parsed.version !== CACHE_VERSION || !isRecord(parsed.products)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function attachCacheScope(result, secret) {
+  const scope = createHash('sha256').update(`${result.id}\0${secret}`).digest('hex');
+  Object.defineProperty(result, 'cacheScope', { value: scope, enumerable: false });
+  return result;
+}
+
+export function loadCachedQuota(id, scope, environment = process.env, now = new Date()) {
+  if (!scope) return null;
+  const raw = loadDocument(environment)?.products?.[id];
+  if (!raw || raw.scope !== scope || raw.status !== 'ok' || !Array.isArray(raw.meters)) return null;
+  try {
+    const dataAsOf = new Date(raw.dataAsOf || raw.fetchedAt);
+    if (Number.isNaN(dataAsOf.getTime()) || now.getTime() - dataAsOf.getTime() > MAX_CACHE_AGE_MS) {
+      return null;
+    }
+    const meters = raw.meters.map(normalizeMeter).filter(meter => {
+      if (meter.resetsAt) return new Date(meter.resetsAt) > now;
+      if (meter.windowSeconds) {
+        return dataAsOf.getTime() + meter.windowSeconds * 1000 > now.getTime();
+      }
+      return true;
+    });
+    if (!meters.length) return null;
+    return quotaResult({
+      ...raw,
+      id,
+      status: 'ok',
+      meters,
+      source: 'cache',
+      fetchedAt: raw.fetchedAt,
+      dataAsOf: raw.dataAsOf || raw.fetchedAt,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function saveCachedQuota(result, scope, environment = process.env) {
+  if (result?.status !== 'ok' || !scope) return;
+  try {
+    // All disposable-cache work belongs inside the failure boundary, including
+    // path resolution and updating a document recovered from disk.
+    const path = cachePath(environment);
+    const document = loadDocument(environment) || { version: CACHE_VERSION, products: {} };
+    document.products[result.id] = {
+      id: result.id,
+      status: 'ok',
+      meters: result.meters,
+      planLabel: result.planLabel,
+      fetchedAt: result.fetchedAt,
+      dataAsOf: result.dataAsOf,
+      scope,
+    };
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(document)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, path);
+  } catch {
+    // The cache is disposable. A read-only home must not turn a successful
+    // provider response into a CLI failure.
+  }
+}

package/src/quotas/index.js

@@ -0,0 +1,35 @@
+import { discoverQuotaProducts, fetchQuotaProducts } from './registry.js';
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function parseFetchArguments(args) {
+  const products = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--json') continue;
+    if (argument !== '--product') fail(`Unknown quota fetch option: ${argument}`);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) fail('Option --product requires a value.');
+    products.push(value);
+    index += 1;
+  }
+  if (!products.length) fail('quota fetch requires at least one --product.');
+  return products;
+}
+
+export async function runQuota(args) {
+  const subcommand = args[0];
+  if (subcommand === 'discover') {
+    const unknown = args.slice(1).filter(argument => argument !== '--json');
+    if (unknown.length) fail(`Unknown quota discover option: ${unknown[0]}`);
+    console.log(JSON.stringify(discoverQuotaProducts()));
+    return;
+  }
+  if (subcommand === 'fetch') {
+    console.log(JSON.stringify(await fetchQuotaProducts(parseFetchArguments(args.slice(1)))));
+    return;
+  }
+  fail(`Unknown quota subcommand: ${subcommand || '(none)'}`);
+}

package/src/quotas/providers/grok.js

@@ -0,0 +1,151 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { quotaResult } from '../schema.js';
+
+const PRODUCT_ID = 'grok';
+const DEFAULT_MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+export function grokBillingLogPath(environment = process.env, home = homedir()) {
+  const configured = environment.GROK_HOME?.trim();
+  let root = configured || join(home, '.grok');
+  if (root === '~') root = home;
+  else if (root.startsWith('~/') || root.startsWith('~\\')) root = join(home, root.slice(2));
+  return join(root, 'logs', 'unified.jsonl');
+}
+
+function readLogTail(path, maxBytes = DEFAULT_MAX_LOG_BYTES) {
+  const descriptor = openSync(path, 'r');
+  try {
+    const size = fstatSync(descriptor).size;
+    const length = Math.min(size, maxBytes);
+    if (length <= 0) return '';
+    const buffer = Buffer.allocUnsafe(length);
+    const offset = size - length;
+    let total = 0;
+    while (total < length) {
+      const count = readSync(descriptor, buffer, total, length - total, offset + total);
+      if (count <= 0) break;
+      total += count;
+    }
+    let text = buffer.subarray(0, total).toString('utf8');
+    // A bounded tail may begin in the middle of a UTF-8 JSON line. Drop only
+    // that incomplete line; the CLI emits this billing snapshot repeatedly.
+    if (offset > 0) {
+      const newline = text.indexOf('\n');
+      text = newline < 0 ? '' : text.slice(newline + 1);
+    }
+    return text;
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function finiteNumber(value) {
+  const number = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function date(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+function periodLabel(type, seconds) {
+  if (type === 'USAGE_PERIOD_TYPE_DAILY') return '1d';
+  if (type === 'USAGE_PERIOD_TYPE_WEEKLY') return '7d';
+  if (type === 'USAGE_PERIOD_TYPE_MONTHLY') return 'Month';
+  const days = seconds / 86_400;
+  return Number.isInteger(days) && days > 0 ? `${days}d` : 'Credits';
+}
+
+/**
+ * Reads only Grok CLI's structured, non-secret billing status event. Other log
+ * messages are parsed only far enough to reject them and are never returned,
+ * cached, logged, or uploaded by Vibe Usage.
+ */
+export function parseGrokBillingLog(text, now = new Date()) {
+  if (typeof text !== 'string' || !text) return null;
+  const lines = text.split(/\r?\n/);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index].trim();
+    if (!line) continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event?.msg !== 'billing: fetched credits config') continue;
+    const config = event?.ctx?.config;
+    if (!config || typeof config !== 'object' || Array.isArray(config)) continue;
+    const utilization = finiteNumber(config.creditUsagePercent);
+    const dataAsOf = date(event.ts);
+    const startsAt = date(config.currentPeriod?.start || config.billingPeriodStart);
+    const resetsAt = date(config.currentPeriod?.end || config.billingPeriodEnd);
+    if (utilization === null || !dataAsOf || !startsAt || !resetsAt) continue;
+    const windowSeconds = (resetsAt.getTime() - startsAt.getTime()) / 1000;
+    if (windowSeconds <= 0) continue;
+    const planLabel = [event.ctx?.subscriptionTier, config.subscriptionTier]
+      .find(value => typeof value === 'string' && value.trim())?.trim();
+    return {
+      active: resetsAt > now,
+      dataAsOf,
+      meters: [{
+        id: 'subscription-credits',
+        label: periodLabel(config.currentPeriod?.type, windowSeconds),
+        utilization,
+        resetsAt: resetsAt.toISOString(),
+        windowSeconds,
+      }],
+      planLabel,
+    };
+  }
+  return null;
+}
+
+export function fetchGrokQuota({
+  environment = process.env,
+  home = homedir(),
+  now = new Date(),
+  maxLogBytes = DEFAULT_MAX_LOG_BYTES,
+} = {}) {
+  let parsed;
+  try {
+    parsed = parseGrokBillingLog(
+      readLogTail(grokBillingLogPath(environment, home), maxLogBytes),
+      now
+    );
+  } catch (error) {
+    const status = error?.code === 'ENOENT' ? 'no_data' : 'retryable_error';
+    return quotaResult({
+      id: PRODUCT_ID,
+      status,
+      message: status === 'no_data'
+        ? 'Grok billing status is not available yet'
+        : 'Grok billing status could not be read',
+      fetchedAt: now,
+      source: 'local',
+    });
+  }
+  if (!parsed || !parsed.active) {
+    return quotaResult({
+      id: PRODUCT_ID,
+      status: 'no_data',
+      message: 'Grok billing status is not available yet',
+      fetchedAt: now,
+      dataAsOf: parsed?.dataAsOf,
+      source: 'local',
+    });
+  }
+  return quotaResult({
+    id: PRODUCT_ID,
+    status: 'ok',
+    meters: parsed.meters,
+    planLabel: parsed.planLabel,
+    fetchedAt: now,
+    dataAsOf: parsed.dataAsOf,
+    source: 'local',
+  });
+}

package/src/quotas/providers/kimi-code.js

@@ -0,0 +1,504 @@
+import {
+  accessSync,
+  closeSync,
+  constants as fsConstants,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { attachCacheScope } from '../cache.js';
+import { quotaResult } from '../schema.js';
+
+const PRODUCT_ID = 'kimi-code';
+const DEFAULT_USAGE_URL = 'https://api.kimi.com/coding/v1/usages';
+const DEFAULT_OAUTH_HOST = 'https://auth.kimi.com';
+const KIMI_CODE_CLIENT_ID = '17e5f671-d194-4dfb-9706-5516cb48c098';
+const MIN_REFRESH_THRESHOLD_SECONDS = 300;
+const REFRESH_THRESHOLD_RATIO = 0.5;
+const RETRYABLE_REFRESH_STATUSES = new Set([429, 500, 502, 503, 504]);
+const REFRESH_LOCK_RETRIES = 50;
+const REFRESH_LOCK_RETRY_MS = 100;
+const REFRESH_LOCK_STALE_MS = 120_000;
+
+class RefreshUnauthorizedError extends Error {}
+class RefreshRetryableError extends Error {}
+class RefreshNonRetryableError extends Error {}
+class RefreshPersistenceError extends Error {}
+
+const sleep = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+function number(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function resetDate(data, now = new Date()) {
+  for (const key of ['reset_at', 'resetAt', 'reset_time', 'resetTime']) {
+    const value = data?.[key];
+    if (value === null || value === undefined || value === '') continue;
+    if (typeof value === 'number') {
+      const millis = value > 10_000_000_000 ? value : value * 1000;
+      if (Number.isFinite(millis)) return new Date(millis);
+    }
+    const millis = Date.parse(String(value));
+    if (!Number.isNaN(millis)) return new Date(millis);
+  }
+  const seconds = number(data?.reset_in ?? data?.resetIn ?? data?.ttl);
+  return seconds !== null && seconds > 0 ? new Date(now.getTime() + seconds * 1000) : null;
+}
+
+function durationSeconds(item, detail) {
+  const window = item?.window && typeof item.window === 'object' ? item.window : {};
+  const duration = number(window.duration ?? item?.duration ?? detail?.duration);
+  if (duration === null || duration <= 0) return null;
+  const unit = String(window.timeUnit ?? item?.timeUnit ?? detail?.timeUnit ?? '').toUpperCase();
+  if (unit.includes('MINUTE')) return duration * 60;
+  if (unit.includes('HOUR')) return duration * 3600;
+  if (unit.includes('DAY')) return duration * 86400;
+  if (unit.includes('WEEK')) return duration * 7 * 86400;
+  return duration;
+}
+
+function labelFor(item, detail, index) {
+  for (const key of ['name', 'title', 'scope']) {
+    const value = item?.[key] ?? detail?.[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  const seconds = durationSeconds(item, detail);
+  if (seconds && seconds % (7 * 86400) === 0) return `${seconds / (7 * 86400)}w`;
+  if (seconds && seconds % 86400 === 0) return `${seconds / 86400}d`;
+  if (seconds && seconds % 3600 === 0) return `${seconds / 3600}h`;
+  if (seconds && seconds % 60 === 0) return `${seconds / 60}m`;
+  return `Quota ${index + 1}`;
+}
+
+function meterFrom(data, item, index, defaultLabel, now) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return null;
+  const limit = number(data.limit);
+  let used = number(data.used);
+  if (used === null && limit !== null) {
+    const remaining = number(data.remaining);
+    if (remaining !== null) used = limit - remaining;
+  }
+  if (limit === null || limit <= 0 || used === null) return null;
+  const label = String(data.name || data.title || defaultLabel).trim();
+  const rawIdentifier = String(data.id || item?.id || label)
+    .trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  const meter = {
+    id: `${index}-${rawIdentifier || 'quota'}`,
+    label,
+    utilization: Math.max(0, Math.min(100, used / limit * 100)),
+  };
+  const resetsAt = resetDate(data, now) || resetDate(item, now);
+  if (resetsAt) meter.resetsAt = resetsAt.toISOString();
+  const seconds = durationSeconds(item, data);
+  if (seconds) meter.windowSeconds = seconds;
+  return meter;
+}
+
+export function parseKimiUsage(payload, now = new Date()) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Kimi usage response is not an object');
+  }
+  const meters = [];
+  if (payload.usage && typeof payload.usage === 'object' && !Array.isArray(payload.usage)) {
+    const summary = meterFrom(payload.usage, payload.usage, 0, 'Weekly', now);
+    if (summary) meters.push(summary);
+  }
+  if (Array.isArray(payload.limits)) {
+    const offset = meters.length;
+    for (const [index, item] of payload.limits.entries()) {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+      const detail = item.detail && typeof item.detail === 'object' && !Array.isArray(item.detail)
+        ? item.detail : item;
+      const meter = meterFrom(detail, item, index + offset,
+        labelFor(item, detail, index), now);
+      if (meter) meters.push(meter);
+    }
+  }
+  const seen = new Set();
+  return meters.filter(meter => {
+    const key = `${meter.label}\0${meter.windowSeconds || ''}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function kimiCredentialPath(environment = process.env, home = homedir()) {
+  const shareDirectory = environment.KIMI_SHARE_DIR?.trim() || join(home, '.kimi');
+  return join(shareDirectory, 'credentials', 'kimi-code.json');
+}
+
+function readCredentials(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function accessToken(credentials) {
+  return typeof credentials?.access_token === 'string' ? credentials.access_token.trim() : '';
+}
+
+function refreshToken(credentials) {
+  return typeof credentials?.refresh_token === 'string' ? credentials.refresh_token.trim() : '';
+}
+
+function refreshThreshold(credentials) {
+  const expiresIn = number(credentials?.expires_in);
+  return Math.max(
+    MIN_REFRESH_THRESHOLD_SECONDS,
+    expiresIn !== null && expiresIn > 0 ? expiresIn * REFRESH_THRESHOLD_RATIO : 0,
+  );
+}
+
+function shouldRefresh(credentials, now, force = false) {
+  if (force) return true;
+  if (!accessToken(credentials)) return true;
+  const expiresAt = number(credentials?.expires_at);
+  if (expiresAt === null || expiresAt <= 0) return false;
+  return expiresAt * 1000 - now.getTime() <= refreshThreshold(credentials) * 1000;
+}
+
+function credentialsWereRotated(latest, previous) {
+  const latestRefresh = refreshToken(latest);
+  const previousRefresh = refreshToken(previous);
+  if (latestRefresh && latestRefresh !== previousRefresh) return true;
+  return Boolean(accessToken(latest) && accessToken(latest) !== accessToken(previous));
+}
+
+function atomicWriteCredentials(path, credentials) {
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  let descriptor = -1;
+  try {
+    descriptor = openSync(temporary, 'wx', 0o600);
+    writeFileSync(descriptor, `${JSON.stringify(credentials)}\n`, 'utf8');
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = -1;
+    renameSync(temporary, path);
+  } catch (error) {
+    if (descriptor >= 0) {
+      try { closeSync(descriptor); } catch {}
+    }
+    try { unlinkSync(temporary); } catch {}
+    throw error;
+  }
+}
+
+function assertCredentialStoreWritable(path) {
+  // Check this before rotating a refresh token. A successful refresh can
+  // invalidate the old token, so discovering a read-only credential store only
+  // after the network request could log the user out of Kimi Code.
+  try {
+    accessSync(dirname(path), fsConstants.W_OK);
+  } catch {
+    throw new RefreshPersistenceError();
+  }
+}
+
+function lockPathFor(credentialsPath) {
+  return `${credentialsPath}.vibe-usage-refresh-lock`;
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function removeAbandonedLock(path, nowMs) {
+  try {
+    let owner = null;
+    try { owner = JSON.parse(readFileSync(join(path, 'owner.json'), 'utf8')); } catch {}
+    const isOrphan = owner?.pid && !processIsAlive(Number(owner.pid));
+    const isStale = nowMs - statSync(path).mtimeMs > REFRESH_LOCK_STALE_MS;
+    if (!isOrphan && !isStale) return false;
+    try { unlinkSync(join(path, 'owner.json')); } catch {}
+    rmdirSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function acquireRefreshLock(credentialsPath, sleepImpl) {
+  const path = lockPathFor(credentialsPath);
+  for (let attempt = 0; attempt <= REFRESH_LOCK_RETRIES; attempt += 1) {
+    try {
+      mkdirSync(path, { mode: 0o700 });
+      try {
+        writeFileSync(join(path, 'owner.json'), JSON.stringify({ pid: process.pid }), {
+          encoding: 'utf8',
+          mode: 0o600,
+        });
+      } catch {
+        try { unlinkSync(join(path, 'owner.json')); } catch {}
+        try { rmdirSync(path); } catch {}
+        throw new RefreshPersistenceError();
+      }
+      return () => {
+        try { unlinkSync(join(path, 'owner.json')); } catch {}
+        try { rmdirSync(path); } catch {}
+      };
+    } catch (error) {
+      if (error instanceof RefreshPersistenceError) throw error;
+      if (error?.code !== 'EEXIST') throw new RefreshPersistenceError();
+      if (removeAbandonedLock(path, Date.now())) continue;
+      if (attempt < REFRESH_LOCK_RETRIES) await sleepImpl(REFRESH_LOCK_RETRY_MS);
+    }
+  }
+  throw new RefreshRetryableError();
+}
+
+function refreshedCredentials(payload, previous, now) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new RefreshRetryableError();
+  }
+  const nextAccessToken = typeof payload.access_token === 'string' ? payload.access_token.trim() : '';
+  const nextRefreshToken = typeof payload.refresh_token === 'string'
+    ? payload.refresh_token.trim() : refreshToken(previous);
+  const expiresIn = number(payload.expires_in);
+  if (!nextAccessToken || !nextRefreshToken || expiresIn === null || expiresIn <= 0) {
+    throw new RefreshRetryableError();
+  }
+  return {
+    access_token: nextAccessToken,
+    refresh_token: nextRefreshToken,
+    expires_at: now.getTime() / 1000 + expiresIn,
+    scope: typeof payload.scope === 'string' ? payload.scope : String(previous.scope || ''),
+    token_type: typeof payload.token_type === 'string'
+      ? payload.token_type : String(previous.token_type || 'Bearer'),
+    expires_in: expiresIn,
+  };
+}
+
+async function requestTokenRefresh({
+  credentials,
+  fetchImpl,
+  oauthURL,
+  now,
+  timeoutMs,
+  sleepImpl,
+}) {
+  let lastError;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const response = await fetchImpl(oauthURL, {
+        method: 'POST',
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: new URLSearchParams({
+          client_id: KIMI_CODE_CLIENT_ID,
+          grant_type: 'refresh_token',
+          refresh_token: refreshToken(credentials),
+        }),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      let payload = {};
+      try { payload = await response.json(); } catch {}
+      if (response.status === 401 || response.status === 403) {
+        throw new RefreshUnauthorizedError();
+      }
+      if (!response.ok) {
+        if (payload?.error === 'invalid_grant') throw new RefreshUnauthorizedError();
+        if (!RETRYABLE_REFRESH_STATUSES.has(response.status)) throw new RefreshNonRetryableError();
+        lastError = new RefreshRetryableError();
+      } else {
+        return refreshedCredentials(payload, credentials, now);
+      }
+    } catch (error) {
+      if (error instanceof RefreshUnauthorizedError) throw error;
+      if (error instanceof RefreshNonRetryableError) throw new RefreshRetryableError();
+      lastError = error;
+    }
+    if (attempt < 2) await sleepImpl(2 ** attempt * 1000);
+  }
+  throw new RefreshRetryableError(undefined, { cause: lastError });
+}
+
+async function ensureFreshCredentials({
+  credentialsPath,
+  credentials,
+  fetchImpl,
+  oauthURL,
+  now,
+  timeoutMs,
+  sleepImpl,
+  force = false,
+}) {
+  if (!shouldRefresh(credentials, now, force)) return credentials;
+  if (!refreshToken(credentials)) return credentials;
+
+  let release;
+  try {
+    release = await acquireRefreshLock(credentialsPath, sleepImpl);
+    const latest = readCredentials(credentialsPath) || credentials;
+    if (credentialsWereRotated(latest, credentials)) return latest;
+    if (!shouldRefresh(latest, now, force)) return latest;
+    assertCredentialStoreWritable(credentialsPath);
+
+    let refreshed;
+    try {
+      refreshed = await requestTokenRefresh({
+        credentials: latest,
+        fetchImpl,
+        oauthURL,
+        now,
+        timeoutMs,
+        sleepImpl,
+      });
+    } catch (error) {
+      if (error instanceof RefreshUnauthorizedError) {
+        // A Kimi process may have rotated and persisted the token while our
+        // request was in flight. Re-read once before reporting a stale refresh
+        // token as rejected.
+        await sleepImpl(1000);
+        const concurrent = readCredentials(credentialsPath);
+        if (concurrent && credentialsWereRotated(concurrent, latest)) return concurrent;
+      }
+      throw error;
+    }
+
+    const concurrent = readCredentials(credentialsPath);
+    if (concurrent && credentialsWereRotated(concurrent, latest)) return concurrent;
+    try {
+      atomicWriteCredentials(credentialsPath, refreshed);
+    } catch {
+      throw new RefreshPersistenceError();
+    }
+    return refreshed;
+  } finally {
+    release?.();
+  }
+}
+
+export async function fetchKimiCodeQuota({
+  environment = process.env,
+  home = homedir(),
+  fetchImpl = globalThis.fetch,
+  usageURL = DEFAULT_USAGE_URL,
+  oauthURL = `${(environment.KIMI_CODE_OAUTH_HOST || environment.KIMI_OAUTH_HOST
+    || DEFAULT_OAUTH_HOST).replace(/\/$/, '')}/api/oauth/token`,
+  now = new Date(),
+  timeoutMs = 10_000,
+  sleepImpl = sleep,
+} = {}) {
+  const credentialsPath = kimiCredentialPath(environment, home);
+  let credentials = readCredentials(credentialsPath);
+  if (!credentials) {
+    return quotaResult({ id: PRODUCT_ID, status: 'missing_credentials',
+      message: 'Kimi Code is not logged in', fetchedAt: now });
+  }
+
+  try {
+    credentials = await ensureFreshCredentials({
+      credentialsPath,
+      credentials,
+      fetchImpl,
+      oauthURL,
+      now,
+      timeoutMs,
+      sleepImpl,
+    });
+  } catch (error) {
+    const token = accessToken(credentials);
+    if (error instanceof RefreshUnauthorizedError) {
+      return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'unauthorized',
+        message: 'Kimi Code login refresh was rejected', fetchedAt: now }), token);
+    }
+    const message = error instanceof RefreshPersistenceError
+      ? 'Kimi Code could not securely save the refreshed login'
+      : 'Kimi Code login refresh failed';
+    return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'retryable_error',
+      message, fetchedAt: now }), token);
+  }
+
+  let token = accessToken(credentials);
+  if (!token) {
+    return quotaResult({ id: PRODUCT_ID, status: 'missing_credentials',
+      message: 'Kimi Code access token is missing', fetchedAt: now });
+  }
+  const expiresAt = number(credentials.expires_at);
+  if (expiresAt !== null && expiresAt > 0 && expiresAt * 1000 <= now.getTime()) {
+    return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'expired_credentials',
+      message: 'Kimi Code access token is expired and no refresh token is available',
+      fetchedAt: now }), token);
+  }
+
+  try {
+    let response = await fetchImpl(usageURL, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 401 && refreshToken(credentials)) {
+      try {
+        credentials = await ensureFreshCredentials({
+          credentialsPath,
+          credentials,
+          fetchImpl,
+          oauthURL,
+          now,
+          timeoutMs,
+          sleepImpl,
+          force: true,
+        });
+        token = accessToken(credentials);
+        response = await fetchImpl(usageURL, {
+          method: 'GET',
+          headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch (error) {
+        if (error instanceof RefreshUnauthorizedError) {
+          return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'unauthorized',
+            message: 'Kimi Code login refresh was rejected', fetchedAt: now }), token);
+        }
+        const message = error instanceof RefreshPersistenceError
+          ? 'Kimi Code could not securely save the refreshed login'
+          : 'Kimi Code login refresh failed';
+        return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'retryable_error',
+          message, fetchedAt: now }), token);
+      }
+    }
+    if (response.status === 401 || response.status === 403) {
+      return quotaResult({ id: PRODUCT_ID, status: 'unauthorized',
+        message: 'Kimi Code rejected the saved login', fetchedAt: now });
+    }
+    if (!response.ok) {
+      return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'retryable_error',
+        message: `Kimi usage API returned HTTP ${response.status}`, fetchedAt: now }), token);
+    }
+    const meters = parseKimiUsage(await response.json(), now);
+    return attachCacheScope(quotaResult({
+      id: PRODUCT_ID,
+      status: meters.length ? 'ok' : 'no_data',
+      meters,
+      fetchedAt: now,
+      dataAsOf: now,
+    }), token);
+  } catch (error) {
+    return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'retryable_error',
+      message: error?.name === 'TimeoutError' ? 'Kimi usage request timed out' : 'Kimi usage request failed',
+      fetchedAt: now }), token);
+  }
+}

package/src/quotas/providers/zai.js

@@ -0,0 +1,143 @@
+import { attachCacheScope } from '../cache.js';
+import { quotaResult } from '../schema.js';
+
+const PRODUCT_ID = 'zcode';
+const BIGMODEL_USAGE_URL = 'https://open.bigmodel.cn/api/monitor/usage/quota/limit';
+const ZAI_USAGE_URL = 'https://api.z.ai/api/monitor/usage/quota/limit';
+
+function credential(environment) {
+  const bigModelToken = environment.BIGMODEL_API_KEY?.trim();
+  if (bigModelToken) {
+    return {
+      token: bigModelToken,
+      region: 'bigmodel',
+      providerName: 'BigModel',
+      usageURL: BIGMODEL_USAGE_URL,
+    };
+  }
+  const zaiToken = environment.Z_AI_API_KEY?.trim();
+  if (zaiToken) {
+    return {
+      token: zaiToken,
+      region: 'zai',
+      providerName: 'Z.ai',
+      usageURL: ZAI_USAGE_URL,
+    };
+  }
+  return null;
+}
+
+function integer(value) {
+  return Number.isInteger(value) ? value : null;
+}
+
+function parseLimit(raw, now, index) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!['TOKENS_LIMIT', 'CREDIT_LIMIT', 'TIME_LIMIT'].includes(raw.type)) return null;
+  const percentage = integer(raw.percentage);
+  const unit = integer(raw.unit);
+  const count = integer(raw.number);
+  if (percentage === null || unit === null || count === null) return null;
+
+  const usage = integer(raw.usage);
+  const current = integer(raw.currentValue);
+  const remaining = integer(raw.remaining);
+  let utilization = percentage;
+  if (usage !== null && usage > 0) {
+    let used = current;
+    if (remaining !== null) used = Math.max(usage - remaining, current ?? usage - remaining);
+    if (used !== null) utilization = used * 100 / usage;
+  }
+  utilization = Math.max(0, Math.min(100, utilization));
+
+  const minutesPerUnit = { 1: 1440, 3: 60, 5: 1, 6: 10080 };
+  let windowMinutes = count > 0 ? count * (minutesPerUnit[unit] || 0) : 0;
+  if (raw.type === 'TIME_LIMIT' && unit === 5 && count === 1) {
+    // The API uses this marker for the monthly MCP pool.
+    windowMinutes = 30 * 24 * 60;
+  }
+  const isFiveHour = raw.type !== 'TIME_LIMIT' && windowMinutes === 300;
+  const resetMillis = integer(raw.nextResetTime);
+  const plausibleReset = resetMillis !== null
+    && (!isFiveHour || resetMillis <= now.getTime() + (5 * 3600 + 60) * 1000);
+  const typeName = raw.type === 'TIME_LIMIT'
+    ? 'MCP'
+    : raw.type === 'CREDIT_LIMIT' ? 'Credits' : 'Tokens';
+  let label = typeName;
+  if (raw.type !== 'TIME_LIMIT' && windowMinutes === 300) label = '5h';
+  else if (raw.type !== 'TIME_LIMIT' && windowMinutes === 10080) label = '7d';
+  else if (raw.type !== 'TIME_LIMIT' && windowMinutes && windowMinutes % 1440 === 0) {
+    label = `${windowMinutes / 1440}d`;
+  }
+  const meter = {
+    id: `${index}-${raw.type.toLowerCase()}-${unit}-${count}`,
+    label,
+    utilization,
+  };
+  if (windowMinutes > 0) meter.windowSeconds = windowMinutes * 60;
+  if (plausibleReset) meter.resetsAt = new Date(resetMillis).toISOString();
+  return { meter, windowMinutes, type: raw.type };
+}
+
+export function parseZaiQuota(payload, now = new Date()) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+      || payload.success !== true || payload.code !== 200
+      || !payload.data || typeof payload.data !== 'object'
+      || !Array.isArray(payload.data.limits)) {
+    throw new Error('Invalid Z.ai quota response');
+  }
+  const parsed = payload.data.limits.map((raw, index) => parseLimit(raw, now, index)).filter(Boolean);
+  const planLimits = parsed
+    .filter(item => item.type === 'TOKENS_LIMIT' || item.type === 'CREDIT_LIMIT')
+    .sort((a, b) => (a.windowMinutes || Number.MAX_SAFE_INTEGER)
+      - (b.windowMinutes || Number.MAX_SAFE_INTEGER));
+  const mcp = parsed.filter(item => item.type === 'TIME_LIMIT').pop();
+  const ordered = [...planLimits];
+  if (mcp) ordered.push(mcp);
+  const planLabel = ['planName', 'plan', 'plan_type', 'packageName', 'level']
+    .map(key => payload.data[key])
+    .find(value => typeof value === 'string' && value.trim());
+  return { meters: ordered.map(item => item.meter), planLabel: planLabel?.trim() };
+}
+
+export async function fetchZaiQuota({
+  environment = process.env,
+  fetchImpl = globalThis.fetch,
+  usageURL,
+  now = new Date(),
+  timeoutMs = 10_000,
+} = {}) {
+  const selected = credential(environment);
+  if (!selected) {
+    return quotaResult({ id: PRODUCT_ID, status: 'missing_credentials',
+      message: 'ZCode API key is not configured', fetchedAt: now });
+  }
+  const { token, region, providerName } = selected;
+  const endpoint = usageURL || selected.usageURL;
+  const cacheCredential = `${region}:${token}`;
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 401 || response.status === 403) {
+      return quotaResult({ id: PRODUCT_ID, status: 'unauthorized',
+        message: `${providerName} rejected the API key`, fetchedAt: now });
+    }
+    if (!response.ok) {
+      return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'retryable_error',
+        message: `${providerName} quota API returned HTTP ${response.status}`, fetchedAt: now }),
+      cacheCredential);
+    }
+    const { meters, planLabel } = parseZaiQuota(await response.json(), now);
+    return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: meters.length ? 'ok' : 'no_data',
+      meters, planLabel, fetchedAt: now, dataAsOf: now }), cacheCredential);
+  } catch (error) {
+    return attachCacheScope(quotaResult({ id: PRODUCT_ID, status: 'retryable_error',
+      message: error?.name === 'TimeoutError'
+        ? `${providerName} quota request timed out`
+        : `${providerName} quota request failed`,
+      fetchedAt: now }), cacheCredential);
+  }
+}

package/src/quotas/registry.js

@@ -0,0 +1,114 @@
+import { accessSync, constants, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { loadCachedQuota, saveCachedQuota } from './cache.js';
+import { fetchGrokQuota } from './providers/grok.js';
+import { fetchKimiCodeQuota } from './providers/kimi-code.js';
+import { fetchZaiQuota } from './providers/zai.js';
+import { FETCHABLE_QUOTA_PRODUCT_IDS, quotaEnvelope, quotaResult } from './schema.js';
+
+const providers = new Map([
+  ['kimi-code', fetchKimiCodeQuota],
+  ['zcode', fetchZaiQuota],
+  ['grok', fetchGrokQuota],
+]);
+
+function executableExists(name, environment, platform) {
+  const pathDelimiter = platform === 'win32' ? ';' : delimiter;
+  const candidateNames = [name];
+  if (platform === 'win32') {
+    const extensions = (environment.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+      .split(';')
+      .map(value => value.trim())
+      .filter(Boolean)
+      .map(value => value.startsWith('.') ? value : `.${value}`);
+    for (const extension of extensions) {
+      candidateNames.push(`${name}${extension}`, `${name}${extension.toLowerCase()}`);
+    }
+  }
+
+  return (environment.PATH || '').split(pathDelimiter).filter(Boolean).some(directory => (
+    candidateNames.some(candidate => {
+      const path = join(directory, candidate);
+      try {
+        // Windows does not expose POSIX execute bits; file presence plus a
+        // PATHEXT executable suffix is its ordinary command-discovery rule.
+        accessSync(path, platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    })
+  ));
+}
+
+export function discoverQuotaProducts({
+  environment = process.env,
+  home = homedir(),
+  platform = process.platform,
+} = {}) {
+  const applications = platform === 'darwin'
+    ? ['/Applications', join(home, 'Applications')] : [];
+  const existsAny = paths => paths.some(path => existsSync(path));
+  const configuredGrokHome = environment.GROK_HOME?.trim();
+  const grokHome = configuredGrokHome
+    ? configuredGrokHome.replace(/^~(?=$|[\\/])/, home)
+    : join(home, '.grok');
+  return quotaEnvelope([
+    {
+      id: 'kimi-code',
+      detected: existsAny([join(home, '.kimi'), join(home, '.kimi-code')])
+        || executableExists('kimi', environment, platform),
+      fetchable: true,
+    },
+    {
+      id: 'zcode',
+      detected: existsAny([join(home, '.zcode'), join(home, '.config', 'zcode'),
+        ...applications.map(path => join(path, 'ZCode.app'))])
+        || executableExists('zcode', environment, platform),
+      fetchable: true,
+    },
+    {
+      id: 'grok',
+      detected: existsAny([grokHome]) || executableExists('grok', environment, platform),
+      fetchable: true,
+    },
+    {
+      id: 'cursor',
+      detected: existsAny([join(home, '.cursor'),
+        ...applications.map(path => join(path, 'Cursor.app'))])
+        || executableExists('cursor', environment, platform),
+      fetchable: false,
+    },
+  ]);
+}
+
+export async function fetchQuotaProducts(ids, options = {}) {
+  const unique = [...new Set(ids)];
+  const invalid = unique.filter(id => !FETCHABLE_QUOTA_PRODUCT_IDS.includes(id));
+  if (invalid.length) throw new Error(`Unsupported quota product: ${invalid.join(', ')}`);
+
+  const fetched = await Promise.all(unique.map(async id => {
+    try {
+      return await providers.get(id)(options);
+    } catch {
+      return quotaResult({ id, status: 'retryable_error', message: 'Provider failed unexpectedly' });
+    }
+  }));
+  const results = fetched.map(result => {
+    if (result.status === 'ok') {
+      saveCachedQuota(result, result.cacheScope, options.environment);
+      return result;
+    }
+    if (result.status === 'retryable_error') {
+      return loadCachedQuota(
+        result.id,
+        result.cacheScope,
+        options.environment,
+        options.now || new Date()
+      ) || result;
+    }
+    return result;
+  });
+  return quotaEnvelope(results);
+}

package/src/quotas/schema.js

@@ -0,0 +1,94 @@
+export const QUOTA_SCHEMA_VERSION = 1;
+
+export const QUOTA_PRODUCT_IDS = Object.freeze([
+  'kimi-code',
+  'zcode',
+  'grok',
+  'cursor',
+]);
+
+export const FETCHABLE_QUOTA_PRODUCT_IDS = Object.freeze([
+  'kimi-code',
+  'zcode',
+  'grok',
+]);
+
+const FETCH_STATUSES = new Set([
+  'ok',
+  'no_data',
+  'missing_credentials',
+  'expired_credentials',
+  'unauthorized',
+  'retryable_error',
+  'unsupported',
+]);
+
+function finiteNumber(value, name) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new TypeError(`${name} must be a finite number`);
+  }
+  return value;
+}
+
+function optionalISODate(value, name) {
+  if (value === undefined || value === null) return undefined;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError(`${name} must be an ISO date string`);
+  }
+  return date.toISOString();
+}
+
+export function normalizeMeter(raw, index = 0) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new TypeError(`meters[${index}] must be an object`);
+  }
+  const id = String(raw.id || '').trim();
+  const label = String(raw.label || '').trim();
+  if (!id || !label) throw new TypeError(`meters[${index}] needs id and label`);
+
+  const utilization = Math.max(0, Math.min(100,
+    finiteNumber(raw.utilization, `meters[${index}].utilization`)));
+  const meter = { id, label, utilization };
+  const resetsAt = optionalISODate(raw.resetsAt, `meters[${index}].resetsAt`);
+  if (resetsAt) meter.resetsAt = resetsAt;
+  if (raw.windowSeconds !== undefined && raw.windowSeconds !== null) {
+    const seconds = finiteNumber(raw.windowSeconds, `meters[${index}].windowSeconds`);
+    if (seconds > 0) meter.windowSeconds = seconds;
+  }
+  return meter;
+}
+
+export function quotaResult({
+  id,
+  status,
+  meters = [],
+  planLabel,
+  fetchedAt = new Date(),
+  dataAsOf = fetchedAt,
+  message,
+  source = 'live',
+}) {
+  if (!FETCHABLE_QUOTA_PRODUCT_IDS.includes(id)) {
+    throw new TypeError(`unsupported quota product: ${id}`);
+  }
+  if (!FETCH_STATUSES.has(status)) {
+    throw new TypeError(`invalid quota status: ${status}`);
+  }
+  const result = {
+    id,
+    status,
+    meters: meters.map(normalizeMeter),
+    fetchedAt: new Date(fetchedAt).toISOString(),
+    source,
+  };
+  const normalizedDataAsOf = optionalISODate(dataAsOf, 'dataAsOf');
+  if (normalizedDataAsOf) result.dataAsOf = normalizedDataAsOf;
+  if (typeof planLabel === 'string' && planLabel.trim()) result.planLabel = planLabel.trim();
+  if (typeof message === 'string' && message.trim()) result.message = message.trim();
+  return result;
+}
+
+export function quotaEnvelope(products) {
+  return { schemaVersion: QUOTA_SCHEMA_VERSION, products };
+}