runtime_provider.py 74 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206
  1. """Shared runtime provider resolution for CLI, gateway, cron, and helpers: the resolution ORDER
  2. (:func:`resolve_runtime_provider`), api_mode / base_url helpers and the pool / OAuth / explicit paths.
  3. Custom-provider lookup lives in :mod:`hermes_cli.runtime_provider_custom`; Azure Foundry,
  4. OpenRouter/bare-custom, Bedrock and external-process builders in
  5. :mod:`hermes_cli.runtime_provider_backends` — both re-exported here so
  6. ``hermes_cli.runtime_provider.<name>`` imports and test patches keep working."""
  7. from __future__ import annotations
  8. import copy
  9. import logging
  10. import re
  11. from contextlib import contextmanager
  12. from contextvars import ContextVar
  13. from dataclasses import dataclass
  14. from typing import Any, Callable, Dict, Optional
  15. logger = logging.getLogger(__name__)
  16. from hermes_cli import auth as auth_mod
  17. from agent.credential_pool import ( # custom_provider_pool_key_candidates is read via origin by runtime_provider_custom
  18. CredentialPool, PooledCredential, credential_pool_matches_provider, custom_provider_pool_key_candidates,
  19. load_pool,
  20. )
  21. from agent.secret_scope import get_secret_str
  22. from hermes_cli.auth import ( # resolve_external_process_provider_credentials is read via origin by runtime_provider_backends
  23. ACTUAL_LOCAL_NOAUTH_PLACEHOLDER, AuthError, DEFAULT_CODEX_BASE_URL, DEFAULT_QWEN_BASE_URL, DEFAULT_XAI_OAUTH_BASE_URL,
  24. PROVIDER_REGISTRY, _agent_key_is_usable, _nous_inference_env_override, _qwen_base_url, format_auth_error, resolve_provider,
  25. resolve_nous_runtime_credentials, resolve_codex_runtime_credentials, resolve_xai_oauth_runtime_credentials,
  26. resolve_qwen_runtime_credentials, resolve_api_key_provider_credentials,
  27. resolve_external_process_provider_credentials,
  28. has_usable_secret, is_actual_local_base_url, looks_like_openrouter_key, normalize_actual_base_url,
  29. )
  30. from hermes_cli import config as _config_mod
  31. from hermes_cli import models as _models # attribute access keeps ``hermes_cli.models.<name>`` patches effective
  32. from hermes_constants import OPENROUTER_BASE_URL
  33. from hermes_cli.providers import determine_api_mode, get_provider, is_actual_route, is_official_openai_host, nous_api_mode
  34. from utils import base_url_host_matches, base_url_hostname, base_url_path, env_int
  35. # A frozen session route's config (``frozen_runtime_config``); None = the live profile config.
  36. _FROZEN_RUNTIME_CONFIG: ContextVar[Optional[dict[str, Any]]] = ContextVar("_FROZEN_RUNTIME_CONFIG", default=None)
  37. @contextmanager
  38. def frozen_runtime_config(config: dict[str, Any]):
  39. """Resolve against a session's frozen config instead of the live config.yaml.
  40. Every rung reads its endpoint through ``load_config``/``_get_model_config``, so a frozen route's
  41. credential stays paired with the endpoint it was frozen with after a live ``model.base_url``
  42. edit (R2-M2). The auth store (credential pool) is not config and still refreshes/rotates.
  43. """
  44. merged = _config_mod._deep_merge(copy.deepcopy(_config_mod.DEFAULT_CONFIG), config)
  45. token = _FROZEN_RUNTIME_CONFIG.set(merged)
  46. try:
  47. yield
  48. finally:
  49. _FROZEN_RUNTIME_CONFIG.reset(token)
  50. _DEFER_TOKEN_MINT: ContextVar[bool] = ContextVar("_DEFER_TOKEN_MINT", default=False)
  51. @contextmanager
  52. def deferred_token_mint():
  53. """Resolve the route without exchanging short-lived OAuth tokens up front (Vertex today): the
  54. resolved ``api_key`` is a callable that mints on first use. For the gateway-backed classic
  55. CLI, whose gateway session mints its own token for every turn it runs."""
  56. token = _DEFER_TOKEN_MINT.set(True)
  57. try:
  58. yield
  59. finally:
  60. _DEFER_TOKEN_MINT.reset(token)
  61. # Late-bound delegates, deliberately NOT module-level from-imports: this module is often imported
  62. # lazily, so its first import can happen while a test has ``hermes_cli.config.load_config`` patched
  63. # — a from-import would bind the MagicMock permanently and poison every later caller.
  64. def load_config():
  65. frozen = _FROZEN_RUNTIME_CONFIG.get()
  66. return copy.deepcopy(frozen) if frozen is not None else _config_mod.load_config()
  67. def get_compatible_custom_providers(config=None):
  68. return _config_mod.get_compatible_custom_providers(config)
  69. def normalize_extra_headers(value):
  70. return _config_mod.normalize_extra_headers(value)
  71. def _loopback_hostname(host: str) -> bool:
  72. return (host or "").lower().rstrip(".") in {"localhost", "127.0.0.1", "::1", "0.0.0.0"}
  73. def _resolves_to_custom(name: str) -> bool:
  74. """True when a provider alias (ollama, vllm, llamacpp, …) resolves to ``custom``."""
  75. try:
  76. return auth_mod.resolve_provider(name) == "custom"
  77. except Exception:
  78. return False
  79. def _config_base_url_trustworthy_for_bare_custom(cfg_base_url: str, cfg_provider: str) -> bool:
  80. """Whether ``model.base_url`` may back bare ``custom`` runtime resolution. The picker can select
  81. Custom while ``model.provider`` still names a previous provider, so non-loopback URLs are rejected
  82. unless the YAML provider is already ``custom`` or a local-server alias (ollama/vllm/llamacpp —
  83. else a legit LAN ollama endpoint falls through to OpenRouter): a stale OpenRouter/Z.ai base_url
  84. cannot hijack local sessions.
  85. See #14676.
  86. """
  87. cfg_provider_norm = (cfg_provider or "").strip().lower()
  88. bu = (cfg_base_url or "").strip()
  89. # A bare or ``auto`` provider is the caller currently resolving auto. Asking
  90. # ``resolve_provider`` whether it aliases custom re-enters that same path.
  91. return bool(bu) and (cfg_provider_norm == "custom" or (
  92. cfg_provider_norm not in {"", "auto"} and _resolves_to_custom(cfg_provider_norm)
  93. )
  94. or (not base_url_host_matches(bu, "openrouter.ai") and _loopback_hostname(base_url_hostname(bu))))
  95. # ── api_mode detection ─────────────────────────────────────────────────────────────────────
  96. # Hosts that only speak one wire protocol. Mirrors host_mandated_api_mode in hermes_cli/providers.py
  97. # so the runtime resolver stays in lockstep: api.meta.ai — prompt caching only on Responses;
  98. # api.router.com — /v1/chat/completions is a minimal shim; api.anthropic.com — native Messages.
  99. _HOST_MANDATED_API_MODES = {
  100. "api.x.ai": "codex_responses", "api.meta.ai": "codex_responses", "api.actual.inc": "chat_completions",
  101. "api.router.com": "codex_responses", "api.anthropic.com": "anthropic_messages",
  102. }
  103. # codex_app_server is opt-in: hand the whole turn to a `codex app-server` subprocess (Codex's own
  104. # tool runtime), gated on `model.openai_runtime == "codex_app_server"` AND provider in {openai, openai-codex}.
  105. _VALID_API_MODES = {"chat_completions", "codex_responses", "anthropic_messages", "bedrock_converse", "codex_app_server"}
  106. def _detect_api_mode_for_url(base_url: str) -> Optional[str]:
  107. """Auto-detect api_mode from the resolved base URL, or None. Exact-hostname matches reject
  108. lookalike subdomains (api.anthropic.com.attacker.test) and path-segment spoofing
  109. (proxy.test/api.anthropic.com/v1). Official OpenAI hosts (incl. us./eu. data-residency hosts)
  110. need Responses for GPT-5.x tool calls with reasoning.
  111. - Direct api.anthropic.com endpoints must use the native Messages API (``/v1/messages``). Anthropic also
  112. exposes an OpenAI-compat ``/chat/completions`` shim on the same host, but Pro/Max OAuth subscriptions
  113. are only billed against the native Messages route; hitting the shim accounts against a separate "extra
  114. usage" pool that is empty by default and surfaces as HTTP 400 "You're out of extra usage." See issue
  115. #32243. - Third-party Anthropic-compatible gateways (MiniMax, Zhipu GLM, LiteLLM proxies, etc.)
  116. conventionally expose the native Anthropic protocol under a ``/anthropic`` suffix — treat those as
  117. ``anthropic_messages`` transport instead of the default ``chat_completions``. - Kimi Code's
  118. ``api.kimi.com/coding`` endpoint also speaks the Anthropic Messages protocol (the /coding route accepts
  119. Claude Code's native request shape).
  120. """
  121. normalized = (base_url or "").strip().lower().rstrip("/")
  122. hostname = base_url_hostname(base_url)
  123. mandated = _HOST_MANDATED_API_MODES.get(hostname) or ("codex_responses" if is_official_openai_host(base_url) else None)
  124. if mandated:
  125. return mandated
  126. path = base_url_path(normalized)
  127. if path.endswith(("/anthropic", "/anthropic/v1")) or (hostname == "api.kimi.com" and "/coding" in normalized):
  128. # Direct native Anthropic host: realign with providers.determine_api_mode, which already maps this
  129. # host to anthropic_messages. The exact-hostname match rejects lookalike subdomains
  130. # (api.anthropic.com.attacker.test) and path-segment spoofing (proxy.test/api.anthropic.com/v1).
  131. # (#32243)
  132. return "anthropic_messages"
  133. return None
  134. def _parse_api_mode(raw: Any) -> Optional[str]:
  135. """Validate an api_mode from config (None if invalid). Legacy/alias spellings (``openai``,
  136. ``anthropic``, ``responses``, …) are canonicalized first so old configs keep their transport
  137. instead of silently falling through to hostname-based detection. A mode with a registered
  138. transport (a provider plugin's own dialect) is valid too."""
  139. normalized = _config_mod._canonical_api_mode(raw).lower() if isinstance(raw, str) else ""
  140. if not normalized:
  141. return None
  142. from agent.transports import registered_api_modes
  143. return normalized if normalized in _VALID_API_MODES or normalized in registered_api_modes() else None
  144. def _fallback_api_mode(provider: str, base_url: str, model: str = "") -> str:
  145. """api_mode when no explicit/persisted mode applies: URL detection (host-mandated wire shapes)
  146. first, then the transport the provider overlay declares via ``providers.determine_api_mode``
  147. (``openai-api`` pointed at us.api.openai.com 400'd on every tool call without it), then
  148. ``chat_completions``. A declared ``anthropic_messages`` is kept only on the provider's own
  149. endpoint (#76836)."""
  150. if is_actual_route(provider, base_url):
  151. return "chat_completions"
  152. detected = _detect_api_mode_for_url(base_url)
  153. if detected:
  154. return detected
  155. declared = determine_api_mode(provider, base_url, model)
  156. if declared == "anthropic_messages" and not _on_declared_anthropic_endpoint(provider, base_url):
  157. # The declared Anthropic transport describes the provider's own endpoint. A base_url
  158. # override at a foreign host (OpenAI-compatible relay, LiteLLM, egress proxy) or at the
  159. # provider's OpenAI-compatible path (api.minimax.io/v1) speaks chat/completions; sending
  160. # Messages-shaped requests with x-api-key there is a 401 on every turn (#76836).
  161. return "chat_completions"
  162. return declared
  163. def _on_declared_anthropic_endpoint(provider: str, base_url: str) -> bool:
  164. """True when ``base_url`` is the provider's own Anthropic-protocol endpoint: the catalog
  165. default's host (or a subdomain of it) and either the bare host — the provider's own host
  166. with no path still means the native endpoint (#53054) — or the default's path
  167. (``/anthropic`` for MiniMax, ``/plan/anthropic`` for Tencent) with or without a ``/v1``
  168. tail. With nothing to compare — no URL, an overlay-only provider whose models.dev default
  169. is not cached (offline), or a default with no path at all (``api.anthropic.com``: no sibling
  170. OpenAI-compatible path exists to tell an override's protocol from) — keep the declared
  171. transport: demoting the provider's own endpoint would be the worse failure."""
  172. pdef = get_provider(provider, allow_network=False)
  173. default = (pdef.base_url if pdef else "").strip()
  174. default_path = base_url_path(default).removesuffix("/v1")
  175. if not default_path or not (base_url or "").strip():
  176. return True
  177. if not base_url_host_matches(base_url, base_url_hostname(default)):
  178. return False
  179. path = base_url_path(base_url)
  180. return path == "" or path == default_path or path.startswith(default_path + "/")
  181. def _resolve_plain_custom_api_mode(model_cfg: dict[str, Any], base_url: str) -> str:
  182. """api_mode for legacy/plain ``provider: custom`` endpoints — conservative by default: only
  183. direct OpenAI/xAI/Meta URLs imply Responses; named custom providers opt in via ``api_mode``."""
  184. if is_actual_route(base_url=base_url):
  185. return "chat_completions"
  186. configured_mode = _parse_api_mode(model_cfg.get("api_mode"))
  187. detected_mode = _detect_api_mode_for_url(base_url)
  188. if configured_mode == "codex_responses" and detected_mode != "codex_responses":
  189. logger.info("Ignoring persisted custom api_mode=codex_responses for non-OpenAI endpoint %s", base_url or "(unknown)")
  190. configured_mode = None
  191. return configured_mode or detected_mode or "chat_completions"
  192. def _same_registered_provider(provider: str, configured_provider: str) -> bool:
  193. """Profile aliases share an auth registry ID; unrelated routes must stay distinct."""
  194. if provider == configured_provider:
  195. return True
  196. pconfig = PROVIDER_REGISTRY.get(provider)
  197. configured = PROVIDER_REGISTRY.get(configured_provider)
  198. return bool(pconfig and configured and pconfig.id == configured.id)
  199. def _provider_supports_explicit_api_mode(provider: Optional[str], configured_provider: Optional[str] = None) -> bool:
  200. """Whether a persisted api_mode may be honored for ``provider`` — only when the config's
  201. provider matches (or none is recorded), so a stale mode never leaks across a switch."""
  202. p, c = (provider or "").strip().lower(), (configured_provider or "").strip().lower()
  203. return not c or (c == "custom" or c.startswith("custom:") if p == "custom" else _same_registered_provider(p, c))
  204. def _configured_api_mode(provider: str, model_cfg: dict[str, Any]) -> Optional[str]:
  205. """Persisted ``model.api_mode`` when valid and recorded for this provider, else None."""
  206. configured_mode = _parse_api_mode(model_cfg.get("api_mode"))
  207. return configured_mode if configured_mode and _provider_supports_explicit_api_mode(provider, _cfg_provider(model_cfg)) else None
  208. def _effective_model(model_cfg: dict[str, Any], target_model: Optional[str]) -> str:
  209. """The caller's target model (e.g. /model switch) beats the persisted default, else api_mode
  210. is computed from a stale default."""
  211. return target_model or model_cfg.get("default") or ""
  212. def _per_model_profile(provider: str) -> Any:
  213. """The provider's profile when it routes ``api_mode`` per model (``ProviderProfile.api_mode_for_model``)."""
  214. from providers import get_provider_profile
  215. from providers.base import ProviderProfile
  216. profile = get_provider_profile(provider) if provider else None
  217. if profile is None or type(profile).api_mode_for_model is ProviderProfile.api_mode_for_model:
  218. return None
  219. return profile
  220. def _profile_runtime_api_mode(provider: str, model_cfg: dict[str, Any], api_key: str, *,
  221. target_model: Optional[str] = None) -> str:
  222. """api_mode for a provider that routes per model: its hard per-model wire wins over a stale persisted
  223. ``codex_responses`` (pure check, no network); otherwise the profile decides with the live key."""
  224. from agent.provider_route_hooks import model_api_mode
  225. profile = _per_model_profile(provider)
  226. configured_mode = _configured_api_mode(provider, model_cfg)
  227. # Use the model being resolved, not the persisted default: a Claude MoA slot inheriting
  228. # codex_responses from a GPT-5 default fails with "model ... does not support Responses API".
  229. model_name = str(_effective_model(model_cfg, target_model)).strip()
  230. if configured_mode:
  231. # A stale explicit ``codex_responses`` (written by setup for the model first picked, kept after a
  232. # switch to a chat-only model) must not override the provider's per-model requirement: the
  233. # Responses request silently succeeds but returns no reasoning content (#46527).
  234. if (configured_mode == "codex_responses" and model_name and profile is not None
  235. and model_api_mode(profile, model_name) == "chat_completions"):
  236. return "chat_completions"
  237. return configured_mode
  238. if profile is None:
  239. return "chat_completions"
  240. declared = profile.api_mode or "chat_completions" # the hook's None means "keep the static api_mode"
  241. return (model_api_mode(profile, model_name, api_key=api_key) or declared) if model_name else declared
  242. def _azure_inferred_api_mode(effective_model: str, api_mode: str) -> str:
  243. """Upgrade api_mode for GPT-5.x / codex / o1-o4 deployments on Azure Foundry (Azure 400s
  244. /chat/completions on these). Skipped when the user explicitly picked anthropic_messages."""
  245. if not effective_model or api_mode == "anthropic_messages":
  246. return api_mode
  247. try:
  248. return _models.azure_foundry_model_api_mode(effective_model) or api_mode
  249. except Exception:
  250. return api_mode
  251. def _configured_or_fallback_api_mode(provider: str, model_cfg: dict[str, Any], base_url: str, effective_model: Any, *,
  252. opencode_by_model: bool) -> str:
  253. """Persisted ``model.api_mode`` when it belongs to this provider, else URL/transport fallback.
  254. OpenCode Zen/Go serve both anthropic_messages and chat_completions models, so (when
  255. ``opencode_by_model``) their mode is always re-derived from the effective model."""
  256. if provider == "actual":
  257. configured_mode = _configured_api_mode(provider, model_cfg)
  258. if configured_mode and configured_mode != "chat_completions":
  259. logger.info("Routing built-in Actual through chat_completions instead of persisted api_mode=%s", configured_mode)
  260. return "chat_completions"
  261. if opencode_by_model and _models.opencode_provider_family(provider) is not None:
  262. return _models.opencode_model_api_mode(provider, effective_model)
  263. return _configured_api_mode(provider, model_cfg) or _fallback_api_mode(provider, base_url, effective_model)
  264. def _api_key_provider_api_mode(provider: str, model_cfg: dict[str, Any], api_key: str, base_url: str, effective_model: Any, *,
  265. opencode_by_model: bool) -> str:
  266. """api_mode for a registry ``api_key`` provider (explicit and env/config paths)."""
  267. if _per_model_profile(provider) is not None:
  268. return _profile_runtime_api_mode(provider, model_cfg, api_key, target_model=effective_model)
  269. if provider == "xai":
  270. # Ramp Router: Responses-native host — /v1/chat/completions is only a minimal compatibility shim,
  271. # while reasoning and caching support live on /v1/responses (docs.router.com/api/endpoint). Mirrors
  272. # the host_mandated_api_mode clause in hermes_cli/providers.py so the runtime resolver stays in
  273. # lockstep. Exact hostname per #32243.
  274. return "codex_responses"
  275. return _configured_or_fallback_api_mode(provider, model_cfg, base_url, effective_model, opencode_by_model=opencode_by_model)
  276. def _maybe_apply_codex_app_server_runtime(*, provider: str, api_mode: str, model_cfg: Optional[dict[str, Any]],
  277. requested_provider: str = "") -> str:
  278. """Opt-in rewrite to "codex_app_server" via ``model.openai_runtime``. Eligible: ``openai`` /
  279. ``openai-codex``, and a configured named custom provider (``providers.<name>``) whose id codex
  280. looks up in its own ``[model_providers.<name>]`` table (#75186). Anonymous ``custom`` has no
  281. stable id and stays ineligible. No-op when unset, "auto", or empty. Applied once, on the
  282. runtime ``resolve_runtime_provider`` picked — never inside an individual ladder rung."""
  283. if not model_cfg or str(model_cfg.get("openai_runtime") or "").strip().lower() != "codex_app_server":
  284. return api_mode
  285. if provider in {"openai", "openai-codex"} or requested_provider in {"openai", "openai-codex"} \
  286. or (provider == "custom" and codex_model_provider_id(requested_provider)):
  287. return "codex_app_server"
  288. return api_mode
  289. # ── base_url / credential helpers ──────────────────────────────────────────────────────────
  290. _ANTHROPIC_DEFAULT_BASE_URL = "https://api.anthropic.com"
  291. _NO_ANTHROPIC_CREDENTIALS_MSG = ("No Anthropic credentials found. Run 'hermes auth add anthropic' to sign in, "
  292. "or set ANTHROPIC_TOKEN / ANTHROPIC_API_KEY.")
  293. def _runtime(provider: str, api_mode: str, base_url: Any, api_key: Any, **extra: Any) -> dict[str, Any]:
  294. """Build a resolved-runtime dict; ``extra`` carries source/requested_provider/provider-specific keys."""
  295. if is_actual_route(provider, base_url):
  296. api_mode = "chat_completions"
  297. base_url = normalize_actual_base_url(base_url)
  298. return {"provider": provider, "api_mode": api_mode, "base_url": base_url, "api_key": api_key, **extra}
  299. def _cfg_provider(model_cfg: dict[str, Any]) -> str:
  300. return str(model_cfg.get("provider") or "").strip().lower()
  301. def _config_base_url_for_provider(model_cfg: dict[str, Any], provider: str) -> str:
  302. """``model.base_url`` (stripped, no trailing slash) only when ``model.provider`` is
  303. ``provider`` — a stale base_url must not leak into another provider."""
  304. configured_provider = _cfg_provider(model_cfg)
  305. if provider == "actual":
  306. configured_provider = _models.normalize_provider(configured_provider)
  307. return str(model_cfg.get("base_url") or "").strip().rstrip("/") if _same_registered_provider(provider, configured_provider) else ""
  308. def is_foreign_provider_endpoint(provider: Optional[str], base_url: Optional[str]) -> bool:
  309. """True when ``base_url`` is another built-in provider's canonical endpoint, not ``provider``'s.
  310. A persisted session route that pairs one provider with another's endpoint is left over from a
  311. switch that kept the old URL (openai-codex + the Nous Portal URL sent the Codex slug to the Portal).
  312. Only registered providers are judged: a custom or proxy URL is never another provider's canonical one.
  313. """
  314. pconfig = PROVIDER_REGISTRY.get(str(provider or "").strip().lower())
  315. url = str(base_url or "").strip().rstrip("/")
  316. if pconfig is None or not url or url == (pconfig.inference_base_url or "").rstrip("/"):
  317. return False
  318. return any(url == (other.inference_base_url or "").rstrip("/") for other in PROVIDER_REGISTRY.values())
  319. def _anthropic_base_url_override_ok(base_url: str) -> bool:
  320. """Whether a configured ``model.base_url`` plausibly speaks the Anthropic Messages protocol:
  321. official Anthropic/Claude hosts, Azure Foundry, or ``/anthropic`` / Kimi ``/coding`` proxies
  322. (the same signal :func:`_detect_api_mode_for_url` uses). Otherwise the caller falls back to
  323. ``https://api.anthropic.com`` so a stale non-Anthropic URL cannot hijack native Anthropic."""
  324. candidate = (base_url or "").strip()
  325. hostname = (base_url_hostname(candidate) or "").lower() if candidate else ""
  326. return bool(hostname) and (hostname == "api.anthropic.com" or hostname.endswith((".anthropic.com", ".claude.com", ".azure.com"))
  327. or _detect_api_mode_for_url(candidate) == "anthropic_messages")
  328. def _anthropic_cfg_base_url(model_cfg: dict[str, Any]) -> str:
  329. """Config base_url for native Anthropic, or "" when absent/untrustworthy."""
  330. cfg_base_url = _config_base_url_for_provider(model_cfg, "anthropic")
  331. return cfg_base_url if _anthropic_base_url_override_ok(cfg_base_url) else ""
  332. def _anthropic_token_or_raise(*, model: str | None = None) -> str:
  333. from agent.anthropic_credentials import resolve_anthropic_token
  334. token = resolve_anthropic_token(model=model)
  335. if not token:
  336. # A key the pool benched for *this* model is not a missing credential; telling the
  337. # user to re-authenticate would send them chasing a cooldown that lifts on its own.
  338. if model and resolve_anthropic_token():
  339. raise AuthError(f"Anthropic credentials are rate-limited for {model}; "
  340. "other Claude models remain available (see `hermes auth list`).")
  341. raise AuthError(_NO_ANTHROPIC_CREDENTIALS_MSG)
  342. return token
  343. def _host_derived_api_key(base_url: str) -> str:
  344. """``<VENDOR>_API_KEY`` from the env, vendor = registrable hostname label (``api.deepseek.com``
  345. → ``deepseek``). Lookalike hosts pick the ATTACKER's label (api.deepseek.com.attacker.test →
  346. "attacker") so DEEPSEEK_API_KEY stays put. "" for IPs/loopback/single-label hosts and for
  347. OPENAI/OPENROUTER/OLLAMA, which have their own host-gated paths."""
  348. hostname = base_url_hostname(base_url)
  349. if not hostname or any(ch.isdigit() for ch in hostname.split(".")[-1]) or hostname == "localhost" or ":" in hostname:
  350. return ""
  351. labels = [lbl for lbl in hostname.split(".") if lbl]
  352. while labels and labels[0] in ("api", "www"):
  353. labels.pop(0)
  354. sanitized = "".join(ch if ch.isalnum() else "_" for ch in labels[-2]).upper() if len(labels) >= 2 else ""
  355. if not sanitized or not sanitized[0].isalpha() or sanitized in ("OPENAI", "OPENROUTER", "OLLAMA"):
  356. return ""
  357. return (get_secret_str(f"{sanitized}_API_KEY", "") or "").strip()
  358. def _host_gated_env_key_candidates(base_url: str, *, ollama: bool) -> list:
  359. """Env API keys gated on their authoritative hosts, then the host-derived ``<VENDOR>_API_KEY``.
  360. Sending OPENAI/OPENROUTER/OLLAMA keys to an unrelated endpoint leaks credentials
  361. (GHSA-76xc-57q6-vm5m); match on HOST, not substring. ``_host_derived_api_key`` skips OLLAMA, so
  362. callers that want it opt in via ``ollama``."""
  363. is_openai = base_url_host_matches(base_url, "openai.com") or base_url_host_matches(base_url, "openai.azure.com")
  364. # OPENAI_BASE_URL names the proxy/gateway the OPENAI_API_KEY was issued for (the ``openai`` alias
  365. # expands onto it); an exact match is the user's own pairing, not a leak to an unrelated host.
  366. env_openai_base = get_secret_str("OPENAI_BASE_URL", "").strip().rstrip("/")
  367. is_openai = is_openai or (bool(env_openai_base) and (base_url or "").strip().rstrip("/") == env_openai_base)
  368. candidates = [get_secret_str("OLLAMA_API_KEY", "").strip() if base_url_host_matches(base_url, "ollama.com") else ""] if ollama else []
  369. return candidates + [get_secret_str("OPENAI_API_KEY", "").strip() if is_openai else "",
  370. get_secret_str("OPENROUTER_API_KEY", "").strip() if base_url_host_matches(base_url, "openrouter.ai") else "",
  371. _host_derived_api_key(base_url)]
  372. def _pool_entry_api_key(entry: Any) -> str:
  373. return getattr(entry, "runtime_api_key", None) or getattr(entry, "access_token", "")
  374. def _pool_entry_base_url(entry: Any) -> str:
  375. return getattr(entry, "runtime_base_url", None) or getattr(entry, "base_url", None) or ""
  376. def _nous_entry_key_usable(entry: Any, min_ttl: int) -> bool:
  377. return _agent_key_is_usable({k: getattr(entry, k, None) for k in ("agent_key", "agent_key_expires_at", "scope")}, min_ttl)
  378. def _nous_min_key_ttl() -> int:
  379. return max(60, env_int("HERMES_NOUS_MIN_KEY_TTL_SECONDS", 1800))
  380. def _resolve_nous_creds() -> dict[str, Any]:
  381. return resolve_nous_runtime_credentials(timeout_seconds=float(get_secret_str("HERMES_NOUS_TIMEOUT_SECONDS", "15")))
  382. def _finalize_base_url(provider: str, api_mode: str, base_url: str) -> str:
  383. """Shared tail for pool-entry and api-key paths: OpenCode /v1 rule (OpenCode URLs end with /v1
  384. for OpenAI-compatible models but the Anthropic SDK prepends its own /v1/messages — strip for
  385. anthropic_messages, re-append otherwise), then LM Studio normalization."""
  386. if _models.opencode_provider_family(provider) is not None:
  387. base_url = _models.normalize_opencode_base_url(provider, api_mode, base_url)
  388. if provider == "lmstudio":
  389. base_url = auth_mod._normalize_lmstudio_runtime_base_url(base_url)
  390. if provider == "actual":
  391. base_url = normalize_actual_base_url(base_url)
  392. return base_url
  393. # ── model config ───────────────────────────────────────────────────────────────────────────
  394. def _auto_detect_local_model(base_url: str) -> str:
  395. """Query a local server for its model name when only one model is loaded."""
  396. if not base_url:
  397. return ""
  398. try:
  399. import requests
  400. url = base_url.rstrip("/")
  401. resp = requests.get((url if url.endswith("/v1") else url + "/v1") + "/models", timeout=(2, 3))
  402. if resp.ok:
  403. models = resp.json().get("data", [])
  404. if len(models) == 1 and models[0].get("id", ""):
  405. return models[0]["id"]
  406. except Exception as exc:
  407. logger.debug("Auto-detect model from %s failed: %s", base_url, exc)
  408. return ""
  409. def _get_model_config() -> dict[str, Any]:
  410. """``model`` config section with ``model`` accepted as an alias for ``default``, a dict
  411. ``default`` split into model/provider, and a local single-model server auto-detected."""
  412. config = load_config()
  413. model_cfg = config.get("model")
  414. if isinstance(model_cfg, str) and model_cfg.strip():
  415. return {"default": model_cfg.strip()}
  416. if not isinstance(model_cfg, dict):
  417. return {}
  418. cfg = dict(model_cfg)
  419. if not cfg.get("default") and cfg.get("model"):
  420. cfg["default"] = cfg["model"]
  421. _default = cfg.get("default")
  422. if isinstance(_default, dict):
  423. cfg_model, cfg_provider = _config_mod.split_model_config_default(_default)
  424. cfg_provider = cfg_provider or str(model_cfg.get("provider") or "")
  425. cfg["default"] = cfg_model
  426. if cfg_provider and not cfg.get("provider"):
  427. cfg["provider"] = cfg_provider
  428. _default = cfg_model
  429. base_url = (cfg.get("base_url") or "").strip()
  430. if not str(_default or "").strip() and base_url and base_url_hostname(base_url) in ("localhost", "127.0.0.1"):
  431. detected = _auto_detect_local_model(base_url)
  432. if detected:
  433. cfg["default"] = detected
  434. return cfg
  435. def resolve_requested_provider(requested: Optional[str] = None) -> str:
  436. """Provider request from explicit arg, then config, then ``HERMES_INFERENCE_PROVIDER``, else
  437. "auto". Config beats the env so chat uses the endpoint the user last saved, not a stale
  438. shell/.env override."""
  439. if requested and requested.strip():
  440. return requested.strip().lower()
  441. cfg_provider = _get_model_config().get("provider")
  442. if isinstance(cfg_provider, str) and cfg_provider.strip():
  443. return cfg_provider.strip().lower()
  444. from agent.session_client_env import bound_client_env
  445. client = bound_client_env() # a local session's turn: its client's export, never the daemon's
  446. requested = client.get("HERMES_INFERENCE_PROVIDER", "") if client is not None else get_secret_str("HERMES_INFERENCE_PROVIDER", "")
  447. return requested.strip().lower() or "auto"
  448. # ── extracted collaborators (re-exported; see module docstring) ────────────────────────────
  449. from hermes_cli.runtime_provider_custom import (
  450. _LLAMACPP_ALIASES, _apply_custom_provider_extras, _custom_provider_request_overrides, _filter_capabilities, _find_custom_identity,
  451. _get_named_custom_provider, _lift_common_custom_fields, _lift_extra_headers,
  452. _lift_model_capabilities, _normalize_base_url_for_match, _normalize_custom_provider_name, _resolve_named_custom_runtime,
  453. _try_resolve_from_custom_pool, canonical_custom_identity, codex_model_provider_id, expand_direct_api_alias,
  454. find_custom_provider_identity,
  455. find_custom_provider_identity_by_model, has_named_custom_provider, is_routable_provider,
  456. )
  457. from hermes_cli.runtime_provider_backends import (
  458. _is_external_process_provider, _resolve_azure_foundry_runtime, _resolve_bedrock_runtime,
  459. _resolve_external_process_runtime, _resolve_openrouter_runtime,
  460. )
  461. # ── credential-pool entries ────────────────────────────────────────────────────────────────
  462. # Pool-entry providers whose api_mode is fixed: provider -> (api_mode, default base_url when the
  463. # pool entry carries none). Callables are evaluated lazily (registry lookups). MiniMax OAuth tokens
  464. # are valid only against the Anthropic Messages endpoint, so a stale model.api_mode from a prior
  465. # OpenAI-compatible provider is never honoured for it (it would 404 on /chat/completions).
  466. _POOL_ENTRY_SIMPLE_MODES: dict[str, tuple] = {
  467. "openai-codex": ("codex_responses", DEFAULT_CODEX_BASE_URL), "xai-oauth": ("codex_responses", DEFAULT_XAI_OAUTH_BASE_URL),
  468. "qwen-oauth": ("chat_completions", DEFAULT_QWEN_BASE_URL), "openrouter": ("chat_completions", OPENROUTER_BASE_URL),
  469. "minimax-oauth": ("anthropic_messages", lambda: getattr(PROVIDER_REGISTRY.get("minimax-oauth"), "inference_base_url", "")),
  470. "xai": ("codex_responses", ""),
  471. }
  472. def _pool_entry_mode_and_url(provider, entry, model_cfg, effective_model, base_url) -> tuple:
  473. """(api_mode, base_url) for a pool entry of ``provider``."""
  474. if provider == "actual" and str(getattr(entry, "source", "")).startswith("env:"):
  475. base_url = _config_base_url_for_provider(model_cfg, provider) or base_url
  476. if provider in _POOL_ENTRY_SIMPLE_MODES:
  477. api_mode, default_url = _POOL_ENTRY_SIMPLE_MODES[provider]
  478. if provider == "openai-codex":
  479. # Pool entries retain the canonical ChatGPT URL, but the profile-wide
  480. # HERMES_CODEX_BASE_URL override must apply consistently to every
  481. # credential source, including pooled OAuth credentials.
  482. override_url = get_secret_str("HERMES_CODEX_BASE_URL", "").strip().rstrip("/")
  483. if override_url:
  484. return api_mode, override_url
  485. # model.base_url is the secondary proxy override (same rule as the generic tail below:
  486. # only when the pool row still carries the canonical URL).
  487. if base_url in ("", default_url):
  488. base_url = _config_base_url_for_provider(model_cfg, provider) or base_url
  489. if provider == "xai":
  490. # Env-seeded rows keep the registry host. model.base_url is the relay
  491. # override, and only while the row is still that host — an explicit
  492. # per-credential endpoint stays authoritative (#121347).
  493. canonical = (PROVIDER_REGISTRY["xai"].inference_base_url or "").rstrip("/")
  494. if base_url.rstrip("/") in ("", canonical):
  495. base_url = _config_base_url_for_provider(model_cfg, provider) or base_url
  496. return api_mode, base_url or (default_url() if callable(default_url) else default_url)
  497. if provider == "anthropic":
  498. return "anthropic_messages", _anthropic_cfg_base_url(model_cfg) or base_url or _ANTHROPIC_DEFAULT_BASE_URL
  499. if provider == "nous":
  500. return nous_api_mode(effective_model), (_nous_inference_env_override() or "") or base_url
  501. if _per_model_profile(provider) is not None:
  502. api_mode = _profile_runtime_api_mode(provider, model_cfg, getattr(entry, "runtime_api_key", ""),
  503. target_model=effective_model)
  504. return api_mode, base_url or PROVIDER_REGISTRY[provider].inference_base_url
  505. if provider == "azure-foundry":
  506. api_mode = "chat_completions"
  507. if _cfg_provider(model_cfg) == "azure-foundry":
  508. base_url = _config_base_url_for_provider(model_cfg, "azure-foundry") or base_url
  509. api_mode = _parse_api_mode(model_cfg.get("api_mode")) or api_mode
  510. api_mode = _azure_inferred_api_mode(effective_model, api_mode)
  511. return api_mode, (re.sub(r"/v1/?$", "", base_url) if api_mode == "anthropic_messages" else base_url)
  512. # Missing and registry-default endpoints may use this provider's configured URL.
  513. # An explicit per-credential endpoint remains authoritative.
  514. pconfig = PROVIDER_REGISTRY.get(provider)
  515. if pconfig and (not base_url or base_url.rstrip("/") == pconfig.inference_base_url.rstrip("/")):
  516. base_url = _config_base_url_for_provider(model_cfg, provider) or base_url or pconfig.inference_base_url
  517. return _configured_or_fallback_api_mode(provider, model_cfg, base_url, effective_model, opencode_by_model=True), base_url
  518. def _resolve_runtime_from_pool_entry(*, provider: str, entry: PooledCredential, requested_provider: str,
  519. model_cfg: Optional[dict[str, Any]] = None, pool: Optional[CredentialPool] = None,
  520. target_model: Optional[str] = None) -> dict[str, Any]:
  521. model_cfg = model_cfg or _get_model_config()
  522. api_mode, base_url = _pool_entry_mode_and_url(provider, entry, model_cfg, _effective_model(model_cfg, target_model),
  523. _pool_entry_base_url(entry).rstrip("/"))
  524. base_url = _finalize_base_url(provider, api_mode, base_url)
  525. return _runtime(provider, api_mode, base_url, _pool_entry_api_key(entry), source=getattr(entry, "source", "pool"),
  526. credential_pool=pool, requested_provider=requested_provider)
  527. def _openrouter_should_use_pool(requested_provider, model_cfg, explicit_api_key, explicit_base_url) -> bool:
  528. """OpenRouter pool only for a plain openrouter/auto request with no custom endpoint or override."""
  529. cfg_base_url = str(model_cfg.get("base_url") or "").strip()
  530. env_base_urls = get_secret_str("OPENAI_BASE_URL", "").strip() or get_secret_str("OPENROUTER_BASE_URL", "").strip()
  531. # A config base_url under provider: openrouter is a mirror only when it is NOT the canonical
  532. # OpenRouter host — `hermes setup` persists https://openrouter.ai/api/v1 for plain installs,
  533. # and treating that as custom would drop the auth.json pool (empty key).
  534. cfg_is_mirror = bool(cfg_base_url) and (
  535. _cfg_provider(model_cfg) in {"auto", "custom"}
  536. or (_cfg_provider(model_cfg) == "openrouter" and not base_url_host_matches(cfg_base_url, "openrouter.ai"))
  537. )
  538. has_custom_endpoint = bool(explicit_base_url or env_base_urls or cfg_is_mirror)
  539. return requested_provider in {"openrouter", "auto"} and not has_custom_endpoint and not bool(explicit_api_key or explicit_base_url)
  540. def _refresh_nous_pool_entry(pool: CredentialPool, entry: Any, pool_api_key: str):
  541. """Nous pool entries carry the agent_key (an invoke JWT) which the pool does not refresh on
  542. selection (avoids network calls in `hermes auth list`); refresh here before falling back to
  543. singleton auth resolution. Returns (entry, pool_api_key) — key "" when still unusable."""
  544. min_ttl = _nous_min_key_ttl()
  545. if _nous_entry_key_usable(entry, min_ttl):
  546. return entry, pool_api_key
  547. logger.debug("Nous pool entry agent_key expired/missing, refreshing selected pool entry")
  548. try:
  549. refreshed = pool.try_refresh_current()
  550. except Exception as exc:
  551. logger.debug("Nous pool entry refresh failed: %s", exc)
  552. refreshed = None
  553. if refreshed is not None:
  554. entry, pool_api_key = refreshed, _pool_entry_api_key(refreshed)
  555. if not pool_api_key or not _nous_entry_key_usable(entry, min_ttl):
  556. logger.debug("Nous pool entry agent_key still unavailable, falling through to runtime resolution")
  557. pool_api_key = ""
  558. return entry, pool_api_key
  559. def _resolve_from_pool(provider: str, requested_provider: str, model_cfg: dict[str, Any], explicit_api_key, explicit_base_url,
  560. target_model) -> Optional[dict[str, Any]]:
  561. """Runtime from the provider's credential pool, or None to continue down the ladder."""
  562. should_use_pool = provider != "openrouter" or _openrouter_should_use_pool(requested_provider, model_cfg, explicit_api_key,
  563. explicit_base_url)
  564. try:
  565. pool = load_pool(provider) if should_use_pool else None
  566. except Exception:
  567. pool = None
  568. if not (pool and pool.has_credentials()):
  569. return None
  570. entry = pool.select(model=target_model or None)
  571. if entry is None:
  572. return None
  573. pool_api_key = _pool_entry_api_key(entry)
  574. if provider == "nous":
  575. entry, pool_api_key = _refresh_nous_pool_entry(pool, entry, pool_api_key)
  576. else:
  577. from providers import get_provider_profile
  578. if (profile := get_provider_profile(provider)) is not None:
  579. pool_api_key = profile.prepare_pool_entry(entry, pool_api_key)
  580. if not has_usable_secret(pool_api_key):
  581. return None
  582. if pool_api_key and credential_pool_matches_provider(pool, provider, base_url=_pool_entry_base_url(entry)):
  583. return _resolve_runtime_from_pool_entry(provider=provider, entry=entry, requested_provider=requested_provider,
  584. model_cfg=model_cfg, pool=pool, target_model=target_model)
  585. return None
  586. # ── explicit (--api-key / --base-url) path ─────────────────────────────────────────────────
  587. def _explicit_anthropic(requested_provider, model_cfg, api_key, base_url, target_model):
  588. base_url = base_url or _anthropic_cfg_base_url(model_cfg) or _ANTHROPIC_DEFAULT_BASE_URL
  589. api_key = api_key or _anthropic_token_or_raise(model=target_model)
  590. return _runtime("anthropic", "anthropic_messages", base_url, api_key, source="explicit", requested_provider=requested_provider)
  591. def _creds_fallback(api_key, explicit_base_url, base_url, expiry, expiry_key, resolve):
  592. """When no explicit key was given, take api_key / expiry / base_url from stored credentials
  593. (an explicit --base-url still wins over the stored one)."""
  594. if api_key:
  595. return api_key, base_url, expiry
  596. creds = resolve()
  597. return creds.get("api_key", ""), explicit_base_url or creds.get("base_url", "").rstrip("/") or base_url, creds.get(expiry_key)
  598. def _explicit_codex(requested_provider, model_cfg, api_key, explicit_base_url, target_model):
  599. api_key, base_url, last_refresh = _creds_fallback(api_key, explicit_base_url, explicit_base_url or DEFAULT_CODEX_BASE_URL,
  600. None, "last_refresh", resolve_codex_runtime_credentials)
  601. return _runtime("openai-codex", "codex_responses", base_url, api_key, source="explicit", last_refresh=last_refresh,
  602. requested_provider=requested_provider)
  603. def _explicit_qwen(requested_provider, model_cfg, api_key, explicit_base_url, target_model):
  604. # A supplied token is the credential: the Qwen CLI login is read only when none was given.
  605. api_key, base_url, expires_at_ms = _creds_fallback(api_key, explicit_base_url, explicit_base_url or _qwen_base_url(),
  606. None, "expires_at_ms", resolve_qwen_runtime_credentials)
  607. return _runtime("qwen-oauth", "chat_completions", base_url, api_key, source="explicit", expires_at_ms=expires_at_ms,
  608. requested_provider=requested_provider)
  609. def _explicit_nous(requested_provider, model_cfg, api_key, explicit_base_url, target_model):
  610. state = auth_mod.get_provider_auth_state("nous") or {}
  611. base_url = (explicit_base_url or _nous_inference_env_override()
  612. or str(state.get("inference_base_url") or auth_mod.DEFAULT_NOUS_INFERENCE_URL).strip().rstrip("/"))
  613. # The agent_key compatibility field is used for inference only when it holds a NAS invoke JWT;
  614. # raw OAuth access_token fallback is handled by resolve_nous_runtime_credentials().
  615. api_key = api_key or (str(state.get("agent_key") or "").strip() if _agent_key_is_usable(state, _nous_min_key_ttl()) else "")
  616. api_key, base_url, expires_at = _creds_fallback(api_key, explicit_base_url, base_url,
  617. state.get("agent_key_expires_at") or state.get("expires_at"), "expires_at",
  618. _resolve_nous_creds)
  619. return _runtime("nous", nous_api_mode(_effective_model(model_cfg, target_model)), base_url, api_key, source="explicit",
  620. expires_at=expires_at, requested_provider=requested_provider)
  621. def _actual_local_key(provider: str, api_key: str, base_url: str) -> str:
  622. """Actual Computer's loopback daemon speaks a no-auth local API — substitute the placeholder key."""
  623. return ACTUAL_LOCAL_NOAUTH_PLACEHOLDER if provider == "actual" and not api_key and is_actual_local_base_url(base_url) else api_key
  624. def _actual_url(provider: str, base_url: str) -> str:
  625. return normalize_actual_base_url(base_url) if provider == "actual" else base_url
  626. def _explicit_api_key_provider(provider, pconfig, requested_provider, model_cfg, api_key, base_url, target_model):
  627. if not base_url:
  628. if provider == "actual":
  629. base_url = (_config_base_url_for_provider(model_cfg, provider)
  630. or resolve_api_key_provider_credentials(provider).get("base_url", ""))
  631. elif provider in {"kimi-coding", "kimi-coding-cn"}:
  632. base_url = resolve_api_key_provider_credentials(provider).get("base_url", "").rstrip("/")
  633. else:
  634. env_url = get_secret_str(pconfig.base_url_env_var, "").strip().rstrip("/") if pconfig.base_url_env_var else ""
  635. base_url = env_url or pconfig.inference_base_url
  636. base_url = _actual_url(provider, base_url)
  637. if not api_key:
  638. creds = resolve_api_key_provider_credentials(provider)
  639. api_key = creds.get("api_key", "")
  640. if not base_url:
  641. base_url = _actual_url(provider, creds.get("base_url", "").rstrip("/"))
  642. api_mode = _api_key_provider_api_mode(provider, model_cfg, api_key, base_url, target_model or model_cfg.get("default", ""),
  643. opencode_by_model=True)
  644. base_url = _finalize_base_url(provider, api_mode, base_url)
  645. api_key = _actual_local_key(provider, api_key, base_url)
  646. return _runtime(provider, api_mode, base_url.rstrip("/"), api_key, source="explicit", requested_provider=requested_provider)
  647. # Providers with a dedicated explicit-credential builder; everything else goes through the
  648. # registry ``api_key`` path (or None when the provider takes no explicit creds).
  649. _EXPLICIT_RESOLVERS: dict[str, Callable[..., dict[str, Any]]] = {
  650. "anthropic": _explicit_anthropic, "openai-codex": _explicit_codex, "nous": _explicit_nous, "qwen-oauth": _explicit_qwen,
  651. "azure-foundry": lambda rq, mc, key, url, tm: _resolve_azure_foundry_runtime(requested_provider=rq, model_cfg=mc,
  652. explicit_api_key=key, explicit_base_url=url),
  653. }
  654. def _resolve_explicit_runtime(*, provider: str, requested_provider: str, model_cfg: dict[str, Any],
  655. explicit_api_key: Optional[str] = None, explicit_base_url: Optional[str] = None,
  656. target_model: Optional[str] = None) -> Optional[dict[str, Any]]:
  657. explicit_api_key = str(explicit_api_key or "").strip()
  658. explicit_base_url = str(explicit_base_url or "").strip().rstrip("/")
  659. if not explicit_api_key and not explicit_base_url:
  660. return None
  661. resolver = _EXPLICIT_RESOLVERS.get(provider)
  662. if resolver is not None:
  663. return resolver(requested_provider, model_cfg, explicit_api_key, explicit_base_url, target_model)
  664. pconfig = PROVIDER_REGISTRY.get(provider)
  665. if not (pconfig and pconfig.auth_type == "api_key"):
  666. return None
  667. return _explicit_api_key_provider(provider, pconfig, requested_provider, model_cfg, explicit_api_key, explicit_base_url, target_model)
  668. # ── OAuth / auth-store providers ───────────────────────────────────────────────────────────
  669. @dataclass(frozen=True)
  670. class _OAuthRuntimeSpec:
  671. """Env/auth-store OAuth providers resolved by a single credential call."""
  672. resolve: Callable[[], dict[str, Any]]
  673. api_mode: Any # str, or callable(model) -> str
  674. default_source: str
  675. expiry_key: str
  676. failure_msg: str
  677. default_base_url: str = ""
  678. # ``resolve`` entries are late-bound lambdas so tests can monkeypatch the module-level
  679. # ``resolve_*_runtime_credentials`` names.
  680. _OAUTH_RUNTIME_PROVIDERS: dict[str, _OAuthRuntimeSpec] = {
  681. "nous": _OAuthRuntimeSpec(_resolve_nous_creds, nous_api_mode, "portal", "expires_at",
  682. "Auto-detected Nous provider but credentials failed"),
  683. "openai-codex": _OAuthRuntimeSpec(lambda: resolve_codex_runtime_credentials(), "codex_responses", "hermes-auth-store",
  684. "last_refresh", "Auto-detected Codex provider but credentials failed"),
  685. "xai-oauth": _OAuthRuntimeSpec(lambda: resolve_xai_oauth_runtime_credentials(), "codex_responses", "hermes-auth-store",
  686. "last_refresh", "Auto-detected xAI OAuth provider but credentials failed", DEFAULT_XAI_OAUTH_BASE_URL),
  687. "qwen-oauth": _OAuthRuntimeSpec(lambda: resolve_qwen_runtime_credentials(), "chat_completions", "qwen-cli",
  688. "expires_at_ms", "Qwen OAuth credentials failed"),
  689. }
  690. def _resolve_oauth_runtime(provider, requested_provider, model_cfg, target_model) -> Optional[dict[str, Any]]:
  691. """Runtime from an ``_OAUTH_RUNTIME_PROVIDERS`` spec; raises AuthError when the credential is
  692. stale/revoked/benched (``_ladder_rungs`` decides whether an "auto" request falls through)."""
  693. spec = _OAUTH_RUNTIME_PROVIDERS[provider]
  694. creds = spec.resolve()
  695. api_mode = spec.api_mode(_effective_model(model_cfg, target_model)) if callable(spec.api_mode) else spec.api_mode
  696. return _runtime(provider, api_mode, (creds.get("base_url") or "").rstrip("/") or spec.default_base_url,
  697. creds.get("api_key", ""), source=creds.get("source", spec.default_source),
  698. **{spec.expiry_key: creds.get(spec.expiry_key)}, requested_provider=requested_provider)
  699. def _minimax_oauth_runtime(provider, requested_provider) -> Optional[dict[str, Any]]:
  700. pconfig = PROVIDER_REGISTRY.get(provider)
  701. if not (pconfig and pconfig.auth_type == "oauth_minimax"):
  702. return None
  703. creds = auth_mod.resolve_minimax_oauth_runtime_credentials()
  704. return _runtime(provider, "anthropic_messages", creds["base_url"], creds["api_key"], source=creds.get("source", "oauth"),
  705. requested_provider=requested_provider)
  706. # ── env/config paths for anthropic and registry api_key providers ──────────────────────────
  707. def _azure_anthropic_env_key(model_cfg: dict[str, Any]) -> str:
  708. """Azure Anthropic key: `key_env` / `api_key_env` hints on the model config, then an inline
  709. api_key (multi-profile setups), then the historical fixed names."""
  710. for hint_key in ("key_env", "api_key_env"):
  711. env_var = str(model_cfg.get(hint_key) or "").strip()
  712. if env_var and (token := get_secret_str(env_var, "").strip()):
  713. return token
  714. return (str(model_cfg.get("api_key") or "").strip() or get_secret_str("AZURE_ANTHROPIC_KEY", "").strip()
  715. or get_secret_str("ANTHROPIC_API_KEY", "").strip())
  716. def _anthropic_env_runtime(requested_provider: str, model_cfg: dict[str, Any], target_model: str | None = None) -> dict[str, Any]:
  717. """Native Anthropic (Messages API) from env/auth store; ``model.base_url`` honoured only when
  718. the configured provider is anthropic (else a Codex endpoint would leak into Anthropic requests)."""
  719. base_url = _anthropic_cfg_base_url(model_cfg) or _ANTHROPIC_DEFAULT_BASE_URL
  720. # Microsoft Foundry endpoints reject Claude Code OAuth tokens, which resolve_anthropic_token()
  721. # would return first — use the env key directly.
  722. if base_url_host_matches(base_url, "azure.com"):
  723. token = _azure_anthropic_env_key(model_cfg)
  724. if not token:
  725. raise AuthError("No Azure Anthropic API key found. Set AZURE_ANTHROPIC_KEY or ANTHROPIC_API_KEY, or point "
  726. "key_env/api_key_env in your config.yaml model section at a custom env var.")
  727. else:
  728. token = _anthropic_token_or_raise(model=target_model)
  729. return _runtime("anthropic", "anthropic_messages", base_url, token, source="env", requested_provider=requested_provider)
  730. def _api_key_provider_runtime(provider, pconfig, requested_provider, model_cfg, target_model) -> dict[str, Any]:
  731. """Registry ``api_key`` providers (z.ai/GLM, Kimi, MiniMax, …) from env/config."""
  732. creds = resolve_api_key_provider_credentials(provider)
  733. # Actual Computer: a loopback model_cfg base_url selects the daemon's no-auth local API; inject
  734. # the placeholder BEFORE the usable-secret gate (mirrors the env-driven path).
  735. if provider == "actual" and not has_usable_secret(creds.get("api_key")):
  736. cfg_url = _config_base_url_for_provider(model_cfg, provider)
  737. if is_actual_local_base_url(normalize_actual_base_url(cfg_url or creds.get("base_url", "").rstrip("/"))):
  738. creds = {**creds, "api_key": ACTUAL_LOCAL_NOAUTH_PLACEHOLDER, "source": creds.get("source") or "local-offline"}
  739. # An explicitly selected API-key provider is authoritative: an empty key would defer failure
  740. # to the first request and make a later fallback look like a silent provider switch.
  741. if not has_usable_secret(creds.get("api_key")):
  742. from hermes_cli.runtime_readiness import missing_credentials_suffix
  743. from hermes_cli.runtime_provider_missing_key import named_profile_key_hint
  744. hint = (f" Set {', '.join(pconfig.api_key_env_vars)}." if pconfig.api_key_env_vars else "") + missing_credentials_suffix(provider)
  745. hint += named_profile_key_hint(pconfig.api_key_env_vars)
  746. raise AuthError(f"No usable credentials found for provider '{provider}'.{hint}", provider=provider, code="missing_api_key")
  747. # Honour model.base_url when the configured provider matches (e.g. api.minimaxi.com China endpoint).
  748. base_url = _actual_url(provider, _config_base_url_for_provider(model_cfg, provider) or creds.get("base_url", "").rstrip("/"))
  749. api_mode = _api_key_provider_api_mode(provider, model_cfg, creds.get("api_key", ""), base_url,
  750. target_model or model_cfg.get("default", ""), opencode_by_model=True)
  751. base_url = _finalize_base_url(provider, api_mode, base_url)
  752. api_key = _actual_local_key(provider, creds.get("api_key", ""), base_url)
  753. return _runtime(provider, api_mode, base_url, api_key, source=creds.get("source", "env"), requested_provider=requested_provider)
  754. # ── the resolution ladder ──────────────────────────────────────────────────────────────────
  755. _VERTEX_NAMES = ("vertex", "google-vertex", "vertex-ai", "gcp-vertex", "vertexai")
  756. _LOCAL_BYPASS_CLOUD_HOSTS = ("openrouter.ai", "anthropic.com", "openai.com")
  757. def _raise_if_provider_disabled(requested_provider: str) -> None:
  758. """Honour ``providers.<name>.enabled: false`` for built-ins too (the custom lookup gate only
  759. covers custom blocks); a typed error lets the fallback chain advance."""
  760. full_cfg = load_config()
  761. provs_cfg = full_cfg.get("providers") if isinstance(full_cfg, dict) else None
  762. block = provs_cfg.get(requested_provider) if isinstance(provs_cfg, dict) else None
  763. if isinstance(block, dict) and not _config_mod.is_provider_enabled(block):
  764. raise ValueError(f"provider {requested_provider!r} is disabled in config "
  765. f"(providers.{requested_provider}.enabled: false)")
  766. def _raise_if_local_alias_missing_endpoint(requested_provider: str, explicit_base_url: Optional[str]) -> None:
  767. """A local-server alias (``ollama``, ``vllm`` — anything ``auth.resolve_provider`` maps to
  768. ``custom`` without a rung of its own) with NO endpoint configured anywhere would otherwise walk
  769. the whole ladder to the OpenRouter fallback and spend an unrelated cloud key there (#113703).
  770. Keyed on the ABSENCE of an endpoint, not on the alias name: ``/model <direct-alias>`` resolves
  771. the alias label with the alias endpoint as ``explicit_base_url`` and must keep working, which
  772. is why the name-keyed version was reverted (e9a54c48f2 / a9fabe43c4). Endpoint sources:
  773. explicit call base_url, ``CUSTOM_BASE_URL``, a trusted ``model.base_url``, or a
  774. ``providers.<alias>`` block carrying a ``base_url``. ``OPENROUTER_BASE_URL`` is never the
  775. alias endpoint, and an explicit api_key does not lift the guard — that key was meant for the
  776. alias's own server. ``llamacpp`` fails fast on its own managed-server rung."""
  777. requested_norm = (requested_provider or "").strip().lower()
  778. if (requested_norm in ("", "custom") or requested_norm in _LLAMACPP_ALIASES
  779. or not _resolves_to_custom(requested_norm)):
  780. return
  781. if str(explicit_base_url or "").strip() or get_secret_str("CUSTOM_BASE_URL", "").strip():
  782. return
  783. model_cfg = _get_model_config()
  784. if _config_base_url_trustworthy_for_bare_custom(str(model_cfg.get("base_url") or ""), _cfg_provider(model_cfg)):
  785. return
  786. if str((_get_named_custom_provider(requested_provider) or {}).get("base_url") or "").strip():
  787. return
  788. raise AuthError(
  789. f"provider '{requested_provider}' has no endpoint configured, so the request is not sent anywhere "
  790. f"(it would otherwise fall back to OpenRouter). Set providers.{requested_norm}.base_url or "
  791. "model.base_url in config.yaml.",
  792. provider=requested_provider,
  793. code="missing_base_url",
  794. )
  795. def _resolve_vertex_runtime(requested_provider: str) -> dict[str, Any]:
  796. """Vertex AI (OAuth2). The credential *path* (GOOGLE_APPLICATION_CREDENTIALS) must never be
  797. treated as a static API key; a short-lived token is minted per call, and mid-session expiry is
  798. recovered on 401 by run_agent._try_refresh_vertex_client_credentials(). Under
  799. :func:`deferred_token_mint` the credentials are loaded (same failure copy) but the token is a
  800. callable minted on first use, so a process that only routes never exchanges a JWT."""
  801. from agent.vertex_adapter import get_vertex_base_url, get_vertex_config, vertex_access_token
  802. if _DEFER_TOKEN_MINT.get():
  803. token, base_url = vertex_access_token, get_vertex_base_url()
  804. else:
  805. token, base_url = get_vertex_config()
  806. if not token or not base_url:
  807. raise AuthError("Vertex AI credentials could not be resolved. Vertex uses OAuth2 (not a static API key): provide a "
  808. "service-account JSON via GOOGLE_APPLICATION_CREDENTIALS (or VERTEX_CREDENTIALS_PATH) in ~/.hermes/.env, "
  809. "or run 'gcloud auth application-default login' for ADC. Set the GCP project/region under vertex: in "
  810. "config.yaml if they aren't embedded in the credentials. Run `hermes setup` to install Vertex support.")
  811. return _runtime("vertex", "chat_completions", base_url.rstrip("/"), token, source="vertex-oauth", requested_provider=requested_provider)
  812. def _resolve_requested_shortcuts(requested_provider, explicit_api_key, explicit_base_url, target_model) -> Optional[dict[str, Any]]:
  813. """Providers decided on the REQUESTED name alone, before custom / pool / generic paths."""
  814. if requested_provider == "moa":
  815. return _runtime("moa", "chat_completions", "moa://local", "moa-virtual-provider", source="moa-virtual-provider",
  816. requested_provider=requested_provider)
  817. # Azure Anthropic short-circuit: an explicit Azure endpoint with provider="anthropic" must
  818. # bypass _resolve_named_custom_runtime (which would yield custom/chat_completions/no key).
  819. eff_base = (explicit_base_url or "").strip()
  820. if requested_provider == "anthropic" and base_url_host_matches(eff_base, "azure.com"):
  821. return _runtime("anthropic", "anthropic_messages", eff_base.rstrip("/"),
  822. (explicit_api_key or "").strip() or _azure_anthropic_env_key({}), source="azure-explicit",
  823. requested_provider=requested_provider)
  824. # Azure Foundry resolves before the custom-runtime / pool / generic paths so its config is
  825. # always picked up from model.base_url + model.api_mode, with or without explicit_* args.
  826. if requested_provider == "azure-foundry":
  827. return _resolve_azure_foundry_runtime(requested_provider=requested_provider, model_cfg=_get_model_config(),
  828. explicit_api_key=explicit_api_key, explicit_base_url=explicit_base_url,
  829. target_model=target_model)
  830. if requested_provider in _VERTEX_NAMES:
  831. return _resolve_vertex_runtime(requested_provider)
  832. return None
  833. def _local_endpoint_bypass(requested_provider: str, explicit_api_key, explicit_base_url) -> Optional[dict[str, Any]]:
  834. """provider "auto"/unset with a config base_url at a custom/local endpoint routes through the
  835. OpenAI-compatible resolver, so resolve_provider() cannot pick up an env ANTHROPIC/OPENAI key
  836. and send the request to a cloud API. Only non-cloud roots take the bypass; match on HOST, not
  837. substring, so a look-alike (api.anthropic.com.attacker.test) cannot leak a cloud credential."""
  838. model_cfg = _get_model_config()
  839. cfg_base_url = str(model_cfg.get("base_url") or "").strip()
  840. if (not cfg_base_url or _cfg_provider(model_cfg) not in ("auto", "")
  841. or any(base_url_host_matches(cfg_base_url, host) for host in _LOCAL_BYPASS_CLOUD_HOSTS)):
  842. return None
  843. return _openrouter_fallback(requested_provider, explicit_api_key, explicit_base_url)
  844. def _tag(runtime: Optional[dict[str, Any]], requested_provider: str) -> Optional[dict[str, Any]]:
  845. """Stamp ``requested_provider`` on a runtime built by a collaborator that does not set it."""
  846. if runtime:
  847. runtime["requested_provider"] = requested_provider
  848. return runtime
  849. def _named_custom_rung(requested_provider, explicit_api_key, explicit_base_url, target_model) -> Optional[dict[str, Any]]:
  850. """Rung 3: a configured named custom provider. Honours the ``model.openai_runtime`` opt-in like the
  851. pool path does for openai/openai-codex (codex resolves the provider from its own config by id)."""
  852. runtime = _tag(_resolve_named_custom_runtime(requested_provider=requested_provider, explicit_api_key=explicit_api_key,
  853. explicit_base_url=explicit_base_url, target_model=target_model), requested_provider)
  854. if runtime and runtime.get("provider") == "custom":
  855. runtime["api_mode"] = _maybe_apply_codex_app_server_runtime(
  856. provider="custom", api_mode=runtime.get("api_mode") or "chat_completions", model_cfg=_get_model_config(),
  857. requested_provider=requested_provider)
  858. return runtime
  859. def _openrouter_fallback(requested_provider, explicit_api_key, explicit_base_url) -> dict[str, Any]:
  860. return _tag(_resolve_openrouter_runtime(requested_provider=requested_provider, explicit_api_key=explicit_api_key,
  861. explicit_base_url=explicit_base_url), requested_provider)
  862. def resolve_runtime_provider(*, requested: Optional[str] = None, explicit_api_key: Optional[str] = None,
  863. explicit_base_url: Optional[str] = None, target_model: Optional[str] = None) -> dict[str, Any]:
  864. """Resolve runtime provider credentials for agent execution. Ladder (order is behavior — each
  865. rung returns or raises, else falls to the next):
  866. 1. disabled-provider guard (``providers.<name>.enabled: false``)
  867. 2. requested-name shortcuts: moa, anthropic@azure, azure-foundry, vertex
  868. 3. named custom provider / llamacpp alias / bare-custom direct alias
  869. 4. local-endpoint bypass (no explicit creds, config base_url at a non-cloud host)
  870. 5. ``auth.resolve_provider`` → explicit --api-key/--base-url path
  871. 6. credential pool (OpenRouter pool only without custom endpoint/override)
  872. 7. OAuth specs (nous/codex/xai/qwen; "auto" swallows AuthError, logs, and stamps it on a
  873. keyless fallback as ``auth_error``) → minimax-oauth
  874. → external-process → anthropic env → bedrock → registry api_key providers
  875. 8. OpenRouter / bare-custom fallback
  876. 9. ``model.openai_runtime`` overlay (openai/openai-codex, named custom providers): rewrites the picked rung's
  877. api_mode to ``codex_app_server``; the rung's credential/endpoint is then not used
  878. target_model overrides model_cfg["default"] when computing provider-specific api_mode (e.g.
  879. OpenCode Zen/Go where different models route through different API surfaces)."""
  880. requested_provider = resolve_requested_provider(requested)
  881. from hermes_cli.left_core_migration import recover_for_provider
  882. recover_for_provider(requested_provider) # a provider whose plugin left core: install it before resolving
  883. _raise_if_provider_disabled(requested_provider)
  884. # Same alias expansion the auxiliary client applies, so ``provider: openai`` means one thing on
  885. # every path (background review, curator, MoA slots, delegation) instead of "Unknown provider".
  886. # The pre-expansion name is what the codex_app_server overlay judges: ``openai`` is eligible,
  887. # the anonymous ``custom`` it expands to is not.
  888. requested_alias = requested_provider
  889. requested_provider, explicit_base_url = expand_direct_api_alias(requested_provider, explicit_base_url)
  890. _raise_if_local_alias_missing_endpoint(requested_provider, explicit_base_url)
  891. runtime = next(r for r in _ladder_rungs(requested_provider, explicit_api_key, explicit_base_url, target_model) if r)
  892. _raise_for_credentialless_bare_custom(requested_provider, runtime)
  893. # model.openai_runtime is applied ONCE, after the ladder: every rung (pool, OAuth store,
  894. # explicit --api-key/--base-url, env key) hardcodes the wire api_mode for openai/openai-codex,
  895. # so applying the opt-in inside one rung left the others on codex_responses (#115169).
  896. api_mode = _maybe_apply_codex_app_server_runtime(
  897. provider=runtime.get("provider", ""), api_mode=runtime.get("api_mode", ""), model_cfg=_get_model_config(),
  898. requested_provider=requested_alias)
  899. if api_mode != runtime.get("api_mode"):
  900. logger.info("model.openai_runtime=codex_app_server overrides the %s runtime (source=%s); its credential/endpoint "
  901. "is not used — the app-server authenticates with its own login", runtime.get("provider"), runtime.get("source"))
  902. runtime["api_mode"] = api_mode
  903. from hermes_cli.runtime_provider_missing_key import raise_if_declared_key_missing
  904. raise_if_declared_key_missing(requested_provider, runtime, _get_model_config(), _FROZEN_RUNTIME_CONFIG.get(),
  905. explicit_api_key=explicit_api_key)
  906. return runtime
  907. def _raise_for_credentialless_bare_custom(requested_provider: str, runtime: dict[str, Any]) -> None:
  908. """Reject a bare ``custom`` placeholder request that fell through the whole ladder to the
  909. OpenRouter default endpoint with no credential. Every other custom rung (named entry, local
  910. bypass, pool, ``key_cmd``) yields a key, a callable or the ``no-key-required`` placeholder, so
  911. an EMPTY key on a ``custom`` runtime is exactly the dead shape that otherwise dies at agent
  912. construction as ``No LLM provider configured``. Keyed on the literal request, not the resolved
  913. shape: local aliases (``ollama``, ``vllm``) are resolved tolerantly by ``/model`` direct-alias
  914. switching, which supplies the alias endpoint AFTER this call and must not fail here. Typed
  915. ``AuthError`` so every caller's fallback chain (CLI, gateway, TUI, cron) still advances (#17929).
  916. """
  917. if requested_provider != "custom" or runtime.get("provider") != "custom" or runtime.get("api_key"):
  918. return
  919. raise AuthError(
  920. f"provider '{requested_provider}' resolved without credentials (no endpoint or API key configured). "
  921. "If this is a named custom provider, use its real name (see providers: in config.yaml).",
  922. provider=requested_provider,
  923. code="missing_api_key",
  924. )
  925. def _ladder_rungs(requested_provider, explicit_api_key, explicit_base_url, target_model):
  926. """Ladder rungs 2-8, yielded lazily so each is evaluated only when the previous one returned
  927. nothing; the last rung (OpenRouter / bare-custom fallback) always yields a runtime."""
  928. yield _resolve_requested_shortcuts(requested_provider, explicit_api_key, explicit_base_url, target_model)
  929. yield _named_custom_rung(requested_provider, explicit_api_key, explicit_base_url, target_model)
  930. # If provider is "auto" (or unset) but config.yaml has an explicit base_url pointing at a custom/local
  931. # endpoint (e.g. Ollama at localhost:11434), route through the OpenAI-compatible resolver instead of
  932. # letting resolve_provider() pick up an ANTHROPIC_API_KEY or OPENAI_API_KEY from the environment and
  933. # send the request to a cloud API. Fixes #3846.
  934. if not explicit_base_url and not explicit_api_key:
  935. yield _local_endpoint_bypass(requested_provider, explicit_api_key, explicit_base_url)
  936. provider = resolve_provider(requested_provider, explicit_api_key=explicit_api_key, explicit_base_url=explicit_base_url)
  937. model_cfg = _get_model_config()
  938. yield _resolve_explicit_runtime(provider=provider, requested_provider=requested_provider, model_cfg=model_cfg,
  939. explicit_api_key=explicit_api_key, explicit_base_url=explicit_base_url,
  940. target_model=target_model)
  941. yield _resolve_from_pool(provider, requested_provider, model_cfg, explicit_api_key, explicit_base_url, target_model)
  942. swallowed_auth_error = None
  943. if provider in _OAUTH_RUNTIME_PROVIDERS:
  944. try:
  945. yield _resolve_oauth_runtime(provider, requested_provider, model_cfg, target_model)
  946. except AuthError as exc:
  947. # Auto-detected login with stale/revoked/benched credentials: fall through to the env-var
  948. # providers, but keep the error so a keyless fallback can still say what is wrong.
  949. if requested_provider != "auto":
  950. raise
  951. logger.info("%s; falling through to next provider.", _OAUTH_RUNTIME_PROVIDERS[provider].failure_msg)
  952. swallowed_auth_error = exc
  953. if provider == "minimax-oauth":
  954. yield _minimax_oauth_runtime(provider, requested_provider)
  955. if _is_external_process_provider(provider):
  956. yield _resolve_external_process_runtime(provider, requested_provider)
  957. if provider == "anthropic":
  958. yield _anthropic_env_runtime(requested_provider, model_cfg, target_model)
  959. if provider == "bedrock":
  960. yield _resolve_bedrock_runtime(requested_provider, model_cfg, target_model)
  961. pconfig = PROVIDER_REGISTRY.get(provider)
  962. if pconfig and pconfig.auth_type == "api_key":
  963. yield _api_key_provider_runtime(provider, pconfig, requested_provider, model_cfg, target_model)
  964. fallback = _openrouter_fallback(requested_provider, explicit_api_key, explicit_base_url)
  965. if swallowed_auth_error is not None and not fallback.get("api_key"):
  966. fallback["auth_error"] = swallowed_auth_error
  967. yield fallback
  968. def format_runtime_provider_error(error: Exception) -> str:
  969. return format_auth_error(error) if isinstance(error, AuthError) else str(error)
  970. def resolve_runtime_with_fallback(config: Optional[dict[str, Any]], *, requested: Optional[str] = None,
  971. target_model: Optional[str] = None, explicit_base_url: Optional[str] = None,
  972. explicit_api_key: Optional[str] = None,
  973. ) -> tuple[dict[str, Any], Optional[dict[str, Any]]]:
  974. """``resolve_runtime_provider`` plus resolution-time fallback: ``(runtime, fallback_entry_or_None)``.
  975. Only an ``AuthError`` from the primary (missing/expired credentials, exhausted quota, cooled-down pool)
  976. walks ``get_fallback_chain(config)`` in order and returns the first entry that resolves — the single
  977. resolution-time walker shared by the gateway and oneshot. ``ValueError``/other errors are genuine
  978. misconfiguration (unknown ``--provider`` ...) and propagate unchanged, so a typo is never silently
  979. rerouted onto a provider the operator did not ask for. When every entry fails, the *primary* error is
  980. re-raised: a fallback entry's failure is not what the operator configured first (#81209). The entry's
  981. ``model`` is the model the caller must send.
  982. """
  983. from hermes_cli.auth import AuthError, primary_failure_wording
  984. try:
  985. return resolve_runtime_provider(requested=requested, target_model=target_model,
  986. explicit_base_url=explicit_base_url, explicit_api_key=explicit_api_key), None
  987. except AuthError as primary_exc:
  988. from hermes_cli.fallback_config import effective_runtime_provider, get_fallback_chain, resolve_entry_api_key
  989. for entry in get_fallback_chain(config):
  990. provider = (entry.get("provider") or "").strip().lower()
  991. model = (entry.get("model") or "").strip()
  992. if not provider or not model:
  993. continue
  994. kwargs: dict[str, Any] = {"requested": provider, "target_model": model}
  995. if entry.get("base_url"):
  996. kwargs["explicit_base_url"] = entry["base_url"]
  997. if entry_key := resolve_entry_api_key(entry):
  998. kwargs["explicit_api_key"] = entry_key
  999. try:
  1000. runtime = resolve_runtime_provider(**kwargs)
  1001. except AuthError as fb_exc:
  1002. logger.debug("Fallback entry %s/%s failed: %s", provider, model, fb_exc)
  1003. continue
  1004. except Exception as fb_exc:
  1005. # Not a credential problem: a mistyped provider/base_url must be visible, not silently skipped.
  1006. logger.warning("Fallback entry %s/%s is misconfigured and was skipped: %s", provider, model, fb_exc)
  1007. continue
  1008. # Named custom entries resolve to the bare "custom" class; persist the configured identity (#98739).
  1009. runtime["provider"] = effective_runtime_provider(entry, runtime)
  1010. # A rate-limit/quota cap is transient (credentials are fine, re-auth cannot help); the log must not
  1011. # mislabel it as an auth failure (#32790).
  1012. logger.warning("Primary provider %s (%s). Falling back to %s/%s",
  1013. primary_failure_wording(primary_exc)[0], primary_exc, provider, model)
  1014. return runtime, entry
  1015. raise primary_exc