agy-cli-usage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abruption
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# agy-cli-usage
+
+[![CI](https://github.com/abruption/agy-cli-usage/actions/workflows/ci.yml/badge.svg)](https://github.com/abruption/agy-cli-usage/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/agy-cli-usage.svg)](https://www.npmjs.com/package/agy-cli-usage)
+
+Headless usage/quota monitor for the Antigravity CLI (`agy`). `agy`의 인터랙티브 `/usage` 패널과 동일한 정보(모델 그룹별 주간·5시간 한도, 잔여율, 리프레시 시각)를 **headless로** 조회한다. IDE 불필요.
+
+`agy -p "<prompt>"`(headless)는 `/usage` 같은 TUI 슬래시 커맨드를 렌더링하지 않으므로 자동화가 불가능하다. 이 도구는 `agy`가 내부적으로 호출하는 Cloud Code API를 직접 호출하거나, 불가능할 때 `agy`를 PTY로 구동해 패널을 파싱한다.
+
+## 설치
+
+```bash
+# npm 레지스트리에서
+npm install -g agy-cli-usage
+
+# 또는 GitHub에서 직접
+npm install -g github:abruption/agy-cli-usage
+npx github:abruption/agy-cli-usage
+
+# 또는 소스에서
+git clone https://github.com/abruption/agy-cli-usage && cd agy-cli-usage
+npm install && npm link
+```
+
+전역 명령은 `agy-cli-usage` (별칭 `agy-usage`)로 등록된다. Node.js >= 18 (전역 `fetch` 필요). 사전 조건: 같은 머신에서 `agy`에 로그인되어 있을 것.
+
+## 사용법
+
+```bash
+agy-usage                  # /usage 와 동일한 패널 출력 (1회성)
+agy-usage --json           # 머신 리더블 JSON
+agy-usage --watch 60       # 60초 간격 자동 갱신 (5분 캐시 경유)
+agy-usage --source api|pty|auto   # 데이터 소스 (기본 auto: API → 실패 시 PTY)
+agy-usage --channel daily|prod    # Cloud Code 호스트 (기본 auto: daily→prod 탐지)
+agy-usage --no-cache               # 5분 캐시 무시하고 강제 조회
+```
+
+## 동작 방식
+
+`agy`는 OAuth 토큰을 OS 키링(zalando/go-keyring 규약, service=`gemini`/account=`antigravity`)에 저장한다.
+
+1. **직접 API (기본)** — 키링에서 토큰을 읽고(만료 시 자동 refresh), `agy`와 동일하게:
+   - `POST https://<host>/v1internal:loadCodeAssist` → `cloudaicompanionProject` 획득
+   - `POST https://<host>/v1internal:retrieveUserQuotaSummary {project}` → 쿼타
+   - 호스트: `daily-cloudcode-pa.googleapis.com`(현재 CLI) 또는 `cloudcode-pa.googleapis.com`
+2. **PTY 폴백** — 키링을 읽을 수 없거나(헤드리스 등) 내부 API가 바뀌면, `agy`를 가상 터미널로 띄워 `/usage`를 보내고, `@xterm/headless`로 alt-screen을 재구성해 패널을 파싱한다.
+
+### 크로스플랫폼 자격증명
+
+| OS | 키링 백엔드 | 비고 |
+|----|-----------|------|
+| macOS | Keychain | `@napi-rs/keyring`, CLI 폴백 `security` |
+| Windows | Credential Manager | `@napi-rs/keyring` |
+| Linux (데스크톱) | Secret Service | `@napi-rs/keyring`, CLI 폴백 `secret-tool` |
+| Linux (헤드리스) | — | Secret Service 부재 시 `--source pty`로 우회 (python3 필요) |
+
+## HTTP 엔드포인트 (선택)
+
+```bash
+PORT=3007 node server.js     # GET /quota → 정규화 JSON (5분 캐시), GET /healthz
+```
+
+외부 대시보드/스크립트에서 `GET /quota`로 소비하거나, `agy-usage --json`을 subprocess로 호출한다.
+
+## 개발 / 릴리스
+
+```bash
+npm test          # node --test (자격증명·네트워크 불필요, 순수 로직)
+npm run check     # 구문 검사
+```
+
+- **CI** (`.github/workflows/ci.yml`): push/PR마다 ubuntu(Node 18/20/22) + macOS/Windows(Node 22)에서 테스트.
+- **Release** (`.github/workflows/release.yml`): `v*` 태그 push 시 빌드·테스트 후 npm publish(provenance) + GitHub Release 생성. `NPM_TOKEN` 시크릿 필요.
+
+```bash
+npm version patch        # package.json 버전 +0.0.1 & v* 태그 생성
+git push --follow-tags   # → Release 워크플로 실행 → npm 자동 배포
+```
+
+## 주의
+
+- `v1internal:retrieveUserQuotaSummary`는 **비공개 내부 엔드포인트**다. 스키마/호스트가 예고 없이 바뀔 수 있으며, 그때를 위한 안전망이 PTY 폴백이다.
+- 본인 계정의 키링 토큰만 읽으며(읽기 전용), refresh 토큰을 키링에 되쓰지 않는다.
+- OAuth client_secret은 데스크톱(공개) 클라이언트 값이라 비밀이 아니다.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "agy-cli-usage",
+  "version": "0.1.0",
+  "description": "Headless usage/quota monitor for the Antigravity CLI (agy) — reads Cloud Code quota directly, with a PTY fallback. No IDE required.",
+  "type": "module",
+  "bin": {
+    "agy-cli-usage": "src/main.js",
+    "agy-usage": "src/main.js"
+  },
+  "scripts": {
+    "start": "node src/main.js",
+    "serve": "node server.js",
+    "test": "node --test",
+    "check": "node --check src/main.js && node --check server.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "server.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "antigravity",
+    "agy",
+    "gemini",
+    "code-assist",
+    "quota",
+    "usage",
+    "cli",
+    "rate-limit"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abruption/agy-cli-usage.git"
+  },
+  "homepage": "https://github.com/abruption/agy-cli-usage#readme",
+  "bugs": {
+    "url": "https://github.com/abruption/agy-cli-usage/issues"
+  },
+  "author": "abruption",
+  "dependencies": {
+    "@napi-rs/keyring": "^1.3.0",
+    "@xterm/headless": "^6.0.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.0.0"
+  },
+  "license": "MIT"
+}

package/server.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Optional lightweight HTTP endpoint for dashboard integration (e.g. ontology).
+// Serves the normalized quota snapshot as JSON, going through the same 5-minute
+// cache as the CLI so polling clients never hammer the upstream API.
+//
+//   PORT=3007 node server.js
+//   GET /quota   -> normalized snapshot JSON
+//   GET /healthz -> { ok: true }
+
+import { createServer } from 'node:http';
+import { getSnapshot } from './src/main.js';
+
+const PORT = Number(process.env.PORT) || 3007;
+const HOST = process.env.HOST || '127.0.0.1';
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+
+  if (url.pathname === '/healthz') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
+
+  if (url.pathname === '/quota') {
+    try {
+      const noCache = url.searchParams.get('refresh') === '1';
+      const snap = await getSnapshot({ source: 'auto', channel: 'auto', cache: !noCache });
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+        'Cache-Control': 'public, max-age=300',
+      });
+      res.end(JSON.stringify(snap));
+    } catch (err) {
+      res.writeHead(502, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
+  res.writeHead(404, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'not found' }));
+});
+
+server.listen(PORT, HOST, () => {
+  process.stdout.write(`agy-usage server on http://${HOST}:${PORT}  (GET /quota)\n`);
+});

