ompchamber 2.0.2 → 3.1.0

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

@@ -0,0 +1,208 @@
+/**
+ * @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 { listCredentialedProviders, type CredentialedProvider } from '@/server/lib/usage/provider-key';
+import { titleCaseProviderSlug } from '@/shared/lib/models/provider/label';
+import type { 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);
+  // The kenari and DeepSeek reports are built for their canonical slugs only;
+  // each returns null when that provider has no credential. Vendor balances are
+  // fetched for every slug that has a balance adapter (a pay-as-you-go vendor
+  // omp ships no usage adapter for).
+  const [kenari, deepseek, balances] = await Promise.all([
+    credentials.has('kenari') ? buildKenariReport() : Promise.resolve(null),
+    credentials.has('deepseek') ? buildDeepSeekReport() : Promise.resolve(null),
+    loadVendorBalances([...credentials.keys()]),
+  ]);
+
+  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 } : {}),
+    };
+
+    if (slug === 'kenari' && kenari) {
+      summary.kenari = kenari;
+      if (kenari.error) summary.error = kenari.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/vendor-balance.server.test.ts

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { BALANCE_ADAPTER_SLUGS, parseVendorBalance } from '@/server/lib/usage/vendor-balance.server';
+
+/**
+ * The field mapping is the part that silently breaks when a vendor changes its
+ * schema — a renamed field yields `undefined`, which would render as an empty
+ * card rather than an error. Each payload below is the documented response
+ * shape for that vendor.
+ */
+describe('parseVendorBalance', () => {
+  test('has no adapter for a provider without a balance endpoint', () => {
+    expect(BALANCE_ADAPTER_SLUGS).not.toContain('anthropic');
+    expect(parseVendorBalance('anthropic', {})).toBeNull();
+    expect(parseVendorBalance('groq', {})).toBeNull();
+  });
+
+  test('OpenRouter reads the current key limit/usage envelope', () => {
+    const windows = parseVendorBalance('openrouter', {
+      data: {
+        limit: 100,
+        limit_remaining: 74.5,
+        usage: 25.5,
+        usage_daily: 1.82,
+        limit_reset: 'monthly',
+      },
+    });
+    const credits = windows?.find((window) => window.id === 'openrouter:credits');
+    expect(credits?.unit).toBe('usd');
+    expect(credits?.limit).toBe(100);
+    expect(credits?.remaining).toBe(74.5);
+    expect(credits?.usedFraction).toBeCloseTo(0.255, 5);
+    expect(credits?.status).toBe('ok');
+    expect(windows?.some((window) => window.id === 'openrouter:daily')).toBe(true);
+  });
+
+  test('OpenRouter without a credit limit still reports usage', () => {
+    const windows = parseVendorBalance('openrouter', { data: { usage: 3.5 } });
+    const credits = windows?.[0];
+    expect(credits?.limit).toBeUndefined();
+    expect(credits?.usedFraction).toBeUndefined();
+    expect(credits?.notes?.[0]).toContain('No credit limit');
+  });
+
+  test('Moonshot splits available/voucher/cash and flags an empty balance', () => {
+    const windows = parseVendorBalance('moonshot', {
+      code: 0,
+      status: true,
+      data: { available_balance: 49.58894, voucher_balance: 46.58893, cash_balance: 3.00001 },
+    });
+    expect(windows?.map((window) => window.id)).toEqual([
+      'moonshot:available',
+      'moonshot:voucher',
+      'moonshot:cash',
+    ]);
+    expect(windows?.[0].remaining).toBeCloseTo(49.58894, 5);
+
+    const drained = parseVendorBalance('moonshot', { data: { available_balance: 0 } });
+    expect(drained?.[0].status).toBe('exhausted');
+  });
+
+  test('SiliconFlow reads data.balance fields', () => {
+    const windows = parseVendorBalance('siliconflow', {
+      code: 20000,
+      data: { totalBalance: '88.88', chargeBalance: '88.00', balance: '0.88' },
+    });
+    expect(windows?.find((window) => window.id === 'siliconflow:total')?.remaining).toBeCloseTo(88.88, 5);
+    expect(windows?.find((window) => window.id === 'siliconflow:charge')?.remaining).toBeCloseTo(88, 5);
+  });
+
+  test('Novita converts 1/10000 USD units', () => {
+    const windows = parseVendorBalance('novita', {
+      availableBalance: '1000000',
+      cashBalance: '800000',
+      creditLimit: '200000',
+    });
+    const available = windows?.find((window) => window.id === 'novita:available');
+    expect(available?.remaining).toBeCloseTo(100, 5);
+    expect(available?.limit).toBeCloseTo(20, 5);
+    expect(windows?.find((window) => window.id === 'novita:cash')?.remaining).toBeCloseTo(80, 5);
+  });
+
+  test('DeepInfra maps one window per API key with its monthly limit', () => {
+    const windows = parseVendorBalance('deepinfra', [
+      { token_id: 'tok_1', name: 'prod', limit: 50, spend: 12.5 },
+      { token_id: 'tok_2', name: 'dev', limit: null, spend: null },
+    ]);
+    expect(windows?.length).toBe(2);
+    expect(windows?.[0].label).toBe('prod · monthly');
+    expect(windows?.[0].remaining).toBeCloseTo(37.5, 5);
+    expect(windows?.[1].limit).toBeUndefined();
+    expect(windows?.[1].notes?.[0]).toContain('No monthly limit');
+  });
+
+  test('rejects an unusable payload instead of inventing windows', () => {
+    expect(() => parseVendorBalance('moonshot', 'not json')).toThrow();
+    expect(() => parseVendorBalance('deepinfra', { not: 'an array' })).toThrow();
+  });
+});

