@vantran-se/openchamber-web 1.22.2 → 1.23.0

package/server/lib/quota/DOCUMENTATION.md

@@ -3,6 +3,11 @@
 ## Purpose
 This module fetches quota and usage signals for supported providers in the web server runtime.
 
+Node server entrypoints apply `../network-defaults.js` before serving requests,
+including the daemon launched directly through `server/index.js`. Connection
+attempts get 5 seconds without changing address-family selection. The VS Code
+extension applies the same policy in its own process at activation.
+
 ## Entrypoints and structure
 - `packages/web/server/lib/quota/index.js`: public entrypoint imported by `packages/web/server/index.js`.
 - `packages/web/server/lib/quota/routes.js`: Express route registration for quota endpoints.
@@ -18,6 +23,7 @@ These provider IDs are currently dispatchable via `fetchQuotaForProvider(provide
 | Provider ID | Display name | Module | Auth aliases/keys |
 | --- | --- | --- | --- |
 | `claude` | Claude | `providers/claude/` | Claude Code Keychain entry, Claude Code credentials file, OpenCode `auth.json` (`anthropic`, `claude`), `CLAUDE_CODE_OAUTH_TOKEN` |
+| `cline-pass` | ClinePass | `providers/cline-pass.js` | `cline-pass` (API key under `key` or `token`) |
 | `codex` | Codex | `providers/codex.js` | `openai`, `codex`, `chatgpt` |
 | `command-code` | Command Code | `providers/command-code.js` | `command-code` OAuth/API credential in OpenCode `auth.json`, or `COMMAND_CODE_API_KEY` |
 | `cursor` | Cursor | `providers/cursor.js` | Environment/token files, OpenChamber-managed credentials, or explicit one-time Cursor import |
@@ -25,6 +31,7 @@ These provider IDs are currently dispatchable via `fetchQuotaForProvider(provide
 | `deepseek` | DeepSeek | `providers/deepseek.js` | `deepseek` (API key under `key` or `token`) |
 | `exe-dev` | exe.dev | `providers/exe-dev.js` | Usage API token stored under `~/.config/openchamber/quota/` |
 | `google` | Google | `providers/google/index.js` | `google`, `google.oauth`, Antigravity accounts file |
+| `hyper` | Charm Hyper | `providers/hyper.js` | `hyper` (API key under `key` or `token`) |
 | `github-copilot` | GitHub Copilot | `providers/copilot.js` | `github-copilot`, `copilot` |
 | `github-copilot-addon` | GitHub Copilot Add-on | `providers/copilot.js` | `github-copilot`, `copilot` |
 | `kimi-for-coding` | Kimi for Coding | `providers/kimi.js` | `kimi-for-coding`, `kimi` |
@@ -34,7 +41,7 @@ These provider IDs are currently dispatchable via `fetchQuotaForProvider(provide
 | `zhipuai-coding-plan` | Zhipu AI Coding Plan | `providers/zhipuai-coding-plan.js` | `zhipuai-coding-plan`, `zhipuai`, `zhipu` |
 | `minimax-coding-plan` | MiniMax Coding Plan (minimax.io) | `providers/minimax-coding-plan.js` / `providers/minimax-shared.js` | `minimax-coding-plan` |
 | `minimax-cn-coding-plan` | MiniMax Coding Plan (minimaxi.com) | `providers/minimax-cn-coding-plan.js` / `providers/minimax-shared.js` | `minimax-cn-coding-plan` |
-| `ollama-cloud` | Ollama Cloud | `providers/ollama-cloud.js` | Manual cookie stored under `~/.config/openchamber/quota/` |
+| `ollama-cloud` | Ollama Cloud | `providers/ollama-cloud.js` | Manual cookie pasted into Settings (`aid=...; __Secure-session=...` from `ollama.com`), stored under `~/.config/openchamber/quota/` |
 | `wafer` | Wafer.ai | `providers/wafer.js` | `wafer`, `wafer-ai`, `wafer_ai`, `wafer.ai` |
 | `opencode-go` | OpenCode Go | `providers/opencode-go.js` | `opencode-go` API key from OpenCode `auth.json` |
 | `neuralwatt` | NeuralWatt | `providers/neuralwatt.js` | `neuralwatt` (API key under `key` or `token`) |
@@ -90,6 +97,22 @@ In 2025/2026 MiniMax rebranded "Coding Plan" to "Token Plan" alongside the M3 mo
 - **model_remains array**: Now contains entries for multiple model categories (chat, speech, video, image). The provider selects the chat-model entry by matching `MiniMax-M*`, then `general`/`chat`/`text` by name, then any entry with a remaining percent.
 - **Window status**: The `current_interval_status` and `current_weekly_status` fields indicate whether a window is active. Status `3` means the window is not applicable for the current plan tier (e.g. legacy plans without weekly limits). The provider omits inactive windows.
 
+## ClinePass quota semantics
+
+ClinePass reads `data.limits` from its usage-limits endpoint. Web/Electron and
+VS Code accept only known window types with finite numeric or non-empty numeric
+string percentages. Invalid windows are skipped independently; no usable windows
+is a failed refresh, not zero usage. Both implementations choose a non-empty
+`key`, then `token`, and expose auth/fetch dependencies for focused tests.
+Saved UI provider-visibility lists remain authoritative; installations without a
+saved list include ClinePass through the provider registry.
+
+## Charm Hyper balance semantics
+
+`GET https://hyper.charm.land/v1/credits` returns a team's current Hypercredit balance, not a percentage or reset timestamp. The [Hyper FAQ](https://hyper.charm.land/faq) defines one Hypercredit as $0.05. Both runtimes expose `credits_balance` in dollars and `credits` as a numeric label under the UI's localized window title. Keep English unit text out of that numeric label.
+
+Web and VS Code accept finite numeric balances and non-empty numeric strings. Missing, blank, or malformed balances remain explicit failures; zero is valid. Credential lookup uses a non-empty string `key`, then `token`, so malformed or blank keys cannot mark the provider configured or hide a valid fallback token. Hyper fetchers accept `readAuth` and `fetchImpl` dependencies for tests without replacing filesystem or auth modules.
+
 ## Kimi for Coding field semantics
 
 `GET https://api.kimi.com/coding/v1/usages` is inconsistent about which field carries consumption:
@@ -98,6 +121,10 @@ In 2025/2026 MiniMax rebranded "Coding Plan" to "Token Plan" alongside the M3 mo
 
 The provider computes `usedPercent` from whichever of `used`/`remaining` is present (`used` takes precedence when both exist) rather than assuming one field name. Both `packages/web/server/lib/quota/providers/kimi.js` and `packages/vscode/src/quotaProviders.ts` (`fetchKimiQuota`) must stay in sync — the VS Code extension duplicates this parsing logic rather than importing it.
 
+## Ollama Cloud settings-page shapes
+
+Ollama Cloud authentication uses two cookies (`aid` and `__Secure-session`) pasted together as one single-line Cookie header value. Ollama serves two different `/settings` page shapes and `parseOllamaSettingsHtml` supports both: session/weekly/premium-interaction windows (percent-based plans) and a `monthly` window derived from "Monthly usage: $X of $Y used" (cost-based plans) with a symmetric `$X / $Y` money `valueLabel` that reads correctly in both used/remaining display modes. The "Extra usage" credits block is surfaced as a balance-only `credits_balance` window with a plain money `valueLabel` when present, matching the Codex/DeepSeek credits treatment ("Credits Balance" in the UI); a $0 balance is omitted instead of showing an empty credits row. Keep `packages/web/server/lib/quota/providers/ollama-cloud.js` and `packages/vscode/src/quotaProviders.ts` (`parseOllamaSettingsHtml`) in sync — the VS Code extension duplicates this parsing logic rather than importing it.
+
 ## GitHub Copilot quota semantics
 
 GitHub Copilot usage exposes only the `premium_interactions` snapshot as the
@@ -117,6 +144,16 @@ snapshot carries `entitlement`, `remaining`, `unlimited`, and
 - When entitlement/remaining are unusable, fall back to `100 - percent_remaining`.
 - Snapshots other than `premium_interactions` (legacy annual plans) yield zero windows.
 
+## OpenRouter key semantics
+
+OpenRouter quota reads `GET https://openrouter.ai/api/v1/key`, which is documented as callable with any valid API key. `GET /api/v1/credits` is documented as "Management key required" and is not used. Calling `/credits` with a normal inference key has been observed to return HTTP 200 with `{total_credits:0, total_usage:0}` rather than an error; this behavior is not documented and is why the old implementation silently rendered "$0.00 left · $0.00 spent". A `/credits` fallback for unlimited keys would render the same zeros, so unlimited keys report `usage_monthly` instead.
+
+The documented `limit`, `limit_remaining`, and `limit_reset` fields are present and null on unlimited keys; null means unlimited, never missing data. For a limited key, window usage is `limit - limit_remaining`, not `usage`: `usage` is all-time and measures a different axis from the current reset window. Pairing `usage` with the current limit produces a wrong number. `limit_remaining` is server-computed and already honors `include_byok_in_limit`, so `byok_*` fields are ignored.
+
+Unlimited keys report `usage_monthly` in a `monthly` window with no percent. `limit_reset` is a period string (`daily`, `weekly`, `monthly`, or null), not a timestamp; `resetAt` is derived from the documented midnight-UTC boundaries, with weeks starting Monday. A set `limit` with a null `limit_reset` is a lifetime cap and maps to the `credits` window with no reset.
+
+Keep `packages/web/server/lib/quota/providers/openrouter.js` and `packages/vscode/src/quotaProviders.ts` in sync, as with the Kimi and Copilot providers; the VS Code extension duplicates this parsing logic rather than importing the web provider.
+
 ## Notes for contributors
 - Keep provider IDs stable; clients use them directly.
 - Avoid adding alias-based dispatch in `fetchQuotaForProvider`; dispatch currently expects exact provider IDs.

package/server/lib/quota/index.js

@@ -14,6 +14,7 @@ export {
   fetchCodexQuota,
   fetchCursorQuota,
   fetchDeepseekQuota,
+  fetchHyperQuota,
   fetchCopilotQuota,
   fetchCopilotAddonQuota,
   fetchKimiQuota,

package/server/lib/quota/providers/cline-pass.js

@@ -0,0 +1,125 @@
+import { readAuthFile } from '../../opencode/auth.js';
+import {
+  getAuthEntry,
+  normalizeAuthEntry,
+  asObject,
+  asNonEmptyString,
+  buildResult,
+  toUsageWindow,
+  toNumber,
+  toTimestamp
+} from '../utils/index.js';
+
+export const providerId = 'cline-pass';
+export const providerName = 'ClinePass';
+export const aliases = ['cline-pass'];
+const CLINE_USAGE_URL = 'https://api.cline.bot/api/v1/users/me/plan/usage-limits';
+
+// Cline reports a rolling five-hour window, a rolling weekly window, and a
+// calendar-month limit. Each window carries its duration so consumers can rank
+// limits by how soon they run out; the calendar month has no fixed duration.
+const WINDOW_KINDS = new Map([
+  ['five_hour', { key: '5h', windowSeconds: 5 * 60 * 60 }],
+  ['weekly', { key: 'weekly', windowSeconds: 7 * 24 * 60 * 60 }],
+  ['monthly', { key: 'monthly', windowSeconds: null }]
+]);
+
+const getApiKey = (auth) => {
+  const entry = normalizeAuthEntry(getAuthEntry(auth, aliases));
+  return asNonEmptyString(entry?.key) ?? asNonEmptyString(entry?.token);
+};
+
+export const isConfigured = (auth = readAuthFile()) => Boolean(getApiKey(auth));
+
+export const fetchQuota = async ({ readAuth = readAuthFile, fetchImpl = fetch } = {}) => {
+  const apiKey = getApiKey(readAuth());
+
+  if (!apiKey) {
+    return buildResult({
+      providerId,
+      providerName,
+      ok: false,
+      configured: false,
+      error: 'Not configured'
+    });
+  }
+
+  const timeoutSignal = AbortSignal.timeout(15_000);
+
+  try {
+    const response = await fetchImpl(CLINE_USAGE_URL, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Accept-Encoding': 'identity'
+      },
+      signal: timeoutSignal
+    });
+
+    if (!response.ok) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: response.status === 401
+          ? 'Session expired — please re-authenticate with ClinePass'
+          : `API error: ${response.status}`
+      });
+    }
+
+    const payload = asObject(await response.json());
+    const data = asObject(payload?.data);
+    const limits = Array.isArray(data?.limits) ? data.limits : [];
+
+    const windows = {};
+    for (const item of limits) {
+      const limit = asObject(item);
+      if (!limit) continue;
+      const kind = WINDOW_KINDS.get(asNonEmptyString(limit.type));
+      if (!kind) continue;
+      const usedPercent = toNumber(asNonEmptyString(limit.percentUsed)
+        ?? (Number.isFinite(limit.percentUsed) ? limit.percentUsed : null));
+      if (usedPercent === null) continue;
+      windows[kind.key] = toUsageWindow({
+        usedPercent,
+        windowSeconds: kind.windowSeconds,
+        resetAt: toTimestamp(limit.resetsAt)
+      });
+    }
+
+    if (Object.keys(windows).length === 0) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: 'No quota data in response'
+      });
+    }
+
+    return buildResult({
+      providerId,
+      providerName,
+      ok: true,
+      configured: true,
+      usage: { windows }
+    });
+  } catch (error) {
+    const isTimeout = error instanceof DOMException && (
+      error.name === 'TimeoutError' || (error.name === 'AbortError' && timeoutSignal.aborted)
+    );
+    const isParseError = error instanceof SyntaxError;
+    return buildResult({
+      providerId,
+      providerName,
+      ok: false,
+      configured: true,
+      error: isTimeout
+        ? 'Request timed out'
+        : isParseError
+          ? 'Invalid response from provider'
+          : (error instanceof Error ? error.message : 'Request failed')
+    });
+  }
+};

