Summary

When using GitHub Copilot as the provider, HTTP 401 errors cause Hermes to silently fall back to the next model in the chain instead of recovering. This PR adds a one-shot retry mechanism that re-resolves the Copilot token, rebuilds the OpenAI client, and retries the failed request before falling back.

Problem

Copilot OAuth tokens (gho_*) are typically long-lived and valid, but the httpx client state can become stale — particularly after startup race conditions or in long-lived sessions. When this happens, the API returns 401, and Hermes drops to a fallback model without attempting recovery.

Other providers (Codex, Nous, Anthropic) already have 401 recovery handlers. Copilot was missing one.

Changes

run_agent.py

• New method: _try_refresh_copilot_client_credentials()
  • Re-resolves token via the standard priority chain (COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN → gh auth token)
  • Updates api_key and _client_kwargs
  • Reapplies Copilot-specific headers via _apply_client_headers_for_base_url()
  • Rebuilds the shared OpenAI client via _replace_primary_openai_client()
• New retry guard: copilot_auth_retry_attempted = False (matches existing pattern for other providers)
• New 401 handler in the error recovery loop: checks provider == "copilot", calls refresh, retries on success

tests/run_agent/test_run_agent_codex_responses.py

• test_run_conversation_copilot_refreshes_after_401_and_retries — end-to-end 401→refresh→retry
• test_try_refresh_copilot_client_credentials_rebuilds_client — unit test for the refresh method
• test_try_refresh_copilot_client_credentials_rebuilds_even_if_token_unchanged — verifies rebuild happens even when token string is identical (stale client state recovery)

website/docs/integrations/providers.md

• New info section documenting Copilot auth behavior: direct-token auth, 401 recovery flow, and why token exchange via /copilot_internal/v2/token is not used (returns 404 for some account types)

Design Decisions

• Always rebuild client even if token unchanged: The gho_* token is often stable across refreshes. The 401 recovery is about rebuilding stale httpx client state, not necessarily getting a new token.
• Uses _apply_client_headers_for_base_url(): Canonical way to set provider-specific headers (Editor-Version, Copilot-Integration-Id, etc.) — more maintainable than manual header construction.
• One-shot flag guard: Prevents infinite 401 loops. Matches the existing pattern used by Codex, Nous, and Anthropic providers exactly.
• No token exchange endpoint: /copilot_internal/v2/token returns 404 for some account types. Direct gho_* auth works reliably and matches approaches used by other editors (e.g., Zed).

Testing

All 46 tests pass:

pytest tests/run_agent/test_run_agent_codex_responses.py -q
46 passed in 9.96s