package/src/server/lib/usage/vendor-balance.server.ts

@@ -0,0 +1,284 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Provider-reported BALANCE endpoints, for vendors that expose one to a plain
+ * API key.
+ *
+ * This is a deliberately narrow complement to `omp usage --json`, not a
+ * replacement: omp ships ~20 usage adapters, but they cover subscription plans
+ * (rolling 5h/7d windows). Pay-as-you-go vendors are not among them, and a
+ * credit balance is the only "quota" they have — so those are fetched here.
+ *
+ * Every endpoint below was verified to exist and to accept an ordinary API key
+ * (a bogus key returns 401, not 404). Anthropic and OpenAI are NOT here on
+ * purpose: their usage/cost reports require an org ADMIN key
+ * (`sk-ant-admin01-…`) that a normal workspace key cannot substitute, so the
+ * chamber cannot read them with the credential the user actually configured.
+ *
+ * Results are shaped as `UsageLimitWindow[]` so the existing quota renderer
+ * draws them — a balance is just a window whose unit is USD.
+ */
+
+import { readOmpProviderApiKey } from '@/server/lib/omp/core/auth-credentials';
+import { loadProviderEntries } from '@/server/lib/usage/provider-key';
+import { isRecord } from '@/shared/lib/util/guards';
+import type { UsageLimitWindow, UsageWindowStatus } from '@/shared/types';
+
+const FETCH_TIMEOUT_MS = 10_000;
+const MASKED_KEY_PATTERN = /•{3,}/;
+
+/** A vendor balance adapter: where to ask, and how to read the answer. */
+interface BalanceAdapter {
+  /** Provider slug as omp spells it. */
+  slug: string;
+  /** Env var omp reads for this provider, used when no stored key exists. */
+  envKey: string;
+  url: string;
+  /** Map the parsed JSON body into quota windows. Throws on an unusable body. */
+  parse: (payload: unknown) => UsageLimitWindow[];
+}
+
+function num(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+/** Status for a credit window: exhausted at zero remaining, else ok. */
+function balanceStatus(remaining: number | undefined): UsageWindowStatus {
+  if (remaining === undefined) return 'unknown';
+  return remaining <= 0 ? 'exhausted' : 'ok';
+}
+
+/** One USD window from a balance; `limit` is omitted when the vendor has none. */
+function usdWindow(input: {
+  id: string;
+  label: string;
+  used?: number;
+  limit?: number;
+  remaining?: number;
+  note?: string;
+}): UsageLimitWindow {
+  const usedFraction = input.limit && input.limit > 0 && input.used !== undefined
+    ? input.used / input.limit
+    : undefined;
+  return {
+    id: input.id,
+    label: input.label,
+    unit: 'usd',
+    status: balanceStatus(input.remaining),
+    ...(input.used !== undefined ? { used: input.used } : {}),
+    ...(input.limit !== undefined ? { limit: input.limit } : {}),
+    ...(input.remaining !== undefined ? { remaining: input.remaining } : {}),
+    ...(usedFraction !== undefined ? { usedFraction } : {}),
+    ...(input.note ? { notes: [input.note] } : {}),
+  };
+}
+
+/** Pull `data` (or the root) out of a vendor envelope. */
+function envelope(payload: unknown): Record<string, unknown> {
+  if (!isRecord(payload)) throw new Error('unexpected balance response');
+  return isRecord(payload.data) ? payload.data : payload;
+}
+
+const ADAPTERS: readonly BalanceAdapter[] = [
+  {
+    // Documented at openrouter.ai/docs — GET /api/v1/key returns the CURRENT
+    // key's own limit/usage, so no management key is needed (unlike /credits).
+    slug: 'openrouter',
+    envKey: 'OPENROUTER_API_KEY',
+    url: 'https://openrouter.ai/api/v1/key',
+    parse: (payload) => {
+      const data = envelope(payload);
+      const limit = num(data.limit);
+      const usage = num(data.usage);
+      const remaining = num(data.limit_remaining);
+      const reset = typeof data.limit_reset === 'string' ? data.limit_reset : undefined;
+      const windows = [
+        usdWindow({
+          id: 'openrouter:credits',
+          label: 'Key credits',
+          used: usage,
+          limit,
+          remaining,
+          note: limit === undefined ? 'No credit limit is set on this key.' : undefined,
+        }),
+      ];
+      const daily = num(data.usage_daily);
+      if (daily !== undefined) {
+        windows.push(usdWindow({ id: 'openrouter:daily', label: `Spent today${reset ? ` (${reset})` : ''}`, used: daily }));
+      }
+      return windows;
+    },
+  },
+  {
+    // Moonshot / Kimi Open Platform: GET /v1/users/me/balance with a Bearer key.
+    slug: 'moonshot',
+    envKey: 'MOONSHOT_API_KEY',
+    url: 'https://api.moonshot.ai/v1/users/me/balance',
+    parse: (payload) => {
+      const data = envelope(payload);
+      const available = num(data.available_balance);
+      const voucher = num(data.voucher_balance);
+      const cash = num(data.cash_balance);
+      const windows = [
+        usdWindow({ id: 'moonshot:available', label: 'Available balance', remaining: available }),
+      ];
+      if (voucher !== undefined) {
+        windows.push(usdWindow({ id: 'moonshot:voucher', label: 'Voucher balance', remaining: voucher }));
+      }
+      if (cash !== undefined) {
+        windows.push(usdWindow({ id: 'moonshot:cash', label: 'Cash balance', remaining: cash }));
+      }
+      return windows;
+    },
+  },
+  {
+    // SiliconFlow: GET /v1/user/info → data.balance / chargeBalance / totalBalance.
+    slug: 'siliconflow',
+    envKey: 'SILICONFLOW_API_KEY',
+    url: 'https://api.siliconflow.com/v1/user/info',
+    parse: (payload) => {
+      const data = envelope(payload);
+      const total = num(data.totalBalance);
+      const charge = num(data.chargeBalance);
+      const windows = [
+        usdWindow({ id: 'siliconflow:total', label: 'Total balance', remaining: total }),
+      ];
+      if (charge !== undefined) {
+        windows.push(usdWindow({ id: 'siliconflow:charge', label: 'Topped-up balance', remaining: charge }));
+      }
+      return windows;
+    },
+  },
+  {
+    // Novita: GET /openapi/v1/billing/balance/detail. Amounts are in 1/10000 USD.
+    slug: 'novita',
+    envKey: 'NOVITA_API_KEY',
+    url: 'https://api.novita.ai/openapi/v1/billing/balance/detail',
+    parse: (payload) => {
+      if (!isRecord(payload)) throw new Error('unexpected balance response');
+      const scale = 1 / 10_000;
+      const available = num(payload.availableBalance);
+      const cash = num(payload.cashBalance);
+      const creditLimit = num(payload.creditLimit);
+      const windows = [
+        usdWindow({
+          id: 'novita:available',
+          label: 'Available balance',
+          remaining: available !== undefined ? available * scale : undefined,
+          limit: creditLimit !== undefined ? creditLimit * scale : undefined,
+        }),
+      ];
+      if (cash !== undefined) {
+        windows.push(usdWindow({ id: 'novita:cash', label: 'Topped-up balance', remaining: cash * scale }));
+      }
+      return windows;
+    },
+  },
+  {
+    // DeepInfra: GET /payment/key-limits → one entry per API key with the
+    // monthly spending limit and what that key has spent this month.
+    slug: 'deepinfra',
+    envKey: 'DEEPINFRA_TOKEN',
+    url: 'https://api.deepinfra.com/payment/key-limits',
+    parse: (payload) => {
+      if (!Array.isArray(payload)) throw new Error('unexpected balance response');
+      const windows: UsageLimitWindow[] = [];
+      for (const entry of payload) {
+        if (!isRecord(entry)) continue;
+        const name = typeof entry.name === 'string' && entry.name ? entry.name : 'API key';
+        const limit = num(entry.limit);
+        const spend = num(entry.spend);
+        windows.push(usdWindow({
+          id: `deepinfra:${typeof entry.token_id === 'string' ? entry.token_id : name}`,
+          label: `${name} · monthly`,
+          used: spend,
+          limit,
+          remaining: limit !== undefined && spend !== undefined ? Math.max(0, limit - spend) : undefined,
+          note: limit === undefined ? 'No monthly limit is set on this key.' : undefined,
+        }));
+      }
+      return windows;
+    },
+  },
+];
+
+/** Balance adapters keyed by slug, for callers that need the table. */
+export const BALANCE_ADAPTER_SLUGS: readonly string[] = ADAPTERS.map((adapter) => adapter.slug);
+
+function adapterFor(slug: string): BalanceAdapter | undefined {
+  return ADAPTERS.find((adapter) => adapter.slug === slug);
+}
+
+/**
+ * Map a vendor's balance payload into quota windows, or null when the slug has
+ * no adapter. Exported so the field mapping (the part that breaks when a vendor
+ * changes its schema) is unit-testable without a network call.
+ */
+export function parseVendorBalance(slug: string, payload: unknown): UsageLimitWindow[] | null {
+  const adapter = adapterFor(slug);
+  if (!adapter) return null;
+  return adapter.parse(payload);
+}
+
+/**
+ * The provider's key: the chamber overlay first, then omp's own stores, then
+ * the environment variable omp itself reads. The env fallback matters because a
+ * key can live only in the user's shell (omp picks it up there), which no store
+ * on disk would reveal.
+ */
+async function resolveVendorKey(adapter: BalanceAdapter): Promise<string | null> {
+  for (const entry of await loadProviderEntries()) {
+    const slug = (entry.slug || entry.name).trim().toLowerCase();
+    const key = entry.apiKey.trim();
+    if (slug === adapter.slug && key && !MASKED_KEY_PATTERN.test(key)) return key;
+  }
+  const stored = await readOmpProviderApiKey(adapter.slug);
+  if (stored) return stored;
+  const fromEnv = Bun.env[adapter.envKey];
+  return fromEnv && fromEnv.trim() ? fromEnv.trim() : null;
+}
+
+export interface VendorBalance {
+  limits: UsageLimitWindow[];
+  error?: string;
+}
+
+/**
+ * Fetch a vendor balance. Returns null when the provider has no balance
+ * adapter, or when no credential could be resolved (a provider omp reports
+ * through an env var the chamber was not launched with is a silent miss, not an
+ * error — the caller already knows the credential exists somewhere).
+ */
+export async function fetchVendorBalance(slug: string): Promise<VendorBalance | null> {
+  const adapter = adapterFor(slug);
+  if (!adapter) return null;
+  const apiKey = await resolveVendorKey(adapter);
+  if (!apiKey) return null;
+  try {
+    const response = await fetch(adapter.url, {
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (response.status === 401 || response.status === 403) {
+      return { limits: [], error: `${adapter.slug} rejected the API key (HTTP ${response.status}).` };
+    }
+    if (response.status < 200 || response.status >= 300) {
+      return { limits: [], error: `${adapter.slug} balance request failed (HTTP ${response.status}).` };
+    }
+    const limits = adapter.parse(await response.json());
+    return { limits };
+  } catch (error) {
+    return {
+      limits: [],
+      error: error instanceof Error ? error.message : `${adapter.slug} balance request failed`,
+    };
+  }
+}

package/src/server/plugins/shell.server.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The HTML shell, rendered by Bun's own HTML pipeline.
+ *
+ * The shell used to be a file the bundler wrote and the server read back
+ * (`dist/client/index.html`). It is now a route Bun bundles and renders: the
+ * `index.html` import carries a manifest of hashed assets, and fetching the
+ * shell route returns that markup with the correct script and stylesheet tags
+ * for the current build — which is also what keeps the dev HMR client injected.
+ *
+ * The round-trip through the local listener is deliberate. Bun renders an HTML
+ * route only when serving it, and there is no API to render an `HTMLBundle` in
+ * process: `new Response(bundle)` yields the string "[object HTMLBundle]" and
+ * `app.handle('/_shell')` answers 404, because the route lives in `Bun.serve`'s
+ * own routing table rather than Elysia's (verified against Bun 1.4.2). Fetching
+ * our own listener is the supported way to obtain the markup.
+ *
+ * The server reference is injected rather than imported to avoid a cycle:
+ * `index.ts` owns the listener and imports `ssrRoutes`, which reaches here.
+ */
+
+import { SHELL_ROUTE } from '@/server/lib/lifecycle/shell-route';
+
+type ShellSource = { url: URL } | null;
+
+let source: ShellSource = null;
+
+/** Called by the server entry once its listener is up. */
+export function setShellSource(server: { url: URL }): void {
+  source = server;
+}
+
+export type ShellRender = { ok: true; html: string } | { ok: false; reason: string };
+
+/**
+ * The current shell markup, or a reason it could not be produced.
+ *
+ * Never cached: Bun re-renders the route per request in development, and in
+ * production the manifest is already in memory — a cache here would be the one
+ * thing that could serve markup pointing at a previous build's asset hashes.
+ */
+export async function renderShell(): Promise<ShellRender> {
+  if (!source) return { ok: false, reason: 'The HTTP listener is not up yet.' };
+  try {
+    const response = await fetch(new URL(SHELL_ROUTE, source.url));
+    if (!response.ok) return { ok: false, reason: `Shell route answered ${response.status}.` };
+    return { ok: true, html: await response.text() };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, reason: message };
+  }
+}