@vibe-cafe/vibe-usage 0.10.33 → 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 |
@@ -89,6 +102,7 @@ npx @vibe-cafe/vibe-usage help --all   # Full help (plain `help` shows the short
 | Trae CLI | macOS: `~/Library/Caches/trae-cli/sessions/`; Windows: `%LOCALAPPDATA%/trae-cli/cache/sessions/`; Linux: `~/.cache/trae-cli/sessions/` (CLI telemetry only; Trae IDE/Trae Work chats are not supported). Token usage is summed per unique LLM call (`model.stream.eino`, plus `model.generate` failovers); nested duplicate spans that share a session `traceID` are not max-merged. `traces.jsonl` / `events.jsonl` are streamed line-by-line so a multi-hundred-MB events file cannot hit Node's string-length limit. |
 | Antigravity | Scans App 2.0 `~/.gemini/antigravity/conversations/`, `agy` CLI `~/.gemini/antigravity-cli/conversations/`, and standalone IDE `~/.gemini/antigravity-ide/conversations/`. `.db` stores, including the same paths below explicitly added alternate Homes, are parsed offline (tokens, model, project, sessions). When Gemini blobs omit `chatStartMetadata.createdAt` or `modelDisplayName`, timestamps fall back to `steps.metadata` and model names to `responseModel`. `.pb` history in the default stores requires the corresponding App/IDE language server to be running; when several servers are open, the parser tries the others for unreadable conversations. Unavailable legacy history produces a warning and preserves prior sync state. |
 | WorkBuddy | Current releases: `~/.workbuddy-ai/projects/**/*.jsonl`; legacy releases: `~/.workbuddy/projects/**/*.jsonl` (fixture/relocation override: `VIBE_USAGE_WORKBUDDY_DIRS`). Reads usage-bearing completed assistant and `function_call` records, using the routed model identifier exposed as `providerData.requestModelId`. Splits cache reads and reasoning from inclusive input/output totals, deduplicates copied record IDs, and extracts local session timing without uploading message content. |
+| CodeBuddy | Tencent's CodeBuddy Code CLI (`@tencent-ai/codebuddy-code`). Home is `$CODEBUDDY_CONFIG_DIR` or `~/.codebuddy` (fixture/relocation override: `VIBE_USAGE_CODEBUDDY_DIRS`); transcripts at `projects/<compressed-cwd>/<sessionId>.jsonl`, including nested subagent directories. Only the API-message records' `message.usage` is read: `input_tokens` + `cache_creation_input_tokens` fold into input (the store writes no per-TTL breakdown), `cache_read_input_tokens` stays separate, `output_tokens` is the full completion. Retries and copies dedupe onto one logical call using `message.id`, `providerData.messageId`, or the record id (the CLI leaves `message.id` empty on some builds; `conversationRequestId` is a turn id, never a dedup key). The model comes from `message.model` and falls back to `providerData.requestModelId`/`model`, because successful calls can write `message.model: null`; routing-tier labels are namespaced (`codebuddy-auto`) so they can never match another vendor's price. Prompt text, thinking signatures, and tool payloads are never read. |
 | ZCode | `~/.zcode/cli/db/db.sqlite` (SQLite; reads the `message` table for per-message tokens, model, and project `cwd`/`root`, joined to `session.directory`; fixture/relocation override: `VIBE_USAGE_ZCODE_DB`) |
 | Qoder | International edition (qoder.com). IDE store `~/Library/Application Support/Qoder/SharedClientCache/cache/db/local.db` (Windows `%APPDATA%\Qoder`, Linux `~/.config/Qoder`; honors `QODER_HOME`, fixture override `VIBE_USAGE_QODER_DB`) gives real tokens from `chat_message.token_info` (prompt includes cached; split out) with `model_key` usually a routing tier, reported as `qoder-auto` / `qoder-ultimate` / … so it never collides with a priced model id; message content is never selected, and lock/schema failures fall back to a snapshot or `skipped`. CLI + desktop app transcripts `~/.qoder/projects/**/*.jsonl` (honors `QODER_CONFIG_DIR`, fixture override `VIBE_USAGE_QODER_PROJECTS`; sub-agents under `<session>/subagents/`) are credit-billed with every token field at 0, so they contribute sessions only — credits are account funding and are not collected |
 | Qoder CN | China edition (qoder.com.cn, separate account). Same two shapes under `~/Library/Application Support/QoderCN/SharedClientCache/cache/db/local.db` (`QODER_CN_HOME` / `VIBE_USAGE_QODER_CN_DB`) and `~/.qoder-cn/projects/` (`QODERCN_CONFIG_DIR` / `VIBE_USAGE_QODER_CN_PROJECTS`); reported as source `qoder-cn` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-cafe/vibe-usage",
-  "version": "0.10.33",
+  "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/parsers/codebuddy.js