package/src/api.js

@@ -0,0 +1,92 @@
+// Direct client for the Antigravity / Gemini Code Assist "Cloud Code" internal API.
+//
+// Reproduces exactly what `agy` does on startup to populate its /usage panel:
+//   1. POST /v1internal:loadCodeAssist  {metadata:{ideType:"ANTIGRAVITY"}}
+//        -> { cloudaicompanionProject, currentTier, ... }
+//   2. POST /v1internal:retrieveUserQuotaSummary  {project:<cloudaicompanionProject>}
+//        -> { groups:[ { displayName, description, buckets:[ {bucketId, displayName,
+//             window, resetTime, description?, remainingFraction} ] } ], description }
+//
+// Captured from live agy traffic (mitmproxy). The internal endpoint is undocumented;
+// the PTY fallback exists for when it changes.
+
+const UA = `antigravity-usage-monitor/0.1 ${process.platform}/${process.arch}`;
+
+// Antigravity ships against the "daily" Cloud Code host; stable builds use the
+// plain host. Try daily first (matches current CLI), fall back to prod.
+const HOSTS = ['daily-cloudcode-pa.googleapis.com', 'cloudcode-pa.googleapis.com'];
+
+class ApiError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+
+function extractEmail(uri) {
+  const m = uri?.match(/[?&]Email=([^&]+)/);
+  if (!m) return null;
+  try {
+    return decodeURIComponent(m[1]);
+  } catch {
+    return m[1];
+  }
+}
+
+async function postInternal(host, accessToken, method, body) {
+  const res = await fetch(`https://${host}/v1internal:${method}`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+      'User-Agent': UA,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw new ApiError(`${method} -> HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`, res.status);
+  }
+  return res.json();
+}
+
+/**
+ * Fetch the raw quota summary from the Cloud Code API.
+ * @param {string} accessToken
+ * @param {{ host?: string, channel?: 'daily'|'prod' }} [opts]
+ * @returns {Promise<{ raw: object, host: string, account: string|null, tier: string|null }>}
+ */
+export async function fetchQuotaSummary(accessToken, opts = {}) {
+  const candidates = opts.host
+    ? [opts.host]
+    : opts.channel === 'prod'
+      ? ['cloudcode-pa.googleapis.com']
+      : opts.channel === 'daily'
+        ? ['daily-cloudcode-pa.googleapis.com']
+        : HOSTS;
+
+  let lastErr;
+  for (const host of candidates) {
+    try {
+      const lca = await postInternal(host, accessToken, 'loadCodeAssist', {
+        metadata: { ideType: 'ANTIGRAVITY' },
+      });
+      const project = lca.cloudaicompanionProject;
+      if (!project) throw new ApiError('loadCodeAssist returned no cloudaicompanionProject', 0);
+
+      const raw = await postInternal(host, accessToken, 'retrieveUserQuotaSummary', { project });
+      return {
+        raw,
+        host,
+        tier: lca.currentTier?.id ?? null,
+        account: extractEmail(lca.currentTier?.upgradeSubscriptionUri),
+      };
+    } catch (err) {
+      lastErr = err;
+      // 404 / wrong-host -> try next candidate; auth errors -> stop early.
+      if (err instanceof ApiError && (err.status === 401 || err.status === 403)) throw err;
+    }
+  }
+  throw lastErr ?? new ApiError('No Cloud Code host responded', 0);
+}
+
+export { ApiError };

