fix(retry): cap jittered delay to max_delay

[Dhakshin2007]

Summary

This PR fixes a bug introduced in the feat: add opt-in model retry policies commit (3a52673) inside src/agents/run_internal/model_retry.py.

Per reviewer feedback from @seratch, the Retry-After OverflowError handling has been dropped as it is unnecessary in practice. This PR now focuses solely on the jitter cap fix.

---

Bug: Jitter can produce delay > max_delay (silent backoff violation)

Location: _default_retry_delay(), lines 287–290

Root cause:
The original code caps the exponential delay with min(..., max_delay) before applying jitter:

# BEFORE (buggy)
delay = min(initial_delay * (multiplier ** max(attempt - 1, 0)), max_delay)
if not use_jitter:
    return delay
return max(delay * (0.875 + random.random() * 0.25), 0.0)

Because jitter multiplies the already-capped value by up to 1.125, the final result can exceed max_delay by ~12.5%.

Fix:

# AFTER (fixed)
base = min(initial_delay * (multiplier ** max(attempt - 1, 0)), max_delay)
if not use_jitter:
    return base
return min(max(base * (0.875 + random.random() * 0.25), 0.0), max_delay)

Apply min(..., max_delay) after jitter so the final delay is always bounded by max_delay.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0161128362

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[Dhakshin2007]

Thanks for the P2 feedback, @chatgpt-codex-connector!

You are correct — applying jitter to the uncapped exponential (delay * jitter_factor) and then clamping makes the jitter ineffective once the base grows well past max_delay (≥ attempt 5 with defaults), because even the minimum jitter factor (0.875) keeps the result above max_delay, so every call returns exactly max_delay.

The second commit addresses this by clamping the base first, then applying jitter to the clamped value, and finally capping the result:

# Clamp base first so jitter stays effective even at saturation
base = min(initial_delay * (multiplier ** max(attempt - 1, 0)), max_delay)
if not use_jitter:
    return base
return min(max(base * (0.875 + random.random() * 0.25), 0.0), max_delay)

With this approach at saturation (base = max_delay), jitter produces delays in [0.875 * max_delay, max_delay] — preserving the thundering-herd spread Codex correctly identified was lost.

[chatgpt-codex-connector]

Note

To use Codex here, create a Codex account and connect to github.

[seratch]

I think the Retry-After overflow handling is not necessary in practice. That header value is supplied by the model provider, and an extremely large numeric value there is a very unlikely scenario. Also, the current overflow change does not materially improve the common path enough to justify carrying the extra logic.

The jitter cap fix, on the other hand, is useful on its own. It preserves randomness while ensuring the computed retry delay never exceeds max_delay, which is a concrete improvement to the backoff behavior.

Could you please update this PR to keep only the jitter improvement and drop the Retry-After overflow handling changes?

[Dhakshin2007]

@seratch Thank you for the review! I've addressed your feedback:

• Dropped the Retry-After OverflowError handling as requested
• The PR now contains only the jitter cap fix (capping the final jittered delay to max_delay)

Updated the PR title and description accordingly.