| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262 |
- """Delegation routing routes: which ``delegation.backend`` runs subagents, and each plugin backend's
- routes under ``delegation.backends.<name>``.
- The settings shapes are the ones the official advanced-delegation plugin reads (``model_map``:
- named model routes; ``profile_routes``: Hermes profiles subagents may run as). Writes replace one
- backend's block wholesale through the same profile scope + config lock every config route uses, so
- deleting a route really deletes it (``PUT /api/config`` deep-merges and cannot drop a key).
- """
- from __future__ import annotations
- import asyncio
- import logging
- from dataclasses import asdict
- from typing import Any, Callable, Mapping, Optional
- from fastapi import APIRouter, HTTPException
- from hermes_cli.web_deps import late
- from hermes_cli.web_models import DelegationBackendSelect, DelegationModelMapUpdate, DelegationProfileRoutesUpdate
- from hermes_cli.web_routers._common import (
- _profile_scope, config_write_scope, is_redacted_credential_preview, redacted_credential_preview,
- )
- router = APIRouter()
- _log = logging.getLogger(__name__)
- load_config = late("load_config", "hermes_cli.config")
- save_config = late("save_config", "hermes_cli.config")
- DEFAULT_BACKEND = "default"
- MODEL_MAP = "model_map"
- PROFILE_ROUTES = "profile_routes"
- _OPTION_TEXT_KEYS = ("name", "description", "provider", "model", "base_url", "api_mode")
- def _bad_request(detail: str) -> HTTPException:
- return HTTPException(status_code=400, detail=detail)
- def _managed_install(message: str) -> HTTPException:
- """A package-manager-managed install's config.yaml is not ours to write (``save_config`` would skip it and
- report nothing): 409 with core's one-line reason, which the page shows as the error. Not 403, which the
- Desktop transport reads as an auth rejection and answers with a re-login."""
- return HTTPException(status_code=409, detail=" ".join(message.split()))
- def _mapping(parent: Any, key: str) -> dict:
- value = parent.get(key) if isinstance(parent, Mapping) else None
- return value if isinstance(value, dict) else {}
- def _section(config: dict, key: str) -> dict:
- value = config.get(key)
- if not isinstance(value, dict):
- value = {}
- config[key] = value
- return value
- def _registered_backends() -> list[dict[str, Any]]:
- """``default`` plus every plugin-registered backend of the active profile, with availability."""
- from agent.delegation_backends import list_backends
- from agent.delegation_registry import DEFAULT_BACKEND as builtin
- from hermes_cli.plugins import discover_plugins
- discover_plugins() # idempotent; a plugin enabled after boot loads on the next scan
- # ``description`` is the provider's ``summary``: the one line a backend picker shows for it.
- return [{**asdict(b), "builtin": b.name == builtin} for b in list_backends()]
- def _redacted_options(options: Any) -> list[dict[str, Any]]:
- """Model routes as stored, with an ``api_key`` reduced to a display-only preview."""
- if not isinstance(options, list):
- return []
- out = []
- for entry in options:
- if not isinstance(entry, dict):
- continue
- row = dict(entry)
- if row.get("api_key"):
- row["api_key"] = redacted_credential_preview(row["api_key"])
- out.append(row)
- return out
- def _profile_names() -> list[str]:
- from hermes_cli.profiles import list_profile_names
- return list_profile_names()
- @router.get("/api/delegation/routing")
- async def get_delegation_routing(profile: Optional[str] = None):
- """The profile's delegation backend (``configured``) and, when it cannot run here, why
- (``blocked_reason``, ``None`` when it runs: core fails closed, so subagents are refused until it is fixed), the registered
- backends, both route blocks and the profiles a profile route may name."""
- def _read():
- from agent.delegation_registry import backend_status, configured_backend
- with _profile_scope(profile):
- delegation = _mapping(load_config(), "delegation")
- backends = _registered_backends()
- configured = configured_backend(delegation)
- blocks = _mapping(delegation, "backends")
- model_map, routes = _mapping(blocks, MODEL_MAP), _mapping(blocks, PROFILE_ROUTES)
- return {
- "configured": configured,
- "blocked_reason": backend_status(configured)[1] or None,
- "backends": backends,
- MODEL_MAP: {"options": _redacted_options(model_map.get("options")),
- "default": model_map.get("default") or None},
- PROFILE_ROUTES: {"profiles": [p for p in routes.get("profiles") or [] if isinstance(p, dict)],
- "default": routes.get("default") or None},
- "profiles": _profile_names(),
- }
- return await asyncio.to_thread(_read)
- @router.put("/api/delegation/backend")
- async def select_delegation_backend(body: DelegationBackendSelect, profile: Optional[str] = None):
- """Persist ``delegation.backend`` through core's ``set_global_backend``: only ``default`` or a backend
- that can run for this profile (core fails closed on any other, refusing every subagent)."""
- name = (body.backend or "").strip().lower() or DEFAULT_BACKEND
- def _run():
- from agent.delegation_backends import set_global_backend
- from hermes_cli.plugins import discover_plugins
- with config_write_scope(body.profile or profile):
- discover_plugins()
- try:
- set_global_backend(name)
- except PermissionError as exc:
- raise _managed_install(str(exc)) from exc
- except ValueError as exc:
- raise _bad_request(str(exc)) from exc
- await asyncio.to_thread(_run)
- return {"ok": True, "backend": name}
- def _text(entry: dict, key: str) -> str:
- value = entry.get(key)
- return value.strip() if isinstance(value, str) else ""
- def _check_default(default: Optional[str], names: list[str], what: str) -> Optional[str]:
- value = (default or "").strip()
- if value and value not in names:
- raise _bad_request(f"Default {what} {value!r} is not in the list.")
- return value or None
- def _clean_model_option(index: int, entry: dict, stored: dict[str, dict]) -> dict[str, Any]:
- from agent.delegation_provider import ROUTE_KEYS
- from agent.fast_mode import STATIC_TIERS, parse_exact_service_tier
- from hermes_constants import VALID_REASONING_EFFORTS, parse_reasoning_effort
- row = {key: _text(entry, key) for key in _OPTION_TEXT_KEYS if _text(entry, key)}
- label = f"Route {index + 1}"
- if not row.get("name"):
- raise _bad_request(f"{label} needs a name.")
- label = f"Route {row['name']!r}"
- if not row.get("description"):
- raise _bad_request(f"{label} needs a description: it is what the agent reads to choose it.")
- if not row.get("model"):
- raise _bad_request(f"{label} needs a model.")
- if not (row.get("provider") or row.get("base_url")):
- raise _bad_request(f"{label} needs a provider.")
- effort = _text(entry, "reasoning_effort")
- if effort:
- if parse_reasoning_effort(effort) is None:
- raise _bad_request(f"{label}: unknown reasoning effort {effort!r}. "
- f"Use none or one of: {', '.join(VALID_REASONING_EFFORTS)}.")
- row["reasoning_effort"] = effort
- tier = _text(entry, "service_tier")
- if tier:
- try:
- parsed = parse_exact_service_tier(tier)
- except ValueError:
- parsed = None
- if parsed is None or (parsed and parsed not in STATIC_TIERS):
- raise _bad_request(f"{label}: unknown service tier {tier!r}. Use normal, fast or ultrafast.")
- row["service_tier"] = tier
- if isinstance(entry.get("fallback_providers"), list):
- row["fallback_providers"] = entry["fallback_providers"]
- # Route fields the editor never touches (request_overrides, label, profile) round-trip as stored.
- validated = {*_OPTION_TEXT_KEYS, "api_key", "reasoning_effort", "service_tier", "fallback_providers"}
- for field in sorted(ROUTE_KEYS - validated):
- if entry.get(field) not in (None, "", [], {}):
- row[field] = entry[field]
- key = entry.get("api_key")
- if is_redacted_credential_preview(key):
- # The renderer only ever saw a preview: keep the stored key of the route it came from (a rename names
- # it in original_name; once that save landed, the route is stored under its new name).
- source = stored.get(_text(entry, "original_name")) or stored.get(row["name"]) or {}
- key = source.get("api_key")
- if isinstance(key, str) and key.strip():
- row["api_key"] = key.strip()
- return row
- def _write_backend_block(profile: Optional[str], backend: str, build: Callable[[dict], dict]) -> dict:
- from hermes_cli.config import format_managed_message, is_managed
- if is_managed():
- raise _managed_install(format_managed_message(f"save delegation.backends.{backend}"))
- with config_write_scope(profile):
- config = load_config()
- blocks = _section(_section(config, "delegation"), "backends")
- block = build(_mapping(blocks, backend))
- blocks[backend] = block
- save_config(config)
- return block
- @router.put("/api/delegation/backends/model_map")
- async def save_model_routes(body: DelegationModelMapUpdate, profile: Optional[str] = None):
- """Replace ``delegation.backends.model_map`` (``options`` + ``default``) after validating every route."""
- def _build(current: dict) -> dict:
- stored = {_text(o, "name"): o for o in current.get("options") or [] if isinstance(o, dict)}
- options = [_clean_model_option(i, dict(o), stored) for i, o in enumerate(body.options)]
- names = [o["name"] for o in options]
- duplicate = next((n for n in names if names.count(n) > 1), None)
- if duplicate:
- raise _bad_request(f"Two routes are named {duplicate!r}; route names must be unique.")
- block: dict[str, Any] = {"options": options}
- default = _check_default(body.default, names, "route")
- if default:
- block["default"] = default
- return block
- block = await asyncio.to_thread(_write_backend_block, body.profile or profile, MODEL_MAP, _build)
- return {"ok": True, MODEL_MAP: {"options": _redacted_options(block["options"]),
- "default": block.get("default")}}
- @router.put("/api/delegation/backends/profile_routes")
- async def save_profile_routes(body: DelegationProfileRoutesUpdate, profile: Optional[str] = None):
- """Replace ``delegation.backends.profile_routes`` (``profiles`` + ``default``); every name must be an
- existing profile."""
- def _build(_current: dict) -> dict:
- known = set(_profile_names())
- profiles: list[dict[str, str]] = []
- names: list[str] = []
- for entry in body.profiles:
- name = _text(entry, "name")
- if not name:
- raise _bad_request("A profile route needs a profile name.")
- if name not in known:
- raise _bad_request(f"Profile {name!r} does not exist.")
- if name in names:
- raise _bad_request(f"Profile {name!r} is listed twice.")
- names.append(name)
- description = _text(entry, "description")
- profiles.append({"name": name, **({"description": description} if description else {})})
- block: dict[str, Any] = {"profiles": profiles}
- default = _check_default(body.default, names, "profile")
- if default:
- block["default"] = default
- return block
- block = await asyncio.to_thread(_write_backend_block, body.profile or profile, PROFILE_ROUTES, _build)
- return {"ok": True, PROFILE_ROUTES: {"profiles": block["profiles"], "default": block.get("default")}}
|