agy-usage 0.1.0__tar.gz

agy_usage-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: publish
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

agy_usage-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+*.pyc

agy_usage-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: agy-usage
+Version: 0.1.0
+Summary: Antigravity CLI usage and quota monitor
+Project-URL: Homepage, https://github.com/wakamex/agy-usage
+Project-URL: Source, https://github.com/wakamex/agy-usage
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# agy-usage
+
+Antigravity CLI usage and quota monitor. It mirrors the small `ccusage`,
+`gemini-cli-usage`, and `codex-cli-usage` tools: dependency-free Python,
+terminal output, JSON output, statusline output, and a cache-refresh daemon.
+
+## Example output
+
+```text
+Project: agy-usage
+Model: Gemini 3.5 Flash (High)
+  gemini-3.5-flash-high  12.4% used  resets 1h05m
+History: 24 entries, latest 2026-06-29T22:53:01+00:00
+```
+
+Statusline:
+
+```text
+q:12.4% reset:1h05m model:Gemini_3.5_Flash_(High)
+```
+
+## Install
+
+```bash
+uv tool install agy-usage
+```
+
+For local development from a checkout:
+
+```bash
+uv tool install .
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `agy-usage` | Show current usage |
+| `agy-usage status` | Same as above |
+| `agy-usage json` | Print raw JSON |
+| `agy-usage statusline` | Compact statusline output |
+| `agy-usage refresh` | Force a fresh fetch, rewrite cache, and print status |
+| `agy-usage daemon [-i SECS]` | Keep the cache fresh in the foreground |
+| `agy-usage install` | Print setup instructions |
+
+## Data sources
+
+- Antigravity settings: `~/.gemini/antigravity-cli/settings.json`
+- Antigravity OAuth token: `~/.gemini/antigravity-cli/antigravity-oauth-token`
+- Antigravity command history: `~/.gemini/antigravity-cli/history.jsonl`
+- Cache written by this tool: `~/.gemini/antigravity-cli/usage-limits.json`
+
+Quota lookup uses the same Code Assist quota flow Antigravity logs mention:
+`loadCodeAssist` followed by `retrieveUserQuota`.
+
+## Options
+
+```text
+usage: agy-usage [-h] [--root ROOT] [-i INTERVAL] [--max-age MAX_AGE]
+                 [--refresh]
+                 {status,json,daemon,statusline,refresh,install}
+```
+
+- `--root ROOT`: inspect a different project root instead of the current directory
+- `--max-age MAX_AGE`: cache TTL for `statusline`
+- `--refresh`: ignore the cache and rebuild fresh data where applicable
+
+Environment overrides:
+
+- `AGY_USAGE_FILE`: alternate cache path
+- `AGY_ACCESS_TOKEN`: provide an access token instead of reading Antigravity state
+- `AGY_CODE_ASSIST_BASE_URL`: alternate Code Assist base URL

agy_usage-0.1.0/README.md

@@ -0,0 +1,72 @@
+# agy-usage
+
+Antigravity CLI usage and quota monitor. It mirrors the small `ccusage`,
+`gemini-cli-usage`, and `codex-cli-usage` tools: dependency-free Python,
+terminal output, JSON output, statusline output, and a cache-refresh daemon.
+
+## Example output
+
+```text
+Project: agy-usage
+Model: Gemini 3.5 Flash (High)
+  gemini-3.5-flash-high  12.4% used  resets 1h05m
+History: 24 entries, latest 2026-06-29T22:53:01+00:00
+```
+
+Statusline:
+
+```text
+q:12.4% reset:1h05m model:Gemini_3.5_Flash_(High)
+```
+
+## Install
+
+```bash
+uv tool install agy-usage
+```
+
+For local development from a checkout:
+
+```bash
+uv tool install .
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `agy-usage` | Show current usage |
+| `agy-usage status` | Same as above |
+| `agy-usage json` | Print raw JSON |
+| `agy-usage statusline` | Compact statusline output |
+| `agy-usage refresh` | Force a fresh fetch, rewrite cache, and print status |
+| `agy-usage daemon [-i SECS]` | Keep the cache fresh in the foreground |
+| `agy-usage install` | Print setup instructions |
+
+## Data sources
+
+- Antigravity settings: `~/.gemini/antigravity-cli/settings.json`
+- Antigravity OAuth token: `~/.gemini/antigravity-cli/antigravity-oauth-token`
+- Antigravity command history: `~/.gemini/antigravity-cli/history.jsonl`
+- Cache written by this tool: `~/.gemini/antigravity-cli/usage-limits.json`
+
+Quota lookup uses the same Code Assist quota flow Antigravity logs mention:
+`loadCodeAssist` followed by `retrieveUserQuota`.
+
+## Options
+
+```text
+usage: agy-usage [-h] [--root ROOT] [-i INTERVAL] [--max-age MAX_AGE]
+                 [--refresh]
+                 {status,json,daemon,statusline,refresh,install}
+```
+
+- `--root ROOT`: inspect a different project root instead of the current directory
+- `--max-age MAX_AGE`: cache TTL for `statusline`
+- `--refresh`: ignore the cache and rebuild fresh data where applicable
+
+Environment overrides:
+
+- `AGY_USAGE_FILE`: alternate cache path
+- `AGY_ACCESS_TOKEN`: provide an access token instead of reading Antigravity state
+- `AGY_CODE_ASSIST_BASE_URL`: alternate Code Assist base URL

