fix: OpenAI data-residency endpoints get the declared transport, correct catalog, and authoritative listing

[victor-kyriazakos]

Summary

An enterprise deployment with data-residency obligations pointed openai-api at OpenAI's documented regional host (base_url: https://us.api.openai.com/v1) and Hermes silently degraded four independent ways — the worst being every tool-calling turn failing with HTTP 400 ("Function tools with reasoning_effort are not supported ... use /v1/responses"), which makes the agent completely unusable: no chat, no cron, no subagents. All four defects reduce to two patterns: exact-hostname equality against api.openai.com, and model.base_url honored for inference but not for discovery/cache identity.

All four were reproduced on current main before fixing (resolver-level, no customer credentials needed).

Root cause

Provider policy was duplicated across independent subsystems that each rederived "is this OpenAI" / "which endpoint applies":

Lane	Defect
runtime_provider fallback sites (pool-entry, explicit, api-key paths)	default chat_completions + URL-only detection; the overlay's declared codex_responses never consulted → P1 wrong wire protocol
providers.host_mandated_api_mode / _detect_api_mode_for_url	hostname == "api.openai.com" only → regional hosts unrecognized
models.provider_model_ids openai branch	read $OPENAI_BASE_URL only → discovery probed the wrong endpoint; literal two-URL is_default_openai → regional listings flooded the picker with whisper/tts/embedding rows
models._credential_fingerprint	env-vars-only hash → hermes config set model.base_url didn't invalidate the cached catalog
models.validate_requested_model	curated-catalog soft-accept (#46850) overrode the access-scoped, authoritative OpenAI listing → /model accepted models the key cannot serve

The fix (3 commits, each independently green)

1. fix(providers) — one shared predicate is_official_openai_host(): canonical host + dot-suffix subdomains (us./eu./future <region>.api.openai.com), hostname-parsed only. Spoof rejection preserved ([Bug]: OAuth Pro/Max credential returns "out of extra usage" 400 immediately after fresh login, despite empty/unused account quota #32243): api.openai.com.attacker.test and proxy.test/api.openai.com/v1 do not match. host_mandated_api_mode routes through it.
2. fix(runtime) — _fallback_api_mode(provider, base_url, model): URL detection first, then the provider's declared transport via determine_api_mode(), then chat_completions only for genuinely unknown providers. All three fallback sites share it so the lanes cannot drift. Blast radius beyond openai-api: minimax, minimax-cn, copilot-acp — the other overlays whose declared non-chat transport fell through to chat_completions on the same paths (same bug class). openrouter unaffected (declares openai_chat).
3. fix(models) — _openai_discovery_base_url() (env → matching model.base_url → default, same precedence as inference); effective endpoint folded into the cache fingerprint; is_default_openai → shared predicate; curated soft-accept disabled only when the listing came from an official OpenAI host. Custom OpenAI-compatible proxies keep all existing permissive behavior.

Deliberately unchanged: #37404's empty-intersection → curated picker fallback (existing product decision), Anthropic listing authority (no evidence its listings are authoritative; its curated merge intentionally compensates for lagging listings).

Testing

40 new tests in 4 files, all asserting end-to-end contracts (resolved api_mode on the real resolver paths, picker output through provider_model_ids, switch verdicts through validate_requested_model, fingerprint inequality):

• test_official_openai_host.py — 15 security-contract cases (official hosts match; lookalike/path-spoof/unrelated rejected)
• test_runtime_transport_precedence.py — regional hosts → codex_responses on the fallback helper and the explicit-runtime path; openrouter pinned chat_completions; minimax declared transport honored; URL detection still wins over declaration
• test_openai_discovery_endpoint.py — config/env precedence, provider-mismatch guard, fingerprint changes on config endpoint change (and doesn't for unrelated providers), regional catalog intersection, custom-proxy verbatim list
• test_openai_listing_authority.py — absent model rejected on all three official hosts, present model accepted, custom proxy keeps /model picker omits unlisted models that are callable (zai / glm-5.2) #46850 fallback

scripts/run_tests.sh tests/hermes_cli/ tests/agent/ → 850 files, 7013 passed, 6 failed — the 6 (test_update_eol_churn ×5, test_gateway_service ×1) fail identically on unmodified main in this environment (verified via git stash before any change; local-environment sensitivity, not this PR).

Mutation check — reverted each fix mechanism (predicate narrowed to exact host, fallback helper stubbed to URL-only, discovery resolver stubbed to env-only, authority gate removed) and re-ran the new tests:

tests/hermes_cli/test_runtime_transport_precedence.py  (5 tests failed)
tests/hermes_cli/test_openai_discovery_endpoint.py     (4 tests failed)
tests/hermes_cli/test_openai_listing_authority.py      (3 tests failed)

Tests go red when the fixes are removed; fixes restored, 40/40 green. Each commit was also checked out and tested in isolation (bisectable).

Not in this PR (follow-ups)

• Diagnosability: surface resolved api_mode/endpoint in hermes status / cron listing, and session-start debug logging (separate PR per the triage recommendation).
• Per-job cron endpoint/API-mode controls (changes the cron persistence model).