delegate_tool_config.py 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665
  1. """Delegation config knobs (delegation.* keys) and child credential/provider resolution."""
  2. from __future__ import annotations
  3. import logging
  4. import os
  5. from contextlib import contextmanager
  6. from contextvars import ContextVar
  7. from typing import Any, Dict, Iterator, List, NamedTuple, Optional
  8. from utils import base_url_hostname, is_truthy_value
  9. from hermes_cli.fallback_config import scoped_fallback_chain
  10. logger = logging.getLogger("tools.delegate_tool") # log-record parity with the origin module
  11. # Runtime-provider sentinel for providers that are not natively known; must
  12. # match hermes_cli.runtime_provider.RUNTIME_PROVIDER_TYPE_CUSTOM.
  13. _RUNTIME_PROVIDER_CUSTOM = "custom"
  14. _DEFAULT_MAX_CONCURRENT_CHILDREN = 10
  15. # One-shot guard: _get_max_concurrent_children() runs on every get_definitions()
  16. # schema rebuild, so the >10 cost advisory would otherwise log on every turn.
  17. _HIGH_CONCURRENCY_WARNED = False
  18. MAX_DEPTH = 1 # flat by default: parent (0) -> child (1); deeper needs max_spawn_depth
  19. _MIN_SPAWN_DEPTH = 1 # floor for the configurable cap; MAX_DEPTH stays the default
  20. _LEGACY_MAX_ASYNC_WARNED = False
  21. # No default wall-clock cap on children: legitimate heavy work (deep reviews, research fan-outs, slow reasoning
  22. # models) was being killed mid-task. Stuck-child detection is the heartbeat staleness monitor;
  23. # delegation.child_timeout_seconds opts back in.
  24. DEFAULT_CHILD_TIMEOUT: Optional[float] = None
  25. def _cfg() -> dict:
  26. """The ``delegation`` section, read through the origin so tests can patch it."""
  27. from tools.delegate_tool import _load_config
  28. return _load_config()
  29. # ── Subagent approval callbacks ─────────────────────────────────────────────
  30. # Subagent worker threads don't inherit the CLI's threading.local approval
  31. # callback, so prompt_dangerous_approval() would fall back to input() and
  32. # deadlock the parent's prompt_toolkit TUI. Every worker gets a non-interactive
  33. # callback via ThreadPoolExecutor(initializer=...): deny by default, approve when
  34. # delegation.subagent_auto_approve is true. Both warn for audit. Gateway sessions
  35. # are unaffected (they resolve approvals via tools/approval.py's per-session queue).
  36. def _subagent_auto_deny(command: str, description: str, **kwargs) -> str:
  37. """Auto-deny (safe default): returns 'deny' so the child sees a recoverable refusal."""
  38. logger.warning(
  39. "Subagent auto-denied dangerous command: %s (%s). Set delegation.subagent_auto_approve: true to allow.",
  40. command, description,
  41. )
  42. return "deny"
  43. def _subagent_auto_approve(command: str, description: str, **kwargs) -> str:
  44. """Auto-approve (opt-in YOLO via delegation.subagent_auto_approve): returns 'once'."""
  45. logger.warning("Subagent auto-approved dangerous command: %s (%s)", command, description)
  46. return "once"
  47. def _get_subagent_approval_callback():
  48. """Callback for subagent worker threads per delegation.subagent_auto_approve (default False)."""
  49. if is_truthy_value(_cfg().get("subagent_auto_approve", False)):
  50. return _subagent_auto_approve
  51. return _subagent_auto_deny
  52. def _knob(key: str, env_var: Optional[str], parse, default, invalid_msg: str):
  53. """delegation.<key> > <env_var> > default. A config value that fails ``parse`` logs ``invalid_msg`` (``%r`` = the
  54. value) and yields the default; an env value that fails is silently ignored."""
  55. val = _cfg().get(key)
  56. if val is not None:
  57. try:
  58. return parse(val)
  59. except (TypeError, ValueError):
  60. logger.warning(invalid_msg, val)
  61. return default
  62. env_val = os.getenv(env_var) if env_var else None
  63. if env_val:
  64. try:
  65. return parse(env_val)
  66. except (TypeError, ValueError):
  67. pass
  68. return default
  69. def _warn_once(flag_name: str, message: str, *args: Any) -> None:
  70. """Module-global one-shot warning (``flag_name`` is the ``_*_WARNED`` global)."""
  71. if not globals()[flag_name]:
  72. globals()[flag_name] = True
  73. logger.warning(message, *args)
  74. def _get_oneshot_max_children() -> int:
  75. """delegation.oneshot_max_children (total children per finite one-shot session; 0 = unlimited)."""
  76. return _knob(
  77. "oneshot_max_children", None, lambda v: max(0, int(v)), 2,
  78. "delegation.oneshot_max_children=%r is not a valid integer; using default 2",
  79. )
  80. def _get_prefix_stagger_seconds() -> float:
  81. """delegation.prefix_stagger_seconds: longest a batch sibling waits for the first child's response to start so
  82. its request reads the shared prompt cache (0 = off, the default). See tools/delegate_tool_prefix_gate.py."""
  83. return _knob(
  84. "prefix_stagger_seconds", None, lambda v: min(60.0, max(0.0, float(v))), 0.0,
  85. "delegation.prefix_stagger_seconds=%r is not a number; the prompt-cache warm-up wait is off",
  86. )
  87. def _get_max_concurrent_children() -> int:
  88. """delegation.max_concurrent_children > DELEGATION_MAX_CONCURRENT_CHILDREN env > 10.
  89. Floor of 1 is the only bound enforced; there is no ceiling.
  90. """
  91. result = _knob(
  92. "max_concurrent_children", "DELEGATION_MAX_CONCURRENT_CHILDREN", lambda v: max(1, int(v)),
  93. _DEFAULT_MAX_CONCURRENT_CHILDREN,
  94. f"delegation.max_concurrent_children=%r is not a valid integer; using default {_DEFAULT_MAX_CONCURRENT_CHILDREN}",
  95. )
  96. if result > 10 and _cfg().get("max_concurrent_children") is not None:
  97. _warn_once(
  98. "_HIGH_CONCURRENCY_WARNED", "delegation.max_concurrent_children=%d: each child consumes API tokens "
  99. "independently. High values multiply cost linearly.", result,
  100. )
  101. return result
  102. def _get_independent_completions() -> bool:
  103. """delegation.independent_completions (bool, default False): split a background call into per-task / per-group
  104. completion messages that land as each finishes. Off = one consolidated message when the whole call is done."""
  105. return is_truthy_value(_cfg().get("independent_completions", False))
  106. # delegation.gateway_mode: "background" (alias "async") always detaches; "inline" joins in the turn; anything else is
  107. # "auto". Read from the gateway turn's own (profile-scoped) user config, not from this process's config.
  108. _GATEWAY_MODES = {"inline": True, "background": False, "async": False}
  109. def gateway_delegation_inline(user_config: Any, platform_key: str, *, interim_enabled: bool) -> bool:
  110. """Whether a gateway session joins its top-level delegations inside the turn (``delegation.gateway_mode``).
  111. ``auto`` (default) joins on a human chat whose interim assistant messages are off (the gateway's resolved
  112. ``display.interim_assistant_messages``, platform overrides included): there the "status, end your turn" reply
  113. the background path asks for would be delivered as the turn's answer, then the real answer as a second message.
  114. API, local and webhook surfaces keep the background path under ``auto``."""
  115. from gateway.session_context import NON_MESSAGING_SESSION_SURFACES
  116. section = user_config.get("delegation") if isinstance(user_config, dict) else None
  117. mode = str(section.get("gateway_mode") or "auto").strip().lower() if isinstance(section, dict) else "auto"
  118. if mode in _GATEWAY_MODES:
  119. return _GATEWAY_MODES[mode]
  120. return not interim_enabled and str(platform_key or "").lower() not in NON_MESSAGING_SESSION_SURFACES
  121. # Set by the gateway around building a session's agent; read once by that agent's first tool build.
  122. _GATEWAY_DELEGATION_INLINE: ContextVar[bool] = ContextVar("hermes_gateway_delegation_inline", default=False)
  123. @contextmanager
  124. def gateway_delegation_inline_scope(inline: bool) -> Iterator[None]:
  125. """Build an agent whose tools carry the joined ``delegate_task`` variant (frozen on the agent by
  126. :func:`agent_joins_delegation`). Dispatch reads the variant the session carries, not this flag."""
  127. token = _GATEWAY_DELEGATION_INLINE.set(bool(inline))
  128. try:
  129. yield
  130. finally:
  131. _GATEWAY_DELEGATION_INLINE.reset(token)
  132. def agent_joins_delegation(agent: Any) -> bool:
  133. """The gateway's inline decision, frozen on *agent* at its first tool build (like ``agent_is_oneshot``) and
  134. re-frozen from a restored tools[] pin (``tools.delegate_tool.adopt_session_delegation_mode``), so later rebuilds
  135. outside the build scope keep the session's ``delegate_task`` bytes. Dispatch does not read this: it follows the
  136. schema the session carries (``tools.delegate_tool.session_joins_delegation``)."""
  137. cached = getattr(agent, "_delegation_inline", None)
  138. if not isinstance(cached, bool):
  139. cached = _GATEWAY_DELEGATION_INLINE.get()
  140. agent._delegation_inline = cached
  141. return cached
  142. def _get_worktree_isolation() -> bool:
  143. """delegation.worktree_isolation (bool, default False): each child gets its own
  144. git worktree off the parent's HEAD so parallel children never contend for one
  145. working copy. Git-only and local-backend-only; otherwise silently ignored."""
  146. return bool(_cfg().get("worktree_isolation", False))
  147. def _get_max_async_children() -> int:
  148. """Concurrency cap for background delegations == delegation.max_concurrent_children. At capacity a new async
  149. dispatch is REJECTED (not queued) so a runaway model can't pile up unbounded background work; the caller then
  150. runs synchronously. A leftover ``delegation.max_async_children`` key is ignored with a one-time warning."""
  151. from tools.delegate_tool import _get_max_concurrent_children
  152. if _cfg().get("max_async_children") is not None:
  153. _warn_once(
  154. "_LEGACY_MAX_ASYNC_WARNED", "delegation.max_async_children is deprecated and ignored; "
  155. "delegation.max_concurrent_children now caps background "
  156. "delegations too. Remove the stale key from config.yaml.",
  157. )
  158. return _get_max_concurrent_children()
  159. def _parse_timeout(raw: Any) -> Optional[float]:
  160. """Seconds → None (<= 0 disables) or max(30, value). Raises on non-numeric."""
  161. parsed = float(raw)
  162. return None if parsed <= 0 else max(30.0, parsed)
  163. def _get_child_timeout() -> Optional[float]:
  164. """Inactivity cap for one child (seconds of NO progress), or None (default: no cap). Failures should come from
  165. what the child does (API/tool errors, iteration budget), not a stopwatch: the cap restarts on every sign of
  166. progress — a completed call, a tool change, an activity-clock tick — so a slow provider serving multi-minute
  167. completions never loses a live child, and a child frozen for the whole window is still caught. A configured
  168. value pre-empts nothing the heartbeat staleness monitor would not also catch. delegation.child_timeout_seconds
  169. > 0 opts in (floor 30 s); 0 or negative disables. Env fallback: DELEGATION_CHILD_TIMEOUT_SECONDS."""
  170. return _knob(
  171. "child_timeout_seconds", "DELEGATION_CHILD_TIMEOUT_SECONDS", _parse_timeout, DEFAULT_CHILD_TIMEOUT,
  172. "delegation.child_timeout_seconds=%r is not a valid number; using default (no timeout)",
  173. )
  174. def _get_max_spawn_depth() -> int:
  175. """delegation.max_spawn_depth floored at 1 (no ceiling). Depth 0 is the parent; agents at depths 0..N-1 may spawn,
  176. depth N is the leaf floor. Default 1 is flat. Each extra level multiplies API cost."""
  177. def _floored(v):
  178. ival = int(v)
  179. if ival < _MIN_SPAWN_DEPTH:
  180. logger.warning("delegation.max_spawn_depth=%d below floor %d; using %d", ival, _MIN_SPAWN_DEPTH, _MIN_SPAWN_DEPTH)
  181. return max(_MIN_SPAWN_DEPTH, ival)
  182. return _knob(
  183. "max_spawn_depth", None, _floored, MAX_DEPTH,
  184. f"delegation.max_spawn_depth=%r is not a valid integer; using default {MAX_DEPTH}",
  185. )
  186. def _get_orchestrator_enabled() -> bool:
  187. """delegation.orchestrator_enabled kill switch (default True): False forces every child to leaf."""
  188. val = _cfg().get("orchestrator_enabled", True)
  189. if isinstance(val, bool):
  190. return val
  191. # Accept "true"/"false" strings from YAML that doesn't auto-coerce.
  192. if isinstance(val, str):
  193. return val.strip().lower() in {"true", "1", "yes", "on"}
  194. return True
  195. def _get_inherit_mcp_toolsets() -> bool:
  196. """Whether narrowed child toolsets should keep the parent's MCP toolsets."""
  197. return is_truthy_value(_cfg().get("inherit_mcp_toolsets"), default=True)
  198. def _normalized_runtime_url(value: Any) -> str:
  199. return str(value or "").strip().rstrip("/")
  200. def _inherit_parent_capabilities(parent_agent, override_provider, override_base_url) -> Optional[dict]:
  201. """Parent's endpoint-trust capability map for a child, or None. ``agent.capabilities`` is a trust decision scoped
  202. to one provider+endpoint: inherited ONLY when the child runs the parent's exact route; any provider or base_url
  203. override stays DEFAULT-DENY (matches the /model switch posture).
  204. See #94036, #97292.
  205. """
  206. if override_provider or override_base_url:
  207. return None
  208. parent_caps = getattr(parent_agent, "capabilities", None)
  209. if not isinstance(parent_caps, dict):
  210. return None
  211. return {key: value for key, value in parent_caps.items() if isinstance(key, str) and isinstance(value, bool)}
  212. def _inherit_parent_endpoint(parent_agent, surface_base_url: Optional[str], surface_api_key: Any) -> tuple:
  213. """``(base_url, api_key)`` the parent is actually calling, taken from ONE source. ``parent_agent.base_url`` /
  214. ``api_key`` can lag the live client (old OpenRouter URL vs local Ollama; a fallback runtime the surface attributes
  215. have not caught up with), and pairing the live endpoint with the surface key hands the child a (base_url, key)
  216. pair that was never valid anywhere — an instant, non-retryable 401 (#90009). The live client's key travels with
  217. its URL; the surface attributes are used only when there is no live OpenAI-wire client (native Anthropic/Bedrock
  218. runtimes keep ``client=None``)."""
  219. client_kwargs = getattr(parent_agent, "_client_kwargs", None)
  220. client = getattr(parent_agent, "client", None)
  221. live_candidates = (
  222. (client_kwargs.get("base_url"), client_kwargs.get("api_key")) if isinstance(client_kwargs, dict) else (None, None),
  223. # OpenAI SDK exposes base_url as httpx.URL — coerce before comparing.
  224. (getattr(client, "base_url", ""), getattr(client, "api_key", None)) if client is not None else (None, None),
  225. )
  226. for raw_url, live_key in live_candidates:
  227. url = _normalized_runtime_url(raw_url)
  228. if url and url.startswith(("http://", "https://")):
  229. return url, (live_key or surface_api_key)
  230. return (surface_base_url or None), surface_api_key
  231. def _loaded_pool(key: Any):
  232. """``load_pool(key)`` when it holds credentials, else None."""
  233. from agent.credential_pool import load_pool
  234. pool = load_pool(key)
  235. return pool if pool is not None and pool.has_credentials() else None
  236. def _pool_serves_endpoint(pool: Any, provider: Optional[str], base_url: Optional[str]) -> bool:
  237. """Provider identity AND at least one entry for the child's endpoint; pools without entry metadata pass."""
  238. from agent.credential_pool import (
  239. credential_pool_entry_serves_endpoint as _entry_serves_endpoint, credential_pool_matches_provider,
  240. )
  241. if not credential_pool_matches_provider(pool, provider, base_url=base_url):
  242. return False
  243. entries_fn = getattr(pool, "entries", None)
  244. if not callable(entries_fn):
  245. return True
  246. entries = entries_fn()
  247. return not isinstance(entries, list) or any(_entry_serves_endpoint(entry, base_url) for entry in entries)
  248. def _resolve_child_credential_pool(
  249. effective_provider: Optional[str], parent_agent, effective_base_url: Optional[str] = None,
  250. effective_requested_provider: Optional[str] = None,
  251. ):
  252. """Credential pool for the child: parent's pool (same provider), that provider's own pool, or None (child keeps
  253. its fixed credential). Custom endpoints all collapse to ``provider="custom"``, so they are matched by endpoint
  254. identity (the ``custom:<name>`` pool key) — sharing the parent's pool across different custom endpoints would
  255. overwrite the child's delegated base_url on lease; an unregistered custom endpoint (no custom_providers entry)
  256. keeps the child's fixed credential rather than inherit the parent's.
  257. Custom endpoints are a special case: every direct ``delegation.base_url`` runtime collapses to
  258. ``provider="custom"``, so bare provider equality would treat two *different* custom endpoints as
  259. interchangeable and let the child inherit the parent's pool. We therefore resolve custom runtimes by
  260. endpoint identity (the ``custom:<name>`` pool key derived from the base_url) and only share the parent's
  261. pool when both resolve to the *same* custom endpoint. See #7833.
  262. Named custom providers may share one gateway URL with different credentials, so the inherited
  263. ``requested_provider`` identity takes precedence over URL-only matching (#45763): the child must not
  264. lease the first pool registered for the shared endpoint.
  265. """
  266. parent_pool = getattr(parent_agent, "_credential_pool", None)
  267. if not effective_provider:
  268. return parent_pool
  269. parent_provider = getattr(parent_agent, "provider", None) or ""
  270. try:
  271. if effective_provider == "custom":
  272. from agent.credential_pool import get_custom_provider_pool_key
  273. child_key = get_custom_provider_pool_key(effective_base_url, provider_name=effective_requested_provider)
  274. if child_key is None:
  275. return None
  276. parent_key = get_custom_provider_pool_key(
  277. getattr(parent_agent, "base_url", None), provider_name=getattr(parent_agent, "requested_provider", None),
  278. )
  279. if parent_pool is not None and parent_provider == "custom" and parent_key is not None and parent_key == child_key:
  280. return parent_pool
  281. # The entry's slug may also be a same-named built-in's pool: lease only the rows the entry
  282. # owns, or a fixed entry credential becomes the built-in's account on a shared endpoint.
  283. from agent.custom_entry_pool import custom_entry_for_endpoint, entry_scoped_pool
  284. owner = custom_entry_for_endpoint(effective_base_url, effective_requested_provider)
  285. return entry_scoped_pool(_loaded_pool(child_key), child_key, owner[1] if owner else None)
  286. if effective_provider == parent_provider:
  287. # A same-provider parent with no pool is using a fixed credential.
  288. # Loading a separate provider pool here can replace the inherited
  289. # endpoint and key when the child acquires its startup lease (#71424).
  290. if parent_pool is None:
  291. return None
  292. if not effective_base_url or _pool_serves_endpoint(parent_pool, effective_provider, effective_base_url):
  293. return parent_pool
  294. logger.debug("Parent %s pool has no entry for child endpoint %s; not sharing it",
  295. effective_provider, effective_base_url)
  296. pool = _loaded_pool(effective_provider)
  297. if pool is not None and effective_base_url and not _pool_serves_endpoint(pool, effective_provider, effective_base_url):
  298. return None # child keeps its fixed credential
  299. return pool
  300. except Exception as exc:
  301. if effective_provider == "custom":
  302. logger.debug("Could not resolve custom credential pool for child endpoint '%s': %s", effective_base_url, exc)
  303. else:
  304. logger.debug("Could not load credential pool for child provider '%s': %s", effective_provider, exc)
  305. return None
  306. def _merge_request_overrides(runtime_overrides, explicit_overrides):
  307. """Merge explicit ``delegation.request_overrides`` OVER runtime-derived ones. Explicit top-level keys win;
  308. ``extra_body`` is deep-merged ONE level so provider personality (e.g. ``thinking: {type: disabled}``) survives
  309. unless the explicit dict redefines that exact key. Both sides are deep-copied so transport-side mutation can't
  310. leak into the config/runtime cache. None when both are empty."""
  311. import copy as _copy
  312. runtime_overrides = runtime_overrides if isinstance(runtime_overrides, dict) else None
  313. explicit_overrides = explicit_overrides if isinstance(explicit_overrides, dict) else None
  314. if not runtime_overrides and not explicit_overrides:
  315. return None
  316. merged = _copy.deepcopy(runtime_overrides) if runtime_overrides else {}
  317. explicit = _copy.deepcopy(explicit_overrides) if explicit_overrides else {}
  318. runtime_extra = merged.get("extra_body")
  319. explicit_extra = explicit.pop("extra_body", None)
  320. merged.update(explicit)
  321. if isinstance(runtime_extra, dict) and isinstance(explicit_extra, dict):
  322. runtime_extra.update(explicit_extra)
  323. merged["extra_body"] = runtime_extra
  324. elif explicit_extra is not None:
  325. merged["extra_body"] = explicit_extra
  326. return merged or None
  327. # Native-SDK providers speak their own wire protocol and can't be reached via chat_completions against a base_url:
  328. # always take the runtime-provider path (a configured base_url still flows through it, e.g. a Bedrock region).
  329. _NATIVE_SDK_PROVIDERS = frozenset({"bedrock", "vertex", "google", "google-genai"})
  330. _EXPLICIT_API_MODES = frozenset({"chat_completions", "codex_responses", "anthropic_messages"})
  331. def _require_pinned_command(command: Optional[str], message: str) -> None:
  332. """A pinned ACP transport command must exist on PATH — refuse loudly rather
  333. than let the child silently fall back to another transport."""
  334. import shutil as _shutil
  335. if command and not _shutil.which(command):
  336. raise ValueError(message)
  337. def _credential_bundle(model, provider, base_url, api_key, api_mode, request_overrides, **extra) -> dict:
  338. """The child credential dict every branch of ``_resolve_delegation_credentials`` returns."""
  339. return {
  340. "model": model, "provider": provider, "base_url": base_url, "api_key": api_key, "api_mode": api_mode,
  341. "request_overrides": request_overrides, **extra,
  342. }
  343. def _direct_endpoint_credentials(v: dict, explicit_request_overrides) -> dict:
  344. """``delegation.base_url`` branch: provider/api_mode from URL heuristics."""
  345. # Shared URL-based api_mode detector so Anthropic-compatible direct endpoints (/anthropic suffix: Azure AI
  346. # Foundry, MiniMax, Zhipu, LiteLLM) get the Messages transport instead of 404ing on chat_completions.
  347. # Without this, subagents would default to chat_completions and hit 404s on endpoints that only speak
  348. # the Anthropic Messages protocol. Fixes #10213.
  349. from hermes_cli.runtime_provider import _detect_api_mode_for_url
  350. base_lower = v["base_url"].lower()
  351. host = base_url_hostname(v["base_url"])
  352. provider = "custom"
  353. api_mode = _detect_api_mode_for_url(v["base_url"]) or "chat_completions"
  354. if host == "chatgpt.com" and "/backend-api/codex" in base_lower:
  355. provider, api_mode = "openai-codex", "codex_responses"
  356. elif host == "api.anthropic.com":
  357. provider, api_mode = "anthropic", "anthropic_messages"
  358. elif "api.kimi.com/coding" in base_lower:
  359. api_mode = "anthropic_messages"
  360. # Explicit delegation.api_mode always wins over the URL heuristic; a provider plugin's
  361. # registered dialect counts as explicit.
  362. from agent.transports import registered_api_modes
  363. if v["api_mode"] in _EXPLICIT_API_MODES or (v["api_mode"] and v["api_mode"] in registered_api_modes()):
  364. api_mode = v["api_mode"]
  365. # Preserve the configured provider's request personality on an explicit endpoint.
  366. request_overrides = None
  367. if v["provider"]:
  368. try:
  369. from hermes_cli.runtime_provider import resolve_runtime_provider
  370. runtime = resolve_runtime_provider(requested=v["provider"], target_model=v["model"])
  371. request_overrides = dict(runtime.get("request_overrides") or {}) or None
  372. except Exception as exc:
  373. logger.debug(
  374. "delegation.base_url: runtime resolution for provider '%s' failed; proceeding without request_overrides: %s",
  375. v["provider"], exc,
  376. )
  377. # api_key None → inherited from parent in _build_child_agent
  378. return _credential_bundle(
  379. v["model"], provider, v["base_url"], v["api_key"], api_mode,
  380. _merge_request_overrides(request_overrides, explicit_request_overrides),
  381. )
  382. def _runtime_provider_credentials(v: dict, explicit_request_overrides) -> dict:
  383. """``delegation.provider`` branch: full bundle via the runtime provider system."""
  384. configured_provider = v["provider"]
  385. try:
  386. from hermes_cli.runtime_provider import resolve_runtime_provider
  387. runtime = resolve_runtime_provider(requested=configured_provider, target_model=v["model"])
  388. except Exception as exc:
  389. raise ValueError(
  390. f"Cannot resolve delegation provider '{configured_provider}': {exc}. "
  391. f"Check that the provider is configured (API key set, valid provider name), "
  392. f"or set delegation.base_url/delegation.api_key for a direct endpoint. "
  393. f"Available providers: openrouter, nous, zai, kimi-coding, minimax."
  394. ) from exc
  395. api_key = runtime.get("api_key", "")
  396. if not api_key:
  397. raise ValueError(
  398. f"Delegation provider '{configured_provider}' resolved but has no API key. "
  399. f"Set the appropriate environment variable or run 'hermes auth'."
  400. )
  401. # A pinned ACP transport command must exist — refuse the spawn loudly rather than letting the child
  402. # silently fall back to another transport (#80450).
  403. pinned_command = runtime.get("command")
  404. _require_pinned_command(
  405. pinned_command, f"Delegation provider '{configured_provider}' is pinned to the "
  406. f"'{pinned_command}' command, which was not found on PATH. "
  407. f"Install it or choose a different delegation provider.",
  408. )
  409. # A provider override is assembled into the child as one bundle (see _resolve_child_runtime), so it must
  410. # carry its own endpoint. ACP transports are addressed by command and native-SDK providers by their SDK,
  411. # so neither needs a URL; anything else without one would otherwise be built with no endpoint at all.
  412. if (not runtime.get("base_url") and not pinned_command
  413. and configured_provider.strip().lower() not in _NATIVE_SDK_PROVIDERS):
  414. raise ValueError(
  415. f"Delegation provider '{configured_provider}' resolved without a base_url. "
  416. f"Refusing to build a subagent with an incomplete credential bundle — check the provider's "
  417. f"configuration / auth, or set delegation.base_url for a direct endpoint."
  418. )
  419. return _credential_bundle(
  420. v["model"] or runtime.get("model") or None,
  421. configured_provider if runtime.get("provider") == _RUNTIME_PROVIDER_CUSTOM else runtime.get("provider"),
  422. runtime.get("base_url"), api_key, runtime.get("api_mode"),
  423. _merge_request_overrides(runtime.get("request_overrides"), explicit_request_overrides) or {},
  424. command=pinned_command, args=list(runtime.get("args") or []),
  425. )
  426. def _resolve_delegation_credentials(cfg: dict, parent_agent) -> dict:
  427. """Child credential bundle from the ``delegation`` config section. Three branches: ``base_url`` set → direct
  428. endpoint (``api_key`` None means inherit the parent's key, so providers keyed outside OPENAI_API_KEY work);
  429. ``provider`` set → full bundle via the runtime provider system (same path as CLI/gateway startup); neither →
  430. None values, child inherits everything. ``request_overrides`` is honored on every branch. Raises ValueError
  431. with a user-facing message."""
  432. values = {k: str(cfg.get(k) or "").strip() or None for k in ("model", "provider", "base_url", "api_key")}
  433. values["api_mode"] = str(cfg.get("api_mode") or "").strip().lower() or None
  434. explicit_request_overrides = cfg.get("request_overrides") if isinstance(cfg.get("request_overrides"), dict) else None
  435. is_native_sdk_provider = (values["provider"] or "").strip().lower() in _NATIVE_SDK_PROVIDERS
  436. if values["base_url"] and not is_native_sdk_provider:
  437. return _direct_endpoint_credentials(values, explicit_request_overrides)
  438. if not values["provider"]:
  439. # Pure inherit; explicit request_overrides still merge OVER the parent's.
  440. return _credential_bundle(
  441. values["model"], None, None, None, None,
  442. _merge_request_overrides(getattr(parent_agent, "request_overrides", None), explicit_request_overrides),
  443. )
  444. return _runtime_provider_credentials(values, explicit_request_overrides)
  445. def _load_config() -> dict:
  446. """The ``delegation`` config section (read-only — do NOT mutate). Prefers the shared ``load_config_readonly()``
  447. (follows HERMES_HOME/profile; no deepcopy, since this runs on every get_definitions() rebuild) over the legacy
  448. ``cli.CLI_CONFIG``, which can hide user-set keys — except that ``HERMES_IGNORE_USER_CONFIG=1`` is only honored
  449. by the legacy loader, so it stays authoritative when that flag is set."""
  450. if os.environ.get("HERMES_IGNORE_USER_CONFIG") != "1":
  451. try:
  452. from hermes_cli.config import load_config_readonly
  453. cfg = load_config_readonly().get("delegation") or {}
  454. if isinstance(cfg, dict):
  455. return cfg
  456. except Exception:
  457. pass
  458. try:
  459. from cli import CLI_CONFIG
  460. cfg = CLI_CONFIG.get("delegation") or {}
  461. return cfg if isinstance(cfg, dict) else {}
  462. except Exception:
  463. return {}
  464. # OpenRouter routing filters: inherited from the parent, but reset to these defaults under a pinned provider — parent
  465. # filters (e.g. only=["Anthropic"]) would silently force the child back onto the parent's provider.
  466. # openrouter_min_coding_score stays inherited: model-gated, no-op elsewhere.
  467. _ROUTING_FILTER_DEFAULTS = (
  468. ("providers_allowed", None), ("providers_ignored", None), ("providers_order", None), ("provider_sort", None),
  469. ("provider_require_parameters", False), ("provider_data_collection", ""),
  470. )
  471. _NOUS_PROVIDERS = frozenset({"nous", "nous-portal", "nousresearch"})
  472. def _resolve_child_fallback_chain(parent_agent, routing_cfg: Any, pinned: bool) -> Optional[list[dict[str, Any]]]:
  473. """Fallback chain for a child, owned by the same config block as its route.
  474. Pinned children (provider, endpoint or model override) never borrow the parent chain;
  475. unpinned children inherit it when ``fallback_providers`` is absent/null. An explicit ``[]``
  476. disables fallback either way. Malformed entries are dropped by the canonical normalizer.
  477. Same rule as a pinned cron job (``cron/scheduler.py::_job_fallback_chain``).
  478. """
  479. return scoped_fallback_chain(
  480. getattr(parent_agent, "_fallback_chain", None),
  481. routing_cfg.get("fallback_providers") if isinstance(routing_cfg, dict) else None,
  482. pinned=pinned, owner="delegation")
  483. class ResolvedReasoning(NamedTuple):
  484. """A route's FINAL reasoning config, used as-is (``None`` included = the route's own default): a profile route
  485. resolves its profile's ``agent.reasoning_effort`` / ``reasoning_overrides``, so neither the launching profile's
  486. ``delegation.reasoning_effort`` nor the parent's level may fill it in."""
  487. config: Optional[dict]
  488. def _child_reasoning(parent_agent, delegation_cfg: dict, route_effort: Any) -> Any:
  489. """Child reasoning config: a :class:`ResolvedReasoning` route value as-is, else the route's raw effort >
  490. ``delegation.reasoning_effort`` > the parent's level. Keep the raw value — a YAML ``false`` must disable
  491. thinking, not coerce to "" and inherit."""
  492. if isinstance(route_effort, ResolvedReasoning):
  493. return route_effort.config
  494. child_reasoning = getattr(parent_agent, "reasoning_config", None)
  495. delegation_effort = route_effort
  496. if not (delegation_effort or delegation_effort is False):
  497. delegation_effort = (delegation_cfg or {}).get("reasoning_effort")
  498. if delegation_effort or delegation_effort is False:
  499. from hermes_constants import parse_reasoning_effort
  500. parsed = parse_reasoning_effort(delegation_effort)
  501. if parsed is None:
  502. logger.warning("Unknown delegation.reasoning_effort '%s', inheriting parent level", delegation_effort)
  503. else:
  504. child_reasoning = parsed
  505. return child_reasoning
  506. def _resolve_child_runtime(
  507. parent_agent, delegation_cfg: dict, parent_api_key: Any, *, model: Optional[str], override_provider: Optional[str],
  508. override_base_url: Optional[str], override_api_key: Optional[str], override_api_mode: Optional[str],
  509. override_acp_command: Optional[str], override_acp_args: Optional[list[str]],
  510. routing_cfg: Optional[dict[str, Any]] = None, override_reasoning_effort: Any = None,
  511. ) -> dict[str, Any]:
  512. """Child credentials, transport and routing (config override > parent inherit) as ``AIAgent`` kwargs. Rules that
  513. are easy to break: api_mode is re-derived (not inherited) when the child's provider differs from the parent's
  514. or is Nous Portal (dual-wire); a pinned ``delegation.command`` must exist on PATH or the spawn fails loudly;
  515. ``override_provider`` clears the parent's ACP transport, fallback chain and OpenRouter routing filters so the
  516. pinned provider is actually honoured."""
  517. effective_model = model or parent_agent.model
  518. # provider/base_url are one bundle: all from the override, or all from the parent. Per-field fallback built
  519. # children like an override provider pointed at the PARENT's endpoint (e.g. one provider's credentials on the
  520. # parent's Codex URL), which 404s on every request and can't be rescued by the fallback chain, whose dedup
  521. # matches provider+model and so skips the entry as a self-loop. _inherit_parent_endpoint recovers the
  522. # parent's live endpoint (with its key), which is meaningless for a different provider.
  523. if override_provider:
  524. effective_provider = override_provider
  525. effective_base_url = override_base_url
  526. elif override_base_url:
  527. effective_provider = getattr(parent_agent, "provider", None)
  528. effective_base_url = override_base_url
  529. else:
  530. effective_provider = getattr(parent_agent, "provider", None)
  531. effective_base_url, parent_api_key = _inherit_parent_endpoint(parent_agent, parent_agent.base_url, parent_api_key)
  532. # api_mode: each provider has its own wire, so a different provider re-derives (None) instead of inheriting (404s
  533. # otherwise). Nous Portal is dual-wire within one provider (anthropic/* → Messages, else chat_completions), so
  534. # same-provider inheritance would pin the child on the wrong wire — re-derive.
  535. # Bug #20558 / PR #20563: api_mode must NOT be inherited when the child uses a different provider than
  536. # the parent — each provider has its own API surface (e.g. MiniMax uses anthropic_messages, DeepSeek
  537. # uses chat_completions). Inheriting the parent's mode causes 404 errors when the child routes to the
  538. # wrong endpoint. Derive the mode from the target provider when it differs. Same-provider inheritance
  539. # would pin a child Hermes/Qwen subagent onto the parent's Claude Messages wire (or the reverse).
  540. # agent_init honors an explicit api_mode above its nous branch, so re-derive here before construction.
  541. _parent_provider = getattr(parent_agent, "provider", None) or ""
  542. if override_api_mode is not None:
  543. effective_api_mode = override_api_mode
  544. elif (effective_provider or "").strip().lower() in _NOUS_PROVIDERS:
  545. from hermes_cli.providers import nous_api_mode
  546. effective_api_mode = nous_api_mode(effective_model)
  547. elif effective_provider != _parent_provider:
  548. effective_api_mode = None # force re-derivation from provider's defaults
  549. else:
  550. effective_api_mode = getattr(parent_agent, "api_mode", None)
  551. # A pinned transport that cannot run must fail the spawn loudly, never fall
  552. # back silently (delegate_task pre-validates; this covers direct callers).
  553. _require_pinned_command(
  554. override_acp_command, f"Pinned delegation command '{override_acp_command}' was not "
  555. f"found on PATH. Install it or remove delegation.command from config.yaml.",
  556. )
  557. effective_acp_command = override_acp_command or getattr(parent_agent, "acp_command", None)
  558. effective_acp_args = list(
  559. override_acp_args if override_acp_args is not None else (getattr(parent_agent, "acp_args", []) or [])
  560. )
  561. # A pinned provider must use direct API calls; inheriting the parent's ACP transport would build the
  562. # ACP client and bypass the override credentials entirely (issue #16816).
  563. if override_provider and not override_acp_command:
  564. effective_acp_command, effective_acp_args = None, []
  565. # A pinned command arrives only with the runtime of the provider that resolved it, so the selected
  566. # provider (and its api_mode) is kept as is.
  567. # A named provider identity is endpoint-scoped. Preserve it only when the
  568. # child inherits the exact parent route; an override owns its final identity.
  569. effective_requested_provider = effective_provider
  570. if not override_provider and not override_base_url and not override_acp_command:
  571. effective_requested_provider = (
  572. getattr(parent_agent, "requested_provider", None) or effective_provider
  573. )
  574. # Reasoning: the task route's effort (delegation provider) > delegation.reasoning_effort > parent.
  575. child_reasoning = _child_reasoning(parent_agent, delegation_cfg, override_reasoning_effort)
  576. kwargs: dict[str, Any] = {
  577. "base_url": effective_base_url, "api_key": override_api_key or parent_api_key, "model": effective_model,
  578. "provider": effective_provider, "requested_provider": effective_requested_provider,
  579. "capabilities": _inherit_parent_capabilities(parent_agent, override_provider, override_base_url),
  580. "api_mode": effective_api_mode, "acp_command": effective_acp_command, "acp_args": effective_acp_args,
  581. "reasoning_config": child_reasoning,
  582. # Resolve routing and recovery policy from the same configuration owner. A pinned provider, endpoint, or
  583. # model never borrows the parent's chain; an explicitly declared child chain still remains available.
  584. "fallback_model": _resolve_child_fallback_chain(
  585. parent_agent, delegation_cfg if routing_cfg is None else routing_cfg,
  586. pinned=bool(override_provider or override_base_url or model)),
  587. "openrouter_min_coding_score": getattr(parent_agent, "openrouter_min_coding_score", None),
  588. # Routing filters reset to their defaults under a pinned provider (see _ROUTING_FILTER_DEFAULTS).
  589. **{a: d if override_provider else getattr(parent_agent, a, d) for a, d in _ROUTING_FILTER_DEFAULTS},
  590. }
  591. if not override_provider:
  592. kwargs["provider_data_collection"] = kwargs["provider_data_collection"] or ""
  593. child_max_tokens = getattr(parent_agent, "max_tokens", None)
  594. if isinstance(child_max_tokens, int):
  595. kwargs["max_tokens"] = child_max_tokens
  596. return kwargs