fix(provider): unify provider/credential resolution — config.yaml as single source, fail-closed on custom intent

[banditburai]

Parallel provider/credential resolution paths (CLI, gateway, ACP, auxiliary) had drifted, and OpenRouter was the terminal fallback in every one — so a configured custom/local provider was silently dropped to OpenRouter or had credentials mixed from another provider. This collapses them into one offline resolver → one ResolvedProvider value object → one alias table → one /v1 normalizer → one path-scoped api_mode detector, fail-closed on declared custom intent, with zero network during resolution. Closes 6 issues, supersedes 1 PR.

Issues fixed

Issue	Symptom / root cause	Fix (file:area)	Proof
#3263	Model-switcher loses persisted config; no pre-fill for custom endpoints; probe errors swallowed	main.py (switch + classified probe), config.py (model surface)	test_probe_classification, test_model_flow_custom_probe, test_config_model_surface
#4600	Custom base_url drops /v1 on chat completions	provider_resolution.normalize_base_url via runtime_provider._finalize_runtime	test_provider_resolution, test_runtime_provider_resolution
#5358	Gateway + CLI ignore model.provider, fall back to OpenRouter when OPENROUTER_API_KEY set	auth.resolve_provider (ambient short-circuit demoted below per-provider scan)	test_provider_resolution_cross_path
#8919	Custom provider config ignored at runtime; api_base dropped; OPENAI_BASE_URL silently consulted	config._normalize_model_api_base, runtime_provider, auxiliary_client (warn)	test_config_model_surface, test_clear_stale_base_url, test_auxiliary_custom_runtime_delegation
#12146	Runs fall back to OpenRouter despite provider=custom (alias-table drift)	provider_resolution.canonicalize_provider (single table), auth.py, models.py picker	test_provider_resolution (alias parity), test_auxiliary_named_custom_providers
#13489	ACP provider=custom resolves the wrong credential	acp_adapter/session.py threads explicit_base_url into resolution	test_session_explicit_base_url

⚠ Behavior changes

Most users unaffected — these matter only if you relied on env-based routing or incidental keys.

• OPENAI_BASE_URL no longer routes — ignored for routing, warned when set. [potentially breaking] → move it to model.base_url (or model.api_base) in config.yaml.
• Ambient OPENAI_API_KEY / OPENROUTER_API_KEY short-circuit moved below the per-provider scan. [breaking for incidental-key setups] a configured vendor key (e.g. DEEPSEEK_API_KEY) now wins; force OpenRouter with provider: openrouter.
• openai-api is skipped in auto-detect so a bare OPENAI_API_KEY still falls to the OpenRouter last-resort. [behavior change] → set provider: openai-api explicitly to use direct OpenAI.
• Declared custom provider with no resolvable base_url AND no usable key now raises AuthError(code="custom_provider_unresolved") instead of silently hitting openrouter.ai with an empty key. [breaking — now errors] → supply a base_url or key. The established key-present → OpenRouter fallback is unchanged.
• Bare custom/local base_url now gains exactly one /v1 (chat); anthropic endpoints never gain /v1. [low risk]

Back-compat

• ResolvedProvider supports dict-style reads (get / [] / in) and as_dict() stays byte-compatible with the legacy runtime dict — existing consumers untouched.
• model.api_base is a permanent accepted alias for model.base_url (folded at load).
• All explicit provider: values (openai-api, openrouter, anthropic, vendors) remain reachable.

Security

Preserves host-gated key selection from security advisory GHSA-76xc-57q6-vm5m — env keys only sent to matching hosts; lookalike/path-spoof hosts rejected. The new path-scoped api_mode detector additionally resists query/fragment spoofing the old full-URL detector allowed.

Design

• New leaf module hermes_cli/provider_resolution.py — pure, offline, import-light; the single source of truth.
• ResolvedProvider frozen value object resolved once per lifecycle and carried on the agent (provenance: base_url_source / key_source).
• Resolution memoized on args + config.yaml mtime/size + env fingerprint; only static sources cached — pool / OAuth / portal / process bypass so expiring credentials stay live.
• Fail-closed scoped exactly to "custom intent + no base_url + no usable key" (preserves the key-present fallback).
• api_mode detector / _parse_api_mode / VALID_API_MODES consolidated into the leaf (eliminates the 3 previously-divergent copies; locked by an identity test).

