PR #15173: fix(auth/gateway): surface Codex OAuth credential from credential_pool to /usage (#15167)

• Repository: NousResearch/hermes-agent
• Author: briandevans
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/15173

Description (problem / solution / changelog)

What does this PR do?

Fixes #15167. When a user runs `hermes auth add openai-codex --type oauth`, the OAuth tokens land in `auth.json -> credential_pool["openai-codex"]` — the newer pooled slot — not the legacy `providers["openai-codex"]` slot. Two gaps then conspired to make `/usage` in the gateway surface nothing, even with a valid OAuth credential on disk:

Gap 1 — `_read_codex_tokens` only reads the legacy slot. Every downstream Codex consumer (`agent/account_usage.py::_fetch_codex_account_usage`, refresh paths) funnels through this reader. A fresh OAuth add bypasses the legacy slot, so the reader raised `AuthError(code=codex_auth_missing)` despite the credential existing, and `fetch_account_usage` silently returned `None`.

Gap 2 — `/usage` handler only probed live/cached agent + session DB. A fresh-after-login user whose agent has been evicted (or never instantiated yet) has neither a live `agent.provider` nor a `billing_provider` row on the session DB. The handler fell through to the "Session Info" stub and never even attempted the account-usage call.

Net user-visible effect: `/usage` shows the stub message (`(Detailed usage available after the first agent response)`) instead of the ChatGPT subscription window (5h / weekly) even though the credential is valid.

Fix

Two surgical patches that land together:

1. `hermes_cli/auth.py::_read_codex_tokens` — fall back to credential_pool

When the legacy slot is empty, pick the first pool entry with `auth_type == "oauth"` and a non-empty `access_token`, then project it onto the same `{"tokens": {...}, "last_refresh": ..., "base_url": ...}` shape the legacy slot returns. The rest of the module stays unaware of where the credential came from.

Invariants preserved:

• Legacy slot still wins when both slots are populated (backward-compat for any hybrid state left by tooling mid-migration)
• Non-OAuth pool entries (`auth_type: api_key` and friends) are skipped — they lack `refresh_token` and would crash the refresh flow
• Malformed OAuth entries (missing `access_token`) fall through to the existing `codex_auth_missing` error path rather than being silently returned

2. `gateway/run.py::_handle_usage_command` — probe credential_pool when no provider resolved

After the existing `live agent → cached agent → session DB billing row` resolution chain, probe the auth `credential_pool` for a small allow-list of account-usage-capable providers when `provider` is still unset. First hit wins. Probe errors are swallowed — strictly best-effort; the handler always returns a string rather than propagating a `RuntimeError` from a corrupted auth.json.

The allow-list is a new module-level `_USAGE_ACCOUNT_PROVIDERS = ("openai-codex", "anthropic")` constant so future providers with account-usage APIs can be added in one obvious place instead of sprinkled inline.

Verified behavior after fix

``` 📈 Account limits Provider: openai-codex (Plus) Session: 82% remaining (18% used) • resets in 22m Weekly: 91% remaining (9% used) • resets in 4d 5h ```

Appears even when no agent is in cache.

Test coverage (9 new tests, all green locally)

`tests/hermes_cli/test_auth_codex_provider.py` — 6 cases:

• `test_read_codex_tokens_falls_back_to_credential_pool_oauth_entry` — the core fix: OAuth in pool, legacy empty → pool wins
• `test_read_codex_tokens_prefers_legacy_slot_over_pool` — hybrid state: both populated → legacy still wins (backward-compat guard)
• `test_read_codex_tokens_skips_non_oauth_pool_entries` — `auth_type: api_key` in pool doesn't get treated as a Codex OAuth token
• `test_read_codex_tokens_skips_pool_entries_missing_access_token` — malformed entries don't silently pass through
• `test_read_codex_tokens_picks_first_valid_oauth_entry_when_multiple` — deterministic order when pool has several OAuth entries
• `test_read_codex_tokens_empty_pool_raises_auth_error` — both slots empty still raises, user gets the "run hermes auth" guidance

`tests/gateway/test_usage_command.py` — 3 cases:

• `test_usage_command_probes_credential_pool_when_no_agent_and_no_billing_row` — the #15167 repro end-to-end
• `test_usage_command_stops_probing_pool_on_first_hit` — iteration short-circuits on first provider with a stored credential
• `test_usage_command_pool_probe_errors_fall_through_gracefully` — handler swallows `RuntimeError` from a corrupted auth.json and still returns a string

Related Issue

Fixes #15167

Type of Change

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

Test plan

• `tests/hermes_cli/test_auth_codex_provider.py` — 22 passed (16 pre-existing + 6 new)
• `tests/gateway/test_usage_command.py` — my 3 new tests pass; the pre-existing tests that fail locally (`requests` missing in my venv, unrelated to this PR) are green on clean `origin/main` per CI history
• No behavioural change when the legacy `providers` slot is populated — hybrid-state backward-compat explicitly tested
• The `_USAGE_ACCOUNT_PROVIDERS` tuple is a single-line extension point — adding anthropic/openrouter OAuth probe in future is a 1-char edit

Not in scope (explicit follow-up candidates per the reporter's own notes)

• Unifying the legacy `providers` and `credential_pool` reads behind a single accessor — probably worthwhile across anthropic/openrouter/qwen too since they have the same legacy-vs-pool skew, but a much bigger surface than what this user-facing regression needs to unblock.
• The "agent cached but `agent.provider` is unset" case — not encountered in the reported repro; separate change if it turns out to be real.

Changed files

• gateway/run.py (modified, +27/-0)
• hermes_cli/auth.py (modified, +52/-1)
• tests/gateway/test_usage_command.py (modified, +158/-0)
• tests/hermes_cli/test_auth_codex_provider.py (modified, +180/-0)