@astrosheep/pi-quota 0.5.0

package/README.md

@@ -0,0 +1,77 @@
+# @astrosheep/pi-quota
+
+Compact quota status for Pi: Codex, Kimi and OpenCode Go work out of the box; new-api, DeepSeek and Sub2API use explicit provider bindings.
+
+```bash
+pi install npm:@astrosheep/pi-quota
+```
+
+Reload Pi after installing or changing settings. Use `/usage` for a persistent, context-free snapshot in the chat history. Automatic footer polling never adds chat items.
+
+## What it shows
+
+| Kind | Footer | `/usage` |
+|---|---|---|
+| Renewable window | `5h [▆] 72% ↺ 2h15m` | Horizontal bar, remaining percentage, reset, exact amounts if available |
+| Wallet | `Bal $12.34` | Balance; optional Today/Lifetime spend |
+| Fixed quota | `Quota [▇] $85.00` | Remaining bar plus used and limit |
+
+A percentage always means **remaining**, not used. Unknown is `[?] ?`; an expired reset is `↺ due` with the stale percentage hidden until the next successful query. A wallet balance never becomes a percentage. Historical spend is not a quota.
+
+The footer shows at most two windows and `+N` for additional ones. `/usage` includes all windows; it does not open a modal or send messages to the model. Snapshots remain frozen at capture time. Errors replace stale values.
+
+## Configure providers
+
+Add bindings in global `~/.pi/agent/settings.json` under `quotaUsage` (not project settings):
+
+```json
+{
+  "quotaUsage": {
+    "providers": {
+      "my-sub2api": { "adapter": "sub2api" },
+      "my-new-api": { "adapter": "new-api", "quotaPerUnit": 500000, "currency": "USD" },
+      "deepseek": { "adapter": "deepseek" }
+    }
+  }
+}
+```
+
+Use the **exact Pi provider ID**. Only selected, explicitly bound providers are queried; built-in `openai-codex`, `kimi-coding` and `opencode-go` cannot be overridden. Unknown keys or adapter options are rejected. The API key and model `baseUrl` come from Pi's active provider auth; do not put model API keys in `quotaUsage`.
+
+| Adapter | Endpoint | Result |
+|---|---|---|
+| `sub2api` | `{baseUrl}/usage` | Wallet, key quota, rate windows or subscription day/week/month windows; API-key Today/Lifetime actual spend |
+| `new-api` | Account PAT `/api/user/self`, falling back to key-native billing/token endpoints | Account or key balance; **not** a renewable window |
+| `deepseek` | Official `/user/balance` | Balance only; no invented spend |
+
+Sub2API accepts no extra settings; it preserves deployment subpaths. Rate-only keys need not expose a top-level currency (rates are USD). Unknown rate-window durations and invalid limits fail rather than inventing a 1d window. Subscription periods without a cap are omitted. Its dashboard `/api/v1/usage` is a separate, JWT-authenticated paginated request log; the adapter uses the API-key `/v1/usage` instead.
+
+For new-api, `quotaPerUnit` defaults to `500000`, `currency` to `USD`. Optionally add `dashboardAccessToken` (console system access token) and `dashboardUserId` (positive numeric ID required by some old forks) to that provider. This PAT is the **only** optional secret kept in settings. The account endpoint takes precedence; failures fall back to the key-native billing and token usage paths. Without a PAT, an API key cannot read the dashboard account quota. Values in settings and server error bodies are never logged.
+
+Authenticated quota URLs must use HTTPS, except HTTP loopback for local deployments. URL userinfo, query strings, fragments and HTTP redirects are rejected; credentials never follow redirects. Fixed official endpoints reject custom origins. No browser cookie scraping or credential discovery.
+
+## Architecture
+
+```text
+Pi model/auth → adapter → QuotaSnapshot → controller → footer / /usage / state event
+```
+
+- `src/query/`: protocol-specific parsing, credential resolution, safe URLs, bounded GET client, state validation and controller. No Pi/TUI imports.
+- `src/config.ts`: strict global provider bindings.
+- `src/bar/`: pure compact rendering and persistent chat card.
+- `src/extension.ts` and `src/index.ts`: Pi lifecycle and auth bridge.
+
+`QuotaSnapshot` separates `balance` (wallet), `allowance` (finite key quota), `windows` (renewable limits), and optional `spend` (Today/Lifetime actual charge). This prevents unrelated amounts from sharing an ambiguous `Used` label. Custom adapters can be passed to `createQuotaExtension({ adapters: [...] })`; see `examples/custom-provider.ts`. Provider aliases are never inferred.
+
+The extension publishes structured state on `quota-bar:state:v1`. Use `createQuotaExtension({ footer: false })` to consume it without this extension's footer. Normal queries are throttled, cancellable, timeout-bounded and backed off after errors. `/usage` forces a fresh query. Switching provider discards old values immediately.
+
+## Development
+
+Requires Node ≥22.18 and a compatible Pi installation.
+
+```bash
+npm install --ignore-scripts
+npm test
+npm run typecheck
+npm run demo
+```

