quse 0.0.1__tar.gz

quse-0.0.1/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: quse
+Version: 0.0.1
+Summary: Quota and usage checks for coding-agent CLIs.
+Author: Alexey Grigorev
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.2.0
+Description-Content-Type: text/markdown
+
+# quse
+
+Quota and usage checks for coding-agent CLIs.
+
+`quse` reports normalized usage for providers used by tools such as Codex,
+Claude Code, GitHub Copilot, and Z.AI/goz.
+
+```bash
+quse
+quse codex
+quse copilot --json
+```
+
+The CLI prints one line per provider by default. `--json` emits the same record
+shape as JSON.
+
+Supported providers:
+
+- `codex`
+- `claude`
+- `copilot`
+- `zai`
+
+`gemini` is accepted and reports `unsupported` because it does not currently
+expose a usage endpoint.
+

quse-0.0.1/README.md

@@ -0,0 +1,26 @@
+# quse
+
+Quota and usage checks for coding-agent CLIs.
+
+`quse` reports normalized usage for providers used by tools such as Codex,
+Claude Code, GitHub Copilot, and Z.AI/goz.
+
+```bash
+quse
+quse codex
+quse copilot --json
+```
+
+The CLI prints one line per provider by default. `--json` emits the same record
+shape as JSON.
+
+Supported providers:
+
+- `codex`
+- `claude`
+- `copilot`
+- `zai`
+
+`gemini` is accepted and reports `unsupported` because it does not currently
+expose a usage endpoint.
+

quse-0.0.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quse"
+version = "0.0.1"
+description = "Quota and usage checks for coding-agent CLIs."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "Alexey Grigorev"}]
+license = {text = "MIT"}
+dependencies = [
+    "click>=8.2.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.0",
+    "hatch>=1.14.0",
+]
+
+[project.scripts]
+quse = "quse.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["quse"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

quse-0.0.1/quse/__init__.py

@@ -0,0 +1,8 @@
+"""Quota helpers for engine adapters."""
+
+from quse._shared import *
+from quse.claude_quota import *
+from quse.codex_quota import *
+from quse.copilot_quota import *
+from quse.usage import *
+from quse.zai_quota import *

quse-0.0.1/quse/_shared.py