package/src/credentials.js

@@ -0,0 +1,158 @@
+// Cross-platform reader for the Antigravity CLI (`agy`) OAuth credential.
+//
+// `agy` stores its token in the OS keyring using the zalando/go-keyring
+// convention: service="gemini", account="antigravity". Long/binary values are
+// stored with a `go-keyring-base64:` prefix followed by base64(JSON). The
+// decoded JSON looks like:
+//   { "token": { "access_token", "token_type", "refresh_token", "expiry" },
+//     "auth_method": "consumer" }
+//
+// Read backends, tried in order:
+//   1. @napi-rs/keyring native module  (macOS / Windows / Linux Secret Service)
+//   2. OS CLI fallback                  (`security` on macOS, `secret-tool` on Linux)
+// If every backend fails (e.g. a headless Linux box with no Secret Service),
+// the caller falls back to the PTY path which drives `agy` itself.
+
+import { execFileSync } from 'node:child_process';
+
+// OAuth client for the Antigravity CLI. This is an installed/desktop ("public")
+// OAuth client: per Google's own docs the client secret of an installed app is
+// "obviously not treated as a secret" — it ships inside the agy binary and is
+// identical for every user (the per-user identity is the keyring token, not
+// this). Verified: the same client_id appears in agy's browser consent URL
+// regardless of account, and the flow uses PKCE (code_challenge/S256), the
+// mechanism that secures public clients precisely because the secret is public.
+// Same pattern as Google's open-source gemini-cli.
+const OAUTH_CLIENT_ID = '1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com';
+const OAUTH_CLIENT_SECRET = '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';
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+
+const KEYRING_SERVICE = 'gemini';
+const KEYRING_ACCOUNT = 'antigravity';
+const B64_PREFIX = 'go-keyring-base64:';
+
+class CredentialError extends Error {}
+
+// --- raw keyring read --------------------------------------------------------
+
+async function readViaNapiEsm() {
+  try {
+    const mod = await import('@napi-rs/keyring');
+    const Entry = mod.Entry ?? mod.default?.Entry;
+    if (!Entry) return null;
+    return new Entry(KEYRING_SERVICE, KEYRING_ACCOUNT).getPassword();
+  } catch {
+    return null;
+  }
+}
+
+function readViaCli() {
+  try {
+    if (process.platform === 'darwin') {
+      return execFileSync(
+        'security',
+        ['find-generic-password', '-s', KEYRING_SERVICE, '-a', KEYRING_ACCOUNT, '-w'],
+        { encoding: 'utf8' },
+      ).trim();
+    }
+    if (process.platform === 'linux') {
+      return execFileSync(
+        'secret-tool',
+        ['lookup', 'service', KEYRING_SERVICE, 'account', KEYRING_ACCOUNT],
+        { encoding: 'utf8' },
+      ).trim();
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+async function readRawSecret() {
+  const fromNapi = await readViaNapiEsm();
+  if (fromNapi) return fromNapi;
+  const fromCli = readViaCli();
+  if (fromCli) return fromCli;
+  return null;
+}
+
+// --- decode ------------------------------------------------------------------
+
+function decodeSecret(raw) {
+  const payload = raw.startsWith(B64_PREFIX)
+    ? Buffer.from(raw.slice(B64_PREFIX.length), 'base64').toString('utf8')
+    : raw;
+  let parsed;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    throw new CredentialError('Stored agy credential is not valid JSON');
+  }
+  const token = parsed.token ?? parsed;
+  if (!token?.access_token) {
+    throw new CredentialError('Stored agy credential has no access_token');
+  }
+  return {
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token,
+    expiry: token.expiry ? new Date(token.expiry) : null,
+    authMethod: parsed.auth_method ?? null,
+  };
+}
+
+// --- refresh -----------------------------------------------------------------
+
+function isExpired(cred, skewMs = 60_000) {
+  if (!cred.expiry) return false;
+  return cred.expiry.getTime() - Date.now() < skewMs;
+}
+
+async function refreshAccessToken(refreshToken) {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: OAUTH_CLIENT_ID,
+    client_secret: OAUTH_CLIENT_SECRET,
+  });
+  const res = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    throw new CredentialError(`Token refresh failed: HTTP ${res.status} ${await res.text()}`);
+  }
+  const json = await res.json();
+  return json.access_token;
+}
+
+// --- public API --------------------------------------------------------------
+
+/**
+ * Returns a valid access token for the Cloud Code API, refreshing if needed.
+ * Throws CredentialError if no credential can be read from any keyring backend
+ * (the caller should then consider the PTY fallback).
+ * @returns {Promise<{ accessToken: string, authMethod: string|null }>}
+ */
+export async function getAccessToken() {
+  const raw = await readRawSecret();
+  if (!raw) {
+    throw new CredentialError(
+      'Could not read agy credential from the OS keyring. ' +
+        'Is agy logged in on this machine? (headless servers may lack a keyring — use --source pty)',
+    );
+  }
+  const cred = decodeSecret(raw);
+  if (isExpired(cred) && cred.refreshToken) {
+    const fresh = await refreshAccessToken(cred.refreshToken);
+    return { accessToken: fresh, authMethod: cred.authMethod };
+  }
+  return { accessToken: cred.accessToken, authMethod: cred.authMethod };
+}
+
+/** Whether a keyring-based credential is readable at all (no refresh attempted). */
+export async function hasCredential() {
+  return (await readRawSecret()) != null;
+}
+
+export { CredentialError };

