@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/usage/providers.server.ts

@@ -0,0 +1,214 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Builds the `providers` list of `GET /api/settings/usage`.
+ *
+ * Three inputs are folded per provider:
+ *  1. credentials — a provider with no usable key is dropped entirely, never
+ *     rendered as an empty "not configured" row;
+ *  2. provider-reported quota windows (`omp usage --json`), which omp already
+ *     normalizes per vendor;
+ *  3. the token/cost burn omp recorded locally in its session transcripts
+ *     (trailing 30 days), attributed by the `message.provider` omp wrote.
+ *
+ * kenari and DeepSeek additionally carry their provider-specific reports
+ * (Rupiah wallet/quota, prepaid balance) — those two expose far more than a
+ * generic limit list, and the richer card is what the user already reads.
+ */
+
+import { fetchOmpRegistrySnapshot } from '@/server/lib/models/provider-registry.server';
+import { buildDeepSeekReport } from '@/server/lib/usage/deepseek';
+import { buildKenariReport } from '@/server/lib/usage/kenari';
+import { fetchOmpUsageSnapshot, type OmpUsageSnapshot } from '@/server/lib/usage/omp-usage.server';
+import { fetchVendorBalance, type VendorBalance } from '@/server/lib/usage/vendor-balance.server';
+import { kenariProviderSlugs, listCredentialedProviders, type CredentialedProvider } from '@/server/lib/usage/provider-key';
+import { titleCaseProviderSlug } from '@/shared/lib/models/provider/label';
+import type { KenariUsageReport, UsageProviderSummary } from '@/shared/types';
+
+/** Slug aliases omp uses interchangeably, folded onto one display entry. */
+const SLUG_ALIASES: Record<string, string> = {
+  'command-code': 'commandcode',
+};
+
+/**
+ * Brand spellings a title-case pass cannot produce. Kept small on purpose: the
+ * slug is the identity, this is only how it is printed.
+ */
+const BRAND_NAMES: Record<string, string> = {
+  openai: 'OpenAI',
+  kenari: 'Kenari.id',
+  deepseek: 'DeepSeek',
+  'openai-codex': 'OpenAI Codex',
+  'google-gemini-cli': 'Google Gemini CLI',
+  'google-antigravity': 'Google Antigravity',
+  'github-copilot': 'GitHub Copilot',
+  zai: 'Z.AI',
+  'zai-coding-plan': 'Z.AI Coding Plan',
+  xai: 'xAI',
+  'xai-oauth': 'xAI (OAuth)',
+  'kimi-code': 'Kimi Code',
+  'qwen-portal': 'Qwen Portal',
+  'minimax-code': 'MiniMax Code',
+  'minimax-code-cn': 'MiniMax Code (CN)',
+  'alibaba-token-plan': 'Alibaba Token Plan',
+  'alibaba-coding-plan': 'Alibaba Coding Plan',
+  'zhipu-coding-plan': 'Zhipu Coding Plan',
+  'gitlab-duo': 'GitLab Duo',
+  'gitlab-duo-agent': 'GitLab Duo Agent',
+  'charm-hyper': 'Charm Hyper',
+  'cline-pass': 'Cline Pass',
+  'opencode-go': 'OpenCode Go',
+  'xiaomi-token-plan-sgp': 'Xiaomi Token Plan (SGP)',
+  'xiaomi-token-plan-ams': 'Xiaomi Token Plan (AMS)',
+  'xiaomi-token-plan-cn': 'Xiaomi Token Plan (CN)',
+  'openai-codex-device': 'OpenAI Codex (Device)',
+};
+
+function canonicalSlug(slug: string): string {
+  const lower = slug.trim().toLowerCase();
+  return SLUG_ALIASES[lower] ?? lower;
+}
+
+/** Human-readable provider name: brand spelling when known, title case otherwise. */
+function displayName(slug: string): string {
+  return BRAND_NAMES[slug] ?? titleCaseProviderSlug(slug);
+}
+
+/**
+ * omp's own display names for the providers it knows (slug → name), e.g.
+ * `commandcode` → "Command Code". Best-effort: a cold or busy omp degrades to
+ * the slug-derived names.
+ */
+async function loadProviderNames(): Promise<Record<string, string>> {
+  try {
+    const { providers } = await fetchOmpRegistrySnapshot();
+    const names: Record<string, string> = {};
+    for (const provider of providers) {
+      const slug = canonicalSlug(provider.id);
+      const name = provider.name.trim();
+      if (slug && name) names[slug] = name;
+    }
+    return names;
+  } catch {
+    // no-excuse-ok: catch — display names are supplementary, never load-bearing
+    return {};
+  }
+}
+
+/**
+ * Fetch vendor balance windows for every slug that has an adapter. Failures are
+ * per provider and never reject the batch.
+ */
+async function loadVendorBalances(slugs: string[]): Promise<Map<string, VendorBalance>> {
+  const results = await Promise.all(
+    slugs.map(async (slug) => [slug, await fetchVendorBalance(slug)] as const),
+  );
+  const balances = new Map<string, VendorBalance>();
+  for (const [slug, balance] of results) {
+    if (balance) balances.set(slug, balance);
+  }
+  return balances;
+}
+
+/** Merge credentialed slugs that resolve to the same canonical provider. */
+function mergeCredentials(entries: CredentialedProvider[]): Map<string, string[]> {
+  const bySlug = new Map<string, string[]>();
+  for (const entry of entries) {
+    const slug = canonicalSlug(entry.slug);
+    if (!slug) continue;
+    const sources = bySlug.get(slug) ?? [];
+    for (const source of entry.sources) {
+      if (!sources.includes(source)) sources.push(source);
+    }
+    bySlug.set(slug, sources);
+  }
+  return bySlug;
+}
+
+/**
+ * Whether omp ships a usage adapter for `slug`, and whether that adapter came
+ * back empty.
+ *
+ * `omp usage --json` names a provider in `accountsWithoutUsage` **only when it
+ * has an adapter whose fetch produced nothing** — a provider omp does not track
+ * never appears there at all (verified: with a stored DeepSeek key and no
+ * adapter it is absent; with a stored Anthropic key and a failing fetch it is
+ * present). So the slug's presence is exactly the "tracked but empty" signal,
+ * and a provider that is neither in `reports` nor in `accountsWithoutUsage` has
+ * no quota endpoint to speak of.
+ */
+export function resolveUsageTracking(
+  slug: string,
+  snapshot: Pick<OmpUsageSnapshot, 'reports' | 'accountsWithoutUsage'>,
+): { tracked: boolean; limitsUnavailable: boolean } {
+  const limitsUnavailable = snapshot.accountsWithoutUsage.includes(slug);
+  return {
+    tracked: snapshot.reports.has(slug) || limitsUnavailable,
+    limitsUnavailable,
+  };
+}
+
+/**
+ * Build the provider rows. Providers are ordered by display name so the
+ * sidebar and the right-panel picker list them identically.
+ *
+ * `force` bypasses the provider-quota cache (see `fetchOmpUsageSnapshot`).
+ */
+export async function buildUsageProviders(options: { force?: boolean } = {}): Promise<UsageProviderSummary[]> {
+  const [credentialed, snapshot, names] = await Promise.all([
+    listCredentialedProviders(),
+    fetchOmpUsageSnapshot({ force: options.force }),
+    loadProviderNames(),
+  ]);
+
+  const credentials = mergeCredentials(credentialed);
+  // Each Kenari provider carries its own report: two accounts share the same
+  // upstream endpoints, so gating on the literal slug `kenari` left a second
+  // one (`kenari2`) with no quota card while its key was never read. DeepSeek
+  // still resolves by its canonical slug.
+  const kenariSlugs = await kenariProviderSlugs(credentials.keys());
+  const [kenariReports, deepseek, balances] = await Promise.all([
+    Promise.all([...kenariSlugs].map(async (slug) => [slug, await buildKenariReport(slug)] as const)),
+    credentials.has('deepseek') ? buildDeepSeekReport() : Promise.resolve(null),
+    loadVendorBalances([...credentials.keys()]),
+  ]);
+  const kenariBySlug = new Map<string, KenariUsageReport>();
+  for (const [slug, report] of kenariReports) {
+    if (report) kenariBySlug.set(slug, report);
+  }
+
+  const summaries: UsageProviderSummary[] = [];
+  for (const [slug, sources] of credentials) {
+    const report = snapshot.reports.get(slug);
+    const balance = balances.get(slug);
+    const { tracked, limitsUnavailable } = resolveUsageTracking(slug, snapshot);
+    const summary: UsageProviderSummary = {
+      id: slug,
+      name: names[slug] ?? displayName(slug),
+      credentialSources: sources,
+      // A vendor balance is real quota data even when omp has no adapter for it.
+      tracked: tracked || Boolean(balance && balance.limits.length > 0),
+      limits: [...(report?.limits ?? []), ...(balance?.limits ?? [])],
+      ...(limitsUnavailable ? { limitsUnavailable: true } : {}),
+      ...(report?.notes ? { notes: report.notes } : {}),
+    };
+
+    const kenariReport = kenariBySlug.get(slug);
+    if (kenariReport) {
+      summary.kenari = kenariReport;
+      if (kenariReport.error) summary.error = kenariReport.error;
+    } else if (slug === 'deepseek' && deepseek) {
+      summary.deepseek = deepseek;
+      if (deepseek.error) summary.error = deepseek.error;
+    } else if (balance?.error && !summary.error) {
+      // Only surface a balance failure when nothing richer already reported one.
+      summary.error = balance.error;
+    }
+    summaries.push(summary);
+  }
+
+  return summaries.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/server/lib/usage/report.server.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `UsageReport` both read paths answer with: `GET /api/settings/usage` and
+ * the realtime `usage` topic.
+ *
+ * One builder, because the two must never disagree. The right panel renders
+ * whichever arrived first (`usage.data ?? fetched`), so a topic payload shaped
+ * differently from the HTTP body is not a stale reading — it is a crash: the
+ * topic used to resolve the provider ROWS while both consumers expect the
+ * report envelope, so `report.providers.map` ran on `undefined`.
+ *
+ * The demo report lives here rather than in the route for the reason
+ * `omp/session/data-mock.ts` documents: under MOCK the panel reads the TOPIC,
+ * so a demo reachable only over HTTP would leave the view empty (and, before
+ * the shape was unified, crash it outright).
+ */
+
+import { isMockMode } from '@/server/mock.server';
+import { buildUsageProviders } from '@/server/lib/usage/providers.server';
+import type { UsageProviderSummary, UsageReport } from '@/shared/types';
+
+/**
+ * Build the report. `force` bypasses the provider-quota cache (the user's own
+ * Refresh button: each read calls every provider's endpoint).
+ */
+export async function buildUsageReport(options: { force?: boolean } = {}): Promise<UsageReport> {
+  if (isMockMode()) return mockUsageReport();
+  return {
+    isMock: false,
+    generatedAt: new Date().toISOString(),
+    providers: await buildUsageProviders({ force: options.force }),
+  };
+}
+
+/** Deterministic demo report so the Usage surfaces render under MOCK=true. */
+export function mockUsageReport(): UsageReport {
+  const providers: UsageProviderSummary[] = [
+    {
+      id: 'kenari',
+      name: 'Kenari.id',
+      credentialSources: ['models.yml'],
+      // kenari is a plain OpenAI-compatible gateway: omp ships no usage adapter.
+      tracked: false,
+      limits: [],
+      kenari: {
+        balance: { amountRp: 25_000, raw: 'Saldo: Rp 25.000' },
+        usage: {
+          rows: [
+            { model: 'gemini-3-7-flash', requests: 37, inputTokens: 22255, outputTokens: 11487, costRp: 0 },
+            { model: 'glm-5-3-flash', requests: 2122, inputTokens: 369435677, outputTokens: 914679, costRp: 0 },
+          ],
+          totalRequests: 5941,
+          totalCostRp: 0,
+          raw: 'Pemakaian 30 hari terakhir (biaya Rupiah).',
+        },
+        quota: {
+          planName: 'Pro',
+          windows: [
+            { key: 'five_hour', label: '5 hours', usedRp: 0, remainingRp: 50_000, resetsAt: '2026-09-14T10:00:00.000Z' },
+            { key: 'week', label: 'Weekly', usedRp: 12_500, remainingRp: 287_500, resetsAt: '2026-09-20T00:00:00.000Z' },
+            { key: 'month', label: 'Monthly', usedRp: 120_000, remainingRp: 880_000, resetsAt: '2026-10-01T00:00:00.000Z' },
+          ],
+          coupon: null,
+        },
+      },
+    },
+    {
+      id: 'deepseek',
+      name: 'DeepSeek',
+      credentialSources: ['agent.db'],
+      tracked: false,
+      limits: [],
+      deepseek: {
+        balance: {
+          isAvailable: true,
+          entries: [
+            { currency: 'USD', totalBalance: '10.00', grantedBalance: '10.00', toppedUpBalance: '0.00' },
+          ],
+        },
+      },
+    },
+    {
+      id: 'anthropic',
+      name: 'Anthropic (Claude Pro/Max)',
+      credentialSources: ['agent.db'],
+      tracked: true,
+      limits: [
+        {
+          id: 'anthropic:5h',
+          label: 'Claude 5 hour limit',
+          windowLabel: '5h',
+          used: 42,
+          limit: 100,
+          usedFraction: 0.42,
+          unit: 'percent',
+          status: 'ok',
+          resetsAt: Date.now() + 3 * 60 * 60 * 1000,
+        },
+        {
+          id: 'anthropic:7d',
+          label: 'Claude weekly limit',
+          windowLabel: '7d',
+          used: 88,
+          limit: 100,
+          usedFraction: 0.88,
+          unit: 'percent',
+          status: 'warning',
+          resetsAt: Date.now() + 4 * 24 * 60 * 60 * 1000,
+        },
+        {
+          id: 'anthropic:fast',
+          label: 'Fast requests',
+          windowLabel: '24h',
+          used: 320,
+          limit: 500,
+          usedFraction: 0.64,
+          unit: 'requests',
+          status: 'ok',
+          resetsAt: Date.now() + 6 * 60 * 60 * 1000,
+        },
+      ],
+    },
+    {
+      // A pay-as-you-go vendor: no omp adapter, only a credit balance.
+      id: 'openrouter',
+      name: 'OpenRouter',
+      credentialSources: ['agent.db'],
+      tracked: false,
+      limits: [
+        {
+          id: 'openrouter:credits',
+          label: 'Key credits',
+          used: 25.5,
+          limit: 100,
+          remaining: 74.5,
+          usedFraction: 0.255,
+          unit: 'usd',
+          status: 'ok',
+        },
+        {
+          id: 'openrouter:daily',
+          label: 'Spent today (monthly)',
+          used: 1.82,
+          unit: 'usd',
+          status: 'unknown',
+        },
+      ],
+    },
+  ];
+
+  return { isMock: true, generatedAt: new Date().toISOString(), providers };
+}

package/src/server/lib/usage/reset.server.test.ts

@@ -0,0 +1,175 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Saved rate-limit resets: the parse, the list, and the spend.
+ *
+ * Pinned because both halves are easy to get silently wrong:
+ *
+ *  - a row without a `credentialId` cannot be spent (the target grammar is
+ *    `<provider>/<credential id>`), so rendering it would draw a dead button;
+ *  - omp exits 1 for "no accounts" AND for a real failure, so an empty list and
+ *    a failed read look identical on screen — the list path must REPORT the
+ *    failure rather than answer an empty list;
+ *  - a spend refusal (`already_redeemed`, `nothing_to_reset`) is a normal
+ *    outcome, so its sentence must survive rather than collapsing to `ok:false`.
+ *
+ * Shapes captured from `omp usage reset --json` on 18.11.0.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { executableStub } from '@/test-support/executable-stub';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { invalidateOmpCliCache } from '@/server/lib/omp/core/cli';
+import { listUsageResets, parseUsageResetList, spendUsageReset } from '@/server/lib/usage/reset.server';
+
+/** Answers `omp usage reset …` from a file the test rewrites. */
+function stubSource(responseFile: string): string {
+  return `const raw = (await Bun.file(${JSON.stringify(responseFile)}).text()).trim();
+const { stdout = '', stderr = '', exit = 0 } = raw ? JSON.parse(raw) : {};
+if (stdout) process.stdout.write(stdout);
+if (stderr) process.stderr.write(stderr);
+process.exit(exit);
+`;
+}
+
+const dirs: string[] = [];
+let stubBin = '';
+let responseFile = '';
+let realBin: string | undefined;
+const originalMock = Bun.env.MOCK;
+
+/** Point the stub at an outcome. */
+function stubResult(result: { stdout?: string; stderr?: string; exit?: number }): void {
+  writeFileSync(responseFile, JSON.stringify(result));
+}
+
+beforeAll(async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'omp-usage-reset-'));
+  dirs.push(dir);
+  responseFile = join(dir, 'response.json');
+  stubResult({ stdout: '{"generatedAt":1,"accounts":[]}' });
+  stubBin = await executableStub(stubSource(responseFile), 'fake-omp-reset');
+  realBin = Bun.env.KABMO_OMP_BIN;
+  Bun.env.KABMO_OMP_BIN = stubBin;
+  invalidateOmpCliCache();
+});
+
+afterAll(() => {
+  if (originalMock === undefined) delete Bun.env.MOCK;
+  else Bun.env.MOCK = originalMock;
+  if (realBin === undefined) delete Bun.env.KABMO_OMP_BIN;
+  else Bun.env.KABMO_OMP_BIN = realBin;
+  invalidateOmpCliCache();
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  Bun.env.MOCK = 'false';
+});
+
+describe('parseUsageResetList', () => {
+  test('keeps a spendable account and its credits', () => {
+    const list = parseUsageResetList({
+      generatedAt: 1792031781355,
+      accounts: [{
+        provider: 'openai-codex',
+        credentialId: 'cred-1',
+        email: 'a@b.c',
+        availableCount: 2,
+        redeemableCount: 1,
+        nextCreditId: 'c1',
+        credits: [{ id: 'c1', title: 'Rate-limit reset', usable: true, clears: ['openai-codex:5h'] }],
+      }],
+    });
+    expect(list.accounts).toHaveLength(1);
+    expect(list.accounts[0].credentialId).toBe('cred-1');
+    expect(list.accounts[0].redeemableCount).toBe(1);
+    expect(list.accounts[0].credits[0].clears).toEqual(['openai-codex:5h']);
+  });
+
+  test('drops an account with no credential id — its button could never work', () => {
+    const list = parseUsageResetList({
+      accounts: [
+        { provider: 'anthropic', credits: [] },
+        { provider: 'anthropic', credentialId: 'ok', credits: [] },
+      ],
+    });
+    expect(list.accounts.map((account) => account.credentialId)).toEqual(['ok']);
+  });
+
+  test('an unknown payload is an empty list, not a throw', () => {
+    expect(parseUsageResetList(null).accounts).toEqual([]);
+    expect(parseUsageResetList({ accounts: 'nope' }).accounts).toEqual([]);
+  });
+
+  test('a credit with no id is dropped rather than rendered', () => {
+    const list = parseUsageResetList({
+      accounts: [{ provider: 'anthropic', credentialId: 'c', credits: [{ title: 'x' }, { id: 'keep' }] }],
+    });
+    expect(list.accounts[0].credits.map((credit) => credit.id)).toEqual(['keep']);
+  });
+});
+
+describe('listUsageResets', () => {
+  test('parses a successful read', async () => {
+    stubResult({
+      stdout: JSON.stringify({
+        generatedAt: 5,
+        accounts: [{ provider: 'anthropic', credentialId: 'a1', availableCount: 1, credits: [] }],
+      }),
+    });
+    const list = await listUsageResets();
+    expect(list.generatedAt).toBe(5);
+    expect(list.accounts[0].provider).toBe('anthropic');
+  });
+
+  test('a failed read REPORTS omp’s sentence instead of answering an empty list', async () => {
+    stubResult({ stderr: 'No Codex or Claude accounts found. Run `omp` and use /login to add one.\n', exit: 1 });
+    await expect(listUsageResets()).rejects.toThrow('No Codex or Claude accounts found');
+  });
+
+  test('malformed JSON is reported, not silently empty', async () => {
+    stubResult({ stdout: 'not json' });
+    await expect(listUsageResets()).rejects.toThrow('unexpected JSON');
+  });
+});
+
+describe('spendUsageReset', () => {
+  test('a success keeps omp’s own sentence', async () => {
+    stubResult({ stdout: "Reset applied for a@b.c (Codex) — Claude's 5h session limit has been refreshed; weekly limits are unchanged.\n" });
+    const result = await spendUsageReset('openai-codex/cred-1');
+    expect(result.ok).toBe(true);
+    expect(result.message).toContain('Reset applied for a@b.c');
+  });
+
+  test('a refusal is an outcome with its reason, not a bare failure', async () => {
+    stubResult({ stderr: 'a@b.c (Codex): that reset was already redeemed.\n', exit: 1 });
+    const result = await spendUsageReset('openai-codex/cred-1');
+    expect(result.ok).toBe(false);
+    expect(result.message).toBe('a@b.c (Codex): that reset was already redeemed.');
+  });
+
+  test('an unknown target reports the same way', async () => {
+    stubResult({ stderr: 'No stored account matches "openai-codex/foo". List choices with `omp usage reset`.\n', exit: 1 });
+    const result = await spendUsageReset('openai-codex/foo');
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain('No stored account matches');
+  });
+});
+
+describe('mock mode', () => {
+  test('lists a deterministic demo and refuses a spend', async () => {
+    Bun.env.MOCK = 'true';
+    const list = await listUsageResets();
+    expect(list.accounts.length).toBeGreaterThan(0);
+    const result = await spendUsageReset('openai-codex/demo-codex-1');
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain('demo mode');
+  });
+});