package/examples/custom-provider.ts

@@ -0,0 +1,30 @@
+// Template only. Replace the provider ID, fixed URL and schema for your service.
+// Load this entry INSTEAD OF src/index.ts, not alongside it.
+import { createQuotaExtension } from '../src/extension.ts';
+import { numeric, object, percent, timestamp } from '../src/query/parse.ts';
+import { QuotaError } from '../src/query/types.ts';
+import type { QuotaAdapter } from '../src/query/types.ts';
+
+const customAdapter: QuotaAdapter = {
+  provider: 'my-gateway',
+  label: 'My Gateway',
+  async query(context) {
+    // Resolve ONLY this provider's credentials. Never reuse Codex/Kimi credentials.
+    const auth = await context.getAuth(context.provider);
+    context.signal.throwIfAborted();
+    if (!auth?.apiKey) throw new QuotaError('auth');
+    // This deliberately nonfunctional domain must be replaced explicitly.
+    const data = object(await context.getJson('https://quota.example.invalid/v1/usage', {
+      Authorization: `Bearer ${auth.apiKey}`,
+    }, context.signal));
+    const remaining = numeric(data.remaining_percent);
+    if (remaining === null) throw new QuotaError('schema');
+    return {
+      fetchedAt: context.now(),
+      windows: [{ id: 'daily', label: '1d', durationSeconds: 86400,
+        remainingPercent: percent(remaining), resetAt: timestamp(data.reset_at) }],
+    };
+  },
+};
+
+export default createQuotaExtension({ adapters: [customAdapter] });

package/examples/preview.ts

@@ -0,0 +1,30 @@
+// Offline mock: no credentials, no HTTP, no Pi session.
+import { renderBar } from '../src/bar/bar.ts';
+import type { Paint } from '../src/bar/bar.ts';
+import { quotaElement, renderFooter, renderUsage } from '../src/bar/quota.ts';
+import type { QuotaState } from '../src/query/types.ts';
+
+const now = Date.now();
+const colors = { text: 39, dim: 90, success: 32, warning: 33, error: 31 };
+const paint: Paint = process.env.NO_COLOR !== undefined ? (_tone, text) => text
+  : (tone, text) => `\x1b[${colors[tone]}m${text}\x1b[0m`;
+function mock(short: number, weekly: number): QuotaState {
+  return { kind: 'ready', provider: 'openai-codex', label: 'Codex', snapshot: {
+    fetchedAt: now, windows: [
+      { id: '5h', label: '5h', durationSeconds: 18000, remainingPercent: short, resetAt: now + 8100000 },
+      { id: '1w', label: '1w', durationSeconds: 604800, remainingPercent: weekly, resetAt: now + 442800000 },
+    ],
+  } };
+}
+console.log('MOCK DATA — no live queries\n');
+for (const [short, weekly] of [[72, 85], [25, 60], [8, 50], [0, 50]]) {
+  console.log(renderFooter(mock(short, weekly), paint, now));
+}
+console.log('\n/usage\n');
+console.log(renderUsage(mock(72, 85), paint, now).join('\n'));
+console.log('\nComposed bar\n');
+console.log(renderBar([
+  { id: 'context', spans: [{ text: 'ctx [▃] 32%', tone: 'dim' }] },
+  quotaElement(mock(72, 85), now),
+  { id: 'git', spans: [{ text: 'main', tone: 'dim' }] },
+], paint));

