@astrosheep/pi-quota 0.8.1 → 0.10.0

package/README.md

@@ -18,7 +18,7 @@ Reload Pi after installing or changing settings. Use `/usage` for a persistent,
 
 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, for the current provider only. `/usage` queries all configured supported providers and shows successful results with all windows, grouped by provider; it does not open a modal or send messages to the model. Snapshots remain frozen at capture time. Query failures replace stale values in the footer and appear in `/usage --all`.
+The footer shows at most two windows — set `quotaUsage.footerWindows` to a positive integer or `"all"` to show more — and `+N` for additional ones, for the current provider only. `/usage` queries all configured supported providers and shows successful results with all windows, grouped by provider; it does not open a modal or send messages to the model. Snapshots remain frozen at capture time. Query failures replace stale values in the footer and appear in `/usage --all`.
 
 ## Configure providers
 
@@ -32,7 +32,8 @@ 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" }
     }
   }
 }
@@ -47,6 +48,7 @@ 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 |
 
 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 +58,8 @@ 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`.
+
 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.8.1",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },

package/src/bar/quota.ts

@@ -24,14 +24,18 @@ function windowSpans(window: QuotaWindow, now: number): Span[] {
   ];
 }
 
-export function quotaElement(state: QuotaState, now = Date.now()): BarElement {
+// Footer window cap: a positive count, or 'all' for every shared window.
+export type FooterWindows = number | 'all';
+
+export function quotaElement(state: QuotaState, now = Date.now(), maxWindows: FooterWindows = 2): 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 eligible = shared.length ? shared : windows;
+  const shown = maxWindows === 'all' ? eligible : eligible.slice(0, maxWindows);
   const spans: Span[] = state.snapshot.balance ? balanceSpans(state.snapshot.balance)
     : state.snapshot.allowance ? allowanceSpans(state.snapshot.allowance) : [];
   for (const window of shown) {
@@ -42,8 +46,8 @@ export function quotaElement(state: QuotaState, now = Date.now()): BarElement {
   return { ...element, spans };
 }
 
-export function renderFooter(state: QuotaState, paint: Paint = plain, now = Date.now()): string {
-  return renderBar([quotaElement(state, now)], paint);
+export function renderFooter(state: QuotaState, paint: Paint = plain, now = Date.now(), maxWindows: FooterWindows = 2): string {
+  return renderBar([quotaElement(state, now, maxWindows)], paint);
 }
 
 export function renderUsage(state: QuotaState, paint: Paint = plain, now = Date.now(), barWidth = 16): string[] {

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';
@@ -6,12 +7,14 @@ 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> }
+export interface QuotaConfig { providers: Record<string, ProviderQuotaConfig>; footerWindows?: FooterWindows }
 
 const DASHBOARD_KEYS = ['dashboardAccessToken', 'dashboardUserId'] as const;
 
@@ -29,10 +32,16 @@ function parseDashboardOptions(item: Record<string, unknown>): Pick<NewApiOption
   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" or "yescode".');
+    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".');
   }
 }
 
@@ -41,7 +50,7 @@ function record(value: unknown): value is Record<string, unknown> {
 }
 
 export function parseQuotaConfig(value: unknown): QuotaConfig {
-  if (!record(value) || Object.keys(value).some(key => key !== 'providers')
+  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)) {
@@ -67,6 +76,13 @@ 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 !== 'new-api'
       || Object.keys(item).some(key => !['adapter', 'quotaPerUnit', 'currency', ...DASHBOARD_KEYS].includes(key))
       || (item.quotaPerUnit !== undefined && typeof item.quotaPerUnit !== 'number')
@@ -76,7 +92,14 @@ export function parseQuotaConfig(value: unknown): QuotaConfig {
       providers[provider] = { adapter: 'new-api', ...settings, ...parseDashboardOptions(item) };
     } catch { throw new QuotaConfigError(); }
   }
-  return { providers };
+  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[] {
@@ -88,6 +111,7 @@ export function loadQuotaAdaptersFromSettings(settings: unknown): QuotaAdapter[]
       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);
     }
   });

package/src/extension.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 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';
@@ -23,6 +24,7 @@ export interface QuotaExtensionOptions {
   adapters?: readonly QuotaAdapter[];
   providers?: readonly string[]; // Extra configured quota providers to include in /usage
   footer?: boolean; // false: query + /usage + structured events only
+  footerWindows?: FooterWindows; // footer window cap; default 2, 'all' shows every window
   intervalMs?: number;
   timeoutMs?: number;
 }
@@ -57,7 +59,7 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
         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;
+        const text = renderFooter(controller.state, paint, Date.now(), options.footerWindows) || undefined;
         if (text !== lastStatus) {
           ctx.ui.setStatus(STATUS_KEY, text);
           lastStatus = text;

package/src/index.ts

@@ -1,11 +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, QuotaConfigError } from './config.ts';
+import { loadQuotaAdaptersFromSettings, 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 footerWindows: FooterWindows | undefined;
   try {
     // Quota provider bindings belong to the user's global Pi settings. Project
     // settings are intentionally not read here: a project must not redirect a
@@ -14,11 +16,12 @@ export default function (pi: ExtensionAPI): void {
       projectTrusted: false,
     }).getGlobalSettings() as unknown;
     adapters = loadQuotaAdaptersFromSettings(settings);
+    footerWindows = loadQuotaFooterWindows(settings);
   } catch {
     pi.on('session_start', (_event, ctx) => {
       if (ctx.hasUI) ctx.ui.notify(new QuotaConfigError().message, 'warning');
     });
   }
   // Invalid optional settings never disable the built-in Codex/Kimi/OpenCode Go adapters.
-  createQuotaExtension({ adapters })(pi);
+  createQuotaExtension({ adapters, footerWindows })(pi);
 }

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;
+    },
+  };
+}