package/src/main.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// agy-usage — Antigravity CLI (agy) usage/quota monitor.
+//
+// Usage:
+//   agy-usage                 one-shot panel (like agy's /usage)
+//   agy-usage --json          machine-readable JSON
+//   agy-usage --watch [secs]  refresh every N seconds (default 60)
+//   agy-usage --source api|pty|auto   data source (default auto: api, fall back to pty)
+//   agy-usage --channel daily|prod    Cloud Code host (default: auto-detect)
+//   agy-usage --no-cache      bypass the 5-minute cache
+//   agy-usage --refresh       force a fresh fetch (alias for --no-cache)
+
+import { getAccessToken, CredentialError } from './credentials.js';
+import { fetchQuotaSummary } from './api.js';
+import { captureUsageViaPty } from './pty-fallback.js';
+import { fromApi, fromPty } from './quota.js';
+import { renderPanel } from './render.js';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CACHE_DIR = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'agy-usage');
+const CACHE_FILE = join(CACHE_DIR, 'quota.json');
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+function parseArgs(argv) {
+  const o = { json: false, watch: null, source: 'auto', channel: 'auto', cache: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') o.json = true;
+    else if (a === '--watch') {
+      const n = Number(argv[i + 1]);
+      if (Number.isFinite(n)) { o.watch = n; i++; } else o.watch = 60;
+    } else if (a === '--source') o.source = argv[++i];
+    else if (a === '--channel') o.channel = argv[++i];
+    else if (a === '--no-cache' || a === '--refresh') o.cache = false;
+    else if (a === '-h' || a === '--help') o.help = true;
+  }
+  return o;
+}
+
+const HELP = `agy-usage — Antigravity CLI (agy) usage/quota monitor
+
+  agy-usage                 one-shot panel
+  agy-usage --json          machine-readable JSON
+  agy-usage --watch [secs]  auto-refresh (default 60s)
+  agy-usage --source <auto|api|pty>
+  agy-usage --channel <auto|daily|prod>
+  agy-usage --no-cache | --refresh
+`;
+
+// --- cache -------------------------------------------------------------------
+
+function readCache() {
+  try {
+    const { ts, snap } = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+    if (Date.now() - ts < CACHE_TTL_MS) return snap;
+  } catch {}
+  return null;
+}
+
+function writeCache(snap) {
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), snap }));
+  } catch {}
+}
+
+// --- fetch -------------------------------------------------------------------
+
+export async function getSnapshot(opts) {
+  if (opts.cache && opts.source !== 'pty') {
+    const cached = readCache();
+    if (cached) return cached;
+  }
+
+  let snap;
+  if (opts.source === 'pty') {
+    snap = fromPty(await captureUsageViaPty());
+  } else {
+    try {
+      const { accessToken } = await getAccessToken();
+      const raw = await fetchQuotaSummary(accessToken, { channel: opts.channel === 'auto' ? undefined : opts.channel });
+      snap = fromApi(raw);
+    } catch (err) {
+      if (opts.source === 'api') throw err;
+      // auto: fall back to PTY
+      process.stderr.write(`[api failed: ${err.message}] falling back to PTY (agy)…\n`);
+      snap = fromPty(await captureUsageViaPty());
+    }
+  }
+  writeCache(snap);
+  return snap;
+}
+
+// --- main --------------------------------------------------------------------
+
+async function once(opts) {
+  const snap = await getSnapshot(opts);
+  if (opts.json) process.stdout.write(JSON.stringify(snap, null, 2) + '\n');
+  else process.stdout.write(renderPanel(snap) + '\n');
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { process.stdout.write(HELP); return; }
+
+  if (opts.watch != null) {
+    const intervalMs = Math.max(5, opts.watch) * 1000;
+    const tick = async () => {
+      try {
+        if (!opts.json) process.stdout.write('\x1b[2J\x1b[H'); // clear screen
+        await once(opts);
+      } catch (err) {
+        process.stderr.write(`error: ${err.message}\n`);
+      }
+    };
+    await tick();
+    setInterval(tick, intervalMs);
+  } else {
+    await once(opts);
+  }
+}
+
+main().catch((err) => {
+  if (err instanceof CredentialError) {
+    process.stderr.write(`credential error: ${err.message}\n`);
+  } else {
+    process.stderr.write(`error: ${err.message}\n`);
+  }
+  process.exit(1);
+});