package/server/lib/quota/providers/cline-pass.test.js

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { fetchQuota, isConfigured } from './cline-pass.js';
+
+const readAuth = () => ({ 'cline-pass': { key: 'test-token' } });
+
+// Response shape verified by the contributor against the live ClinePass API.
+const documentedPayload = {
+  data: { limits: [
+    { type: 'five_hour', percentUsed: 43, resetsAt: '2026-09-08T17:00:44.598174595Z' },
+    { type: 'weekly', percentUsed: 17 },
+    { type: 'monthly', percentUsed: 8 },
+  ] },
+  success: true,
+};
+
+describe('ClinePass quota provider', () => {
+  it('maps the documented windows and sends credentials only in headers', async () => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async (url, options) => {
+      expect(url).toBe('https://api.cline.bot/api/v1/users/me/plan/usage-limits');
+      expect(new Headers(options.headers).get('Authorization')).toBe('Bearer test-token');
+      expect(options.signal).toBeInstanceOf(AbortSignal);
+      return Response.json(documentedPayload);
+    } });
+    expect(result.ok).toBe(true);
+    expect(result.providerId).toBe('cline-pass');
+    expect(Object.keys(result.usage.windows)).toEqual(['5h', 'weekly', 'monthly']);
+    expect(result.usage.windows['5h'].usedPercent).toBe(43);
+    expect(result.usage.windows['5h'].remainingPercent).toBe(57);
+    expect(result.usage.windows['5h'].windowSeconds).toBe(18_000);
+    expect(result.usage.windows['5h'].resetAt).toBe(Date.parse('2026-09-08T17:00:44.598174595Z'));
+    expect(result.usage.windows.weekly.usedPercent).toBe(17);
+    expect(result.usage.windows.weekly.windowSeconds).toBe(604_800);
+    expect(result.usage.windows.monthly.usedPercent).toBe(8);
+    expect(result.usage.windows.monthly.windowSeconds).toBeNull();
+    expect(JSON.stringify(result)).not.toContain('test-token');
+  });
+
+  it.each([0, '0', '51'])('accepts finite percentage %s', async (percentUsed) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [{ type: 'weekly', percentUsed }] } }) });
+    expect(result.ok).toBe(true);
+    expect(result.usage.windows.weekly.usedPercent).toBe(Number(percentUsed));
+  });
+
+  it.each([
+    { type: 'constructor', percentUsed: 5 }, { type: 'toString', percentUsed: 5 },
+    { type: '__proto__', percentUsed: 5 }, { type: 'quarterly', percentUsed: 5 },
+    { type: 'weekly', percentUsed: '' }, { type: 'weekly', percentUsed: ' ' },
+    { type: 'weekly', percentUsed: null }, { type: 'weekly', percentUsed: true },
+    { type: 'weekly', percentUsed: 'NaN' }, null,
+  ])('ignores malformed windows without discarding valid siblings: %j', async (limit) => {
+    const invalid = await fetchQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [limit] } }) });
+    expect(invalid.ok).toBe(false);
+    expect(invalid.configured).toBe(true);
+    expect(invalid.usage).toBeNull();
+    const mixed = await fetchQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [limit, { type: 'monthly', percentUsed: 8 }] } }) });
+    expect(mixed.ok).toBe(true);
+    expect(Object.keys(mixed.usage.windows)).toEqual(['monthly']);
+  });
+
+  it.each([null, [], {}, { data: null }, { data: { limits: [] } }])('rejects empty or malformed payload %j', async (payload) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => Response.json(payload) });
+    expect(result.ok).toBe(false);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe('No quota data in response');
+  });
+
+  it.each([{ key: '' }, { key: ' ' }, { key: 42 }, {}])('uses a usable token when the key is malformed: %j', async (entry) => {
+    const auth = { 'cline-pass': { ...entry, token: 'test-token' } };
+    expect(isConfigured(auth)).toBe(true);
+    const result = await fetchQuota({ readAuth: () => auth, fetchImpl: async (_url, options) => {
+      expect(new Headers(options.headers).get('Authorization')).toBe('Bearer test-token');
+      return Response.json(documentedPayload);
+    } });
+    expect(result.ok).toBe(true);
+  });
+
+  it.each([{}, { 'cline-pass': { key: '' } }, { 'cline-pass': { key: 42 } }])('does not fetch without usable credentials: %j', async (auth) => {
+    expect(isConfigured(auth)).toBe(false);
+    const result = await fetchQuota({ readAuth: () => auth, fetchImpl: async () => { throw new Error('Unexpected fetch'); } });
+    expect(result.configured).toBe(false);
+    expect(result.error).toBe('Not configured');
+  });
+
+  it.each([[401, 'Session expired — please re-authenticate with ClinePass'], [503, 'API error: 503']])('reports HTTP %s', async (status, error) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => new Response(null, { status }) });
+    expect(result.ok).toBe(false);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe(error);
+  });
+
+  it('reports invalid JSON', async () => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => new Response('{') });
+    expect(result.error).toBe('Invalid response from provider');
+  });
+
+  it('recognizes the timeout exception from AbortSignal.timeout', async () => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => { throw new DOMException('Timed out', 'TimeoutError'); } });
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe('Request timed out');
+  });
+});