package/examples/settings.fragment.json

@@ -0,0 +1,15 @@
+{
+  "providers": {
+    "my-new-api": {
+      "adapter": "new-api",
+      "quotaPerUnit": 500000,
+      "currency": "USD"
+    },
+    "deepseek": {
+      "adapter": "deepseek"
+    },
+    "my-sub2api": {
+      "adapter": "sub2api"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@astrosheep/pi-quota",
+  "version": "0.5.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "Composable quota bar with Codex, Kimi, OpenCode Go, new-api, DeepSeek and Sub2API adapters",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "examples",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "demo": "node examples/preview.ts"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/bar/balance.ts

@@ -0,0 +1,57 @@
+import { horizontalBar, remainingTone, verticalBar } from './bar.ts';
+import type { AccountBalance, QuotaAllowance, SpendSummary } from '../query/types.ts';
+import type { Paint, Span } from './bar.ts';
+
+export function money(amount: number, currency: string): string {
+  const sign = amount < 0 ? '-' : '';
+  const prefix = currency === 'USD' ? '$' : `${currency} `;
+  const absolute = Math.abs(amount);
+  if (absolute > 0 && absolute < 0.01) return `${sign}<${prefix}0.01`;
+  return `${sign}${prefix}${absolute.toFixed(2)}`;
+}
+
+export function remainingMoney(balance: AccountBalance): string {
+  if (balance.unlimited === true) return balance.currency === 'USD' ? '$∞' : `${balance.currency} ∞`;
+  return money(balance.remaining, balance.currency);
+}
+
+export function balanceSpans(balance: AccountBalance): Span[] {
+  return [
+    { text: 'Bal ', tone: 'dim' },
+    { text: remainingMoney(balance), tone: !balance.unlimited && balance.remaining <= 0 ? 'error' : 'text' },
+  ];
+}
+
+export function balanceLines(balance: AccountBalance, paint: Paint): string[] {
+  const remaining = remainingMoney(balance);
+  return [paint('dim', 'Balance   ') + paint(!balance.unlimited && balance.remaining <= 0 ? 'error' : 'text', remaining)];
+}
+
+export function allowancePercent(allowance: QuotaAllowance): number {
+  return Math.max(0, Math.min(100, allowance.remaining / allowance.limit * 100));
+}
+
+export function allowanceSpans(allowance: QuotaAllowance): Span[] {
+  const remaining = allowancePercent(allowance);
+  return [
+    { text: 'Quota ', tone: 'dim' },
+    { text: `${verticalBar(remaining)} ${money(allowance.remaining, allowance.currency)}`, tone: remainingTone(remaining) },
+  ];
+}
+
+export function allowanceLines(allowance: QuotaAllowance, paint: Paint, barWidth: number): string[] {
+  const remaining = allowancePercent(allowance);
+  return [
+    paint(remainingTone(remaining), horizontalBar(remaining, barWidth))
+      + paint('dim', `  ${money(allowance.remaining, allowance.currency)} left`),
+    paint('dim', `Used      ${money(allowance.used, allowance.currency)}`),
+    paint('dim', `Limit     ${money(allowance.limit, allowance.currency)}`),
+  ];
+}
+
+export function spendLines(spend: SpendSummary, paint: Paint): string[] {
+  const lines: string[] = [];
+  if (spend.today !== undefined) lines.push(paint('dim', `Today     ${money(spend.today, spend.currency)}`));
+  if (spend.lifetime !== undefined) lines.push(paint('dim', `Lifetime  ${money(spend.lifetime, spend.currency)}`));
+  return lines;
+}

package/src/bar/bar.ts

@@ -0,0 +1,50 @@
+// A bar composes independent, already-computed elements. It never queries providers.
+export type Tone = 'text' | 'dim' | 'success' | 'warning' | 'error';
+export interface Span { text: string; tone?: Tone }
+export interface BarElement { id: string; spans: readonly Span[] }
+export type Paint = (tone: Tone, text: string) => string;
+export const plain: Paint = (_tone, text) => text;
+
+export function renderBar(elements: readonly BarElement[], paint: Paint = plain): string {
+  const parts = elements.filter(element => element.spans.length > 0).map(element =>
+    element.spans.map(span => paint(span.tone ?? 'text', span.text)).join(''));
+  // Explicit trailing space is part of the public rendering contract.
+  return parts.length ? parts.join(paint('dim', ' │ ')) + ' ' : '';
+}
+
+export function remainingTone(value: number | null): Tone {
+  return value === null ? 'dim' : value <= 10 ? 'error' : value <= 30 ? 'warning' : 'success';
+}
+
+export function verticalBar(value: number | null): string {
+  if (value === null || !Number.isFinite(value)) return '[?]';
+  if (value <= 0) return '[·]';
+  if (value >= 100) return '[█]';
+  const height = Math.max(1, Math.min(7, Math.round(value * 8 / 100)));
+  return `[${'▁▂▃▄▅▆▇'[height - 1]}]`;
+}
+
+export function horizontalBar(value: number | null, width = 20): string {
+  width = Math.max(1, Math.min(80, Math.floor(width) || 20));
+  if (value === null || !Number.isFinite(value)) return `[${'░'.repeat(width)}]`;
+  const filled = value >= 100 ? width : value <= 0 ? 0
+    : Math.min(width - 1, Math.round(value / 100 * width));
+  return `[${'█'.repeat(filled)}${'░'.repeat(width - filled)}]`;
+}
+
+export function formatPercent(value: number | null): string {
+  if (value === null) return '?';
+  const rounded = value > 0 && value < 100
+    ? Math.max(0.1, Math.min(99.9, Math.round(value * 10) / 10)) : value;
+  return `${rounded}%`;
+}
+
+export function duration(ms: number): string {
+  if (ms <= 0) return 'due';
+  if (ms < 60000) return '<1m';
+  const minutes = Math.floor(ms / 60000);
+  const days = Math.floor(minutes / 1440);
+  const hours = Math.floor((minutes % 1440) / 60);
+  if (days) return `${days}d${hours ? `${hours}h` : ''}`;
+  return `${hours ? `${hours}h` : ''}${minutes % 60 ? `${minutes % 60}m` : ''}`;
+}

package/src/bar/card.ts

@@ -0,0 +1,35 @@
+import { Text } from '@earendil-works/pi-tui';
+import type { Component } from '@earendil-works/pi-tui';
+import type { Paint } from './bar.ts';
+import { renderUsage } from './quota.ts';
+import type { QuotaState } from '../query/types.ts';
+
+export const USAGE_ENTRY = 'quota-bar:usage:v1';
+
+export interface UsageCard {
+  version: 1;
+  capturedAt: number;
+  state: Exclude<QuotaState, { kind: 'loading' }>;
+}
+
+export function captureUsage(state: QuotaState, now = Date.now()): UsageCard | undefined {
+  if (state.kind === 'loading') return undefined;
+  // Separate the persistent entry from the live controller's state/objects.
+  return { version: 1, capturedAt: now, state: structuredClone(state) };
+}
+
+export function usageCardComponent(card: UsageCard | undefined, paint?: Paint): Component {
+  return {
+    render(width: number): string[] {
+      if (width <= 0) return [];
+      if (!card || card.version !== 1 || !Number.isFinite(card.capturedAt)) {
+        return new Text('Usage snapshot unavailable.', 0, 0).render(width);
+      }
+      // Rebuild on every render for theme/width changes, but freeze time at capture.
+      const lines = renderUsage(card.state, paint, card.capturedAt, width < 55 ? 10 : 20);
+      // Wrapping, not clipping: long quota names remain readable in narrow terminals.
+      return new Text(lines.join('\n'), 0, 0).render(width);
+    },
+    invalidate() {},
+  };
+}

package/src/bar/quota.ts

@@ -0,0 +1,94 @@
+import { visibleWidth } from '@earendil-works/pi-tui';
+import { duration, formatPercent, horizontalBar, plain, remainingTone, renderBar, verticalBar } from './bar.ts';
+import type { BarElement, Paint, Span } from './bar.ts';
+import { allowanceLines, allowanceSpans, balanceLines, balanceSpans, money, spendLines } from './balance.ts';
+import type { QuotaErrorCode, QuotaState, QuotaWindow } from '../query/types.ts';
+
+const errorText: Record<QuotaErrorCode, string> = {
+  auth: 'Sign in with /login',
+  'unsupported-auth': 'Unsupported credentials or endpoint',
+  'account-access': 'Account quota access denied',
+  network: 'Network error', timeout: 'Request timed out',
+  'rate-limit': 'Rate limited', http: 'Service unavailable', schema: 'Unrecognized quota response',
+};
+
+function windowSpans(window: QuotaWindow, now: number): Span[] {
+  const expired = window.resetAt !== null && window.resetAt <= now;
+  // Reaching the reset deadline is not proof the provider granted a fresh quota.
+  const remaining = expired ? null : window.remainingPercent;
+  const glyph = verticalBar(remaining);
+  return [
+    { text: `${window.scope ? `${window.scope}/` : ''}${window.label} `, tone: 'dim' },
+    { text: `${glyph} ${formatPercent(remaining)}`, tone: remainingTone(remaining) },
+    { text: ` ↺ ${window.resetAt === null ? '?' : duration(window.resetAt - now)}`, tone: 'dim' },
+  ];
+}
+
+export function quotaElement(state: QuotaState, now = Date.now()): BarElement {
+  const element: BarElement = { id: 'quota', spans: [] };
+  if (state.kind === 'hidden') return element;
+  if (state.kind === 'loading') return { ...element, spans: [{ text: 'Quota …', tone: 'dim' }] };
+  if (state.kind === 'error') return { ...element, spans: [{ text: `Quota ! ${errorText[state.code]}`, tone: 'warning' }] };
+  const windows = state.snapshot.windows;
+  const shared = windows.filter(window => !window.scope);
+  const shown = (shared.length ? shared : windows).slice(0, 2);
+  const spans: Span[] = state.snapshot.balance ? balanceSpans(state.snapshot.balance)
+    : state.snapshot.allowance ? allowanceSpans(state.snapshot.allowance) : [];
+  for (const window of shown) {
+    if (spans.length) spans.push({ text: ' · ', tone: 'dim' });
+    spans.push(...windowSpans(window, now));
+  }
+  if (windows.length > shown.length) spans.push({ text: ` +${windows.length - shown.length}`, tone: 'dim' });
+  return { ...element, spans };
+}
+
+export function renderFooter(state: QuotaState, paint: Paint = plain, now = Date.now()): string {
+  return renderBar([quotaElement(state, now)], paint);
+}
+
+export function renderUsage(state: QuotaState, paint: Paint = plain, now = Date.now(), barWidth = 20): string[] {
+  if (state.kind === 'hidden') return ['No quota adapter for the current provider.'];
+  const balanceOnly = state.kind === 'ready' && state.snapshot.balance
+    && !state.snapshot.allowance && state.snapshot.windows.length === 0;
+  const spendOnly = state.kind === 'ready' && state.snapshot.spend
+    && !state.snapshot.balance && !state.snapshot.allowance && state.snapshot.windows.length === 0;
+  const title = `${state.label} · ${balanceOnly ? (state.snapshot.spend ? 'Account' : 'Balance')
+    : spendOnly ? 'Usage' : 'Remaining quota'}`;
+  if (state.kind === 'loading') return [title, '', 'Loading…'];
+  if (state.kind === 'error') return [title, '', errorText[state.code]];
+  const rows = state.snapshot.windows.map(window => {
+    const remaining = window.resetAt !== null && window.resetAt <= now ? null : window.remainingPercent;
+    return {
+      label: `${window.scope ? `${window.scope}/` : ''}${window.label}`,
+      remaining,
+      value: formatPercent(remaining),
+      reset: window.resetAt === null ? '?' : duration(window.resetAt - now),
+      amounts: window.amounts,
+    };
+  });
+  const labelWidth = Math.max(0, ...rows.map(row => visibleWidth(row.label)));
+  const valueWidth = Math.max(4, ...rows.map(row => visibleWidth(row.value)));
+  const lines = [title, '', ...rows.map(row => {
+    const label = row.label + ' '.repeat(labelWidth - visibleWidth(row.label));
+    const value = ' '.repeat(valueWidth - visibleWidth(row.value)) + row.value;
+    const tone = remainingTone(row.remaining);
+    return paint('dim', `${label}  `)
+      + paint(tone, `${horizontalBar(row.remaining, barWidth)} ${value}`)
+      + paint('dim', ` ↺ ${row.reset}${row.amounts
+        ? ` · ${money(row.amounts.remaining, row.amounts.currency)}/${money(row.amounts.limit, row.amounts.currency)}`
+        : ''}`);
+  })];
+  if (state.snapshot.allowance) {
+    if (rows.length) lines.push('');
+    lines.push(...allowanceLines(state.snapshot.allowance, paint, barWidth));
+  }
+  if (state.snapshot.balance) {
+    if (rows.length || state.snapshot.allowance) lines.push('');
+    lines.push(...balanceLines(state.snapshot.balance, paint));
+  }
+  if (state.snapshot.spend) {
+    if (rows.length || state.snapshot.allowance || state.snapshot.balance) lines.push('');
+    lines.push(...spendLines(state.snapshot.spend, paint));
+  }
+  return lines;
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+import { createDeepSeekAdapter } from './query/deepseek.ts';
+import { createNewApiAdapter, validateNewApiOptions } from './query/new-api.ts';
+import { createSub2ApiAdapter } from './query/sub2api.ts';
+import type { NewApiOptions } from './query/new-api.ts';
+import type { QuotaAdapter } from './query/types.ts';
+
+export type ProviderQuotaConfig =
+  | ({ adapter: 'new-api'; quotaPerUnit: number; currency: string } & Pick<NewApiOptions, 'dashboardAccessToken' | 'dashboardUserId'>)
+  | { adapter: 'deepseek' | 'sub2api' };
+export interface QuotaConfig { providers: Record<string, ProviderQuotaConfig> }
+
+const DASHBOARD_KEYS = ['dashboardAccessToken', 'dashboardUserId'] as const;
+
+function parseDashboardOptions(item: Record<string, unknown>): Pick<NewApiOptions, 'dashboardAccessToken' | 'dashboardUserId'> {
+  const result: Pick<NewApiOptions, 'dashboardAccessToken' | 'dashboardUserId'> = {};
+  if (item.dashboardAccessToken !== undefined) {
+    if (typeof item.dashboardAccessToken !== 'string' || item.dashboardAccessToken.trim() === '') throw new QuotaConfigError();
+    result.dashboardAccessToken = item.dashboardAccessToken;
+  }
+  if (item.dashboardUserId !== undefined) {
+    if (typeof item.dashboardUserId !== 'number'
+      || !Number.isSafeInteger(item.dashboardUserId) || item.dashboardUserId <= 0) throw new QuotaConfigError();
+    result.dashboardUserId = item.dashboardUserId;
+  }
+  return result;
+}
+
+export class QuotaConfigError extends Error {
+  constructor() {
+    // Settings may accidentally contain secrets. Never echo content/values.
+    super('Invalid settings.json quotaUsage. Use providers with adapter "new-api", "deepseek" or "sub2api".');
+  }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function parseQuotaConfig(value: unknown): QuotaConfig {
+  if (!record(value) || Object.keys(value).some(key => key !== 'providers')
+    || !record(value.providers) || Object.keys(value.providers).length > 64) throw new QuotaConfigError();
+  const providers: Record<string, ProviderQuotaConfig> = Object.create(null);
+  for (const [provider, item] of Object.entries(value.providers)) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(provider)
+      || ['openai-codex', 'kimi-coding', 'opencode-go'].includes(provider)
+      || !record(item)) throw new QuotaConfigError();
+    if (item.adapter === 'deepseek') {
+      if (Object.keys(item).some(key => key !== 'adapter')) throw new QuotaConfigError();
+      providers[provider] = { adapter: 'deepseek' };
+      continue;
+    }
+    if (item.adapter === 'sub2api') {
+      if (Object.keys(item).length !== 1) throw new QuotaConfigError();
+      providers[provider] = { adapter: 'sub2api' };
+      continue;
+    }
+    if (item.adapter !== 'new-api'
+      || Object.keys(item).some(key => !['adapter', 'quotaPerUnit', 'currency', ...DASHBOARD_KEYS].includes(key))
+      || (item.quotaPerUnit !== undefined && typeof item.quotaPerUnit !== 'number')
+      || (item.currency !== undefined && typeof item.currency !== 'string')) throw new QuotaConfigError();
+    try {
+      const settings = validateNewApiOptions({ quotaPerUnit: item.quotaPerUnit, currency: item.currency });
+      providers[provider] = { adapter: 'new-api', ...settings, ...parseDashboardOptions(item) };
+    } catch { throw new QuotaConfigError(); }
+  }
+  return { providers };
+}
+
+export function loadQuotaAdaptersFromSettings(settings: unknown): QuotaAdapter[] {
+  if (!record(settings) || settings.quotaUsage === undefined) return [];
+  const config = parseQuotaConfig(settings.quotaUsage);
+  return Object.entries(config.providers).map(([provider, options]) => {
+    switch (options.adapter) {
+      case 'deepseek': return createDeepSeekAdapter(provider);
+      case 'sub2api': return createSub2ApiAdapter(provider);
+      case 'new-api': return createNewApiAdapter(provider, options);
+    }
+  });
+}

package/src/extension.ts

@@ -0,0 +1,152 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { renderFooter, renderUsage } from './bar/quota.ts';
+import { captureUsage, USAGE_ENTRY, usageCardComponent } from './bar/card.ts';
+import type { UsageCard } from './bar/card.ts';
+import { codexAdapter } from './query/codex.ts';
+import { kimiAdapter } from './query/kimi.ts';
+import { openCodeGoAdapter } from './query/opencode-go.ts';
+import { QuotaController } from './query/controller.ts';
+import { createJsonClient } from './query/http.ts';
+import { AdapterRegistry } from './query/registry.ts';
+import type { ProviderAuth, QuotaAdapter } from './query/types.ts';
+
+export const STATUS_EVENT = 'quota-bar:state:v1';
+const STATUS_KEY = 'quota-bar';
+const USAGE_WIDGET = 'quota-bar:usage';
+
+export interface QuotaExtensionOptions {
+  adapters?: readonly QuotaAdapter[]; // Extra adapters; duplicate IDs are rejected.
+  footer?: boolean; // false: query + /usage + structured events only
+  intervalMs?: number;
+  timeoutMs?: number;
+}
+
+export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
+  return (pi: ExtensionAPI): void => {
+    const registry = new AdapterRegistry([codexAdapter, kimiAdapter, openCodeGoAdapter, ...(options.adapters ?? [])]);
+    let current: ExtensionContext | undefined;
+    let selectedProvider: string | undefined;
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let lastStatus: string | undefined;
+    // Invalidates pending commands on model/session replacement or another /usage.
+    let commandGeneration = 0;
+
+    pi.registerEntryRenderer<UsageCard>(USAGE_ENTRY, (entry, _options, theme) => {
+      const paint = process.env.NO_COLOR !== undefined ? undefined
+        : (tone: Parameters<typeof theme.fg>[0], text: string) => theme.fg(tone, text);
+      return usageCardComponent(entry.data, paint);
+    });
+
+    const paintFooter = () => {
+      if (!current?.hasUI || options.footer === false) return;
+      try {
+        const ctx = current;
+        const paint = process.env.NO_COLOR !== undefined ? undefined
+          : (tone: Parameters<typeof ctx.ui.theme.fg>[0], text: string) => ctx.ui.theme.fg(tone, text);
+        const text = renderFooter(controller.state, paint) || undefined;
+        if (text !== lastStatus) {
+          ctx.ui.setStatus(STATUS_KEY, text);
+          lastStatus = text;
+        }
+      } catch {
+        // Stale session contexts must not keep a background polling loop alive.
+        current = undefined;
+        commandGeneration++;
+        if (timer) clearInterval(timer);
+        timer = undefined;
+        controller.stop();
+      }
+    };
+
+    const controller = new QuotaController({
+      registry, getJson: createJsonClient(), intervalMs: options.intervalMs, timeoutMs: options.timeoutMs,
+      onState(state) {
+        paintFooter();
+        pi.events.emit(STATUS_EVENT, state); // Structured data, no credentials or ANSI.
+      },
+    });
+
+    const refresh = (force = false): Promise<void> => {
+      const ctx = current;
+      if (!ctx?.hasUI) return Promise.resolve();
+      return controller.refresh(async provider => {
+        const resolved = await ctx.modelRegistry.getProviderAuth(provider);
+        if (!resolved) return undefined;
+        const headers: Record<string, string | undefined> = {};
+        for (const [name, value] of Object.entries(resolved.auth.headers ?? {})) {
+          if (typeof value === 'string') headers[name] = value;
+        }
+        const auth: ProviderAuth = { ...resolved.auth, headers };
+        // A model-level custom endpoint must not be mistaken for an official account.
+        if (ctx.model?.provider === provider && ctx.model.baseUrl) auth.baseUrl = ctx.model.baseUrl;
+        return auth;
+      }, force);
+    };
+
+    const bind = (ctx: ExtensionContext, select = false, provider = ctx.model?.provider) => {
+      current = ctx;
+      if (!ctx.hasUI) return;
+      if (select || provider !== selectedProvider) {
+        commandGeneration++;
+        if (ctx.mode === 'tui') ctx.ui.setWidget(USAGE_WIDGET, undefined);
+        selectedProvider = provider;
+        controller.select(provider);
+      }
+      void refresh();
+    };
+
+    pi.on('session_start', (_event, ctx) => {
+      lastStatus = undefined;
+      bind(ctx, true);
+      if (timer) clearInterval(timer);
+      if (ctx.hasUI) {
+        timer = setInterval(() => {
+          paintFooter(); // Local countdown/theme refresh, no extra HTTP request.
+          void refresh(); // Controller throttles queries and applies error backoff.
+        }, 10000);
+        timer.unref?.();
+      }
+    });
+    pi.on('model_select', (event, ctx) => bind(ctx, true, event.model.provider));
+    pi.on('turn_end', (_event, ctx) => bind(ctx));
+    pi.on('session_shutdown', (_event, ctx) => {
+      if (timer) clearInterval(timer);
+      timer = undefined;
+      current = undefined;
+      selectedProvider = undefined;
+      lastStatus = undefined;
+      commandGeneration++;
+      controller.stop();
+      if (ctx.hasUI && ctx.mode === 'tui') ctx.ui.setWidget(USAGE_WIDGET, undefined);
+      if (ctx.hasUI && options.footer !== false) ctx.ui.setStatus(STATUS_KEY, undefined);
+    });
+
+    pi.registerCommand('usage', {
+      description: 'Query current provider quota and add a snapshot to the chat history',
+      handler: async (_args, ctx) => {
+        if (!ctx.hasUI) return;
+        bind(ctx);
+        const generation = ++commandGeneration;
+        if (ctx.mode === 'tui') ctx.ui.setWidget(USAGE_WIDGET, ['Loading…']);
+        try {
+          await refresh(true);
+          // Never append via a stale Pi runtime, or label a replacement model's data
+          // as the result of the original command. A newer command owns its result.
+          if (!current || generation !== commandGeneration) return;
+          const card = captureUsage(controller.state);
+          if (!card) return;
+          pi.appendEntry<UsageCard>(USAGE_ENTRY, card);
+          // Custom entry renderers are TUI-only; RPC clients still get readable output.
+          if (ctx.mode !== 'tui') {
+            ctx.ui.notify(renderUsage(card.state, undefined, card.capturedAt).join('\n'), 'info');
+          }
+        } finally {
+          // An older request must not clear a newer command's loading indicator.
+          if (current && generation === commandGeneration && ctx.mode === 'tui') {
+            ctx.ui.setWidget(USAGE_WIDGET, undefined);
+          }
+        }
+      },
+    });
+  };
+}