@astrosheep/pi-quota 0.10.0 → 0.12.0

package/README.md

@@ -33,7 +33,8 @@ Add bindings in global `~/.pi/agent/settings.json` under `quotaUsage` (not proje
       "deepseek": { "adapter": "deepseek" },
       "opencode-go-2": { "adapter": "opencode-go" },
       "yes-vg": { "adapter": "yescode", "username": "you@example.com", "password": "..." },
-      "my-script": { "adapter": "exec", "command": ["my-quota-cli", "--json"], "label": "My Script" }
+      "my-script": { "adapter": "exec", "command": ["my-quota-cli", "--json"], "label": "My Script" },
+      "my-alias": { "adapter": "alias", "of": "my-sub2api" }
     }
   }
 }
@@ -49,6 +50,7 @@ Use the **exact Pi provider ID**. Built-in providers and explicitly bound provid
 | `opencode-go` | Official `https://opencode.ai/zen/go/v1/usage` | 5h/1w/30d windows, same as the built-in `opencode-go` adapter |
 | `yescode` | `co.yes.vg` login → session → `/api/v1/auth/profile` + `/api/v1/user/balance` | Wallet (subscription + pay-as-you-go) plus daily/weekly subscription windows |
 | `exec` | Runs `command` as argv (no shell), parses stdout as a `QuotaSnapshot` JSON | Whatever the command reports; `fetchedAt` is stamped by the adapter, never by the command |
+| `alias` | No endpoint — delegates to the `of` binding (built-in or explicit) | Shares the target account's quota; one folded row in `/usage` |
 
 Bind `opencode-go` to a second OpenCode Go account: register it as its own Pi provider in `models.json` with its own `apiKey` (e.g. `opencode-go-2`), then bind that ID here. The built-in `opencode-go` binding is implicit and needs no entry; the reserved IDs `openai-codex`, `kimi-coding` and `opencode-go` cannot be rebound.
 
@@ -60,6 +62,8 @@ For YesCode, `username` is the account email and `password` the account password
 
 Exec runs the configured argv without a shell and parses stdout as a `QuotaSnapshot` JSON object: `windows`, optional `balance`, `allowance` and `spend` — the same schema every adapter produces, enforced by the controller. `fetchedAt` is stamped by the adapter; a value from the command is ignored. The controller bounds every query (10s default) and kills the child on timeout; non-zero exits, unreadable JSON and output over 256KB become errors, and command output is never logged. The child inherits Pi's environment, so keep secrets in env vars, not in `quotaUsage`.
 
+Alias binds a second provider ID to the same account: `"of"` names the real binding, which may be a built-in or an explicit adapter. The alias never queries on its own — a session on the alias shows the target's quota in the footer, queried under the target's identity and credentials, and `/usage` folds the alias into the target's single row with the session pin (and ★) following the fold. Aliases are one hop: `of` must not itself be an alias, and an alias whose target is not configured fails visibly instead of vanishing.
+
 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
@@ -77,6 +81,28 @@ Pi model/auth → adapter → QuotaSnapshot → controller → footer / /usage /
 
 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 for every configured supported provider, then omits failed results from its default view. Switching provider discards old footer values immediately.
 
+## Standalone query layer
+
+Non-Pi consumers (bridges, plugins, scripts) can import the query layer without pulling in the Pi extension or its peer dependencies:
+
+```ts
+import {
+  AdapterRegistry, codexAdapter, createJsonClient, createPostJsonClient,
+} from '@astrosheep/pi-quota/query';
+
+const registry = new AdapterRegistry([codexAdapter]);
+const snapshot = await registry.get('openai-codex')!.query({
+  provider: 'openai-codex',
+  signal: AbortSignal.timeout(10_000),
+  now: () => Date.now(),
+  getAuth: myAuthResolver,      // you supply credentials
+  getJson: createJsonClient(),
+  postJson: createPostJsonClient(),
+});
+```
+
+The subpath exports every adapter, the registry/controller, option validators, HTTP/exec plumbing, and all query types. Peer dependencies are marked optional, so installing for the query layer alone stays light.
+
 ## Development
 
 Requires Node ≥22.18 and a compatible Pi installation.

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@astrosheep/pi-quota",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./query": "./src/query/index.ts",
+    "./package.json": "./package.json"
+  },
   "description": "Composable quota bar with Codex, Kimi, OpenCode Go, new-api, DeepSeek, Sub2API and YesCode adapters",
   "keywords": [
     "pi-package"
@@ -31,6 +36,10 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true }
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^6.0.3"

