feat: configure API retry backoff (#370)

[jatmn]

Summary

• Adds OpenClaude-branded retry controls for retryable API failures:
  • OPENCLAUDE_MAX_RETRIES
  • OPENCLAUDE_RETRY_DELAY_MS
• Replaces the old CLAUDE_CODE_MAX_RETRIES configuration name in the retry path.
• Allows OPENCLAUDE_MAX_RETRIES=0 to disable retries after the initial request.
• Keeps provider Retry-After headers authoritative when they are present.
• Documents the new settings in .env.example and docs/advanced-setup.md.
• Adds focused tests for retry defaults, invalid values, caps, zero retries, configured delay, and Retry-After precedence.

Why

Fixes #370.

Some OpenAI-compatible providers, including providers with per-second rate limits, can return transient 429 responses without a useful Retry-After header. Before this change, OpenClaude had retry behavior, but users could not tune the fallback backoff delay for providers that omit Retry-After, and the exposed retry-count env var still used old Claude Code branding.

This gives users a clear OpenClaude configuration surface for retry count and fallback retry delay while preserving the existing behavior by default.

User Impact

Users can now tune retry behavior without changing code:

OPENCLAUDE_MAX_RETRIES=10
OPENCLAUDE_RETRY_DELAY_MS=500

OPENCLAUDE_MAX_RETRIES=0 disables retries after the initial request.

When an API response includes Retry-After, OpenClaude still honors that server-provided delay instead of the configured fallback delay.

Provider Paths

This affects the shared API retry path used for retryable API failures, including OpenAI-compatible providers. The most relevant path for issue #370 is providers that return retryable 429s without Retry-After.

Validation

• bun install
  • Passed
  • Checked 714 installs across 516 packages with no changes
• bun run build
  • Passed
  • Built dist/cli.mjs
  • Built dist/sdk.mjs
  • External list validation passed
  • SDK type declarations were in sync
  • Build printed existing warnings about optional external entries not in package.json, but exited successfully
• bun run smoke
  • Passed
  • Rebuilt successfully
  • node dist/cli.mjs --version returned 0.9.2 (OpenClaude)
• bun test src/services/api/withRetry.test.ts
  • Passed in earlier focused validation for this branch
  • Note: this focused test can hit an unrelated source-checkout import issue around optional feature-gated command modules when run in isolation. I did not add unrelated test scaffolding changes to this PR.

Notes

• No unrelated model-effort changes are included.
• Branch is based on upstream main.
• No changes were made to persistent unattended retry mode.

[techbrewboss]

Thanks for the focused retry-config slice. The new OPENCLAUDE_RETRY_DELAY_MS path behaves as described in the branch tests, and bun run build passes locally.

I found one compatibility issue with the env var rename that should be handled before merge.

Validation I ran locally:

• bun run build passed
• bun test src/services/api/withRetry.test.ts currently fails on the known isolated-import issue: Cannot find module './commands/fork/index.js' from 'src/commands.ts'. After that first import failure, the remaining retry assertions in this file pass.

[techbrewboss]

This drops support for the previously documented CLAUDE_CODE_MAX_RETRIES setting without any fallback. Existing users who already set CLAUDE_CODE_MAX_RETRIES=0 or tuned it down for CI will silently go back to the default 10 retries after upgrading, which is a behavioral regression in the same retry path this PR is changing. Can we keep a compatibility fallback when OPENCLAUDE_MAX_RETRIES is unset, preferably with the new env var taking precedence and maybe a debug/deprecation message for the legacy name?

[techbrewboss]

Re-reviewed current head f41c1972. The compatibility issue I raised earlier is fixed: OPENCLAUDE_MAX_RETRIES takes precedence, and CLAUDE_CODE_MAX_RETRIES is still honored as a deprecated fallback when the new env var is unset. The docs and tests cover that behavior.

Validation I ran locally:

• CLAUDE_CODE_MAX_RETRIES=0 with no OPENCLAUDE_MAX_RETRIES returns 0 from getDefaultMaxRetries()
• bun test src/services/api/withRetry.test.ts passes: 28/28
• git diff upstream/main...HEAD --check passes
• bun run build passes

I do not see a remaining blocker.

[Vasanthdev2004]

Targeted review of current head f41c197, focused on the retry configuration behavior for #370.

Verdict: Approve-ready

What I checked:

• OPENCLAUDE_MAX_RETRIES is the new primary setting.
• CLAUDE_CODE_MAX_RETRIES remains a deprecated fallback when the OpenClaude setting is unset, so existing users do not silently lose their retry config.
• OPENCLAUDE_MAX_RETRIES=0 correctly disables retries after the initial request.
• Retry-After remains authoritative over configured fallback delay.
• Ran bun test ./src/services/api/withRetry.test.ts: 28/28 passing.

I do not see a blocker on current head.

[jatmn]

@kevincodex1

[Vasanthdev2004]

Blockers

None.

Non-Blocking

None.

Looks Good

• Configurable API retry backoff
• 153 additions, 6 deletions — focused feature
• Already has maintainer approvals

---

Verdict: Approve — clean retry backoff feature.

[Vasanthdev2004]

Clean retry backoff feature.

[gnanam1990]

Approving — clean, well-scoped retry-config slice. 🎉

I verified the safety properties: bounded (100-retry / 60s caps), invalid values fall back to defaults, OPENCLAUDE_MAX_RETRIES=0 correctly disables retries, server-provided Retry-After stays authoritative over the configured fallback, and legacy CLAUDE_CODE_MAX_RETRIES is honored as a documented deprecated fallback so existing users don't silently lose config. No new network surface in third-party paths, no red flags, and the tests cover the matrix and pass on current head. Maps cleanly to #370. Thanks!