@@ -0,0 +1,85 @@
+"""Shared quota status models and normalization helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+
+@dataclass(slots=True)
+class UsageWindow:
+    percent_remaining: float = 100.0
+    reset_at: str | None = None
+
+    @property
+    def used_percent(self) -> float:
+        return max(0.0, 100.0 - self.percent_remaining)
+
+
+@dataclass(slots=True)
+class UsageStatus:
+    limit_reached: bool = False
+    short_term: UsageWindow = field(default_factory=UsageWindow)
+    long_term: UsageWindow = field(default_factory=UsageWindow)
+    checked_at: float = 0.0
+    error: str | None = None
+
+
+def preferred_reset_at(
+    status: UsageStatus,
+    *,
+    include_short_term_fallback: bool = False,
+) -> str | None:
+    if status.long_term.reset_at:
+        return status.long_term.reset_at
+    if include_short_term_fallback:
+        return status.short_term.reset_at
+    return None
+
+
+def usage_limit_block_reason(engine_name: str, status: UsageStatus) -> str | None:
+    if status.error:
+        return None
+    if engine_name == "codex":
+        from quse.codex_quota import codex_quota_block_reason
+
+        return codex_quota_block_reason()
+    if engine_name == "claude":
+        from quse.claude_quota import claude_quota_block_reason
+
+        return claude_quota_block_reason()
+    if engine_name == "copilot":
+        from quse.copilot_quota import copilot_quota_block_reason
+
+        return copilot_quota_block_reason()
+    if engine_name in {"goz", "opencode"}:
+        from quse.zai_quota import zai_quota_block_reason
+
+        return zai_quota_block_reason()
+    if not status.limit_reached:
+        return None
+    reset_at = preferred_reset_at(status, include_short_term_fallback=True)
+    reset_suffix = f", resets {reset_at}" if reset_at else ""
+    return f"{engine_name} usage limit reached{reset_suffix}"
+
+
+def normalize_reset_at(value: object) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        parsed = value
+    else:
+        normalized = str(value).strip()
+        if not normalized:
+            return None
+        try:
+            parsed = datetime.fromisoformat(normalized.replace("Z", "+00:00"))
+        except ValueError:
+            try:
+                parsed = datetime.strptime(normalized, "%Y-%m-%d")
+            except ValueError:
+                return None
+            parsed = parsed.replace(tzinfo=timezone.utc)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

quse-0.0.1/quse/claude_quota.py

@@ -0,0 +1,170 @@
+"""Proactive Claude quota checking via OAuth usage endpoint."""
+
+from dataclasses import dataclass, field
+import json
+import logging
+import os
+import time
+from pathlib import Path
+
+import urllib.error
+import urllib.request
+
+from quse._shared import UsageWindow, normalize_reset_at
+
+logger = logging.getLogger(__name__)
+
+_USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
+_CACHE_TTL_SECONDS = 60
+
+
+@dataclass(slots=True)
+class ClaudeQuotaWindow:
+    used_percent: float = 0.0
+    reset_at: str | None = None
+
+    def __post_init__(self) -> None:
+        self.used_percent = float(self.used_percent)
+        self.reset_at = normalize_reset_at(self.reset_at)
+
+    @property
+    def percent_remaining(self) -> float:
+        return max(0.0, 100.0 - self.used_percent)
+
+
+@dataclass(slots=True)
+class ClaudeQuotaStatus:
+    five_hour: ClaudeQuotaWindow = field(default_factory=ClaudeQuotaWindow)
+    seven_day: ClaudeQuotaWindow = field(default_factory=ClaudeQuotaWindow)
+    limit_reached: bool = False
+    checked_at: float = 0.0
+    error: str | None = None
+    subscription: str | None = None
+
+    @property
+    def short_term(self) -> UsageWindow:
+        return UsageWindow(percent_remaining=self.five_hour.percent_remaining, reset_at=self.five_hour.reset_at)
+
+    @property
+    def long_term(self) -> UsageWindow:
+        return UsageWindow(percent_remaining=self.seven_day.percent_remaining, reset_at=self.seven_day.reset_at)
+
+
+def _default_credentials_path() -> Path:
+    """Resolve Claude credentials path, respecting config dir overrides."""
+    config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
+    if config_dir:
+        return Path(config_dir) / ".credentials.json"
+    return Path.home() / ".claude" / ".credentials.json"
+
+
+_cached_status: ClaudeQuotaStatus | None = None
+
+
+def _read_access_token(creds_path: Path | None = None) -> str | None:
+    path = creds_path or _default_credentials_path()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        oauth = data.get("claudeAiOauth", {})
+        token = oauth.get("accessToken")
+        if token:
+            return token
+        logger.warning("claude credentials missing claudeAiOauth.accessToken")
+        return None
+    except FileNotFoundError:
+        logger.warning("claude credentials not found at %s", path)
+        return None
+    except (json.JSONDecodeError, KeyError, TypeError) as exc:
+        logger.warning("claude credentials parse error: %s", exc)
+        return None
+
+
+def _parse_usage_response(data: dict) -> ClaudeQuotaStatus:
+    five_hour_data = data.get("five_hour")
+    if not isinstance(five_hour_data, dict):
+        five_hour_data = {}
+    seven_day_data = data.get("seven_day")
+    if not isinstance(seven_day_data, dict):
+        seven_day_data = {}
+
+    five_hour = ClaudeQuotaWindow(
+        used_percent=five_hour_data.get("utilization", 0),
+        reset_at=five_hour_data.get("resets_at"),
+    )
+    seven_day = ClaudeQuotaWindow(
+        used_percent=seven_day_data.get("utilization", 0),
+        reset_at=seven_day_data.get("resets_at"),
+    )
+    subscription = data.get("subscription")
+
+    return ClaudeQuotaStatus(
+        five_hour=five_hour,
+        seven_day=seven_day,
+        limit_reached=seven_day.percent_remaining <= 5.0,
+        checked_at=time.monotonic(),
+        subscription=subscription if isinstance(subscription, str) and subscription else None,
+    )
+
+
+def _fetch_usage(token: str, *, timeout: float = 10.0) -> ClaudeQuotaStatus:
+    req = urllib.request.Request(
+        _USAGE_URL,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "anthropic-beta": "oauth-2025-04-20",
+        },
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        return _parse_usage_response(data)
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError, OSError) as exc:
+        logger.warning("claude quota check failed (fail-open): %s", exc)
+        return ClaudeQuotaStatus(checked_at=time.monotonic(), error=str(exc))
+
+
+def check_claude_quota(
+    *,
+    creds_path: Path | None = None,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> ClaudeQuotaStatus:
+    """Check Claude quota proactively. Returns cached result within TTL.
+
+    Fails open: if auth is missing or API call fails, returns a non-blocking status.
+    """
+    global _cached_status
+    if _cached_status is not None and time.monotonic() - _cached_status.checked_at < cache_ttl:
+        return _cached_status
+
+    token = _read_access_token(creds_path)
+    if token is None:
+        return ClaudeQuotaStatus(checked_at=time.monotonic(), error="no-credentials")
+
+    fetcher = _fetch if callable(_fetch) else _fetch_usage
+    _cached_status = fetcher(token)
+    return _cached_status
+
+
+def claude_quota_block_reason(
+    *,
+    creds_path: Path | None = None,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> str | None:
+    """Return a blocking reason string if Claude quota is reached, or None."""
+    status = check_claude_quota(creds_path=creds_path, cache_ttl=cache_ttl, _fetch=_fetch)
+    if status.error:
+        return None  # fail-open
+    if status.limit_reached:
+        return (
+            f"claude usage limit reached "
+            f"(long-term window at {status.long_term.used_percent:.0f}%, resets {status.long_term.reset_at})"
+        )
+    return None
+
+
+def reset_cache() -> None:
+    global _cached_status
+    _cached_status = None

quse-0.0.1/quse/cli.py

@@ -0,0 +1,52 @@
+"""Command-line interface for quse."""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from quse.usage import UnknownProviderError, collect_usage, format_usage_line
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("provider", required=False)
+@click.option("--json", "json_output", is_flag=True, help="Emit machine-readable JSON output.")
+def usage_command(
+    provider: str | None = None,
+    json_output: bool = False,
+) -> int:
+    try:
+        records = collect_usage(provider)
+    except UnknownProviderError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if json_output:
+        if len(records) == 1:
+            click.echo(json.dumps(records[0], sort_keys=True))
+        else:
+            for record in records:
+                click.echo(json.dumps(record, sort_keys=True))
+        return 0
+
+    for record in records:
+        click.echo(format_usage_line(record))
+    return 0
+
+
+app = usage_command
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        result = app.main(args=argv, prog_name="quse", standalone_mode=False)
+    except click.exceptions.Exit as exc:
+        return exc.exit_code
+    except click.ClickException as exc:
+        exc.show()
+        return exc.exit_code
+    return 0 if result is None else int(result)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

quse-0.0.1/quse/codex_quota.py

@@ -0,0 +1,175 @@
+"""Proactive codex quota checking via chatgpt.com API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+import logging
+import time
+from pathlib import Path
+
+import urllib.error
+import urllib.request
+
+from quse._shared import UsageWindow, normalize_reset_at
+
+logger = logging.getLogger(__name__)
+
+_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage"
+_AUTH_PATH = Path.home() / ".codex" / "auth.json"
+_CACHE_TTL_SECONDS = 60
+
+
+@dataclass(slots=True)
+class CodexQuotaWindow:
+    used_percent: float = 0.0
+    reset_at: str | None = None
+
+    def __post_init__(self) -> None:
+        self.used_percent = float(self.used_percent)
+        self.reset_at = normalize_reset_at(self.reset_at)
+
+    @property
+    def percent_remaining(self) -> float:
+        return max(0.0, 100.0 - self.used_percent)
+
+
+@dataclass(slots=True)
+class CodexQuotaStatus:
+    primary_window: CodexQuotaWindow = field(default_factory=CodexQuotaWindow)
+    secondary_window: CodexQuotaWindow = field(default_factory=CodexQuotaWindow)
+    limit_reached: bool = False
+    checked_at: float = 0.0
+    error: str | None = None
+
+    @property
+    def short_term(self) -> UsageWindow:
+        return UsageWindow(percent_remaining=100.0)
+
+    @property
+    def long_term(self) -> UsageWindow:
+        return UsageWindow(
+            percent_remaining=self.secondary_window.percent_remaining,
+            reset_at=self.secondary_window.reset_at,
+        )
+
+    @property
+    def earliest_reset_at(self) -> str | None:
+        reset_candidates = [value for value in (self.primary_window.reset_at, self.secondary_window.reset_at) if value]
+        return min(reset_candidates) if reset_candidates else None
+
+
+_cached_status: CodexQuotaStatus | None = None
+
+
+def _read_bearer_token(auth_path: Path | None = None) -> str | None:
+    path = auth_path or _AUTH_PATH
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        token = data.get("tokens", {}).get("access_token")
+        if token:
+            return token
+        logger.warning("codex auth.json missing tokens.access_token")
+        return None
+    except FileNotFoundError:
+        logger.warning("codex auth.json not found at %s", path)
+        return None
+    except (json.JSONDecodeError, KeyError, TypeError) as exc:
+        logger.warning("codex auth.json parse error: %s", exc)
+        return None
+
+
+def _parse_quota_response(data: dict) -> CodexQuotaStatus:
+    rate_limit = data.get("rate_limit")
+    if not isinstance(rate_limit, dict):
+        rate_limit = {}
+    primary_data = rate_limit.get("primary_window")
+    if not isinstance(primary_data, dict):
+        primary_data = {}
+    secondary_data = rate_limit.get("secondary_window")
+    if not isinstance(secondary_data, dict):
+        secondary_data = {}
+
+    primary_window = CodexQuotaWindow(
+        used_percent=primary_data.get("used_percent", 0),
+        reset_at=primary_data.get("reset_at"),
+    )
+    secondary_window = CodexQuotaWindow(
+        used_percent=secondary_data.get("used_percent", 0),
+        reset_at=secondary_data.get("reset_at"),
+    )
+
+    return CodexQuotaStatus(
+        primary_window=primary_window,
+        secondary_window=secondary_window,
+        limit_reached=bool(rate_limit.get("limit_reached", False)) or secondary_window.used_percent >= 80.0,
+        checked_at=time.monotonic(),
+    )
+
+
+def _fetch_quota(token: str, *, timeout: float = 10.0) -> CodexQuotaStatus:
+    req = urllib.request.Request(
+        _USAGE_URL,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+        },
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        return _parse_quota_response(data)
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError, OSError) as exc:
+        logger.warning("codex quota check failed (fail-open): %s", exc)
+        return CodexQuotaStatus(checked_at=time.monotonic(), error=str(exc))
+
+
+def check_codex_quota(
+    *,
+    auth_path: Path | None = None,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> CodexQuotaStatus:
+    """Check codex quota proactively. Returns cached result within TTL.
+
+    Fails open: if auth is missing or API call fails, returns a non-blocking status.
+    """
+    global _cached_status
+    now = time.monotonic()
+
+    if _cached_status is not None and (now - _cached_status.checked_at) < cache_ttl:
+        return _cached_status
+
+    token = _read_bearer_token(auth_path)
+    if token is None:
+        status = CodexQuotaStatus(checked_at=now, error="no auth token")
+        _cached_status = status
+        return status
+
+    fetcher = _fetch if callable(_fetch) else _fetch_quota
+    status = fetcher(token)
+    _cached_status = status
+    return status
+
+
+def codex_quota_block_reason(
+    *,
+    auth_path: Path | None = None,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> str | None:
+    """Return a blocking reason string if codex quota is exhausted, or None if OK."""
+    status = check_codex_quota(auth_path=auth_path, cache_ttl=cache_ttl, _fetch=_fetch)
+    if status.error is not None:
+        return None  # fail-open
+    if status.limit_reached:
+        reset_info = f", resets {status.long_term.reset_at}" if status.long_term.reset_at else ""
+        return f"codex quota exhausted (weekly window at {status.long_term.used_percent:.0f}%{reset_info})"
+    return None
+
+
+def reset_cache() -> None:
+    """Clear the cached quota status (useful for testing)."""
+    global _cached_status
+    _cached_status = None