usage-cli 0.29.32__py3-none-any.whl

analyzer/subscription.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Read the locally-stored subscription plan + start date for each agent.
+
+Everything here is read-only and stays on disk — we only pull the plan name and
+the subscription start date out of the OAuth account files that Claude Code and
+Codex already keep. Tokens, emails and account IDs are never read or returned.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from pathlib import Path
+from typing import Any
+
+from codex_paths import codex_home
+
+CLAUDE_CONFIG = Path.home() / ".claude.json"
+CODEX_AUTH = codex_home() / "auth.json"
+
+_CLAUDE_PLAN_NAMES = {
+    "claude_pro": "Claude Pro",
+    "claude_max": "Claude Max",
+    "claude_team": "Claude Team",
+    "claude_enterprise": "Claude Enterprise",
+}
+
+
+def _decode_jwt_payload(token: str) -> dict[str, Any]:
+    if not isinstance(token, str):
+        return {}
+    parts = token.split(".")
+    if len(parts) < 2:
+        return {}
+    payload = parts[1]
+    payload += "=" * (-len(payload) % 4)
+    try:
+        claims = json.loads(base64.urlsafe_b64decode(payload))
+        if not isinstance(claims, dict):
+            return {}
+        return claims
+    except (binascii.Error, ValueError):
+        return {}
+
+
+def _load_claude_subscription() -> dict[str, str | None] | None:
+    try:
+        data = json.loads(CLAUDE_CONFIG.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    account = data.get("oauthAccount")
+    if not isinstance(account, dict):
+        account = {}
+    org_type = account.get("organizationType")
+    since = account.get("subscriptionCreatedAt")
+    if not isinstance(org_type, str):
+        org_type = None
+    if not isinstance(since, str):
+        since = None
+    if not org_type and not since:
+        return None
+    plan = _CLAUDE_PLAN_NAMES.get(org_type or "")
+    if not plan:
+        plan = (org_type or "Claude").replace("claude_", "Claude ").replace("_", " ").title()
+    return {"agent": "Claude Code", "plan": plan, "since": since[:10] if since else None}
+
+
+def _load_codex_subscription() -> dict[str, str | None] | None:
+    try:
+        data = json.loads(CODEX_AUTH.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    tokens = data.get("tokens")
+    if not isinstance(tokens, dict):
+        tokens = {}
+    claims = _decode_jwt_payload(tokens.get("id_token", ""))
+    auth = claims.get("https://api.openai.com/auth")
+    if not isinstance(auth, dict):
+        auth = {}
+    plan_type = auth.get("chatgpt_plan_type")
+    since = auth.get("chatgpt_subscription_active_start")
+    if not isinstance(plan_type, str):
+        plan_type = None
+    if not isinstance(since, str):
+        since = None
+    if not plan_type and not since:
+        return None
+    plan = f"ChatGPT {plan_type.title()}" if plan_type else "ChatGPT"
+    return {"agent": "Codex", "plan": plan, "since": since[:10] if since else None}
+
+
+def load_subscriptions() -> list[dict[str, str | None]]:
+    """Return ``[{agent, plan, since}]`` for whichever agents we can detect."""
+    subs: list[dict[str, str | None]] = []
+    for loader in (_load_claude_subscription, _load_codex_subscription):
+        sub = loader()
+        if sub:
+            subs.append(sub)
+    return subs

burn_rate.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+
+ROLLING_WINDOW_SECONDS = 60 * 60
+FORECAST_WINDOW_SECONDS = 10 * 60
+RESET_DROP_PERCENT = 5.0
+MIN_FORECAST_SAMPLES = 5
+MIN_FORECAST_SPAN_SECONDS = 5 * 60
+WARNING_PERCENT_FLOOR = 50.0
+
+
+@dataclass(slots=True)
+class BurnSample:
+    timestamp: float
+    percent: float
+
+
+class BurnRateTracker:
+    def __init__(self) -> None:
+        self._samples: deque[BurnSample] = deque()
+
+    def record(self, now: float, percent: float) -> None:
+        sample = BurnSample(timestamp=float(now), percent=float(percent))
+        previous = self._samples[-1] if self._samples else None
+        if previous is not None and (previous.percent - sample.percent) > RESET_DROP_PERCENT:
+            self._samples.clear()
+        self._samples.append(sample)
+        self._prune(now=sample.timestamp)
+
+    def forecast_seconds(
+        self,
+        window_seconds: float | None = None,
+        min_span_seconds: float | None = None,
+    ) -> float | None:
+        if len(self._samples) < 2:
+            return None
+
+        latest = self._samples[-1]
+        window = window_seconds if window_seconds is not None else FORECAST_WINDOW_SECONDS
+        cutoff = latest.timestamp - window
+        selected = [sample for sample in self._samples if sample.timestamp >= cutoff]
+        if len(selected) < MIN_FORECAST_SAMPLES:
+            return None
+
+        first = selected[0]
+        elapsed = latest.timestamp - first.timestamp
+        span_threshold = (
+            min_span_seconds if min_span_seconds is not None else MIN_FORECAST_SPAN_SECONDS
+        )
+        if elapsed < span_threshold:
+            return None
+        if elapsed <= 0:
+            return None
+
+        slope_per_second = (latest.percent - first.percent) / elapsed
+        if slope_per_second <= 0:
+            return None
+
+        remaining_percent = 100.0 - latest.percent
+        if remaining_percent <= 0:
+            return 0.0
+        return remaining_percent / slope_per_second
+
+    def _prune(self, now: float) -> None:
+        cutoff = now - ROLLING_WINDOW_SECONDS
+        while self._samples and self._samples[0].timestamp < cutoff:
+            self._samples.popleft()

cache_quarantine.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Best-effort quarantine for corrupt disk cache files."""
+
+from __future__ import annotations
+
+import errno
+import logging
+import os
+import shutil
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+QUARANTINE_DIR = Path.home() / ".usage" / "quarantine"
+_MAX_FILE_SIZE = 5 * 1024 * 1024
+_MAX_BACKUPS = 10
+
+
+def quarantine(path: Path, reason: str) -> None:
+    """Best-effort move of a corrupt cache file into the quarantine directory."""
+    try:
+        if path.stat().st_size > _MAX_FILE_SIZE:
+            return
+
+        quarantine_dir = QUARANTINE_DIR
+        quarantine_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        timestamp_ms = time.time_ns() // 1_000_000
+        backup_path = quarantine_dir / f"{path.name}.{timestamp_ms}.bak"
+        try:
+            os.replace(path, backup_path)
+        except OSError as exc:
+            if exc.errno != errno.EXDEV:
+                raise
+            shutil.copy2(path, backup_path)
+            path.unlink()
+
+        backups = sorted(
+            quarantine_dir.glob("*.bak"), key=lambda candidate: candidate.stat().st_mtime
+        )
+        for backup in backups[:-_MAX_BACKUPS]:
+            backup.unlink()
+    except Exception as exc:
+        if os.environ.get("USAGE_DEBUG") == "1":
+            logger.warning("failed to quarantine cache file %s (%s): %s", path, reason, exc)

codex_disk_cache.py

@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Sharded disk persistence for codex_loader's parse caches."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any
+
+from codex_events import _SessionFileInfo, _TokenUsage
+from disk_cache_common import (
+    _SHARD_COUNT,
+    _cache_dir,
+    _deserialize_usage_entry,
+    _encoded_payload,
+    _load_payload,
+    _remove_legacy_cache,
+    _serialize_usage_entry,
+    _shard_index,
+    _shard_path,
+    _write_if_changed,
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["_shard_index", "_shard_path", "flush_caches", "seed_caches"]
+
+_JsonlCache = OrderedDict[Path, Any]
+_FileInfoCache = OrderedDict[Path, tuple[float, int, _SessionFileInfo]]
+
+
+def _serialize_token_usage(value: _TokenUsage | None) -> dict[str, int] | None:
+    if value is None:
+        return None
+    return {
+        "input_tokens": value.input_tokens,
+        "output_tokens": value.output_tokens,
+        "cache_read_tokens": value.cache_read_tokens,
+    }
+
+
+def _deserialize_token_usage(value: Any) -> _TokenUsage | None:
+    if not isinstance(value, dict):
+        return None
+    try:
+        return _TokenUsage(
+            input_tokens=int(value["input_tokens"]),
+            output_tokens=int(value["output_tokens"]),
+            cache_read_tokens=int(value["cache_read_tokens"]),
+        )
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+def _sqlite_log_path(cache_path: Path) -> Path:
+    return _cache_dir(cache_path) / "sqlite-log.json"
+
+
+def seed_caches(
+    cache_path: Path,
+    schema_version: int,
+    maxsize: int,
+    jsonl_cache: _JsonlCache,
+    file_info_cache: _FileInfoCache,
+    sqlite_log_cache: Any,
+) -> None:
+    """Seed valid shards, skipping only corrupt or stale shards."""
+    from codex_loader import _JsonlCacheEntry, _JsonlParseState
+
+    _remove_legacy_cache(cache_path)
+    sqlite_payload = _load_payload(_sqlite_log_path(cache_path), schema_version)
+    if sqlite_payload is not None:
+        try:
+            watermark = sqlite_payload["watermark"]
+            entries_data = sqlite_payload["entries"]
+            if (
+                isinstance(watermark, list)
+                and len(watermark) == 3
+                and isinstance(entries_data, list)
+            ):
+                sqlite_log_cache.watermark = tuple(int(item) for item in watermark)
+                sqlite_log_cache.entries = [
+                    _deserialize_usage_entry(entry) for entry in entries_data
+                ]
+        except (KeyError, TypeError, ValueError):
+            pass
+
+    for index in range(_SHARD_COUNT):
+        payload = _load_payload(_shard_path(cache_path, index), schema_version)
+        if payload is None:
+            continue
+        files = payload.get("files")
+        if not isinstance(files, dict):
+            continue
+        for path_str, file_data in files.items():
+            if not isinstance(file_data, dict):
+                continue
+            try:
+                path = Path(path_str)
+                mtime = file_data["mtime"]
+                size = file_data["size"]
+                session_id = file_data["session_id"]
+                forked_from_id = file_data["forked_from_id"]
+                entries_data = file_data["entries"]
+                confirmed_offset = int(file_data.get("confirmed_offset", 0))
+                digest_hex = file_data.get("confirmed_prefix_digest", "")
+                parse_state_data = file_data.get("parse_state", {})
+                if not isinstance(parse_state_data, dict):
+                    parse_state_data = {}
+
+                if len(file_info_cache) >= maxsize:
+                    file_info_cache.popitem(last=False)
+                file_info_cache[path] = (
+                    mtime,
+                    size,
+                    _SessionFileInfo(session_id=session_id, forked_from_id=forked_from_id),
+                )
+                if entries_data is None:
+                    continue
+                if not isinstance(entries_data, list):
+                    continue
+                if (
+                    "confirmed_offset" not in file_data
+                    or "confirmed_prefix_digest" not in file_data
+                    or "parse_state" not in file_data
+                ):
+                    continue
+                state = _JsonlParseState(
+                    session_timestamp=str(parse_state_data.get("session_timestamp", "")),
+                    project=str(parse_state_data.get("project", "unknown")),
+                    session_model=str(parse_state_data.get("session_model", "unknown")),
+                    previous_usage=_deserialize_token_usage(parse_state_data.get("previous_usage")),
+                    token_count_index=int(parse_state_data.get("token_count_index", 0)),
+                )
+                if len(jsonl_cache) >= maxsize:
+                    jsonl_cache.popitem(last=False)
+                jsonl_cache[path] = _JsonlCacheEntry(
+                    mtime=mtime,
+                    size=size,
+                    replay_cache_key=None,
+                    entries=[_deserialize_usage_entry(entry) for entry in entries_data],
+                    confirmed_offset=confirmed_offset,
+                    confirmed_prefix_digest=bytes.fromhex(digest_hex)
+                    if isinstance(digest_hex, str)
+                    else b"",
+                    state=state,
+                )
+            except (KeyError, TypeError, ValueError):
+                continue
+
+
+def flush_caches(
+    cache_path: Path,
+    schema_version: int,
+    jsonl_cache: _JsonlCache,
+    file_info_cache: _FileInfoCache,
+    sqlite_log_cache: Any,
+) -> None:
+    """Atomically replace only shards whose serialized contents changed."""
+    try:
+        _remove_legacy_cache(cache_path)
+        shards: list[dict[str, Any]] = [{} for _ in range(_SHARD_COUNT)]
+        for path, entry in jsonl_cache.items():
+            info = file_info_cache.get(path)
+            if entry.replay_cache_key is not None:
+                if info is None:
+                    continue
+                entries_data = None
+                session_id = info[2].session_id
+                forked_from_id = info[2].forked_from_id
+            else:
+                entries_data = [_serialize_usage_entry(item) for item in entry.entries]
+                if entry.entries:
+                    session_id = entry.entries[0].session_id
+                    forked_from_id = ""
+                elif info is not None:
+                    session_id = info[2].session_id
+                    forked_from_id = info[2].forked_from_id
+                else:
+                    continue
+            shards[_shard_index(path)][str(path)] = {
+                "mtime": entry.mtime,
+                "size": entry.size,
+                "session_id": session_id,
+                "forked_from_id": forked_from_id,
+                "entries": entries_data,
+                "confirmed_offset": entry.confirmed_offset,
+                "confirmed_prefix_digest": entry.confirmed_prefix_digest.hex(),
+                "parse_state": {
+                    "session_timestamp": entry.state.session_timestamp,
+                    "project": entry.state.project,
+                    "session_model": entry.state.session_model,
+                    "previous_usage": _serialize_token_usage(entry.state.previous_usage),
+                    "token_count_index": entry.state.token_count_index,
+                },
+            }
+
+        for index, files in enumerate(shards):
+            path = _shard_path(cache_path, index)
+            if files:
+                _write_if_changed(
+                    path,
+                    _encoded_payload({"schema_version": schema_version, "files": files}),
+                )
+            else:
+                path.unlink(missing_ok=True)
+
+        sqlite_payload = {
+            "schema_version": schema_version,
+            "watermark": list(sqlite_log_cache.watermark)
+            if sqlite_log_cache.watermark is not None
+            else None,
+            "entries": [
+                _serialize_usage_entry(entry) for entry in sqlite_log_cache.entries
+            ],
+        }
+        _write_if_changed(_sqlite_log_path(cache_path), _encoded_payload(sqlite_payload))
+    except Exception as exc:
+        if os.environ.get("USAGE_DEBUG") == "1":
+            logger.warning("failed to write codex jsonl cache %s: %s", cache_path, exc)

codex_events.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Stateless value parsing for Codex session logs.
+
+Leaf helpers shared by codex_loader's JSONL and sqlite readers: coercing raw
+JSON/log values into scalars, token-usage payloads and per-file metadata.
+Nothing here touches module state, the filesystem layout constants, or caches —
+those all stay in codex_loader so test monkeypatching keeps working.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class _ThreadMetadata:
+    model: str = "unknown"
+    cwd: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class _SessionFileInfo:
+    session_id: str = ""
+    forked_from_id: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class _TokenUsage:
+    input_tokens: int
+    output_tokens: int
+    cache_read_tokens: int
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens + self.cache_read_tokens
+
+    def delta(self, previous: _TokenUsage | None) -> _TokenUsage:
+        if previous is None:
+            return self
+        return _TokenUsage(
+            input_tokens=max(0, self.input_tokens - previous.input_tokens),
+            output_tokens=max(0, self.output_tokens - previous.output_tokens),
+            cache_read_tokens=max(0, self.cache_read_tokens - previous.cache_read_tokens),
+        )
+
+
+def _token_usage_from_payload(usage: dict[str, Any]) -> _TokenUsage:
+    cached = _as_int(usage.get("cached_input_tokens"))
+    input_tokens = max(0, _as_int(usage.get("input_tokens")) - cached)
+    output_tokens = _as_int(usage.get("output_tokens"))
+    return _TokenUsage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_read_tokens=cached,
+    )
+
+
+def _load_json_line(line: str) -> dict[str, Any] | None:
+    try:
+        data = json.loads(line)
+    except (json.JSONDecodeError, RecursionError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+_EVENT_VALUE_RE_CACHE: dict[str, re.Pattern[str]] = {}
+
+
+def _event_value(body: str, key: str) -> str:
+    pattern = _EVENT_VALUE_RE_CACHE.get(key)
+    if pattern is None:
+        pattern = re.compile(rf'(?:^|[\s{{]){re.escape(key)}=(?:"([^"]*)"|([^\s}}]+))')
+        _EVENT_VALUE_RE_CACHE[key] = pattern
+    match = pattern.search(body)
+    if match is None:
+        return ""
+    return match.group(1) if match.group(1) is not None else match.group(2)
+
+
+def _timestamp_from_log_ts(value: Any) -> datetime | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        timestamp = float(value)
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(timestamp):
+        return None
+    return datetime.fromtimestamp(timestamp, UTC)
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _session_model(payload: Any, fallback: str) -> str:
+    model = _as_str(_as_dict(payload).get("model"))
+    return model or fallback
+
+
+def _as_int(value: Any) -> int:
+    if isinstance(value, bool):
+        return 0
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return 0
+    if not math.isfinite(number):
+        return 0
+    return max(0, int(number))
+
+
+def _as_str(value: Any) -> str:
+    return value if isinstance(value, str) else ""
+
+
+def _as_optional_float(value: Any) -> float | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(number):
+        return None
+    return number