delegation_backends.py 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. """Which delegation backend Hermes uses: the public API behind a ``/delegation`` command.
  2. ``delegation.backend`` in config.yaml is the saved choice. A session routes on the backend its ``delegate_task``
  3. schema was built from (``agent._delegation_backend``, captured with its tools and pinned with them to the session
  4. row), because that schema (a backend's per-task parameters) is cached prompt: a save, or a config.yaml edit,
  5. changes nothing in a running chat and applies from its next session (``/new``). ``apply_now`` opts into
  6. rebuilding the calling session's tools at its next turn instead, so routing and schema switch together there:
  7. one prompt-cache break, the rule every slash command that changes prompt state follows (``--now``). A task
  8. carrying parameters its session's backend does not declare is still refused (``tools/delegate_tool_routes.py``).
  9. Session keys are the ``session_key`` a plugin command handler receives: the gateway/TUI route key, or the
  10. session id on the classic in-process CLI. A turn resolves the same key from its session context, else from the
  11. agent's session id.
  12. """
  13. from __future__ import annotations
  14. import threading
  15. from dataclasses import asdict, dataclass
  16. from typing import Any
  17. from agent.delegation_registry import DEFAULT_BACKEND, _registry, backend_status, configured_backend
  18. from agent.provider_registry import lower_key
  19. _rebuild_requests: set[str] = set()
  20. _lock = threading.Lock()
  21. @dataclass(frozen=True)
  22. class BackendInfo:
  23. """One selectable delegation backend: ``available`` False carries the ``reason`` it cannot run."""
  24. name: str
  25. label: str
  26. description: str
  27. available: bool
  28. reason: str = ""
  29. def _info(name: str) -> BackendInfo:
  30. provider, reason = backend_status(name)
  31. if provider is None:
  32. return BackendInfo(name, name, "", False, reason)
  33. return BackendInfo(name, provider.display_name, provider.summary, not reason, reason)
  34. def list_backends() -> list[BackendInfo]:
  35. """``default`` first, then every registered backend (unavailable ones included, with their reason)."""
  36. names = [DEFAULT_BACKEND, *sorted({p.name for p in _registry.list_providers()} - {DEFAULT_BACKEND})]
  37. return [_info(name) for name in names]
  38. def saved_backend() -> str:
  39. """``delegation.backend`` as config.yaml has it now: what a tool build reads."""
  40. from tools.delegate_tool_config import _load_config
  41. return configured_backend(_load_config())
  42. def _delegate_def(tools: Any) -> Any:
  43. return next((t for t in tools or () if isinstance(t, dict)
  44. and (t.get("function") or {}).get("name") == "delegate_task"), None)
  45. def adopt_built_backend(agent: Any, defs: Any, backend: str) -> None:
  46. """Record ``backend`` as the session's when the agent's ``delegate_task`` is the one ``defs`` carries (built
  47. from ``backend``, or pinned with it); a kept older definition keeps the backend it was built from."""
  48. if _delegate_def(getattr(agent, "tools", None)) == _delegate_def(defs):
  49. agent._delegation_backend = backend
  50. def pinned_backend(agent: Any) -> str:
  51. """The backend ``agent``'s ``delegate_task`` was built from; ``""`` for no agent (or one never built), whose
  52. tasks route on config.yaml's."""
  53. pinned = getattr(agent, "_delegation_backend", None)
  54. return pinned if isinstance(pinned, str) else ""
  55. def set_global_backend(name: str, *, session_key: str = "", apply_now: bool = False) -> None:
  56. """Persist ``delegation.backend`` to the active profile's config.yaml (raw user config, never merged
  57. defaults). Running sessions keep routing on the backend their tools were built from; ``apply_now`` rebuilds
  58. ``session_key``'s tools at that session's next turn, so it routes on and offers the new backend's parameters
  59. from there (an opt-in prompt-cache break); otherwise sessions pick the switch up from ``/new``. Raises ``PermissionError`` on a package-manager-managed
  60. install (its config.yaml is not ours to write) and ``ValueError`` (with the reason) for a backend that cannot
  61. run or an ``apply_now`` without a session, before anything is written."""
  62. from hermes_cli.config import (
  63. atomic_config_write, format_managed_message, get_config_path, is_managed, read_user_config_raw,
  64. )
  65. if is_managed():
  66. raise PermissionError(format_managed_message("set delegation.backend"))
  67. if apply_now and not session_key:
  68. raise ValueError("No session to apply the switch to: apply_now needs the command's session_key.")
  69. key = lower_key(name)
  70. info = _info(key)
  71. if not info.available:
  72. raise ValueError(info.reason)
  73. path = get_config_path()
  74. user_config = read_user_config_raw(path)
  75. section = user_config.get("delegation")
  76. if not isinstance(section, dict):
  77. section = user_config["delegation"] = {}
  78. section["backend"] = key
  79. atomic_config_write(path, user_config)
  80. if apply_now:
  81. with _lock:
  82. _rebuild_requests.add(session_key)
  83. def _current_session_key(agent: Any) -> str:
  84. from gateway.session_context import get_session_env
  85. return get_session_env("HERMES_SESSION_KEY", "") or str(getattr(agent, "session_id", "") or "")
  86. def apply_requested_tool_rebuild(agent: Any) -> bool:
  87. """Turn start, after the session's tools are restored: rebuild ``agent.tools`` (and with it the backend the
  88. session routes on) if ``set_global_backend(apply_now=True)`` asked for this session, and pin both to the
  89. session row so a later fresh agent restores them. True when the tool list changed. Forks (background review, ``/btw``) and
  90. subagents share the session's key but never take its request."""
  91. if getattr(agent, "_turn_origin", None) or getattr(agent, "_delegate_depth", 0):
  92. return False
  93. key = _current_session_key(agent)
  94. with _lock:
  95. if key not in _rebuild_requests:
  96. return False
  97. _rebuild_requests.discard(key)
  98. from hermes_cli.observability.shared_metrics_efficiency import record_cache_break
  99. from tools.mcp_tool_agent import refresh_agent_mcp_tools
  100. before = getattr(agent, "tools", None)
  101. refresh_agent_mcp_tools(agent, quiet_mode=True, content_aware=True) # adopts the saved backend, re-pins a change
  102. if agent.tools is before:
  103. return False
  104. record_cache_break(agent, "toolset_change")
  105. return True
  106. class DelegationBackends:
  107. """``ctx.delegation_backends``: this API for plugins, as plain data. It is a host remote facade, so a plugin
  108. running under ``plugins.isolation: host`` lists and switches the owner process's backend and sessions, not
  109. copies in its own process."""
  110. def list_backends(self) -> list[dict[str, Any]]:
  111. return [asdict(info) for info in list_backends()]
  112. def set_global_backend(self, name: str, *, session_key: str = "", apply_now: bool = False) -> None:
  113. set_global_backend(name, session_key=session_key, apply_now=apply_now)