package/src/pty-fallback.js

@@ -0,0 +1,211 @@
+// Fallback path: drive the real `agy` TUI in a pseudo-terminal, send `/usage`,
+// reconstruct the rendered screen with a headless VT emulator, and parse the
+// panel. Used only when the direct API path is unavailable (no readable
+// keyring, or the internal API changed). Slower and more brittle than the API
+// path, but uses agy's own auth so it works wherever agy itself works.
+//
+// Why a VT emulator: agy renders /usage in the alternate screen buffer using
+// cursor addressing, so naive ANSI-stripping yields nothing. We feed the raw
+// PTY bytes through @xterm/headless to get the final visible screen, then parse.
+//
+// Capture backend: python3 `pty` on POSIX (no native build), node-pty on
+// Windows (ConPTY). agy shows a welcome screen first, so `/usage` is sent after
+// a delay and the session is held open long enough to render.
+
+import { spawn } from 'node:child_process';
+import { writeFileSync, readFileSync, mkdtempSync, existsSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join, delimiter } from 'node:path';
+
+// Resolve the agy binary: explicit AGY_BIN, then PATH, then common install dir.
+function resolveAgy() {
+  const explicit = process.env.AGY_BIN;
+  if (explicit) return explicit;
+  const exe = process.platform === 'win32' ? 'agy.exe' : 'agy';
+  for (const dir of (process.env.PATH || '').split(delimiter)) {
+    if (dir && existsSync(join(dir, exe))) return join(dir, exe);
+  }
+  const local = join(homedir(), '.local', 'bin', exe);
+  if (existsSync(local)) return local;
+  return 'agy'; // last resort: let the OS resolve it
+}
+
+const AGY_BIN = resolveAgy();
+const COLS = 120;
+const ROWS = 60;
+const USAGE_AT_MS = 10_000; // send /usage after the welcome screen settles
+const TEARDOWN_MS = 23_000; // keep session open long enough to render
+
+// --- capture: returns raw PTY bytes (Buffer) or null --------------------------
+
+async function captureViaNodePty() {
+  let pty;
+  try {
+    pty = await import('node-pty');
+  } catch {
+    return null;
+  }
+  return new Promise((resolve) => {
+    let term;
+    try {
+      term = pty.spawn(AGY_BIN, [], { name: 'xterm-256color', cols: COLS, rows: ROWS, cwd: process.cwd(), env: process.env });
+    } catch {
+      resolve(null);
+      return;
+    }
+    const chunks = [];
+    term.onData((d) => chunks.push(Buffer.from(d, 'utf8')));
+    const t1 = setTimeout(() => { try { term.write('/usage\r'); } catch {} }, USAGE_AT_MS);
+    const t2 = setTimeout(() => {
+      try { term.write('\x03'); } catch {}
+      try { term.kill(); } catch {}
+      resolve(Buffer.concat(chunks));
+    }, TEARDOWN_MS);
+    term.onExit(() => { clearTimeout(t1); clearTimeout(t2); resolve(Buffer.concat(chunks)); });
+  });
+}
+
+async function captureViaPython() {
+  if (process.platform === 'win32') return null;
+  const dir = mkdtempSync(join(tmpdir(), 'agy-usage-'));
+  const helper = join(dir, 'drive.py');
+  const outFile = join(dir, 'out.bin');
+  writeFileSync(
+    helper,
+    `import os, pty, time, select, signal, struct, fcntl, termios
+AGY = ${JSON.stringify(AGY_BIN)}
+out = open(${JSON.stringify(outFile)}, "wb")
+pid, fd = pty.fork()
+if pid == 0:
+    os.execvpe(AGY, [AGY], os.environ)
+    os._exit(127)
+fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", ${ROWS}, ${COLS}, 0, 0))
+start = time.time(); sent = False
+while time.time() - start < ${TEARDOWN_MS / 1000}:
+    e = time.time() - start
+    r, _, _ = select.select([fd], [], [], 0.5)
+    if r:
+        try: d = os.read(fd, 8192)
+        except OSError: break
+        if not d: break
+        out.write(d); out.flush()
+    if not sent and e > ${USAGE_AT_MS / 1000}:
+        os.write(fd, b"/usage\\r"); sent = True
+try: os.write(fd, b"\\x03")
+except OSError: pass
+try: os.kill(pid, signal.SIGTERM)
+except Exception: pass
+out.close()
+`,
+  );
+  return new Promise((resolve) => {
+    const proc = spawn('python3', [helper], { stdio: 'ignore' });
+    proc.on('error', () => resolve(null));
+    proc.on('exit', () => {
+      try { resolve(readFileSync(outFile)); } catch { resolve(null); }
+    });
+  });
+}
+
+// --- VT reconstruction --------------------------------------------------------
+
+async function reconstructScreen(raw) {
+  const mod = await import('@xterm/headless');
+  const Terminal = mod.Terminal ?? mod.default?.Terminal ?? mod.default;
+  const term = new Terminal({ cols: COLS, rows: ROWS, allowProposedApi: true, scrollback: 200 });
+  await new Promise((res) => term.write(raw, res));
+  const buf = term.buffer.active;
+  const lines = [];
+  // include scrollback so a panel taller than the viewport is still captured
+  for (let i = 0; i < buf.length; i++) {
+    const line = buf.getLine(i);
+    if (line) lines.push(line.translateToString(true).replace(/\s+$/, ''));
+  }
+  term.dispose?.();
+  return lines.join('\n');
+}
+
+// --- parse --------------------------------------------------------------------
+
+function parseDuration(text) {
+  let seconds = 0;
+  const d = text.match(/(\d+)\s*day/i);
+  const h = text.match(/(\d+)\s*h(?:our)?/i);
+  const m = text.match(/(\d+)\s*m(?:in)?/i);
+  if (d) seconds += +d[1] * 86400;
+  if (h) seconds += +h[1] * 3600;
+  if (m) seconds += +m[1] * 60;
+  return seconds || null;
+}
+
+/** Parse the reconstructed /usage screen text into { account, groups:[...] }. */
+export function parsePanel(text) {
+  const lines = text.split(/\r?\n/);
+  const account = text.match(/Account:\s*(\S+)/)?.[1] ?? null;
+
+  const groups = [];
+  let group = null;
+  let bucket = null;
+  const pushBucket = () => { if (group && bucket) group.buckets.push(bucket); bucket = null; };
+  const pushGroup = () => { pushBucket(); if (group) groups.push(group); group = null; };
+
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t) continue;
+
+    if (/^[A-Z][A-Z0-9 &/]*MODELS$/.test(t)) {
+      pushGroup();
+      group = { name: t.replace(/\s+/g, ' '), models: '', buckets: [] };
+      continue;
+    }
+    const models = t.match(/^Models within this group:\s*(.+)$/i);
+    if (models && group) { group.models = models[1].trim(); continue; }
+
+    if (/^(Weekly Limit|Five Hour Limit|5[- ]?Hour Limit)$/i.test(t)) {
+      pushBucket();
+      bucket = {
+        kind: /week/i.test(t) ? 'weekly' : '5h',
+        label: t,
+        remainingFraction: null,
+        resetsInSeconds: null,
+        available: false,
+        description: null,
+      };
+      continue;
+    }
+    if (bucket) {
+      const pct = t.match(/(\d+(?:\.\d+)?)\s*%/);
+      if (pct && bucket.remainingFraction == null) bucket.remainingFraction = +pct[1] / 100;
+      if (/Quota available/i.test(t)) { bucket.available = true; bucket.remainingFraction = 1; }
+      const refresh = t.match(/Refreshes in (.+)$/i);
+      if (refresh) bucket.resetsInSeconds = parseDuration(refresh[1]);
+    }
+  }
+  pushGroup();
+  return { account, groups };
+}
+
+/**
+ * Run agy, capture /usage, reconstruct + parse the panel.
+ * @returns {Promise<{ account, groups }>}
+ */
+export async function captureUsageViaPty() {
+  const order = process.platform === 'win32'
+    ? [captureViaNodePty, captureViaPython]
+    : [captureViaPython, captureViaNodePty];
+
+  let raw = null;
+  for (const fn of order) {
+    raw = await fn();
+    if (raw && raw.length) break;
+  }
+  if (!raw || !raw.length) {
+    throw new Error('No PTY backend captured agy output (need python3 on POSIX, or node-pty on Windows)');
+  }
+  const screen = await reconstructScreen(raw);
+  const parsed = parsePanel(screen);
+  if (!parsed.groups.length) {
+    throw new Error('Could not parse /usage panel from agy output');
+  }
+  return parsed;
+}

