agy-cli-usage 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -10,6 +10,21 @@
 
 * use plain v* tags in release-please ([#12](https://github.com/abruption/agy-cli-usage/issues/12)) ([74b648d](https://github.com/abruption/agy-cli-usage/commit/74b648df24967f71a43095a80e7340a6b5ac2e39)), closes [#9](https://github.com/abruption/agy-cli-usage/issues/9)
 
+## [0.4.6](https://github.com/abruption/agy-cli-usage/compare/v0.4.5...v0.4.6) (2026-09-07)
+
+
+### Bug Fixes
+
+* restore the "antigravity" User-Agent the quota API gates on ([#48](https://github.com/abruption/agy-cli-usage/issues/48)) ([c375d5a](https://github.com/abruption/agy-cli-usage/commit/c375d5a3e9c1698cbb1dfe998be6e7c388363986)), closes [#47](https://github.com/abruption/agy-cli-usage/issues/47)
+
+## [0.4.5](https://github.com/abruption/agy-cli-usage/compare/v0.4.4...v0.4.5) (2026-07-03)
+
+
+### Bug Fixes
+
+* derive UA from package version, name error classes, bound update-check timeouts, document env vars in --help, show cache freshness in watch mode ([62becdc](https://github.com/abruption/agy-cli-usage/commit/62becdcf4175d2cda3cec8dc3f5bba13005c0d59)), closes [#32](https://github.com/abruption/agy-cli-usage/issues/32)
+* UA version, error class names, update-check timeouts, --help env vars, watch/cache indicator ([#37](https://github.com/abruption/agy-cli-usage/issues/37)) ([62becdc](https://github.com/abruption/agy-cli-usage/commit/62becdcf4175d2cda3cec8dc3f5bba13005c0d59))
+
 ## [0.4.4](https://github.com/abruption/agy-cli-usage/compare/v0.4.3...v0.4.4) (2026-07-03)
 
 

package/README.md

@@ -107,6 +107,8 @@ The token is **read only** from wherever `agy` stored it. Handled per platform a
 
 Read order: `keyring → OS CLI → Windows credman → token file → PTY`. Override the file path with `AGY_OAUTH_TOKEN_FILE`.
 
+Token files are tried in order: `AGY_OAUTH_TOKEN_FILE`, then `~/.gemini/antigravity-cli/antigravity-oauth-token`, then `~/.gemini/jetski-standalone-oauth-token`. The last one is checked only after every keyring backend has failed — on macOS it sits beside the Keychain entry and can hold an older grant from a different session, so it must not win over a working one.
+
 ## HTTP endpoint (optional)
 
 ```bash

package/dist/src/api.d.ts

@@ -1,7 +1,21 @@
 import type { FetchResult } from './types.js';
+/** Exported for direct unit testing — keeps the UA tied to the real package name/version. */
+export declare function buildUserAgent(): string;
+/**
+ * Why these are distinct: the endpoint uses 401 and 403 for unrelated problems
+ * and only one of them is fixed by signing in again.
+ *   unauthorized — the token was rejected (expired/revoked): re-authenticate.
+ *   not-entitled — the token is fine but the account has no Antigravity
+ *                  license ("You do not have a valid license of this
+ *                  product…"): signing in again changes nothing.
+ *   no-project   — HTTP 200 without `cloudaicompanionProject`.
+ *   http         — anything else (wrong host, 5xx, …).
+ */
+export type ApiErrorKind = 'unauthorized' | 'not-entitled' | 'no-project' | 'http';
 declare class ApiError extends Error {
     status: number;
-    constructor(message: string, status: number);
+    kind: ApiErrorKind;
+    constructor(message: string, status: number, kind?: ApiErrorKind);
 }
 export interface FetchOptions {
     host?: string;

package/dist/src/api.js

@@ -8,15 +8,30 @@
 //
 // 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}`;
+import { currentVersion } from './update.js';
+// The UA is load-bearing, not cosmetic: Cloud Code picks the product from the
+// User-Agent, not from the request body. Without an `antigravity` substring
+// (case-insensitive, position and version format irrelevant) `loadCodeAssist`
+// answers HTTP 200 but omits `cloudaicompanionProject`, so the quota call can
+// never run — sending `ideType: "ANTIGRAVITY"` does not compensate. Dropping
+// that substring is what broke v0.4.5 (#47). Verified against the live daily
+// host on 2026-09-07.
+/** Exported for direct unit testing — keeps the UA tied to the real package name/version. */
+export function buildUserAgent() {
+    return `antigravity-agy-cli-usage/${currentVersion()} ${process.platform}/${process.arch}`;
+}
+const UA = buildUserAgent();
 // 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 {
     status;
-    constructor(message, status) {
+    kind;
+    constructor(message, status, kind) {
         super(message);
+        this.name = 'ApiError';
         this.status = status;
+        this.kind = kind ?? (status === 401 ? 'unauthorized' : status === 403 ? 'not-entitled' : 'http');
     }
 }
 // Known limitation: this is the only email source `loadCodeAssist` exposes —
@@ -71,8 +86,11 @@ export async function fetchQuotaSummary(accessToken, opts = {}) {
                 metadata: { ideType: 'ANTIGRAVITY' },
             });
             const project = lca.cloudaicompanionProject;
-            if (!project)
-                throw new ApiError('loadCodeAssist returned no cloudaicompanionProject', 0);
+            if (!project) {
+                throw new ApiError(`loadCodeAssist on ${host} returned HTTP 200 without cloudaicompanionProject — either the ` +
+                    `request was not recognized as Antigravity (the API reads the product off the User-Agent, ` +
+                    `which must contain "antigravity") or the signed-in account has no Antigravity entitlement`, 0, 'no-project');
+            }
             const raw = await postInternal(host, accessToken, 'retrieveUserQuotaSummary', { project });
             return {
                 raw,
@@ -83,8 +101,11 @@ export async function fetchQuotaSummary(accessToken, opts = {}) {
         }
         catch (err) {
             lastErr = err;
-            // 404 / wrong-host -> try next candidate; auth errors -> stop early.
-            if (err instanceof ApiError && (err.status === 401 || err.status === 403))
+            // 404 / wrong-host -> try next candidate. A rejected token or a missing
+            // license is account-level, identical on every host: stop early.
+            // `no-project` deliberately keeps going — an account can be entitled on
+            // one channel and not the other, and one extra round trip is cheap.
+            if (err instanceof ApiError && (err.kind === 'unauthorized' || err.kind === 'not-entitled'))
                 throw err;
         }
     }

package/dist/src/credentials.d.ts

@@ -1,4 +1,5 @@
 declare class CredentialError extends Error {
+    constructor(message: string);
 }
 interface Cred {
     accessToken: string;

package/dist/src/credentials.js

@@ -35,6 +35,10 @@ const KEYRING_SERVICE = 'gemini';
 const KEYRING_ACCOUNT = 'antigravity';
 const B64_PREFIX = 'go-keyring-base64:';
 class CredentialError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CredentialError';
+    }
 }
 // --- raw keyring read --------------------------------------------------------
 async function readViaNapiEsm() {
@@ -123,10 +127,18 @@ function readViaWindowsCredman() {
 }
 // On headless Linux (no Secret Service) agy persists the token to a plain-JSON
 // file instead of the keyring. Same payload shape, no `go-keyring-base64:` prefix.
+//
+// The jetski path is last on purpose. macOS keeps that file around next to the
+// Keychain entry, and the two can hold *different* grants — an observed one was
+// three days stale and belonged to a session with no Antigravity license, which
+// still refreshes fine and only fails later at the quota call. Every keyring
+// backend is tried first, so this is reached only where the alternative is no
+// credential at all.
 function readViaFile() {
     const candidates = [
         process.env.AGY_OAUTH_TOKEN_FILE,
         join(homedir(), '.gemini', 'antigravity-cli', 'antigravity-oauth-token'),
+        join(homedir(), '.gemini', 'jetski-standalone-oauth-token'),
     ].filter((p) => Boolean(p));
     for (const path of candidates) {
         try {

package/dist/src/main.js

@@ -12,7 +12,7 @@
 //   agy-cli-usage update [--check]  self-update via npm
 //   agy-cli-usage --version | -v  print the installed version
 import { getAccessToken, CredentialError } from './credentials.js';
-import { fetchQuotaSummary } from './api.js';
+import { fetchQuotaSummary, ApiError } from './api.js';
 import { captureUsageViaPty } from './pty-fallback.js';
 import { fromApi, fromPty } from './quota.js';
 import { renderPanel } from './render.js';
@@ -24,6 +24,15 @@ import { fileURLToPath } from 'node:url';
 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;
+// The API path fails in ways that look alike on the wire but need different
+// things from the user — see ApiErrorKind in api.ts. Printing "sign in again"
+// for a missing license just sends people round a loop that cannot help.
+const API_ERROR_HINTS = {
+    unauthorized: 'hint: the stored token was rejected — run `agy` and sign in again.',
+    'not-entitled': 'hint: the token is valid but this Google account has no Antigravity license. Signing in again ' +
+        'will not change that — check which account `agy` is using, or its subscription.',
+    'no-project': 'hint: `--source pty` reads the panel from `agy` itself and does not need this endpoint.',
+};
 const VALID_SOURCES = ['auto', 'api', 'pty'];
 const VALID_CHANNELS = ['auto', 'daily', 'prod'];
 const errMessage = (e) => (e instanceof Error ? e.message : String(e));
@@ -82,6 +91,15 @@ const HELP = `agy-cli-usage — Antigravity CLI (agy) usage/quota monitor
   agy-cli-usage --no-cache | --refresh
   agy-cli-usage update [--check]  self-update via npm (--check: report only)
   agy-cli-usage --version | -v
+
+Environment variables:
+  AGY_OAUTH_TOKEN_FILE  Override the token file path (headless fallback).
+  AGY_BIN               Path to the agy binary (PTY source). Else resolved from
+                        PATH, then ~/.local/bin.
+  XDG_CACHE_HOME        Cache base dir (cache lives at
+                        <base>/agy-usage/quota.json; default ~/.cache).
+  NO_COLOR              Disable ANSI color in the rendered panel.
+  PORT / HOST           HTTP server bind (server mode only).
 `;
 /** Exported for direct unit testing via an injected `cacheFile` — not part of the CLI's public surface. */
 export function readCache(source, channel, cacheFile = CACHE_FILE) {
@@ -197,6 +215,9 @@ if (isMainModule()) {
         }
         else {
             process.stderr.write(`error: ${errMessage(err)}\n`);
+            const hint = err instanceof ApiError ? API_ERROR_HINTS[err.kind] : undefined;
+            if (hint)
+                process.stderr.write(`${hint}\n`);
         }
         process.exit(1);
     });

package/dist/src/render.d.ts

@@ -1,3 +1,3 @@
 import type { Snapshot } from './types.js';
-/** Returns the full panel as a string. */
-export declare function renderPanel(snap: Snapshot): string;
+/** Returns the full panel as a string. `nowMs` is injectable for testing. */
+export declare function renderPanel(snap: Snapshot, nowMs?: number): string;

package/dist/src/render.js

@@ -46,14 +46,40 @@ function bucketLine(b) {
     }
     return lines.join('\n');
 }
-/** Returns the full panel as a string. */
-export function renderPanel(snap) {
+// `--watch`'s default interval (60s) is faster than the 5-minute quota cache
+// TTL, so most refreshes just re-render a cached snapshot with no visual
+// sign the fetch didn't actually happen. `fetchedAt` is set once, when the
+// data was truly fetched (see quota.ts), and carried through untouched on a
+// cache hit — so comparing it to "now" at render time is enough to tell the
+// two cases apart without threading extra state through Snapshot/the cache.
+// A small skew is tolerated so a genuinely fresh fetch isn't mislabeled
+// "cached" just because rendering happened slightly after fetching.
+const FRESHNESS_SKEW_MS = 3_000;
+function formatAge(totalSeconds) {
+    const s = Math.max(0, Math.round(totalSeconds));
+    if (s < 60)
+        return `${s}s`;
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    if (h > 0)
+        return `${h}h ${m}m`;
+    return `${m}m ${s % 60}s`;
+}
+function freshnessSuffix(fetchedAt, nowMs) {
+    const ageMs = nowMs - new Date(fetchedAt).getTime();
+    if (!Number.isFinite(ageMs) || ageMs < FRESHNESS_SKEW_MS)
+        return '';
+    return dim(` (cached, refreshed ${formatAge(ageMs / 1000)} ago)`);
+}
+/** Returns the full panel as a string. `nowMs` is injectable for testing. */
+export function renderPanel(snap, nowMs = Date.now()) {
     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(`  ${dim(`source: ${snap.source}${snap.host ? ` · ${snap.host}` : ''} · ${snap.fetchedAt}`)}` +
+        freshnessSuffix(snap.fetchedAt, nowMs));
     out.push('');
     for (const g of snap.groups) {
         out.push(bold(`  ${g.name.toUpperCase()}`));

package/dist/src/update.d.ts

@@ -9,8 +9,15 @@ export declare function currentVersion(): string;
  * Returns negative if a<b, 0 if equal, positive if a>b.
  */
 export declare function semverCompare(a: string, b: string): number;
+export declare const NPM_VIEW_TIMEOUT_MS = 8000;
+export declare const REGISTRY_FETCH_TIMEOUT_MS = 8000;
+/** Exported for direct unit testing via injection — not part of the public surface. */
+export interface LatestVersionDeps {
+    execNpmView?: (pkgName: string, timeoutMs: number) => string;
+    fetchRegistry?: (pkgName: string, timeoutMs: number) => Promise<Response>;
+}
 /** Latest published version: prefer the user's configured registry (npm view), fall back to public. */
-export declare function latestVersion(): Promise<string | null>;
+export declare function latestVersion(deps?: LatestVersionDeps): Promise<string | null>;
 /** Run the update flow. Returns the intended process exit code. */
 export declare function runUpdate({ checkOnly }?: {
     checkOnly?: boolean;

package/dist/src/update.js

@@ -34,26 +34,42 @@ export function semverCompare(a, b) {
     }
     return 0;
 }
+// Both the `npm view` child process and the registry fetch fallback are
+// bounded so a slow/unreachable registry can't hang the update check
+// indefinitely — a timed-out attempt is treated the same as "unavailable"
+// and falls through to the next strategy (or to `latestVersion` returning
+// null, which `runUpdate` reports as "could not determine the latest version").
+export const NPM_VIEW_TIMEOUT_MS = 8_000;
+export const REGISTRY_FETCH_TIMEOUT_MS = 8_000;
+function defaultExecNpmView(pkgName, timeoutMs) {
+    return execFileSync('npm', ['view', pkgName, 'version'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: timeoutMs,
+    });
+}
+function defaultFetchRegistry(pkgName, timeoutMs) {
+    return fetch(`https://registry.npmjs.org/${pkgName}/latest`, { signal: AbortSignal.timeout(timeoutMs) });
+}
 /** Latest published version: prefer the user's configured registry (npm view), fall back to public. */
-export async function latestVersion() {
+export async function latestVersion(deps = {}) {
+    const execNpmView = deps.execNpmView ?? defaultExecNpmView;
+    const fetchRegistry = deps.fetchRegistry ?? defaultFetchRegistry;
     try {
-        const out = execFileSync('npm', ['view', PKG_NAME, 'version'], {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
+        const out = execNpmView(PKG_NAME, NPM_VIEW_TIMEOUT_MS).trim();
         if (out)
             return out;
     }
     catch {
-        // npm missing or offline — try the public registry directly
+        // npm missing, offline, or timed out — try the public registry directly
     }
     try {
-        const res = await fetch(`https://registry.npmjs.org/${PKG_NAME}/latest`);
+        const res = await fetchRegistry(PKG_NAME, REGISTRY_FETCH_TIMEOUT_MS);
         if (res.ok)
             return (await res.json()).version;
     }
     catch {
-        // offline
+        // offline or timed out
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-cli-usage",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Headless usage/quota monitor for the Antigravity CLI (agy) — reads Cloud Code quota directly, with a PTY fallback. No IDE required.",
   "type": "module",
   "types": "dist/src/main.d.ts",
@@ -56,9 +56,9 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@eslint/js": "^9.39.4",
-    "@types/node": "^26.0.0",
-    "eslint": "^9.39.4",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.2",
+    "eslint": "^10.6.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.62.1"
   }