delegation.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262
  1. """Delegation routing routes: which ``delegation.backend`` runs subagents, and each plugin backend's
  2. routes under ``delegation.backends.<name>``.
  3. The settings shapes are the ones the official advanced-delegation plugin reads (``model_map``:
  4. named model routes; ``profile_routes``: Hermes profiles subagents may run as). Writes replace one
  5. backend's block wholesale through the same profile scope + config lock every config route uses, so
  6. deleting a route really deletes it (``PUT /api/config`` deep-merges and cannot drop a key).
  7. """
  8. from __future__ import annotations
  9. import asyncio
  10. import logging
  11. from dataclasses import asdict
  12. from typing import Any, Callable, Mapping, Optional
  13. from fastapi import APIRouter, HTTPException
  14. from hermes_cli.web_deps import late
  15. from hermes_cli.web_models import DelegationBackendSelect, DelegationModelMapUpdate, DelegationProfileRoutesUpdate
  16. from hermes_cli.web_routers._common import (
  17. _profile_scope, config_write_scope, is_redacted_credential_preview, redacted_credential_preview,
  18. )
  19. router = APIRouter()
  20. _log = logging.getLogger(__name__)
  21. load_config = late("load_config", "hermes_cli.config")
  22. save_config = late("save_config", "hermes_cli.config")
  23. DEFAULT_BACKEND = "default"
  24. MODEL_MAP = "model_map"
  25. PROFILE_ROUTES = "profile_routes"
  26. _OPTION_TEXT_KEYS = ("name", "description", "provider", "model", "base_url", "api_mode")
  27. def _bad_request(detail: str) -> HTTPException:
  28. return HTTPException(status_code=400, detail=detail)
  29. def _managed_install(message: str) -> HTTPException:
  30. """A package-manager-managed install's config.yaml is not ours to write (``save_config`` would skip it and
  31. report nothing): 409 with core's one-line reason, which the page shows as the error. Not 403, which the
  32. Desktop transport reads as an auth rejection and answers with a re-login."""
  33. return HTTPException(status_code=409, detail=" ".join(message.split()))
  34. def _mapping(parent: Any, key: str) -> dict:
  35. value = parent.get(key) if isinstance(parent, Mapping) else None
  36. return value if isinstance(value, dict) else {}
  37. def _section(config: dict, key: str) -> dict:
  38. value = config.get(key)
  39. if not isinstance(value, dict):
  40. value = {}
  41. config[key] = value
  42. return value
  43. def _registered_backends() -> list[dict[str, Any]]:
  44. """``default`` plus every plugin-registered backend of the active profile, with availability."""
  45. from agent.delegation_backends import list_backends
  46. from agent.delegation_registry import DEFAULT_BACKEND as builtin
  47. from hermes_cli.plugins import discover_plugins
  48. discover_plugins() # idempotent; a plugin enabled after boot loads on the next scan
  49. # ``description`` is the provider's ``summary``: the one line a backend picker shows for it.
  50. return [{**asdict(b), "builtin": b.name == builtin} for b in list_backends()]
  51. def _redacted_options(options: Any) -> list[dict[str, Any]]:
  52. """Model routes as stored, with an ``api_key`` reduced to a display-only preview."""
  53. if not isinstance(options, list):
  54. return []
  55. out = []
  56. for entry in options:
  57. if not isinstance(entry, dict):
  58. continue
  59. row = dict(entry)
  60. if row.get("api_key"):
  61. row["api_key"] = redacted_credential_preview(row["api_key"])
  62. out.append(row)
  63. return out
  64. def _profile_names() -> list[str]:
  65. from hermes_cli.profiles import list_profile_names
  66. return list_profile_names()
  67. @router.get("/api/delegation/routing")
  68. async def get_delegation_routing(profile: Optional[str] = None):
  69. """The profile's delegation backend (``configured``) and, when it cannot run here, why
  70. (``blocked_reason``, ``None`` when it runs: core fails closed, so subagents are refused until it is fixed), the registered
  71. backends, both route blocks and the profiles a profile route may name."""
  72. def _read():
  73. from agent.delegation_registry import backend_status, configured_backend
  74. with _profile_scope(profile):
  75. delegation = _mapping(load_config(), "delegation")
  76. backends = _registered_backends()
  77. configured = configured_backend(delegation)
  78. blocks = _mapping(delegation, "backends")
  79. model_map, routes = _mapping(blocks, MODEL_MAP), _mapping(blocks, PROFILE_ROUTES)
  80. return {
  81. "configured": configured,
  82. "blocked_reason": backend_status(configured)[1] or None,
  83. "backends": backends,
  84. MODEL_MAP: {"options": _redacted_options(model_map.get("options")),
  85. "default": model_map.get("default") or None},
  86. PROFILE_ROUTES: {"profiles": [p for p in routes.get("profiles") or [] if isinstance(p, dict)],
  87. "default": routes.get("default") or None},
  88. "profiles": _profile_names(),
  89. }
  90. return await asyncio.to_thread(_read)
  91. @router.put("/api/delegation/backend")
  92. async def select_delegation_backend(body: DelegationBackendSelect, profile: Optional[str] = None):
  93. """Persist ``delegation.backend`` through core's ``set_global_backend``: only ``default`` or a backend
  94. that can run for this profile (core fails closed on any other, refusing every subagent)."""
  95. name = (body.backend or "").strip().lower() or DEFAULT_BACKEND
  96. def _run():
  97. from agent.delegation_backends import set_global_backend
  98. from hermes_cli.plugins import discover_plugins
  99. with config_write_scope(body.profile or profile):
  100. discover_plugins()
  101. try:
  102. set_global_backend(name)
  103. except PermissionError as exc:
  104. raise _managed_install(str(exc)) from exc
  105. except ValueError as exc:
  106. raise _bad_request(str(exc)) from exc
  107. await asyncio.to_thread(_run)
  108. return {"ok": True, "backend": name}
  109. def _text(entry: dict, key: str) -> str:
  110. value = entry.get(key)
  111. return value.strip() if isinstance(value, str) else ""
  112. def _check_default(default: Optional[str], names: list[str], what: str) -> Optional[str]:
  113. value = (default or "").strip()
  114. if value and value not in names:
  115. raise _bad_request(f"Default {what} {value!r} is not in the list.")
  116. return value or None
  117. def _clean_model_option(index: int, entry: dict, stored: dict[str, dict]) -> dict[str, Any]:
  118. from agent.delegation_provider import ROUTE_KEYS
  119. from agent.fast_mode import STATIC_TIERS, parse_exact_service_tier
  120. from hermes_constants import VALID_REASONING_EFFORTS, parse_reasoning_effort
  121. row = {key: _text(entry, key) for key in _OPTION_TEXT_KEYS if _text(entry, key)}
  122. label = f"Route {index + 1}"
  123. if not row.get("name"):
  124. raise _bad_request(f"{label} needs a name.")
  125. label = f"Route {row['name']!r}"
  126. if not row.get("description"):
  127. raise _bad_request(f"{label} needs a description: it is what the agent reads to choose it.")
  128. if not row.get("model"):
  129. raise _bad_request(f"{label} needs a model.")
  130. if not (row.get("provider") or row.get("base_url")):
  131. raise _bad_request(f"{label} needs a provider.")
  132. effort = _text(entry, "reasoning_effort")
  133. if effort:
  134. if parse_reasoning_effort(effort) is None:
  135. raise _bad_request(f"{label}: unknown reasoning effort {effort!r}. "
  136. f"Use none or one of: {', '.join(VALID_REASONING_EFFORTS)}.")
  137. row["reasoning_effort"] = effort
  138. tier = _text(entry, "service_tier")
  139. if tier:
  140. try:
  141. parsed = parse_exact_service_tier(tier)
  142. except ValueError:
  143. parsed = None
  144. if parsed is None or (parsed and parsed not in STATIC_TIERS):
  145. raise _bad_request(f"{label}: unknown service tier {tier!r}. Use normal, fast or ultrafast.")
  146. row["service_tier"] = tier
  147. if isinstance(entry.get("fallback_providers"), list):
  148. row["fallback_providers"] = entry["fallback_providers"]
  149. # Route fields the editor never touches (request_overrides, label, profile) round-trip as stored.
  150. validated = {*_OPTION_TEXT_KEYS, "api_key", "reasoning_effort", "service_tier", "fallback_providers"}
  151. for field in sorted(ROUTE_KEYS - validated):
  152. if entry.get(field) not in (None, "", [], {}):
  153. row[field] = entry[field]
  154. key = entry.get("api_key")
  155. if is_redacted_credential_preview(key):
  156. # The renderer only ever saw a preview: keep the stored key of the route it came from (a rename names
  157. # it in original_name; once that save landed, the route is stored under its new name).
  158. source = stored.get(_text(entry, "original_name")) or stored.get(row["name"]) or {}
  159. key = source.get("api_key")
  160. if isinstance(key, str) and key.strip():
  161. row["api_key"] = key.strip()
  162. return row
  163. def _write_backend_block(profile: Optional[str], backend: str, build: Callable[[dict], dict]) -> dict:
  164. from hermes_cli.config import format_managed_message, is_managed
  165. if is_managed():
  166. raise _managed_install(format_managed_message(f"save delegation.backends.{backend}"))
  167. with config_write_scope(profile):
  168. config = load_config()
  169. blocks = _section(_section(config, "delegation"), "backends")
  170. block = build(_mapping(blocks, backend))
  171. blocks[backend] = block
  172. save_config(config)
  173. return block
  174. @router.put("/api/delegation/backends/model_map")
  175. async def save_model_routes(body: DelegationModelMapUpdate, profile: Optional[str] = None):
  176. """Replace ``delegation.backends.model_map`` (``options`` + ``default``) after validating every route."""
  177. def _build(current: dict) -> dict:
  178. stored = {_text(o, "name"): o for o in current.get("options") or [] if isinstance(o, dict)}
  179. options = [_clean_model_option(i, dict(o), stored) for i, o in enumerate(body.options)]
  180. names = [o["name"] for o in options]
  181. duplicate = next((n for n in names if names.count(n) > 1), None)
  182. if duplicate:
  183. raise _bad_request(f"Two routes are named {duplicate!r}; route names must be unique.")
  184. block: dict[str, Any] = {"options": options}
  185. default = _check_default(body.default, names, "route")
  186. if default:
  187. block["default"] = default
  188. return block
  189. block = await asyncio.to_thread(_write_backend_block, body.profile or profile, MODEL_MAP, _build)
  190. return {"ok": True, MODEL_MAP: {"options": _redacted_options(block["options"]),
  191. "default": block.get("default")}}
  192. @router.put("/api/delegation/backends/profile_routes")
  193. async def save_profile_routes(body: DelegationProfileRoutesUpdate, profile: Optional[str] = None):
  194. """Replace ``delegation.backends.profile_routes`` (``profiles`` + ``default``); every name must be an
  195. existing profile."""
  196. def _build(_current: dict) -> dict:
  197. known = set(_profile_names())
  198. profiles: list[dict[str, str]] = []
  199. names: list[str] = []
  200. for entry in body.profiles:
  201. name = _text(entry, "name")
  202. if not name:
  203. raise _bad_request("A profile route needs a profile name.")
  204. if name not in known:
  205. raise _bad_request(f"Profile {name!r} does not exist.")
  206. if name in names:
  207. raise _bad_request(f"Profile {name!r} is listed twice.")
  208. names.append(name)
  209. description = _text(entry, "description")
  210. profiles.append({"name": name, **({"description": description} if description else {})})
  211. block: dict[str, Any] = {"profiles": profiles}
  212. default = _check_default(body.default, names, "profile")
  213. if default:
  214. block["default"] = default
  215. return block
  216. block = await asyncio.to_thread(_write_backend_block, body.profile or profile, PROFILE_ROUTES, _build)
  217. return {"ok": True, PROFILE_ROUTES: {"profiles": block["profiles"], "default": block.get("default")}}