package/src/bar/quota.ts

@@ -3,6 +3,7 @@ import { duration, formatPercent, horizontalBar, plain, remainingTone, renderBar
 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';
+import type { FooterWindows } from '../query/settings.ts';
 
 const errorText: Record<QuotaErrorCode, string> = {
   auth: 'Sign in with /login',
@@ -25,7 +26,7 @@ function windowSpans(window: QuotaWindow, now: number): Span[] {
 }
 
 // Footer window cap: a positive count, or 'all' for every shared window.
-export type FooterWindows = number | 'all';
+export type { FooterWindows };
 
 export function quotaElement(state: QuotaState, now = Date.now(), maxWindows: FooterWindows = 2): BarElement {
   const element: BarElement = { id: 'quota', spans: [] };

package/src/config.ts

@@ -1,121 +1,11 @@
-import { createDeepSeekAdapter } from './query/deepseek.ts';
-import { createExecAdapter, validateExecOptions } from './query/exec.ts';
-import { createNewApiAdapter, validateNewApiOptions } from './query/new-api.ts';
-import { createOpenCodeGoAdapter } from './query/opencode-go.ts';
-import { createSub2ApiAdapter } from './query/sub2api.ts';
-import { createYesCodeAdapter, validateYesCodeOptions } from './query/yescode.ts';
-import type { NewApiOptions } from './query/new-api.ts';
-import type { YesCodeOptions } from './query/yescode.ts';
-import type { QuotaAdapter } from './query/types.ts';
-import type { FooterWindows } from './bar/quota.ts';
-
-export type ProviderQuotaConfig =
-  | ({ adapter: 'new-api'; quotaPerUnit: number; currency: string } & Pick<NewApiOptions, 'dashboardAccessToken' | 'dashboardUserId'>)
-  | ({ adapter: 'yescode' } & YesCodeOptions)
-  | { adapter: 'exec'; command: string[]; label: string }
-  | { adapter: 'deepseek' | 'sub2api' | 'opencode-go' };
-export interface QuotaConfig { providers: Record<string, ProviderQuotaConfig>; footerWindows?: FooterWindows }
-
-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;
-}
-
-function parseFooterWindows(value: unknown): FooterWindows {
-  if (value === 'all') return value;
-  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 1) return value;
-  throw new QuotaConfigError();
-}
-
-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", "sub2api", "opencode-go", "yescode" or "exec", and optionally footerWindows as a positive integer or "all".');
-  }
-}
-
-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' && key !== 'footerWindows')
-    || !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' || item.adapter === 'opencode-go') {
-      if (Object.keys(item).length !== 1) throw new QuotaConfigError();
-      providers[provider] = { adapter: item.adapter };
-      continue;
-    }
-    if (item.adapter === 'yescode') {
-      if (Object.keys(item).some(key => !['adapter', 'username', 'password'].includes(key))
-        || typeof item.username !== 'string' || typeof item.password !== 'string') throw new QuotaConfigError();
-      try {
-        providers[provider] = { adapter: 'yescode',
-          ...validateYesCodeOptions({ username: item.username, password: item.password }) };
-      } catch { throw new QuotaConfigError(); }
-      continue;
-    }
-    if (item.adapter === 'exec') {
-      if (Object.keys(item).some(key => !['adapter', 'command', 'label'].includes(key))) throw new QuotaConfigError();
-      try {
-        providers[provider] = { adapter: 'exec', ...validateExecOptions(item) };
-      } catch { throw new QuotaConfigError(); }
-      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(); }
-  }
-  const config: QuotaConfig = { providers };
-  if (value.footerWindows !== undefined) config.footerWindows = parseFooterWindows(value.footerWindows);
-  return config;
-}
-
-export function loadQuotaFooterWindows(settings: unknown): FooterWindows | undefined {
-  if (!record(settings) || settings.quotaUsage === undefined) return undefined;
-  return parseQuotaConfig(settings.quotaUsage).footerWindows;
-}
-
-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 'opencode-go': return createOpenCodeGoAdapter(provider);
-      case 'yescode': return createYesCodeAdapter(provider, options);
-      case 'exec': return createExecAdapter(provider, options);
-      case 'new-api': return createNewApiAdapter(provider, options);
-    }
-  });
-}
-
-  // Explicit adapter bindings from quotaUsage already have adapters registered; listing every
-  // registered adapter is the boundary between quota providers and ordinary model providers.
+// Back-compatible surface: the implementation lives in the Pi-free query layer
+// (src/query/settings.ts) so non-Pi consumers can compose the same registry.
+export {
+  composeQuotaRegistry,
+  loadQuotaAdaptersFromSettings,
+  loadQuotaAliasesFromSettings,
+  loadQuotaFooterWindows,
+  parseQuotaConfig,
+  QuotaConfigError,
+} from './query/settings.ts';
+export type { ComposedQuota, FooterWindows, ProviderQuotaConfig, QuotaConfig } from './query/settings.ts';