package/src/quota.js

@@ -0,0 +1,100 @@
+// Normalizes quota data from either source (direct API JSON or PTY-parsed text)
+// into one shape consumed by the renderer / JSON output / HTTP endpoint.
+//
+// Normalized model:
+//   {
+//     account, fetchedAt, source: 'api'|'pty', host?,
+//     note,                       // the API's overall description blurb
+//     groups: [
+//       { name, models,           // e.g. "Gemini Models", "Gemini Flash, Gemini Pro"
+//         buckets: [
+//           { kind: 'weekly'|'5h', label,
+//             remainingFraction,  // 0..1  (null if unknown)
+//             usedFraction,       // 1 - remaining
+//             resetAt,            // ISO string or null
+//             resetsInSeconds,    // derived from resetAt - now (null if unknown)
+//             available,          // true when nothing consumed (remainingFraction === 1)
+//             description } ] } ]
+//   }
+
+function bucketKind(window, label) {
+  if (window === 'weekly' || /week/i.test(label)) return 'weekly';
+  if (window === '5h' || /5.?hour|five.?hour/i.test(label)) return '5h';
+  return window || label;
+}
+
+function secondsUntil(resetAt, now) {
+  if (!resetAt) return null;
+  const ms = new Date(resetAt).getTime() - now;
+  return Number.isFinite(ms) ? Math.max(0, Math.round(ms / 1000)) : null;
+}
+
+/** Build a normalized snapshot from the raw retrieveUserQuotaSummary response. */
+export function fromApi({ raw, host, account, tier }, nowMs = Date.now()) {
+  const groups = (raw.groups ?? []).map((g) => ({
+    name: g.displayName ?? 'Models',
+    models: (g.description ?? '').replace(/^Models within this group:\s*/i, '').trim(),
+    buckets: (g.buckets ?? []).map((b) => {
+      const remaining = typeof b.remainingFraction === 'number' ? b.remainingFraction : null;
+      return {
+        kind: bucketKind(b.window, b.displayName ?? ''),
+        label: b.displayName ?? b.window ?? '',
+        remainingFraction: remaining,
+        usedFraction: remaining == null ? null : 1 - remaining,
+        resetAt: b.resetTime ?? null,
+        resetsInSeconds: secondsUntil(b.resetTime, nowMs),
+        available: remaining === 1,
+        description: b.description ?? null,
+      };
+    }),
+  }));
+  return {
+    account: account ?? null,
+    tier: tier ?? null,
+    fetchedAt: new Date(nowMs).toISOString(),
+    source: 'api',
+    host: host ?? null,
+    note: raw.description ?? null,
+    groups,
+  };
+}
+
+/**
+ * Build a normalized snapshot from PTY-parsed groups (see pty-fallback.js).
+ * Input groups: [{ name, models, buckets:[{ kind, label, remainingFraction,
+ *   resetsInSeconds, available, description }] }]
+ */
+export function fromPty(parsed, nowMs = Date.now()) {
+  const groups = (parsed.groups ?? []).map((g) => ({
+    name: g.name,
+    models: g.models ?? '',
+    buckets: (g.buckets ?? []).map((b) => ({
+      kind: b.kind,
+      label: b.label,
+      remainingFraction: b.remainingFraction ?? null,
+      usedFraction: b.remainingFraction == null ? null : 1 - b.remainingFraction,
+      resetAt: b.resetsInSeconds != null ? new Date(nowMs + b.resetsInSeconds * 1000).toISOString() : null,
+      resetsInSeconds: b.resetsInSeconds ?? null,
+      available: b.available ?? b.remainingFraction === 1,
+      description: b.description ?? null,
+    })),
+  }));
+  return {
+    account: parsed.account ?? null,
+    tier: null,
+    fetchedAt: new Date(nowMs).toISOString(),
+    source: 'pty',
+    host: null,
+    note: parsed.note ?? null,
+    groups,
+  };
+}
+
+/** Format a seconds duration like agy: "73h 53m" / "2h 7m" / "12m". */
+export function formatDuration(seconds) {
+  if (seconds == null) return null;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}

