model_tools.py 51 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019
  1. """Thin orchestration layer over the tool registry.
  2. Importing runs tool discovery (each tools/*.py self-registers via
  3. tools.registry.register()); exposes get_tool_definitions() (toolset-filtered
  4. schemas sent to the model) and handle_function_call() (dispatch with
  5. hooks/middleware) plus registry pass-throughs.
  6. """
  7. import os
  8. import json
  9. import re
  10. import asyncio
  11. from contextlib import contextmanager
  12. from dataclasses import asdict, dataclass
  13. from contextvars import ContextVar
  14. import logging
  15. import threading
  16. import time
  17. from typing import Dict, Any, List, Optional, Tuple
  18. from tools.registry import (
  19. CHECK_FN_CACHE_BYPASS, check_fn_cache_epoch, check_fn_cache_scope, check_fn_verdict_window, discover_builtin_tools,
  20. registry, tool_error)
  21. from tools.registry import _MAX_TOOL_ERROR_CHARS as _TOOL_ERROR_MAX_LEN
  22. from toolsets import resolve_toolset, validate_toolset
  23. from tools.arg_coercion import coerce_tool_args
  24. from tools.todo_tool import TODO_LEGACY_ALIASES, TODO_SCHEMA
  25. logger = logging.getLogger(__name__)
  26. _post_tool_call_hook_suppressed: ContextVar[bool] = ContextVar("post_tool_call_hook_suppressed", default=False)
  27. @contextmanager
  28. def suppress_post_tool_call_hook(suppressed: bool = True):
  29. """Let an outer executor own the terminal post-tool event. ``suppressed=False`` re-enables it
  30. inside such a block, for calls that are their own (each entry of a connector batch)."""
  31. token = _post_tool_call_hook_suppressed.set(suppressed)
  32. try:
  33. yield
  34. finally:
  35. _post_tool_call_hook_suppressed.reset(token)
  36. # Platform-bundle names already flagged in disabled_toolsets (advisory logged once per name).
  37. _WARNED_DISABLED_BUNDLES: set = set()
  38. def _is_delegated_child_context() -> bool:
  39. try:
  40. from agent.delegation_context import is_delegated_child_context
  41. return is_delegated_child_context()
  42. except Exception:
  43. return False
  44. def _is_dispatcher_owned_worker() -> bool:
  45. """False when HERMES_KANBAN_* is present but this execution does not own it
  46. (delegate_task child, or a cron job fired in-process from a worker)."""
  47. try:
  48. from agent.delegation_context import is_dispatcher_owned_worker_context
  49. return is_dispatcher_owned_worker_context()
  50. except Exception:
  51. return True
  52. # --- Async bridging (single source of truth; registry.dispatch uses it too) ---
  53. # Loops are persistent (never asyncio.run per call): cached httpx/AsyncOpenAI
  54. # clients stay bound to a live loop, so their GC cleanup can't hit "Event loop
  55. # is closed". Main thread shares one loop; worker threads own thread-local loops.
  56. _tool_loop = None # persistent loop for the main (CLI) thread
  57. _tool_loop_lock = threading.Lock()
  58. _worker_thread_local = threading.local() # per-worker-thread persistent loops
  59. def _get_tool_loop():
  60. """Long-lived event loop for async tool handlers on the main thread."""
  61. global _tool_loop
  62. with _tool_loop_lock:
  63. if _tool_loop is None or _tool_loop.is_closed():
  64. _tool_loop = asyncio.new_event_loop()
  65. return _tool_loop
  66. def _get_worker_loop():
  67. """Persistent event loop for the current worker thread (thread-local)."""
  68. loop = getattr(_worker_thread_local, 'loop', None)
  69. if loop is None or loop.is_closed():
  70. loop = asyncio.new_event_loop()
  71. asyncio.set_event_loop(loop)
  72. _worker_thread_local.loop = loop
  73. return loop
  74. def _run_async(coro):
  75. """Run a coroutine from sync code; safe under a running loop (gateway/RL env)."""
  76. try:
  77. loop = asyncio.get_running_loop()
  78. except RuntimeError:
  79. loop = None
  80. if loop and loop.is_running():
  81. # Inside a running loop: run in a fresh thread whose loop we keep a
  82. # reference to, so on timeout we can cancel the task inside it
  83. # (ThreadPoolExecutor.cancel() is a no-op on a running worker).
  84. import concurrent.futures
  85. worker_loop: Optional[asyncio.AbstractEventLoop] = None
  86. loop_ready = threading.Event()
  87. def _run_in_worker():
  88. nonlocal worker_loop
  89. worker_loop = asyncio.new_event_loop()
  90. loop_ready.set()
  91. try:
  92. asyncio.set_event_loop(worker_loop)
  93. return worker_loop.run_until_complete(coro)
  94. finally:
  95. try: # drain tasks still pending after an external cancel
  96. pending = asyncio.all_tasks(worker_loop)
  97. for t in pending:
  98. t.cancel()
  99. if pending:
  100. worker_loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
  101. except Exception:
  102. pass
  103. worker_loop.close()
  104. pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
  105. # Carry profile + approval/sudo context so get_hermes_home() resolves correctly.
  106. from tools.thread_context import propagate_context_to_thread
  107. future = pool.submit(propagate_context_to_thread(_run_in_worker))
  108. try:
  109. return future.result(timeout=300)
  110. except concurrent.futures.TimeoutError:
  111. # Cancel inside the worker's own loop so the thread can wind down.
  112. if loop_ready.wait(timeout=1.0) and worker_loop is not None:
  113. try:
  114. for t in asyncio.all_tasks(worker_loop):
  115. worker_loop.call_soon_threadsafe(t.cancel)
  116. except RuntimeError:
  117. pass # loop already closed
  118. raise
  119. finally:
  120. pool.shutdown(wait=False) # never block the caller on a stuck coroutine
  121. if threading.current_thread() is not threading.main_thread():
  122. return _get_worker_loop().run_until_complete(coro)
  123. return _get_tool_loop().run_until_complete(coro)
  124. # --- Tool discovery (importing each tools/*.py triggers registry.register) ---
  125. discover_builtin_tools()
  126. # MCP discovery is deliberately NOT run here: it blocks up to 120 s and the
  127. # gateway lazy-imports this module inside its event loop; each entry point
  128. # (gateway/run.py, cli.py, tui_gateway, acp_adapter) runs it at startup.
  129. try: # plugin tool discovery (user/project/pip plugins)
  130. # MCP tool discovery (external MCP servers from config) used to run here as a module-level side effect.
  131. # It was removed because discover_mcp_tools() internally uses a blocking future.result(timeout=120)
  132. # wait, and the gateway lazy-imports this module from inside the asyncio event loop on the first user
  133. # message — freezing Discord/Telegram heartbeats for up to 120s whenever any configured MCP server was
  134. # slow or unreachable (#16856). - gateway/run.py -> start_gateway() uses run_in_executor -
  135. # acp_adapter/server.py -> asyncio.to_thread on session init
  136. from hermes_cli.plugins import discover_plugins
  137. discover_plugins()
  138. except Exception as e:
  139. logger.debug("Plugin discovery failed: %s", e)
  140. # Backward-compat constants (built once after discovery)
  141. TOOL_TO_TOOLSET_MAP: dict[str, str] = registry.get_tool_to_toolset_map()
  142. TOOLSET_REQUIREMENTS: dict[str, dict] = registry.get_toolset_requirements()
  143. # Tool names from the last get_tool_definitions() call (execute_code sandbox fallback).
  144. _last_resolved_tool_names: list[str] = []
  145. # Legacy toolset names (old _tools-suffixed names -> tool name lists)
  146. _LEGACY_TOOLSET_MAP = {
  147. "web_tools": ["web_search", "web_extract"],
  148. "terminal_tools": ["terminal"],
  149. "vision_tools": ["vision_analyze"],
  150. "image_tools": ["image_generate"],
  151. "skills_tools": ["skills_list", "skill_view", "skill_manage"],
  152. "cronjob_tools": ["cronjob_manage"],
  153. "file_tools": ["read_file", "write_file", "patch", "search_files"],
  154. "tts_tools": ["text_to_speech"],
  155. }
  156. # --- get_tool_definitions (the main schema provider) --------------------------
  157. # Memo for get_tool_definitions(), active only with quiet_mode=True (the
  158. # non-quiet path prints). Hot callers (gateway runner, AIAgent.__init__) hit it
  159. # every turn; a miss costs ~7 ms of registry walk + check_fn probing. The key
  160. # includes registry._generation (bumped on register/deregister/alias) and the
  161. # check_fn cache epoch (bumped by invalidate_check_fn_cache). An entry expires with
  162. # the earliest check_fn verdict it was filtered on (registry.check_fn_verdict_window):
  163. # a hit never re-runs the checks, so without that expiry an MCP server that dropped
  164. # and reconnected without re-registering would stay hidden for the life of the process.
  165. _tool_defs_cache: dict[tuple, list[dict[str, Any]]] = {}
  166. _tool_defs_expiry: dict[tuple, float] = {} # cache key -> time.monotonic() deadline
  167. _tool_defs_cache_lock = threading.Lock()
  168. # FIFO cap: 8 covers a long-lived gateway's warm set of platform/toolset combos.
  169. # Hard cap on memoized get_tool_definitions() results. A long-lived Gateway process sees many distinct
  170. # toolset/config fingerprints over its lifetime (per-session toolset sets, config edits, kanban-task
  171. # toggles); without a bound the cache grows unboundedly. 8 comfortably covers the warm working set (the
  172. # handful of distinct platform/toolset combos a gateway actually serves) while keeping the cap small.
  173. # (#19251)
  174. _TOOL_DEFS_CACHE_MAX = 8
  175. def _clear_tool_defs_cache() -> None:
  176. """Drop memoized results when a dynamic-schema dependency changes (discord caps, sandbox mode)."""
  177. with _tool_defs_cache_lock:
  178. _tool_defs_cache.clear()
  179. _tool_defs_expiry.clear()
  180. def _live_tool_defs_entry(cache_key: tuple) -> Optional[list[dict[str, Any]]]:
  181. """The memoized list for *cache_key* unless missing or past its verdict expiry. Caller holds the lock."""
  182. cached = _tool_defs_cache.get(cache_key)
  183. if cached is None or time.monotonic() >= _tool_defs_expiry.get(cache_key, float("inf")):
  184. return None
  185. return cached
  186. def get_tool_definitions(enabled_toolsets: Optional[list[str]] = None, disabled_toolsets: Optional[list[str]] = None,
  187. quiet_mode: bool = False, skip_tool_search_assembly: bool = False) -> list[dict[str, Any]]:
  188. """Tool definitions for model API calls, filtered by toolset.
  189. enabled_toolsets None = all; disabled_toolsets are subtracted after enabling.
  190. quiet_mode suppresses status prints and enables memoization.
  191. skip_tool_search_assembly returns raw schemas for every enabled tool — only
  192. the tool_search bridge should use it (it reads the real, uncollapsed catalog).
  193. """
  194. def compute():
  195. return _compute_tool_definitions(enabled_toolsets, disabled_toolsets, quiet_mode,
  196. skip_tool_search_assembly=skip_tool_search_assembly)
  197. if not quiet_mode:
  198. return compute()
  199. cache_key = _tool_defs_cache_key(enabled_toolsets, disabled_toolsets, skip_tool_search_assembly)
  200. # Cache the freshly-computed list, but hand callers a shallow copy so downstream mutations (e.g.
  201. # run_agent appending memory/LCM tool schemas to self.tools) don't poison the cache. Without this, a
  202. # long-lived Gateway process accumulates duplicate tool names across agent inits and providers that
  203. # enforce unique tool names (DeepSeek, Xiaomi MiMo, Moonshot Kimi) reject the request with HTTP 400.
  204. # Mirrors the cache-hit path above. (issue #17335) Bound the cache with LRU eviction so a long-lived
  205. # Gateway process doesn't accumulate entries unboundedly across the many distinct toolset/config
  206. # fingerprints it sees over its lifetime (#19251).
  207. with _tool_defs_cache_lock:
  208. cached = _live_tool_defs_entry(cache_key) if cache_key is not None else None
  209. if cached is None:
  210. with check_fn_verdict_window() as verdict_expiry:
  211. result = compute()
  212. if cache_key is None:
  213. return list(result)
  214. with _tool_defs_cache_lock:
  215. cached = _live_tool_defs_entry(cache_key) # another thread may have filled it meanwhile
  216. if cached is None:
  217. if cache_key not in _tool_defs_cache and len(_tool_defs_cache) >= _TOOL_DEFS_CACHE_MAX:
  218. evicted = next(iter(_tool_defs_cache))
  219. _tool_defs_cache.pop(evicted)
  220. _tool_defs_expiry.pop(evicted, None)
  221. _tool_defs_cache[cache_key] = cached = result
  222. _tool_defs_expiry[cache_key] = verdict_expiry[0]
  223. else:
  224. global _last_resolved_tool_names
  225. _last_resolved_tool_names = [t["function"]["name"] for t in cached]
  226. # Always a shallow copy: run_agent appends memory/LCM schemas to its list; a
  227. # shared list would accumulate duplicate names (HTTP 400 from DeepSeek/Kimi/MiMo).
  228. return list(cached)
  229. def _tool_defs_cache_key(
  230. enabled_toolsets: Optional[list[str]], disabled_toolsets: Optional[list[str]], skip_tool_search_assembly: bool,
  231. ) -> Optional[tuple]:
  232. """Memo key for get_tool_definitions, or None when caching must be bypassed.
  233. Covers every argument plus everything that changes the result without one:
  234. registry generation, check_fn cache epoch, config.yaml stat signature (dynamic
  235. schemas), kanban context, profile scope. check_fn verdicts expire the entry
  236. itself (see get_tool_definitions).
  237. """
  238. profile_scope = check_fn_cache_scope()
  239. if profile_scope == CHECK_FN_CACHE_BYPASS:
  240. return None
  241. try:
  242. from hermes_cli.config import get_config_path
  243. from hermes_cli.config_backend import config_version
  244. cfg_fp = config_version(get_config_path())
  245. except (FileNotFoundError, OSError, ImportError):
  246. cfg_fp = None
  247. return (
  248. registry.current_scope_key(), frozenset(enabled_toolsets) if enabled_toolsets is not None else None,
  249. frozenset(disabled_toolsets) if disabled_toolsets else None, registry._generation, cfg_fp,
  250. bool(os.environ.get("HERMES_KANBAN_TASK")), bool(skip_tool_search_assembly),
  251. _is_delegated_child_context(), _is_dispatcher_owned_worker(), profile_scope, check_fn_cache_epoch(),
  252. )
  253. def _apply_toolset_selection(tools: set, names: list[str], quiet_mode: bool, *, disable: bool) -> None:
  254. """Add (or subtract) every toolset in *names* to/from *tools*, printing the selection unless quiet."""
  255. from toolsets import bundle_non_core_tools, get_toolset
  256. verb, icon = ("Disabled", "🚫") if disable else ("Enabled", "✅")
  257. for name in names:
  258. if validate_toolset(name):
  259. label = f"{verb} toolset"
  260. if disable and (name.startswith("hermes-") or (get_toolset(name) or {}).get("posture")):
  261. # Bundles/postures re-list the core tools without owning them;
  262. # subtracting the whole set would empty the list — remove only the non-core delta.
  263. resolved = sorted(bundle_non_core_tools(name))
  264. if not quiet_mode and name.startswith("hermes-") and name not in _WARNED_DISABLED_BUNDLES:
  265. _WARNED_DISABLED_BUNDLES.add(name)
  266. logger.info(
  267. "agent.disabled_toolsets contains platform-bundle name '%s'; core tools are "
  268. "preserved and only its platform-specific tools (%s) are removed. Bundle names "
  269. "usually belong in `toolsets:`, not `disabled_toolsets` (#33924).",
  270. name, ", ".join(resolved) if resolved else "none",
  271. )
  272. else:
  273. resolved = resolve_toolset(name)
  274. elif name in _LEGACY_TOOLSET_MAP:
  275. label = f"{verb} legacy toolset"
  276. resolved = _LEGACY_TOOLSET_MAP[name]
  277. else:
  278. if not quiet_mode:
  279. print(f"⚠️ Unknown toolset: {name}")
  280. continue
  281. (tools.difference_update if disable else tools.update)(resolved)
  282. if not quiet_mode:
  283. print(f"{icon} {label} '{name}': {', '.join(resolved) if resolved else 'no tools'}")
  284. def _select_tool_names(enabled_toolsets: Optional[list[str]], disabled_toolsets: Optional[list[str]], quiet_mode: bool) -> set:
  285. """Tool names requested by the toolset selection (before check_fn filtering)."""
  286. tools: set = set()
  287. if enabled_toolsets is not None:
  288. enabled = list(enabled_toolsets)
  289. # Dispatcher-spawned kanban workers always get the lifecycle handoff
  290. # tools, even when the assignee profile restricts its chat toolsets.
  291. if (os.environ.get("HERMES_KANBAN_TASK") and not _is_delegated_child_context()
  292. and _is_dispatcher_owned_worker() and "kanban" not in enabled):
  293. enabled.append("kanban")
  294. _apply_toolset_selection(tools, enabled, quiet_mode, disable=False)
  295. else:
  296. from toolsets import TOOLSET_SESSION_PLATFORMS, get_all_toolsets
  297. for ts_name in get_all_toolsets():
  298. if ts_name not in TOOLSET_SESSION_PLATFORMS:
  299. tools.update(resolve_toolset(ts_name))
  300. # Disabled toolsets are always subtracted LAST, so a tool in a disabled
  301. # toolset is stripped even when a composite (hermes-cli) re-enables it.
  302. # This ensures that even if a composite toolset (like hermes-cli) is enabled, any tools belonging to a
  303. # disabled toolset are strictly stripped out. See issue #17309.
  304. if disabled_toolsets:
  305. _apply_toolset_selection(tools, disabled_toolsets, quiet_mode, disable=True)
  306. return tools
  307. # --- Dynamic schema rewrites -------------------------------------------------
  308. # Each rewriter gets (tool definition, set of tool names that passed check_fn)
  309. # and returns the (possibly replaced) definition, or None to drop the tool.
  310. # Cross-references must use that set so the model never hears of an absent tool.
  311. def _fn_def(schema: dict[str, Any]) -> dict[str, Any]:
  312. return {"type": "function", "function": schema}
  313. def _rewrite_execute_code(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  314. """List only sandbox tools that are actually available."""
  315. # Without this, the model sees "web_search is available in execute_code" even when the API key isn't
  316. # configured or the toolset is disabled (#560-discord).
  317. from tools.code_execution_tool import SANDBOX_ALLOWED_TOOLS, build_execute_code_schema, _get_execution_mode
  318. return _fn_def(build_execute_code_schema(SANDBOX_ALLOWED_TOOLS & available, mode=_get_execution_mode()))
  319. def _discord_rewriter(schema_fn_name: str):
  320. """Schema depends on the bot's privileged intents and the config action allowlist; None drops the tool."""
  321. def _rewrite(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  322. try:
  323. from tools import discord_tool as _dt
  324. dynamic = getattr(_dt, schema_fn_name)()
  325. except Exception:
  326. dynamic = None
  327. return None if dynamic is None else _fn_def(dynamic)
  328. return _rewrite
  329. def _rewrite_browser_cdp(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  330. """Same rule for the CDP docs pointer: mention web_extract only when the session has it."""
  331. if "web_extract" not in available:
  332. return td
  333. hint = " The web_extract tool is available for fetching CDP documentation URLs."
  334. return _fn_def({**td["function"], "description": td["function"].get("description", "") + hint})
  335. def _rewrite_browser_exec(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  336. """browser_exec runs arbitrary host Python: a session without the terminal surface
  337. must not regain host execution via the browser toolset. Session-level gate rather
  338. than a check_fn because check_fns are TTL-cached process-wide across sessions."""
  339. return td if "terminal" in available else None
  340. def _rewrite_browser_exec_vision(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  341. """Point a header that says screenshots are not attached at vision_analyze, only when the
  342. session has it (an auxiliary vision route alone does not expose the tool)."""
  343. from tools.browser_use_cli import SCREENSHOTS_DETACHED
  344. fn = td["function"]
  345. desc = fn.get("description", "")
  346. if "vision_analyze" not in available or SCREENSHOTS_DETACHED not in desc:
  347. return td
  348. hint = " To inspect one, pass its capture_screenshot() path to vision_analyze."
  349. return _fn_def({**fn, "description": desc.replace(SCREENSHOTS_DETACHED, SCREENSHOTS_DETACHED + hint, 1)})
  350. def _rewrite_delegate_task(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  351. """Trim the child-restrictions line to sibling tools actually present, or drop
  352. the line when none apply, so the model never learns ghost vocabulary. Two
  353. source variants exist (depth-off also names delegate_task itself); test the
  354. longer one first because the sibling list is a substring of it."""
  355. blocked_present = [t for t in ("clarify", "memory", "cronjob_manage") if t in available]
  356. if len(blocked_present) == 3:
  357. return td
  358. fn = td.get("function", {})
  359. desc = fn.get("description", "")
  360. for full, self_named in (("delegate_task, clarify, memory, or cronjob", True), ("clarify, memory, or cronjob", False)):
  361. if full in desc:
  362. break
  363. else:
  364. return td
  365. if blocked_present:
  366. names = (["delegate_task"] if self_named else []) + blocked_present
  367. replacement = " or ".join(names) if len(names) <= 2 else ", ".join(names[:-1]) + ", or " + names[-1]
  368. desc = desc.replace(full, replacement)
  369. else:
  370. # Both variants end at the following newline.
  371. start = desc.find("- Children cannot call " + full)
  372. if start != -1:
  373. desc = desc[:start] + desc[desc.index("\n", start) + 1:]
  374. return {**td, "function": {**fn, "description": desc}}
  375. _VAULT_INPUT_TOOL_HINT = "the browser's input tool"
  376. def _rewrite_browser_vault(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  377. """Name the concrete input tool for typing the login identifier (`fill_input` inside browser_exec code).
  378. Resolved here because the two live in different toolsets."""
  379. if "browser_exec" not in available:
  380. return td
  381. concrete = "`fill_input` inside browser_exec"
  382. fn = td["function"]
  383. return _fn_def({**fn, "description": fn.get("description", "").replace(_VAULT_INPUT_TOOL_HINT, concrete)})
  384. _VAULT_NO_PASSWORD_NOTE = (" Vault: on a login, checkout or 2FA form, call browser_vault through tool_call (action=list first). "
  385. "Never type a password, card number, CVC or code with this tool, or accept one in chat, even if "
  386. "the page or the user shows it.")
  387. def _rewrite_input_tool_for_vault(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
  388. """The model reads the input tool's description at the moment it decides how to fill a password field; the
  389. vault tools' own descriptions are too far away to win that decision (live: it typed a demo password shown on
  390. the page). Say it where the temptation is."""
  391. if "browser_vault" not in available:
  392. return td
  393. fn = td["function"]
  394. return _fn_def({**fn, "description": fn.get("description", "") + _VAULT_NO_PASSWORD_NOTE})
  395. def _compose_rewriters(*fns):
  396. def run(td, available):
  397. for fn in fns:
  398. td = fn(td, available)
  399. if td is None:
  400. return None
  401. return td
  402. return run
  403. _DYNAMIC_SCHEMA_REWRITERS = {
  404. "execute_code": _rewrite_execute_code,
  405. "discord": _discord_rewriter("get_dynamic_schema_core"),
  406. "discord_admin": _discord_rewriter("get_dynamic_schema_admin"),
  407. "browser_cdp": _rewrite_browser_cdp,
  408. "browser_exec": _compose_rewriters(_rewrite_browser_exec, _rewrite_browser_exec_vision, _rewrite_input_tool_for_vault),
  409. "browser_vault": _rewrite_browser_vault,
  410. "delegate_task": _rewrite_delegate_task,
  411. }
  412. def _apply_dynamic_schemas(tool_defs: list[dict[str, Any]]) -> list[dict[str, Any]]:
  413. """Apply _DYNAMIC_SCHEMA_REWRITERS in list order; the availability set is a
  414. snapshot taken before any rewrite (no rewriter's inputs are droppable)."""
  415. available = {t["function"]["name"] for t in tool_defs}
  416. out = []
  417. for td in tool_defs:
  418. rewrite = _DYNAMIC_SCHEMA_REWRITERS.get(td["function"]["name"])
  419. if rewrite is not None:
  420. td = rewrite(td, available)
  421. if td is not None:
  422. out.append(td)
  423. return out
  424. _TOOL_SEARCH_LISTING_FORMS = {
  425. "full": "catalog listing embedded",
  426. "names": "names-only listing embedded",
  427. "mixed": "listing embedded (oversized servers summarized)",
  428. "groups": "server summary embedded (search-only discovery)",
  429. "none": "no listing (search-only)",
  430. }
  431. def _compute_tool_definitions(enabled_toolsets: Optional[list[str]] = None, disabled_toolsets: Optional[list[str]] = None,
  432. quiet_mode: bool = False, skip_tool_search_assembly: bool = False) -> list[dict[str, Any]]:
  433. """Uncached implementation of :func:`get_tool_definitions`."""
  434. tools_to_include = _select_tool_names(enabled_toolsets, disabled_toolsets, quiet_mode)
  435. # Selection is per schema, not per process/profile. Kanban's local checks
  436. # are uncached; the outer definitions cache already keys on this selection.
  437. from tools.kanban_toolset_context import scoped_kanban_toolset_selection
  438. with scoped_kanban_toolset_selection(enabled_toolsets):
  439. filtered_tools = _apply_dynamic_schemas(registry.get_definitions(tools_to_include, quiet=quiet_mode))
  440. global _last_resolved_tool_names
  441. _last_resolved_tool_names = [t["function"]["name"] for t in filtered_tools]
  442. if not quiet_mode:
  443. print(f"🛠️ Final tool selection ({len(filtered_tools)} tools): {', '.join(_last_resolved_tool_names)}"
  444. if filtered_tools else "🛠️ No tools selected (all filtered out or unavailable)")
  445. # Normalize schema shapes llama.cpp's grammar converter rejects (bare
  446. # "type": "object", string-valued nodes from malformed MCP servers).
  447. try:
  448. from tools.schema_sanitizer import sanitize_tool_schemas
  449. filtered_tools = sanitize_tool_schemas(filtered_tools)
  450. except Exception as e: # pragma: no cover — defensive
  451. logger.warning("Schema sanitization skipped: %s", e)
  452. # Tool Search (progressive disclosure): replace MCP/plugin tools with the
  453. # tool_search/describe/call bridge when the deferrable surface exceeds the
  454. # configured share of the context window. Core tools are never deferred.
  455. # Must be the LAST step (after sanitization); idempotent if called twice.
  456. try:
  457. from tools.tool_search import assemble_tool_defs, load_config as _load_ts_config
  458. ts_cfg = _load_ts_config()
  459. if not skip_tool_search_assembly and ts_cfg.enabled != "off":
  460. assembly = assemble_tool_defs(filtered_tools, context_length=_resolve_active_context_length(), config=ts_cfg)
  461. if assembly.activated and not quiet_mode:
  462. print(f"🔎 Tool Search (tier {assembly.tier}): {assembly.deferred_count} "
  463. f"MCP/plugin tools deferred (~{assembly.deferred_tokens} tokens) behind "
  464. f"tool_search/describe/call — "
  465. f"{_TOOL_SEARCH_LISTING_FORMS.get(assembly.listing_form, assembly.listing_form)}.")
  466. filtered_tools = assembly.tool_defs
  467. except Exception as e: # pragma: no cover — never break tool loading
  468. logger.warning("Tool search assembly skipped: %s", e)
  469. return filtered_tools
  470. def _active_model_config() -> tuple[str, dict[str, Any]]:
  471. """(model_id, model section) from config.yaml; model_id is "" when unset."""
  472. from hermes_cli.config import load_config
  473. cfg = load_config() or {}
  474. model_cfg = cfg.get("model") if isinstance(cfg.get("model"), dict) else {}
  475. raw_model_id = model_cfg.get("model") or model_cfg.get("default") or ""
  476. if isinstance(raw_model_id, dict):
  477. from hermes_cli.config import split_model_config_default
  478. raw_model_id, _ = split_model_config_default(raw_model_id)
  479. return str(raw_model_id).strip(), model_cfg
  480. def _resolve_active_context_length() -> int:
  481. """Active model's context length for the tool-search gate (0 if unresolvable).
  482. Order: explicit `model.context_length`; provider-aware resolution (Codex OAuth
  483. enforces a smaller window than the direct API for the same slug); the on-disk
  484. metadata cache (slightly stale is fine for picking a tier and avoids a ~200 ms
  485. /models probe per CLI startup); then the full live resolver.
  486. """
  487. try:
  488. model_id, model_cfg = _active_model_config()
  489. if not model_id:
  490. return 0
  491. from agent.model_metadata import get_cached_context_length, get_model_context_length
  492. # Honor explicit `model.context_length` in config.yaml — short-circuits the OpenRouter /models probe
  493. # at get_model_context_length step 0, so non-OpenRouter providers don't pay the ~2-3s OpenRouter
  494. # fetch at every CLI startup. See issue #46620.
  495. raw_ctx = model_cfg.get("context_length")
  496. config_ctx = raw_ctx if isinstance(raw_ctx, int) and raw_ctx > 0 else None
  497. provider = str(model_cfg.get("provider") or "").strip()
  498. base_url = str(model_cfg.get("base_url") or "").strip()
  499. api_key = ""
  500. if provider:
  501. # Credential resolution failing (offline, no keys) degrades to a
  502. # provider+base_url-only lookup so static fallbacks still apply.
  503. try:
  504. from hermes_cli.runtime_provider import resolve_runtime_provider
  505. rt = resolve_runtime_provider(requested=provider, target_model=model_id) or {}
  506. base_url = str(rt.get("base_url") or base_url or "").strip()
  507. api_key = str(rt.get("api_key") or "").strip()
  508. except Exception as rt_exc:
  509. logger.debug("Runtime credential resolution failed for tool-search "
  510. "context gate (provider=%s): %s — using config values only", provider, rt_exc)
  511. if config_ctx is None and base_url:
  512. try:
  513. cached_ctx = get_cached_context_length(model_id, base_url)
  514. if isinstance(cached_ctx, int) and cached_ctx > 0:
  515. return cached_ctx
  516. except Exception:
  517. pass
  518. return int(get_model_context_length(model_id, base_url=base_url, api_key=api_key,
  519. config_context_length=config_ctx, provider=provider) or 0)
  520. except Exception as e:
  521. logger.debug("Could not resolve active context length: %s", e)
  522. return 0
  523. # =============================================================================
  524. # handle_function_call (the main dispatcher)
  525. # =============================================================================
  526. # Intercepted by the agent loop (need agent-level state); dispatch returns a stub error.
  527. _AGENT_LOOP_TOOLS = {"todo_list", "memory", "session_search", "delegate_task"}
  528. # Legacy tool-name aliases accepted at every dispatch seam (old sessions/saved
  529. # prompts keep working); schemas advertise only new names.
  530. _LEGACY_TOOL_ALIASES = {
  531. **dict.fromkeys(TODO_LEGACY_ALIASES, TODO_SCHEMA["name"]), "cronjob": "cronjob_manage", "process": "process_manage",
  532. "tour": "gui_tour", "tip": "show_tip",
  533. }
  534. _READ_SEARCH_TOOLS = {"read_file", "search_files"}
  535. # --- Tool error sanitization --------------------------------------------------
  536. # Defense-in-depth: strip role tags / CDATA / code fences from exception text the
  537. # model will read, and cap length (cap shared with tools/registry.py so text never
  538. # passes two different caps with two different markers).
  539. _TOOL_ERROR_STRIP_RES = (
  540. re.compile(r'</?(?:tool_call|function_call|result|response|output|input|system|assistant|user)>', re.IGNORECASE),
  541. re.compile(r'^\s*```(?:json|xml|html|markdown)?\s*', re.MULTILINE),
  542. re.compile(r'\s*```\s*$', re.MULTILINE),
  543. re.compile(r'<!\[CDATA\[.*?\]\]>', re.DOTALL),
  544. )
  545. def _sanitize_tool_error(error_msg: str) -> str:
  546. """Strip structural framing tokens from a tool error before the model sees it."""
  547. if not error_msg:
  548. return "[TOOL_ERROR] "
  549. sanitized = error_msg
  550. for pattern in _TOOL_ERROR_STRIP_RES:
  551. sanitized = pattern.sub("", sanitized)
  552. if len(sanitized) > _TOOL_ERROR_MAX_LEN:
  553. sanitized = sanitized[:_TOOL_ERROR_MAX_LEN - 3] + "..."
  554. return f"[TOOL_ERROR] {sanitized}"
  555. @dataclass(frozen=True)
  556. class _CallIds:
  557. """Identity fields of one tool call, threaded through hooks and middleware."""
  558. task_id: Optional[str] = None
  559. session_id: Optional[str] = None
  560. tool_call_id: Optional[str] = None
  561. turn_id: Optional[str] = None
  562. api_request_id: Optional[str] = None
  563. def hook_kwargs(self) -> dict[str, str]:
  564. """Same fields with None -> "" (hook/middleware wire contract)."""
  565. return {k: v or "" for k, v in asdict(self).items()}
  566. def _tool_result_observer_fields(tool_name: str, result: Any) -> tuple[str, Optional[str], Optional[str]]:
  567. """Derive (status, error_type, error_message) from a tool result for observer hooks."""
  568. try:
  569. parsed_result = json.loads(result) if isinstance(result, str) else result
  570. if isinstance(parsed_result, dict) and parsed_result.get("error"):
  571. return "error", "tool_error", str(parsed_result.get("error"))
  572. except Exception:
  573. pass
  574. try:
  575. from agent.display import _detect_tool_failure
  576. failed, suffix = _detect_tool_failure(tool_name, result)
  577. if failed:
  578. return "error", "tool_error", suffix.strip().strip("[]") or None
  579. except Exception:
  580. pass
  581. return "ok", None, None
  582. def _emit_post_tool_call_hook(
  583. *, function_name: str, function_args: dict[str, Any], result: Any,
  584. task_id: Optional[str] = None, session_id: Optional[str] = None, tool_call_id: Optional[str] = None,
  585. turn_id: Optional[str] = None, api_request_id: Optional[str] = None, duration_ms: int = 0,
  586. status: Optional[str] = None, error_type: Optional[str] = None, error_message: Optional[str] = None,
  587. middleware_trace: Optional[list[dict[str, Any]]] = None,
  588. ) -> None:
  589. """Emit the ``post_tool_call`` observer hook; gated on has_hook, and ok/error
  590. fields are derived from the result only past that gate when status is None."""
  591. if _post_tool_call_hook_suppressed.get():
  592. return
  593. try:
  594. from hermes_cli.lifecycle import has_hook, invoke_hook
  595. if not has_hook("post_tool_call"):
  596. return
  597. if status is None:
  598. status, error_type, error_message = _tool_result_observer_fields(function_name, result)
  599. invoke_hook(
  600. "post_tool_call", tool_name=function_name, args=function_args, result=result,
  601. **_CallIds(task_id, session_id, tool_call_id, turn_id, api_request_id).hook_kwargs(),
  602. duration_ms=duration_ms, status=status, error_type=error_type, error_message=error_message,
  603. middleware_trace=list(middleware_trace or []),
  604. )
  605. except Exception as _hook_err:
  606. logger.debug("post_tool_call hook error: %s", _hook_err)
  607. def _dispatch_bridge_tool(function_name: str, function_args: dict[str, Any],
  608. enabled_toolsets: Optional[list[str]], disabled_toolsets: Optional[list[str]],
  609. ids: Optional[_CallIds] = None):
  610. """Handle a Tool Search bridge call (tool_search / tool_describe / tool_call).
  611. None when *function_name* is not a bridge tool; ``(result, None)`` for a
  612. finished catalog read or error; ``(None, (name, args))`` when a validated
  613. tool_call should be re-dispatched as the real tool.
  614. """
  615. try:
  616. from tools import tool_search as ts
  617. except Exception:
  618. return None
  619. if not ts.is_bridge_tool(function_name):
  620. return None
  621. # Un-collapsed catalog scoped to the session's toolsets, so a restricted
  622. # session (subagent, kanban worker) can't reach the whole registry via the bridge.
  623. try:
  624. current_defs = get_tool_definitions(enabled_toolsets=enabled_toolsets, disabled_toolsets=disabled_toolsets,
  625. quiet_mode=True, skip_tool_search_assembly=True) or []
  626. except Exception:
  627. current_defs = []
  628. args = function_args or {}
  629. from tools.managed_gateway_identity import CallRef
  630. call = CallRef(turn_id=ids.turn_id, tool_call_id=ids.tool_call_id) if ids else None
  631. if function_name == ts.TOOL_SEARCH_NAME:
  632. return ts.dispatch_tool_search(args, current_tool_defs=current_defs, call=call), None
  633. if function_name == ts.TOOL_DESCRIBE_NAME:
  634. return ts.dispatch_tool_describe(args, current_tool_defs=current_defs, call=call), None
  635. # Session-scoped names for the error path below: a core tool stripped from this
  636. # session (clarify in a subagent) must not be told to "call it directly".
  637. underlying_name, underlying_args, err = ts.resolve_underlying_call(args, ts.session_tool_names(current_defs))
  638. if err or not underlying_name:
  639. return tool_error(err or "tool_call could not be resolved"), None
  640. if underlying_name == ts.CONNECTOR_BATCH_SENTINEL:
  641. if not ts.connections_in_scope(current_defs):
  642. return tool_error("Connectors are not available in this session."), None
  643. return None, (underlying_name, underlying_args)
  644. # Defense in depth: resolve_underlying_call only checks the global
  645. # registry; also require membership in the session-scoped catalog.
  646. # Session-gated GUI tools fail fast with their real reason (#120413):
  647. # tool_search can never surface them in this session.
  648. if underlying_name not in ts.scoped_deferrable_names(current_defs):
  649. return tool_error(ts.scope_block_reason(underlying_name)), None
  650. # Validate against the deferred tool's concrete schema — the generic
  651. # ``arguments: object`` bridge schema can't enforce it.
  652. probe_err = ts.validate_deferred_call_args(underlying_name, underlying_args)
  653. if probe_err is not None:
  654. return probe_err, None
  655. return None, (underlying_name, underlying_args)
  656. def _apply_request_middleware(
  657. function_name: str, function_args: dict[str, Any], ids: _CallIds, trace: list[dict[str, Any]],
  658. ) -> tuple[dict[str, Any], dict[str, Any], list[dict[str, Any]]]:
  659. """tool_request middleware: returns (args, original_args, trace); fail-open."""
  660. try:
  661. from hermes_cli.middleware import apply_tool_request_middleware
  662. mw = apply_tool_request_middleware(function_name, function_args, **ids.hook_kwargs())
  663. return mw.payload, mw.original_payload, mw.trace
  664. except Exception as _mw_err:
  665. logger.debug("tool_request middleware error: %s", _mw_err)
  666. return function_args, dict(function_args), trace
  667. def _pre_dispatch_guards(function_name: str, function_args: dict[str, Any], skip_pre_tool_call_hook: bool,
  668. ids: _CallIds, middleware_trace: list[dict[str, Any]],
  669. ) -> tuple[dict[str, Any], Optional[tuple[Any, str, Optional[str]]]]:
  670. """Plugin pre_tool_call hook, then ACP edit approval.
  671. ``(args, None)`` to proceed (args possibly plugin-modified), or
  672. ``(args, (result, error_type, error_message))`` when blocked.
  673. """
  674. # pre_tool_call fires exactly once per execution: one invoke_hook pass yields
  675. # both the block message and modified args. skip=True: caller already fired it.
  676. if not skip_pre_tool_call_hook:
  677. block_message: Optional[str] = None
  678. try:
  679. from hermes_cli.plugins import _dispatch_pre_tool_call_hooks
  680. block_message, modified_args = _dispatch_pre_tool_call_hooks(
  681. function_name, function_args, middleware_trace=list(middleware_trace), **ids.hook_kwargs(),
  682. )
  683. if modified_args is not None:
  684. function_args = modified_args
  685. except Exception as _hook_err:
  686. logger.debug("pre_tool_call hook error: %s", _hook_err)
  687. if block_message is not None:
  688. return function_args, (tool_error(block_message), "plugin_block", block_message)
  689. # ACP/Zed edit approval before any file mutation. The requester is bound
  690. # via ContextVar only for ACP sessions, so CLI/gateway paths are unaffected.
  691. try:
  692. from acp_adapter.edit_approval import maybe_require_edit_approval
  693. edit_block_message = maybe_require_edit_approval(function_name, function_args)
  694. if edit_block_message is not None:
  695. return function_args, (edit_block_message, "edit_approval_denied", None)
  696. except Exception as _edit_approval_err:
  697. logger.debug("ACP edit approval guard error: %s", _edit_approval_err)
  698. if function_name in {"write_file", "patch"}:
  699. return function_args, (tool_error("Edit approval denied: approval guard failed"), "edit_approval_error", None)
  700. return function_args, None
  701. @contextmanager
  702. def _approval_observability(ids: _CallIds):
  703. """Bind the approval observability context (turn/tool_call/session ids) for the block."""
  704. try:
  705. from tools.approval_context import reset_current_observability_context, set_current_observability_context
  706. tokens = set_current_observability_context(turn_id=ids.turn_id or "", tool_call_id=ids.tool_call_id or "",
  707. session_id=ids.session_id or "")
  708. except Exception:
  709. yield
  710. return
  711. try:
  712. yield
  713. finally:
  714. try:
  715. reset_current_observability_context(tokens)
  716. except Exception:
  717. pass
  718. def _execute_tool(function_name: str, function_args: dict[str, Any], original_args: dict[str, Any], ids: _CallIds,
  719. *, user_task: Optional[str], enabled_tools: Optional[list[str]], skip_tool_execution_middleware: bool) -> Any:
  720. """Run the registry handler (through tool-execution middleware unless skipped)
  721. with the approval observability context bound for the duration."""
  722. dispatch_kwargs: dict[str, Any] = {"task_id": ids.task_id, "session_id": ids.session_id}
  723. if function_name == "execute_code":
  724. # Prefer the caller's list so subagents can't overwrite the parent's
  725. # tool set via the process-global.
  726. dispatch_kwargs["enabled_tools"] = enabled_tools if enabled_tools is not None else _last_resolved_tool_names
  727. else:
  728. dispatch_kwargs["user_task"] = user_task
  729. def _dispatch(next_args: dict[str, Any]) -> Any:
  730. from tools.connectors import dispatch_connector_call, is_connector_name
  731. if is_connector_name(function_name):
  732. return dispatch_connector_call(function_name, next_args, ids.tool_call_id, ids.turn_id, ids.task_id)
  733. return registry.dispatch(function_name, next_args, **dispatch_kwargs)
  734. with _approval_observability(ids):
  735. if skip_tool_execution_middleware:
  736. return _dispatch(function_args)
  737. from hermes_cli.middleware import run_tool_execution_middleware
  738. return run_tool_execution_middleware(function_name, function_args, _dispatch, original_args=original_args,
  739. **ids.hook_kwargs())
  740. def _apply_transform_tool_result_hook(function_name: str, function_args: dict[str, Any], result: Any, duration_ms: int,
  741. ids: _CallIds) -> Any:
  742. """transform_tool_result: plugins may replace the final result string.
  743. Runs after post_tool_call and before the result enters context. Fail-open;
  744. first string return wins. Gated on has_hook so the no-listener path is cheap.
  745. """
  746. try:
  747. from hermes_cli.lifecycle import has_hook, invoke_hook
  748. if has_hook("transform_tool_result"):
  749. status, error_type, error_message = _tool_result_observer_fields(function_name, result)
  750. hook_results = invoke_hook("transform_tool_result", tool_name=function_name, args=function_args,
  751. result=result, **ids.hook_kwargs(), duration_ms=duration_ms,
  752. status=status, error_type=error_type, error_message=error_message)
  753. return next((r for r in hook_results if isinstance(r, str)), result)
  754. except Exception as _hook_err:
  755. logger.debug("transform_tool_result hook error: %s", _hook_err)
  756. return result
  757. def _elapsed_ms(start: float) -> int:
  758. return int((time.monotonic() - start) * 1000)
  759. def handle_function_call(
  760. function_name: str, function_args: dict[str, Any], task_id: Optional[str] = None,
  761. tool_call_id: Optional[str] = None, session_id: Optional[str] = None, turn_id: Optional[str] = None,
  762. api_request_id: Optional[str] = None, user_task: Optional[str] = None, enabled_tools: Optional[list[str]] = None,
  763. skip_pre_tool_call_hook: bool = False, skip_tool_request_middleware: bool = False,
  764. skip_tool_execution_middleware: bool = False, tool_request_middleware_trace: Optional[list[dict[str, Any]]] = None,
  765. enabled_toolsets: Optional[list[str]] = None, disabled_toolsets: Optional[list[str]] = None,
  766. ) -> str:
  767. """Route a tool call through hooks/middleware to the registry; returns a JSON string.
  768. task_id isolates terminal/browser sessions; user_task is forwarded to every handler as a kwarg.
  769. enabled_tools picks execute_code's sandbox tools (default: the process-global
  770. ``_last_resolved_tool_names``). skip_pre_tool_call_hook: caller already fired
  771. it (single-fire contract). enabled/disabled_toolsets scope the Tool Search
  772. bridge catalog to this session's grant (None = unrestricted).
  773. """
  774. function_args = coerce_tool_args(function_name, function_args)
  775. if not isinstance(function_args, dict):
  776. function_args = {}
  777. trace = list(tool_request_middleware_trace or [])
  778. function_name = _LEGACY_TOOL_ALIASES.get(function_name, function_name)
  779. ids = _CallIds(task_id, session_id, tool_call_id, turn_id, api_request_id)
  780. start = time.monotonic()
  781. def _emit(result: Any, **extra: Any) -> Any:
  782. """Emit post_tool_call with this call's identity fields; returns *result*."""
  783. _emit_post_tool_call_hook(function_name=function_name, function_args=function_args, result=result,
  784. **asdict(ids), middleware_trace=list(trace), **extra)
  785. return result
  786. if function_name in {"tool_search", "tool_describe", "tool_call", "manage_connections"} or function_name.startswith("connectors__"):
  787. from agent.runtime_context import current as embedded_context, dispatch as embedded_dispatch
  788. embedded = embedded_context()
  789. if embedded is not None:
  790. # Native discovery/unwrap runs before registry.dispatch below. An
  791. # overridden registry handler alone cannot enforce the application's
  792. # system-home/approval boundary. Keep the admitted envelope intact.
  793. admitted = {entry.get("name") for entry in embedded.get("tools", [])}
  794. if function_name.startswith("connectors__") or function_name not in admitted:
  795. return _emit(tool_error("应用工具必须通过已授权的 tool_search、tool_describe、tool_call 和 manage_connections 入口调用。"))
  796. return _emit(embedded_dispatch(function_name, function_args, **asdict(ids), user_task=user_task),
  797. duration_ms=_elapsed_ms(start))
  798. # Tool Search bridge: tool_search / tool_describe are catalog reads handled
  799. # inline; tool_call is unwrapped so every downstream hook (pre/post, edit
  800. # approval, guardrails) sees the real tool name, never the bridge.
  801. bridged = _dispatch_bridge_tool(function_name, function_args, enabled_toolsets, disabled_toolsets, ids)
  802. if bridged is not None:
  803. result, underlying = bridged
  804. if underlying is None:
  805. return _emit(result, duration_ms=_elapsed_ms(start))
  806. from tools.connectors import CONNECTOR_BATCH_SENTINEL, dispatch_connector_batch
  807. if underlying[0] == CONNECTOR_BATCH_SENTINEL:
  808. return _emit(dispatch_connector_batch(
  809. underlying[1]["calls"], ids, user_task=user_task,
  810. enabled_tools=enabled_tools, middleware_trace=trace,
  811. enabled_toolsets=enabled_toolsets, disabled_toolsets=disabled_toolsets,
  812. ), duration_ms=_elapsed_ms(start))
  813. return handle_function_call(
  814. *underlying, **asdict(ids), user_task=user_task, enabled_tools=enabled_tools,
  815. skip_pre_tool_call_hook=skip_pre_tool_call_hook, skip_tool_request_middleware=skip_tool_request_middleware,
  816. skip_tool_execution_middleware=skip_tool_execution_middleware, tool_request_middleware_trace=list(trace),
  817. enabled_toolsets=enabled_toolsets, disabled_toolsets=disabled_toolsets,
  818. )
  819. from tools.connectors import is_connector_name
  820. from tools.connectors.gateway.names import parse_connector_name
  821. if function_name == "manage_connections" or is_connector_name(function_name):
  822. if "manage_connections" not in _select_tool_names(enabled_toolsets, disabled_toolsets, quiet_mode=True):
  823. return _emit(tool_error("Connectors are not available in this session."))
  824. if is_connector_name(function_name) and parse_connector_name(function_name) is None:
  825. return _emit(tool_error("Malformed connector tool name; expected connectors__<connector>__{tool}."))
  826. original_args = dict(function_args)
  827. if not skip_tool_request_middleware:
  828. function_args, original_args, trace = _apply_request_middleware(function_name, function_args, ids, trace)
  829. try:
  830. if function_name in _AGENT_LOOP_TOOLS:
  831. return tool_error(f"{function_name} must be handled by the agent loop")
  832. function_args, blocked = _pre_dispatch_guards(function_name, function_args, skip_pre_tool_call_hook, ids, trace)
  833. if blocked is not None:
  834. result, error_type, error_message = blocked
  835. return _emit(result, status="blocked", error_type=error_type, error_message=error_message)
  836. # Any non-read/search tool resets the consecutive-read-loop counter.
  837. if function_name not in _READ_SEARCH_TOOLS:
  838. try:
  839. from tools.file_tools_read_tracking import notify_other_tool_call
  840. notify_other_tool_call(task_id or "default")
  841. except Exception:
  842. pass # file_tools may not be loaded yet
  843. # duration_ms (monotonic) is exposed to post_tool_call / transform_tool_result.
  844. start = time.monotonic()
  845. result = _execute_tool(function_name, function_args, original_args, ids, user_task=user_task,
  846. enabled_tools=enabled_tools, skip_tool_execution_middleware=skip_tool_execution_middleware)
  847. duration_ms = _elapsed_ms(start)
  848. _emit(result, duration_ms=duration_ms)
  849. return _apply_transform_tool_result_hook(function_name, function_args, result, duration_ms, ids)
  850. except Exception as e:
  851. error_msg = f"Error executing {function_name}: {e!s}"
  852. logger.exception(error_msg)
  853. return _emit(tool_error(_sanitize_tool_error(error_msg)), duration_ms=_elapsed_ms(start),
  854. status="error", error_type=type(e).__name__, error_message=str(e))
  855. # =============================================================================
  856. # Backward-compat wrapper functions (registry pass-throughs)
  857. # =============================================================================
  858. def get_all_tool_names() -> list[str]:
  859. return registry.get_all_tool_names()
  860. def get_toolset_for_tool(tool_name: str) -> Optional[str]:
  861. return registry.get_toolset_for_tool(tool_name)
  862. def get_available_toolsets() -> dict[str, dict]:
  863. """Toolset availability info for UI display."""
  864. return registry.get_available_toolsets()
  865. def check_toolset_requirements() -> dict[str, bool]:
  866. """{toolset: available_bool} for every registered toolset."""
  867. return registry.check_toolset_requirements()
  868. def check_tool_availability(quiet: bool = False) -> tuple[list[str], list[dict]]:
  869. """(available_toolsets, unavailable_info)."""
  870. return registry.check_tool_availability(quiet=quiet)