Add extra_headers support

[tembo]

What does this PR do?

Adds comprehensive support for custom HTTP headers (extra_headers) across the hermes-agent codebase. This enables custom providers to include additional authentication headers or routing information with API requests.

Related Issue

Follows up on PR NousResearch#3526 feedback to merge latest changes and add test coverage.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)
• ✅ Tests (adding or improving test coverage)

Changes Made

Core Implementation

• run_agent.py: Added extra_headers parameter to AIAgent.__init__() with proper documentation. Implemented logic to merge custom headers with existing default_headers for custom providers.
• cli.py: Added extra_headers attribute to HermesCLI and propagated it through runtime configuration in _resolve_turn_agent_config() and _resolve_agent_config().
• hermes_cli/runtime_provider.py: Enhanced _get_named_custom_provider() to parse and validate extra_headers from config (dict type only). Updated _resolve_named_custom_runtime() to include extra_headers in resolved runtime.
• agent/smart_model_routing.py: Added extra_headers propagation in resolve_turn_route() for both primary fallback and routed runtime scenarios.
• gateway/run.py: Added extra_headers to _resolve_runtime_agent_kwargs() and GatewayRunner runtime configuration.

Test Coverage

• tests/test_run_agent.py: Added TestExtraHeaders class with 7 comprehensive tests covering:

  • Storage of extra_headers on agent instance
  • Proper application to OpenAI client for custom providers
  • Non-application for non-custom providers
  • Merging with existing default headers
  • Handling of None/empty values

• tests/agent/test_smart_model_routing.py: Added 3 tests for smart routing:

  • Preservation of extra_headers from primary runtime
  • Exclusion from signature tuple
  • Inclusion from routed runtime

• tests/test_runtime_provider_resolution.py: Added 8 tests for provider resolution:

  • Named custom provider with valid extra_headers
  • Type validation (dict-only)
  • Empty dict and non-dict handling
  • Gateway integration tests

• tests/test_cli_provider_resolution.py: Updated existing tests to initialize extra_headers = None.

How to Test

1. Run all tests: pytest tests/ -q
2. Verify custom provider with headers: Configure a custom provider in cli-config.yaml with extra_headers dict
3. Test smart routing: Verify headers are preserved when routing to different models
4. Test gateway: Verify headers are passed through gateway runtime resolution

Checklist

Code

• My commit messages follow Conventional Commits
• I've run pytest tests/ -q and all tests pass
• I've added comprehensive tests for the changes
• Changes are focused on extra_headers feature only

Documentation & Housekeeping

• Updated docstrings in AIAgent.__init__() with extra_headers parameter documentation
• Changes are backward compatible (extra_headers defaults to None)
• Cross-platform compatible (no platform-specific code)

Want tembo to make any changes? Add a review or comment with @tembo and i'll get back to work!