delegate_tool_routes.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339
  1. """Per-task child routes from the active delegation provider (``delegation.backend``).
  2. ``delegate_task`` asks the active :class:`agent.delegation_provider.DelegationProvider` for one
  3. route per task, validates the model's provider-declared parameters, turns each route into the
  4. credential bundle child construction already consumes (the same resolver ``delegation.*`` uses),
  5. and binds a profile route's scope around the child's construction and conversation. The provider
  6. never touches the lifecycle; this module is the whole contract between the two.
  7. """
  8. from __future__ import annotations
  9. import contextlib
  10. import json
  11. import logging
  12. import re
  13. from dataclasses import dataclass, replace
  14. from pathlib import Path
  15. from typing import Any, Iterator, Mapping, Optional
  16. from agent.delegation_provider import (
  17. RESERVED_TASK_PARAMETERS, ROUTE_KEYS, DelegationProvider, DelegationRouteError,
  18. )
  19. logger = logging.getLogger("tools.delegate_tool") # log-record parity with the origin module
  20. _PARAM_NAME_RE = re.compile(r"^[a-z][a-z0-9_]{0,63}$")
  21. @dataclass
  22. class TaskRoute:
  23. """How core builds one child: the credential bundle (with a route's speed tier applied), the config block
  24. owning its fallback policy, an optional reasoning override, and the profile home it runs as (None = this one).
  25. ``error`` set = the backend could not route this task: it is refused alone and its siblings still run."""
  26. creds: dict[str, Any]
  27. routing_cfg: dict[str, Any]
  28. reasoning_effort: Any = None
  29. profile_home: Optional[Path] = None
  30. label: Optional[str] = None
  31. backend: str = "default"
  32. error: Optional[str] = None
  33. def report(self) -> Optional[dict[str, Any]]:
  34. """The ``route`` a backend-routed task's result carries (None for the default backend's unlabelled route)."""
  35. if self.backend == "default" and not self.label:
  36. return None
  37. return {"backend": self.backend, **({"label": self.label} if self.label else {})}
  38. def refused_entry(self, index: int) -> dict[str, Any]:
  39. """Result entry for a task this route refused: no child was built for it."""
  40. return {"task_index": index, "status": "error", "summary": None, "error": self.error, "api_calls": 0,
  41. "duration_seconds": 0, "route": {**(self.report() or {"backend": self.backend}), "refused": True}}
  42. def _active_provider(config: Mapping[str, Any]) -> DelegationProvider:
  43. from agent.delegation_registry import get_active_provider
  44. return get_active_provider(config)
  45. def _declared_parameters(provider: DelegationProvider, config: Mapping[str, Any]) -> dict[str, dict[str, Any]]:
  46. """The provider's per-task parameters, minus anything malformed or reserved (warned)."""
  47. try:
  48. raw = provider.task_parameters(config)
  49. except Exception: # plugin boundary: a broken provider costs its parameters, never the delegate_task tool
  50. logger.warning("delegation provider %s.task_parameters() raised; no extra parameters", provider.name,
  51. exc_info=True)
  52. return {}
  53. if not isinstance(raw, Mapping):
  54. return {}
  55. accepted: dict[str, dict[str, Any]] = {}
  56. for name, schema in raw.items():
  57. if not isinstance(name, str) or not _PARAM_NAME_RE.match(name) or name in RESERVED_TASK_PARAMETERS:
  58. logger.warning("delegation provider %s: task parameter %r refused (reserved or invalid name)",
  59. provider.name, name)
  60. continue
  61. if isinstance(schema, Mapping):
  62. accepted[name] = json.loads(json.dumps(schema)) # plain, detached copy
  63. return accepted
  64. def schema_extension(config: Mapping[str, Any]) -> tuple[dict[str, dict[str, Any]], str]:
  65. """``(extra task properties, description addendum)`` for the active provider (none for the
  66. default strategy, whose schema is the base one)."""
  67. try:
  68. provider = _active_provider(config)
  69. except DelegationRouteError:
  70. return {}, "" # fails closed at spawn time, with the fix; the schema just stays the base one
  71. try:
  72. addendum = provider.description(config)
  73. except Exception: # plugin boundary: a broken provider costs its guidance, never the delegate_task tool
  74. logger.warning("delegation provider %s.description() raised", provider.name, exc_info=True)
  75. addendum = ""
  76. return _declared_parameters(provider, config), addendum.strip() if isinstance(addendum, str) else ""
  77. def _param_error(index: int, name: str, value: Any, schema: Mapping[str, Any]) -> Optional[str]:
  78. enum = schema.get("enum")
  79. if isinstance(enum, list) and value not in enum:
  80. return f"Task {index}: '{name}' must be one of {', '.join(map(str, enum))} (got {value!r})."
  81. return None
  82. def _clean_route(provider_name: str, route: Any) -> dict[str, Any]:
  83. """The route keys of a provider's answer. Other keys are dropped silently: returning the whole
  84. ``delegation`` section (``dict(config)``, the default route) legitimately carries lifecycle knobs."""
  85. if not isinstance(route, Mapping):
  86. raise DelegationRouteError(f"delegation backend '{provider_name}' returned no route.")
  87. return {k: v for k, v in route.items() if k in ROUTE_KEYS}
  88. def _profile_home(name: Any) -> Path:
  89. from hermes_cli.profiles import get_profile_dir, profile_exists
  90. if not isinstance(name, str) or not name.strip() or not profile_exists(name):
  91. raise DelegationRouteError(f"Profile {name!r} does not exist (see `hermes profile list`).")
  92. return Path(get_profile_dir(name))
  93. @contextlib.contextmanager
  94. def delegated_profile_scope(home: Any) -> Iterator[None]:
  95. """Run the block as profile ``home``: HERMES_HOME override, that profile's secret scope,
  96. multiplex semantics when it is not this process's own profile, and its terminal policy - the
  97. binding a multiplexed gateway applies to a routed turn (gateway/AGENTS.md § Profile scope).
  98. A no-op for anything but a path (``None``: no profile route) and for the home already in effect."""
  99. from hermes_constants import get_hermes_home, get_routing_process_hermes_home, hermes_home_key
  100. if not isinstance(home, (str, Path)) or hermes_home_key(home) == hermes_home_key(get_hermes_home()):
  101. yield
  102. return
  103. from agent.secret_scope import (
  104. reset_multiplex_context, reset_secret_scope, set_multiplex_context, set_secret_scope,
  105. )
  106. from hermes_cli.env_loader import hydrate_profile_secret_sources
  107. from hermes_constants import reset_hermes_home_override, set_hermes_home_override
  108. from tools.terminal_scope import install_profile_terminal_scope, reset_terminal_scope
  109. from tui_gateway.launch_profile_policy import owner_secret_scope
  110. routed = hermes_home_key(home) != hermes_home_key(get_routing_process_hermes_home())
  111. hydrate_profile_secret_sources(home)
  112. # Each step is entered inside the stack, so one that raises unwinds the ones already bound and the
  113. # parent never stays in the child's profile (same discipline as the gateway's routed-turn scope).
  114. with contextlib.ExitStack() as stack:
  115. stack.callback(reset_hermes_home_override, set_hermes_home_override(str(home)))
  116. stack.callback(reset_secret_scope, set_secret_scope(owner_secret_scope(home), profile_home=str(home)))
  117. if routed:
  118. stack.callback(reset_multiplex_context, set_multiplex_context(True))
  119. stack.callback(reset_terminal_scope, install_profile_terminal_scope(home))
  120. yield
  121. def child_profile_scope(child: Any) -> contextlib.AbstractContextManager:
  122. """The profile scope a built child's own work runs in (its startup credential lease, every conversation turn
  123. incl. the output_schema retry); a no-op for children without a profile route. Parent bookkeeping (registry,
  124. heartbeat, progress, result assembly) stays outside it."""
  125. return delegated_profile_scope(getattr(child, "_delegate_profile_home", None))
  126. def _profile_model_request(cfg: Mapping[str, Any]) -> dict[str, Any]:
  127. """``resolve_runtime_provider`` kwargs for a profile's primary model, decoded by the same owner CLI startup
  128. uses (``resolve_startup_model_route``): a ``model.default`` alias takes the alias's model, endpoint and key."""
  129. from hermes_cli.model_switch import resolve_startup_model_route
  130. model_cfg = cfg.get("model")
  131. if isinstance(model_cfg, dict):
  132. model = model_cfg.get("default") or model_cfg.get("model")
  133. cfg_provider = str(model_cfg.get("provider") or "").strip()
  134. else:
  135. model, cfg_provider = (model_cfg if isinstance(model_cfg, str) else None), ""
  136. request: dict[str, Any] = {"target_model": model or None}
  137. if not isinstance(model, str) or not model.strip():
  138. return request
  139. startup = resolve_startup_model_route(
  140. model, current_provider=cfg_provider.lower(), user_providers=cfg.get("providers"),
  141. custom_providers=cfg.get("custom_providers"), alias_config=dict(cfg))
  142. if startup is not None:
  143. request = {"target_model": startup.model, "requested": startup.provider or None,
  144. "explicit_base_url": startup.base_url or None, "explicit_api_key": startup.api_key or None}
  145. return request
  146. def _refuse_under_worker_snapshot(home: Path) -> None:
  147. """A managed worker (kanban, safe mode, managed sessions) runs on the session config frozen at creation:
  148. every config reader returns that snapshot and the process never opens profile files, so another profile's
  149. config.yaml is unreachable here. Refuse rather than pair the launch profile's model with the target's keys."""
  150. from agent.safe_worker_policy import worker_config_snapshot
  151. from hermes_constants import get_hermes_home, hermes_home_key
  152. if worker_config_snapshot() is not None and hermes_home_key(home) != hermes_home_key(get_hermes_home()):
  153. raise DelegationRouteError(
  154. f"Profile routes are unavailable in a managed worker session (its config is frozen at creation): "
  155. f"cannot run as the profile at {home}. Delegate without a profile.")
  156. def _profile_route(home: Path) -> TaskRoute:
  157. """The profile's own primary route, resolved inside its scope (its config.yaml + secrets). The
  158. child never borrows the launching profile's key, pool, fallback chain or reasoning level."""
  159. from hermes_cli.config import load_config_readonly
  160. from hermes_cli.runtime_provider import resolve_runtime_provider
  161. from hermes_constants import resolve_reasoning_config
  162. from tools.delegate_tool_config import ResolvedReasoning, _credential_bundle, _require_pinned_command
  163. _refuse_under_worker_snapshot(home)
  164. with delegated_profile_scope(home):
  165. cfg = load_config_readonly() or {}
  166. request = _profile_model_request(cfg)
  167. try:
  168. rt = resolve_runtime_provider(**request)
  169. except Exception as exc:
  170. raise DelegationRouteError(f"Profile at {home} has no usable model provider: {exc}") from exc
  171. model = request["target_model"] or rt.get("model") or None
  172. fallback = cfg.get("fallback_providers")
  173. # A named custom provider resolves to provider "custom": keep its name as the identity (as delegation.provider
  174. # does) so two named providers sharing one URL never lease each other's pool.
  175. requested = str(rt.get("requested_provider") or "").strip()
  176. provider = requested if rt.get("provider") == "custom" and requested.lower() not in ("", "auto") else rt.get("provider")
  177. # Same rule as delegation.provider (#80450): a pinned ACP command that is not on PATH refuses the spawn.
  178. _require_pinned_command(
  179. rt.get("command"), f"Profile at {home} is pinned to the '{rt.get('command')}' command, which was not "
  180. f"found on PATH. Install it or route this task elsewhere.")
  181. creds = _credential_bundle(
  182. model, provider, rt.get("base_url"),
  183. rt.get("api_key") or "no-key-required", rt.get("api_mode"), dict(rt.get("request_overrides") or {}),
  184. command=rt.get("command"), args=list(rt.get("args") or []),
  185. )
  186. return TaskRoute(creds, {"fallback_providers": fallback if isinstance(fallback, list) else []},
  187. ResolvedReasoning(resolve_reasoning_config(cfg, model or "")), home)
  188. def _with_inherited_fallback(route: dict[str, Any], config: Mapping[str, Any]) -> dict[str, Any]:
  189. """A route without a fallback chain of its own takes ``delegation.fallback_providers`` (an explicit ``[]`` on the
  190. route still disables fallback). A profile route keeps its profile's own chain."""
  191. if route.get("profile") or route.get("fallback_providers") is not None:
  192. return route
  193. inherited = config.get("fallback_providers")
  194. return route if inherited is None else {**route, "fallback_providers": inherited}
  195. def _resolve_route(route: dict[str, Any], parent_agent: Any, backend: str) -> TaskRoute:
  196. if route.get("profile"):
  197. return replace(_profile_route(_profile_home(route["profile"])), backend=backend)
  198. from tools.delegate_tool import _resolve_delegation_credentials # the facade is the patch seam
  199. creds = _resolve_delegation_credentials(route, parent_agent)
  200. if route.get("service_tier") not in (None, ""):
  201. from tools.delegate_tool_tuning import task_service_tier
  202. creds = {**creds, **task_service_tier(str(route["service_tier"]), creds, parent_agent)}
  203. return TaskRoute(creds, route, route.get("reasoning_effort"), None, None, backend)
  204. def _route_to_task_route(route: dict[str, Any], parent_agent: Any, cache: dict[str, TaskRoute],
  205. config: Optional[Mapping[str, Any]] = None, backend: str = "default") -> TaskRoute:
  206. label = route.get("label") if isinstance(route.get("label"), str) else None
  207. route = _with_inherited_fallback(route, config or {})
  208. # The label is display-only: two labels on one route (or one profile) resolve once.
  209. key = json.dumps({k: v for k, v in route.items() if k != "label"}, sort_keys=True, default=str)
  210. if key not in cache:
  211. cache[key] = _resolve_route(route, parent_agent, backend)
  212. return replace(cache[key], label=label)
  213. def _check_backend_effort(index: int, route: Mapping[str, Any], config: Mapping[str, Any]) -> None:
  214. """A backend's ``reasoning_effort`` must be a known level: a typo is a tool error, never the parent's level.
  215. The ``delegation`` section's own value (the default route, ``dict(config)``) keeps its warn-and-inherit rule."""
  216. effort = route.get("reasoning_effort")
  217. if route.get("profile") or effort in (None, "") or effort == config.get("reasoning_effort"):
  218. return
  219. from hermes_constants import VALID_REASONING_EFFORTS, parse_reasoning_effort
  220. if parse_reasoning_effort(effort) is None:
  221. raise DelegationRouteError(
  222. f"Task {index}: unknown reasoning_effort {effort!r} on this route. "
  223. f"Use none or one of: {', '.join(VALID_REASONING_EFFORTS)}.")
  224. def _undeclared_error(provider: DelegationProvider, index: int, names: list[str], config: Mapping[str, Any]) -> str:
  225. """Why a task carrying parameters the session's backend does not declare is refused (a model inventing them, or
  226. a session whose tools came from another build than its backend); dropping them would run the task on this
  227. backend's default route. ``/delegation <backend> --now`` or ``/new`` rebuilds the tools and the backend together."""
  228. from agent.delegation_registry import _registry
  229. active = provider.name
  230. listed = ", ".join(f"'{name}'" for name in names)
  231. owners = sorted({other.name for other in _registry.list_providers() if other.name != active
  232. and set(names) & set(_declared_parameters(other, config))})
  233. head = f"Task {index}: the delegation backend is '{active}', which does not take {listed}"
  234. fix = (f"run `/delegation {active} --now` to rebuild this session's delegate_task for '{active}', "
  235. f"or start a new session with /new")
  236. if owners:
  237. quoted = ", ".join(f"'{owner}'" for owner in owners)
  238. return (f"{head} (declared by {quoted}), so this task was not started. This session's delegate_task was "
  239. f"built for another backend: {fix}.")
  240. return (f"{head}, and no installed delegation backend does, so this task was not started. Resend it without "
  241. f"{listed}; if this session's delegate_task tool offers {listed}, {fix}.")
  242. def _route_one(provider: DelegationProvider, declared: dict[str, dict[str, Any]], index: int,
  243. task: Mapping[str, Any], config: Mapping[str, Any]) -> dict[str, Any]:
  244. undeclared = sorted(name for name, value in task.items()
  245. if value is not None and name not in declared and name not in RESERVED_TASK_PARAMETERS)
  246. if undeclared:
  247. raise DelegationRouteError(_undeclared_error(provider, index, undeclared, config))
  248. params = {name: task[name] for name in declared if task.get(name) is not None}
  249. for name, value in params.items():
  250. error = _param_error(index, name, value, declared[name])
  251. if error:
  252. raise DelegationRouteError(error)
  253. payload = {"goal": task.get("goal"), "context": task.get("context"), "index": index, **params}
  254. try:
  255. return _clean_route(provider.name, provider.route_task(payload, config))
  256. except DelegationRouteError as exc:
  257. raise DelegationRouteError(f"Task {index}: {exc}") from exc
  258. except Exception as exc:
  259. logger.warning("delegation provider %s.route_task() raised", provider.name, exc_info=True)
  260. raise DelegationRouteError(f"Task {index}: delegation backend '{provider.name}' failed: {exc}") from exc
  261. def resolve_task_routes(task_list: list[dict[str, Any]], config: Mapping[str, Any], parent_agent: Any,
  262. ) -> tuple[list[TaskRoute], Optional[str]]:
  263. """One :class:`TaskRoute` per task from the backend the session's ``delegate_task`` was built from (else
  264. ``delegation.backend``), or ``([], error)`` when that backend cannot run (fails closed, never another backend).
  265. A task the backend cannot route gets a route with ``error`` set; its siblings are unaffected. Identical routes
  266. resolve credentials once per call (the default backend resolves exactly once)."""
  267. from agent.delegation_backends import pinned_backend
  268. if pinned := pinned_backend(parent_agent):
  269. config = {**config, "backend": pinned}
  270. try:
  271. provider = _active_provider(config)
  272. except DelegationRouteError as exc:
  273. return [], str(exc)
  274. declared = _declared_parameters(provider, config)
  275. cache: dict[str, TaskRoute] = {}
  276. routes: list[TaskRoute] = []
  277. for i, task in enumerate(task_list):
  278. try:
  279. route = _route_one(provider, declared, i, task, config)
  280. _check_backend_effort(i, route, config)
  281. routes.append(_route_to_task_route(route, parent_agent, cache, config, provider.name))
  282. except ValueError as exc: # DelegationRouteError, the credential resolver's and the tier check's refusals
  283. routes.append(TaskRoute({}, {}, backend=provider.name, error=str(exc)))
  284. return routes, None
  285. def route_for_config(routing_cfg: dict[str, Any], parent_agent: Any) -> TaskRoute:
  286. """The route an internal caller's explicit config block describes (``/review`` ->
  287. ``auxiliary.review``); bypasses the provider, as those callers own their route."""
  288. from tools.delegate_tool import _resolve_delegation_credentials # the facade is the patch seam
  289. return TaskRoute(_resolve_delegation_credentials(routing_cfg, parent_agent), routing_cfg)