@@ -0,0 +1,202 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { createReadStream } from 'node:fs';
+import { basename, join, sep } from 'node:path';
+import { aggregateToBuckets, extractSessions } from './aggregate.js';
+import { projectFromCwd, toCount } from './fs-utils.js';
+import { getCodebuddyRoots } from '../tools.js';
+
+// CodeBuddy Code (Tencent's terminal agent, `@tencent-ai/codebuddy-code`). The
+// store follows Claude Code's layout:
+//   <home>/projects/<compressed-cwd>/<sessionId>.jsonl   (+ nested subagent dirs)
+// where <home> is `$CODEBUDDY_CONFIG_DIR` or ~/.codebuddy.
+//
+// Two record shapes live in those transcripts (verified against 2.151.0's own
+// writer and a real store): local turns are `{type:"message", role:"user"|…,
+// content, sessionId, cwd}`, while every successful model call is the API
+// message shape — `{message:{id, model, role:"assistant",
+// usage:{input_tokens, output_tokens, cache_read_input_tokens,
+// cache_creation_input_tokens}}}` — so token accounting reads `message.usage`
+// only. `usage.cache_creation` (the per-TTL breakdown) is written as `null`, so
+// cache writes fold into input and cannot be priced per TTL, matching every
+// parser that has no split.
+const SOURCE = 'codebuddy';
+const PROJECTS = 'projects';
+
+export function resolveCodebuddyRoots(env = process.env, home) {
+  return getCodebuddyRoots(env, home);
+}
+
+/** Session id of a transcript file, and the project fallback from its folder. */
+function fileIdentity(filePath, projectsDir) {
+  const sessionId = basename(filePath, '.jsonl');
+  const relative = filePath.startsWith(projectsDir + sep) ? filePath.slice(projectsDir.length + 1) : '';
+  const folder = relative.split(sep)[0] || '';
+  // Compressed cwd folders look like `private-tmp-my-project`; the last segment
+  // is the best guess when a record carries no cwd.
+  const fallback = folder.split('-').filter(Boolean).at(-1) || 'unknown';
+  return { sessionId, fallback };
+}
+
+function findTranscripts(root, onWarning) {
+  const projectsDir = join(root, PROJECTS);
+  if (!existsSync(projectsDir)) return { projectsDir, files: [] };
+  const files = [];
+  const walk = dir => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); }
+    catch (err) { onWarning(`codebuddy: 无法读取目录 ${dir}: ${err.message}`); return; }
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile() && entry.name.endsWith('.jsonl')) files.push(path);
+    }
+  };
+  walk(projectsDir);
+  return { projectsDir, files };
+}
+
+/**
+ * Provider routing/tier labels ('auto', 'default', …) are not model ids, and
+ * server-side pricing matches the model string alone: a bare `auto` would be
+ * billed at Cursor's `auto` rate — the collision PR #83 fixed for Qoder by
+ * renaming it `qoder-auto`. Namespace the tier labels with the tool prefix;
+ * concrete ids (`claude-sonnet-4-6`, …) pass through untouched.
+ */
+const ROUTING_TIER_IDS = new Set([
+  'auto', 'default', 'default-model', 'fast', 'turbo', 'lite', 'ultimate', 'performance', 'efficient',
+]);
+
+function normalizeModel(model) {
+  const lower = model.toLowerCase();
+  return ROUTING_TIER_IDS.has(lower) ? `${SOURCE}-${lower}` : model;
+}
+
+/** One usage-bearing assistant message, keyed so retries/copies collapse. */
+function usageEntry(obj, projectFallback, sessionId) {
+  const usage = obj.message?.usage;
+  if (!usage) return null;
+  const timestampMs = Number(obj.timestamp) || Date.parse(obj.message?.timestamp) || null;
+  const timestamp = Number.isFinite(timestampMs) ? new Date(timestampMs) : null;
+  if (!timestamp || isNaN(timestamp.getTime())) return null;
+
+  const cacheWrite = toCount(usage.cache_creation_input_tokens);
+  const inputTokens = toCount(usage.input_tokens) + cacheWrite;
+  const outputTokens = toCount(usage.output_tokens);
+  const cachedInputTokens = toCount(usage.cache_read_input_tokens);
+  if (!inputTokens && !outputTokens && !cachedInputTokens) return null;
+
+  const messageId = typeof obj.message?.id === 'string' ? obj.message.id.trim() : '';
+  const providerMessageId = typeof obj.providerData?.messageId === 'string' ? obj.providerData.messageId.trim() : '';
+  const ownId = typeof obj.id === 'string' ? obj.id.trim() : '';
+  // The CLI leaves `message.id` empty on some builds and keeps the per-message id
+  // in providerData; `conversationRequestId` is a *turn* id (one turn can hold
+  // several billable calls), so it is explicitly not a dedup key. Without this
+  // chain every call collapses onto one empty key and the session under-counts.
+  const identity = messageId || providerMessageId || ownId;
+  const dedupeKey = identity ? `call:${identity}` : null;
+
+  const model = normalizeModel([
+    obj.message?.model,
+    obj.providerData?.requestModelId,
+    obj.providerData?.model,
+  ].find(value => typeof value === 'string' && value.trim()) || 'unknown');
+
+  return {
+    dedupeKey,
+    usageScore: inputTokens + outputTokens + cachedInputTokens,
+    entry: {
+      source: SOURCE,
+      model,
+      project: projectFromCwd(obj.cwd, projectFallback),
+      timestamp,
+      inputTokens,
+      outputTokens,
+      cachedInputTokens,
+      reasoningOutputTokens: 0,
+    },
+    sessionId: typeof obj.sessionId === 'string' && obj.sessionId ? obj.sessionId : sessionId,
+  };
+}
+
+/** Human prompt? Local user turns only — the CLI marks injected/system text. */
+function isHumanPrompt(obj) {
+  if (obj?.role !== 'user' && obj?.message?.role !== 'user') return false;
+  if (obj.providerData?.isMeta || obj.providerData?.skipRun) return false;
+  if (obj.providerData?.isSessionSeparator || obj.providerData?.isCompactSummary) return false;
+  return true;
+}
+
+function readTimestamp(obj) {
+  const ms = Number(obj?.timestamp);
+  return Number.isFinite(ms) ? new Date(ms) : null;
+}
+
+export async function parse() {
+  const warnings = [];
+  const onWarning = message => warnings.push(message);
+  const entries = [];
+  const events = [];
+  const byKey = new Map();
+  const anonymous = [];
+  let skipped = false;
+
+  for (const root of resolveCodebuddyRoots()) {
+    const { projectsDir, files } = findTranscripts(root, onWarning);
+    for (const file of files) {
+      const { sessionId, fallback } = fileIdentity(file, projectsDir);
+      let stream;
+      try {
+        stream = createReadStream(file);
+        const lines = createInterface({ input: stream, crlfDelay: Infinity });
+        for await (const line of lines) {
+          if (!line.trim()) continue;
+          let obj;
+          try { obj = JSON.parse(line); } catch { continue; }
+          if (!obj || typeof obj !== 'object') continue;
+
+          const entry = usageEntry(obj, fallback, sessionId);
+          if (entry) {
+            if (!entry.dedupeKey) anonymous.push(entry);
+            else {
+              const current = byKey.get(entry.dedupeKey);
+              if (!current || entry.usageScore > current.usageScore) byKey.set(entry.dedupeKey, entry);
+            }
+            const timestamp = readTimestamp(obj);
+            if (timestamp) events.push({ sessionId: entry.sessionId, source: SOURCE, project: entry.entry.project, timestamp, role: 'assistant' });
+            continue;
+          }
+
+          if (isHumanPrompt(obj)) {
+            const timestamp = readTimestamp(obj);
+            if (timestamp) {
+              events.push({
+                sessionId: typeof obj.sessionId === 'string' && obj.sessionId ? obj.sessionId : sessionId,
+                source: SOURCE,
+                project: projectFromCwd(obj.cwd) || fallback,
+                timestamp,
+                role: 'user',
+              });
+            }
+          }
+        }
+      } catch (err) {
+        // A transcript that cannot be read means this source's snapshot is
+        // incomplete: skip the source so its previous upload state survives.
+        skipped = true;
+        onWarning(`codebuddy: 无法读取会话 ${file}: ${err.message}`);
+      } finally {
+        stream?.close();
+      }
+    }
+  }
+
+  for (const entry of anonymous) entries.push(entry.entry);
+  for (const entry of byKey.values()) entries.push(entry.entry);
+
+  const buckets = aggregateToBuckets(entries);
+  const sessions = extractSessions(events);
+  return skipped
+    ? { buckets: [], sessions: [], skipped: true, warnings }
+    : { buckets, sessions, warnings };
+}

package/src/parsers/index.js

@@ -29,6 +29,7 @@ import { parse as parseTraeCli } from './trae-cli.js';
 import { parse as parseWorkbuddy } from './workbuddy.js';
 import { parseQoder, parseQoderCn } from './qoder.js';
 import { parse as parseDevin } from './devin.js';
+import { parse as parseCodebuddy } from './codebuddy.js';
 
 export const parsers = {
   'claude-code': parseClaudeCode,
@@ -63,6 +64,7 @@ export const parsers = {
   'workbuddy': parseWorkbuddy,
   'zcode': parseZcode,
   'devin': parseDevin,
+  'codebuddy': parseCodebuddy,
 };
 
 export { roundToHalfHour, aggregateToBuckets, extractSessions } from './aggregate.js';

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',
+  });
+}