fix(429): humanize unix reset times; fail-fast hard usage limits

Author: elkaix

src/pythinker_code/soul/pythinkersoul.py

@@ -199,6 +199,25 @@ def classify_api_error(e: Exception) -> tuple[str, int | None]:
     return "other", None
 
 
+def _is_hard_usage_limit(exception: BaseException) -> bool:
+    """Whether a 429 is a subscription usage cap (resets in hours) rather than a
+    transient RPM/TPM burst (clears in seconds).
+
+    Hard caps — e.g. ChatGPT Codex ``usage_limit_reached`` — should NOT be retried:
+    the backoff just delays the inevitable failure. Detected from the parsed body
+    when present, else from the stringified message (the streaming 429 often
+    carries only the bare text)."""
+    body = getattr(exception, "body", None)
+    if isinstance(body, dict):
+        err = cast(dict[str, object], body).get("error")
+        if isinstance(err, dict):
+            err_type = cast(dict[str, object], err).get("type")
+            if str(err_type or "") == "usage_limit_reached":
+                return True
+    text = str(exception).lower()
+    return "usage_limit_reached" in text or "usage limit" in text
+
+
 type StepStopReason = Literal["no_tool_calls", "tool_rejected", "stuck"]
 
 
@@ -2087,7 +2106,14 @@ def _is_retryable_error(exception: BaseException) -> bool:
             return not bool(getattr(exception, "_pythinker_recovery_exhausted", False))
         if isinstance(exception, APIEmptyResponseError):
             return True
