registry.py 54 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122
  1. """Central registry for all hermes-agent tools: each tool file calls ``registry.register()``
  2. at import to declare schema, handler, toolset membership and availability check;
  3. ``model_tools.py`` queries the registry instead of keeping parallel data structures.
  4. Cycle-safe import chain: this module imports nothing from model_tools or tool files;
  5. tools/*.py import it at module level; model_tools.py imports both; run_agent/cli import
  6. model_tools."""
  7. import ast
  8. import functools
  9. import importlib
  10. import inspect
  11. import json
  12. import logging
  13. import sys
  14. import threading
  15. import time
  16. from dataclasses import dataclass
  17. from contextlib import contextmanager
  18. from contextvars import ContextVar
  19. from pathlib import Path
  20. from typing import Callable, Dict, List, Optional, Set
  21. from hermes_constants import hermes_home_key, normalize_scope
  22. logger = logging.getLogger(__name__)
  23. _session_tool_scope = ContextVar("session_tool_scope", default=None)
  24. @contextmanager
  25. def session_tool_scope(scope):
  26. """Execution-owned overlay, additive to the existing profile registry."""
  27. token = _session_tool_scope.set(scope)
  28. try:
  29. yield
  30. finally:
  31. _session_tool_scope.reset(token)
  32. def current_session_tool_scope():
  33. return _session_tool_scope.get()
  34. def _session_slot_key():
  35. """The overlay slot key for the current session scope: writes go through ``normalize_scope``
  36. (``register``/``deregister``), so reads must key the same way or the overlay is invisible."""
  37. return normalize_scope(_session_tool_scope.get())
  38. # Cap on a tool error body; only trims runaway interpolated exceptions (static msgs are ~115 chars).
  39. _MAX_TOOL_ERROR_CHARS = 2048
  40. _TOOL_ERROR_TRUNCATION_MARKER = "… [truncated]"
  41. # Logs keep more of the body than the model sees, but still a bounded amount.
  42. _MAX_LOGGED_ERROR_CHARS = 8192
  43. def _bound_error_text(text: str) -> str:
  44. """Bound an error body destined for model context; logs keep a longer prefix."""
  45. if len(text) <= _MAX_TOOL_ERROR_CHARS:
  46. return text
  47. logger.debug(
  48. "tool error body truncated for context (%d chars): %s",
  49. len(text), text[:_MAX_LOGGED_ERROR_CHARS])
  50. return text[:_MAX_TOOL_ERROR_CHARS] + _TOOL_ERROR_TRUNCATION_MARKER
  51. def _bound_json_error_result(result: str) -> str:
  52. """Trim an oversized ``error`` field in a JSON string result: handlers that
  53. ``json.dumps({"error": str(exc)})`` directly bypass ``tool_error``'s cap, so this runs
  54. at the dispatch boundary to stop unbounded errors stacking across retries."""
  55. if len(result) <= _MAX_TOOL_ERROR_CHARS or '"error"' not in result:
  56. return result
  57. try:
  58. payload = json.loads(result)
  59. except ValueError:
  60. return result
  61. error = payload.get("error") if isinstance(payload, dict) else None
  62. if not isinstance(error, str) or len(error) <= _MAX_TOOL_ERROR_CHARS:
  63. return result
  64. payload["error"] = _bound_error_text(error)
  65. return json.dumps(payload, ensure_ascii=False)
  66. def _is_registry_register_call(node: ast.AST) -> bool:
  67. """True when *node* is a ``registry.register(...)`` call expression."""
  68. if not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call):
  69. return False
  70. func = node.value.func
  71. return (
  72. isinstance(func, ast.Attribute) and func.attr == "register"
  73. and isinstance(func.value, ast.Name) and func.value.id == "registry")
  74. def _module_registers_tools(module_path: Path) -> bool:
  75. """True when the module body (or a module-level ``for``) calls ``registry.register(...)``.
  76. Only module-body statements count, so helpers registering inside a function are skipped;
  77. a text prefilter avoids ``ast.parse`` for files lacking both words."""
  78. try:
  79. source = module_path.read_text(encoding="utf-8-sig")
  80. if "registry" not in source or "register" not in source:
  81. return False
  82. tree = ast.parse(source, filename=str(module_path))
  83. except (OSError, SyntaxError):
  84. return False
  85. # Table-driven modules register several tools from one loop, still at import time.
  86. return any(
  87. _is_registry_register_call(stmt)
  88. or (isinstance(stmt, ast.For) and any(_is_registry_register_call(s) for s in stmt.body))
  89. for stmt in tree.body)
  90. def _tool_module_candidates(tools_path: Path) -> list[Path]:
  91. """Flat ``tools/*.py`` modules plus the package entry point ``tools/<pkg>/tool.py``, in one
  92. sorted list. Only ``tool.py`` is scanned in a package, so every other file in it is a library
  93. by construction. Sorted after merging: ``register()`` lets a same-name, same-toolset duplicate
  94. overwrite silently, so the import order must not depend on file depth."""
  95. candidates = list(tools_path.glob("*.py")) + list(tools_path.glob("*/tool.py"))
  96. return sorted(candidates)
  97. def discover_builtin_tools(tools_dir: Optional[Path] = None) -> list[str]:
  98. """Import built-in self-registering tool modules and return their module names. The
  99. per-file AST scan costs ~145 ms over ~100 files, so verdicts are memoized on disk keyed
  100. by ``(mtime_ns, size)``; a mismatch or corrupt cache re-scans that file. The write is
  101. best-effort and atomic, so concurrent processes race harmlessly."""
  102. from agent.safe_worker_policy import safe_worker_enabled
  103. if safe_worker_enabled():
  104. # Toolset filtering happens AFTER import. Keep the troubleshooting worker's
  105. # import graph closed over reviewed core tools, not plugin-backed wrappers
  106. # or a profile-writable discovery cache. Core approval/redaction stay intact.
  107. module_names = ["tools.file_tools", "tools.terminal_tool", "tools.process_registry"]
  108. for module_name in module_names:
  109. importlib.import_module(module_name)
  110. return module_names
  111. tools_path = (Path(tools_dir) if tools_dir is not None else Path(__file__).resolve().parent).resolve()
  112. cache = _load_discovery_cache()
  113. fresh_cache: dict[str, list] = {}
  114. cache_dirty = False
  115. module_names: list[str] = []
  116. for path in _tool_module_candidates(tools_path):
  117. if path.name in {"__init__.py", "registry.py", "mcp_tool.py"}:
  118. continue
  119. rel_parts = path.relative_to(tools_path).with_suffix("").parts
  120. if len(rel_parts) > 1 and not (path.parent / "__init__.py").exists():
  121. # setuptools' package finder drops a directory without __init__.py, so this tool would
  122. # register from a checkout and vanish from an installed wheel.
  123. logger.warning("Skipping %s: package %s has no __init__.py", path, path.parent.name)
  124. continue
  125. abs_path = str(path.resolve())
  126. try:
  127. st = path.stat()
  128. stat_key = (st.st_mtime_ns, st.st_size)
  129. except OSError:
  130. continue
  131. cached = cache.get(abs_path)
  132. if isinstance(cached, (list, tuple)) and len(cached) == 3 and tuple(cached[:2]) == stat_key:
  133. registers = bool(cached[2])
  134. else:
  135. registers = _module_registers_tools(path)
  136. cache_dirty = True
  137. fresh_cache[abs_path] = [stat_key[0], stat_key[1], registers]
  138. if registers:
  139. module_names.append(".".join(("tools", *rel_parts)))
  140. # Drop entries for files that no longer exist; rewrite only when changed.
  141. if cache_dirty or set(fresh_cache) != set(cache):
  142. _save_discovery_cache(fresh_cache)
  143. imported: list[str] = []
  144. for mod_name in module_names:
  145. try:
  146. importlib.import_module(mod_name)
  147. imported.append(mod_name)
  148. except Exception as e:
  149. logger.warning("Could not import tool module %s: %s", mod_name, e)
  150. return imported
  151. def _discovery_cache_path() -> Optional[Path]:
  152. """Path of the tool-discovery verdict cache, or None if unresolvable."""
  153. try:
  154. # Deferred import keeps tools/registry.py a no-deps leaf at import time.
  155. from hermes_constants import get_hermes_home
  156. return Path(get_hermes_home()) / "cache" / "tool_discovery_cache.json"
  157. except Exception:
  158. return None
  159. def _load_discovery_cache() -> dict[str, list]:
  160. """Read the discovery cache; any error → empty dict (full scan)."""
  161. path = _discovery_cache_path()
  162. if path is None:
  163. return {}
  164. try:
  165. with open(path, "r", encoding="utf-8-sig") as fh:
  166. data = json.load(fh)
  167. return data if isinstance(data, dict) else {}
  168. except (OSError, ValueError):
  169. return {}
  170. def _save_discovery_cache(cache: dict[str, list]) -> None:
  171. """Best-effort atomic write of the discovery cache. Never raises."""
  172. path = _discovery_cache_path()
  173. if path is None:
  174. return
  175. try:
  176. from utils import atomic_json_write # stdlib+yaml only; no cycle
  177. from hermes_constants import mkdir_under_hermes_home
  178. mkdir_under_hermes_home(path.parent)
  179. atomic_json_write(path, cache, indent=0)
  180. except Exception as e:
  181. logger.debug("Could not write tool discovery cache %s: %s", path, e)
  182. @dataclass(eq=False, slots=True)
  183. class ToolEntry:
  184. """Metadata for one registered tool (identity semantics: restore/CAS paths compare ``is``)."""
  185. name: str
  186. toolset: str
  187. schema: dict
  188. handler: Callable
  189. check_fn: Optional[Callable]
  190. requires_env: list
  191. is_async: bool
  192. description: str
  193. emoji: str
  194. max_result_size_chars: int | float | None = None
  195. # Zero-arg callable whose dict is shallow-merged onto the schema at every get_definitions()
  196. # — for fields tracking runtime config (delegate_task's description reflects limits).
  197. dynamic_schema_overrides: Optional[Callable] = None
  198. execution_timeout: float | None = None
  199. class _PluginOverridePolicy:
  200. """Identity-bearing authorization record for one plugin generation."""
  201. __slots__ = ("allowed",)
  202. def __init__(self, allowed: bool) -> None:
  203. self.allowed = bool(allowed)
  204. _OVERRIDE_DENIED_MSG = (
  205. "Plugin module {owner!r} cannot override built-in tool {name!r} "
  206. "without operator opt-in (allow_tool_override).")
  207. # ---- check_fn TTL cache ----------------------------------------------------
  208. # check_fns probe external state (Docker, Modal SDK, playwright) that changes on human
  209. # timescales, so results are cached ~30 s: env-var flips via ``hermes tools`` still land
  210. # within a turn or two. Transient-failure suppression: a flapping probe (``docker version``
  211. # timing out under load) would silently strip a whole toolset from the agent being built —
  212. # most visibly a subagent reporting "Tool read_file does not exist" — so a failure within a
  213. # short grace window of the last success serves the last-good True WITHOUT caching it; a
  214. # failure persisting past the window is honored so a dead backend stops advertising tools.
  215. _CHECK_FN_TTL_SECONDS = 30.0
  216. # Grace window after a success in which a failure counts as a flake; kept short
  217. # so a genuinely-down backend is reflected within a couple of turns.
  218. _CHECK_FN_FAILURE_GRACE_SECONDS = 60.0
  219. # How long a list built on a grace-served True may be reused (``check_fn_verdict_window``). Inside the
  220. # grace window the tool is advertised whatever the re-probe returns, so reuse changes no result and only
  221. # bounds how often a failing probe re-runs: at most 12 per 60 s grace per memo key instead of one per
  222. # catalog read or tool_call, which a probe that fails by timing out would block for its full duration.
  223. _CHECK_FN_GRACE_REUSE_SECONDS = 5.0
  224. _CHECK_FN_CACHE_MAX = 512
  225. _check_fn_cache: dict[tuple[Callable, Optional[str]], tuple[float, bool]] = {}
  226. _check_fn_last_good: dict[tuple[Callable, Optional[str]], float] = {}
  227. _check_fn_ever_good: set[tuple[Callable, Optional[str]]] = set() # probes that admitted tools this process
  228. _check_fn_core_drop_warned: set[tuple[Callable, Optional[str]]] = set() # once-per-process WARNING gate
  229. _check_fn_cache_lock = threading.Lock()
  230. CHECK_FN_CACHE_BYPASS = ""
  231. _NO_CACHE_CHECK_FNS: set[Callable] = set()
  232. # Bumped by invalidate_check_fn_cache(): anything derived from the dropped verdicts is void.
  233. _check_fn_epoch = 0
  234. # Earliest expiry of the verdicts consulted inside check_fn_verdict_window() (None outside one).
  235. _verdict_expiry: ContextVar[Optional[list]] = ContextVar("check_fn_verdict_expiry", default=None)
  236. def no_cache_check_fn(fn: Callable) -> Callable:
  237. """Mark a local, config-backed availability check as uncached."""
  238. _NO_CACHE_CHECK_FNS.add(fn)
  239. return fn
  240. def check_fn_cache_epoch() -> int:
  241. """Changes whenever ``invalidate_check_fn_cache()`` drops the cached verdicts."""
  242. return _check_fn_epoch
  243. @contextmanager
  244. def check_fn_verdict_window():
  245. """Yield a one-item list holding the earliest expiry (``time.monotonic``) of the cached
  246. ``check_fn`` verdicts consulted inside the block, ``inf`` when none was. A result filtered on
  247. those verdicts must not be reused past it: reusing it would replay a verdict this cache has
  248. already expired. A grace-served True expires after ``_CHECK_FN_GRACE_REUSE_SECONDS``, never past
  249. the end of its grace window. ``no_cache_check_fn`` probes are config-backed and set no expiry."""
  250. sink = [float("inf")]
  251. token = _verdict_expiry.set(sink)
  252. try:
  253. yield sink
  254. finally:
  255. _verdict_expiry.reset(token)
  256. def _note_verdict_expiry(deadline: float) -> None:
  257. sink = _verdict_expiry.get()
  258. if sink is not None and deadline < sink[0]:
  259. sink[0] = deadline
  260. def _fn_label(fn: Callable) -> object:
  261. return getattr(fn, "__qualname__", fn)
  262. def _prune_check_fn_caches(now: float) -> None:
  263. """Expire stale entries and cap profile-dimensional cache growth. Caller holds the lock."""
  264. for cache, ttl, stamp in (
  265. (_check_fn_cache, _CHECK_FN_TTL_SECONDS, lambda v: v[0]),
  266. (_check_fn_last_good, _CHECK_FN_FAILURE_GRACE_SECONDS, lambda v: v)):
  267. for key, value in list(cache.items()):
  268. if now - stamp(value) >= ttl:
  269. cache.pop(key, None)
  270. while len(cache) >= _CHECK_FN_CACHE_MAX:
  271. cache.pop(next(iter(cache)))
  272. def check_fn_cache_scope() -> Optional[str]:
  273. """Return the active profile key when availability is profile-scoped. Single-profile
  274. processes keep the process-wide cache; a multiplex gateway installs a Hermes-home override
  275. per profile turn, so the canonical profile key is the boundary."""
  276. try:
  277. from agent.secret_scope import serves_routed_profile
  278. from hermes_constants import get_hermes_home_override
  279. if not serves_routed_profile():
  280. return None
  281. override = get_hermes_home_override()
  282. return str(Path(override).expanduser().resolve()) if override else CHECK_FN_CACHE_BYPASS
  283. except Exception:
  284. # Fail closed: bypass both cache layers rather than aliasing requests
  285. # whose multiplex profile identity could not be resolved.
  286. return CHECK_FN_CACHE_BYPASS
  287. def _run_check_fn_uncached(fn: Callable) -> bool:
  288. """Run an availability check without cache/grace handling."""
  289. from agent.secret_scope import UnscopedSecretError, current_secret_scope
  290. try:
  291. return bool(fn())
  292. except UnscopedSecretError:
  293. # The verdict comes from the LIVE scope at the catch site, not from which registry branch
  294. # ran the probe: ``no_cache_check_fn`` probes skip the cache-scope lookup entirely, so a
  295. # branch-derived hint misreported every boot-time uncached probe as a lost scope (#110635).
  296. if current_secret_scope() is None:
  297. # Expected fail-closed probe: with multiplexing on, boot-time check_fns run before any
  298. # profile secret scope exists, so get_secret raises by design. No traceback, so this
  299. # cannot be mistaken for a crashed check_fn (#100697).
  300. logger.debug(
  301. "check_fn %s hit the multiplex fail-closed path with no "
  302. "profile secret scope active; dependent tools re-probe on the first scoped turn",
  303. _fn_label(fn))
  304. else:
  305. # The caller IS scoped but the read still failed closed: the probe dropped the scope on
  306. # the way to get_secret (a bare thread/executor hop) — a spawn-site bug, kept loud.
  307. logger.warning(
  308. "check_fn %s raised UnscopedSecretError while the profile cache "
  309. "scope was resolved; dependent tools will be unavailable this turn",
  310. _fn_label(fn), exc_info=True)
  311. except Exception:
  312. logger.warning(
  313. "check_fn %s raised; dependent tools will be unavailable this turn",
  314. _fn_label(fn), exc_info=True)
  315. return False
  316. def _check_fn_cached(fn: Callable) -> bool:
  317. """Return bool(fn()), TTL-cached across calls."""
  318. now = time.monotonic()
  319. if fn in _NO_CACHE_CHECK_FNS:
  320. return _run_check_fn_uncached(fn)
  321. scope = check_fn_cache_scope()
  322. if scope == CHECK_FN_CACHE_BYPASS:
  323. return _run_check_fn_uncached(fn)
  324. cache_key = (fn, scope)
  325. with _check_fn_cache_lock:
  326. _prune_check_fn_caches(now) # leaves only entries within TTL
  327. cached = _check_fn_cache.get(cache_key)
  328. if cached is not None:
  329. _note_verdict_expiry(cached[0] + _CHECK_FN_TTL_SECONDS)
  330. return cached[1]
  331. exc_info = None
  332. try:
  333. value, outcome = bool(fn()), "returned False"
  334. except Exception as exc:
  335. # Keep the exception for the verdict log below (emitted outside this block, where
  336. # ``exc_info=True`` would resolve to nothing): a check_fn that raises is a bug in the probe
  337. # or its resolver, and a bare "raised" verdict reads as "nothing configured" (#87950).
  338. value, outcome, exc_info = False, "raised", exc
  339. # Resolved outside the cache lock: the registry snapshot takes its own lock.
  340. core_dropped = sorted(_core_tools_gated_by(fn)) if not value else []
  341. # Stamped at completion: a probe that fails by timing out has spent its timeout, and a window
  342. # measured from its start would already be over when it returns, so every read would re-probe.
  343. now = time.monotonic()
  344. with _check_fn_cache_lock:
  345. _prune_check_fn_caches(now)
  346. if value:
  347. _check_fn_last_good[cache_key] = now
  348. _check_fn_ever_good.add(cache_key)
  349. _check_fn_cache[cache_key] = (now, True)
  350. _note_verdict_expiry(now + _CHECK_FN_TTL_SECONDS)
  351. return True
  352. last_good = _check_fn_last_good.get(cache_key)
  353. if last_good is not None and now - last_good < _CHECK_FN_FAILURE_GRACE_SECONDS:
  354. # Recent success → flake: serve last-good True, do NOT cache (next direct check re-probes).
  355. _note_verdict_expiry(min(now + _CHECK_FN_GRACE_REUSE_SECONDS, last_good + _CHECK_FN_FAILURE_GRACE_SECONDS))
  356. logger.warning(
  357. "check_fn %s failed (%s) within %.0fs of last success; "
  358. "treating as transient and keeping tool(s) available",
  359. _fn_label(fn), outcome, _CHECK_FN_FAILURE_GRACE_SECONDS)
  360. return True
  361. # No recent success (or grace expired) — honor the failure. A False verdict is the
  362. # expected state for optional, unconfigured toolsets; only a raised probe is actionable.
  363. # Core (non-deferrable) tools are the exception when they were available earlier in
  364. # this process and the probe now fails: dropped, they leave neither the schema nor the
  365. # tool_search catalog, so the model's "no such tool" is accurate and nothing points at
  366. # the probe. That regression is a WARNING once per probe per process (#112649). A core
  367. # tool whose probe never succeeded (browser, image_gen, HA unconfigured on a stock home)
  368. # is the expected state and keeps the INFO verdict.
  369. if core_dropped and cache_key in _check_fn_ever_good and cache_key not in _check_fn_core_drop_warned:
  370. _check_fn_core_drop_warned.add(cache_key)
  371. logger.warning(
  372. "check_fn %s %s; previously available core tool(s) %s dropped (non-deferrable, "
  373. "so not searchable either); dependent tools will be unavailable this turn",
  374. _fn_label(fn), outcome, ", ".join(core_dropped), exc_info=exc_info)
  375. else:
  376. log = logger.warning if exc_info else logger.info
  377. log(
  378. "check_fn %s %s; dependent tools will be unavailable this turn", _fn_label(fn), outcome,
  379. exc_info=exc_info)
  380. _check_fn_cache[cache_key] = (now, False)
  381. _note_verdict_expiry(now + _CHECK_FN_TTL_SECONDS)
  382. return False
  383. def _core_tools_gated_by(fn: Callable) -> set[str]:
  384. """Names of ``_HERMES_CORE_TOOLS`` members whose registered ``check_fn`` is *fn*."""
  385. try:
  386. from toolsets import _HERMES_CORE_TOOLS
  387. core = frozenset(_HERMES_CORE_TOOLS)
  388. except Exception:
  389. return set()
  390. return {e.name for e in registry._snapshot_entries() if e.check_fn is fn and e.name in core}
  391. def _memo_check(fn: Callable, memo: dict[Callable, bool]) -> bool:
  392. """Per-pass memo on top of the TTL cache: one probe per distinct check_fn."""
  393. if fn not in memo:
  394. memo[fn] = _check_fn_cached(fn)
  395. return memo[fn]
  396. def invalidate_check_fn_cache() -> None:
  397. """Drop all cached ``check_fn`` results (after config changes like ``hermes tools enable``)."""
  398. global _check_fn_epoch
  399. with _check_fn_cache_lock:
  400. _check_fn_epoch += 1
  401. _check_fn_cache.clear()
  402. _check_fn_last_good.clear()
  403. _check_fn_ever_good.clear()
  404. _check_fn_core_drop_warned.clear()
  405. def get_cached_check_fn_result(fn: Callable) -> Optional[bool]:
  406. """Cached verdict for *fn* if its TTL is still valid, else None. NEVER runs the probe:
  407. for read-only surfaces (dashboard panels) that must not do network/auth/SDK work."""
  408. now = time.monotonic()
  409. scope = check_fn_cache_scope()
  410. if scope == CHECK_FN_CACHE_BYPASS:
  411. # Unresolved profile identity bypasses the cache; nothing trustworthy to report.
  412. return None
  413. with _check_fn_cache_lock:
  414. cached = _check_fn_cache.get((fn, scope))
  415. return cached[1] if cached is not None and now - cached[0] < _CHECK_FN_TTL_SECONDS else None
  416. class ToolRegistry:
  417. """Singleton registry that collects tool schemas + handlers from tool files."""
  418. def __init__(self):
  419. self._tools: dict[str, ToolEntry] = {} # built-in / process-global registrations
  420. # Plugin overlays keyed by resolved HERMES_HOME; a profile sees its overlay first.
  421. self._scoped_tools: dict[str, dict[str, ToolEntry]] = {}
  422. # Plugin namespace -> operator opt-in for built-in override (lifecycle-managed);
  423. # scope attribution stays durable after policy removal so delayed callbacks
  424. # remain confined to the profile that loaded them.
  425. self._plugin_override_policy: dict[tuple[Optional[str], str], _PluginOverridePolicy] = {}
  426. self._plugin_module_scopes: dict[str, set[Optional[str]]] = {}
  427. self._toolset_checks: dict[str, Callable] = {}
  428. self._toolset_aliases: dict[str, str] = {}
  429. # MCP refresh mutates while other threads read: serialize writes, snapshot reads.
  430. self._lock = threading.RLock()
  431. # Bumped on every mutation; get_tool_definitions memoizes against it.
  432. self._generation: int = 0
  433. @staticmethod
  434. def current_scope_key() -> str:
  435. return hermes_home_key()
  436. @staticmethod
  437. def _grouped(entries: list[ToolEntry]) -> dict[str, list[ToolEntry]]:
  438. """``{toolset: entries}`` in first-appearance order."""
  439. groups: dict[str, list[ToolEntry]] = {}
  440. for entry in entries:
  441. groups.setdefault(entry.toolset, []).append(entry)
  442. return groups
  443. def _slot(self, scope: Optional[str], *, create: bool = False) -> dict[str, ToolEntry]:
  444. """The registration map for *scope*: global when None, else that profile's overlay."""
  445. scope = normalize_scope(scope)
  446. if scope is None:
  447. return self._tools
  448. if create:
  449. return self._scoped_tools.setdefault(scope, {})
  450. return self._scoped_tools.get(scope, {})
  451. def _drop_toolset_aliases(self, toolset: str) -> None:
  452. self._toolset_aliases = {
  453. alias: target for alias, target in self._toolset_aliases.items() if target != toolset}
  454. def _merged_tools(self, scope: Optional[str] = None) -> dict[str, ToolEntry]:
  455. """Return global tools overlaid with one profile's plugin tools."""
  456. entries = {**self._tools, **self._scoped_tools.get(hermes_home_key(scope), {})}
  457. if scope is None:
  458. entries.update(self._scoped_tools.get(_session_slot_key(), {}))
  459. return entries
  460. def _toolset_entries(self, toolset: str, scope: Optional[str]) -> list[ToolEntry]:
  461. return self._grouped(self._merged_tools(scope).values()).get(toolset, [])
  462. def _snapshot_state(
  463. self, scope: Optional[str] = None) -> tuple[list[ToolEntry], dict[str, Callable]]:
  464. """Return a coherent snapshot of registry entries and toolset checks."""
  465. with self._lock:
  466. entries = list(self._merged_tools(scope).values())
  467. checks = dict(self._toolset_checks)
  468. checks.update({e.toolset: e.check_fn for e in entries if e.check_fn is not None})
  469. return entries, checks
  470. def _snapshot_entries(self) -> list[ToolEntry]:
  471. return self._snapshot_state()[0]
  472. def _toolset_has_exposable_tools(self, toolset: str, entries: list[ToolEntry]) -> bool:
  473. """True when at least one tool in *toolset* would be exposed. Mirrors
  474. :meth:`get_definitions` per-tool filtering so doctor/banners agree with runtime:
  475. mixed toolsets (``terminal`` + desktop-only ``read_terminal``) must not be gated
  476. by the first ``check_fn``."""
  477. memo: dict[Callable, bool] = {}
  478. members = (e for e in entries if e.toolset == toolset)
  479. return any(not e.check_fn or _memo_check(e.check_fn, memo) for e in members)
  480. def get_entry(self, name: str, *, scope: Optional[str] = None) -> Optional[ToolEntry]:
  481. """Active profile's entry by name, falling back to global."""
  482. with self._lock:
  483. return self._lookup(name, scope or self.current_scope_key(), explicit_scope=scope is not None)
  484. def _lookup(self, name: str, scope_key: Optional[str], *, explicit_scope: bool = True) -> Optional[ToolEntry]:
  485. """``_merged_tools(scope).get(name)`` without building the merged dict. An implicit scope
  486. (the caller passed none) also sees the current session's tool overlay, as the merge does."""
  487. if not explicit_scope:
  488. session_scoped = self._scoped_tools.get(_session_slot_key())
  489. if session_scoped is not None and name in session_scoped:
  490. return session_scoped[name]
  491. scoped = self._scoped_tools.get(scope_key)
  492. if scoped is not None and name in scoped:
  493. return scoped[name]
  494. return self._tools.get(name)
  495. def snapshot_registration(
  496. self, name: str, *, scope: Optional[str] = None) -> Optional[ToolEntry]:
  497. """Local slot state only — no global fallback."""
  498. with self._lock:
  499. return self._slot(scope).get(name)
  500. def get_registered_toolset_names(self) -> list[str]:
  501. return sorted(self._grouped(self._snapshot_entries()))
  502. def get_all_entries(self) -> list[ToolEntry]:
  503. return self._snapshot_entries()
  504. def get_tool_names_for_toolset(self, toolset: str) -> list[str]:
  505. return sorted(e.name for e in self._grouped(self._snapshot_entries()).get(toolset, []))
  506. def register_toolset_alias(self, alias: str, toolset: str) -> None:
  507. """Register an explicit alias for a canonical toolset name."""
  508. with self._lock:
  509. existing = self._toolset_aliases.get(alias)
  510. if existing and existing != toolset:
  511. logger.warning(
  512. "Toolset alias collision: '%s' (%s) overwritten by %s", alias, existing, toolset
  513. )
  514. self._toolset_aliases[alias] = toolset
  515. self._generation += 1
  516. def get_registered_toolset_aliases(self) -> dict[str, str]:
  517. with self._lock:
  518. return dict(self._toolset_aliases)
  519. def get_toolset_alias_target(self, alias: str) -> Optional[str]:
  520. with self._lock:
  521. return self._toolset_aliases.get(alias)
  522. # ---- Registration ------------------------------------------------
  523. def register_plugin_override_policy(
  524. self, module_namespace: str, allowed: bool, *, scope: Optional[str] = None,
  525. ) -> _PluginOverridePolicy:
  526. """Bind a plugin module namespace to its current operator opt-in. The identity-bearing
  527. result lets unload/reload revoke a stale authorization without losing attribution."""
  528. scope = normalize_scope(scope)
  529. with self._lock:
  530. policy = _PluginOverridePolicy(allowed)
  531. self._plugin_override_policy[(scope, module_namespace)] = policy
  532. self._plugin_module_scopes.setdefault(module_namespace, set()).add(scope)
  533. return policy
  534. def snapshot_plugin_override_policy(
  535. self, module_namespace: str, *, scope: Optional[str] = None,
  536. ) -> Optional[_PluginOverridePolicy]:
  537. """Return one local authorization generation without fallback."""
  538. scope = normalize_scope(scope)
  539. with self._lock:
  540. return self._plugin_override_policy.get((scope, module_namespace))
  541. def restore_plugin_override_policy(
  542. self, module_namespace: str, current: _PluginOverridePolicy,
  543. previous: Optional[_PluginOverridePolicy], *, scope: Optional[str] = None) -> bool:
  544. """CAS-restore policy state while retaining durable scope attribution."""
  545. scope = normalize_scope(scope)
  546. with self._lock:
  547. key = (scope, module_namespace)
  548. if self._plugin_override_policy.get(key) is not current:
  549. return False
  550. if previous is None:
  551. self._plugin_override_policy.pop(key, None)
  552. else:
  553. self._plugin_override_policy[key] = previous
  554. return True
  555. def _plugin_override_allowed(self, scope: Optional[str], module_namespace: str) -> bool:
  556. policy = self._plugin_override_policy.get((scope, module_namespace))
  557. if policy is None and scope is not None:
  558. policy = self._plugin_override_policy.get((None, module_namespace))
  559. return bool(policy and policy.allowed)
  560. def _plugin_owner_of(self, handler: Callable) -> Optional[str]:
  561. """Plugin namespace that DEFINED *handler* (None for built-in/MCP handlers). Bound to
  562. ``handler.__globals__["__name__"]``, fixed at definition time so it cannot drift with
  563. call site/thread/timing; lambdas and nested functions inherit it, so a plugin cannot
  564. launder an override via a callback."""
  565. mod = self._callable_module(handler)
  566. return self._plugin_namespace_of_module(mod) if mod else None
  567. @staticmethod
  568. def _callable_module(handler: Callable) -> str:
  569. """Resolve defining module through wrappers, partials, and objects."""
  570. current = handler
  571. seen: set[int] = set()
  572. while id(current) not in seen:
  573. seen.add(id(current))
  574. globals_dict = getattr(current, "__globals__", None)
  575. if isinstance(current, functools.partial):
  576. current = current.func
  577. elif getattr(current, "__func__", None) is not None:
  578. current = current.__func__
  579. elif isinstance(globals_dict, dict) and globals_dict.get("__name__", ""):
  580. return str(globals_dict["__name__"])
  581. elif getattr(current, "__wrapped__", None) is not None:
  582. current = current.__wrapped__
  583. else:
  584. break
  585. module_name = getattr(current, "__module__", "")
  586. return str(module_name or getattr(type(current), "__module__", "") or "")
  587. def _plugin_namespace_of_module(self, module_namespace: str) -> Optional[str]:
  588. """Resolve a module/submodule to its durable plugin namespace."""
  589. with self._lock:
  590. matches = [
  591. namespace for namespace in self._plugin_module_scopes
  592. if module_namespace == namespace or module_namespace.startswith(f"{namespace}.")]
  593. if matches:
  594. return max(matches, key=len)
  595. # Also gate plugin modules currently loading but not yet policy-recorded
  596. # (defensive: a handler defined in the plugin namespace is plugin code).
  597. if module_namespace.startswith("hermes_plugins."):
  598. return ".".join(module_namespace.split(".")[:2])
  599. return None
  600. def _plugin_scope_of(self, module_namespace: str) -> Optional[str]:
  601. """Return the profile scope bound to a loaded plugin module."""
  602. with self._lock:
  603. scopes = self._plugin_module_scopes.get(module_namespace)
  604. if not scopes:
  605. return None
  606. active_scope = self.current_scope_key()
  607. if active_scope in scopes:
  608. return active_scope
  609. if len(scopes) == 1:
  610. return next(iter(scopes))
  611. raise PermissionError(
  612. f"Plugin module {module_namespace!r} is active in multiple profiles and cannot "
  613. "register outside one of those scopes.")
  614. def plugin_scope_for_module(self, module_namespace: str) -> Optional[str]:
  615. """Public host lookup for a loaded plugin module's immutable scope."""
  616. owner = self._plugin_namespace_of_module(module_namespace)
  617. return self._plugin_scope_of(owner or module_namespace)
  618. def plugin_scope_for_callable(self, callback: Callable) -> Optional[str]:
  619. """Return the durable plugin scope for any supported callable shape."""
  620. module_name = self._callable_module(callback)
  621. return self.plugin_scope_for_module(module_name) if module_name else None
  622. @staticmethod
  623. def _caller_module() -> str:
  624. """Best-effort module name of the registry method's caller (two frames up).
  625. ``deregister()`` takes only a tool name — no handler for ``_plugin_owner_of`` —
  626. so frame inspection is the only way to know who is asking."""
  627. try:
  628. return sys._getframe(2).f_globals.get("__name__", "") or ""
  629. except Exception:
  630. return ""
  631. def register(
  632. self, name: str, toolset: str, schema: dict, handler: Callable,
  633. check_fn: Callable | None = None, requires_env: list | None = None, is_async: bool = False,
  634. description: str = "", emoji: str = "", max_result_size_chars: float | None = None,
  635. dynamic_schema_overrides: Callable | None = None, override: bool = False,
  636. scope: Optional[str] = None, execution_timeout: float | None = None):
  637. """Register a tool (called at import time by each tool file). ``override=True`` is an
  638. explicit opt-in for plugins replacing a built-in implementation (e.g. a headed-Chrome
  639. browser backend); without it, cross-toolset shadowing is rejected."""
  640. # Reject malformed schemas at registration, not at request time: a non-dict
  641. # ``parameters`` (e.g. a list) serializes into every provider request and 400s the
  642. # whole turn far from the offending plugin. Failing here names the culprit instead.
  643. if not isinstance(schema, dict):
  644. raise ValueError(
  645. f"Tool {name!r}: schema must be a dict, got {type(schema).__name__}")
  646. params = schema.get("parameters")
  647. if params is not None and not isinstance(params, dict):
  648. raise ValueError(
  649. f"Tool {name!r}: schema['parameters'] must be an object (JSON Schema dict), "
  650. f"got {type(params).__name__}")
  651. handler_owner = self._plugin_owner_of(handler)
  652. caller_owner = self._plugin_namespace_of_module(self._caller_module())
  653. owner = caller_owner or handler_owner
  654. if scope is None and owner is not None:
  655. scope = self._plugin_scope_of(owner)
  656. scope = normalize_scope(scope)
  657. with self._lock:
  658. target = self._slot(scope, create=True)
  659. existing = self._lookup(name, scope)
  660. plugin_override_denied = (
  661. owner is not None and not self._plugin_override_allowed(scope, owner))
  662. shadows_global = (
  663. owner is not None and scope is not None
  664. and name not in target and name in self._tools)
  665. if shadows_global:
  666. if not override:
  667. logger.error(
  668. "Tool registration REJECTED: plugin %r attempted to shadow global tool %r "
  669. "without override=True", owner, name)
  670. return
  671. if plugin_override_denied:
  672. raise PermissionError(_OVERRIDE_DENIED_MSG.format(owner=owner, name=name))
  673. if existing and existing.toolset != toolset:
  674. if override:
  675. if plugin_override_denied:
  676. logger.error(
  677. "Tool registration REJECTED: plugin %r attempted to override built-in "
  678. "tool %r (existing toolset %r) without operator opt-in. Set "
  679. "plugins.entries.<plugin_id>.allow_tool_override: true in config.yaml "
  680. "to allow it.",
  681. owner, name, existing.toolset)
  682. raise PermissionError(_OVERRIDE_DENIED_MSG.format(owner=owner, name=name))
  683. # Explicit opt-in (or non-plugin caller): INFO so the override is auditable.
  684. logger.info(
  685. "Tool '%s': toolset '%s' overriding existing toolset '%s' "
  686. "(override=True opt-in)", name, toolset, existing.toolset)
  687. else:
  688. # Reject every cross-toolset shadow (incl. MCP-to-MCP); same-toolset
  689. # re-registration (MCP reconnect/refresh) stays allowed.
  690. logger.error(
  691. "Tool registration REJECTED: '%s' (toolset '%s') would shadow existing "
  692. "tool from toolset '%s'. Pass override=True to register() if the "
  693. "replacement is intentional, or deregister the existing tool first.",
  694. name, toolset, existing.toolset)
  695. return
  696. target[name] = ToolEntry(
  697. name=name, toolset=toolset, schema=schema, handler=handler, check_fn=check_fn,
  698. requires_env=requires_env or [], is_async=is_async,
  699. description=description or schema.get("description", ""), emoji=emoji,
  700. max_result_size_chars=max_result_size_chars, execution_timeout=execution_timeout,
  701. dynamic_schema_overrides=dynamic_schema_overrides)
  702. # Availability is derived per-tool (_toolset_has_exposable_tools), so this map no
  703. # longer gates a toolset; it still feeds get_toolset_requirements ->
  704. # TOOLSET_REQUIREMENTS["check_fn"], which banner.py reads (presence only,
  705. # never called) to classify an unavailable toolset as lazy-init vs disabled.
  706. if scope is None and check_fn and toolset not in self._toolset_checks:
  707. self._toolset_checks[toolset] = check_fn
  708. self._generation += 1
  709. def deregister(self, name: str, *, scope: Optional[str] = None) -> None:
  710. """Remove a tool; drops the toolset check/aliases if it was the last in its toolset.
  711. ``scope`` selects a profile overlay explicitly (multiplexed MCP tools live in the
  712. owning profile's overlay); plugin callers may not name another scope, non-plugin
  713. callers default to the process-global map. Gated by the same opt-in as
  714. ``register(override=True)``, else a plugin could deregister a tool it doesn't own
  715. and re-register over the empty slot (the override check only runs when an entry
  716. exists). ``mcp-*`` toolsets are exempt — discovery repaves its own tools per refresh."""
  717. scope = normalize_scope(scope)
  718. with self._lock:
  719. caller_mod = self._caller_module()
  720. caller_owner = self._plugin_namespace_of_module(caller_mod)
  721. caller_scope = self._plugin_scope_of(caller_owner) if caller_owner is not None else None
  722. if caller_owner is not None and scope is not None and scope != caller_scope:
  723. raise PermissionError(
  724. f"Plugin module {caller_mod!r} cannot deregister tools "
  725. "outside its own profile scope.")
  726. if scope is None:
  727. scope = caller_scope
  728. target = self._slot(scope)
  729. entry = target.get(name)
  730. if entry is None:
  731. if scope is not None and caller_owner is not None and name in self._tools:
  732. raise PermissionError(
  733. f"Scoped plugin module {caller_mod!r} cannot deregister process-global "
  734. f"tool {name!r}; register a scoped override instead.")
  735. return
  736. if not entry.toolset.startswith("mcp-"):
  737. owner = self._plugin_owner_of(entry.handler)
  738. # Ownership binds to the plugin package root (``hermes_plugins.{name}``), not
  739. # the exact module: a submodule's handler is still the package's to remove.
  740. # A handler defined in ``hermes_plugins.pkg.handlers`` is still owned by the
  741. # ``hermes_plugins.pkg`` package — exact string equality would wrongly block root-module
  742. # cleanup code from removing tools registered by a submodule of the same plugin (egilewski
  743. # review on #55840).
  744. same_plugin = bool(owner and caller_owner == owner)
  745. if (
  746. caller_owner is not None
  747. and not same_plugin
  748. and not self._plugin_override_allowed(caller_scope, caller_owner)):
  749. logger.error(
  750. "Tool deregistration REJECTED: plugin %r attempted to "
  751. "remove tool %r (toolset %r) it does not own, without operator opt-in. Set "
  752. "plugins.entries.%s.allow_tool_override: true in config.yaml to allow it.",
  753. caller_mod, name, entry.toolset, caller_mod)
  754. raise PermissionError(
  755. f"Plugin module {caller_mod!r} cannot deregister tool {name!r} (toolset "
  756. f"{entry.toolset!r}) without operator opt-in (allow_tool_override).")
  757. del target[name]
  758. if scope is not None and not target:
  759. self._scoped_tools.pop(scope, None)
  760. if not self._toolset_entries(entry.toolset, scope):
  761. self._toolset_checks.pop(entry.toolset, None)
  762. self._drop_toolset_aliases(entry.toolset)
  763. self._generation += 1
  764. logger.debug("Deregistered tool: %s", name)
  765. def move_to_scope(self, names, scope: str) -> None:
  766. """Move process-global registrations into *scope*'s overlay (a single-profile process that
  767. starts multiplexing hands its launch profile's MCP tools to that profile's own scope)."""
  768. scope = normalize_scope(scope)
  769. with self._lock:
  770. moved = {name: self._tools.pop(name) for name in names if name in self._tools}
  771. if moved:
  772. self._slot(scope, create=True).update(moved)
  773. self._generation += 1
  774. def restore_registration(
  775. self, name: str, current: ToolEntry, previous: Optional[ToolEntry], *,
  776. scope: Optional[str] = None) -> bool:
  777. """Restore a host-owned registration if it is still current (plugin ownership ledger).
  778. The identity check is deliberate: another plugin (or ``PluginManager`` in a
  779. multi-profile process) may have registered a newer entry under the same name, and
  780. unloading this entry must leave that newer one untouched."""
  781. with self._lock:
  782. target = self._slot(scope, create=True)
  783. if target.get(name) is not current:
  784. return False
  785. if previous is None:
  786. target.pop(name, None)
  787. else:
  788. target[name] = previous
  789. if scope is not None and not target:
  790. self._scoped_tools.pop(scope, None)
  791. # Rebuild affected toolset checks from survivors: a plugin may have replaced an
  792. # entry in the same toolset, so its check_fn would otherwise linger after restore.
  793. affected_toolsets = {current.toolset}
  794. if previous is not None:
  795. affected_toolsets.add(previous.toolset)
  796. for toolset in affected_toolsets:
  797. surviving = self._toolset_entries(toolset, scope)
  798. check_fn = next((entry.check_fn for entry in surviving if entry.check_fn), None)
  799. if scope is None:
  800. if check_fn is None:
  801. self._toolset_checks.pop(toolset, None)
  802. else:
  803. self._toolset_checks[toolset] = check_fn
  804. in_overlays = (e for m in self._scoped_tools.values() for e in m.values())
  805. if not surviving and not any(e.toolset == toolset for e in in_overlays):
  806. self._drop_toolset_aliases(toolset)
  807. self._generation += 1
  808. logger.debug("Restored tool registration: %s", name)
  809. return True
  810. # ---- Schema retrieval --------------------------------------------
  811. def get_definitions(self, tool_names: set[str], quiet: bool = False) -> list[dict]:
  812. """OpenAI-format schemas for the requested tools whose ``check_fn`` passes (or is
  813. absent). Probes use the ~30 s TTL cache so ``hermes tools enable`` lands quickly."""
  814. result = []
  815. check_results: dict[Callable, bool] = {}
  816. entries_by_name = {entry.name: entry for entry in self._snapshot_entries()}
  817. for name in sorted(tool_names):
  818. entry = entries_by_name.get(name)
  819. if not entry:
  820. continue
  821. if entry.check_fn and not _memo_check(entry.check_fn, check_results):
  822. if not quiet:
  823. logger.debug("Tool %s unavailable (check failed)", name)
  824. continue
  825. schema_with_name = {**entry.schema, "name": entry.name}
  826. # Runtime-dynamic overrides (e.g. delegate_task limits); the caller's memo is
  827. # keyed on config.yaml mtime+size, so config changes invalidate it automatically.
  828. if entry.dynamic_schema_overrides is not None:
  829. try:
  830. overrides = entry.dynamic_schema_overrides()
  831. except Exception as exc:
  832. overrides = None
  833. logger.warning(
  834. "dynamic_schema_overrides for tool %s raised %s; using static schema",
  835. name, exc)
  836. if isinstance(overrides, dict):
  837. schema_with_name.update(overrides)
  838. result.append({"type": "function", "function": schema_with_name})
  839. return result
  840. # ---- Dispatch ----------------------------------------------------
  841. @staticmethod
  842. def _normalize_handler_result(name: str, result):
  843. """Results must be a string or the multimodal envelope; anything else becomes a
  844. string error so logging/hooks/budgeting/persistence never receive values they
  845. cannot slice or size."""
  846. if isinstance(result, str):
  847. return _bound_json_error_result(result)
  848. if (
  849. isinstance(result, dict)
  850. and result.get("_multimodal") is True
  851. and isinstance(result.get("content"), list)):
  852. return result
  853. result_type = type(result).__name__
  854. logger.error("Tool %s handler returned unsupported result type: %s", name, result_type)
  855. return tool_error(
  856. f"Tool handler returned unsupported result type: {result_type}",
  857. error_type="tool_result_contract", tool=name, result_type=result_type)
  858. def dispatch(
  859. self, name: str, args: dict, *, scope: Optional[str] = None, **kwargs) -> str | dict:
  860. """Execute a tool handler by name: async handlers bridged via ``_run_async()``,
  861. results normalized, every exception returned as ``{"error": ...}``."""
  862. entry = self.get_entry(name, scope=scope)
  863. if not entry:
  864. return tool_error(f"Unknown tool: {name}")
  865. try:
  866. # Plugin contract (plugins/AGENTS.md): optional context kwargs (task_id, session_id, user_task,
  867. # parent_agent, ...) are signature-inspected like hook payloads, so a narrow ``handle(args)``
  868. # plugin handler is not broken by every field the dispatcher injects (#68318).
  869. kwargs = _kwargs_accepted_by(entry.handler, kwargs)
  870. if entry.is_async:
  871. from model_tools import _run_async
  872. result = _run_async(entry.handler(args, **kwargs))
  873. else:
  874. result = entry.handler(args, **kwargs)
  875. return self._normalize_handler_result(name, result)
  876. except Exception as e:
  877. # exc_info already renders the exception, so keep the message copy bounded.
  878. logger.exception("Tool %s dispatch error: %s", name, _bound_error_text(str(e)))
  879. # Sanitize so framing tokens/CDATA/fences in exception text aren't structural noise.
  880. raw = f"Tool execution failed: {type(e).__name__}: {e}"
  881. try:
  882. from model_tools import _sanitize_tool_error
  883. sanitized = _sanitize_tool_error(raw)
  884. except Exception:
  885. sanitized = raw # defensive: never let the sanitizer block error propagation
  886. return tool_error(sanitized)
  887. # ---- Query helpers -----------------------------------------------
  888. def _attr(self, name: str, attr: str):
  889. return getattr(self.get_entry(name), attr, None)
  890. def get_max_result_size(self, name: str, default: float | None = None) -> int | float:
  891. """Return per-tool max result size, or *default* (or global default)."""
  892. size = self._attr(name, "max_result_size_chars")
  893. if size is not None:
  894. return size
  895. if default is not None:
  896. return default
  897. from tools.budget_config import DEFAULT_RESULT_SIZE_CHARS
  898. return DEFAULT_RESULT_SIZE_CHARS
  899. def get_all_tool_names(self) -> list[str]:
  900. return sorted(entry.name for entry in self._snapshot_entries())
  901. def get_schema(self, name: str) -> Optional[dict]:
  902. """Raw schema dict, bypassing check_fn filtering (token estimates, introspection)."""
  903. return self._attr(name, "schema")
  904. def get_toolset_for_tool(self, name: str) -> Optional[str]:
  905. return self._attr(name, "toolset")
  906. def get_emoji(self, name: str, default: str = "⚡") -> str:
  907. """Return the emoji for a tool, or *default* if unset."""
  908. return self._attr(name, "emoji") or default
  909. def get_tool_to_toolset_map(self) -> dict[str, str]:
  910. return {entry.name: entry.toolset for entry in self._snapshot_entries()}
  911. def is_toolset_available(self, toolset: str) -> bool:
  912. """True when a toolset has at least one exposable tool (never raises)."""
  913. return self._toolset_has_exposable_tools(toolset, self._snapshot_entries())
  914. def check_toolset_requirements(self) -> dict[str, bool]:
  915. entries = self._snapshot_entries()
  916. return {
  917. toolset: self._toolset_has_exposable_tools(toolset, entries)
  918. for toolset in sorted(self._grouped(entries))}
  919. def get_available_toolsets(self) -> dict[str, dict]:
  920. """Return toolset metadata for UI display."""
  921. entries = self._snapshot_entries()
  922. toolsets: dict[str, dict] = {}
  923. for toolset, members in self._grouped(entries).items():
  924. toolsets[toolset] = {
  925. "available": self._toolset_has_exposable_tools(toolset, entries),
  926. "tools": [entry.name for entry in members],
  927. "description": "",
  928. "requirements": _unique_env(members)}
  929. return toolsets
  930. def get_toolset_requirements(self) -> dict[str, dict]:
  931. """Build a TOOLSET_REQUIREMENTS-compatible dict for backward compat."""
  932. entries, toolset_checks = self._snapshot_state()
  933. result: dict[str, dict] = {}
  934. for toolset, members in self._grouped(entries).items():
  935. result[toolset] = {
  936. "name": toolset,
  937. "env_vars": _unique_env(members),
  938. "check_fn": toolset_checks.get(toolset),
  939. "setup_url": None,
  940. "tools": [entry.name for entry in members]}
  941. return result
  942. def check_tool_availability(self, quiet: bool = False):
  943. """Return (available_toolsets, unavailable_info) like the old function."""
  944. available, unavailable = [], []
  945. entries = self._snapshot_entries()
  946. groups = self._grouped(entries)
  947. for ts in sorted(groups):
  948. if self._toolset_has_exposable_tools(ts, entries):
  949. available.append(ts)
  950. else:
  951. unavailable.append({
  952. "name": ts, "env_vars": groups[ts][0].requires_env,
  953. "tools": [entry.name for entry in groups[ts]]})
  954. return available, unavailable
  955. def _unique_env(entries: list[ToolEntry]) -> list:
  956. """Union of ``requires_env`` across *entries*, first-seen order, no duplicates."""
  957. out: list = []
  958. for entry in entries:
  959. out.extend(v for v in (entry.requires_env or []) if v not in out)
  960. return out
  961. # Module-level singleton
  962. registry = ToolRegistry()
  963. # Tool handlers must return JSON strings; these replace the ubiquitous
  964. # ``json.dumps({"error": msg}, ensure_ascii=False)`` boilerplate.
  965. def tool_error(message, **extra) -> str:
  966. """``'{"error": "<message>", **extra}'`` — the error body is bounded so a raw
  967. exception can't bloat history across retries."""
  968. return json.dumps({"error": _bound_error_text(str(message)), **extra}, ensure_ascii=False)
  969. def tool_result(data=None, **kwargs) -> str:
  970. """JSON-encode a dict positional arg *or* keyword arguments (not both)."""
  971. return json.dumps(data if data is not None else kwargs, ensure_ascii=False)
  972. def _kwargs_accepted_by(handler: Callable, kwargs: dict) -> dict:
  973. """*kwargs* narrowed to what *handler*'s signature declares; everything when it takes ``**kwargs`` or
  974. cannot be introspected (builtins, some C callables)."""
  975. try:
  976. parameters = inspect.signature(handler).parameters
  977. except (TypeError, ValueError):
  978. return kwargs
  979. if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in parameters.values()):
  980. return kwargs
  981. keyword_kinds = {inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY}
  982. return {k: v for k, v in kwargs.items() if k in parameters and parameters[k].kind in keyword_kinds}