What does this PR do?

Finishes the retry/backoff work intended for PR #8486 by wiring configurable retry settings all the way from config into AIAgent, and by fixing the actual retry behavior in run_agent.py.

This change adds:

• agent.max_api_retries for full API-call retries
• agent.max_stream_retries for transient streaming reconnect retries

It also fixes the outer retry loop so it no longer uses a hardcoded retry count, honors Retry-After headers, applies smarter rate-limit vs generic retry backoff, and keeps streaming reconnect recovery separate from full-request retries. This approach stays small and idiomatic by extending the existing retry paths instead of introducing a new abstraction.

Related Issue

Fixes #5570

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)

Changes Made

• Added agent.max_api_retries and agent.max_stream_retries defaults and normalization in hermes_cli/config.py
• Added CLI-side defaults and runtime plumbing in cli.py
• Bridged gateway config into env vars in gateway/run.py
• Updated AIAgent retry config handling and retry behavior in run_agent.py
• Fixed outer retry loop to honor configured retries instead of a hardcoded value
• Added capped Retry-After handling and smarter backoff logic for rate limits vs other retryable errors
• Kept non-streaming requests on the outer retry loop only, and streaming reconnects on the inner loop
• Ensured stream retry recovery rebuilds the primary OpenAI client when needed
• Updated retry/config regression tests in:
  • tests/test_api_retry_config.py
  • tests/hermes_cli/test_config.py
  • tests/cli/test_cli_init.py
  • tests/run_agent/test_run_agent.py
• Updated config/docs examples in:
  • cli-config.yaml.example
  • docs/acp-setup.md

How to Test

1. Set retry config in ~/.hermes/config.yaml, for example:

   agent:
     max_api_retries: 5
     max_stream_retries: 5

2. Run the focused regression suite:

   HERMES_HOME=/tmp/hermes-ci-home python -m pytest \
     tests/run_agent/test_run_agent.py \
     tests/run_agent/test_provider_fallback.py \
     tests/run_agent/test_streaming.py \
     tests/run_agent/test_openai_client_lifecycle.py \
     tests/test_api_retry_config.py \
     tests/hermes_cli/test_config.py \
     tests/cli/test_cli_init.py \
     -q -o addopts=''

3. Verify the suite passes and confirm retry behavior:
   • outer retries respect max_api_retries
   • stream reconnects respect max_stream_retries
   • Retry-After is honored and capped
   • rate-limit and generic retryable errors use different backoff behavior

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Focused verification passed locally:

361 passed in 17.93s

Command used:

HERMES_HOME=/tmp/hermes-ci-home python -m pytest \
  tests/run_agent/test_run_agent.py \
  tests/run_agent/test_provider_fallback.py \
  tests/run_agent/test_streaming.py \
  tests/run_agent/test_openai_client_lifecycle.py \
  tests/test_api_retry_config.py \
  tests/hermes_cli/test_config.py \
  tests/cli/test_cli_init.py \
  -q -o addopts=''