pocketshell 0.3.29__tar.gz → 0.3.30__tar.gz

{pocketshell-0.3.29 → pocketshell-0.3.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.3.29
+Version: 0.3.30
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues

{pocketshell-0.3.29 → pocketshell-0.3.30}/pyproject.toml

@@ -8,7 +8,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
 # runs that check before publishing to PyPI. See
 # tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.3.29"
+version = "0.3.30"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

{pocketshell-0.3.29 → pocketshell-0.3.30}/src/pocketshell/usage.py

@@ -61,6 +61,17 @@ import click
 
 _CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage"
 _CODEX_AUTH_PATH = Path.home() / ".codex" / "auth.json"
+_CODEX_COMPATIBLE_PROVIDERS = {
+    "codex",
+    "openai",
+    "openai-codex",
+    "openai_codex",
+    "chatgpt",
+}
+_CLAUDE_USAGE_AUTH_SETUP_MESSAGE = (
+    "Claude usage authentication needs setup on this host. "
+    "Open Claude Code on the host and complete sign-in, then refresh usage."
+)
 
 
 def _resolve_quse_binary() -> Optional[str]:
@@ -151,16 +162,78 @@ def _percent_remaining_from_used(value: Any) -> Optional[float]:
     return round(max(0.0, min(100.0, 100.0 - used)), 2)
 
 
-def _window_from_detail(detail: Any) -> Optional[dict[str, Any]]:
+def _reset_after_seconds_to_iso(
+    value: Any,
+    *,
+    now: Optional[datetime] = None,
+) -> Optional[str]:
+    if value is None:
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return None
+    if seconds < 0:
+        return None
+    base = now or datetime.now(timezone.utc)
+    if base.tzinfo is None:
+        base = base.replace(tzinfo=timezone.utc)
+    reset_at = base.astimezone(timezone.utc).timestamp() + seconds
+    try:
+        parsed = datetime.fromtimestamp(reset_at, tz=timezone.utc)
+    except (OverflowError, OSError, ValueError):
+        return None
+    return parsed.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _window_label_from_seconds(value: Any) -> Optional[str]:
+    try:
+        seconds = int(float(value))
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if seconds <= 0:
+        return None
+    units = (
+        (24 * 60 * 60, "d"),
+        (60 * 60, "h"),
+        (60, "m"),
+    )
+    for unit_seconds, suffix in units:
+        if seconds >= unit_seconds and seconds % unit_seconds == 0:
+            return f"{seconds // unit_seconds}{suffix}"
+    return f"{seconds}s"
+
+
+def _window_label_from_detail(detail: dict[str, Any]) -> Optional[str]:
+    label = _window_label_from_seconds(detail.get("limit_window_seconds"))
+    if label is not None:
+        return label
+    try:
+        minutes = float(detail.get("window_minutes"))
+    except (TypeError, ValueError):
+        return None
+    return _window_label_from_seconds(minutes * 60)
+
+
+def _window_from_detail(
+    detail: Any,
+    *,
+    now: Optional[datetime] = None,
+) -> Optional[dict[str, Any]]:
     if not isinstance(detail, dict):
         return None
     percent_remaining = _percent_remaining_from_used(detail.get("used_percent"))
-    reset_at = _normalize_reset_at(detail.get("reset_at"))
-    if percent_remaining is None and reset_at is None:
+    reset_at = _normalize_reset_at(detail.get("reset_at")) or _reset_after_seconds_to_iso(
+        detail.get("reset_after_seconds"),
+        now=now,
+    )
+    window = _window_label_from_detail(detail)
+    if percent_remaining is None and reset_at is None and window is None:
         return None
     return {
         "percent_remaining": percent_remaining,
         "reset_at": reset_at,
+        "window": window,
     }
 
 
@@ -169,6 +242,7 @@ def _merge_window(
     detail: Any,
     *,
     prefer_detail_percent: bool = False,
+    now: Optional[datetime] = None,
 ) -> Any:
     if not isinstance(current, dict):
         if not isinstance(detail, dict):
@@ -177,14 +251,21 @@ def _merge_window(
     else:
         current = dict(current)
 
-    detail_window = _window_from_detail(detail)
+    detail_window = _window_from_detail(detail, now=now)
     if detail_window is not None:
         if prefer_detail_percent or current.get("percent_remaining") is None:
             current["percent_remaining"] = detail_window.get("percent_remaining")
         if current.get("reset_at") is None:
             current["reset_at"] = detail_window.get("reset_at")
+        if current.get("window") is None and detail_window.get("window") is not None:
+            current["window"] = detail_window.get("window")
 
-    current["reset_at"] = _normalize_reset_at(current.get("reset_at"))
+    reset_after_seconds = current.get("reset_after_seconds")
+    current["reset_at"] = _normalize_reset_at(current.get("reset_at")) or _reset_after_seconds_to_iso(
+        reset_after_seconds,
+        now=now,
+    )
+    current.pop("reset_after_seconds", None)
     return current
 
 
@@ -195,15 +276,19 @@ def _actionable_error(provider: str, error: Any) -> Optional[str]:
     if not text:
         return None
     lower = text.lower()
+    if provider == "claude" and (
+        "claude " + "/login" in lower
+        or "run `claude" in lower
+        or "run claude" in lower
+        or "authentication " + "failed" in lower
+    ):
+        return _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
     if provider == "claude" and (
         "http error 401" in lower
         or "unauthorized" in lower
         or lower in {"no-credentials", "no credentials"}
     ):
-        return (
-            "Claude Code authentication failed on this host. "
-            "Run `claude /login` in the host shell, then refresh usage."
-        )
+        return _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
     if provider == "codex" and lower in {"no auth token", "no-auth-token", "no credentials"}:
         return (
             "Codex authentication is missing on this host. "
@@ -261,14 +346,30 @@ def _codex_needs_source_patch(record: dict[str, Any], detail_windows: dict[str,
     ):
         top_level = record.get(top_level_key)
         detail = detail_windows.get(detail_key)
-        top_level_reset = top_level.get("reset_at") if isinstance(top_level, dict) else None
-        detail_reset = detail.get("reset_at") if isinstance(detail, dict) else None
+        top_level_reset = None
+        if isinstance(top_level, dict):
+            top_level_reset = top_level.get("reset_at")
+            if top_level_reset is None:
+                top_level_reset = top_level.get("reset_after_seconds")
+        detail_reset = None
+        if isinstance(detail, dict):
+            detail_reset = detail.get("reset_at")
+            if detail_reset is None:
+                detail_reset = detail.get("reset_after_seconds")
         if top_level_reset is None and detail_reset is None:
             return True
     return False
 
 
-def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
+def _is_codex_compatible_provider(provider: str) -> bool:
+    return provider.replace(" ", "_").lower() in _CODEX_COMPATIBLE_PROVIDERS
+
+
+def normalize_usage_record(
+    record: dict[str, Any],
+    *,
+    now: Optional[datetime] = None,
+) -> dict[str, Any]:
     """Normalize a provider record emitted by ``quse --json``.
 
     PocketShell owns the app-facing schema even when it delegates provider
@@ -282,7 +383,7 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
     if not isinstance(detail_windows, dict):
         detail_windows = {}
 
-    if provider == "codex":
+    if _is_codex_compatible_provider(provider):
         # Codex's ChatGPT usage response exposes the real primary/secondary
         # windows under details. Older quse versions hard-code short_term to
         # 100% and lose epoch reset timestamps, which regressed issue #501.
@@ -297,6 +398,7 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
             normalized.get("short_term"),
             detail_windows.get("primary_window"),
             prefer_detail_percent=True,
+            now=now,
         )
         if short_term is not None:
             normalized["short_term"] = short_term
@@ -304,6 +406,7 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
             normalized.get("long_term"),
             detail_windows.get("secondary_window"),
             prefer_detail_percent=True,
+            now=now,
         )
         if long_term is not None:
             normalized["long_term"] = long_term
@@ -311,20 +414,22 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
         short_term = _merge_window(
             normalized.get("short_term"),
             detail_windows.get("five_hour"),
+            now=now,
         )
         if short_term is not None:
             normalized["short_term"] = short_term
         long_term = _merge_window(
             normalized.get("long_term"),
             detail_windows.get("seven_day"),
+            now=now,
         )
         if long_term is not None:
             normalized["long_term"] = long_term
     else:
         if isinstance(normalized.get("short_term"), dict):
-            normalized["short_term"] = _merge_window(normalized.get("short_term"), None)
+            normalized["short_term"] = _merge_window(normalized.get("short_term"), None, now=now)
         if isinstance(normalized.get("long_term"), dict):
-            normalized["long_term"] = _merge_window(normalized.get("long_term"), None)
+            normalized["long_term"] = _merge_window(normalized.get("long_term"), None, now=now)
 
     actionable = _actionable_error(provider, normalized.get("error"))
     if actionable != normalized.get("error"):
@@ -332,7 +437,11 @@ def normalize_usage_record(record: dict[str, Any]) -> dict[str, Any]:
     return normalized
 
 
-def normalize_usage_stdout(stdout: str) -> str:
+def normalize_usage_stdout(
+    stdout: str,
+    *,
+    now: Optional[datetime] = None,
+) -> str:
     """Normalize NDJSON stdout from ``quse --json`` for app consumption."""
     if not stdout.strip():
         return stdout
@@ -348,7 +457,7 @@ def normalize_usage_stdout(stdout: str) -> str:
             return stdout
         if not isinstance(parsed, dict):
             return stdout
-        normalized = normalize_usage_record(parsed)
+        normalized = normalize_usage_record(parsed, now=now)
         changed = changed or normalized != parsed
         lines.append(json.dumps(normalized, sort_keys=True))
     suffix = "\n" if stdout.endswith("\n") else ""

{pocketshell-0.3.29 → pocketshell-0.3.30}/tests/test_usage.py

@@ -20,13 +20,19 @@ from __future__ import annotations
 
 import json
 import subprocess
+from datetime import datetime, timezone
 from typing import Sequence
 from unittest.mock import patch
 
 from click.testing import CliRunner
 
 from pocketshell.cli import cli, main
-from pocketshell.usage import usage_command
+from pocketshell.usage import (
+    _CLAUDE_USAGE_AUTH_SETUP_MESSAGE,
+    _actionable_error,
+    normalize_usage_record,
+    usage_command,
+)
 
 
 def _fake_completed(
@@ -112,10 +118,12 @@ def test_usage_json_normalizes_codex_detail_windows_and_epoch_resets() -> None:
                         "windows": {
                             "primary_window": {
                                 "used_percent": 12,
+                                "limit_window_seconds": 18000,
                                 "reset_at": 1780828285,
                             },
                             "secondary_window": {
                                 "used_percent": 31,
+                                "limit_window_seconds": 604800,
                                 "reset_at": 1781137638,
                             },
                         },
@@ -148,15 +156,29 @@ def test_usage_json_normalizes_codex_detail_windows_and_epoch_resets() -> None:
     assert codex["short_term"] == {
         "percent_remaining": 88.0,
         "reset_at": "2026-06-07T10:31:25Z",
+        "window": "5h",
     }
     assert codex["long_term"] == {
         "percent_remaining": 69.0,
         "reset_at": "2026-06-11T00:27:18Z",
+        "window": "7d",
     }
-    assert "claude /login" in lines[1]["error"]
+    assert lines[1]["error"] == _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
+    assert "claude " + "/login" not in lines[1]["error"]
+    assert "authentication " + "failed" not in lines[1]["error"].lower()
     assert "HTTP Error 401" not in lines[1]["error"]
 
 
+def test_claude_stale_auth_telemetry_error_is_usage_unavailable() -> None:
+    stale_error = (
+        "Claude Code authentication "
+        + "failed on this host. Run `claude "
+        + "/login` in the host shell."
+    )
+
+    assert _actionable_error("claude", stale_error) == _CLAUDE_USAGE_AUTH_SETUP_MESSAGE
+
+
 def test_usage_json_patches_codex_resets_from_source_when_quse_dropped_them() -> None:
     raw = json.dumps(
         {
@@ -182,8 +204,16 @@ def test_usage_json_patches_codex_resets_from_source_when_quse_dropped_them() ->
     ), patch(
         "pocketshell.usage._fetch_codex_detail_windows",
         return_value={
-            "primary_window": {"used_percent": 13, "reset_at": 1780828285},
-            "secondary_window": {"used_percent": 31, "reset_at": 1781137638},
+            "primary_window": {
+                "used_percent": 13,
+                "limit_window_seconds": 18000,
+                "reset_at": 1780828285,
+            },
+            "secondary_window": {
+                "used_percent": 31,
+                "limit_window_seconds": 604800,
+                "reset_at": 1781137638,
+            },
         },
     ):
         result = runner.invoke(usage_command, ["--json"])
@@ -193,10 +223,124 @@ def test_usage_json_patches_codex_resets_from_source_when_quse_dropped_them() ->
     assert codex["short_term"] == {
         "percent_remaining": 87.0,
         "reset_at": "2026-06-07T10:31:25Z",
+        "window": "5h",
     }
     assert codex["long_term"] == {
         "percent_remaining": 69.0,
         "reset_at": "2026-06-11T00:27:18Z",
+        "window": "7d",
+    }
+
+
+def test_usage_json_normalizes_openai_compatible_detail_windows() -> None:
+    raw = json.dumps(
+        {
+            "provider": "openai",
+            "status": "ok",
+            "short_term": {"percent_remaining": 100.0, "reset_at": None},
+            "long_term": {"percent_remaining": 35.0, "reset_at": None},
+            "block_reason": None,
+            "error": None,
+            "details": {
+                "windows": {
+                    "primary_window": {
+                        "used_percent": 22,
+                        "limit_window_seconds": 18000,
+                        "reset_at": "2026-06-08T02:19:59Z",
+                    },
+                    "secondary_window": {
+                        "used_percent": 65,
+                        "limit_window_seconds": 604800,
+                        "reset_at": "2026-06-11T00:27:17Z",
+                    },
+                },
+            },
+        },
+    )
+    runner = CliRunner()
+    with patch("pocketshell.usage._resolve_quse_binary", return_value="/fake/quse"), patch(
+        "pocketshell.usage.subprocess.run",
+        return_value=_fake_completed(stdout=raw + "\n"),
+    ):
+        result = runner.invoke(usage_command, ["--json"])
+
+    assert result.exit_code == 0, result.output
+    record = json.loads(result.output)
+    assert record["short_term"] == {
+        "percent_remaining": 78.0,
+        "reset_at": "2026-06-08T02:19:59Z",
+        "window": "5h",
+    }
+    assert record["long_term"] == {
+        "percent_remaining": 35.0,
+        "reset_at": "2026-06-11T00:27:17Z",
+        "window": "7d",
+    }
+
+
+def test_normalize_usage_record_preserves_codex_reset_after_seconds() -> None:
+    record = normalize_usage_record(
+        {
+            "provider": "codex",
+            "status": "ok",
+            "short_term": {"percent_remaining": 35.0, "reset_at": None},
+            "long_term": {"percent_remaining": 69.0, "reset_at": None},
+            "block_reason": None,
+            "error": None,
+            "details": {
+                "windows": {
+                    "primary_window": {
+                        "used_percent": 65,
+                        "window_minutes": 300,
+                        "reset_after_seconds": 3600,
+                    },
+                    "secondary_window": {
+                        "used_percent": 31,
+                        "limit_window_seconds": 604800,
+                        "reset_after_seconds": "604800",
+                    },
+                },
+            },
+        },
+        now=datetime(2026, 6, 8, 10, 0, tzinfo=timezone.utc),
+    )
+
+    assert record["short_term"] == {
+        "percent_remaining": 35.0,
+        "reset_at": "2026-06-08T11:00:00Z",
+        "window": "5h",
+    }
+    assert record["long_term"] == {
+        "percent_remaining": 69.0,
+        "reset_at": "2026-06-15T10:00:00Z",
+        "window": "7d",
+    }
+
+
+def test_normalize_usage_record_converts_top_level_reset_after_seconds() -> None:
+    with patch("pocketshell.usage._fetch_codex_detail_windows", return_value=None):
+        record = normalize_usage_record(
+            {
+                "provider": "codex",
+                "status": "ok",
+                "short_term": {
+                    "percent_remaining": 35.0,
+                    "reset_at": None,
+                    "reset_after_seconds": 3600,
+                    "window": "5h",
+                },
+                "long_term": None,
+                "block_reason": None,
+                "error": None,
+                "details": {},
+            },
+            now=datetime(2026, 6, 8, 10, 0, tzinfo=timezone.utc),
+        )
+
+    assert record["short_term"] == {
+        "percent_remaining": 35.0,
+        "reset_at": "2026-06-08T11:00:00Z",
+        "window": "5h",
     }