package/server/lib/quota/providers/hyper.js

@@ -0,0 +1,118 @@
+import { readAuthFile } from '../../opencode/auth.js';
+import {
+  getAuthEntry,
+  normalizeAuthEntry,
+  buildResult,
+  toUsageWindow,
+  toNumber,
+  formatMoney,
+  asObject,
+  asNonEmptyString
+} from '../utils/index.js';
+
+export const providerId = 'hyper';
+export const providerName = 'Charm Hyper';
+export const aliases = ['hyper'];
+const HYPER_QUOTA_URL = 'https://hyper.charm.land/v1/credits';
+const CREDIT_TO_USD = 0.05;
+
+const getApiKey = (auth) => {
+  const entry = normalizeAuthEntry(getAuthEntry(auth, aliases));
+  return asNonEmptyString(entry?.key) ?? asNonEmptyString(entry?.token);
+};
+
+export const isConfigured = (auth = readAuthFile()) => Boolean(getApiKey(auth));
+
+export const fetchQuota = async ({ readAuth = readAuthFile, fetchImpl = fetch } = {}) => {
+  const apiKey = getApiKey(readAuth());
+
+  if (!apiKey) {
+    return buildResult({
+      providerId,
+      providerName,
+      ok: false,
+      configured: false,
+      error: 'Not configured'
+    });
+  }
+
+  const timeoutSignal = AbortSignal.timeout(15_000);
+
+  try {
+    const response = await fetchImpl(HYPER_QUOTA_URL, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Accept-Encoding': 'identity'
+      },
+      signal: timeoutSignal
+    });
+
+    if (!response.ok) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: response.status === 401 || response.status === 403
+          ? 'Session expired — please re-authenticate with Charm Hyper'
+          : `API error: ${response.status}`
+      });
+    }
+
+    const payload = asObject(await response.json());
+    const rawBalance = payload?.balance;
+    const balance = toNumber(asNonEmptyString(rawBalance)
+      ?? (Number.isFinite(rawBalance) ? rawBalance : null));
+
+    if (balance === null) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: 'No quota data in response'
+      });
+    }
+
+    const creditsLabel = Number.isInteger(balance) ? String(balance) : formatMoney(balance);
+    const windows = {
+      credits_balance: toUsageWindow({
+        usedPercent: null,
+        windowSeconds: null,
+        resetAt: null,
+        valueLabel: `$${formatMoney(balance * CREDIT_TO_USD)}`
+      }),
+      credits: toUsageWindow({
+        usedPercent: null,
+        windowSeconds: null,
+        resetAt: null,
+        valueLabel: creditsLabel
+      })
+    };
+
+    return buildResult({
+      providerId,
+      providerName,
+      ok: true,
+      configured: true,
+      usage: { windows }
+    });
+  } catch (error) {
+    const isTimeout = error instanceof DOMException && (
+      error.name === 'TimeoutError' || (error.name === 'AbortError' && timeoutSignal.aborted)
+    );
+    const isParseError = error instanceof SyntaxError;
+    return buildResult({
+      providerId,
+      providerName,
+      ok: false,
+      configured: true,
+      error: isTimeout
+        ? 'Request timed out'
+        : isParseError
+          ? 'Invalid response from provider'
+          : (error instanceof Error ? error.message : 'Request failed')
+    });
+  }
+};

