fix(core): honor Retry-After for model retries

[asim48-ctrl]

Summary\n- read provider Retry-After headers when VoltAgent retries failed model calls\n- use Retry-After seconds or HTTP-date values before falling back to exponential backoff\n- add a focused agent retry test for 429 provider errors\n\n## Verification\n- corepack pnpm install --ignore-scripts --frozen-lockfile\n- corepack pnpm --filter @voltagent/internal build\n- corepack pnpm exec vitest run src/agent/agent.spec.ts -t "Retry-After"

---

Summary by cubic

Honor provider Retry-After during model retries. Wait the server-recommended delay and clamp oversized values to Node’s max timer to avoid overflow.

• Bug Fixes
  • Parse Retry-After (seconds or HTTP-date) from error headers and use it for the next attempt.
  • Clamp retry delay to 2,147,483,647 ms and cap exponential backoff to the same limit.
  • Add tests for 429 delay handling and clamping; fall back to capped exponential backoff when the header is missing or invalid.

^{Written for commit 7be7e2c. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Application now respects HTTP Retry-After headers when retrying failed model requests.

• Bug Fixes

  • Clamp excessively large Retry-After values to a safe maximum to prevent timer overflow.

• Tests

  • Added unit tests validating retry timing, honoring Retry-After, and clamping behavior.

• Chores

  • Added a changeset entry to publish the patch release.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7be7e2c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@voltagent/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e9c61c78-d544-4d80-b421-6505529b976d

📥 Commits

Reviewing files that changed from the base of the PR and between d75e3a2 and 7be7e2c.

📒 Files selected for processing (2)

• packages/core/src/agent/agent.spec.ts
• packages/core/src/agent/agent.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/core/src/agent/agent.ts
• packages/core/src/agent/agent.spec.ts

---

📝 Walkthrough

Walkthrough

This PR adds Retry-After support: a helper parses Retry-After from error headers, retry logic in executeWithModelFallback prefers that delay (falling back to exponential backoff) and clamps to Node's max timer, tests verify scheduling and clamping, and a Changeset documents the patch bump.

Changes

Retry-After Header Support

Layer / File(s)	Summary
Retry-After delay extraction helper packages/core/src/agent/agent.ts	Introduces MAX_NODE_TIMER_MS and getRetryAfterDelayMs(error) to parse Retry-After from error headers, supporting integer-second and date/RFC3339 values, returning milliseconds or undefined.
Model retry logic integration packages/core/src/agent/agent.ts	executeWithModelFallback now prefers getRetryAfterDelayMs(error) for retry delays, falls back to exponential backoff when absent, and clamps the final delay to MAX_NODE_TIMER_MS.
Retry-After header tests packages/core/src/agent/agent.spec.ts	Adds Vitest cases: one simulates a retryable 429 with retry-after: "3" asserting onRetry and a 3000ms scheduled timer and successful retry; another asserts overly large retry-after values are clamped to 2_147_483_647.
Release changelog entry .changeset/friendly-agents-wait.md	New Changeset documenting a patch bump for @voltagent/core and noting that retry logic now honors HTTP Retry-After headers.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• agent.ts — 429 retry path ignores Retry-After, coordinated amplification under shared provider contention #1276: This PR implements reading and honoring Retry-After in packages/core/src/agent/agent.ts and includes tests, addressing the issue's reported behavior.

Poem

I nibble at headers, sniff the "wait" sign,
Count seconds like carrots one at a time—
When servers say "pause", I pause without fret,
A patient rabbit, retrying with zest 🐇
Timers set, then hops return success.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title clearly and concisely summarizes the main change: adding support to honor Retry-After headers for model retries.
Description check	✅ Passed	The description provides detailed information about the change objectives, implementation details (Retry-After parsing, clamping, fallback), verification steps, and includes a changeset entry. All key template sections are adequately addressed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 2 files

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/core/src/agent/agent.ts`:
- Around line 5752-5759: The Retry-After delay calculation can exceed Node's max
timer (2,147,483,647 ms) causing setTimeout to clamp to ~1ms; introduce a
MAX_NODE_TIMER constant (2147483647) and clamp computed delays to that limit in
getRetryAfterDelayMs and where retryDelayMs is ultimately assigned before
calling setTimeout (refer to function getRetryAfterDelayMs and the variable
retryDelayMs). Ensure both the seconds-parsed branch and the Date-parsed branch
return Math.min(calculatedDelay, MAX_NODE_TIMER) and that the final retryDelayMs
is similarly clamped so setTimeout never receives a value > MAX_NODE_TIMER.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9eebe398-7d11-4c5c-9b99-6d8e62d3d21e

📥 Commits

Reviewing files that changed from the base of the PR and between 08414ed and d75e3a2.

📒 Files selected for processing (3)

• .changeset/friendly-agents-wait.md
• packages/core/src/agent/agent.spec.ts
• packages/core/src/agent/agent.ts