-        return isinstance(exception, APIStatusError) and exception.status_code in (
+        if not isinstance(exception, APIStatusError):
+            return False
+        if exception.status_code == 429 and _is_hard_usage_limit(exception):
+            # A subscription usage cap (e.g. ChatGPT Codex `usage_limit_reached`)
+            # resets in hours, not seconds — retrying with backoff only adds
+            # latency before the inevitable failure. Surface it immediately.
+            return False
+        return exception.status_code in (
             429,  # Too Many Requests
             500,  # Internal Server Error
             502,  # Bad Gateway

src/pythinker_code/ui/shell/__init__.py

@@ -510,7 +510,7 @@ async def _codex_usage_windows(soul: Soul) -> list[str]:
 
         report = await asyncio.wait_for(
             OpenAIChatGPTAdapter().fetch(provider, runtime.oauth),
-            timeout=6.0,
+            timeout=3.0,
         )
     except Exception:
         logger.debug("Codex usage lookup for 429 message failed", exc_info=True)

src/pythinker_code/ui/shell/usage_adapters/openai_chatgpt.py

@@ -207,25 +207,44 @@ def _label_for_codex_window(seconds: int) -> str:
 
 
 def _codex_reset_hint(win_map: Mapping[str, Any]) -> str | None:
-    # Current shape: `resets_at` is a unix-seconds timestamp.
-    # Older shape: `reset_at` is an ISO-8601 string.
-    resets_at_unix = win_map.get("resets_at")
-    if isinstance(resets_at_unix, int | float):
+    # The reset time arrives under `resets_at` or `reset_at`, and as a
+    # unix-seconds timestamp (number or numeric string) or an ISO-8601 string.
+    # Always humanize it ("resets in 2h 14m") rather than printing a raw value.
+    for key in ("resets_at", "reset_at"):
+        raw = win_map.get(key)
+        if raw is None:
+            continue
+        dt = _coerce_reset_datetime(raw)
+        if dt is not None:
+            return _format_reset_delta(dt, win_map)
+        if isinstance(raw, str) and raw.strip():
+            return f"resets at {raw.strip()}"
+    return None
+
+
+def _coerce_reset_datetime(raw: object) -> datetime | None:
+    """Parse a reset timestamp that may be unix seconds (number or numeric
+    string) or an ISO-8601 string."""
+    if isinstance(raw, bool):
+        return None
+    if isinstance(raw, int | float):
         try:
-            dt = datetime.fromtimestamp(float(resets_at_unix), tz=UTC)
+            return datetime.fromtimestamp(float(raw), tz=UTC)
         except (OverflowError, OSError, ValueError):
             return None
-        return _format_reset_delta(dt, win_map)
-
-    reset_at = win_map.get("reset_at")
-    if reset_at is None:
-        return None
-    reset_at_str = str(reset_at)
-    try:
-        dt = datetime.fromisoformat(reset_at_str.replace("Z", "+00:00"))
-    except (TypeError, ValueError):
-        return f"resets at {reset_at_str}"
-    return _format_reset_delta(dt, win_map)
+    if isinstance(raw, str):
+        candidate = raw.strip()
+        if not candidate:
+            return None
+        try:  # numeric string -> unix seconds
+            return datetime.fromtimestamp(float(candidate), tz=UTC)
+        except (OverflowError, OSError, ValueError):
+            pass
+        try:  # ISO-8601
+            return datetime.fromisoformat(candidate.replace("Z", "+00:00"))
+        except (TypeError, ValueError):
+            return None
+    return None
 
 
 def _format_reset_delta(dt: datetime, win_map: Mapping[str, Any]) -> str:

tests/core/test_pythinkersoul_think_only.py

@@ -9,7 +9,7 @@
 from __future__ import annotations
 
 import pytest
-from pythinker_core.chat_provider import APIEmptyResponseError
+from pythinker_core.chat_provider import APIEmptyResponseError, APIStatusError
 
 from pythinker_code.soul.pythinkersoul import PythinkerSoul
 
@@ -18,3 +18,21 @@
 async def test_think_only_error_is_retryable() -> None:
     """APIEmptyResponseError from think-only responses should be retryable."""
     assert PythinkerSoul._is_retryable_error(APIEmptyResponseError("only thinking content"))
+
+
+def test_hard_usage_limit_429_is_not_retryable() -> None:
+    """A subscription usage cap (resets in hours) must NOT be retried — retrying
+    only adds backoff latency before the inevitable failure. Covers both the bare
+    streaming text and the structured-body shape."""
+    bare = APIStatusError(429, "Usage limit reached", body=None)
+    structured = APIStatusError(
+        429, "Error code: 429", body={"error": {"type": "usage_limit_reached"}}
+    )
+    assert PythinkerSoul._is_retryable_error(bare) is False
+    assert PythinkerSoul._is_retryable_error(structured) is False
+
+
+def test_transient_429_and_5xx_remain_retryable() -> None:
+    """A transient RPM/TPM burst (clears in seconds) and server 5xx still retry."""
+    assert PythinkerSoul._is_retryable_error(APIStatusError(429, "rate limit exceeded")) is True
+    assert PythinkerSoul._is_retryable_error(APIStatusError(503, "service unavailable")) is True

tests/ui/usage_adapters/test_openai_chatgpt.py

@@ -29,6 +29,25 @@ def test_parse_codex_usage_two_windows() -> None:
     assert report.limits[0].unit == "%"
 
 
+def test_parse_codex_usage_humanizes_unix_reset_at() -> None:
+    """The live wham/usage payload sends `reset_at` as a unix timestamp number;
+    it must be humanized ("resets in …"), not dumped as a raw integer."""
+    payload = {
+        "rate_limit": {
+            "primary_window": {
+                "percent_left": 99,
+                "limit_window_seconds": 18000,
+                "reset_at": 4102444800,  # far-future unix seconds
+            },
+        }
+    }
+    report = parse_codex_usage_payload(payload)
+    assert report.summary is not None
+    hint = report.summary.reset_hint or ""
+    assert "resets in" in hint
+    assert "4102444800" not in hint  # raw timestamp must not leak
+
+
 def test_parse_codex_usage_handles_alternative_keys() -> None:
     payload = {
         "rate_limits": {