agy_usage-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "agy-usage"
+version = "0.1.0"
+description = "Antigravity CLI usage and quota monitor"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agy_usage"]
+
+[project.urls]
+Homepage = "https://github.com/wakamex/agy-usage"
+Source = "https://github.com/wakamex/agy-usage"
+
+[project.scripts]
+agy-usage = "agy_usage:main"
+agyusage = "agy_usage:main"

agy_usage-0.1.0/src/agy_usage/__init__.py

@@ -0,0 +1,513 @@
+#!/usr/bin/env python3
+"""agy-usage - Antigravity CLI usage and quota monitor."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import signal
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections import Counter
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+AGY_DIR = Path.home() / ".gemini" / "antigravity-cli"
+TOKEN_FILE = AGY_DIR / "antigravity-oauth-token"
+SETTINGS_FILE = AGY_DIR / "settings.json"
+HISTORY_FILE = AGY_DIR / "history.jsonl"
+DEFAULT_USAGE_FILE = AGY_DIR / "usage-limits.json"
+
+DAEMON_INTERVAL = 300
+CACHE_MAX_AGE = 300
+CODE_ASSIST_BASE_URL = "https://daily-cloudcode-pa.googleapis.com/v1internal"
+
+_TTY = sys.stdout.isatty()
+_RED = "\033[0;31m" if _TTY else ""
+_YELLOW = "\033[0;33m" if _TTY else ""
+_GREEN = "\033[0;32m" if _TTY else ""
+_DIM = "\033[0;90m" if _TTY else ""
+_RESET = "\033[0m" if _TTY else ""
+
+
+def _read_json(path: Path) -> dict | list | None:
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _iso_now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _parse_iso(timestamp: str | None) -> datetime | None:
+    if not timestamp:
+        return None
+    try:
+        parsed = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed
+
+
+def _format_duration_until(iso_timestamp: str | None) -> str:
+    reset = _parse_iso(iso_timestamp)
+    if not reset:
+        return ""
+    seconds = int((reset - datetime.now(UTC)).total_seconds())
+    if seconds <= 0:
+        return ""
+    minutes = seconds // 60
+    if minutes >= 60:
+        return f"{minutes // 60}h{minutes % 60}m"
+    return f"{minutes}m"
+
+
+def _format_pct(pct: float | int | None) -> str:
+    if pct is None:
+        return "?"
+    value = float(pct)
+    if value >= 1:
+        return f"{value:.1f}%"
+    return f"{value:.2f}%"
+
+
+def _color_pct(pct: float | int | None) -> str:
+    if pct is None:
+        return "?"
+    value = float(pct)
+    color = _RED if value >= 70 else _YELLOW if value >= 40 else _GREEN
+    return f"{color}{_format_pct(value)}{_RESET}"
+
+
+def get_usage_file() -> Path:
+    override = os.environ.get("AGY_USAGE_FILE") or os.environ.get("ANTIGRAVITY_USAGE_FILE")
+    return Path(override).expanduser() if override else DEFAULT_USAGE_FILE
+
+
+def get_settings() -> dict:
+    data = _read_json(SETTINGS_FILE)
+    return data if isinstance(data, dict) else {}
+
+
+def get_auth() -> dict | None:
+    data = _read_json(TOKEN_FILE)
+    return data if isinstance(data, dict) else None
+
+
+def get_access_token() -> str:
+    env_token = os.environ.get("AGY_ACCESS_TOKEN") or os.environ.get("ANTIGRAVITY_ACCESS_TOKEN")
+    if env_token:
+        return env_token
+
+    auth = get_auth()
+    if not auth:
+        raise RuntimeError("No Antigravity OAuth token at ~/.gemini/antigravity-cli/antigravity-oauth-token")
+
+    token_payload = auth.get("token")
+    token = auth.get("access_token") or auth.get("AccessToken")
+    if isinstance(token_payload, dict):
+        token = token or token_payload.get("access_token") or token_payload.get("AccessToken")
+    elif isinstance(token_payload, str):
+        token = token or token_payload
+    if not isinstance(token, str) or not token:
+        raise RuntimeError("No access token in ~/.gemini/antigravity-cli/antigravity-oauth-token")
+    return token
+
+
+def _code_assist_post(method: str, payload: dict, access_token: str) -> dict:
+    base_url = os.environ.get("AGY_CODE_ASSIST_BASE_URL", CODE_ASSIST_BASE_URL).rstrip("/")
+    req = urllib.request.Request(
+        f"{base_url}:{method}",
+        data=json.dumps(payload).encode(),
+        headers={
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "agy-usage/0.1.0",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read())
+
+
+def _load_code_assist(access_token: str) -> dict:
+    project_id = (
+        os.environ.get("GOOGLE_CLOUD_PROJECT")
+        or os.environ.get("GOOGLE_CLOUD_PROJECT_ID")
+        or _read_default_project_id()
+    )
+    metadata: dict[str, Any] = {
+        "ideType": "IDE_UNSPECIFIED",
+        "platform": "PLATFORM_UNSPECIFIED",
+        "pluginType": "GEMINI",
+    }
+    if project_id:
+        metadata["duetProject"] = project_id
+    return _code_assist_post(
+        "loadCodeAssist",
+        {
+            "cloudaicompanionProject": project_id,
+            "metadata": metadata,
+        },
+        access_token,
+    )
+
+
+def _read_default_project_id() -> str | None:
+    try:
+        project_id = (AGY_DIR / "cache" / "default_project_id.txt").read_text().strip()
+    except OSError:
+        return None
+    return project_id or None
+
+
+def _parse_quota_buckets(buckets: list[dict]) -> list[dict]:
+    parsed = []
+    for bucket in buckets:
+        remaining = None
+        limit = None
+        used_pct = None
+        remaining_fraction = bucket.get("remainingFraction")
+
+        try:
+            if bucket.get("remainingAmount") is not None:
+                remaining = int(bucket["remainingAmount"])
+        except (TypeError, ValueError):
+            remaining = None
+
+        if isinstance(remaining_fraction, int | float):
+            used_pct = (1 - float(remaining_fraction)) * 100
+        if remaining is not None and isinstance(remaining_fraction, int | float):
+            if remaining_fraction > 0:
+                limit = round(remaining / float(remaining_fraction))
+
+        parsed.append(
+            {
+                "model": bucket.get("modelId") or bucket.get("model"),
+                "remaining": remaining,
+                "limit": limit,
+                "used_pct": used_pct,
+                "remaining_fraction": remaining_fraction,
+                "reset_time": bucket.get("resetTime"),
+                "token_type": bucket.get("tokenType"),
+                "disabled": bool(bucket.get("disabled", False)),
+            }
+        )
+    return parsed
+
+
+def _select_summary_bucket(quota: dict) -> dict | None:
+    buckets = quota.get("buckets") or []
+    if not isinstance(buckets, list):
+        return None
+    active = [bucket for bucket in buckets if not bucket.get("disabled")]
+    scored = [bucket for bucket in active if bucket.get("used_pct") is not None]
+    if scored:
+        return max(scored, key=lambda bucket: bucket["used_pct"])
+    return active[0] if active else (buckets[0] if buckets else None)
+
+
+def fetch_quota() -> dict:
+    access_token = get_access_token()
+    load_res = _load_code_assist(access_token)
+
+    project_id = (
+        load_res.get("cloudaicompanionProject")
+        or os.environ.get("GOOGLE_CLOUD_PROJECT")
+        or os.environ.get("GOOGLE_CLOUD_PROJECT_ID")
+        or _read_default_project_id()
+    )
+    if not project_id:
+        raise RuntimeError("No Code Assist project ID available. Set GOOGLE_CLOUD_PROJECT if needed.")
+
+    quota_res = _code_assist_post("retrieveUserQuota", {"project": project_id}, access_token)
+    current_tier = load_res.get("currentTier") or {}
+    paid_tier = load_res.get("paidTier") or {}
+    result = {
+        "project_id": project_id,
+        "user_tier": paid_tier.get("id") or current_tier.get("id"),
+        "user_tier_name": paid_tier.get("name") or current_tier.get("name"),
+        "buckets": _parse_quota_buckets(quota_res.get("buckets") or []),
+    }
+    result["summary_bucket"] = _select_summary_bucket(result)
+    credits = quota_res.get("credits") or quota_res.get("g1Credits")
+    if credits is not None:
+        result["credits"] = credits
+    return result
+
+
+def read_history_summary(path: Path = HISTORY_FILE) -> dict:
+    commands: Counter[str] = Counter()
+    workspaces: Counter[str] = Counter()
+    total = 0
+    latest_ms: int | None = None
+
+    try:
+        lines = path.read_text().splitlines()
+    except OSError:
+        lines = []
+
+    for line in lines:
+        try:
+            item = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(item, dict):
+            continue
+        total += 1
+        display = item.get("display")
+        workspace = item.get("workspace")
+        timestamp = item.get("timestamp")
+        if isinstance(display, str):
+            commands[display] += 1
+        if isinstance(workspace, str):
+            workspaces[workspace] += 1
+        if isinstance(timestamp, int):
+            latest_ms = timestamp if latest_ms is None else max(latest_ms, timestamp)
+
+    latest_at = (
+        datetime.fromtimestamp(latest_ms / 1000, tz=UTC).isoformat()
+        if latest_ms is not None
+        else None
+    )
+    return {
+        "entries": total,
+        "latest_at": latest_at,
+        "top_commands": dict(commands.most_common(10)),
+        "top_workspaces": dict(workspaces.most_common(10)),
+    }
+
+
+def build_usage_json(project_root: Path | None = None) -> dict:
+    root = (project_root or Path.cwd()).resolve()
+    settings = get_settings()
+    result = {
+        "project_root": str(root),
+        "model": settings.get("model"),
+        "source": [],
+        "updated_at": _iso_now(),
+        "history": read_history_summary(),
+    }
+    if result["history"]["entries"]:
+        result["source"].append("history")
+
+    try:
+        result["account_quota"] = fetch_quota()
+        result["source"].append("quota_api")
+    except Exception as exc:
+        result["quota_error"] = str(exc)
+
+    return result
+
+
+def write_usage_file(data: dict):
+    usage_file = get_usage_file()
+    usage_file.parent.mkdir(parents=True, exist_ok=True)
+    usage_file.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def _print_status(data: dict):
+    print(f"Project: {Path(data['project_root']).name}")
+    model = data.get("model")
+    if model:
+        print(f"Model: {model}")
+
+    quota = data.get("account_quota")
+    if quota:
+        bucket_names = [
+            (bucket.get("model") or "unknown")
+            for bucket in quota.get("buckets", [])
+            if isinstance(bucket, dict)
+        ]
+        name_width = max(map(len, bucket_names), default=len("Quota"))
+        for bucket in quota.get("buckets", []):
+            model_name = bucket.get("model") or "unknown"
+            if bucket.get("disabled"):
+                print(f"  {model_name:{name_width}s} {_DIM}disabled{_RESET}")
+                continue
+            reset_time = _format_duration_until(bucket.get("reset_time"))
+            reset_part = f"  resets {reset_time}" if reset_time else ""
+            remaining = bucket.get("remaining")
+            limit = bucket.get("limit")
+            remain_part = (
+                f"  {remaining} / {limit} remaining"
+                if remaining is not None and limit is not None
+                else ""
+            )
+            print(
+                f"  {model_name:{name_width}s} {_color_pct(bucket.get('used_pct'))} used"
+                f"{remain_part}{_DIM}{reset_part}{_RESET}"
+            )
+    elif data.get("quota_error"):
+        print(f"  {'Quota':20s} {_DIM}{data['quota_error']}{_RESET}")
+
+    history = data.get("history") or {}
+    if history.get("entries"):
+        latest = history.get("latest_at") or "unknown"
+        print(f"History: {history['entries']} entries, latest {latest}")
+
+
+def _statusline_text(data: dict) -> str:
+    parts = []
+    quota = data.get("account_quota")
+    if quota and quota.get("summary_bucket"):
+        summary = quota["summary_bucket"]
+        if summary.get("disabled"):
+            parts.append("q:disabled")
+        elif summary.get("used_pct") is not None:
+            parts.append(f"q:{_format_pct(summary['used_pct'])}")
+        reset_time = _format_duration_until(summary.get("reset_time"))
+        if reset_time:
+            parts.append(f"reset:{reset_time}")
+    elif data.get("quota_error"):
+        parts.append("q:err")
+
+    model = data.get("model")
+    if model:
+        parts.append(f"model:{model.replace(' ', '_')}")
+    return " ".join(parts)
+
+
+def _get_cached_usage(
+    project_root: Path | None = None,
+    max_age: int = CACHE_MAX_AGE,
+    force_refresh: bool = False,
+) -> dict:
+    usage_file = get_usage_file()
+    root = str((project_root or Path.cwd()).resolve())
+    if not force_refresh:
+        try:
+            cached = json.loads(usage_file.read_text())
+            updated = _parse_iso(cached.get("updated_at"))
+            if updated and cached.get("project_root") == root:
+                age = (datetime.now(UTC) - updated).total_seconds()
+                if age < max_age and "quota_api" in cached.get("source", []):
+                    return cached
+        except Exception:
+            pass
+
+    try:
+        fresh = build_usage_json(project_root)
+        write_usage_file(fresh)
+        return fresh
+    except Exception:
+        try:
+            return json.loads(usage_file.read_text())
+        except Exception:
+            return build_usage_json(project_root)
+
+
+def cmd_status(args):
+    data = build_usage_json(project_root=Path(args.root).resolve() if args.root else None)
+    _print_status(data)
+
+
+def cmd_json(args):
+    data = build_usage_json(project_root=Path(args.root).resolve() if args.root else None)
+    print(json.dumps(data, indent=2))
+
+
+def cmd_daemon(args):
+    signal.signal(signal.SIGINT, lambda *_: sys.exit(0))
+    if hasattr(signal, "SIGTERM"):
+        signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+
+    root = Path(args.root).resolve() if args.root else None
+    usage_file = get_usage_file()
+
+    print(f"agy-usage daemon started (refreshing every {args.interval}s)")
+    print(f"Writing to {usage_file}")
+
+    while True:
+        try:
+            data = build_usage_json(project_root=root)
+            write_usage_file(data)
+            print(f"[{datetime.now().strftime('%H:%M:%S')}] {_statusline_text(data)}")
+        except Exception as exc:
+            print(f"[{datetime.now().strftime('%H:%M:%S')}] Error: {exc}", file=sys.stderr)
+        time.sleep(args.interval)
+
+
+def cmd_statusline(args):
+    data = _get_cached_usage(
+        project_root=Path(args.root).resolve() if args.root else None,
+        max_age=args.max_age,
+        force_refresh=args.refresh,
+    )
+    print(_statusline_text(data))
+
+
+def cmd_refresh(args):
+    data = build_usage_json(project_root=Path(args.root).resolve() if args.root else None)
+    write_usage_file(data)
+    _print_status(data)
+
+
+def cmd_install(_args):
+    print(
+        "Install with:\n"
+        "  uv tool install agy-usage\n\n"
+        "For local development:\n"
+        "  uv tool install .\n\n"
+        "Then run:\n"
+        "  agy-usage\n"
+        "  agy-usage statusline\n"
+        "  agy-usage refresh\n"
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Antigravity CLI usage and quota monitor")
+    parser.add_argument(
+        "command",
+        nargs="?",
+        default="status",
+        choices=["status", "json", "daemon", "statusline", "refresh", "install"],
+    )
+    parser.add_argument("--root", help="Project root to inspect (default: current working directory)")
+    parser.add_argument(
+        "-i",
+        "--interval",
+        type=int,
+        default=DAEMON_INTERVAL,
+        help="Daemon refresh interval in seconds",
+    )
+    parser.add_argument(
+        "--max-age",
+        type=int,
+        default=CACHE_MAX_AGE,
+        help="Maximum cache age in seconds for statusline",
+    )
+    parser.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Ignore cache and force a fresh fetch where applicable",
+    )
+    return parser
+
+
+def main():
+    parser = _build_parser()
+    args = parser.parse_args()
+    commands = {
+        "status": cmd_status,
+        "json": cmd_json,
+        "daemon": cmd_daemon,
+        "statusline": cmd_statusline,
+        "refresh": cmd_refresh,
+        "install": cmd_install,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

agy_usage-0.1.0/src/agy_usage/__main__.py

@@ -0,0 +1,3 @@
+from agy_usage import main
+
+main()

agy_usage-0.1.0/tests/test_agy_usage.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import unittest
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from unittest import mock
+
+import agy_usage
+
+
+def _write_json(path: Path, payload: dict):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload) + "\n")
+
+
+class AgyUsageTests(unittest.TestCase):
+    def test_parse_quota_buckets_computes_usage_and_limit(self):
+        buckets = agy_usage._parse_quota_buckets(
+            [
+                {
+                    "modelId": "gemini-test",
+                    "remainingAmount": "25",
+                    "remainingFraction": 0.5,
+                    "resetTime": "2026-06-30T01:00:00Z",
+                }
+            ]
+        )
+
+        self.assertEqual(buckets[0]["model"], "gemini-test")
+        self.assertEqual(buckets[0]["remaining"], 25)
+        self.assertEqual(buckets[0]["limit"], 50)
+        self.assertEqual(buckets[0]["used_pct"], 50)
+
+    def test_summary_bucket_skips_disabled_and_picks_highest_used(self):
+        quota = {
+            "buckets": [
+                {"model": "disabled", "used_pct": 99, "disabled": True},
+                {"model": "flash", "used_pct": 10},
+                {"model": "pro", "used_pct": 75},
+            ]
+        }
+
+        self.assertEqual(agy_usage._select_summary_bucket(quota)["model"], "pro")
+
+    def test_read_history_summary_counts_commands_and_workspaces(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            history = Path(tmp) / "history.jsonl"
+            history.write_text(
+                json.dumps({"display": "/usage", "timestamp": 1_000, "workspace": "/code/a"}) + "\n"
+                + "not json\n"
+                + json.dumps({"display": "/model", "timestamp": 2_000, "workspace": "/code/a"}) + "\n"
+                + json.dumps({"display": "/usage", "timestamp": 3_000, "workspace": "/code/b"}) + "\n"
+            )
+
+            summary = agy_usage.read_history_summary(history)
+
+        self.assertEqual(summary["entries"], 3)
+        self.assertEqual(summary["top_commands"]["/usage"], 2)
+        self.assertEqual(summary["top_workspaces"]["/code/a"], 2)
+        self.assertEqual(summary["latest_at"], "1970-01-01T00:00:03+00:00")
+
+    def test_access_token_can_come_from_env(self):
+        with mock.patch.dict(os.environ, {"AGY_ACCESS_TOKEN": "token"}, clear=True):
+            self.assertEqual(agy_usage.get_access_token(), "token")
+
+    def test_access_token_reads_nested_antigravity_token_file(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            token_file = Path(tmp) / "antigravity-oauth-token"
+            _write_json(
+                token_file,
+                {
+                    "auth_method": "consumer",
+                    "token": {
+                        "access_token": "nested-token",
+                        "token_type": "Bearer",
+                    },
+                },
+            )
+
+            with (
+                mock.patch.object(agy_usage, "TOKEN_FILE", token_file),
+                mock.patch.dict(os.environ, {}, clear=True),
+            ):
+                self.assertEqual(agy_usage.get_access_token(), "nested-token")
+
+    def test_build_usage_json_includes_history_when_quota_fails(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            history = tmp_path / "history.jsonl"
+            settings = tmp_path / "settings.json"
+            _write_json(settings, {"model": "Gemini Test"})
+            history.write_text(json.dumps({"display": "/usage", "timestamp": 1_000}) + "\n")
+
+            with (
+                mock.patch.object(agy_usage, "HISTORY_FILE", history),
+                mock.patch.object(agy_usage, "SETTINGS_FILE", settings),
+                mock.patch.object(agy_usage, "fetch_quota", side_effect=RuntimeError("no quota")),
+            ):
+                usage = agy_usage.build_usage_json(tmp_path)
+
+        self.assertEqual(usage["model"], "Gemini Test")
+        self.assertIn("history", usage["source"])
+        self.assertEqual(usage["quota_error"], "no quota")
+
+    def test_force_refresh_bypasses_cache(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            project_root = tmp_path / "project"
+            project_root.mkdir()
+            usage_file = tmp_path / "usage-limits.json"
+            cached = {
+                "project_root": str(project_root.resolve()),
+                "source": ["quota_api"],
+                "updated_at": datetime.now(UTC).isoformat(),
+            }
+            fresh = {
+                "project_root": str(project_root.resolve()),
+                "source": ["quota_api"],
+                "updated_at": (datetime.now(UTC) + timedelta(seconds=1)).isoformat(),
+            }
+            usage_file.write_text(json.dumps(cached) + "\n")
+
+            with (
+                mock.patch.object(agy_usage, "DEFAULT_USAGE_FILE", usage_file),
+                mock.patch.dict(os.environ, {}, clear=True),
+                mock.patch.object(agy_usage, "build_usage_json", return_value=fresh) as build_mock,
+            ):
+                result = agy_usage._get_cached_usage(project_root=project_root)
+                self.assertEqual(result, cached)
+                build_mock.assert_not_called()
+
+                result = agy_usage._get_cached_usage(project_root=project_root, force_refresh=True)
+
+            self.assertEqual(result, fresh)
+            self.assertEqual(json.loads(usage_file.read_text()), fresh)
+
+
+if __name__ == "__main__":
+    unittest.main()

agy_usage-0.1.0/uv.lock

@@ -0,0 +1,20 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"
+
+[options]
+exclude-newer = "2026-06-23T03:29:12.769788954Z"
+exclude-newer-span = "P7D"
+
+[options.exclude-newer-package]
+clanker-analytics = false
+ghp = false
+search-claude-history = false
+gemini-cli-usage = false
+ccusage = false
+codex-cli-usage = false
+
+[[package]]
+name = "agy-usage"
+version = "0.1.0"
+source = { editable = "." }