cli-agent-runner 0.1.26__tar.gz → 0.1.27__tar.gz

{cli_agent_runner-0.1.26 → cli_agent_runner-0.1.27}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.27] - 2026-05-17
+
+### Fixed
+- claude plugin: rate_limit_event with rateLimitType=null no longer misclassified as account
+  5h quota; falls through to api_error_status-based bucket (e.g. infra 429 → rate_limit_model).
+  Affects supervisors consuming transient_error_detected.
+
+### Added
+- docs/migrations/0.1.27.md: supervisor usage guide for transient_error_detected event
+  (4-bucket dispatch table + back-off recipe).
+
+See `docs/migrations/0.1.27.md`.
+
 ## [0.1.26] - 2026-05-17
 
 - Fix claude `agent_usage_recorded` `model` field (was always

{cli_agent_runner-0.1.26 → cli_agent_runner-0.1.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.26
+Version: 0.1.27
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme

{cli_agent_runner-0.1.26 → cli_agent_runner-0.1.27}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.26'
-__version_tuple__ = version_tuple = (0, 1, 26)
+__version__ = version = '0.1.27'
+__version_tuple__ = version_tuple = (0, 1, 27)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.26 → cli_agent_runner-0.1.27}/agent_runner/builtin_plugins/claude_rate_limit.py

@@ -118,13 +118,15 @@ def _classify_transient_error(
     """Refactored from prior _scan_log_for_transient_error 0.1.23 logic; same shape, same
     priority (rate_limit_event.rejected > 429 > 5xx > 408).
     """
-    if rate_limit_info is not None:
+    if rate_limit_info is not None and rate_limit_info.get("rateLimitType") == "five_hour":
         return {
             "classification": "rate_limit_account",
             "agent": "claude",
             "reset_at_epoch": int(rate_limit_info.get("resetsAt", time.time() + 300)),
             "raw": str((result_event or {}).get("result", ""))[:_RAW_CAP],
         }
+    # rate_limit_event with null/other rateLimitType falls through to status-based
+    # classification below.
     if result_event is None or result_event.get("is_error") is not True:
         return None
     status = result_event.get("api_error_status")

cli_agent_runner-0.1.27/docs/migrations/0.1.27.md

@@ -0,0 +1,169 @@
+# 0.1.27 — Rate-limit classifier fix + supervisor usage guide
+
+## What changed
+
+The claude built-in plugin (`agent_runner.builtin_plugins.claude_rate_limit`) previously
+misclassified any `rate_limit_event` with `status="rejected"` as `rate_limit_account`
+(account-level 5-hour quota exhaustion), regardless of `rateLimitType`. As of 0.1.27, the
+`rate_limit_account` branch requires `rateLimitType == "five_hour"`; other `rate_limit_event`
+values (e.g. `rateLimitType: null` for claude.ai infrastructure throttling) fall through to
+status-code-based classification.
+
+Concretely: a claude.ai 429 with `rateLimitType: null` is now correctly emitted as
+`transient_error_detected` with `classification: "rate_limit_model"` and a 60-second default
+`reset_at_epoch`, instead of `rate_limit_account` with a synthetic 5-minute fallback epoch.
+
+No event schema changes. No new event kinds. No new public API.
+
+## Supervisor usage — consuming `transient_error_detected`
+
+External supervisors should subscribe to the `transient_error_detected` event family (added in
+0.1.23). The event carries a `classification` discriminator with one of 4 values:
+
+| classification     | Trigger                                              | reset_at_epoch semantics            | Suggested supervisor action               |
+|--------------------|------------------------------------------------------|-------------------------------------|-------------------------------------------|
+| rate_limit_account | rate_limit_event.rateLimitType == "five_hour"        | Server-provided `resetsAt` (exact)  | Sleep until reset_at_epoch (multi-hour)   |
+| rate_limit_model   | api_error_status == 429 (and not five_hour)          | now + 60s default (no server hint)  | Sleep until reset_at_epoch or exp-backoff |
+| api_transient_5xx  | api_error_status in {500, 502, 503, 504}             | now + 60s default                   | Sleep until reset_at_epoch or exp-backoff |
+| api_timeout        | api_error_status == 408                              | now + 30s default                   | Sleep until reset_at_epoch or exp-backoff |
+
+### Event payload shape
+
+Each line in `events-YYYY-MM.jsonl` looks like:
+
+```json
+{
+  "ts": "2026-05-17T02:13:44.123Z",
+  "event": "transient_error_detected",
+  "classification": "rate_limit_model",
+  "agent": "claude",
+  "reset_at_epoch": 1747450424,
+  "round_num": 7,
+  "raw": "API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited"
+}
+```
+
+Fields:
+
+- `ts` — ISO 8601 UTC timestamp of event emission.
+- `event` — always `"transient_error_detected"`.
+- `classification` — one of the 4 buckets above.
+- `agent` — `"claude"` (gemini uses same schema via its own plugin).
+- `reset_at_epoch` — Unix epoch seconds; supervisor sleeps until this time. For
+  `rate_limit_account` this is the server-provided exact unblock time; for all other buckets
+  it is `now + default_seconds` at the moment of emission.
+- `round_num` — which agent round triggered the error.
+- `raw` — first 200 chars of the result text (useful for logging/alerting).
+
+### Dispatch recipe (Python)
+
+```python
+import time
+
+
+def handle_transient_error(event: dict) -> None:
+    """React to a transient_error_detected event from agent-runner."""
+    bucket = event["classification"]
+    reset_at = event["reset_at_epoch"]
+    now = time.time()
+    wait_s = max(reset_at - now, 0)
+
+    if bucket == "rate_limit_account":
+        # Server-provided exact unblock time; respect it (multi-hour wait typical).
+        time.sleep(wait_s)
+    elif bucket == "rate_limit_model":
+        # Infra-level 429; 60s default. Apply your own exp-backoff curve if desired.
+        time.sleep(wait_s)  # or: time.sleep(exp_backoff_with_cap(attempts, cap=300))
+    elif bucket == "api_transient_5xx":
+        # Transient server error; 60s default.
+        time.sleep(wait_s)
+    elif bucket == "api_timeout":
+        # Request timed out; 30s default.
+        time.sleep(wait_s)
+    else:
+        # Unknown future bucket — safe fallback.
+        time.sleep(max(wait_s, 30))
+```
+
+### Default back-off vs. your own curve
+
+Agent-runner's defaults (`rate_limit_model` and `api_transient_5xx` → 60s, `api_timeout` → 30s)
+are a conservative baseline — a flat one-shot sleep. Supervisors that track consecutive failures
+may apply an exponential curve with a cap (e.g. 30s → 60s → 120s → 300s max) for
+`rate_limit_model` and `api_transient_5xx`. For `rate_limit_account`, always respect
+`reset_at_epoch` verbatim — the server provides the exact unblock time.
+
+## Migration from legacy `rate_limit_rejected` event
+
+Consumers that still listen to `rate_limit_rejected` (added in 0.1.20) continue to receive it
+for `rate_limit_account` events only. It is emitted as a back-compat dual-emit alongside
+`transient_error_detected`. New consumers should subscribe to `transient_error_detected` for
+full 4-bucket coverage; `rate_limit_rejected` only fires for the `five_hour` bucket and carries
+no `classification` field.
+
+## Verification
+
+Write the incident JSONL into a temporary file and call `_parse_claude_log` directly:
+
+```bash
+mkdir -p /tmp/verify-0.1.27
+cat > /tmp/verify-0.1.27/round-1.log <<'EOF'
+{"type":"rate_limit_event","rate_limit_info":{"status":"rejected","rateLimitType":null}}
+{"type":"assistant","message":{"model":"claude-opus-4-7","content":[{"type":"text","text":"API Error: rate limited"}]}}
+{"type":"result","is_error":true,"api_error_status":429,"result":"API Error: rate limited","usage":{"input_tokens":100,"output_tokens":10,"cache_read_input_tokens":0},"duration_ms":1000,"total_cost_usd":0.01}
+EOF
+
+.venv/bin/python -c "
+from pathlib import Path
+from agent_runner.builtin_plugins.claude_rate_limit import _parse_claude_log
+import json
+print(json.dumps(_parse_claude_log(Path('/tmp/verify-0.1.27/round-1.log')), indent=2, default=str))
+"
+```
+
+Expected output:
+
+```json
+{
+  "transient_error": {
+    "classification": "rate_limit_model",
+    "agent": "claude",
+    "reset_at_epoch": 1747450484,
+    "raw": "API Error: rate limited"
+  },
+  "usage": {
+    "agent": "claude",
+    "model": "claude-opus-4-7",
+    "input_tokens": 100,
+    "output_tokens": 10,
+    "cached_tokens": 10,
+    "cost_usd": 0.01,
+    "duration_ms": 1000
+  }
+}
+```
+
+`classification` must be `"rate_limit_model"` and `reset_at_epoch` must be approximately
+`now + 60`. Clean up with `rm -rf /tmp/verify-0.1.27`.
+
+## Impact summary
+
+Supervisors that dispatch semantically on `classification == "rate_limit_account"` (e.g. "this
+is the 5-hour quota — wait until reset") will no longer trigger that path for infrastructure
+429s with `rateLimitType: null`. Instead, a `rate_limit_model` event fires with a 60-second
+`reset_at_epoch`.
+
+Supervisors that dispatch only on `reset_at_epoch` (ignoring classification) will see a shorter
+wait (60s instead of ~300s) for infra 429s — a net improvement.
+
+Supervisors subscribed to the legacy `rate_limit_rejected` event are unaffected: that event
+only fires for genuine `rate_limit_account` (five_hour) events, which continue to work as
+before.
+
+## What did NOT change
+
+- `transient_error_detected` event schema — field names, field types unchanged.
+- `_BACK_OFF_DEFAULTS` table — unchanged.
+- Legacy `rate_limit_rejected` back-compat emission for `rate_limit_account` — unchanged.
+- Other plugins (gemini) — no equivalent `rate_limit_event` semantics; not touched.
+- Public API surface — no new functions, no new event kinds, no signature changes.

{cli_agent_runner-0.1.26 → cli_agent_runner-0.1.27}/tests/unit/test_claude_error_detector.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import json
+import time
 from unittest.mock import MagicMock, patch
 
 from tests._test_helpers import make_hook_context, write_round_log
@@ -355,3 +356,48 @@ def test_given_claude_log_without_assistant_event_when_extracted_then_model_unkn
             with patch(f"{_MOD}.time.time", return_value=1000):
                 ClaudeErrorDetector().after_round(make_hook_context(tmp_path), result=MagicMock())
     assert usage_emit.call_args.kwargs["model"] == "unknown"
+
+
+def test_given_429_with_null_rate_limit_type_when_classified_then_rate_limit_model(tmp_path):
+    """rate_limit_event with rateLimitType=null + api_error_status=429 must classify as
+    rate_limit_model (infra), not rate_limit_account (5h quota).
+    """
+    from agent_runner.builtin_plugins.claude_rate_limit import _parse_claude_log
+
+    log = tmp_path / "round-1.log"
+    assistant_line = (
+        '{"type":"assistant","message":{"model":"claude-opus-4-7",'
+        '"content":[{"type":"text","text":"API Error: rate limited"}]}}\n'
+    )
+    result_line = (
+        '{"type":"result","is_error":true,"api_error_status":429,'
+        '"stop_reason":"stop_sequence","result":"API Error: rate limited",'
+        '"usage":{"input_tokens":100,"output_tokens":10,"cache_read_input_tokens":0},'
+        '"duration_ms":1000,"total_cost_usd":0.01}\n'
+    )
+    log.write_text(
+        '{"type":"rate_limit_event","rate_limit_info":{"status":"rejected","rateLimitType":null}}\n'
+        + assistant_line
+        + result_line,
+        encoding="utf-8",
+    )
+    parsed = _parse_claude_log(log)
+    assert parsed["transient_error"]["classification"] == "rate_limit_model"
+    # reset_at_epoch ≈ now + 60 (_BACK_OFF_DEFAULTS["rate_limit_model"])
+    now = int(time.time())
+    assert now + 55 <= parsed["transient_error"]["reset_at_epoch"] <= now + 65
+
+
+def test_given_rate_limit_event_null_type_without_result_when_classified_then_none(tmp_path):
+    """Edge: rate_limit_event with rateLimitType=null but no result_event returns no
+    transient_error (without a status code we can't bucket; supervisor uses generic retry).
+    """
+    from agent_runner.builtin_plugins.claude_rate_limit import _parse_claude_log
+
+    log = tmp_path / "round-1.log"
+    log.write_text(
+        '{"type":"rate_limit_event","rate_limit_info":{"status":"rejected","rateLimitType":null}}\n',
+        encoding="utf-8",
+    )
+    parsed = _parse_claude_log(log)
+    assert "transient_error" not in parsed