package/server/lib/quota/providers/hyper.test.js

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { fetchQuota, isConfigured } from './hyper.js';
+
+const readAuth = () => ({ hyper: { key: 'test-token' } });
+
+// https://hyper.charm.land/docs/api/credits.html documents the balance payload.
+// https://hyper.charm.land/faq defines one Hypercredit as $0.05.
+describe('Charm Hyper quota provider', () => {
+  it.each([
+    [100, '100', '$5.00'],
+    ['50', '50', '$2.50'],
+    [25.5, '25.50', '$1.28'],
+    [0, '0', '$0.00'],
+    ['0', '0', '$0.00'],
+  ])('formats balance %s without an untranslated unit', async (balance, credits, dollars) => {
+    const result = await fetchQuota({
+      readAuth,
+      fetchImpl: async () => Response.json({ balance }),
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.providerId).toBe('hyper');
+    expect(result.configured).toBe(true);
+    expect(result.usage.windows.credits.valueLabel).toBe(credits);
+    expect(result.usage.windows.credits_balance.valueLabel).toBe(dollars);
+    for (const window of Object.values(result.usage.windows)) {
+      expect(window.usedPercent).toBeNull();
+      expect(window.remainingPercent).toBeNull();
+      expect(window.windowSeconds).toBeNull();
+      expect(window.resetAt).toBeNull();
+      expect(window.resetAfterSeconds).toBeNull();
+    }
+  });
+
+  it.each([
+    {}, null, [], { balance: '' }, { balance: ' \t ' }, { balance: 'NaN' },
+    { balance: 'Infinity' }, { balance: null }, { balance: true }, { balance: [] },
+    { balance: {} },
+  ])('rejects invalid payload %j instead of showing zero', async (payload) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => Response.json(payload) });
+
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.error).toBe('No quota data in response');
+    expect(result.usage).toBeNull();
+  });
+
+  it.each([
+    { hyper: { key: 'test-token' } },
+    { hyper: { token: 'test-token' } },
+    { hyper: 'test-token' },
+    { hyper: { key: '  ', token: 'test-token' } },
+    { hyper: { key: 42, token: 'test-token' } },
+  ])('uses a validated credential for the documented request', async (auth) => {
+    expect(isConfigured(auth)).toBe(true);
+    let requests = 0;
+    const result = await fetchQuota({
+      readAuth: () => auth,
+      fetchImpl: async (url, options) => {
+        requests += 1;
+        expect(url).toBe('https://hyper.charm.land/v1/credits');
+        expect(options.method).toBe('GET');
+        expect(new Headers(options.headers).get('Authorization')).toBe('Bearer test-token');
+        expect(options.signal).toBeInstanceOf(AbortSignal);
+        return Response.json({ balance: 100 });
+      },
+    });
+
+    expect(requests).toBe(1);
+    expect(result.ok).toBe(true);
+    expect(JSON.stringify(result)).not.toContain('test-token');
+  });
+
+  it.each([{}, { hyper: { key: '' } }, { hyper: { key: '  ' } }, { hyper: { key: 42 } }])(
+    'does not request usage without a valid credential',
+    async (auth) => {
+      expect(isConfigured(auth)).toBe(false);
+      let requests = 0;
+      const result = await fetchQuota({
+        readAuth: () => auth,
+        fetchImpl: async () => {
+          requests += 1;
+          return Response.json({ balance: 100 });
+        },
+      });
+
+      expect(requests).toBe(0);
+      expect(result.ok).toBe(false);
+      expect(result.configured).toBe(false);
+      expect(result.error).toBe('Not configured');
+    },
+  );
+
+  it.each([
+    [401, 'Session expired — please re-authenticate with Charm Hyper'],
+    [403, 'Session expired — please re-authenticate with Charm Hyper'],
+    [429, 'API error: 429'],
+    [500, 'API error: 500'],
+  ])('reports HTTP %s as a failure', async (status, error) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => new Response(null, { status }) });
+
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.error).toBe(error);
+    expect(result.usage).toBeNull();
+  });
+
+  it('reports invalid JSON as a parse failure', async () => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => new Response('{') });
+    expect(result.error).toBe('Invalid response from provider');
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.usage).toBeNull();
+  });
+
+  it.each([
+    [new DOMException('Timed out', 'TimeoutError'), 'Request timed out'],
+    [new Error('Network unavailable'), 'Network unavailable'],
+  ])('reports request failure', async (failure, message) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => { throw failure; } });
+    expect(result.error).toBe(message);
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.usage).toBeNull();
+  });
+});

