@vibe-cafe/vibe-usage 0.12.1 → 0.13.1

package/README.md

@@ -62,9 +62,11 @@ npx @vibe-cafe/vibe-usage help --all   # Full help (plain `help` shows the short
 
 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` when configured, otherwise the current CLI home (`$KIMI_CODE_HOME`, else `~/.kimi-code`) and then the legacy `~/.kimi` home, whichever holds a login — 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.
+- A quota result may carry a machine-readable `emptyReason` (`limitReached` / `noWindow` / `notEntitled` / `sessionWithoutPlanLimits`) alongside the human `message`; it is additive within schema v1, so clients that do not know it ignore it, and it says *why* there was no window instead of leaving the caller to parse prose. OpenCode Go sets `notEntitled` for a key without the Go subscription.
+- **Kimi Code** reads the official OAuth file from `$KIMI_CODE_HOME/credentials/kimi-code.json` (otherwise `~/.kimi-code/credentials/kimi-code.json`) and falls back to the legacy `$KIMI_SHARE_DIR` / `~/.kimi` location — the first login that exists wins. It calls `https://api.kimi.com/coding/v1/usages` and supports both the current 2.x response and the legacy quota response. 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.
+- **OpenCode Go** reads only the `opencode-go` integration key from OpenCode's own credential table (`~/.local/share/opencode/opencode.db`, read-only via the shared SQLite helper), falling back to the CLI's `auth.json` `opencode.key` for the pre-2.x layout that keeps its login there (`VIBE_USAGE_OPENCODE_DIRS` replaces discovery for fixtures/relocated data), and calls the official `https://opencode.ai/zen/go/v1/usage` endpoint with it. It reports the three windows OpenCode Go enforces (5-hour rolling, weekly, monthly) as normalized meters. A valid OpenCode key without an active Go subscription (HTTP 403) is a quiet "no data" rather than an error. The key is never written back, logged, or included in output; only a one-way hash of it scopes the disposable cache.
 - **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.
@@ -95,7 +97,7 @@ Quota results are never uploaded or added to incremental sync state. Credential-
 | MiMoCode | `$MIMOCODE_HOME/data/mimocode.db`, `$XDG_DATA_HOME/mimocode/mimocode.db`, or `~/.local/share/mimocode/mimocode.db` (SQLite; exact input, output, reasoning, and cache-read tokens from assistant messages; honors `MIMOCODE_DB`; cache-write tokens are included in input usage) |
 | Amp | `~/.local/share/amp/threads/`; cache-creation tokens are included in input usage |
 | Droid | `~/.factory/sessions/` |