---

Resolves upstream:

• [Bug]: Model Switcher: Configuration Persistence Loss & Missing Pre-fills for Custom Endpoints #3263
• [Bug]: Custom OPENAI_BASE_URL drops /v1 on chat completions for OpenAI-compatible endpoints #4600
• [Bug]: Gateway and CLI ignore model.provider config — fall back to OpenRouter when OPENROUTER_API_KEY exists #5358
• Bug: custom provider config ignored at runtime #8919
• Agent runs fall back to openrouter despite model.provider=custom in config.yaml #12146
• fix(provider): ACP sessions with provider="custom" fail to resolve correct credential #13489

Closes #3263
Closes #4600
Closes #5358
Closes #8919
Closes #12146
Closes #13489
Supersedes #17072 — strict superset of its LM-Studio runtime slice, without its ~20k LOC of unrelated divergence and with full test coverage.

[teknium1]

Thanks for this, @banditburai — genuinely impressive scope and the writeup (per-issue root-cause table, provenance-tracked ResolvedProvider, offline memoization, the api_mode consolidation) is some of the most careful design analysis we've seen on a resolution PR. It's clear you traced the historical drift accurately.

Closing it, though, because the drift it targets has since been fixed piecemeal on current main, and adopting a 3353-line ground-up rewrite of the hottest, most security-sensitive path (provider/credential resolution) to re-solve already-solved problems isn't a trade we can make here. Two of the proposed behavior changes would also regress current behavior. Details, mapped to each issue you referenced:

#4600 — /v1 on custom chat endpoints — Already fixed. hermes_cli/runtime_provider.py does path-scoped /v1 handling: append for OpenAI-compatible chat (if not url.endswith("/v1"): url += "/v1"), strip for Anthropic-style endpoints, and special-case opencode-zen. Not the old full-URL detector.

#5358 — config model.provider ignored, falls to OpenRouter — Already fixed. resolve_provider() in hermes_cli/auth.py reads config.yaml model.provider (tier 2) above the ambient OPENROUTER_API_KEY/OPENAI_API_KEY short-circuit (tier 3). A configured provider wins over an incidental key.

#8919 — custom provider config ignored at runtime — Already closed. main has full custom-provider resolution in runtime_provider.py, provider-gated OPENAI_BASE_URL honoring (only when the active provider matches), and stale-OPENAI_BASE_URL clearing on provider switch (_clear_stale_base_url).

#12146 — falls to OpenRouter despite provider=custom (alias drift) — Already closed. main resolves bare/aliased custom through a dedicated path (incl. #27132 alias-to-custom and non-loopback-URL rejection).

#13489 — ACP provider=custom resolves wrong credential — Already fixed. acp_adapter/session.py threads the ACP-supplied base_url into resolution ("base_url": base_url or runtime.get("base_url")) and calls resolve_runtime_provider(requested=...) with the session provider — the exact threading your PR proposed.

#3263 — model-switcher persistence + custom-endpoint prefill — cmd_model in hermes_cli/main.py already handles switch persistence, a direct OpenAI-compatible base_url prompt (_prompt_direct_base_url), and config-field persistence.

Also: the "3 divergent api_mode copies" are already consolidated on main — a single _parse_api_mode + _VALID_API_MODES in runtime_provider.py.

Why the two behavior changes are regressions, not fixes:

• "Ignore OPENAI_BASE_URL for routing (warn only)" would throw away main's provider-gated honoring, which local vLLM / llama.cpp / self-hosted setups depend on.
• Re-ordering the ambient short-circuit and skipping openai-api in auto-detect re-litigates the deliberate Bug: auth.json active_provider silently overrides model.provider in config.yaml at runtime #29285 ordering (explicit intent > ambient key > stale OAuth, with transparency warnings).

Mechanically the branch is also ~3852 commits behind main, so the diff against current main is 3464 files / ~605k deletions — it would remove nearly everything merged in the interim. Not something we could cherry-pick as a unit even if the direction fit.

If you hit a specific resolution scenario that current main still gets wrong, please open a focused issue with the exact config/env + the wrong-vs-expected provider — a narrow fix on top of the current chain is very welcome. Appreciate the depth here.