package/server/lib/quota/providers/index.js

@@ -8,6 +8,7 @@
 import { buildResult } from '../utils/index.js';
 
 import * as claude from './claude/index.js';
+import * as clinePass from './cline-pass.js';
 import * as codex from './codex.js';
 import * as copilot from './copilot.js';
 import * as crof from './crof.js';
@@ -15,6 +16,7 @@ import * as cursor from './cursor.js';
 import * as deepseek from './deepseek.js';
 import * as exeDev from './exe-dev.js';
 import * as google from './google/index.js';
+import * as hyper from './hyper.js';
 import * as kimi from './kimi.js';
 import * as nanogpt from './nanogpt.js';
 import * as openai from './openai.js';
@@ -36,6 +38,12 @@ const registry = {
     isConfigured: claude.isConfigured,
     fetchQuota: claude.fetchQuota
   },
+  'cline-pass': {
+    providerId: clinePass.providerId,
+    providerName: clinePass.providerName,
+    isConfigured: clinePass.isConfigured,
+    fetchQuota: clinePass.fetchQuota
+  },
   codex: {
     providerId: codex.providerId,
     providerName: codex.providerName,
@@ -72,6 +80,12 @@ const registry = {
     isConfigured: google.isConfigured,
     fetchQuota: google.fetchGoogleQuota
   },
+  hyper: {
+    providerId: hyper.providerId,
+    providerName: hyper.providerName,
+    isConfigured: hyper.isConfigured,
+    fetchQuota: hyper.fetchQuota
+  },
   'zai-coding-plan': {
     providerId: zai.providerId,
     providerName: zai.providerName,
@@ -220,6 +234,7 @@ export const fetchGoogleQuota = google.fetchGoogleQuota;
 export const fetchCodexQuota = codex.fetchQuota;
 export const fetchCursorQuota = cursor.fetchQuota;
 export const fetchDeepseekQuota = deepseek.fetchQuota;
+export const fetchHyperQuota = hyper.fetchQuota;
 export const fetchCopilotQuota = copilot.fetchQuota;
 export const fetchCopilotAddonQuota = copilot.fetchQuotaAddon;
 export const fetchKimiQuota = kimi.fetchQuota;

package/server/lib/quota/providers/neuralwatt.js

@@ -74,7 +74,6 @@ export const fetchQuota = async () => {
     const subscription = payload?.subscription ?? null;
     const inOverage = Boolean(subscription?.in_overage);
     const allowance = payload?.key?.allowance ?? null;
-    const keyName = payload?.key?.name ?? null;
     const creditsRemaining = toNumber(payload?.balance?.credits_remaining_usd);
 
     const windows = {};
@@ -116,19 +115,17 @@ export const fetchQuota = async () => {
         : (spent !== null && effectiveLimit !== null && effectiveLimit > 0
             ? Math.max(0, Math.min(100, (spent / effectiveLimit) * 100))
             : null);
-      // Window title is the localized period label (daily/weekly/monthly); key
-      // name is attached via valueLabel for identification (wafer precedent).
+      // Window title is the localized period label (daily/weekly/monthly); the
+      // usage value stays a percent so the UI's display-mode toggle applies.
       const periodKey = (period === 'daily' || period === 'weekly' || period === 'monthly' || period === 'month')
         ? (period === 'month' ? 'monthly' : period)
         : 'billing_cycle';
-      const labelName = asNonEmptyString(keyName);
       const resetAt = toTimestamp(allowance.reset_at);
       const windowSeconds = period ? periodToWindowSeconds(period) : null;
       windows[periodKey] = toUsageWindow({
         usedPercent,
         windowSeconds,
-        resetAt,
-        ...(labelName ? { valueLabel: labelName } : {})
+        resetAt
       });
     } else if (creditsRemaining !== null) {
       windows.credits_balance = toUsageWindow({