[remote-controlled-man]

Summary

The Python SDK can retry before a provider's numeric Retry-After cooldown ends: the default jitter can turn a 10-second hint into 7.5 seconds, and hints above rate_limit_max_delay are discarded. Treat finite positive hints as minimum waits, retaining jitter without retrying early; invalid hints fall back to ordinary exponential backoff.

This deliberately allows a provider-requested wait above the local exponential-backoff cap. The configuration description now makes that distinction explicit. Five parameterized regression cases exercise early retries, above-cap hints, and negative/NaN/infinite hints.

Type of change

• Bug fix

Test plan

Executed the five test stages from scripts/test-all.sh individually, split across macOS (Python/Node) and the existing Linux Go environment; this is not a claim that one invocation of the script passed on macOS.

• Python SDK: python -m pytest with the unchanged default coverage/marker configuration — 2,809 passed, 4 skipped, 38 deselected; displayed aggregate coverage 95%. This full run preceded an AST-identical formatter-only commit; 28 rate-limiter/config tests passed again on the final commit.
• Python Ruff lint, Mypy (86 source files), and Ruff formatting check of all three changed files passed.
• Control plane and Go SDK: go test ./... in both modules, Linux arm64 / Go 1.25.14, GOFLAGS="-tags=sqlite_fts5 -p=2"; both passed. go mod tidy -diff produced no changes.
• TypeScript SDK: CI=1 npm run test:core — 1,256 passed, 1 skipped.
• Web UI: CI=1 npm run test — 837 passed.

Linux checks ran as a non-root user with real DNS packets forwarded over certificate-validated HTTPS because this host rewrites reserved domains. The Go SDK used a complete writable temporary module copy whose 220 files matched the final commit; no test assertions, timeouts, or Go source overlays were changed. Earlier executor setup failures were corrected before the successful runs.

One earlier full Python run also hit an unrelated existing 1-second harness timeout. Focused, module, collection-prefix, and the latest full run passed unchanged; its root cause remains unproven.

Test coverage

• Ran the changed surface locally with default coverage.
• New code paths have regression tests.
• Coverage gate green in upstream CI (pending).
• No coverage baseline was changed; the four default Python skips and 38 deselections remain in effect.

Checklist

• Read the contribution and development guidance.
• Commits are signed and follow conventional-commits style (messages are conventional; the two commits are unsigned).
• No public API signature or dependency changes.

Related issues / PRs

Related context: #265 established the local backoff cap; #1078 isolated the jitter RNG. This change preserves the private RNG and clarifies how provider cooldowns interact with the cap.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[github-actions]

Performance

SDK	Memory	Δ	Latency	Δ	Tests	Status
Python	9.1 KB	-	0.31 µs	-11%	✓	✓

✓ No regressions detected

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 84%, aggregate ≥ 85%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	88.20%	87.40%	↑ +0.80 pp	🟡
sdk-go	93.70%	92.00%	↑ +1.70 pp	🟢
sdk-python	94.73%	93.73%	↑ +1.00 pp	🟢
sdk-typescript	92.50%	90.42%	↑ +2.08 pp	🟢
web-ui	84.89%	84.79%	↑ +0.10 pp	🟡
aggregate	86.11%	85.75%	↑ +0.36 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	0	—	➖ no changes
sdk-go	0	—	➖ no changes
sdk-python	7	100.00%	✅
sdk-typescript	0	—	➖ no changes
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.

[santoshkumarradha]

Looks good. The retry delay now honors a valid server cooldown without breaking the normal backoff path, and the focused tests cover both valid and invalid values.

[AbirAbbas]

Pushed one commit on top since this had been waiting a few days. Treating a valid Retry-After as a minimum is right, but nothing bounded it: Retry-After: 86400 made the default five retries sleep five days, and direct Agent.ai calls have no outer deadline around the limiter. Hints are now honoured up to max(rate_limit_max_delay, 300s) and anything larger is clamped to that, so jitter still never retries before the (capped) cooldown. New parametrized cases cover 3600s at both jitter ends and a larger configured max_delay. I also merged main. Full Python suite and ruff 0.15.22 are clean locally.

[AbirAbbas]

Re-approving after the Retry-After ceiling commit (my push dismissed the earlier approval). Without the ceiling, the new cases fail with 3600s and 4500s sleeps. The full Python suite (2931 passed) and ruff 0.15.22 are clean, and CI is green.