@astrosheep/pi-quota 0.9.0 → 0.11.0

package/README.md

@@ -32,7 +32,9 @@ Add bindings in global `~/.pi/agent/settings.json` under `quotaUsage` (not proje
       "my-new-api": { "adapter": "new-api", "quotaPerUnit": 500000, "currency": "USD" },
       "deepseek": { "adapter": "deepseek" },
       "opencode-go-2": { "adapter": "opencode-go" },
-      "yes-vg": { "adapter": "yescode", "username": "you@example.com", "password": "..." }
+      "yes-vg": { "adapter": "yescode", "username": "you@example.com", "password": "..." },
+      "my-script": { "adapter": "exec", "command": ["my-quota-cli", "--json"], "label": "My Script" },
+      "my-alias": { "adapter": "alias", "of": "my-sub2api" }
     }
   }
 }
@@ -47,6 +49,8 @@ Use the **exact Pi provider ID**. Built-in providers and explicitly bound provid
 | `deepseek` | Official `/user/balance` | Balance only; no invented spend |
 | `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.
 
@@ -56,6 +60,10 @@ For new-api, `quotaPerUnit` defaults to `500000`, `currency` to `USD`. Optionall
 
 For YesCode, `username` is the account email and `password` the account password; both stay in global `settings.json`, which is the trade-off of this adapter. YesCode rejects API keys on account endpoints ("requires a user session or JWT"), so the adapter logs in via `/api/v1/auth/login`, caches the issued cookie/JWT in memory for ~23 hours, and re-logs in once on an auth failure. The model `cr_` key is never sent to account endpoints; it only pins the provider to the official `co.yes.vg` origin. Balances are summed from subscription and pay-as-you-go; daily/weekly windows appear only when the account actually has those caps.
 
+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.9.0",
+  "version": "0.11.0",
   "publishConfig": {
     "access": "public"
   },

package/src/config.ts

@@ -1,4 +1,5 @@
 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';
@@ -11,6 +12,8 @@ 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: 'alias'; of: string }
   | { adapter: 'deepseek' | 'sub2api' | 'opencode-go' };
 export interface QuotaConfig { providers: Record<string, ProviderQuotaConfig>; footerWindows?: FooterWindows }
 
@@ -39,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" or "yescode", 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".');
   }
 }
 
@@ -74,6 +77,20 @@ export function parseQuotaConfig(value: unknown): QuotaConfig {
       } 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')
@@ -96,16 +113,28 @@ 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);
       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;
+}
+
   // 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')),
+  };
+}

package/src/query/exec.ts

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { QuotaError } from './types.ts';
+import type { QuotaAdapter, QuotaSnapshot } from './types.ts';
+
+export interface ExecOptions { command: string[]; label: string }
+
+export function validateExecOptions(options: { command?: unknown; label?: unknown }): ExecOptions {
+  const { command, label } = options;
+  if (!Array.isArray(command) || command.length === 0 || command.length > 16
+    || command.some(part => typeof part !== 'string' || part.trim() === '' || part.length > 512)) {
+    throw new Error('Invalid exec options');
+  }
+  if (typeof label !== 'string' || label.trim() === '' || label.length > 64) throw new Error('Invalid exec options');
+  return { command: [...command] as string[], label };
+}
+
+// Same bound as the HTTP clients: quota payloads are small.
+const MAX_OUTPUT_BYTES = 256 * 1024;
+
+function runCommand(command: readonly string[], signal: AbortSignal): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (error: unknown) => { if (!settled) { settled = true; reject(error); } };
+    const done = (text: string) => { if (!settled) { settled = true; resolve(text); } };
+    let child;
+    try {
+      // No shell: argv passes verbatim; settings.json is the only trust boundary.
+      // The controller bounds the wait via the signal even if the child hangs.
+      child = spawn(command[0], command.slice(1), { signal, stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch { fail(new QuotaError('network')); return; }
+    let output = '';
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk: string) => {
+      output += chunk;
+      if (output.length > MAX_OUTPUT_BYTES) { child.kill(); fail(new QuotaError('schema')); }
+    });
+    child.on('error', () => fail(signal.aborted ? signal.reason : new QuotaError('network')));
+    child.on('close', code => {
+      if (signal.aborted) fail(signal.reason);
+      else if (code !== 0) fail(new QuotaError('network'));
+      else done(output);
+    });
+  });
+}
+
+export function createExecAdapter(provider: string, options: ExecOptions): QuotaAdapter {
+  return {
+    provider, label: options.label,
+    async query(context) {
+      const text = await runCommand(options.command, context.signal);
+      let payload: unknown;
+      try { payload = JSON.parse(text); } catch { throw new QuotaError('schema'); }
+      if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) throw new QuotaError('schema');
+      // fetchedAt is stamped here, never trusted from the command; the
+      // controller's validateSnapshot performs the real schema check.
+      return { ...(payload as Record<string, unknown>), fetchedAt: context.now() } as QuotaSnapshot;
+    },
+  };
+}