quse 0.0.1__py3-none-any.whl

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/_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/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/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/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

quse/copilot_quota.py

@@ -0,0 +1,119 @@
+"""Proactive Copilot quota checking via GitHub API."""
+
+from dataclasses import dataclass
+import json
+import logging
+import subprocess
+import time
+
+from quse._shared import UsageWindow, normalize_reset_at
+
+logger = logging.getLogger(__name__)
+
+_CACHE_TTL_SECONDS = 60
+
+
+@dataclass(slots=True)
+class CopilotQuotaStatus:
+    premium_remaining: int | None = None
+    premium_entitlement: int | None = None
+    premium_percent_remaining: float = 100.0
+    quota_reset_date: str | None = None
+    checked_at: float = 0.0
+    error: str | None = None
+
+    def __post_init__(self) -> None:
+        self.premium_percent_remaining = float(self.premium_percent_remaining)
+        self.quota_reset_date = normalize_reset_at(self.quota_reset_date)
+
+    @property
+    def used_percent(self) -> float:
+        return max(0.0, 100.0 - self.premium_percent_remaining)
+
+    @property
+    def limit_reached(self) -> bool:
+        return self.error is None and self.premium_percent_remaining <= 20.0
+
+    @property
+    def short_term(self) -> UsageWindow:
+        return UsageWindow(percent_remaining=100.0)
+
+    @property
+    def long_term(self) -> UsageWindow:
+        return UsageWindow(percent_remaining=self.premium_percent_remaining, reset_at=self.quota_reset_date)
+
+
+_cached_status: CopilotQuotaStatus | None = None
+
+
+def _fetch_quota(*, timeout: float = 10.0) -> CopilotQuotaStatus:
+    try:
+        result = subprocess.run(
+            ["gh", "api", "/copilot_internal/user"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if result.returncode != 0:
+            return CopilotQuotaStatus(checked_at=time.monotonic(), error=f"gh exit {result.returncode}")
+        data = json.loads(result.stdout)
+    except FileNotFoundError:
+        return CopilotQuotaStatus(checked_at=time.monotonic(), error="gh not on PATH")
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError) as exc:
+        logger.warning("copilot quota check failed (fail-open): %s", exc)
+        return CopilotQuotaStatus(checked_at=time.monotonic(), error=str(exc))
+
+    snapshots = data.get("quota_snapshots")
+    if not isinstance(snapshots, dict):
+        snapshots = {}
+    premium = snapshots.get("premium_interactions")
+    if not isinstance(premium, dict):
+        premium = {}
+
+    if premium.get("unlimited", False):
+        return CopilotQuotaStatus(checked_at=time.monotonic())
+
+    return CopilotQuotaStatus(
+        premium_remaining=premium.get("remaining") if isinstance(premium.get("remaining"), int) else None,
+        premium_entitlement=premium.get("entitlement") if isinstance(premium.get("entitlement"), int) else None,
+        premium_percent_remaining=max(0.0, float(premium.get("percent_remaining", 100.0))),
+        quota_reset_date=data.get("quota_reset_date"),
+        checked_at=time.monotonic(),
+    )
+
+
+def check_copilot_quota(
+    *,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> CopilotQuotaStatus:
+    """Check Copilot quota via gh CLI. Returns cached result within TTL. Fails open."""
+    global _cached_status
+    if _cached_status is not None and time.monotonic() - _cached_status.checked_at < cache_ttl:
+        return _cached_status
+
+    fetcher = _fetch if callable(_fetch) else _fetch_quota
+    _cached_status = fetcher()
+    return _cached_status
+
+
+def copilot_quota_block_reason(
+    *,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> str | None:
+    """Return a blocking reason if Copilot quota is reached, or None."""
+    status = check_copilot_quota(cache_ttl=cache_ttl, _fetch=_fetch)
+    if status.error:
+        return None  # fail-open
+    if status.limit_reached:
+        return (
+            f"copilot premium requests low "
+            f"({status.long_term.percent_remaining:.0f}% remaining, resets {status.long_term.reset_at})"
+        )
+    return None
+
+
+def reset_cache() -> None:
+    global _cached_status
+    _cached_status = None

quse/usage.py

@@ -0,0 +1,223 @@
+"""Normalized usage records for supported coding-agent providers."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from quse import claude_quota, codex_quota, copilot_quota, zai_quota
+
+USAGE_PROVIDER_CHOICES = ("codex", "claude", "copilot", "zai", "gemini")
+SUPPORTED_USAGE_PROVIDERS = ("codex", "claude", "copilot", "zai")
+
+
+class UnknownProviderError(ValueError):
+    """Raised when a provider name is not supported."""
+
+
+def usage_provider_error_message(name: str) -> str:
+    valid_names = ", ".join(USAGE_PROVIDER_CHOICES)
+    return f"Unknown provider '{name}'. Valid provider names: {valid_names}."
+
+
+def usage_window_record(
+    *,
+    provider: str,
+    status: str,
+    used: float | int | None,
+    limit: float | int | None,
+    remaining: float | int | None,
+    unit: str | None,
+    reset_window: str | None,
+    reset_at: str | None,
+    block_reason: str | None,
+    error: str | None = None,
+    details: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {
+        "provider": provider,
+        "status": status,
+        "used": used,
+        "limit": limit,
+        "remaining": remaining,
+        "unit": unit,
+        "reset_window": reset_window,
+        "reset_at": reset_at,
+        "block_reason": block_reason,
+        "error": error,
+        "details": details or {},
+    }
+
+
+def _pick_named_window(windows: dict[str, Any]) -> tuple[str, Any]:
+    return max(windows.items(), key=lambda item: item[1].used_percent)
+
+
+def normalize_usage_provider(provider: str) -> dict[str, Any]:
+    if provider == "gemini":
+        return usage_window_record(
+            provider="gemini",
+            status="unsupported",
+            used=None,
+            limit=None,
+            remaining=None,
+            unit=None,
+            reset_window=None,
+            reset_at=None,
+            block_reason=None,
+            error="unsupported",
+        )
+
+    if provider == "codex":
+        status_obj = codex_quota.check_codex_quota()
+        block_reason = codex_quota.codex_quota_block_reason()
+        windows = {
+            "primary_window": status_obj.primary_window,
+            "secondary_window": status_obj.secondary_window,
+        }
+        selected_name, selected_window = _pick_named_window(windows)
+        status = "error" if status_obj.error else "blocked" if block_reason else "ok"
+        used = round(selected_window.used_percent, 2)
+        limit = 100.0
+        remaining = round(max(0.0, limit - used), 2)
+        return usage_window_record(
+            provider=provider,
+            status=status,
+            used=None if status_obj.error else used,
+            limit=None if status_obj.error else limit,
+            remaining=None if status_obj.error else remaining,
+            unit="percent",
+            reset_window=selected_name,
+            reset_at=selected_window.reset_at or status_obj.earliest_reset_at,
+            block_reason=block_reason,
+            error=status_obj.error,
+            details={
+                "limit_reached": status_obj.limit_reached,
+                "windows": {
+                    "primary_window": asdict(status_obj.primary_window),
+                    "secondary_window": asdict(status_obj.secondary_window),
+                },
+            },
+        )
+
+    if provider == "claude":
+        status_obj = claude_quota.check_claude_quota()
+        block_reason = claude_quota.claude_quota_block_reason()
+        windows = {
+            "five_hour": status_obj.five_hour,
+            "seven_day": status_obj.seven_day,
+        }
+        selected_name, selected_window = _pick_named_window(windows)
+        status = "error" if status_obj.error else "blocked" if block_reason else "ok"
+        used = round(selected_window.used_percent, 2)
+        limit = 100.0
+        remaining = round(max(0.0, limit - used), 2)
+        return usage_window_record(
+            provider=provider,
+            status=status,
+            used=None if status_obj.error else used,
+            limit=None if status_obj.error else limit,
+            remaining=None if status_obj.error else remaining,
+            unit="percent",
+            reset_window=selected_name,
+            reset_at=selected_window.reset_at,
+            block_reason=block_reason,
+            error=status_obj.error,
+            details={
+                "limit_reached": status_obj.limit_reached,
+                "subscription": status_obj.subscription,
+                "windows": {
+                    "five_hour": asdict(status_obj.five_hour),
+                    "seven_day": asdict(status_obj.seven_day),
+                },
+            },
+        )
+
+    if provider == "copilot":
+        status_obj = copilot_quota.check_copilot_quota()
+        block_reason = copilot_quota.copilot_quota_block_reason()
+        status = "error" if status_obj.error else "blocked" if block_reason else "ok"
+        used = round(status_obj.used_percent, 2)
+        limit = status_obj.premium_entitlement
+        remaining = status_obj.premium_remaining
+        return usage_window_record(
+            provider=provider,
+            status=status,
+            used=None if status_obj.error else used,
+            limit=None if status_obj.error else limit,
+            remaining=None if status_obj.error else remaining,
+            unit="premium_interactions",
+            reset_window="monthly",
+            reset_at=status_obj.quota_reset_date,
+            block_reason=block_reason,
+            error=status_obj.error,
+            details={
+                "premium_percent_remaining": status_obj.premium_percent_remaining,
+                "limit_reached": status_obj.limit_reached,
+            },
+        )
+
+    if provider == "zai":
+        status_obj = zai_quota.check_zai_quota()
+        block_reason = zai_quota.zai_quota_block_reason()
+        windows = {
+            "api_calls": status_obj.api_calls,
+            "tokens": status_obj.tokens,
+        }
+        selected_name, selected_window = _pick_named_window(windows)
+        status = "error" if status_obj.error else "blocked" if block_reason else "ok"
+        used = None
+        if selected_window.limit is not None and selected_window.remaining is not None:
+            used = selected_window.limit - selected_window.remaining
+        return usage_window_record(
+            provider=provider,
+            status=status,
+            used=None if status_obj.error else used,
+            limit=None if status_obj.error else selected_window.limit,
+            remaining=None if status_obj.error else selected_window.remaining,
+            unit=selected_name,
+            reset_window=f"{selected_window.window_hours}h" if selected_window.window_hours else selected_name,
+            reset_at=None,
+            block_reason=block_reason,
+            error=status_obj.error,
+            details={
+                "limit_reached": status_obj.limit_reached,
+                "max_used_percent": status_obj.max_used_percent,
+                "windows": {
+                    "api_calls": asdict(status_obj.api_calls),
+                    "tokens": asdict(status_obj.tokens),
+                },
+            },
+        )
+
+    raise UnknownProviderError(usage_provider_error_message(provider))
+
+
+def format_usage_line(record: dict[str, Any]) -> str:
+    fields = [
+        record["provider"] + ":",
+        f"status={record['status']}",
+        f"used={record['used'] if record['used'] is not None else 'unknown'}",
+        f"limit={record['limit'] if record['limit'] is not None else 'unknown'}",
+        f"remaining={record['remaining'] if record['remaining'] is not None else 'unknown'}",
+        f"unit={record['unit'] or 'unknown'}",
+        f"reset_window={record['reset_window'] or 'unknown'}",
+        f"reset_at={record['reset_at'] or 'unknown'}",
+    ]
+    if record["block_reason"]:
+        fields.append(f"block_reason={record['block_reason']}")
+    if record["error"]:
+        fields.append(f"error={record['error']}")
+    return " ".join(fields)
+
+
+def selected_providers(provider: str | None) -> list[str]:
+    providers = [provider] if provider is not None else list(SUPPORTED_USAGE_PROVIDERS)
+    for name in providers:
+        if name not in USAGE_PROVIDER_CHOICES:
+            raise UnknownProviderError(usage_provider_error_message(name))
+    return providers
+
+
+def collect_usage(provider: str | None = None) -> list[dict[str, Any]]:
+    return [normalize_usage_provider(name) for name in selected_providers(provider)]

quse/zai_quota.py

@@ -0,0 +1,124 @@
+"""Proactive Z.AI quota checking via goz CLI."""
+
+from dataclasses import dataclass, field
+import json
+import logging
+import subprocess
+import time
+
+from quse._shared import UsageWindow
+
+logger = logging.getLogger(__name__)
+
+_CACHE_TTL_SECONDS = 60
+
+
+@dataclass(slots=True)
+class ZaiQuotaWindow:
+    used_percent: float = 0.0
+    window_hours: int | None = None
+    remaining: int | None = None
+    limit: int | None = None
+
+    def __post_init__(self) -> None:
+        self.used_percent = float(self.used_percent)
+
+    @property
+    def percent_remaining(self) -> float:
+        return max(0.0, 100.0 - self.used_percent)
+
+
+@dataclass(slots=True)
+class ZaiQuotaStatus:
+    api_calls: ZaiQuotaWindow = field(default_factory=ZaiQuotaWindow)
+    tokens: ZaiQuotaWindow = field(default_factory=ZaiQuotaWindow)
+    limit_reached: bool = False
+    checked_at: float = 0.0
+    error: str | None = None
+
+    @property
+    def max_used_percent(self) -> float:
+        return max(self.api_calls.used_percent, self.tokens.used_percent)
+
+    @property
+    def short_term(self) -> UsageWindow:
+        return UsageWindow(percent_remaining=self.tokens.percent_remaining)
+
+    @property
+    def long_term(self) -> UsageWindow:
+        return UsageWindow(percent_remaining=100.0)
+
+
+_cached_status: ZaiQuotaStatus | None = None
+
+
+def _fetch_usage(*, timeout: float = 10.0) -> ZaiQuotaStatus:
+    try:
+        result = subprocess.run(
+            ["goz", "usage", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if result.returncode != 0:
+            return ZaiQuotaStatus(checked_at=time.monotonic(), error=f"goz exit {result.returncode}")
+        data = json.loads(result.stdout)
+    except FileNotFoundError:
+        return ZaiQuotaStatus(checked_at=time.monotonic(), error="goz not on PATH")
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError) as exc:
+        logger.warning("zai quota check failed (fail-open): %s", exc)
+        return ZaiQuotaStatus(checked_at=time.monotonic(), error=str(exc))
+
+    api_calls = ZaiQuotaWindow()
+    tokens = ZaiQuotaWindow()
+
+    limits = data.get("limits")
+    if not isinstance(limits, list):
+        limits = []
+    for limit in limits:
+        if not isinstance(limit, dict):
+            continue
+        window = ZaiQuotaWindow(
+            used_percent=limit.get("percentage", 0),
+            window_hours=limit.get("window_hours") if isinstance(limit.get("window_hours"), int) else None,
+            remaining=limit.get("remaining") if isinstance(limit.get("remaining"), int) else None,
+            limit=limit.get("limit") if isinstance(limit.get("limit"), int) else None,
+        )
+        if limit.get("type") == "TIME_LIMIT":
+            api_calls = window
+        if limit.get("type") == "TOKENS_LIMIT":
+            tokens = window
+
+    return ZaiQuotaStatus(api_calls=api_calls, tokens=tokens, checked_at=time.monotonic())
+
+
+def check_zai_quota(
+    *,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> ZaiQuotaStatus:
+    """Check Z.AI quota via goz CLI. Returns cached result within TTL. Fails open."""
+    global _cached_status
+    if _cached_status is not None and time.monotonic() - _cached_status.checked_at < cache_ttl:
+        return _cached_status
+
+    fetcher = _fetch if callable(_fetch) else _fetch_usage
+    _cached_status = fetcher()
+    return _cached_status
+
+
+def zai_quota_block_reason(
+    *,
+    cache_ttl: float = _CACHE_TTL_SECONDS,
+    _fetch: object = None,
+) -> str | None:
+    """Return a blocking reason if Z.AI quota is reached, or None."""
+    status = check_zai_quota(cache_ttl=cache_ttl, _fetch=_fetch)
+    if status.error:
+        return None  # fail-open
+    return None
+
+
+def reset_cache() -> None:
+    global _cached_status
+    _cached_status = None

quse-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+quse/__init__.py,sha256=De4Gv1VWfhpJ2DHdFCadlYDlDmPGc2DMKx7qL--f-1s,219
+quse/_shared.py,sha256=-H4x7niCx0VoP-aCFDgIlNREgjBHEZx5RJryZ90GpQU,2626
+quse/claude_quota.py,sha256=MP4pqlQBgeyt4CGKlyV2xRU849nUdsixjlCT13-Ls5g,5563
+quse/cli.py,sha256=F7zxcQf7MkhI_JLXay-lMKJ1VKt8anBthDVb39aGz28,1387
+quse/codex_quota.py,sha256=VnRQwVMREsYJwJs5p-STRDrstsA7VxcyNRFWNyorx1g,5695
+quse/copilot_quota.py,sha256=D4V78_fyPT8ufROk5i-2TPkzSepaJqaWyRLP-1psh7U,3969
+quse/usage.py,sha256=2ZRh2TmGbpd9UNQE95kywEVyP9CjakSGEjucYCpC5RQ,8464
+quse/zai_quota.py,sha256=gpOXcbvTtJmYOpY4z6vhKZC4wJFW8lnCrcGb1sXv0MA,3829
+quse-0.0.1.dist-info/METADATA,sha256=pB-aBne2aBT8oFFdpFmV_GtkYv1-yrqGMdIweKz1stM,719
+quse-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+quse-0.0.1.dist-info/entry_points.txt,sha256=C5lr1bV7dSOyw7Mx09Bs3TiT8hWjoJ4zy0RENoQoX9g,39
+quse-0.0.1.dist-info/RECORD,,

quse-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

quse-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quse = quse.cli:main