runtime_provider_custom.py 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768
  1. """Custom-provider resolution: ``providers:`` / ``custom_providers:`` lookup, identity recovery,
  2. custom credential pools, and the named-custom runtime builder. Extracted from
  3. :mod:`hermes_cli.runtime_provider`; origin-internal collaborators
  4. (``load_config``, ``_get_model_config``, ``load_pool``, ``has_usable_secret``, …) are looked up on
  5. the origin module AT CALL TIME via :func:`_rp` so ``monkeypatch.setattr(runtime_provider, name, …)``
  6. keeps working for moved bodies."""
  7. from __future__ import annotations
  8. import logging
  9. import os
  10. from typing import Any, Callable, Dict, Optional, Tuple
  11. from hermes_cli.providers import custom_provider_aliases, custom_provider_slug
  12. from agent.custom_entry_pool import custom_entry_for_endpoint, entry_declares_credential, entry_scoped_pool
  13. from agent.secret_scope import get_secret_str
  14. from utils import base_url_hostname
  15. logger = logging.getLogger("hermes_cli.runtime_provider")
  16. _LLAMACPP_ALIASES = ("llamacpp", "llama.cpp", "llama-cpp")
  17. def _rp():
  18. """Origin module, late-bound so test patches on ``hermes_cli.runtime_provider.*`` apply."""
  19. import hermes_cli.runtime_provider as origin
  20. return origin
  21. def _normalize_custom_provider_name(value: str) -> str:
  22. return value.strip().lower().replace(" ", "-")
  23. def _normalize_base_url_for_match(value) -> str:
  24. return str(value or "").strip().rstrip("/").lower()
  25. def _route_key(value) -> str:
  26. """An endpoint compared for identity: scheme and host fold case, the path does not."""
  27. from hermes_cli.route_identity import normalize_route_base_url
  28. return normalize_route_base_url(_clean(value))
  29. def _clean(value: Any) -> str:
  30. return str(value or "").strip()
  31. def _key_env_secret(entry: dict[str, Any], label: str) -> str:
  32. """The credential named by ``key_env`` / ``api_key_env`` on a config block, or "".
  33. A declared variable that resolves to nothing is logged: every custom rung substitutes
  34. ``no-key-required`` for an empty key (keyless local servers), so a misnamed or unexported
  35. variable otherwise surfaces only as the provider's 401/403 (#67453). A block with no key_env at
  36. all stays silent — that IS the keyless-server configuration. A ``providers:`` entry with a
  37. declared credential never falls back to an implicit env key, so the placeholder is what it gets.
  38. """
  39. key_env = _clean(entry.get("key_env") or entry.get("api_key_env"))
  40. if not key_env:
  41. return ""
  42. value = get_secret_str(key_env, "").strip()
  43. if not value:
  44. logger.warning("%s: key_env %s is set but the variable is empty/unset — unless another credential "
  45. "is configured for it, the request carries the placeholder no-key-required and the "
  46. "endpoint will reject it", label, key_env)
  47. return value
  48. def _model_cfg_key_env_for(model_cfg: dict[str, Any], base_url: str) -> str:
  49. """``model.key_env`` for a bare ``provider: custom`` runtime, only when ``base_url`` IS the
  50. configured ``model.base_url`` — the key was declared for that endpoint, never for a direct alias
  51. or CUSTOM_BASE_URL pointing elsewhere."""
  52. cfg_base_url = _clean(model_cfg.get("base_url")).rstrip("/")
  53. if not cfg_base_url or cfg_base_url != _clean(base_url).rstrip("/"):
  54. return ""
  55. return _key_env_secret(model_cfg, "model")
  56. def _entry_url(entry: dict[str, Any]) -> str:
  57. return entry.get("api") or entry.get("url") or entry.get("base_url") or ""
  58. # ── field lifting shared by ``providers:`` and legacy ``custom_providers:`` entries ────────
  59. def _filter_capabilities(value: Any) -> dict[str, bool]:
  60. """Return the string-keyed boolean capabilities accepted at runtime."""
  61. if not isinstance(value, dict):
  62. return {}
  63. return {k: v for k, v in value.items() if isinstance(k, str) and isinstance(v, bool)}
  64. def _lift_model_capabilities(entry: dict[str, Any], model: Optional[str], result: dict[str, Any]) -> None:
  65. """Copy explicit boolean per-model capabilities into the runtime."""
  66. capabilities = _filter_capabilities(entry.get("capabilities"))
  67. models = entry.get("models")
  68. model_config = models.get(model) if isinstance(models, dict) and model else None
  69. if isinstance(model_config, dict):
  70. capabilities.update(_filter_capabilities(model_config))
  71. if capabilities:
  72. result["capabilities"] = capabilities
  73. def _lift_extra_headers(entry: dict[str, Any], result: dict[str, Any]) -> None:
  74. """Copy a validated ``extra_headers`` dict. SECURITY: values carry credentials — never log."""
  75. extra_headers = _rp().normalize_extra_headers(entry.get("extra_headers"))
  76. if extra_headers:
  77. result["extra_headers"] = extra_headers
  78. def _lift_common_custom_fields(entry: dict[str, Any], result: dict[str, Any], *, provider_key: str, key_env: str,
  79. api_mode: Optional[str]) -> None:
  80. """Copy the optional fields shared by ``providers:`` and legacy ``custom_providers:`` entries."""
  81. if key_env:
  82. result["key_env"] = key_env
  83. if provider_key:
  84. result["provider_key"] = provider_key
  85. extra_body = entry.get("extra_body")
  86. if isinstance(extra_body, dict):
  87. result["extra_body"] = dict(extra_body)
  88. _lift_extra_headers(entry, result)
  89. if api_mode:
  90. result["api_mode"] = api_mode
  91. _lift_model_capabilities(entry, None, result)
  92. # ── config lookup ──────────────────────────────────────────────────────────────────────────
  93. def _shadowed_by_builtin(requested_norm: str) -> bool:
  94. """Raw names map to custom providers only when they are not canonical built-ins. Explicit
  95. ``custom:<name>`` keys always target the saved entry, and bare ``custom`` is exempt: a user may
  96. literally name a ``providers:`` entry "custom" (returning None before the config scan made such
  97. cron jobs fail with ``auth_unavailable``). Defer to the built-in only when the raw name IS the
  98. canonical provider (``nous``); an entry matching merely an alias (``kimi`` → ``kimi-coding``)
  99. is the user's target."""
  100. if requested_norm == "custom" or requested_norm.startswith("custom:"):
  101. return False
  102. rp = _rp()
  103. try:
  104. canonical = rp.auth_mod.resolve_provider(requested_norm)
  105. except rp.AuthError:
  106. return False
  107. return (canonical or "").strip().lower() == requested_norm
  108. def _match_new_style_provider(
  109. requested_norm: str, providers: dict[str, Any], *, resolve_credentials: bool = True,
  110. ) -> Optional[tuple[dict[str, Any], Any]]:
  111. """Scan ``providers:`` (new-style, keyed) for ``requested_norm``; ``(entry, config key)``."""
  112. from hermes_cli.config import is_provider_enabled
  113. rp = _rp()
  114. for ep_name, entry in providers.items():
  115. # ``providers.<name>.enabled: false`` entries stay in config but are invisible here.
  116. if not isinstance(entry, dict) or not is_provider_enabled(entry):
  117. continue
  118. if requested_norm not in custom_provider_aliases(str(entry.get("name", "") or ep_name), str(ep_name)):
  119. continue
  120. base_url = _entry_url(entry)
  121. if not base_url:
  122. continue
  123. # Resolve credentials only after identity and endpoint validation. Merely scanning an
  124. # unrelated entry must not read its profile-scoped secret.
  125. key_env = _clean(entry.get("key_env") or entry.get("api_key_env"))
  126. api_key = get_secret_str(key_env, "").strip() if key_env and resolve_credentials else ""
  127. result: dict[str, Any] = {"name": entry.get("name", ep_name), "base_url": base_url.strip(),
  128. "api_key": api_key or _clean(entry.get("api_key", "")), "model": entry.get("default_model", "")}
  129. # Command that PRINTS a short-lived credential; wrapped in a per-request token provider.
  130. key_cmd = _clean(entry.get("key_cmd", ""))
  131. if key_cmd:
  132. result["key_cmd"] = key_cmd
  133. # v12 migration writes ``transport``; hand-edited configs may still use ``api_mode``.
  134. # Accept both or migrated configs silently downgrade to chat_completions.
  135. _lift_common_custom_fields(
  136. entry, result, provider_key=_clean(ep_name), key_env=key_env,
  137. api_mode=rp._parse_api_mode(entry.get("api_mode") or entry.get("transport")),
  138. )
  139. return result, ep_name
  140. return None
  141. def _match_legacy_custom_provider(requested_norm: str, custom_providers) -> Optional[tuple[dict[str, Any], dict]]:
  142. """Scan the legacy ``custom_providers:`` list for ``requested_norm``; ``(result, matched entry)``."""
  143. for entry in custom_providers:
  144. name, base_url = (entry.get("name"), entry.get("base_url")) if isinstance(entry, dict) else (None, None)
  145. if not isinstance(name, str) or not isinstance(base_url, str):
  146. continue
  147. provider_key = _clean(entry.get("provider_key", ""))
  148. if requested_norm not in custom_provider_aliases(name, provider_key):
  149. continue
  150. result = {"name": name.strip(), "base_url": base_url.strip(), "api_key": _clean(entry.get("api_key", ""))}
  151. model_name = _clean(entry.get("model", ""))
  152. if model_name:
  153. result["model"] = model_name
  154. _lift_common_custom_fields(entry, result, provider_key=provider_key, key_env=_clean(entry.get("key_env", "")),
  155. api_mode=_rp()._parse_api_mode(entry.get("api_mode")))
  156. return result, entry
  157. return None
  158. def _get_named_custom_provider(
  159. requested_provider: str, *, config: Optional[dict[str, Any]] = None,
  160. resolve_credentials: bool = True,
  161. ) -> Optional[dict[str, Any]]:
  162. """Resolve a named endpoint. Creation-time config copying supplies its own config snapshot
  163. and skips credential reads; ordinary runtime callers keep their existing scoped resolution."""
  164. found = _select_named_custom_provider(requested_provider, config=config, resolve_credentials=resolve_credentials)
  165. return found[0] if found else None
  166. def named_custom_provider_config_path(requested_provider: str, config: dict[str, Any]) -> Optional[tuple]:
  167. """The config path (``("providers", key)`` / ``("custom_providers", index)``) of the ONE entry
  168. the runtime routes *requested_provider* through, else None. Reads no credential."""
  169. found = _select_named_custom_provider(requested_provider, config=config, resolve_credentials=False)
  170. return found[1] if found else None
  171. def custom_provider_config_path_for_url(base_url: Any, config: dict[str, Any]) -> Optional[tuple]:
  172. """The config path of the entry a bare ``custom`` route at *base_url* takes its key from: the
  173. first compatible ``custom_providers`` / ``providers`` entry with that URL (trailing slash
  174. ignored), the same owner the credential pool seeds from. Reads no credential."""
  175. url = str(base_url or "").strip().rstrip("/")
  176. if not url or isinstance(config.get("custom_providers"), dict):
  177. return None
  178. for entry in _rp().get_compatible_custom_providers(config) or ():
  179. if isinstance(entry, dict) and str(entry.get("base_url") or "").strip().rstrip("/") == url:
  180. return _compatible_entry_path(config, entry)
  181. return None
  182. def _select_named_custom_provider(
  183. requested_provider: str, *, config: Optional[dict[str, Any]], resolve_credentials: bool,
  184. ) -> Optional[tuple[dict[str, Any], Optional[tuple]]]:
  185. """``(resolved entry, its config path)`` for the first usable match: ``providers:`` first,
  186. then the legacy list view."""
  187. requested_norm = _normalize_custom_provider_name(requested_provider or "")
  188. if not requested_norm or requested_norm == "auto" or _shadowed_by_builtin(requested_norm):
  189. return None
  190. rp = _rp()
  191. if config is None:
  192. config = rp.load_config()
  193. providers = config.get("providers")
  194. found = (
  195. _match_new_style_provider(requested_norm, providers, resolve_credentials=resolve_credentials)
  196. if isinstance(providers, dict) else None
  197. )
  198. if found:
  199. return found[0], ("providers", found[1])
  200. if isinstance(config.get("custom_providers"), dict):
  201. logger.warning("custom_providers in config.yaml is a dict, not a list. "
  202. "Each entry must be prefixed with '-' in YAML. "
  203. "Run 'hermes doctor' for details.")
  204. return None
  205. custom_providers = rp.get_compatible_custom_providers(config)
  206. found = _match_legacy_custom_provider(requested_norm, custom_providers) if custom_providers else None
  207. return (found[0], _compatible_entry_path(config, found[1])) if found else None
  208. def _compatible_entry_path(config: dict[str, Any], entry: dict[str, Any]) -> Optional[tuple]:
  209. """Where a ``get_compatible_custom_providers`` entry lives in *config*. The view keeps the first
  210. of identical legacy entries, so the first raw entry normalizing to it is its source."""
  211. from hermes_cli.config_providers import _normalize_custom_provider_entry
  212. providers = config.get("providers")
  213. key = entry.get("provider_key")
  214. if key and isinstance(providers, dict):
  215. return next((("providers", k) for k in providers if str(k).strip() == key), None)
  216. legacy = config.get("custom_providers")
  217. return next((("custom_providers", i) for i, raw in enumerate(legacy if isinstance(legacy, list) else ())
  218. if _normalize_custom_provider_entry(raw) == entry), None)
  219. def has_named_custom_provider(requested_provider: str) -> bool:
  220. """True when config defines a ``providers:`` / ``custom_providers:`` entry matching the request
  221. (public wrapper so e.g. the cronjob tool need not reach into a private helper)."""
  222. try:
  223. return _rp()._get_named_custom_provider(requested_provider) is not None
  224. except Exception:
  225. return False
  226. def codex_model_provider_id(requested_provider: str) -> Optional[str]:
  227. """Codex ``[model_providers.<id>]`` key for a configured named custom provider — its ``custom:``
  228. identity without the prefix (the ``providers:`` config key; legacy ``custom_providers:`` entries
  229. use their normalized display name). None for bare ``custom``, aliases that resolve to custom
  230. (ollama, vllm, …) and unknown names: codex has no stable id to look up for those (#75186)."""
  231. if _normalize_custom_provider_name(requested_provider or "") in {"", "custom"}:
  232. return None
  233. try:
  234. entry = _rp()._get_named_custom_provider(requested_provider)
  235. except Exception:
  236. return None
  237. if not entry:
  238. return None
  239. return custom_provider_slug(str(entry.get("name") or ""), str(entry.get("provider_key") or "")).split(":", 1)[1] or None
  240. # ── identity recovery (bare "custom" -> durable ``custom:<name>``) ─────────────────────────
  241. def _find_custom_identity(matches: Callable[[dict[str, Any]], bool],
  242. config: Optional[dict[str, Any]] = None, prefer: Optional[str] = None) -> Optional[str]:
  243. """First enabled entry in ``providers:`` then legacy ``custom_providers:`` where ``matches(entry)``
  244. holds (*prefer* when it is one of them), as its canonical ``custom:<name>`` slug. A legacy entry
  245. whose slug a ``providers:`` entry with an endpoint owns never matches: runtime resolution runs that one.
  246. *config* defaults to the active profile's."""
  247. from hermes_cli.config import is_provider_enabled
  248. rp = _rp()
  249. try:
  250. config = rp.load_config() if config is None else config
  251. except Exception:
  252. return None
  253. first, owned = None, set()
  254. providers = config.get("providers")
  255. if isinstance(providers, dict):
  256. for ep_name, entry in providers.items():
  257. if not (isinstance(entry, dict) and is_provider_enabled(entry)):
  258. continue
  259. slug = custom_provider_slug(str(ep_name), str(ep_name))
  260. if _entry_url(entry):
  261. owned.add(slug)
  262. if matches(entry):
  263. if prefer is None or slug == prefer:
  264. return slug
  265. first = first or slug
  266. try:
  267. custom_providers = rp.get_compatible_custom_providers(config)
  268. except Exception:
  269. custom_providers = None
  270. for entry in custom_providers or []:
  271. name = entry.get("name") if isinstance(entry, dict) else None
  272. if isinstance(name, str) and name.strip() and matches(entry):
  273. slug = custom_provider_slug(name, str(entry.get("provider_key", "") or ""))
  274. if slug in owned and not entry.get("provider_key"):
  275. continue
  276. if prefer is None or slug == prefer:
  277. return slug
  278. first = first or slug
  279. return first
  280. def find_custom_provider_identity(base_url: str) -> Optional[str]:
  281. """Map an endpoint URL back to its canonical ``custom:<name>`` menu key. Session persistence
  282. stores the agent's *resolved* provider, which for every named custom endpoint is the literal
  283. string ``"custom"`` — the entry name is lost, and the api_key is deliberately never persisted."""
  284. target = _route_key(base_url)
  285. if not target:
  286. return None
  287. return _find_custom_identity(lambda entry: _route_key(_entry_url(entry)) == target)
  288. def _model_id_matches(value: Any, target: str) -> bool:
  289. return isinstance(value, str) and value.strip().lower() == target
  290. def find_custom_provider_identity_by_model(model: str) -> Optional[str]:
  291. """Map a model id back to the ``custom:<name>`` entry that serves it — companion to
  292. :func:`find_custom_provider_identity` for persistence paths where no base_url survived the
  293. round-trip (the session row always stores the model name)."""
  294. target = str(model or "").strip().lower()
  295. return _find_custom_identity(lambda entry: _entry_serves_model(entry, target)) if target else None
  296. def _entry_serves_model(entry: dict[str, Any], target: str) -> bool:
  297. if any(_model_id_matches(entry.get(key), target) for key in ("model", "default_model")):
  298. return True
  299. models = entry.get("models")
  300. if isinstance(models, dict):
  301. return any(str(mid).strip().lower() == target for mid in models)
  302. if isinstance(models, list):
  303. return any(_model_id_matches(item.get("id") or item.get("name") if isinstance(item, dict) else item, target)
  304. for item in models)
  305. return False
  306. def routed_custom_identity(base_url: Optional[str], model: Optional[str],
  307. config: Optional[dict[str, Any]] = None, held: Optional[str] = None) -> Optional[str]:
  308. """The configured ``custom:<name>`` entry a bare ``custom`` pick (the billing class every named
  309. endpoint reports) names: on *base_url*, the entry also serving *model* beats the first one there;
  310. without a URL the model alone names it. Among entries serving *model*, the *held* one (the
  311. profile's own) wins over config order."""
  312. url = _route_key(base_url)
  313. target = str(model or "").strip().lower()
  314. def on_url(entry: dict[str, Any]) -> bool:
  315. return not url or _route_key(_entry_url(entry)) == url
  316. return ((target and _find_custom_identity(lambda e: on_url(e) and _entry_serves_model(e, target), config, held))
  317. or (url and _find_custom_identity(on_url, config)) or None)
  318. def _endpoint_identity(base_url: str) -> Optional[str]:
  319. """The menu identity that owns ``base_url``: a configured entry, else the managed server."""
  320. identity = find_custom_provider_identity(base_url)
  321. if identity:
  322. return identity
  323. # The managed server has no custom-provider config entry. Recover its menu key
  324. # from the ownership-checked endpoint, never from a model name or a fixed port.
  325. from hermes_cli.local_runtime.endpoint import _state_endpoint
  326. endpoint = _state_endpoint()
  327. if endpoint and _route_key(base_url) == _route_key(endpoint["base_url"]):
  328. return "llamacpp"
  329. return None
  330. def canonical_custom_identity(*, base_url: Optional[str] = None, config_provider: Optional[str] = None,
  331. model: Optional[str] = None, requested: Optional[str] = None) -> Optional[str]:
  332. """Recover the durable menu identity for a bare custom provider. Match a configured
  333. endpoint first, then the ownership-checked managed server, then a configured model or
  334. provider. Every session persistence/restore path shares this lookup."""
  335. rp = _rp()
  336. # The entry the live agent resolved (*requested*) while it still serves base_url, else its owner.
  337. identity = session_provider_identity("custom", requested, base_url) if base_url else "custom"
  338. if identity != "custom":
  339. return identity
  340. identity = find_custom_provider_identity_by_model(model) if model else None
  341. if identity:
  342. return identity
  343. candidate = str(config_provider or "").strip()
  344. if not candidate:
  345. try:
  346. candidate = str(rp._get_model_config().get("provider") or "").strip()
  347. except Exception:
  348. candidate = ""
  349. if not candidate:
  350. candidate = os.environ.get("HERMES_INFERENCE_PROVIDER", "").strip()
  351. candidate_norm = _normalize_custom_provider_name(candidate)
  352. # A bare/non-routable candidate cannot heal a bare custom override.
  353. if not candidate_norm or candidate_norm in {"custom", "auto", "openrouter"}:
  354. return None
  355. # Only when it resolves to a configured entry — never invent a ``custom:<x>`` resolution
  356. # can't honor. ``candidate`` may be the entry's DISPLAY NAME, not the durable identity of a
  357. # keyed ``providers:`` entry — re-resolve via its endpoint so every path returns the same
  358. # config-key slug.
  359. try:
  360. entry = rp._get_named_custom_provider(candidate)
  361. except Exception:
  362. return None
  363. if entry is None:
  364. return None
  365. try:
  366. identity = find_custom_provider_identity(str(entry.get("base_url") or ""))
  367. except Exception:
  368. return None
  369. return identity or custom_provider_slug(candidate_norm)
  370. def session_provider_identity(provider: Any, requested_provider: Any, base_url: Any, model: Any = None, *,
  371. config: Optional[dict[str, Any]] = None) -> str:
  372. """A session's identity: the requested entry while it still serves ``base_url``, else the endpoint's
  373. owner, else the adapter. A name for an entry that left ``base_url`` pairs its new key with the old
  374. endpoint on resume, so with an endpoint known the model and config fallbacks never apply."""
  375. adapter = _clean(provider)
  376. if adapter.lower() != "custom":
  377. return adapter
  378. requested = _clean(requested_provider)
  379. url = _route_key(base_url)
  380. if url and requested.lower() not in {"", "custom", "auto"}:
  381. entry = _get_named_custom_provider(requested, config=config, resolve_credentials=False)
  382. if entry and _route_key(_entry_url(entry)) == url:
  383. return requested
  384. if url:
  385. return _endpoint_identity(_clean(base_url)) or adapter
  386. return canonical_custom_identity(model=_clean(model) or None) or adapter
  387. def is_routable_provider(provider: Optional[str]) -> bool:
  388. """Whether a provider name currently resolves to a routable route. Empty/None/``auto`` is
  389. vacuously routable (agent build falls back to the configured default). Bare ``custom`` is the
  390. resolved billing class shared by every named entry — not a routable identity; restore paths
  391. must heal it (:func:`canonical_custom_identity`) or fall back. Anything else is routable iff the
  392. full chain (built-in -> ``providers:`` -> ``custom_providers:`` -> models.dev) resolves it."""
  393. name = str(provider or "").strip()
  394. if not name or name.lower() == "auto":
  395. return True
  396. if name.lower() == "custom":
  397. return False
  398. try:
  399. from hermes_cli.providers import resolve_provider_full
  400. rp = _rp()
  401. config = rp.load_config()
  402. return resolve_provider_full(name, config.get("providers"), rp.get_compatible_custom_providers(config)) is not None
  403. except Exception:
  404. return False
  405. # ── runtime builders ───────────────────────────────────────────────────────────────────────
  406. def _owning_entry(rp, base_url: str, provider_name: Optional[str] = None) -> Optional[dict[str, Any]]:
  407. """The ``providers:`` entry that owns a custom endpoint, from the frozen route's config when the
  408. session froze one (a live edit then neither drops nor reassigns it)."""
  409. frozen = rp._FROZEN_RUNTIME_CONFIG.get()
  410. match = custom_entry_for_endpoint(base_url, provider_name, frozen)
  411. return match[1] if match else None
  412. def _owning_entry_credential(rp, base_url: str) -> tuple[bool, Any]:
  413. """``(declared, key)`` for a bare ``provider: custom`` route whose URL a ``providers:`` entry owns.
  414. ``declared`` is False when no entry owns the URL or it names no credential; the caller then keeps
  415. its implicit env fallbacks. Otherwise ``key`` is the entry's own (key_cmd first, as on the named
  416. path), or "" when it resolves to nothing: no other account's env key may stand in for it."""
  417. entry = _owning_entry(rp, base_url)
  418. if entry is None or not entry_declares_credential(entry):
  419. return False, ""
  420. return True, _entry_credential(rp, entry, str(entry.get("name") or "custom"))
  421. def _entry_credential(rp, entry: dict[str, Any], name: str) -> Any:
  422. """A ``providers:`` entry's own credential, for the named and the URL-matched bare routes alike:
  423. ``key_cmd`` (minted per request) first, else the first usable of ``api_key`` / ``key_env``, else "".
  424. A placeholder ``api_key`` never hides a working ``key_env``."""
  425. key_cmd = _clean(entry.get("key_cmd"))
  426. if key_cmd:
  427. from agent.command_token_source import build_command_token_provider
  428. if (token_provider := build_command_token_provider(key_cmd, name)) is not None:
  429. return token_provider
  430. candidates = (_clean(entry.get("api_key")), _key_env_secret(entry, f"custom provider '{name}'"))
  431. return next((c for c in candidates if rp.has_usable_secret(c)), "")
  432. def _try_resolve_from_custom_pool(
  433. base_url: str, provider_label: str, api_mode_override: Optional[str] = None, provider_name: Optional[str] = None,
  434. ) -> Optional[dict[str, Any]]:
  435. """Runtime dict from the first credential pool that owns this custom endpoint, else None. A pool
  436. the owning entry shares with a same-named built-in yields only the entry's rows (entry_scoped_pool)."""
  437. rp = _rp()
  438. try:
  439. # A frozen route's entry owns the pool, never the live one (a live URL edit would drop it).
  440. frozen = rp._FROZEN_RUNTIME_CONFIG.get()
  441. scope = {} if frozen is None else {"config": frozen}
  442. raw_keys = list(rp.custom_provider_pool_key_candidates(base_url, provider_name, **scope))
  443. owner = _owning_entry(rp, base_url, provider_name)
  444. except Exception:
  445. raw_keys, owner = [], None
  446. # Order-preserving dedupe of normalized keys.
  447. candidates = list(dict.fromkeys(k for k in (str(key or "").strip().lower() for key in raw_keys) if k))
  448. for pool_key in candidates:
  449. try:
  450. if (pool := entry_scoped_pool(rp.load_pool(pool_key), pool_key, owner)) is None:
  451. continue
  452. entry = pool.select() if pool.has_credentials() else None
  453. pool_api_key = rp._pool_entry_api_key(entry) if entry is not None else ""
  454. if not pool_api_key:
  455. continue
  456. if not rp.has_usable_secret(pool_api_key) and rp._loopback_hostname(base_url_hostname(base_url)):
  457. # Legacy configs used short placeholder keys ('123', 'm') for local no-auth
  458. # services; has_usable_secret's 4-char floor rejects them. Every other path
  459. # substitutes "no-key-required" for a loopback endpoint — this was the one gap.
  460. # Every OTHER resolution path in this file already substitutes "no-key-required" for a
  461. # loopback endpoint with no usable secret (the config-based custom_providers fallback a few
  462. # hundred lines below, and the "actual" provider's local-offline exemption further down) --
  463. # this pool path was the one gap (issue #86864).
  464. pool_api_key = "no-key-required"
  465. return rp._runtime(provider_label, api_mode_override or rp._detect_api_mode_for_url(base_url) or "chat_completions",
  466. base_url, pool_api_key, source=f"pool:{pool_key}", credential_pool=pool)
  467. except Exception:
  468. continue
  469. return None
  470. def _custom_provider_request_overrides(custom_provider: dict[str, Any]) -> dict[str, Any]:
  471. extra_body = custom_provider.get("extra_body")
  472. if not isinstance(extra_body, dict) or not extra_body:
  473. return {}
  474. return {"extra_body": dict(extra_body)}
  475. def _apply_custom_provider_extras(custom_provider: dict[str, Any], target_model: Optional[str], result: dict[str, Any]) -> None:
  476. """Copy model / capabilities / extra_headers / request_overrides onto a
  477. resolved custom runtime. An explicit ``target_model`` wins over the provider's configured
  478. default (auxiliary slots / background-review resolve a concrete model and must not fall back to
  479. ``default_model``). ``extra_headers`` may carry credentials — NEVER log them."""
  480. model_name = target_model or custom_provider.get("model")
  481. if model_name:
  482. result["model"] = model_name
  483. _lift_model_capabilities(custom_provider, model_name, result)
  484. if custom_provider.get("extra_headers"):
  485. result["extra_headers"] = dict(custom_provider["extra_headers"])
  486. request_overrides = _custom_provider_request_overrides(custom_provider)
  487. if request_overrides:
  488. result["request_overrides"] = {**(result.get("request_overrides") or {}), **request_overrides}
  489. class LocalRuntimeUnavailableError(ValueError):
  490. """The selected model is the managed local runtime and its server is not serving.
  491. Typed so readiness probes can say "configured, but the local server is down" instead of
  492. "nothing configured": provider onboarding cannot start a local server.
  493. """
  494. error_code = "local_runtime_unavailable"
  495. def __init__(self, message: str, *, retryable: bool = False) -> None:
  496. super().__init__(message)
  497. self.retryable = retryable
  498. def _resolve_llamacpp_runtime(requested_provider: str, explicit_api_key: Optional[str]) -> dict[str, Any]:
  499. """Managed llama.cpp runtime: the supervised (or detected external) server, or a typed error.
  500. No server => say so and stop; falling through to the generic custom path would surface "local
  501. server is off" as OpenRouter's baffling "401 Invalid API key". The switch's state picks the
  502. message (server off → point at the switch; else the setup pane)."""
  503. rp = _rp()
  504. try:
  505. from hermes_cli.local_runtime.endpoint import resolve_llamacpp_endpoint
  506. endpoint = resolve_llamacpp_endpoint(config=rp.load_config())
  507. except Exception:
  508. endpoint = None
  509. if endpoint:
  510. return rp._runtime("custom", "chat_completions", endpoint["base_url"],
  511. (explicit_api_key or "").strip() or endpoint["api_key"] or "no-key-required", source="local-runtime",
  512. requested_provider=requested_provider)
  513. try:
  514. enabled = bool((rp.load_config().get("local_runtime") or {}).get("enabled"))
  515. except Exception:
  516. enabled = False
  517. if enabled:
  518. raise LocalRuntimeUnavailableError("The local model server isn't running. It may still be "
  519. "starting — try again in a moment, or switch to another "
  520. "model with /model.", retryable=True)
  521. # Every chat surface (messaging, TUI, Webapp) shows this sentence, so it names both places a
  522. # user can start the server and no Desktop-only pane; the Desktop client links its pane itself.
  523. raise LocalRuntimeUnavailableError("The local model server is turned off. Start it from the Hermes "
  524. "desktop app or `hermes model` → Local models, or switch to "
  525. "another model with /model.")
  526. def _custom_runtime(rp, base_url: str, api_key: Any, api_mode: Optional[str], **extra: Any) -> dict[str, Any]:
  527. """``custom`` runtime dict with URL-detected api_mode fallback and the no-auth placeholder."""
  528. return rp._runtime("custom", api_mode or rp._detect_api_mode_for_url(base_url) or "chat_completions", base_url,
  529. api_key or "no-key-required", **extra)
  530. # Aliases for direct REST APIs not modeled in PROVIDER_REGISTRY, so ``provider: openai`` (aux slots,
  531. # background review, curator, MoA slots, the main model) resolves to a working ``custom`` endpoint
  532. # instead of "Unknown provider" and a silent fall-back to the main model (#116055).
  533. _DIRECT_API_BASE_URLS: dict[str, str] = {"openai": "https://api.openai.com/v1"}
  534. def expand_direct_api_alias(provider: Optional[str], existing_base: Optional[str]) -> tuple[Optional[str], Optional[str]]:
  535. """``provider: openai`` → custom + the user's OpenAI endpoint, api.openai.com/v1 only as the last resort.
  536. The ONE normalization both aux paths (``agent.auxiliary_client`` and ``resolve_runtime_provider``)
  537. apply, so the same ``auxiliary.<task>.provider`` value routes identically everywhere. A
  538. ``providers.openai`` entry keeps the provider name so the named-custom branch applies its base_url
  539. and key; otherwise ``OPENAI_BASE_URL`` (a proxy/gateway the OPENAI_API_KEY was issued for) wins over
  540. the public endpoint — sending the proxy key to api.openai.com 401s and then quarantines a valid key.
  541. """
  542. if not provider:
  543. return provider, existing_base
  544. target_base = _DIRECT_API_BASE_URLS.get(provider.strip().lower())
  545. if target_base is None or _rp()._get_named_custom_provider(provider) is not None:
  546. return provider, existing_base
  547. return "custom", (existing_base or "").strip() or get_secret_str("OPENAI_BASE_URL", "").strip().rstrip("/") or target_base
  548. def _resolve_direct_alias_runtime(requested_provider: str, explicit_api_key: Optional[str],
  549. explicit_base_url: str) -> dict[str, Any]:
  550. """Bare ``custom`` + explicit base_url (e.g. a ``model_aliases:`` direct alias)."""
  551. rp = _rp()
  552. base_url = explicit_base_url.strip().rstrip("/")
  553. # Pool first — mirrors the named-custom path so bare `provider: custom` with a configured
  554. # custom_providers entry gets its api_key from the pool instead of env fallbacks. An explicit
  555. # launch key still wins over the pool (R2-M1).
  556. explicit_key = (explicit_api_key or "").strip()
  557. pool_result = None if rp.has_usable_secret(explicit_key) else rp._try_resolve_from_custom_pool(base_url, "custom", None)
  558. if pool_result:
  559. pool_result["source"] = "direct-alias"
  560. return pool_result
  561. # OLLAMA_API_KEY gets its own gate here: without it a `model_aliases:` entry pointing at
  562. # Ollama Cloud resolved no key at all.
  563. # ``model.key_env`` only when this alias endpoint IS the configured model.base_url (#67453).
  564. # A ``providers:`` entry that owns the URL and declares a credential supplies it instead of
  565. # the host-gated env keys (on the entry's built-in's host those are another account's).
  566. declared, entry_key = _owning_entry_credential(rp, base_url)
  567. candidates = [(explicit_api_key or "").strip(), _model_cfg_key_env_for(rp._get_model_config(), base_url),
  568. *([] if declared else rp._host_gated_env_key_candidates(base_url, ollama=True))]
  569. api_key = next((c for c in candidates if rp.has_usable_secret(c)), "") or entry_key
  570. return _custom_runtime(rp, base_url, api_key, None, source="direct-alias", requested_provider=requested_provider)
  571. def _opencode_family_for_custom(requested_provider: str, base_url: str) -> Optional[str]:
  572. """OpenCode family by provider name, else by opencode.ai host (``/zen/go`` => opencode-go)."""
  573. # Custom providers in the OpenCode family (name extends opencode-go/zen, or base_url hosted on
  574. # opencode.ai) serve models behind different API surfaces per model — a static api_mode 503s for
  575. # /v1/responses-only models like grok-4.5 (#85589). Re-derive api_mode from the effective model and
  576. # normalize the /v1 suffix, exactly like the built-in opencode-zen/go paths do.
  577. from hermes_cli.models import opencode_provider_family
  578. family = opencode_provider_family(requested_provider)
  579. if family is not None:
  580. return family
  581. try:
  582. if base_url_hostname(base_url).lower() == "opencode.ai":
  583. return "opencode-go" if "/zen/go" in base_url.lower() else "opencode-zen"
  584. except Exception:
  585. pass
  586. return None
  587. def _resolve_named_custom_runtime(*, requested_provider: str, explicit_api_key: Optional[str] = None,
  588. explicit_base_url: Optional[str] = None,
  589. target_model: Optional[str] = None, config=None) -> Optional[dict[str, Any]]:
  590. """Runtime for a llamacpp alias, a bare-custom direct alias, or a configured custom entry.
  591. Aliases resolving to "custom" (ollama, vllm, llamacpp, …) are treated like bare ``custom``. A
  592. llamacpp alias with no explicit base_url resolves to the managed server first; an explicit
  593. base_url always wins."""
  594. rp = _rp()
  595. # Bare `provider="custom"` with an explicit base_url (e.g. propagated from a `model_aliases:`
  596. # direct-alias resolution) — build a runtime directly so the alias's base_url actually takes effect.
  597. # GitHub #27132: provider aliases that resolve to "custom" at runtime (ollama, vllm, llamacpp, …) are
  598. # treated identically here, so a YAML `provider: ollama` with a LAN/WireGuard `base_url` doesn't
  599. # silently fall through to OpenRouter.
  600. requested_norm = (requested_provider or "").strip().lower()
  601. custom_provider = None
  602. if requested_norm in _LLAMACPP_ALIASES and not explicit_base_url:
  603. custom_provider = rp._get_named_custom_provider(requested_provider)
  604. if not custom_provider:
  605. return _resolve_llamacpp_runtime(requested_provider, explicit_api_key)
  606. if requested_norm and requested_norm != "custom" and rp._resolves_to_custom(requested_norm):
  607. requested_norm = "custom"
  608. if requested_norm == "custom" and explicit_base_url:
  609. return _resolve_direct_alias_runtime(requested_provider, explicit_api_key, explicit_base_url)
  610. if custom_provider is None:
  611. custom_provider = (rp._get_named_custom_provider(requested_provider) if config is None
  612. else _get_named_custom_provider(requested_provider, config=config))
  613. if not custom_provider:
  614. return None
  615. base_url = ((explicit_base_url or "").strip() or custom_provider.get("base_url", "")).rstrip("/")
  616. if not base_url:
  617. return None
  618. explicit_key = (explicit_api_key or "").strip()
  619. # The credential pool is the profile's auth store (``hermes auth add``), not config: a frozen
  620. # config snapshot still owes a pooled ``providers:`` entry its keys, or the turn ships the
  621. # ``no-key-required`` placeholder to a host that wants one (C11 pool rows). An explicit launch
  622. # key is the operator's credential for this route and wins over the pool (R2-M1). An entry
  623. # that names its own credential never borrows a same-named built-in's env-seeded pool rows.
  624. pool_result = None if rp.has_usable_secret(explicit_key) else rp._try_resolve_from_custom_pool(
  625. base_url, "custom", custom_provider.get("api_mode"),
  626. provider_name=custom_provider.get("provider_key") or custom_provider.get("name"),
  627. )
  628. if pool_result:
  629. # The pool doesn't know the custom_providers fields — propagate them here too.
  630. _apply_custom_provider_extras(custom_provider, target_model, pool_result)
  631. return pool_result
  632. # An explicit --api-key wins as the one-off recovery escape hatch. ``key_cmd`` credentials are
  633. # minted per request (short-lived bearers would go stale mid-session); both wire clients accept a
  634. # callable api_key (the Entra ID contract). A declared credential that resolves to nothing gets no
  635. # implicit host-gated env key: on the entry's built-in's host that is another account's key.
  636. api_key: Any = explicit_key if rp.has_usable_secret(explicit_key) else (
  637. _entry_credential(rp, custom_provider, str(custom_provider.get("name", requested_provider) or "custom"))
  638. or next((c for c in ([] if entry_declares_credential(custom_provider)
  639. else rp._host_gated_env_key_candidates(base_url, ollama=False)) if rp.has_usable_secret(c)), ""))
  640. result = _custom_runtime(rp, base_url, api_key, custom_provider.get("api_mode"),
  641. source=f"custom_provider:{custom_provider.get('name', requested_provider)}",
  642. requested_provider=requested_provider)
  643. _apply_custom_provider_extras(custom_provider, target_model, result)
  644. # OpenCode-family custom providers (opencode-go/zen names, or opencode.ai hosts) serve models
  645. # on different API surfaces — a static api_mode 503s for /v1/responses-only models. Re-derive
  646. # api_mode from the model and normalize /v1 like the built-in paths.
  647. family = _opencode_family_for_custom(requested_provider, base_url)
  648. if family is not None and not custom_provider.get("api_mode"):
  649. from hermes_cli.models import normalize_opencode_base_url, opencode_model_api_mode
  650. effective_model = str(target_model or custom_provider.get("model") or rp._get_model_config().get("default") or "").strip()
  651. if effective_model:
  652. result["api_mode"] = opencode_model_api_mode(family, effective_model)
  653. result["base_url"] = normalize_opencode_base_url(family, result["api_mode"], result["base_url"])
  654. return result