-| DeepSeek Harness | `$DSH_HOME/sessions/` (default `~/.dsh`, fixture/relocation override: `VIBE_USAGE_DSH_SESSIONS`). Reads V0–V3 logs, including `session.v3.jsonl.zstd` from DSH `0.1.5-alpha.2`, with multi-frame Zstandard support (Node ≥ 22.15 built-in, `zstd` CLI fallback) and plain JSONL support. Each session uses its highest `session[.vN].jsonl[.zstd]` generation once, so frozen pre-migration logs are not double-counted. Usage comes from `assistant/message`: cache writes join uncached input, cache reads remain separate, and reasoning is split out of inclusive output. Fork history uses V0/V1 `seedLength` or V2/V3's last `session/end-seed` tagged `inherited: true`, and is skipped only when the parent copy confirms it; missing parents retain the sole local history. Unknown versions warn and protect sync state. |
+| DeepSeek Harness | `$DSH_HOME/sessions/` (default `~/.dsh`, fixture/relocation override: `VIBE_USAGE_DSH_SESSIONS`). Reads V0–V4 logs, including `session.v4.jsonl.zstd` from DSH's V4 integration format, with multi-frame Zstandard support (Node ≥ 22.15 built-in, `zstd` CLI fallback) and plain JSONL support. Each session uses its highest `session[.vN].jsonl[.zstd]` generation once, so frozen pre-migration logs are not double-counted. Usage comes from `assistant/message`: cache writes join uncached input, cache reads remain separate, and reasoning is split out of inclusive output. Fork history uses V0/V1 `seedLength` or V2–V4's last `session/end-seed` tagged `inherited: true`, and is skipped only when the parent copy confirms it; missing parents retain the sole local history. Unknown versions warn and protect sync state. |
 | Hermes (CLI / Desktop) | `<home>/state.db` + `<home>/profiles/<name>/state.db` (SQLite, multi-profile). Home: `$HERMES_HOME`, otherwise `~/.hermes` on macOS/Linux or `%LOCALAPPDATA%\hermes` on Windows (falls back to an existing `~/.hermes` only when the Windows native root is absent). Cache writes join input; reasoning is separated from inclusive output. Usage is currently a cumulative session total attributed to session start: a session spanning several days does **not** yet provide an accurate daily breakdown. |
 | Kiro | Kiro CLI native event streams `~/.kiro/sessions/cli/*.jsonl` (estimated tokens from message text: input = prompt + tool results, output = reply + tool calls, reasoning = thinking, cacheRead = re-sent context; thinking-block signatures excluded). Falls back to `~/Library/Application Support/kiro-cli/data.sqlite3` / `~/.local/share/kiro-cli/data.sqlite3` + optional `~/.kiro_sessions/*.json` archives, then IDE `q-client.log` whole-credit deltas as `kiro-credits` (floored cumulative diff — the server stores token counts as bigint); legacy IDE `dev_data/devdata.sqlite` token telemetry is opt-in with `VIBE_USAGE_KIRO_LEGACY_TOKENS=1` |
 | Cline (CLI / SDK / Desktop app) | All variants write the same `~/.cline/data/sessions/*/*.messages.json` per-call metrics (the desktop app's manifest says `source: "desktop"`; its Electron userData holds only WebView caches), plus legacy `~/.cline/{,data/}state/taskHistory.json` and editor extension stores. Honors `CLINE_DIR`, `CLINE_DATA_DIR`, and `CLINE_SESSION_DATA_DIR`; copied history is deduplicated |

package/package.json

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

package/src/parsers/dsh.js

@@ -7,13 +7,18 @@ import { aggregateToBuckets, extractSessions } from './aggregate.js';
 
 const SOURCE = 'dsh';
 
-// Verified against deepseek-ai/deepseek-harness tag dsh-v0.1.5-alpha.2:
+// Verified against deepseek-ai/deepseek-harness, released formats V0-V4:
 // packages/session/session-format/src/filename.ts, session-format-v0-to-v1,
-// session-format-v1-to-v2, session-format-v2-to-v3, and core/session/src/types.ts.
-// V0/V1 use header.seedLength; V2/V3 use a tagged inherited end-seed marker.
+// session-format-v1-to-v2, session-format-v2-to-v3, core/session/src/types.ts,
+// and docs/persistence-changes/2026-09-16-session-format-v4.md.
+// V0/V1 use header.seedLength; V2-V4 use a tagged inherited end-seed marker.
+// V4 (SESSION_FORMAT_VERSION = 4, commit 669b724a78) keeps the filename, header
+// fields, assistant usage block, and inherited cut; it lifts user-role tool
+// results into tool-role messages, adds forked to turn/end.reason, and adds
+// developer/message, none of which carry billable usage.
 // Re-check the format before accepting another version; never silently read a
 // frozen predecessor when a newer generation is present.
-const MAX_SESSION_FORMAT_VERSION = 3;
+const MAX_SESSION_FORMAT_VERSION = 4;
 const SESSION_FILENAME = /^session(?:\.v([1-9][0-9]*))?\.jsonl(\.zstd)?$/;
 
 // Safety cap for a single session log. DSH stores many small zstd frames per
@@ -200,7 +205,7 @@ function isUserMessageRecord(rec) {
  *   {"type":"user/message"|"assistant/message","time":...,"data":{...}}
  *
  * V0/V1 use header.seedLength. Their untagged end-seed markers can appear
- * after real history and must never be treated as a replay boundary. V2/V3
+ * after real history and must never be treated as a replay boundary. V2-V4
  * instead require isSeeded and use the LAST end-seed with data.inherited=true.
  * Only a proven inherited prefix also present in the parent is skipped.
  *

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

@@ -2,7 +2,6 @@ import {
   accessSync,
   closeSync,
   constants as fsConstants,
-  existsSync,
   fsyncSync,
   mkdirSync,
   openSync,
@@ -16,7 +15,7 @@ import {
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { attachCacheScope } from '../cache.js';
-import { quotaResult } from '../schema.js';
+import { canonicalizeMeters, quotaResult } from '../schema.js';
 
 const PRODUCT_ID = 'kimi-code';
 const DEFAULT_USAGE_URL = 'https://api.kimi.com/coding/v1/usages';
@@ -111,6 +110,29 @@ export function parseKimiUsage(payload, now = new Date()) {
     throw new Error('Kimi usage response is not an object');
   }
   const meters = [];
+  if (payload.usages && typeof payload.usages === 'object' && !Array.isArray(payload.usages)) {
+    const currentMeters = [
+      ['limit_5h', '5h', 5 * 3600],
+      ['limit_7d', '7d', 7 * 86400],
+      ['limit_month_total', 'Monthly', null],
+      ['limit_month_code', 'Monthly Code', null],
+    ];
+    for (const [key, label, windowSeconds] of currentMeters) {
+      const entry = payload.usages[key];
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+      const ratio = number(entry.used_ratio ?? entry.usedRatio);
+      if (ratio === null) continue;
+      const meter = {
+        id: key.replaceAll('_', '-'),
+        label,
+        utilization: Math.max(0, Math.min(100, ratio * 100)),
+      };
+      const resetsAt = resetDate(entry, now);
+      if (resetsAt) meter.resetsAt = resetsAt.toISOString();
+      if (windowSeconds) meter.windowSeconds = windowSeconds;
+      meters.push(meter);
+    }
+  }
   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);
@@ -127,7 +149,7 @@ export function parseKimiUsage(payload, now = new Date()) {
     }
   }
   const seen = new Set();
-  return meters.filter(meter => {
+  return canonicalizeMeters(meters).filter(meter => {
     const key = `${meter.label}\0${meter.windowSeconds || ''}`;
     if (seen.has(key)) return false;
     seen.add(key);
@@ -135,35 +157,33 @@ export function parseKimiUsage(payload, now = new Date()) {
   });
 }
 
-// Kimi Code has two credential locations in the wild. kimi-cli (1.x) keeps
-// `$KIMI_SHARE_DIR/credentials/kimi-code.json`, defaulting to `~/.kimi`, while
-// the current CLI (2.x) writes `$KIMI_CODE_HOME/credentials/kimi-code.json`,
-// defaulting to `~/.kimi-code` -- the same home the session parser already
-// resolves. Reading only the legacy path reported `missing_credentials` for
+// Kimi Code has two credential locations in the wild: the current CLI (2.x)
+// writes `$KIMI_CODE_HOME/credentials/kimi-code.json`, defaulting to
+// `~/.kimi-code` -- the same home the session parser already resolves -- while
+// kimi-cli (1.x) keeps `$KIMI_SHARE_DIR/credentials/kimi-code.json`, defaulting
+// to `~/.kimi`. Reading only the legacy path reported `missing_credentials` for
 // every 2.x user whose login sits in the new home (issue #112), while their
 // usage parsed fine, so the quota card contradicted the token tables.
 export function kimiCredentialPaths(environment = process.env, home = homedir()) {
-  const directories = [
-    environment.KIMI_SHARE_DIR?.trim(),
-    environment.KIMI_CODE_HOME?.trim(),
-    join(home, '.kimi-code'),
-    join(home, '.kimi'),
-  ];
-  return directories.filter(Boolean).map(directory => join(directory, 'credentials', 'kimi-code.json'));
+  const codeHome = environment.KIMI_CODE_HOME?.trim() || join(home, '.kimi-code');
+  const legacyHome = environment.KIMI_SHARE_DIR?.trim() || join(home, '.kimi');
+  return [...new Set([codeHome, legacyHome]
+    .map(directory => join(directory, 'credentials', 'kimi-code.json')))];
 }
 
-/**
- * The credential file to read and, on refresh, to rotate atomically.
- *
- * A login that exists wins over one that does not, in the order above: an
- * explicitly configured home outranks the CLI default, and the current CLI
- * home outranks the legacy one. With no login anywhere the current CLI's path
- * is returned so `missing_credentials` (and any rotation that follows a later
- * login) names the file the installed CLI actually writes.
- */
+// The file to read and, on refresh, to rotate atomically: the first existing
+// login, current home before legacy, so a stale `KIMI_SHARE_DIR` cannot shadow
+// the CLI the user actually runs. With no login anywhere the current CLI's path
+// is returned, so `missing_credentials` (and any rotation after a later login)
+// names the file the installed CLI writes.
 export function kimiCredentialPath(environment = process.env, home = homedir()) {
   const paths = kimiCredentialPaths(environment, home);
-  return paths.find(path => existsSync(path)) || paths[0];
+  for (const path of paths) {
+    try {
+      if (statSync(path).isFile()) return path;
+    } catch {}
+  }
+  return paths[0];
 }
 
 function readCredentials(path) {

package/src/quotas/providers/opencode-go.js

@@ -0,0 +1,225 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { attachCacheScope } from '../cache.js';
+import { quotaResult } from '../schema.js';
+import { isSqliteUnavailableError, queryDbJson, sqliteUnavailableError } from '../../parsers/sqlite.js';
+
+const PRODUCT_ID = 'opencode-go';
+const INTEGRATION_ID = 'opencode-go';
+const DEFAULT_USAGE_URL = 'https://opencode.ai/zen/go/v1/usage';
+
+// The endpoint reports the three windows OpenCode Go enforces (rolling /
+// weekly / monthly). It does not return the rolling window length, but the
+// official console labels the rolling window "5 hours", so the meter reuses
+// that window name; weekly/monthly are calendar windows whose reset instant
+// travels with the response.
+const METER_ORDER = [
+  ['rolling', '5h'],
+  ['weekly', 'Weekly'],
+  ['monthly', 'Monthly'],
+];
+
+/** Data roots scanned for the OpenCode credential store, in order. */
+export function openCodeDataRoots(environment = process.env, home = homedir()) {
+  const override = environment.VIBE_USAGE_OPENCODE_DIRS?.trim();
+  if (override) {
+    return override.split(delimiter).map(value => value.trim()).filter(Boolean);
+  }
+  return [join(home, '.local', 'share', 'opencode')];
+}
+
+export function openCodeDbPath(root) {
+  return join(root, 'opencode.db');
+}
+
+function date(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+/**
+ * Reads only the `opencode-go` integration key from OpenCode's credential
+ * table. The value is the client's own JSON blob (`{ type: 'key', key }`);
+ * nothing else in the row or database is selected, logged, cached, or
+ * uploaded.
+ */
+function readCredentialTable(root) {
+  const dbPath = openCodeDbPath(root);
+  if (!existsSync(dbPath)) return { status: 'missing' };
+  try {
+    const rows = queryDbJson(dbPath, `SELECT value FROM credential
+      WHERE integration_id = '${INTEGRATION_ID}'
+      ORDER BY coalesce(active, 1) DESC, time_updated DESC
+      LIMIT 1`);
+    const raw = rows[0]?.value;
+    if (typeof raw !== 'string' || !raw.trim()) return { status: 'missing' };
+    let key = '';
+    try {
+      const parsed = JSON.parse(raw);
+      key = typeof parsed?.key === 'string' ? parsed.key.trim() : '';
+    } catch {
+      key = '';
+    }
+    return key ? { status: 'ok', key } : { status: 'missing' };
+  } catch (error) {
+    if (isSqliteUnavailableError(error)) return { status: 'unavailable' };
+    // An older/newer schema without the credential table simply has no login.
+    if (/no such table|no such column/i.test(error?.message || '')) return { status: 'missing' };
+    return { status: 'error' };
+  }
+}
+
+/**
+ * Fallback for the pre-2.x layout, which keeps the same key as plain JSON in
+ * `auth.json` (`{"opencode": {"type": "api", "key": "sk-..."}}`). Only that one
+ * entry is read; sibling provider credentials in the file are never inspected,
+ * and the key is returned to the caller without ever being logged or cached.
+ * The credential table stays authoritative when it has a Go row — it is the
+ * Go-specific record, while `auth.json` also holds non-Go keys.
+ */
+function readAuthFile(root) {
+  let parsed = null;
+  try {
+    parsed = JSON.parse(readFileSync(join(root, 'auth.json'), 'utf8'));
+  } catch {
+    return { status: 'missing' };
+  }
+  const key = parsed?.opencode?.key;
+  const trimmed = typeof key === 'string' ? key.trim() : '';
+  return trimmed ? { status: 'ok', key: trimmed } : { status: 'missing' };
+}
+
+/**
+ * The Go key for one data root, or a failure to report. The credential table
+ * wins; `auth.json` covers stores that never migrated. A concrete table read
+ * failure is preserved only when the fallback has no key either, so an
+ * unreadable database cannot hide a perfectly good login.
+ */
+function readCredential(root) {
+  const table = readCredentialTable(root);
+  if (table.status === 'ok') return table;
+  const authFile = readAuthFile(root);
+  if (authFile.status === 'ok') return authFile;
+  return table;
+}
+
+export function parseOpenCodeGoUsage(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('OpenCode usage response is not an object');
+  }
+  const usage = payload.usage;
+  const meters = [];
+  for (const [id, label] of METER_ORDER) {
+    const item = usage?.[id];
+    if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+    const percent = Number(item.percent);
+    if (!Number.isFinite(percent)) continue;
+    const meter = { id, label, utilization: Math.max(0, Math.min(100, percent)) };
+    const resetsAt = date(item.resetsAt);
+    if (resetsAt) meter.resetsAt = resetsAt.toISOString();
+    meters.push(meter);
+  }
+  return meters;
+}
+
+export async function fetchOpenCodeGoQuota({
+  environment = process.env,
+  home = homedir(),
+  fetchImpl = globalThis.fetch,
+  usageURL = DEFAULT_USAGE_URL,
+  now = new Date(),
+  timeoutMs = 10_000,
+} = {}) {
+  let credential = { status: 'missing' };
+  for (const root of openCodeDataRoots(environment, home)) {
+    const found = readCredential(root);
+    if (found.status === 'ok') {
+      credential = found;
+      break;
+    }
+    // Keep the first concrete read failure; a missing database just means the
+    // next configured root may hold the login.
+    if (found.status !== 'missing' && credential.status === 'missing') credential = found;
+  }
+  if (credential.status === 'unavailable') {
+    return quotaResult({
+      id: PRODUCT_ID,
+      status: 'retryable_error',
+      message: sqliteUnavailableError('OpenCode Go').message,
+      fetchedAt: now,
+    });
+  }
+  if (credential.status === 'error') {
+    return quotaResult({
+      id: PRODUCT_ID,
+      status: 'retryable_error',
+      message: 'OpenCode credential store could not be read',
+      fetchedAt: now,
+    });
+  }
+  if (credential.status !== 'ok') {
+    return quotaResult({
+      id: PRODUCT_ID,
+      status: 'missing_credentials',
+      message: 'OpenCode Go is not logged in',
+      fetchedAt: now,
+    });
+  }
+
+  const token = credential.key;
+  try {
+    const response = await fetchImpl(usageURL, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 401) {
+      return attachCacheScope(quotaResult({
+        id: PRODUCT_ID,
+        status: 'unauthorized',
+        message: 'OpenCode Go rejected the saved API key',
+        fetchedAt: now,
+      }), token);
+    }
+    if (response.status === 403) {
+      // A valid OpenCode key without an active Go subscription. The reason
+      // travels machine-readably so a client can say "not subscribed" instead
+      // of showing a neutral empty state.
+      return attachCacheScope(quotaResult({
+        id: PRODUCT_ID,
+        status: 'no_data',
+        emptyReason: 'notEntitled',
+        message: 'OpenCode Go subscription is not active',
+        fetchedAt: now,
+      }), token);
+    }
+    if (!response.ok) {
+      return attachCacheScope(quotaResult({
+        id: PRODUCT_ID,
+        status: 'retryable_error',
+        message: `OpenCode usage API returned HTTP ${response.status}`,
+        fetchedAt: now,
+      }), token);
+    }
+    const meters = parseOpenCodeGoUsage(await response.json());
+    return attachCacheScope(quotaResult({
+      id: PRODUCT_ID,
+      status: meters.length ? 'ok' : 'no_data',
+      meters,
+      message: meters.length ? undefined : 'OpenCode usage API returned no window',
+      fetchedAt: now,
+      dataAsOf: now,
+    }), token);
+  } catch (error) {
+    return attachCacheScope(quotaResult({
+      id: PRODUCT_ID,
+      status: 'retryable_error',
+      message: error?.name === 'TimeoutError'
+        ? 'OpenCode usage request timed out'
+        : 'OpenCode usage request failed',
+      fetchedAt: now,
+    }), token);
+  }
+}

package/src/quotas/registry.js

@@ -4,6 +4,7 @@ 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 { fetchOpenCodeGoQuota } from './providers/opencode-go.js';
 import { fetchZaiQuota } from './providers/zai.js';
 import { FETCHABLE_QUOTA_PRODUCT_IDS, quotaEnvelope, quotaResult } from './schema.js';
 
@@ -11,6 +12,7 @@ const providers = new Map([
   ['kimi-code', fetchKimiCodeQuota],
   ['zcode', fetchZaiQuota],
   ['grok', fetchGrokQuota],
+  ['opencode-go', fetchOpenCodeGoQuota],
 ]);
 
 function executableExists(name, environment, platform) {
@@ -73,6 +75,12 @@ export function discoverQuotaProducts({
       detected: existsAny([grokHome]) || executableExists('grok', environment, platform),
       fetchable: true,
     },
+    {
+      id: 'opencode-go',
+      detected: existsAny([join(home, '.local', 'share', 'opencode')])
+        || executableExists('opencode', environment, platform),
+      fetchable: true,
+    },
     {
       id: 'cursor',
       detected: existsAny([join(home, '.cursor'),

package/src/quotas/schema.js

@@ -4,6 +4,7 @@ export const QUOTA_PRODUCT_IDS = Object.freeze([
   'kimi-code',
   'zcode',
   'grok',
+  'opencode-go',
   'cursor',
 ]);
 
@@ -11,6 +12,20 @@ export const FETCHABLE_QUOTA_PRODUCT_IDS = Object.freeze([
   'kimi-code',
   'zcode',
   'grok',
+  'opencode-go',
+]);
+
+/**
+ * Machine-readable "why there was no window" values, shared with the desktop
+ * clients' `EmptyReason` (macOS `RateLimit.swift`) and additive within schema
+ * v1: a client that does not know the field ignores it, and a client that does
+ * can render the reason instead of a neutral empty state.
+ */
+export const QUOTA_EMPTY_REASONS = Object.freeze([
+  'limitReached',
+  'noWindow',
+  'notEntitled',
+  'sessionWithoutPlanLimits',
 ]);
 
 const FETCH_STATUSES = new Set([
@@ -59,6 +74,65 @@ export function normalizeMeter(raw, index = 0) {
   return meter;
 }
 
+const PERIOD_LABELS = new Map([
+  ['daily', { label: '1d', seconds: 24 * 60 * 60, exact: true }],
+  ['day', { label: '1d', seconds: 24 * 60 * 60, exact: true }],
+  ['weekly', { label: '7d', seconds: 7 * 24 * 60 * 60, exact: true }],
+  ['week', { label: '7d', seconds: 7 * 24 * 60 * 60, exact: true }],
+  ['monthly', { label: 'Month', seconds: 30 * 24 * 60 * 60, exact: false }],
+  ['month', { label: 'Month', seconds: 30 * 24 * 60 * 60, exact: false }],
+]);
+
+function periodPresentation(meter) {
+  const compact = meter.label.trim().toLowerCase().replace(/\s+/g, '');
+  const alias = PERIOD_LABELS.get(compact);
+  if (alias) {
+    return {
+      label: alias.label,
+      seconds: meter.windowSeconds || alias.seconds,
+      inferredWindowSeconds: alias.exact ? alias.seconds : undefined,
+    };
+  }
+
+  const match = /^(\d+(?:\.\d+)?)(m|h|d|w)$/.exec(compact);
+  if (!match) return null;
+  const multipliers = { m: 60, h: 3600, d: 86400, w: 7 * 86400 };
+  const seconds = meter.windowSeconds || Number(match[1]) * multipliers[match[2]];
+  const label = compact === '1w' ? '7d' : compact;
+  return { label, seconds, inferredWindowSeconds: seconds };
+}
+
+/**
+ * Keep the compact desktop cards predictable across providers: generic time
+ * windows come first from shortest to longest, followed by model-specific and
+ * feature meters in their provider-defined order. The original index is the
+ * final comparison key so the sort remains deterministic on every JS runtime.
+ */
+export function canonicalizeMeters(rawMeters) {
+  return rawMeters
+    .map((raw, index) => {
+      const meter = normalizeMeter(raw, index);
+      const period = periodPresentation(meter);
+      if (period) {
+        meter.label = period.label;
+        if (!meter.windowSeconds && period.inferredWindowSeconds) {
+          meter.windowSeconds = period.inferredWindowSeconds;
+        }
+      }
+      return { meter, periodSeconds: period?.seconds, index };
+    })
+    .sort((left, right) => {
+      const leftIsPeriod = left.periodSeconds !== undefined;
+      const rightIsPeriod = right.periodSeconds !== undefined;
+      if (leftIsPeriod !== rightIsPeriod) return leftIsPeriod ? -1 : 1;
+      if (leftIsPeriod && left.periodSeconds !== right.periodSeconds) {
+        return left.periodSeconds - right.periodSeconds;
+      }
+      return left.index - right.index;
+    })
+    .map(item => item.meter);
+}
+
 export function quotaResult({
   id,
   status,
@@ -68,6 +142,7 @@ export function quotaResult({
   dataAsOf = fetchedAt,
   message,
   source = 'live',
+  emptyReason,
 }) {
   if (!FETCHABLE_QUOTA_PRODUCT_IDS.includes(id)) {
     throw new TypeError(`unsupported quota product: ${id}`);
@@ -78,7 +153,7 @@ export function quotaResult({
   const result = {
     id,
     status,
-    meters: meters.map(normalizeMeter),
+    meters: canonicalizeMeters(meters),
     fetchedAt: new Date(fetchedAt).toISOString(),
     source,
   };
@@ -86,6 +161,12 @@ export function quotaResult({
   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();
+  if (emptyReason !== undefined && emptyReason !== null) {
+    if (!QUOTA_EMPTY_REASONS.includes(emptyReason)) {
+      throw new TypeError(`invalid quota emptyReason: ${emptyReason}`);
+    }
+    result.emptyReason = emptyReason;
+  }
   return result;
 }