package/src/extension.ts

@@ -3,13 +3,9 @@ import { renderFooter } from './bar/quota.ts';
 import type { FooterWindows } from './bar/quota.ts';
 import { captureAllUsage, USAGE_ENTRY, usageCardComponent, usageLines, compactUsageLines } from './bar/card.ts';
 import type { UsageCard } from './bar/card.ts';
-import { codexAdapter } from './query/codex.ts';
-import { createDeepSeekAdapter } from './query/deepseek.ts';
-import { kimiAdapter } from './query/kimi.ts';
-import { openCodeGoAdapter } from './query/opencode-go.ts';
 import { QuotaController } from './query/controller.ts';
 import { createJsonClient, createPostJsonClient } from './query/http.ts';
-import { AdapterRegistry } from './query/registry.ts';
+import { composeQuotaRegistry } from './query/settings.ts';
 import type { ProviderAuth, QuotaAdapter, QuotaState } from './query/types.ts';
 
 export const STATUS_EVENT = 'quota-bar:state:v1';
@@ -23,6 +19,7 @@ export interface QuotaExtensionOptions {
   // Explicit adapters replace matching built-ins; duplicate explicit IDs are rejected.
   adapters?: readonly QuotaAdapter[];
   providers?: readonly string[]; // Extra configured quota providers to include in /usage
+  aliases?: Record<string, string>; // alias provider → target provider; shares the target's account quota
   footer?: boolean; // false: query + /usage + structured events only
   footerWindows?: FooterWindows; // footer window cap; default 2, 'all' shows every window
   intervalMs?: number;
@@ -31,13 +28,8 @@ export interface QuotaExtensionOptions {
 
 export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
   return (pi: ExtensionAPI): void => {
-    const explicitAdapters = options.adapters ?? [];
-    const explicitProviderIds = new Set(explicitAdapters.map(adapter => adapter.provider));
     // Settings are deliberate user bindings, so they take precedence over defaults.
-    // AdapterRegistry still detects an ambiguous duplicate among explicit adapters.
-    const registry = new AdapterRegistry([
-      codexAdapter, kimiAdapter, openCodeGoAdapter, createDeepSeekAdapter('deepseek'),
-    ].filter(adapter => !explicitProviderIds.has(adapter.provider)).concat(explicitAdapters));
+    const { registry, aliases } = composeQuotaRegistry({ adapters: options.adapters, aliases: options.aliases });
     let current: ExtensionContext | undefined;
     let selectedProvider: string | undefined;
     let timer: ReturnType<typeof setInterval> | undefined;
@@ -119,7 +111,8 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
       add(ctx.model?.provider);
       for (const adapter of registry.list()) add(adapter.provider);
       for (const provider of options.providers ?? []) add(provider);
-      return providers;
+      // An alias absorbed by its queried target gets no row of its own.
+      return providers.filter(provider => aliases[provider] === undefined || !providers.includes(aliases[provider]));
     };
 
     const queryProvider = async (provider: string, getAuth: ReturnType<typeof resolveAuth>): Promise<QuotaState> => {
@@ -218,11 +211,16 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
           const states = await Promise.all(providers.map(provider => queryProvider(provider, getAuth)));
           // The session's own provider always leads, whatever its health looks like.
           const currentProvider = ctx.model?.provider;
+          // An alias session pins and stars the target's folded row instead.
+          const canonicalProvider = currentProvider === undefined ? undefined : (aliases[currentProvider] ?? currentProvider);
           const ordered = states
             .map((state, index) => ({ state, index }))
             .sort((a, b) => {
-              const pinned = (item: { state: QuotaState }) =>
-                currentProvider !== undefined && 'provider' in item.state && item.state.provider === currentProvider ? 0 : 1;
+              const pinned = (item: { state: QuotaState }) => {
+                if (currentProvider === undefined || !('provider' in item.state)) return 1;
+                const provider = item.state.provider;
+                return provider === currentProvider || provider === canonicalProvider ? 0 : 1;
+              };
               const rank = (state: QuotaState) => state.kind === 'error' ? 3
                 : state.kind === 'ready' && state.snapshot.windows.length > 0 ? 1
                 : 2;
@@ -234,7 +232,7 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
           if (!current || generation !== commandGeneration) return;
           const visibleStates = args.trim() === '--all'
             ? ordered : ordered.filter(state => state.kind === 'ready');
-          const card = captureAllUsage(visibleStates, Date.now(), currentProvider);
+          const card = captureAllUsage(visibleStates, Date.now(), canonicalProvider);
           hasUsageSnapshot = true;
           pi.appendEntry<UsageCard>(USAGE_ENTRY, card);
           // Custom entry renderers are TUI-only; RPC clients still get readable output.

package/src/index.ts

@@ -1,12 +1,13 @@
 import { getAgentDir, SettingsManager } from '@earendil-works/pi-coding-agent';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { createQuotaExtension } from './extension.ts';
-import { loadQuotaAdaptersFromSettings, loadQuotaFooterWindows, QuotaConfigError } from './config.ts';
+import { loadQuotaAdaptersFromSettings, loadQuotaAliasesFromSettings, loadQuotaFooterWindows, QuotaConfigError } from './config.ts';
 import type { FooterWindows } from './bar/quota.ts';
 import type { QuotaAdapter } from './query/types.ts';
 
 export default function (pi: ExtensionAPI): void {
   let adapters: QuotaAdapter[] = [];
+  let aliases: Record<string, string> = {};
   let footerWindows: FooterWindows | undefined;
   try {
     // Quota provider bindings belong to the user's global Pi settings. Project
@@ -16,6 +17,7 @@ export default function (pi: ExtensionAPI): void {
       projectTrusted: false,
     }).getGlobalSettings() as unknown;
     adapters = loadQuotaAdaptersFromSettings(settings);
+    aliases = loadQuotaAliasesFromSettings(settings);
     footerWindows = loadQuotaFooterWindows(settings);
   } catch {
     pi.on('session_start', (_event, ctx) => {
@@ -23,5 +25,5 @@ export default function (pi: ExtensionAPI): void {
     });
   }
   // Invalid optional settings never disable the built-in Codex/Kimi/OpenCode Go adapters.
-  createQuotaExtension({ adapters, footerWindows })(pi);
+  createQuotaExtension({ adapters, aliases, footerWindows })(pi);
 }

package/src/query/alias.ts

@@ -0,0 +1,20 @@
+import { QuotaError } from './types.ts';
+import type { QuotaAdapter } from './types.ts';
+
+// An alias provider shares another provider's account: the query runs under
+// the target's identity, so auth and endpoints resolve exactly as a direct
+// query of the target would. The alias never queries on its own behalf.
+export function createAliasAdapter(provider: string, target: QuotaAdapter): QuotaAdapter {
+  return {
+    provider, label: target.label,
+    query: context => target.query({ ...context, provider: target.provider }),
+  };
+}
+
+// A dangling alias stays visible as an error instead of silently vanishing.
+export function createDanglingAliasAdapter(provider: string): QuotaAdapter {
+  return {
+    provider, label: provider,
+    query: () => Promise.reject(new QuotaError('unsupported-auth')),
+  };
+}

package/src/query/index.ts

@@ -0,0 +1,23 @@
+// Public entry for the standalone query layer — no Pi, terminal, or rendering
+// dependencies. Consumers supply auth and transport through QueryContext.
+export * from './types.ts';
+export { AdapterRegistry, validateSnapshot } from './registry.ts';
+export { QuotaController } from './controller.ts';
+export { createJsonClient, createPostJsonClient, officialAuth, bearer, header } from './http.ts';
+export { createAliasAdapter, createDanglingAliasAdapter } from './alias.ts';
+export { createExecAdapter, validateExecOptions } from './exec.ts';
+export type { ExecOptions } from './exec.ts';
+export { codexAccountId, codexAdapter } from './codex.ts';
+export { kimiAdapter } from './kimi.ts';
+export { openCodeGoAdapter, createOpenCodeGoAdapter } from './opencode-go.ts';
+export { createDeepSeekAdapter, DEEPSEEK_ORIGIN } from './deepseek.ts';
+export { createNewApiAdapter, validateNewApiOptions } from './new-api.ts';
+export type { NewApiOptions } from './new-api.ts';
+export { createSub2ApiAdapter } from './sub2api.ts';
+export { createYesCodeAdapter, validateYesCodeOptions, YESCODE_ORIGIN } from './yescode.ts';
+export type { YesCodeOptions } from './yescode.ts';
+export {
+  composeQuotaRegistry, loadQuotaAdaptersFromSettings, loadQuotaAliasesFromSettings,
+  loadQuotaFooterWindows, parseQuotaConfig, QuotaConfigError,
+} from './settings.ts';
+export type { ComposedQuota, FooterWindows, ProviderQuotaConfig, QuotaConfig } from './settings.ts';

package/src/query/settings.ts

@@ -0,0 +1,179 @@
+import { createAliasAdapter, createDanglingAliasAdapter } from './alias.ts';
+import { codexAdapter } from './codex.ts';
+import { createDeepSeekAdapter } from './deepseek.ts';
+import { createExecAdapter, validateExecOptions } from './exec.ts';
+import { kimiAdapter } from './kimi.ts';
+import { createNewApiAdapter, validateNewApiOptions } from './new-api.ts';
+import { createOpenCodeGoAdapter, openCodeGoAdapter } from './opencode-go.ts';
+import { AdapterRegistry } from './registry.ts';
+import { createSub2ApiAdapter } from './sub2api.ts';
+import { createYesCodeAdapter, validateYesCodeOptions } from './yescode.ts';
+import type { NewApiOptions } from './new-api.ts';
+import type { YesCodeOptions } from './yescode.ts';
+import type { QuotaAdapter } from './types.ts';
+
+export type FooterWindows = number | 'all';
+
+export type ProviderQuotaConfig =
+  | ({ adapter: 'new-api'; quotaPerUnit: number; currency: string } & Pick<NewApiOptions, 'dashboardAccessToken' | 'dashboardUserId'>)
+  | ({ adapter: 'yescode' } & YesCodeOptions)
+  | { adapter: 'exec'; command: string[]; label: string }
+  | { adapter: 'alias'; of: string }
+  | { adapter: 'deepseek' | 'sub2api' | 'opencode-go' };
+export interface QuotaConfig { providers: Record<string, ProviderQuotaConfig>; footerWindows?: FooterWindows }
+
+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;
+}
+
+function parseFooterWindows(value: unknown): FooterWindows {
+  if (value === 'all') return value;
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 1) return value;
+  throw new QuotaConfigError();
+}
+
+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", "sub2api", "opencode-go", "yescode", "exec" or "alias", and optionally footerWindows as a positive integer or "all".');
+  }
+}
+
+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' && key !== 'footerWindows')
+    || !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' || item.adapter === 'opencode-go') {
+      if (Object.keys(item).length !== 1) throw new QuotaConfigError();
+      providers[provider] = { adapter: item.adapter };
+      continue;
+    }
+    if (item.adapter === 'yescode') {
+      if (Object.keys(item).some(key => !['adapter', 'username', 'password'].includes(key))
+        || typeof item.username !== 'string' || typeof item.password !== 'string') throw new QuotaConfigError();
+      try {
+        providers[provider] = { adapter: 'yescode',
+          ...validateYesCodeOptions({ username: item.username, password: item.password }) };
+      } catch { throw new QuotaConfigError(); }
+      continue;
+    }
+    if (item.adapter === 'exec') {
+      if (Object.keys(item).some(key => !['adapter', 'command', 'label'].includes(key))) throw new QuotaConfigError();
+      try {
+        providers[provider] = { adapter: 'exec', ...validateExecOptions(item) };
+      } catch { throw new QuotaConfigError(); }
+      continue;
+    }
+    if (item.adapter === 'alias') {
+      if (Object.keys(item).some(key => key !== 'adapter' && key !== 'of')
+        || typeof item.of !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(item.of)
+        || item.of === provider) throw new QuotaConfigError();
+      providers[provider] = { adapter: 'alias', of: item.of };
+      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(); }
+  }
+  const config: QuotaConfig = { providers };
+  if (value.footerWindows !== undefined) config.footerWindows = parseFooterWindows(value.footerWindows);
+  return config;
+}
+
+export function loadQuotaFooterWindows(settings: unknown): FooterWindows | undefined {
+  if (!record(settings) || settings.quotaUsage === undefined) return undefined;
+  return parseQuotaConfig(settings.quotaUsage).footerWindows;
+}
+
+export function loadQuotaAdaptersFromSettings(settings: unknown): QuotaAdapter[] {
+  if (!record(settings) || settings.quotaUsage === undefined) return [];
+  const config = parseQuotaConfig(settings.quotaUsage);
+  return Object.entries(config.providers).flatMap(([provider, options]) => {
+    switch (options.adapter) {
+      case 'alias': return []; // Aliases declare no adapter; extension.ts wires them.
+      case 'deepseek': return createDeepSeekAdapter(provider);
+      case 'sub2api': return createSub2ApiAdapter(provider);
+      case 'opencode-go': return createOpenCodeGoAdapter(provider);
+      case 'yescode': return createYesCodeAdapter(provider, options);
+      case 'exec': return createExecAdapter(provider, options);
+      case 'new-api': return createNewApiAdapter(provider, options);
+    }
+  });
+}
+
+export function loadQuotaAliasesFromSettings(settings: unknown): Record<string, string> {
+  if (!record(settings) || settings.quotaUsage === undefined) return {};
+  const config = parseQuotaConfig(settings.quotaUsage);
+  const aliases: Record<string, string> = Object.create(null);
+  for (const [provider, options] of Object.entries(config.providers)) {
+    if (options.adapter === 'alias') aliases[provider] = options.of;
+  }
+  return aliases;
+}
+
+export interface ComposedQuota {
+  registry: AdapterRegistry;
+  aliases: Record<string, string>;
+  footerWindows: FooterWindows | undefined;
+}
+
+/**
+ * The full quota surface in one place: built-in adapters, settings-bound adapters
+ * and aliases wired exactly as the Pi extension does. Settings are deliberate user
+ * bindings, so they take precedence over defaults; AdapterRegistry still detects an
+ * ambiguous duplicate among explicit adapters. Alias providers share their target's
+ * account: one hop only, and a dangling alias stays visible as an error instead of
+ * vanishing silently.
+ */
+export function composeQuotaRegistry(input: {
+  settings?: unknown;
+  adapters?: readonly QuotaAdapter[];
+  aliases?: Record<string, string>;
+} = {}): ComposedQuota {
+  const settingsAdapters = input.settings === undefined ? [] : loadQuotaAdaptersFromSettings(input.settings);
+  const explicitAdapters = [...settingsAdapters, ...(input.adapters ?? [])];
+  const aliases = { ...loadQuotaAliasesFromSettings(input.settings ?? {}), ...(input.aliases ?? {}) };
+  const explicitProviderIds = new Set([...explicitAdapters.map(adapter => adapter.provider), ...Object.keys(aliases)]);
+  const registry = new AdapterRegistry([
+    codexAdapter, kimiAdapter, openCodeGoAdapter, createDeepSeekAdapter('deepseek'),
+  ].filter(adapter => !explicitProviderIds.has(adapter.provider)).concat(explicitAdapters));
+  for (const [alias, targetId] of Object.entries(aliases)) {
+    const target = aliases[targetId] === undefined ? registry.get(targetId) : undefined;
+    registry.register(target ? createAliasAdapter(alias, target) : createDanglingAliasAdapter(alias));
+  }
+  return {
+    registry,
+    aliases,
+    footerWindows: input.settings === undefined ? undefined : loadQuotaFooterWindows(input.settings),
+  };
+}