@astrosheep/pi-quota 0.10.0 → 0.11.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-quota",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "publishConfig": {
     "access": "public"
   },

package/src/config.ts

@@ -13,6 +13,7 @@ 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 }
 
@@ -41,7 +42,7 @@ function parseFooterWindows(value: unknown): FooterWindows {
 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".');
+    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".');
   }
 }
 
@@ -83,6 +84,13 @@ export function parseQuotaConfig(value: unknown): QuotaConfig {
       } 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')
@@ -105,8 +113,9 @@ export function loadQuotaFooterWindows(settings: unknown): FooterWindows | undef
 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]) => {
+  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);
@@ -117,5 +126,15 @@ export function loadQuotaAdaptersFromSettings(settings: unknown): QuotaAdapter[]
   });
 }
 
+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;
+}
+
   // Explicit adapter bindings from quotaUsage already have adapters registered; listing every
   // registered adapter is the boundary between quota providers and ordinary model providers.

package/src/extension.ts

@@ -10,6 +10,7 @@ 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 { createAliasAdapter, createDanglingAliasAdapter } from './query/alias.ts';
 import type { ProviderAuth, QuotaAdapter, QuotaState } from './query/types.ts';
 
 export const STATUS_EVENT = 'quota-bar:state:v1';
@@ -23,6 +24,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;
@@ -32,12 +34,20 @@ 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));
+    const aliases = options.aliases ?? {};
+    const explicitProviderIds = new Set([...explicitAdapters.map(adapter => adapter.provider), ...Object.keys(aliases)]);
     // 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));
+    // Alias providers share their target's account: register a delegating adapter
+    // under the alias ID. One hop only — an alias of an alias never resolves, and
+    // a dangling alias stays visible as an error instead of vanishing silently.
+    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));
+    }
     let current: ExtensionContext | undefined;
     let selectedProvider: string | undefined;
     let timer: ReturnType<typeof setInterval> | undefined;
@@ -119,7 +129,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 +229,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 +250,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')),
+  };
+}