config_env.py 56 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122
  1. """Config, env var and provider custom-endpoint dashboard routes.
  2. Extracted from ``hermes_cli.web_server``; helpers/state that tests monkeypatch on
  3. ``web_server`` stay there and are late-bound (cycle-safe).
  4. """
  5. import contextlib
  6. import logging
  7. import re
  8. import asyncio
  9. import time
  10. import urllib.parse
  11. from fastapi import APIRouter
  12. from hermes_cli.web_routers._common import (
  13. REDACTED_CREDENTIAL_WRITE_DETAIL, config_scoped_to_thread, http_failure,
  14. is_redacted_credential_preview, redacted_credential_preview, scoped_to_thread,
  15. )
  16. from hermes_cli.config_backend import refusing_locked_omissions
  17. from hermes_cli.web_deps import LateState, late
  18. from hermes_cli.web_server_config import (
  19. _apply_main_model_assignment, _denormalize_config_from_web, drop_model_key, _normalize_config_for_web, _schema_with_dynamic_provider_options,
  20. _validated_main_model_selection,
  21. )
  22. from hermes_cli.web_server_profiles import (
  23. _approval_mode_of, _broadcast_gateway_session_info, _is_other_profile, _parse_model_entries,
  24. )
  25. from fastapi import HTTPException, Request
  26. from hermes_cli.config import DEFAULT_CONFIG, OPTIONAL_ENV_VARS, read_raw_config, require_readable_config_before_write, custom_endpoint_key_env, coerce_provider_id, find_provider_entry, get_compatible_custom_providers, _ENV_REF_RE, _deep_merge
  27. from hermes_cli.config_providers import _canonical_api_mode, _custom_provider_entry_to_provider_config
  28. from hermes_cli.web_models import ConfigUpdate, EnvVarUpdate, EnvVarDelete, EnvVarReveal, CustomEndpointUpdate
  29. from typing import Any, Dict, List, Optional, Tuple
  30. _log = logging.getLogger("hermes_cli.web_server")
  31. config_router = APIRouter()
  32. router = APIRouter()
  33. # Late-bound so a test's monkeypatch on the owning module wins at call time.
  34. _channel_managed_env_keys = late("_channel_managed_env_keys", "hermes_cli.web_server_messaging")
  35. _config_profile_scope = late("_config_profile_scope", "hermes_cli.web_server_profiles")
  36. _profile_scope = late("_profile_scope", "hermes_cli.web_server_profiles")
  37. _require_token = late("_require_token")
  38. load_config = late("load_config", "hermes_cli.config")
  39. load_env = late("load_env", "hermes_cli.config")
  40. remove_env_value = late("remove_env_value", "hermes_cli.config")
  41. save_config = late("save_config", "hermes_cli.config")
  42. save_env_value = late("save_env_value", "hermes_cli.config")
  43. _CONFIG_MUTATION_LOCK = LateState("_CONFIG_MUTATION_LOCK")
  44. # Simple rate limiter for the reveal endpoint
  45. _reveal_timestamps: list[float] = []
  46. _REVEAL_MAX_PER_WINDOW = 5
  47. _REVEAL_WINDOW_SECONDS = 30
  48. # Display order for tabs — unlisted categories sort alphabetically after these.
  49. _CATEGORY_ORDER = [
  50. "general", "agent", "terminal", "display", "delegation",
  51. "memory", "compression", "security", "browser", "voice",
  52. "tts", "stt", "logging", "discord", "auxiliary",
  53. ]
  54. @contextlib.contextmanager
  55. def _env_write_errors(log_msg: str):
  56. """``ValueError`` -> 400 with its message (save/remove_env_value reject
  57. invalid names and denylisted keys — LD_PRELOAD, PATH, PYTHONPATH, …, the
  58. credential lifecycle rejects keys a managed install or administrator pins,
  59. and the SPA needs the reason, not an opaque 500); ``HTTPException`` (the
  60. profile scope's 404 for an unknown ``?profile=``) passes through; anything
  61. else is logged and becomes 500 "Internal server error"."""
  62. try:
  63. yield
  64. except HTTPException:
  65. raise
  66. except ValueError as exc:
  67. raise HTTPException(status_code=400, detail=str(exc)) from exc
  68. except Exception:
  69. _log.exception(log_msg)
  70. raise HTTPException(status_code=500, detail="Internal server error")
  71. @config_router.get("/api/config")
  72. async def get_config(profile: Optional[str] = None, include_defaults: bool = True):
  73. # _profile_scope blocks on the process-wide _SKILLS_PROFILE_LOCK and
  74. # load_config() reads from disk; a slow lock-holder on the event loop froze
  75. # the whole gateway for >1s. asyncio.to_thread copies the contextvar
  76. # context, so the profile override stays scoped to the worker thread.
  77. # Opt in to saved values so clients can distinguish user choices from defaults.
  78. config = await scoped_to_thread(
  79. profile, lambda: _normalize_config_for_web(load_config() if include_defaults else read_raw_config())
  80. )
  81. # Strip internal keys that the frontend shouldn't see or send back
  82. return {k: v for k, v in config.items() if not k.startswith("_")}
  83. @config_router.get("/api/config/defaults")
  84. async def get_defaults():
  85. return DEFAULT_CONFIG
  86. @config_router.get("/api/config/schema")
  87. async def get_schema(profile: Optional[str] = None):
  88. # Discovery-driven provider options (voice command providers + memory
  89. # provider plugins) are merged per-request so providers added after server
  90. # start still show up, scoped to the requested profile's config. That merge
  91. # walks the schema and scans plugin dirs on disk, so it runs on a worker
  92. # thread: on the event loop it froze every other request — including
  93. # /api/ws — for as long as the scan took. asyncio.to_thread copies the
  94. # contextvar context, so the profile override stays scoped to the worker.
  95. fields = await config_scoped_to_thread(profile, _schema_with_dynamic_provider_options)
  96. return {"fields": fields, "category_order": _CATEGORY_ORDER}
  97. @config_router.get("/api/egress/status")
  98. async def get_egress_status(profile: Optional[str] = None):
  99. """Dashboard/Desktop-readable egress proxy status and remediation text."""
  100. from hermes_cli.proxy_cli import format_status_text
  101. # Reads the profile's ``proxy:`` config block from disk; on the event loop
  102. # that read stalled every other dashboard request for its duration.
  103. return {"text": await config_scoped_to_thread(profile, format_status_text)}
  104. @router.put("/api/config")
  105. async def update_config(
  106. body: ConfigUpdate, profile: Optional[str] = None, preserve_language: bool = False
  107. ):
  108. def _run():
  109. approvals_mode_changed = False
  110. with _profile_scope(body.profile or profile):
  111. # The dashboard form is schema-driven; root keys absent from the
  112. # schema (``custom_providers``, ``agent.personalities``, ...) are not
  113. # in the PUT body, so deep-merge incoming over disk rather than
  114. # full-replace — the frontend can only overwrite what it sends.
  115. with _CONFIG_MUTATION_LOCK:
  116. # Strict read: the merge below builds a new dict, so a swallowed read error here
  117. # would save the PUT body alone over the whole file.
  118. existing = require_readable_config_before_write()
  119. incoming = _denormalize_config_from_web(body.config)
  120. merged = _deep_merge(existing, incoming)
  121. # Compare normalized approvals.mode across the in-memory
  122. # documents, not config blocks and not cache re-reads: the page
  123. # PUTs the defaulted GET record while disk holds sparse YAML (a
  124. # block compare is always-unequal), and a post-save reload can
  125. # serve the pre-save cache on an (mtime_ns, size) collision.
  126. # Only approvals.mode feeds session.info, so it is the trigger.
  127. approvals_mode_changed = _approval_mode_of(merged) != _approval_mode_of(existing)
  128. # Explicit English must survive default stripping: an absent
  129. # language lets the desktop follow the OS on its next launch.
  130. # Ordinary settings saves include merged defaults, not a choice.
  131. save_config(
  132. merged, preserve_keys={("display", "language")} if preserve_language else None
  133. )
  134. # REST saves bypass the config.set RPC (which re-emits itself), so
  135. # refresh live sessions' cached approval/YOLO indicators after a mode
  136. # change. Own-profile saves only: a profile-scoped save targets a
  137. # different HERMES_HOME than this process's gateway sessions.
  138. if approvals_mode_changed and not _is_other_profile(body.profile or profile):
  139. _broadcast_gateway_session_info()
  140. return {"ok": True}
  141. with http_failure("PUT /api/config failed", 500, detail="Internal server error"):
  142. return await asyncio.to_thread(_run)
  143. def _provider_card(d, description: str, url, *, is_password: bool, advanced: bool) -> dict:
  144. return {
  145. "provider": d.slug, "provider_label": d.label, "description": description, "url": url,
  146. "is_password": is_password, "advanced": advanced, "category": "provider",
  147. }
  148. _AUTH_TYPE_ENV_VARS = {
  149. "aws_sdk": (
  150. ("AWS_REGION", lambda d, var: f"{d.label} ({var})"),
  151. ("AWS_PROFILE", lambda d, var: f"{d.label} ({var})"),
  152. ),
  153. "vertex": (("VERTEX_CREDENTIALS_PATH", lambda d, var: f"{d.label} — service account JSON path (or use ADC)"),),
  154. }
  155. def _catalog_provider_env_metadata() -> dict:
  156. """Map provider env vars -> desktop card metadata, derived from the catalog.
  157. Returns ``{env_var: {provider, provider_label, description, url, is_password,
  158. advanced}}`` for every API-key provider in the unified ``provider_catalog()``
  159. (the ``hermes model`` universe). When multiple providers intentionally share
  160. one env var, ``provider_profiles`` preserves every provider identity while
  161. the legacy singular fields keep describing the first provider. Hand
  162. ``OPTIONAL_ENV_VARS`` prose is layered on top in the endpoint; this only
  163. supplies membership + grouping + fallbacks.
  164. """
  165. try:
  166. from hermes_cli.provider_catalog import provider_catalog
  167. except Exception:
  168. return {}
  169. # Env vars declared with a NON-provider category (e.g. the shared
  170. # GITHUB_TOKEN, a Skills-Hub "tool" credential) must not be promoted into a
  171. # provider card even when a provider lists them as auth aliases.
  172. _non_provider_keys = {
  173. k for k, v in OPTIONAL_ENV_VARS.items()
  174. if (v or {}).get("category") and (v or {}).get("category") != "provider"
  175. }
  176. meta: dict = {}
  177. def _profile(entry: dict) -> dict:
  178. """Return the provider-specific part of a shared credential row."""
  179. return {
  180. "provider": entry["provider"],
  181. "provider_label": entry["provider_label"],
  182. "description": entry["description"],
  183. "url": entry["url"],
  184. "primary": bool(entry.get("provider_primary")),
  185. }
  186. def _add_provider_env(env_var: str, entry: dict) -> None:
  187. """Add one provider without discarding peers that share ``env_var``."""
  188. existing = meta.get(env_var)
  189. if existing is None:
  190. meta[env_var] = entry
  191. return
  192. if existing.get("provider") == entry.get("provider"):
  193. return
  194. profiles = existing.setdefault("provider_profiles", [_profile(existing)])
  195. if not any(profile.get("provider") == entry.get("provider") for profile in profiles):
  196. profiles.append(_profile(entry))
  197. for d in provider_catalog():
  198. if d.tab != "keys":
  199. continue
  200. # API-key vars: the first is the primary (password) field; aliases are
  201. # kept as additional password fields so users can clear them too.
  202. for index, env_var in enumerate(d.api_key_env_vars):
  203. if env_var in _non_provider_keys:
  204. continue # don't hijack a shared tool/messaging credential
  205. entry = _provider_card(
  206. d, d.description, d.signup_url or None, is_password=True, advanced=False,
  207. )
  208. entry["provider_primary"] = index == 0
  209. _add_provider_env(
  210. env_var,
  211. entry,
  212. )
  213. # Base-URL override is an advanced, non-secret field for the same card.
  214. if d.base_url_env_var:
  215. meta.setdefault(
  216. d.base_url_env_var,
  217. _provider_card(d, f"{d.label} base URL override", None, is_password=False, advanced=True),
  218. )
  219. # Providers without api_key_env_vars would otherwise be invisible on
  220. # the Keys tab: AWS-SDK providers (Bedrock) authenticate via the AWS
  221. # credential chain, Vertex via OAuth2 (service-account JSON path or
  222. # ADC — a path, not a secret). Tag their env vars to the card.
  223. for var, describe in _AUTH_TYPE_ENV_VARS.get(d.auth_type, ()):
  224. existing = meta.get(var, {})
  225. meta[var] = _provider_card(
  226. d, existing.get("description") or describe(d, var), existing.get("url"),
  227. is_password=False, advanced=existing.get("advanced", True),
  228. )
  229. return meta
  230. @router.get("/api/env")
  231. async def get_env_vars(profile: Optional[str] = None):
  232. # _profile_scope takes _SKILLS_PROFILE_LOCK and load_env()/catalog
  233. # discovery read from disk — keep the whole build off the event loop.
  234. return await asyncio.to_thread(_get_env_vars_sync, profile)
  235. def _get_env_vars_sync(profile: Optional[str] = None):
  236. with _profile_scope(profile):
  237. env_on_disk = load_env()
  238. channel_keys = _channel_managed_env_keys()
  239. catalog_meta = _catalog_provider_env_metadata()
  240. def _row(var_name: str, info: dict, *, custom: bool = False) -> dict:
  241. value = env_on_disk.get(var_name)
  242. cat_meta = catalog_meta.get(var_name) or {}
  243. # Hand OPTIONAL_ENV_VARS prose wins where present; the catalog fills any
  244. # gaps (description/url) and always supplies provider grouping hints.
  245. return {
  246. "is_set": bool(value),
  247. "redacted_value": redacted_credential_preview(value),
  248. "description": info.get("description") or cat_meta.get("description", ""),
  249. "url": info.get("url") if info.get("url") is not None else cat_meta.get("url"),
  250. "category": info.get("category") or cat_meta.get("category", ""),
  251. "is_password": info.get("password", cat_meta.get("is_password", False)),
  252. "tools": info.get("tools", []),
  253. "advanced": info.get("advanced", cat_meta.get("advanced", False)),
  254. # Messaging-platform credential owned by a Channels page card; the
  255. # Keys/Env page hides it rather than duplicate the richer UI.
  256. "channel_managed": var_name in channel_keys,
  257. # Provider grouping from the unified catalog, so the desktop groups
  258. # by the SAME provider identity the CLI `hermes model` picker uses.
  259. "provider": cat_meta.get("provider", ""),
  260. "provider_label": cat_meta.get("provider_label", ""),
  261. # One credential can intentionally serve multiple built-in routes.
  262. # Preserve those identities so Desktop can render distinct cards
  263. # that edit the same underlying env var.
  264. "provider_profiles": cat_meta.get("provider_profiles", []),
  265. # The provider's own index-0 credential flag. Desktop picks a card's
  266. # main "Paste key" field from this FIRST, so a shared alias that a
  267. # peer profile contributes (DASHSCOPE_API_KEY for the CN Coding /
  268. # Token Plan cards) can never re-point the card's primary field.
  269. "provider_primary": bool(cat_meta.get("provider_primary", False)),
  270. # True for a .env key in no catalog at all — an arbitrary/custom var
  271. # the user added directly, listed so the Keys page can manage it.
  272. "custom": custom,
  273. }
  274. result = {}
  275. for var_name, info in OPTIONAL_ENV_VARS.items():
  276. result[var_name] = _row(var_name, info)
  277. # Catalog provider env vars with no hand entry in OPTIONAL_ENV_VARS.
  278. for var_name in catalog_meta:
  279. if var_name not in result:
  280. result[var_name] = _row(var_name, {})
  281. # Custom keys from .env: always "set" (on disk), treated as secrets by
  282. # default (is_password=True -> redacted, reveal-gated) since an
  283. # unrecognised key could hold anything. Channel-managed credentials belong
  284. # to the Channels page. A key added via "add a custom key" round-trips here.
  285. for var_name in env_on_disk:
  286. if var_name in result or var_name in channel_keys:
  287. continue
  288. row = _row(var_name, {}, custom=True)
  289. row["category"] = "custom"
  290. row["is_password"] = True
  291. result[var_name] = row
  292. return result
  293. @router.put("/api/env")
  294. async def set_env_var(body: EnvVarUpdate, profile: Optional[str] = None):
  295. # Unified credential lifecycle: writes .env AND reconciles any config.yaml
  296. # mirror still holding the previous value of this var (model.api_key /
  297. # auxiliary.*.api_key / custom_providers[*]), so a rotation can't leave a
  298. # stale higher-precedence copy that keeps authenticating with the old key.
  299. # Display-only previews (sentinel or legacy mask) must never gain write authority.
  300. if is_redacted_credential_preview(body.value):
  301. raise HTTPException(status_code=400, detail=REDACTED_CREDENTIAL_WRITE_DETAIL)
  302. with _env_write_errors("PUT /api/env failed"):
  303. return await scoped_to_thread(body.profile or profile, lambda: _save_env_credential(body.key, body.value, body.provider_setup))
  304. def _save_env_credential(key: str, value: str, provider_setup: bool = False) -> Any:
  305. """Save under the request's profile scope; a new provider API key also counts as a provider setup."""
  306. from hermes_cli.config import load_env
  307. from hermes_cli.credential_lifecycle import save_provider_env_credential
  308. from hermes_cli.observability.shared_metrics_setup import record_api_key_saved, web_setup_surface
  309. previous = load_env().get(key)
  310. result = save_provider_env_credential(key, value)
  311. record_api_key_saved(key, value, previous, web_setup_surface(), connecting=provider_setup)
  312. return result
  313. # Live credential probes keyed by env var: (url, auth) where auth is "bearer"
  314. # (Authorization header) or "query" (?key=). A cheap read-only call that 401s
  315. # on a bad token — enough to catch a mistyped key before it's persisted.
  316. # Providers absent here (or local endpoints) are not network-validated; the
  317. # client treats those as "unknown".
  318. _CREDENTIAL_PROBES: dict[str, tuple[str, str]] = {
  319. "OPENROUTER_API_KEY": ("https://openrouter.ai/api/v1/key", "bearer"),
  320. "OPENAI_API_KEY": ("https://api.openai.com/v1/models", "bearer"),
  321. "XAI_API_KEY": ("https://api.x.ai/v1/models", "bearer"),
  322. "GEMINI_API_KEY": ("https://generativelanguage.googleapis.com/v1beta/models", "query"),
  323. }
  324. def _custom_endpoint_id(raw: str, fallback: str = "custom") -> str:
  325. slug = re.sub(r"[^A-Za-z0-9_-]+", "-", coerce_provider_id(raw)).strip("-_").lower()
  326. return slug or fallback
  327. def _resolve_custom_endpoint_entry(providers: Any, endpoint_id: str) -> tuple[Any, Optional[dict[str, Any]]]:
  328. """Resolve a custom endpoint id using the stored key first, then its legacy slug.
  329. The list route hands Desktop the literal ``providers.<key>`` (a v11→v12
  330. migration keeps dots/colons from the display name: ``local-127.0.0.1:8283``;
  331. hand-written keys keep their case), so that spelling must round-trip
  332. unchanged. Slugging is only the compatibility path for callers that still
  333. send an unslugged display name.
  334. """
  335. stored_key, entry = find_provider_entry(providers, endpoint_id)
  336. if entry is not None:
  337. return stored_key, entry
  338. normalized_key = _custom_endpoint_id(endpoint_id)
  339. if normalized_key == endpoint_id:
  340. return None, None
  341. return find_provider_entry(providers, normalized_key)
  342. def _models_from_custom_endpoint_entry(entry: dict[str, Any]) -> list[str]:
  343. models: list[str] = []
  344. raw_models = entry.get("models")
  345. if isinstance(raw_models, (dict, list)):
  346. models.extend(str(model).strip() for model in raw_models)
  347. default_model = str(entry.get("model") or entry.get("default_model") or "").strip()
  348. if default_model:
  349. models.insert(0, default_model)
  350. seen: set[str] = set()
  351. return [model for model in models if model and not (model in seen or seen.add(model))]
  352. def _api_key_display(entry: dict[str, Any]) -> tuple[bool, Optional[str]]:
  353. """Return ``(has_api_key, preview)`` for a provider or model config block.
  354. Keys live in ``.env`` behind ``key_env``; only older entries still carry a
  355. plaintext ``api_key``. Checking both keeps the panel honest either way.
  356. See #69449.
  357. """
  358. plaintext = str(entry.get("api_key") or "").strip()
  359. if plaintext:
  360. return True, redacted_credential_preview(plaintext)
  361. key_env = str(entry.get("key_env") or "").strip()
  362. if key_env:
  363. return True, f"${{{key_env}}}"
  364. return False, None
  365. def _raw_provider_api_key(endpoint_id: str) -> Any:
  366. """The on-disk (un-expanded) ``api_key`` of a providers entry, or ``None``."""
  367. _stored, entry = find_provider_entry(read_raw_config().get("providers"), endpoint_id)
  368. return entry.get("api_key") if isinstance(entry, dict) else None
  369. def _config_api_key_is_env_ref(endpoint_id: str) -> bool:
  370. """True when this endpoint's on-disk ``api_key`` is a ``${VAR}`` template.
  371. ``load_config()`` expands env refs, so a hand-written ``api_key: ${MY_KEY}``
  372. is indistinguishable from a literal secret by the time it reaches us. Such
  373. an entry already keeps its secret out of config.yaml, so migrating it would
  374. only copy that secret into a second env var the user didn't ask for.
  375. """
  376. raw_key = _raw_provider_api_key(endpoint_id)
  377. return bool(isinstance(raw_key, str) and re.search(r"\$\{[^}]+\}", raw_key))
  378. _DESKTOP_API_MODES = {"chat_completions", "codex_responses", "anthropic_messages"}
  379. def _endpoint_api_mode(entry: dict[str, Any]) -> str:
  380. """The transport a providers entry pins (``api_mode``, or the v12 migration's ``transport``
  381. spelling), canonicalized; ``""`` = runtime auto-detect. Mirrors the read order of
  382. ``runtime_provider_custom._get_named_custom_provider``."""
  383. raw = str(entry.get("api_mode") or entry.get("transport") or "")
  384. mode = _canonical_api_mode(raw).lower()
  385. return mode if mode in _DESKTOP_API_MODES else ""
  386. def _endpoint_row(
  387. endpoint_id: str, name: str, base_url: str, model: str, models: list[str], context_length,
  388. discover_models: bool, key_entry: dict[str, Any], is_current: bool, source: str,
  389. ) -> dict[str, Any]:
  390. has_api_key, api_key_preview = _api_key_display(key_entry)
  391. return {
  392. "id": endpoint_id, "name": name, "base_url": base_url, "model": model, "models": models,
  393. "api_mode": _endpoint_api_mode(key_entry),
  394. "context_length": context_length, "discover_models": discover_models,
  395. "has_api_key": has_api_key, "api_key_preview": api_key_preview,
  396. "is_current": is_current, "source": source,
  397. }
  398. def _model_names_provider(model_cfg: dict[str, Any], provider_key: str, entry: Optional[dict[str, Any]]) -> bool:
  399. """True when ``model.provider`` points at this ``providers`` entry.
  400. ``switch_model`` spells the active provider either as the stored key or as
  401. ``custom:<lowercased name>``; the list's ``is_current`` and delete's mirror
  402. detach must accept both, or a mixed-case key activates but never shows as
  403. active.
  404. """
  405. names = {coerce_provider_id(provider_key).lower()}
  406. if isinstance(entry, dict) and coerce_provider_id(entry.get("name")):
  407. names.add(coerce_provider_id(entry.get("name")).lower())
  408. current = str(model_cfg.get("provider") or "").strip().lower()
  409. return current.removeprefix("custom:") in names
  410. def _custom_endpoint_response(cfg: dict[str, Any]) -> dict[str, Any]:
  411. model_cfg = cfg.get("model", {}) if isinstance(cfg.get("model"), dict) else {}
  412. current_provider = str(model_cfg.get("provider", "") or "")
  413. current_model = str(model_cfg.get("default", model_cfg.get("name", "")) or "")
  414. current_base_url = str(model_cfg.get("base_url", "") or "")
  415. endpoints: list[dict[str, Any]] = []
  416. providers = cfg.get("providers")
  417. if isinstance(providers, dict):
  418. for provider_id, raw_entry in providers.items():
  419. if not isinstance(raw_entry, dict):
  420. continue
  421. base_url = str(raw_entry.get("base_url") or raw_entry.get("url") or raw_entry.get("api") or "").strip()
  422. if not base_url:
  423. continue
  424. endpoint_id = str(provider_id)
  425. models = _models_from_custom_endpoint_entry(raw_entry)
  426. endpoints.append(_endpoint_row(
  427. endpoint_id, str(raw_entry.get("name") or endpoint_id), base_url,
  428. str(raw_entry.get("model") or raw_entry.get("default_model") or (models[0] if models else "")),
  429. models, raw_entry.get("context_length"), bool(raw_entry.get("discover_models", True)),
  430. raw_entry, _model_names_provider(model_cfg, endpoint_id, raw_entry), "providers",
  431. ))
  432. # Legacy ``custom_providers:`` list entries the migration left behind are
  433. # still routed at runtime (get_compatible_custom_providers), so they need a
  434. # row too, or the panel hides an endpoint the agent can pick. Entries from
  435. # ``providers:`` carry ``provider_key``; the legacy ones do not. A bare
  436. # ``provider: custom`` main slot is "current" for the legacy row whose
  437. # base_url it points at.
  438. is_bare_custom = current_provider.lower() == "custom" and bool(current_base_url)
  439. seen_ids = {e["id"] for e in endpoints}
  440. for entry in get_compatible_custom_providers(cfg):
  441. if entry.get("provider_key"):
  442. continue
  443. endpoint_id = _custom_endpoint_id(entry["name"])
  444. if endpoint_id in seen_ids:
  445. continue
  446. seen_ids.add(endpoint_id)
  447. models = _models_from_custom_endpoint_entry(entry)
  448. is_current = is_bare_custom and entry["base_url"].rstrip("/") == current_base_url.rstrip("/")
  449. endpoints.append(_endpoint_row(
  450. endpoint_id, entry["name"], entry["base_url"],
  451. str(entry.get("model") or (models[0] if models else "")), models,
  452. entry.get("context_length"), bool(entry.get("discover_models", True)),
  453. entry, is_current, "custom_providers",
  454. ))
  455. if is_bare_custom and not any(e["id"] == "custom" or e["is_current"] for e in endpoints):
  456. endpoints.insert(0, _endpoint_row(
  457. "custom", "Custom", current_base_url, current_model, [current_model] if current_model else [],
  458. model_cfg.get("context_length"), True, model_cfg, True, "direct-config",
  459. ))
  460. return {
  461. "endpoints": endpoints,
  462. "current": {
  463. "provider": current_provider, "model": current_model, "base_url": current_base_url,
  464. },
  465. }
  466. def _pop_legacy_custom_provider(cfg: dict[str, Any], provider_key: str) -> Optional[dict[str, Any]]:
  467. """Remove and return the legacy ``custom_providers:`` list entry whose name slugs to *provider_key*."""
  468. legacy = cfg.get("custom_providers")
  469. if not isinstance(legacy, list):
  470. return None
  471. for index, entry in enumerate(legacy):
  472. if isinstance(entry, dict) and _custom_endpoint_id(str(entry.get("name") or "")) == provider_key:
  473. return legacy.pop(index)
  474. return None
  475. def _detach_main_model_from_provider(cfg: dict[str, Any], provider_key: str, entry: Optional[dict[str, Any]] = None) -> None:
  476. """Drop the main-slot mirror of a provider that no longer exists.
  477. ``activate_custom_endpoint`` copies the endpoint's ``base_url`` and
  478. ``api_key`` onto ``model``; that mirror outranks the environment at client
  479. construction, so deleting the endpoint without clearing it leaves the agent
  480. authenticating to the deleted host with the deleted key (and the key in
  481. config.yaml). Only touches ``model`` when it names the deleted provider —
  482. ``switch_model`` spells that either as the stored key or as
  483. ``custom:<lowercased name>``, so both spellings count.
  484. See #62269.
  485. """
  486. model_cfg = cfg.get("model")
  487. if not isinstance(model_cfg, dict) or not _model_names_provider(model_cfg, provider_key, entry):
  488. return
  489. for field in ("provider", "base_url", "api_key", "key_env"):
  490. model_cfg.pop(field, None)
  491. cfg["model"] = model_cfg
  492. def _write_custom_endpoint(cfg: dict[str, Any], body: CustomEndpointUpdate) -> tuple[str, dict[str, Any]]:
  493. name = (body.name or "").strip()
  494. base_url = (body.base_url or "").strip().rstrip("/")
  495. model = (body.model or "").strip()
  496. if not name:
  497. raise HTTPException(status_code=400, detail="name required")
  498. if not base_url:
  499. raise HTTPException(status_code=400, detail="base_url required")
  500. try:
  501. parsed = urllib.parse.urlparse(base_url)
  502. except ValueError as exc:
  503. raise HTTPException(status_code=400, detail="base_url must include scheme and host") from exc
  504. if not parsed.scheme or not parsed.netloc:
  505. raise HTTPException(status_code=400, detail="base_url must include scheme and host")
  506. if not model:
  507. raise HTTPException(status_code=400, detail="model required")
  508. # Deliver the bearer token through a named provider entry. A bare ``provider: custom`` cannot carry a
  509. # credential for this host: OPENAI_API_KEY is deliberately gated to openai.com (#28660), so the token
  510. # was dropped and requests went out as "no-key-required".
  511. providers = cfg.get("providers")
  512. if not isinstance(providers, dict):
  513. providers = {}
  514. # An edit payload carries the stored key verbatim; slugging it first would
  515. # miss the entry and fork a slugged twin next to the original.
  516. stored_key, existing = _resolve_custom_endpoint_entry(providers, body.id or body.name)
  517. endpoint_id = coerce_provider_id(stored_key) if existing is not None else _custom_endpoint_id(body.id or body.name)
  518. if existing is None:
  519. # Settings saves the row the list rendered. A legacy custom_providers
  520. # entry is not in providers, so resolving only there forked a keyless
  521. # twin and left the list row (and its key_env) behind.
  522. from hermes_cli.config_providers import _custom_provider_entry_to_provider_config
  523. legacy = _pop_legacy_custom_provider(cfg, endpoint_id)
  524. converted = (
  525. _custom_provider_entry_to_provider_config(legacy, provider_key=endpoint_id)
  526. if legacy is not None else None
  527. )
  528. if isinstance(converted, dict):
  529. existing = converted
  530. elif legacy is not None:
  531. restored = cfg.get("custom_providers")
  532. if isinstance(restored, list):
  533. restored.append(legacy)
  534. if existing is None:
  535. existing = {}
  536. # Merge onto the existing entry rather than replacing it: a providers.<name>
  537. # block can carry hand-written keys the dashboard has no field for
  538. # (``key_env``/``api_key_env``, ``extra_headers`` — possibly with
  539. # credentials — ``request_overrides``); rebuilding from scratch silently
  540. # dropped them on an unrelated edit.
  541. entry: dict[str, Any] = dict(existing)
  542. entry.update({
  543. "name": name, "base_url": base_url, "model": model,
  544. "discover_models": bool(body.discover_models),
  545. })
  546. # A Responses-only or Anthropic-compatible host 404s on the runtime's
  547. # Chat Completions default, so the panel pins the transport the same way
  548. # ``hermes model`` does (``api_mode``; the runtime also reads the v12
  549. # ``transport`` spelling, so drop it rather than let the two disagree).
  550. # ``None`` = older UI payload: keep whatever is hand-written. See #93622.
  551. if body.api_mode is not None:
  552. entry.pop("transport", None)
  553. if body.api_mode:
  554. entry["api_mode"] = body.api_mode
  555. else:
  556. entry.pop("api_mode", None)
  557. # Same for the model map, so existing models keep their context lengths.
  558. # ``body.models`` is the catalogue the panel's Test button discovered;
  559. # without it only the hand-typed model survived Save. A payload with no
  560. # ``models`` (older UI) still ensures the named default is present.
  561. # See #69988.
  562. details = {d.id.strip(): d for d in (body.model_details or ()) if d.id.strip()}
  563. existing_models = entry.get("models")
  564. models_map: dict[str, Any] = dict(existing_models) if isinstance(existing_models, dict) else {}
  565. for candidate in (*(body.models or ()), *details, model):
  566. model_id = str(candidate).strip()
  567. if not model_id:
  568. continue
  569. current = models_map.get(model_id)
  570. row = dict(current) if isinstance(current, dict) else {}
  571. detail = details.get(model_id)
  572. if detail is not None:
  573. # Keep the alias metadata ``/v1/models`` advertised so the catalogue
  574. # still says what ``gpt-5.6-sol-high`` stands for after Save.
  575. row.update({k: v.strip() for k, v in (("canonical_model", detail.canonical_model),
  576. ("reasoning_effort", detail.reasoning_effort)) if v and v.strip()})
  577. models_map[model_id] = row
  578. entry["models"] = models_map
  579. # A reasoning alias is not a model the inference route accepts literally:
  580. # persist the canonical model and pin its effort through the one runtime
  581. # chokepoint (``agent.reasoning_overrides`` → ``resolve_reasoning_config``).
  582. alias = details.get(model)
  583. canonical = (alias.canonical_model or "").strip() if alias is not None else ""
  584. if canonical and canonical != model:
  585. from hermes_constants import parse_reasoning_effort
  586. effort = (alias.reasoning_effort or "").strip().lower()
  587. if parse_reasoning_effort(effort) is not None:
  588. agent_cfg = cfg.get("agent") if isinstance(cfg.get("agent"), dict) else {}
  589. overrides = agent_cfg.get("reasoning_overrides")
  590. overrides = dict(overrides) if isinstance(overrides, dict) else {}
  591. overrides[canonical] = effort
  592. agent_cfg["reasoning_overrides"] = overrides
  593. cfg["agent"] = agent_cfg
  594. model = canonical
  595. entry["model"] = model
  596. models_map.setdefault(model, {})
  597. if body.context_length and body.context_length > 0:
  598. entry["context_length"] = int(body.context_length)
  599. entry["models"][model]["context_length"] = int(body.context_length)
  600. # API keys never belong in config.yaml: write to .env and reference it via
  601. # ``key_env`` — the indirection built-in providers use and that
  602. # runtime_provider.py resolves at load time.
  603. # See #69449.
  604. env_var = custom_endpoint_key_env(endpoint_id)
  605. submitted_key = body.api_key.strip() if body.api_key is not None else None
  606. if submitted_key:
  607. # ``${KEY_ENV}`` is the GET display for key_env entries; the helper covers the
  608. # sentinel and legacy masks. Either one is display-only, current or stale.
  609. if _ENV_REF_RE.fullmatch(submitted_key) or is_redacted_credential_preview(submitted_key):
  610. raise HTTPException(status_code=400, detail=REDACTED_CREDENTIAL_WRITE_DETAIL)
  611. save_env_value(env_var, submitted_key)
  612. entry["key_env"] = env_var
  613. entry.pop("api_key", None)
  614. elif submitted_key is not None:
  615. # Blank field means "clear the key", not "leave it alone".
  616. remove_env_value(env_var)
  617. entry.pop("key_env", None)
  618. entry.pop("api_key", None)
  619. elif str(entry.get("api_key") or "").strip() and not _config_api_key_is_env_ref(endpoint_id):
  620. # Migrate a plaintext key an earlier release wrote, on the next save,
  621. # without the user having to re-enter it.
  622. save_env_value(env_var, entry["api_key"].strip())
  623. entry["key_env"] = env_var
  624. entry.pop("api_key", None)
  625. if stored_key is not None and stored_key != endpoint_id:
  626. providers.pop(stored_key, None)
  627. providers[endpoint_id] = entry
  628. cfg["providers"] = providers
  629. if body.make_default:
  630. result = _validated_main_model_selection(cfg, endpoint_id, model, base_url)
  631. cfg["model"] = _apply_main_model_assignment(cfg.get("model", {}), result)
  632. if entry.get("key_env") and isinstance(cfg["model"], dict):
  633. cfg["model"]["key_env"] = entry["key_env"]
  634. drop_model_key(cfg["model"], "api_key")
  635. return endpoint_id, entry
  636. # Sections a custom-endpoint default assignment writes together: the route and its provider entry.
  637. _ROUTE_SECTIONS = ("model", "providers", "custom_providers")
  638. @router.get("/api/providers/custom-endpoints")
  639. def list_custom_endpoints(profile: Optional[str] = None):
  640. """Return configured OpenAI-compatible custom endpoints for Desktop.
  641. Scoped to the requested profile's config.yaml: the desktop settings UI
  642. targets the active profile, so read/write must resolve that profile's home
  643. rather than the process-level HERMES_HOME (mirrors ``/api/config``).
  644. """
  645. with http_failure("GET /api/providers/custom-endpoints failed", 500, detail="Failed to list custom endpoints"):
  646. with _config_profile_scope(profile):
  647. return _custom_endpoint_response(load_config())
  648. @router.post("/api/providers/custom-endpoints")
  649. def upsert_custom_endpoint(body: CustomEndpointUpdate, profile: Optional[str] = None):
  650. """Create or update a v12+ ``providers`` custom endpoint entry."""
  651. with http_failure("POST /api/providers/custom-endpoints failed", 500, detail="Failed to save custom endpoint"):
  652. # Sync-def endpoints run on worker threads: the load→mutate→save span
  653. # holds _CONFIG_MUTATION_LOCK so a concurrent config autosave cannot
  654. # drop this write (or vice versa).
  655. with _config_profile_scope(profile), _CONFIG_MUTATION_LOCK:
  656. cfg = load_config()
  657. providers = cfg.get("providers")
  658. created = _resolve_custom_endpoint_entry(
  659. providers if isinstance(providers, dict) else {}, body.id or body.name)[1] is None
  660. endpoint_id, _entry = _write_custom_endpoint(cfg, body)
  661. # make_default: the model route and the provider definition it names are one change,
  662. # so a lock on either refuses both (never a model.provider naming an omitted entry).
  663. with refusing_locked_omissions(*_ROUTE_SECTIONS) if body.make_default else contextlib.nullcontext():
  664. save_config(cfg)
  665. response = _custom_endpoint_response(cfg)
  666. from hermes_constants import get_hermes_home
  667. home = get_hermes_home()
  668. if created: # editing an endpoint that exists sets nothing new up
  669. _record_custom_endpoint_setup(home)
  670. response["ok"] = True
  671. response["id"] = endpoint_id
  672. return response
  673. def _record_custom_endpoint_setup(home: Any) -> None:
  674. """Counted after the config lock is released (a cold metrics runtime must not stall writers)."""
  675. from hermes_cli.observability.shared_metrics_setup import record_provider_setup_done, web_setup_surface
  676. record_provider_setup_done(web_setup_surface(), "custom", hermes_home=home, background=True)
  677. @router.post("/api/providers/custom-endpoints/{endpoint_id}/activate")
  678. def activate_custom_endpoint(endpoint_id: str, profile: Optional[str] = None):
  679. """Set a configured custom endpoint as the default model provider."""
  680. with http_failure(
  681. f"POST /api/providers/custom-endpoints/{endpoint_id}/activate failed", 500,
  682. detail="Failed to activate custom endpoint",
  683. ):
  684. with _config_profile_scope(profile), _CONFIG_MUTATION_LOCK: # RMW span
  685. cfg = load_config()
  686. stored_key, entry = _resolve_custom_endpoint_entry(cfg.get("providers"), endpoint_id)
  687. if entry is None:
  688. # A legacy ``custom_providers:`` row: the main slot names providers by
  689. # key, so promote the entry to ``providers.<key>`` (the v12 shape the
  690. # migration would have written) before activating it.
  691. provider_key = _custom_endpoint_id(endpoint_id)
  692. legacy = _pop_legacy_custom_provider(cfg, provider_key)
  693. entry = _custom_provider_entry_to_provider_config(legacy, provider_key=provider_key) if legacy else None
  694. if entry is None:
  695. raise HTTPException(status_code=404, detail="custom endpoint not found")
  696. providers = cfg.get("providers") if isinstance(cfg.get("providers"), dict) else {}
  697. providers[provider_key] = entry
  698. cfg["providers"] = providers
  699. else:
  700. provider_key = coerce_provider_id(stored_key)
  701. models = _models_from_custom_endpoint_entry(entry)
  702. model = str(entry.get("model") or entry.get("default_model") or (models[0] if models else "")).strip()
  703. base_url = str(entry.get("base_url") or entry.get("api") or "").strip()
  704. if not model or not base_url:
  705. raise HTTPException(status_code=400, detail="custom endpoint is incomplete")
  706. model_cfg = _apply_main_model_assignment(
  707. cfg.get("model", {}), _validated_main_model_selection(cfg, provider_key, model, base_url))
  708. if entry.get("key_env"):
  709. model_cfg["key_env"] = entry["key_env"]
  710. drop_model_key(model_cfg, "api_key")
  711. elif entry.get("api_key"):
  712. # `cfg` is env-expanded, so a raw `${VAR}` api_key would land as
  713. # plaintext; copy the raw template when that's what's on disk.
  714. try:
  715. _raw_key = str(_raw_provider_api_key(provider_key) or "").strip()
  716. except Exception:
  717. _raw_key = ""
  718. if _raw_key.startswith("${") and _raw_key.endswith("}"):
  719. model_cfg["api_key"] = _raw_key
  720. else:
  721. model_cfg["api_key"] = entry["api_key"]
  722. cfg["model"] = model_cfg
  723. with refusing_locked_omissions(*_ROUTE_SECTIONS):
  724. save_config(cfg)
  725. return {"ok": True, "provider": provider_key, "model": model}
  726. @router.delete("/api/providers/custom-endpoints/{endpoint_id}")
  727. def delete_custom_endpoint(endpoint_id: str, profile: Optional[str] = None):
  728. """Remove a configured custom endpoint from ``providers``."""
  729. with http_failure(
  730. f"DELETE /api/providers/custom-endpoints/{endpoint_id} failed", 500,
  731. detail="Failed to delete custom endpoint",
  732. ):
  733. with _config_profile_scope(profile), _CONFIG_MUTATION_LOCK: # RMW span
  734. cfg = load_config()
  735. providers = cfg.get("providers")
  736. stored_key, entry = _resolve_custom_endpoint_entry(providers, endpoint_id)
  737. if entry is not None and isinstance(providers, dict):
  738. provider_key = coerce_provider_id(stored_key)
  739. providers.pop(stored_key, None)
  740. cfg["providers"] = providers
  741. else:
  742. # A legacy ``custom_providers:`` row is addressed by its slug.
  743. provider_key = _custom_endpoint_id(endpoint_id)
  744. if _pop_legacy_custom_provider(cfg, provider_key) is None:
  745. raise HTTPException(status_code=404, detail="custom endpoint not found")
  746. _detach_main_model_from_provider(cfg, provider_key, entry)
  747. remove_env_value(custom_endpoint_key_env(provider_key))
  748. save_config(cfg)
  749. response = _custom_endpoint_response(cfg)
  750. response["ok"] = True
  751. return response
  752. @router.post("/api/providers/custom-endpoints/validate")
  753. async def validate_custom_endpoint(body: CustomEndpointUpdate):
  754. """Probe a custom endpoint by calling its OpenAI-compatible /models URL."""
  755. base_url = (body.base_url or "").strip().rstrip("/")
  756. if not base_url:
  757. return {"ok": False, "reachable": True, "message": "Enter an endpoint URL first.", "models": []}
  758. headers = {"Accept": "application/json"}
  759. if body.api_key and body.api_key.strip():
  760. headers["Authorization"] = f"Bearer {body.api_key.strip()}"
  761. resolved, resp = await _probe_openai_compatible_models(base_url, headers)
  762. if resp is None:
  763. return {"ok": False, "reachable": False, "message": f"Could not reach {base_url}/models.", "models": []}
  764. if resp.status_code in (401, 403):
  765. return {"ok": False, "reachable": True, "message": "The endpoint rejected the API key.", "models": []}
  766. if not resp.is_success:
  767. return {"ok": False, "reachable": True, "message": f"Endpoint returned HTTP {resp.status_code}.", "models": []}
  768. # ``models`` stays the bare id list older clients read; ``model_details`` keeps the
  769. # alias metadata (``canonical_model`` / ``reasoning_effort``) the id list flattens.
  770. entries = _parse_model_entries(resp)
  771. ids = [e["id"] for e in entries]
  772. if not ids:
  773. # A 200 that parses to zero models is the SPA-catch-all signature (#83128): a real
  774. # OpenAI-compatible /models answers JSON with a usable list. ``_parse_model_entries``
  775. # is lenient by design, so classify the empty result here instead of reporting
  776. # success. ok:false + reachable:true is a warning in the UI — Save stays possible
  777. # for endpoints that legitimately expose no model list.
  778. return {"ok": False, "reachable": True, "message": _no_models_probe_message(resp, resolved),
  779. "models": [], "model_details": [], "resolved_base_url": resolved}
  780. # /models answering proves nothing about the transport the runtime will POST to:
  781. # a Responses-only host lists models fine and 404s every /chat/completions (#93622).
  782. # Probe the route the saved mode (or the runtime's URL auto-detect) actually uses, on the
  783. # base that actually served /models (#65488) — that is the URL the runtime will persist.
  784. mode = _canonical_api_mode(body.api_mode or "").lower() or _auto_api_mode(resolved)
  785. probe_model = (body.model or "").strip() or (ids[0] if ids else "")
  786. try:
  787. async with _endpoint_probe_client(resolved, 8.0) as client:
  788. missing = await _probe_transport_route(client, resolved, mode, probe_model, headers)
  789. except Exception:
  790. missing = "" # inconclusive (see _probe_transport_route): never block on a transport error
  791. result = {"ok": True, "reachable": True, "message": "", "models": ids, "model_details": entries,
  792. "transport_checked": mode, "resolved_base_url": resolved}
  793. if missing:
  794. result.update(ok=False, message=missing)
  795. return result
  796. def _no_models_probe_message(resp: Any, base_url: str) -> str:
  797. """Why a 200 ``/models`` probe yielded no usable models (#83128).
  798. Distinguishes the three ways that happens — a non-JSON body (an SPA catch-all serves
  799. HTML for every route, so 200 proves nothing), a JSON body without a model list, and a
  800. genuinely empty list — mirroring the onboarding store's wording for the last case.
  801. """
  802. url = base_url + "/models"
  803. content_type = (resp.headers.get("content-type") or "").split(";")[0].strip()
  804. try:
  805. payload = resp.json()
  806. except ValueError: # json.JSONDecodeError — a non-JSON body (HTML, plain text) is the case being named
  807. payload = None
  808. if not isinstance(payload, (dict, list)):
  809. kind = content_type or "a non-JSON body"
  810. return (f"Connected to {url}, but it returned {kind} instead of a JSON model list — "
  811. "the URL may be an SPA catch-all or a wrong base URL, not an OpenAI-compatible API.")
  812. data = payload.get("data") if isinstance(payload, dict) else payload
  813. if not isinstance(data, list):
  814. return f"Connected to {url}, but its response is not an OpenAI-compatible model list."
  815. return (f"Connected to {url}, but it advertised no models. "
  816. "Start a model on that endpoint and try again.")
  817. async def _probe_openai_compatible_models(base_url: str, headers: Optional[dict]) -> tuple[str, Any]:
  818. """GET ``{base}/models``, then ``{base}/v1/models`` (or the ``/v1``-stripped variant) when the
  819. first answers a non-success. Returns ``(resolved_base_url, response)`` — the base that served the
  820. model list is what the caller must PERSIST: the runtime appends ``/chat/completions`` to the saved
  821. URL verbatim, so a bare host root that only "detected" via ``/v1/models`` would 404 every chat
  822. (#65488). ``response`` is None when no candidate could be reached at all."""
  823. base = base_url.rstrip("/")
  824. alternate = base[:-3].rstrip("/") if base.lower().endswith("/v1") else base + "/v1"
  825. resolved, resp = base, None
  826. async with _endpoint_probe_client(base, 8.0) as client:
  827. for candidate in (base, alternate):
  828. try:
  829. candidate_resp = await client.get(candidate + "/models", headers=headers)
  830. except Exception:
  831. continue
  832. # Keep the most telling failure: a 401/403 from the /v1 alternate says "server is
  833. # there, key rejected", which beats the typed root's 404 (wrong path).
  834. if resp is None or candidate_resp.is_success or resp.status_code == 404:
  835. resolved, resp = candidate, candidate_resp
  836. if candidate_resp.is_success:
  837. break
  838. return resolved, resp
  839. _TRANSPORT_ROUTES = {"chat_completions": "/chat/completions", "codex_responses": "/responses",
  840. "anthropic_messages": "/messages"}
  841. _TRANSPORT_LABELS = {"chat_completions": "Chat Completions", "codex_responses": "Responses API",
  842. "anthropic_messages": "Anthropic Messages"}
  843. def _auto_api_mode(base_url: str) -> str:
  844. """The transport the runtime falls back to for an endpoint without a pinned ``api_mode``
  845. (same resolver as ``runtime_provider_custom._custom_runtime``)."""
  846. from hermes_cli.runtime_provider import _detect_api_mode_for_url
  847. return _detect_api_mode_for_url(base_url) or "chat_completions"
  848. async def _probe_transport_route(client, base_url: str, mode: str, model: str, headers: dict[str, str]) -> str:
  849. """POST a 1-token request to ``mode``'s route; return a failure message when the host does
  850. not serve it (404/405/501), ``""`` otherwise. Any other status — 200, 400 (bad body), 401,
  851. 422, 429 — means the route exists, which is all the check needs to know; a network error or
  852. timeout (a local server still loading the model) is inconclusive and does not block."""
  853. route = _TRANSPORT_ROUTES.get(mode)
  854. if route is None:
  855. return ""
  856. if mode == "anthropic_messages":
  857. payload = {"model": model, "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}
  858. token = headers.get("Authorization", "").removeprefix("Bearer ")
  859. headers = {**headers, "anthropic-version": "2023-06-01", **({"x-api-key": token} if token else {})}
  860. elif mode == "codex_responses":
  861. payload = {"model": model, "input": "hi", "max_output_tokens": 16}
  862. else:
  863. payload = {"model": model, "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}
  864. try:
  865. resp = await client.post(base_url + route, json=payload, headers=headers)
  866. except Exception:
  867. return ""
  868. if resp.status_code not in (404, 405, 501):
  869. return ""
  870. return (f"{base_url}/models answered, but POST {route} returned HTTP {resp.status_code}: this host "
  871. f"does not serve the {_TRANSPORT_LABELS[mode]} API. Pick the API mode it does serve.")
  872. def _endpoint_probe_client(url: str, timeout: float):
  873. """httpx client for a user-entered endpoint probe. Local endpoints (loopback, LAN, Tailscale)
  874. ignore ``HTTP(S)_PROXY``: httpx honours the env/system proxy but not its bypass list, so a
  875. system proxy (Clash on Windows, corporate) answered the ``127.0.0.1`` probe with its own error
  876. page and the GUI reported "advertised no models" while the CLI saw the model (#63472)."""
  877. import httpx
  878. from agent.model_metadata import is_local_endpoint
  879. return httpx.AsyncClient(timeout=httpx.Timeout(timeout), trust_env=not is_local_endpoint(url))
  880. @router.post("/api/providers/validate")
  881. async def validate_provider_credential(body: EnvVarUpdate, request: Request):
  882. """Live-probe a provider credential before it's saved.
  883. Returns {ok, reachable, message}. ok=True means the provider accepted the
  884. key; ok=False + reachable=True means the key is bad (caller should block);
  885. reachable=False means the network probe couldn't run (caller may save with
  886. a warning rather than hard-blocking offline users).
  887. """
  888. _require_token(request)
  889. import httpx
  890. key = (body.key or "").strip()
  891. value = (body.value or "").strip()
  892. if not value:
  893. return {"ok": False, "reachable": True, "message": "Enter a value first."}
  894. # Local / custom endpoint: validate connectivity, not auth — any HTTP
  895. # response (even 401) proves the endpoint is up. Also surface the model ids
  896. # it advertises (OpenAI ``/v1/models`` shape) so the GUI can auto-pick a
  897. # default. The optional API key is sent so servers that require auth on
  898. # ``/v1/models`` still enumerate instead of returning an empty list.
  899. if key == "OPENAI_BASE_URL":
  900. api_key = (body.api_key or "").strip()
  901. headers = {"Authorization": f"Bearer {api_key}"} if api_key else None
  902. resolved, resp = await _probe_openai_compatible_models(value, headers)
  903. url = resolved + "/models"
  904. if resp is None:
  905. return {"ok": False, "reachable": False, "message": f"Could not reach {url}."}
  906. entries = _parse_model_entries(resp)
  907. models = [e["id"] for e in entries]
  908. if not models and not resp.is_success:
  909. # A proxy/gateway error page parses as "no models"; name the status instead so the
  910. # GUI does not tell the user to "start a model" on a server that answered.
  911. return {"ok": False, "reachable": True, "message": f"{url} answered HTTP {resp.status_code}.", "models": []}
  912. return {"ok": True, "reachable": True, "message": "", "models": models, "model_details": entries,
  913. "resolved_base_url": resolved}
  914. probe = _CREDENTIAL_PROBES.get(key)
  915. if not probe:
  916. # No probe for this provider — can't validate, don't block.
  917. return {"ok": True, "reachable": False, "message": ""}
  918. url, auth = probe
  919. if key == "GEMINI_API_KEY":
  920. from agent.gemini_native_adapter import normalize_gemini_base_url
  921. # Normalize guarantees the version segment; the key itself never decides the surface —
  922. # AQ. keys exist for both AI Studio and Vertex express mode (#115306).
  923. url = normalize_gemini_base_url(url.rsplit("/models", 1)[0]) + "/models"
  924. headers = {"Accept": "application/json"}
  925. params = {}
  926. if auth == "bearer":
  927. headers["Authorization"] = f"Bearer {value}"
  928. else:
  929. params["key"] = value
  930. try:
  931. async with httpx.AsyncClient(timeout=httpx.Timeout(10.0)) as client:
  932. resp = await client.get(url, headers=headers, params=params)
  933. except Exception:
  934. return {"ok": False, "reachable": False, "message": "Could not reach the provider to verify the key."}
  935. if resp.status_code in (401, 403):
  936. return {"ok": False, "reachable": True, "message": "That API key was rejected. Double-check it and try again."}
  937. if resp.status_code == 429 or resp.is_success:
  938. # 429 = key is valid but rate-limited; success = valid.
  939. return {"ok": True, "reachable": True, "message": ""}
  940. return {"ok": False, "reachable": True, "message": f"Provider returned HTTP {resp.status_code} for this key."}
  941. @router.delete("/api/env")
  942. async def remove_env_var(body: EnvVarDelete, profile: Optional[str] = None):
  943. # Unified credential lifecycle: clears the .env entry AND every mirror of
  944. # the credential — env-seeded credential_pool entries in auth.json (stale
  945. # ones kept providers alive in the model picker), the affected providers'
  946. # model-cache rows, and value-matched config.yaml api_key mirrors.
  947. # OAuth/device-code/manual pool entries for the same provider are preserved.
  948. with _env_write_errors("DELETE /api/env failed"):
  949. from hermes_cli.credential_lifecycle import remove_provider_env_credential
  950. result = await scoped_to_thread(
  951. body.profile or profile, lambda: remove_provider_env_credential(body.key)
  952. )
  953. if not result.get("found"):
  954. raise HTTPException(status_code=404, detail=f"{body.key} not found in .env")
  955. return result
  956. @router.post("/api/env/reveal")
  957. async def reveal_env_var(
  958. body: EnvVarReveal, request: Request, profile: Optional[str] = None
  959. ):
  960. """Return the real (unredacted) value of a single env var.
  961. Protected by the ephemeral session token (per server start, injected into
  962. the SPA), rate limiting (max 5 reveals per 30s window) and audit logging.
  963. """
  964. _require_token(request)
  965. now = time.time()
  966. cutoff = now - _REVEAL_WINDOW_SECONDS
  967. _reveal_timestamps[:] = [t for t in _reveal_timestamps if t > cutoff]
  968. if len(_reveal_timestamps) >= _REVEAL_MAX_PER_WINDOW:
  969. raise HTTPException(status_code=429, detail="Too many reveal requests. Try again shortly.")
  970. _reveal_timestamps.append(now)
  971. env_on_disk = await scoped_to_thread(body.profile or profile, load_env)
  972. value = env_on_disk.get(body.key)
  973. if value is None:
  974. raise HTTPException(status_code=404, detail=f"{body.key} not found in .env")
  975. _log.info("env/reveal: %s", body.key)
  976. return {"key": body.key, "value": value}