package/src/render.js

@@ -0,0 +1,82 @@
+// Renders a normalized quota snapshot as a terminal panel, mirroring agy's
+// `/usage` layout (progress bar + percent + reset time per bucket).
+
+import { formatDuration } from './quota.js';
+
+const BAR_WIDTH = 50;
+
+const useColor = () => process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor() ? `\x1b[${code}m${s}\x1b[0m` : s);
+const dim = (s) => c('2', s);
+const bold = (s) => c('1', s);
+
+// remaining-based color: lots left = green, getting low = yellow/red.
+function barColor(remaining) {
+  if (remaining == null) return '37';
+  if (remaining > 0.5) return '32'; // green
+  if (remaining > 0.2) return '33'; // yellow
+  return '31'; // red
+}
+
+function bar(remainingFraction) {
+  const frac = remainingFraction == null ? 0 : Math.max(0, Math.min(1, remainingFraction));
+  const filled = Math.round(frac * BAR_WIDTH);
+  const body = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
+  return useColor() ? `\x1b[${barColor(remainingFraction)}m${body}\x1b[0m` : body;
+}
+
+function bucketLine(b) {
+  const lines = [];
+  lines.push(`    ${bold(b.label)}`);
+  if (b.available) {
+    lines.push(`    [${bar(1)}] ${c('32', 'Quota available')}`);
+  } else {
+    const pct = b.remainingFraction == null ? '—' : `${(b.remainingFraction * 100).toFixed(2)}%`;
+    const remainPct = b.remainingFraction == null ? '' : `${Math.round(b.remainingFraction * 100)}% remaining`;
+    const dur = formatDuration(b.resetsInSeconds);
+    const reset = dur ? ` · ${dim(`Refreshes in ${dur}`)}` : '';
+    lines.push(`    [${bar(b.remainingFraction)}] ${pct}`);
+    lines.push(`    ${dim(remainPct)}${reset}`);
+  }
+  return lines.join('\n');
+}
+
+/** Returns the full panel as a string. */
+export function renderPanel(snap) {
+  const out = [];
+  out.push('');
+  out.push(bold('  Models & Quota'));
+  if (snap.account) out.push(`  ${dim('Account:')} ${snap.account}`);
+  out.push(`  ${dim(`source: ${snap.source}${snap.host ? ` · ${snap.host}` : ''} · ${snap.fetchedAt}`)}`);
+  out.push('');
+
+  for (const g of snap.groups) {
+    out.push(bold(`  ${g.name.toUpperCase()}`));
+    if (g.models) out.push(`  ${dim(`Models within this group: ${g.models}`)}`);
+    out.push('');
+    for (const b of g.buckets) {
+      out.push(bucketLine(b));
+      out.push('');
+    }
+  }
+  if (snap.note) {
+    out.push(dim(wrap(snap.note, 76, '  │')));
+  }
+  return out.join('\n');
+}
+
+function wrap(text, width, prefix) {
+  const words = text.split(/\s+/);
+  const lines = [];
+  let cur = '';
+  for (const w of words) {
+    if ((cur + ' ' + w).trim().length > width) {
+      lines.push(prefix + cur);
+      cur = w;
+    } else {
+      cur = (cur + ' ' + w).trim();
+    }
+  }
+  if (cur) lines.push(prefix + cur);
+  return lines.join('\n');
+}