@astrosheep/pi-quota 0.9.0 → 0.10.0

package/README.md

@@ -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.9.0",
+  "version": "0.10.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,7 @@ 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 }
 
@@ -39,7 +41,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" or "exec", and optionally footerWindows as a positive integer or "all".');
   }
 }
 
@@ -74,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')
@@ -102,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/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;
+    },
+  };
+}