tool_search.py 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649
  1. """Progressive tool disclosure ("tool search"): MCP/plugin tools and a curated set of
  2. event-triggered core tools are replaced in the model-visible array by three bridge tools —
  3. tool_search / tool_describe / tool_call. Invariants: core tools (``toolsets._HERMES_CORE_TOOLS``)
  4. and session-gated GUI toolsets never defer unless named in ``defer``; ANY deferrable tool
  5. activates the bridge (the listing scales with budget, not activation); the catalog is
  6. stateless — rebuilt from the live tool-defs every assembly (a session-keyed one drifts and
  7. silently drops tools); bridge calls route through ``model_tools.handle_function_call``."""
  8. from __future__ import annotations
  9. import functools
  10. import json
  11. import logging
  12. import math
  13. from collections import Counter
  14. from dataclasses import dataclass
  15. from typing import Any, Dict, Iterable, List, Optional, Tuple
  16. from hermes_cli.config_defaults import DEFAULT_CONFIG
  17. from tools.registry import tool_error
  18. from toolsets import CLIENT_SURFACE_TOOLSETS, TOOLSET_SESSION_PLATFORMS
  19. from tools.tool_search_catalog import (
  20. BRIDGE_TOOL_NAMES, CHARS_PER_TOKEN, TOOL_CALL_NAME, TOOL_DESCRIBE_NAME, TOOL_SEARCH_NAME,
  21. CatalogEntry, _fn, _listing_group_label, _registry_entry, _registry_toolset,
  22. build_catalog, build_catalog_listing_with_form, search_catalog)
  23. from tools.tool_search_validation import (
  24. local_batch_error, normalize_tool_call_entries, not_deferrable_error, session_unavailable_error,
  25. unavailable_in_session_reason, validate_deferred_call_args)
  26. from tools.connectors import CONNECTOR_BATCH_SENTINEL, is_connector_name
  27. from tools.connectors.search import (
  28. connections_in_scope, connector_entries_by_group, connectors_unavailable, remote_schemas_for)
  29. logger = logging.getLogger("tools.tool_search")
  30. # Bound the work one bridge call requests. Search is capped at the gateway's
  31. # own limit: the connector search route answers 7 use_cases per request and
  32. # returns HTTP 502 for 8 or more (measured 2026-09-09), and one local call
  33. # maps to one gateway request. Describe has no such remote limit.
  34. _MAX_QUERIES_PER_CALL = 7
  35. _MAX_DESCRIBE_NAMES_PER_CALL = 10
  36. @dataclass(frozen=True)
  37. class ToolSearchConfig:
  38. """Resolved, validated tool-search configuration for a single assembly."""
  39. enabled: str # "auto" | "on" | "off" — "auto" is an alias of "on" today
  40. # Listing budget as % of context; does NOT gate activation, only bounds how much
  41. # the embedded manifest may consume before it degrades (full -> names -> bare).
  42. threshold_pct: float # 0..100
  43. search_default_limit: int
  44. max_search_limit: int
  45. listing: str = "auto" # "auto"/"on" = embed the manifest when it fits; "off" = bare bridge
  46. listing_max_tokens: int = 4000 # budget = min(this, threshold_pct% of context)
  47. # None = curated default; an explicit list replaces it wholesale ([] = defer no core tools).
  48. defer_tools: Optional[frozenset] = None
  49. @property
  50. def effective_defer_tools(self) -> frozenset:
  51. return _DEFAULT_DEFERRED_TOOLS if self.defer_tools is None else self.defer_tools
  52. @classmethod
  53. def from_raw(cls, raw: Any) -> ToolSearchConfig:
  54. """Build from a raw dict / legacy bool / None; every field is clamped and unknown
  55. values fall back to safe defaults — a config typo must not break the agent."""
  56. if not isinstance(raw, dict): # legacy bool / None
  57. raw = {"enabled": "off" if raw is False else "auto"}
  58. max_search_limit = _clamped_int(raw.get("max_search_limit"), 25, 1, 50)
  59. defer_raw = raw.get("defer")
  60. if defer_raw is not None and not isinstance(defer_raw, (list, tuple, set)):
  61. # Loud, then the curated default: a scalar here means the user tried to shrink the
  62. # tool surface and got nothing — never silently ignore it (#116404).
  63. logger.warning(
  64. "tools.tool_search.defer is %r, expected a YAML list of tool names "
  65. "(e.g. [todo_list, computer_use]; [] keeps every tool eager) - "
  66. "using the curated default set.", defer_raw)
  67. defer_raw = None
  68. return cls(
  69. enabled=_tri_state(raw.get("enabled", "auto")),
  70. threshold_pct=max(0.0, min(100.0, _safe_float(raw.get("threshold_pct"), 5.0))),
  71. search_default_limit=_clamped_int(
  72. raw.get("search_default_limit"), 5, 1, max_search_limit),
  73. max_search_limit=max_search_limit,
  74. listing=_tri_state(raw.get("listing", "auto")),
  75. listing_max_tokens=_clamped_int(raw.get("listing_max_tokens"), 4000, 200, 60000),
  76. defer_tools=(frozenset(str(n).strip() for n in defer_raw if str(n).strip())
  77. if isinstance(defer_raw, (list, tuple, set)) else None))
  78. _TRI_STATE_ALIASES = {"true": "on", "1": "on", "yes": "on", "false": "off", "0": "off", "no": "off"}
  79. def _tri_state(value: Any) -> str:
  80. """Normalize an ``auto``/``on``/``off`` setting (bool-ish aliases accepted)."""
  81. text = str(value).strip().lower()
  82. return _TRI_STATE_ALIASES.get(text, text if text in ("auto", "on", "off") else "auto")
  83. def _clamped_int(value: Any, fallback: int, lo: int, hi: int) -> int:
  84. """``int(value)`` (or ``fallback`` when unparseable) clamped to ``[lo, hi]``."""
  85. try:
  86. value = int(value)
  87. except (TypeError, ValueError):
  88. value = fallback
  89. return max(lo, min(hi, value))
  90. def _safe_float(value: Any, fallback: float) -> float:
  91. try:
  92. return float(value)
  93. except (TypeError, ValueError):
  94. return fallback
  95. def _config_from_loader(loader_name: str) -> ToolSearchConfig:
  96. """Tool-search config via ``hermes_cli.config.<loader_name>`` (defaults on any failure)."""
  97. try:
  98. import hermes_cli.config as _cfg_mod
  99. tools_cfg = (getattr(_cfg_mod, loader_name)() or {}).get("tools")
  100. tools_cfg = tools_cfg if isinstance(tools_cfg, dict) else {}
  101. return ToolSearchConfig.from_raw(tools_cfg.get("tool_search"))
  102. except Exception as e:
  103. logger.debug("Failed to load tool-search config: %s", e)
  104. return ToolSearchConfig.from_raw(None)
  105. load_config = functools.partial(_config_from_loader, "load_config")
  106. load_config_readonly = functools.partial(_config_from_loader, "load_config_readonly") # no copy
  107. def _core_tool_names() -> frozenset[str]:
  108. """Names that never defer by default (lazy: ``toolsets`` imports ``tools.registry``)."""
  109. try:
  110. from toolsets import _HERMES_CORE_TOOLS
  111. return frozenset(_HERMES_CORE_TOOLS)
  112. except Exception:
  113. return frozenset()
  114. # Session-gated GUI toolsets: off ``_HERMES_CORE_TOOLS`` so non-GUI clients never pay
  115. # their schema; once enabled they stay direct unless the deferral list names them.
  116. _DIRECT_SURFACE_TOOLSETS = CLIENT_SURFACE_TOOLSETS | TOOLSET_SESSION_PLATFORMS.keys()
  117. # Event-triggered tools deferred BY DEFAULT (a catalog stub suffices). Keep the curated
  118. # list in DEFAULT_CONFIG so config discovery and runtime behavior cannot drift. An explicit
  119. # ``defer`` list replaces this wholesale ([] = everything eager). ``clarify`` is deliberately
  120. # absent: A/B showed deferring it collapsed structured-clarify usage (18/18 -> 7/18) — the
  121. # ask-the-user affordance must be ambient, a stub is not enough.
  122. _DEFAULT_DEFERRED_TOOLS = frozenset(DEFAULT_CONFIG["tools"]["tool_search"]["defer"])
  123. def is_deferrable_tool_name(name: str, defer_tools: Optional[frozenset] = None) -> bool:
  124. """True if a tool is *eligible* for deferral: named in ``defer_tools`` (curated set or
  125. user override), OR an MCP tool, OR neither core nor a session-gated GUI surface (i.e. a
  126. plugin tool). Bridge names never defer."""
  127. if name in BRIDGE_TOOL_NAMES:
  128. return False
  129. if defer_tools is not None and name in defer_tools:
  130. return True
  131. if name in _core_tool_names():
  132. return False
  133. toolset = _registry_toolset(name) # None (unregistered/malformed) never defers
  134. return toolset is not None and (
  135. toolset.startswith("mcp-") or toolset not in _DIRECT_SURFACE_TOOLSETS)
  136. def _tool_def_names(tool_defs: Iterable[dict[str, Any]]) -> Iterable[str]:
  137. """Function names of a tool-defs list (``""`` for a nameless def)."""
  138. return (_fn(td).get("name", "") for td in tool_defs)
  139. def session_tool_names(tool_defs: Iterable[dict[str, Any]]) -> frozenset[str]:
  140. """Every tool name in the session's ``tool_defs`` — what this session can actually
  141. reach. Public wrapper over the private name extractor so callers outside this module
  142. (the ``model_tools`` dispatcher) can scope error messages to the real session."""
  143. return frozenset(n for n in _tool_def_names(tool_defs) if n)
  144. def classify_tools(tool_defs: list[dict[str, Any]], defer_tools: Optional[frozenset] = None,
  145. ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
  146. """Split a tool-defs list into (visible, deferrable); bridge tools are dropped (re-added
  147. after classification)."""
  148. visible: list[dict[str, Any]] = []
  149. deferrable: list[dict[str, Any]] = []
  150. for td, name in zip(tool_defs, _tool_def_names(tool_defs)):
  151. if name not in BRIDGE_TOOL_NAMES:
  152. (deferrable if is_deferrable_tool_name(name, defer_tools) else visible).append(td)
  153. return visible, deferrable
  154. def _deferrable_in(tool_defs: list[dict[str, Any]]) -> list[dict[str, Any]]:
  155. """Deferrable subset of pre-assembly ``tool_defs`` under the read-only user config."""
  156. return classify_tools(tool_defs, load_config_readonly().effective_defer_tools)[1]
  157. def estimate_tokens_from_schemas(tool_defs: Iterable[dict[str, Any]]) -> int:
  158. """Token cost via the chars/4 rule (order-of-magnitude precision suffices)."""
  159. def _chars(td: dict[str, Any]) -> int:
  160. try:
  161. return len(json.dumps(td, ensure_ascii=False, separators=(",", ":")))
  162. except (TypeError, ValueError):
  163. return len(str(td))
  164. return math.ceil(sum(map(_chars, tool_defs)) / CHARS_PER_TOKEN)
  165. def should_activate(config: ToolSearchConfig, deferrable_tokens: int,
  166. context_length: Optional[int], *, connections_granted: bool = False) -> bool:
  167. """``"off"`` never activates; ``"on"``/``"auto"`` activate whenever any deferrable tool
  168. exists ("auto" is reserved for a future budget-gated mode — do not distinguish them
  169. without that design). ``context_length`` is kept for caller compatibility."""
  170. if config.enabled == "off":
  171. return False
  172. if deferrable_tokens > 0:
  173. return True
  174. return connections_granted
  175. def listing_token_budget(config: ToolSearchConfig, context_length: Optional[int]) -> int:
  176. """``min(listing_max_tokens, threshold_pct% of context)``; unknown context uses a 10K
  177. percentage leg (5% of a typical 200K window)."""
  178. pct_leg = (int(context_length * (config.threshold_pct / 100.0))
  179. if context_length and context_length > 0 else 10_000)
  180. return max(0, min(config.listing_max_tokens, pct_leg))
  181. def _bridge_schema(name: str, description: str, properties: dict[str, Any],
  182. required: list[str]) -> dict[str, Any]:
  183. """One OpenAI-style function schema (key order is part of the frozen bytes)."""
  184. return {"type": "function", "function": {
  185. "name": name, "description": description,
  186. "parameters": {"type": "object", "properties": properties, "required": required}}}
  187. _CONNECTIONS_HINT = (
  188. " Searches also cover the user's connected app accounts, whose tools are hosted and so "
  189. "never listed here (results named `connectors__<app>__<tool>`); `manage_connections` checks "
  190. "or connects an account.")
  191. def _search_description(deferred_count: int, listing: Optional[str], listing_form: str,
  192. connections_granted: bool = False) -> str:
  193. """tool_search bridge description with the listing embedded (framing per ``listing_form``).
  194. ``connections_granted`` adds the one sentence that ties ``connectors__`` names to
  195. ``manage_connections``; without that tool in the session the sentence would name a tool
  196. the model cannot call."""
  197. desc = (
  198. (f"Search {deferred_count} additional tools that are loaded on demand. "
  199. if deferred_count else "Search remote connector tools (email, calendars, issue trackers, and more). ")
  200. + "Send one keyword query per capability you need; returns matching tool names "
  201. f"and descriptions. Then `{TOOL_DESCRIBE_NAME}` loads schemas and `{TOOL_CALL_NAME}` "
  202. "invokes. Tools already in your tool list need no search."
  203. + (_CONNECTIONS_HINT if connections_granted else ""))
  204. if not listing:
  205. return desc
  206. if listing_form == "groups":
  207. return desc + (
  208. "\n\nThe servers below are connected and their tools ARE available "
  209. "through this bridge. For any request in these domains, search "
  210. "here FIRST — do not claim the capability is unavailable and do "
  211. "not substitute a generic tool (terminal/browser) without "
  212. "searching.\n\n" + listing)
  213. desc += (
  214. "\n\nEvery tool listed below exists: never call it unavailable, and go straight to "
  215. f"`{TOOL_DESCRIBE_NAME}` when you see the exact name.")
  216. if listing_form == "mixed":
  217. desc += (
  218. " For servers marked 'names not listed', the tools exist "
  219. f"too — find them with `{TOOL_SEARCH_NAME}` before "
  220. "concluding anything is missing.")
  221. return desc + "\n\n" + listing
  222. def bridge_tool_schemas(deferred_count: int, listing: Optional[str] = None,
  223. listing_form: str = "", connections_granted: bool = False) -> list[dict[str, Any]]:
  224. """Bridge tool schemas injected in place of deferred tools; kept short — every byte is paid
  225. every turn. ``listing`` is embedded in the tool_search description; per-tool forms say
  226. "skip search when you see the exact name", "groups" says search is mandatory."""
  227. return [
  228. _bridge_schema(
  229. TOOL_SEARCH_NAME,
  230. _search_description(deferred_count, listing, listing_form, connections_granted),
  231. {
  232. "queries": {
  233. "type": "array",
  234. "items": {"type": "string"},
  235. "description": "One query per capability: service + action + object keywords (e.g. ['gmail send email', 'github create issue']), never a question; every word must match tool text. Searched in parallel.",
  236. },
  237. "limit": {
  238. "type": "integer",
  239. "description": "Max matches per query (default 5).",
  240. },
  241. },
  242. ["queries"],
  243. ),
  244. _bridge_schema(
  245. TOOL_DESCRIBE_NAME,
  246. f"Load the full JSON schemas for tools returned by `{TOOL_SEARCH_NAME}`. "
  247. f"Required before `{TOOL_CALL_NAME}` if a tool's parameters are unknown. "
  248. "Batch every schema you need into one call.",
  249. {
  250. "names": {
  251. "type": "array",
  252. "items": {"type": "string"},
  253. "description": "Exact tool names (as returned by tool_search). A single string is accepted and treated as one name.",
  254. },
  255. },
  256. ["names"],
  257. ),
  258. _bridge_schema(
  259. TOOL_CALL_NAME,
  260. "Invoke deferred tools: `calls` is an array of {name, arguments}, one entry per "
  261. "invocation (batch independent calls; results come back in order). Arguments match "
  262. f"the schema from `{TOOL_DESCRIBE_NAME}`; approvals and hooks apply as usual.",
  263. {
  264. "calls": {
  265. "type": "array",
  266. "items": {
  267. "type": "object",
  268. "properties": {
  269. "name": {"type": "string", "description": "Exact tool name to invoke."},
  270. "arguments": {"type": "object", "description": "Arguments matching the tool schema."},
  271. },
  272. "required": ["name", "arguments"],
  273. },
  274. "description": "One or more independent deferred tool invocations.",
  275. },
  276. },
  277. ["calls"],
  278. ),
  279. ]
  280. @dataclass
  281. class AssemblyResult:
  282. """Outcome of one assembly (tests and observability)."""
  283. tool_defs: list[dict[str, Any]]
  284. activated: bool
  285. deferred_count: int = 0
  286. deferred_tokens: int = 0
  287. threshold_tokens: int = 0
  288. # 0 = passthrough; 1 = bridge + per-tool listing; 2 = bare bridge / server summary only.
  289. tier: int = 0
  290. listing_form: str = "none" # "full" | "names" | "mixed" | "groups" | "none"
  291. def assemble_tool_defs(tool_defs: list[dict[str, Any]], *, context_length: Optional[int] = None,
  292. config: Optional[ToolSearchConfig] = None) -> AssemblyResult:
  293. """Tool-defs the model should see: passthrough when inactive, else deferrable tools
  294. replaced by the three bridge tools. Idempotent — existing bridge tools are stripped first."""
  295. config = config or load_config()
  296. incoming = [td for td, name in zip(tool_defs, _tool_def_names(tool_defs))
  297. if name not in BRIDGE_TOOL_NAMES]
  298. visible, deferrable = classify_tools(incoming, config.effective_defer_tools)
  299. connections_granted = connections_in_scope(incoming)
  300. if not deferrable:
  301. if should_activate(config, 0, context_length, connections_granted=connections_granted):
  302. return AssemblyResult(tool_defs=incoming + bridge_tool_schemas(0, connections_granted=connections_granted),
  303. activated=True, tier=2)
  304. return AssemblyResult(tool_defs=incoming, activated=False)
  305. deferrable_tokens = estimate_tokens_from_schemas(deferrable)
  306. if not should_activate(config, deferrable_tokens, context_length):
  307. return AssemblyResult(
  308. tool_defs=incoming, activated=False, deferred_count=len(deferrable),
  309. deferred_tokens=deferrable_tokens,
  310. threshold_tokens=int((context_length or 0) * (config.threshold_pct / 100.0)), tier=0)
  311. listing, listing_form = None, "none"
  312. listing_budget = listing_token_budget(config, context_length)
  313. if config.listing != "off":
  314. listing, listing_form = build_catalog_listing_with_form(
  315. deferrable, max_tokens=listing_budget)
  316. bridge = bridge_tool_schemas(len(deferrable), listing=listing, listing_form=listing_form,
  317. connections_granted=connections_granted)
  318. tier = 1 if listing_form in ("full", "names", "mixed") else 2
  319. logger.info(
  320. "tool_search activated (tier %d): %d core/visible tools kept, %d deferred "
  321. "(~%d tokens), listing %s (budget ~%d tokens)",
  322. tier, len(visible), len(deferrable), deferrable_tokens, listing_form, listing_budget)
  323. return AssemblyResult(
  324. tool_defs=visible + bridge, activated=True, deferred_count=len(deferrable),
  325. deferred_tokens=deferrable_tokens, threshold_tokens=listing_budget,
  326. tier=tier, listing_form=listing_form)
  327. def is_bridge_tool(name: str) -> bool:
  328. return name in BRIDGE_TOOL_NAMES
  329. def _clip_description(text: str, cap: int = 500) -> str:
  330. """Cap a record description, marking the cut so it reads as deliberate.
  331. A bare slice ends mid-word ("apply exponential bac") and looks like
  332. corruption; the ellipsis says "there is more — tool_describe has it".
  333. 500 keeps 9 in 10 vendor connector descriptions whole and every first
  334. sentence (measured p90 575, first-sentence max 329 over 353 tools).
  335. """
  336. return text if len(text) <= cap else text[:cap] + "…"
  337. def _shared_tool_record(entry: CatalogEntry) -> dict[str, Any]:
  338. """One record for the shared ``tools`` map (per-query groups carry names only);
  339. ``required`` lets the model attempt a trivial call without a ``tool_describe`` round-trip."""
  340. try:
  341. required = entry.schema["function"]["parameters"]["required"]
  342. except (TypeError, KeyError, AttributeError):
  343. required = []
  344. return {"source": entry.source, "source_name": entry.source_name,
  345. "description": _clip_description(entry.description or ""),
  346. "required": [r[:64] for r in (required if isinstance(required, list) else [])
  347. if isinstance(r, str)][:32]}
  348. def _available_source_summary(catalog: list[CatalogEntry]) -> list[dict[str, Any]]:
  349. """Deterministic summaries of connected and declared unavailable sources."""
  350. from tools.tool_search_catalog import hidden_declared_sources
  351. counts = Counter(_listing_group_label(entry.source_name) for entry in catalog)
  352. rows = [{"name": name, "tool_count": counts[name]} for name in sorted(counts)]
  353. return sorted(rows + hidden_declared_sources(), key=lambda row: row["name"])
  354. def _string_list_arg(args: dict[str, Any], key: str, *, dedupe: bool, max_items: int,
  355. retry_hint: str) -> tuple[Optional[list[str]], Optional[str]]:
  356. """Read a list-of-strings bridge argument -> ``(items, error_json)``. A bare string (a
  357. common model slip) is a one-item list; rejects non-lists, all-blank lists, > ``max_items``."""
  358. raw = args.get(key)
  359. raw = [raw] if isinstance(raw, str) else raw
  360. if not isinstance(raw, list):
  361. return None, tool_error(f"{key} is required and must be an array of strings")
  362. out: list[str] = []
  363. for item in raw:
  364. text = str(item or "").strip()
  365. if text and (not dedupe or text not in out):
  366. out.append(text)
  367. if not out:
  368. return None, tool_error(f"{key} is required and must contain at least one non-empty string")
  369. if len(out) > max_items:
  370. return None, tool_error(f"too many {key}: {len(out)} > max {max_items}. {retry_hint}")
  371. return out, None
  372. def dispatch_tool_search(args: dict[str, Any], *, current_tool_defs: list[dict[str, Any]],
  373. config: Optional[ToolSearchConfig] = None,
  374. connector_search: Optional[Any] = None, call: Optional[Any] = None) -> str:
  375. config = config or load_config()
  376. queries, err = _string_list_arg(args, "queries", dedupe=False, max_items=_MAX_QUERIES_PER_CALL,
  377. retry_hint="Retry with fewer, more targeted queries.")
  378. if err:
  379. _record_search_metric(current_tool_defs, hits=0, outcome="error")
  380. return err
  381. raw_limit = args.get("limit")
  382. limit = (config.search_default_limit if raw_limit is None
  383. else _clamped_int(raw_limit, config.search_default_limit, 1, config.max_search_limit))
  384. catalog = build_catalog(_deferrable_in(current_tool_defs))
  385. remote_entries: list[list[CatalogEntry]] = [[] for _ in queries]
  386. hosted_failure: Optional[str] = None
  387. if connections_in_scope(current_tool_defs):
  388. remote_entries, hosted_failure = connector_entries_by_group(
  389. queries, connector_search=connector_search, call=call)
  390. results: list[dict[str, Any]] = []
  391. tools_map: dict[str, dict[str, Any]] = {}
  392. available_sources = _available_source_summary(catalog)
  393. for position, query in enumerate(queries):
  394. corpus = catalog + remote_entries[position]
  395. hits = search_catalog(corpus, query, limit=limit)
  396. for h in hits:
  397. tools_map.setdefault(h.name, _shared_tool_record(h))
  398. matches = [h.name for h in hits]
  399. group: dict[str, Any] = {"query": query, "matches": matches}
  400. if not matches and available_sources:
  401. group["available_sources"] = available_sources
  402. group["hint"] = (
  403. "This query returned no lexical matches, but the sources above "
  404. "are connected and their tools remain available. Retry "
  405. "tool_search with the service name plus a concrete action or "
  406. "object before concluding the capability is unavailable.")
  407. results.append(group)
  408. remote_count = sum(1 for name in tools_map if is_connector_name(name))
  409. payload: dict[str, Any] = {"queries": queries, "total_available": len(catalog) + remote_count,
  410. "results": results, "tools": tools_map}
  411. if hosted_failure:
  412. payload["connectors"] = connectors_unavailable(hosted_failure, verb="searched")
  413. _record_search_metric(current_tool_defs, catalog=catalog, hits=len(tools_map),
  414. outcome="connector_unavailable" if hosted_failure else "hits" if tools_map else "no_hits")
  415. return json.dumps(payload, ensure_ascii=False)
  416. def _record_search_metric(current_tool_defs: list[dict[str, Any]], *, hits: int, outcome: str,
  417. catalog: Optional[list[CatalogEntry]] = None) -> None:
  418. """One ``hermes.tool_search.count`` row: which corpora the search read, never the query."""
  419. from hermes_cli.observability.shared_metrics_events import record_tool_search
  420. local = bool(catalog if catalog is not None else _deferrable_in(current_tool_defs))
  421. hosted = connections_in_scope(current_tool_defs)
  422. scope = "both" if local and hosted else "connector" if hosted else "local"
  423. record_tool_search(scope=scope, hits=hits, outcome=outcome)
  424. def dispatch_tool_describe(args: dict[str, Any], *, current_tool_defs: list[dict[str, Any]],
  425. config: Optional[ToolSearchConfig] = None,
  426. connector_describe: Optional[Any] = None, call: Optional[Any] = None) -> str:
  427. config = config or load_config_readonly()
  428. names, err = _string_list_arg(
  429. args, "names", dedupe=True, max_items=_MAX_DESCRIBE_NAMES_PER_CALL,
  430. retry_hint="Retry with fewer names per call.")
  431. if err:
  432. return err
  433. deferrable = _deferrable_in(current_tool_defs)
  434. by_name = {name: _fn(td) for td, name in zip(deferrable, _tool_def_names(deferrable)) if name}
  435. remote_schemas, hosted_failure = remote_schemas_for(names, current_tool_defs, connector_describe, call=call)
  436. tools: dict[str, dict[str, Any]] = {}
  437. not_found: list[str] = []
  438. undescribed: list[str] = []
  439. errors: dict[str, str] = {}
  440. session_names = session_tool_names(current_tool_defs)
  441. for name in names:
  442. fn = by_name.get(name)
  443. remote_fn = remote_schemas.get(name)
  444. if fn is not None:
  445. tools[name] = {"description": fn.get("description", ""),
  446. "parameters": fn.get("parameters", {})}
  447. elif isinstance(remote_fn, dict):
  448. tools[name] = {"description": str(remote_fn.get("description", "")),
  449. "parameters": remote_fn.get("parameters", {})}
  450. elif is_connector_name(name):
  451. (undescribed if hosted_failure else not_found).append(name)
  452. elif unavailable := session_unavailable_error(name, session_names):
  453. # A core tool absent here, deferred or not: tool_search cannot surface it.
  454. errors[name] = unavailable
  455. elif _registry_entry(name) is not None and not is_deferrable_tool_name(
  456. name, load_config_readonly().effective_defer_tools):
  457. # Registered but bridge/core/GUI-surface: a real name, wrong door.
  458. errors[name] = not_deferrable_error(name, session_names)
  459. else:
  460. not_found.append(name)
  461. result: dict[str, Any] = {"tools": tools}
  462. if not_found:
  463. result["not_found"] = not_found
  464. result["hint"] = "Names in not_found are not currently available. Re-run tool_search to refresh."
  465. if errors:
  466. result["errors"] = errors
  467. if hosted_failure:
  468. result["connectors"] = connectors_unavailable(hosted_failure, verb="described", names=undescribed)
  469. return json.dumps(result, ensure_ascii=False)
  470. def scoped_deferrable_names(tool_defs: list[dict[str, Any]]) -> frozenset[str]:
  471. """Deferrable names in the *pre-assembly* ``tool_defs`` of the session scope — the
  472. universe ``tool_call`` may reach. Gates bridge dispatch AND the executor unwrap so a
  473. restricted session cannot invoke an out-of-scope tool via the bridge."""
  474. defer_tools = load_config_readonly().effective_defer_tools
  475. return frozenset(n for n in _tool_def_names(tool_defs)
  476. if n and is_deferrable_tool_name(n, defer_tools))
  477. def out_of_scope_reason(name: str) -> Optional[str]:
  478. """Fail-fast reason for a registered session-gated GUI tool outside this session's
  479. scope (#120413). The generic scope block ("not available ... Use tool_search") sends
  480. the model on a round-trip tool_search can never satisfy — the tool is not in this
  481. session's catalog at all. Name the missing surface instead. None for anything else
  482. (the generic message still applies). Fail-open: never raises."""
  483. try:
  484. if _registry_toolset(name) in _DIRECT_SURFACE_TOOLSETS:
  485. return (f"'{name}' needs a desktop-app session with a GUI surface (preview/terminal panes). "
  486. "This session has none: use it only from the Hermes desktop app, not via tool_search.")
  487. except Exception:
  488. pass
  489. return None
  490. def scope_block_reason(name: str) -> str:
  491. """Block message for a ``tool_call`` naming a tool outside the session's scope. A core tool
  492. (deferred by ``defer:`` or not) names its real reason, since tool_search cannot surface it
  493. here; anything else keeps the search hint."""
  494. return (out_of_scope_reason(name)
  495. or (unavailable_in_session_reason(name)
  496. if name in _core_tool_names() and _registry_entry(name) is not None else None)
  497. or f"'{name}' is not available in this session. Use tool_search to find tools you can call.")
  498. def resolve_underlying_call(args: dict[str, Any], session_tool_names: Optional[Iterable[str]] = None,
  499. ) -> tuple[Optional[str], dict[str, Any], Optional[str]]:
  500. """Parse a ``tool_call`` invocation into (underlying_name, args, error_msg).
  501. Used by:
  502. * the dispatcher in ``model_tools.handle_function_call``,
  503. * the display layer (so the activity feed shows the underlying tool),
  504. * the trajectory recorder.
  505. A connector-only batch resolves
  506. to ``(CONNECTOR_BATCH_SENTINEL, {"calls": [...]}, None)``: the batch is
  507. one dispatch unit owned by the ``model_tools`` bridge branch, and the
  508. sentinel is what planners/display layers see. A single local entry keeps
  509. the historical single-tool contract unchanged.
  510. ``session_tool_names`` is the session's own tool list, when the caller has it. Passed
  511. through so a core tool this session cannot reach reports *unavailable* rather than
  512. "call it directly" — the static core list cannot tell the two apart.
  513. On parse error, returns ``(None, {}, error_message)``.
  514. """
  515. entries, err = normalize_tool_call_entries(args)
  516. if err:
  517. return None, {}, err
  518. if len(entries) > 1 and any(not is_connector_name(e["name"]) for e in entries):
  519. return None, {}, local_batch_error(entries)
  520. if is_connector_name(entries[0]["name"]):
  521. return CONNECTOR_BATCH_SENTINEL, {"calls": entries}, None
  522. name = entries[0]["name"]
  523. raw_args = entries[0]["arguments"]
  524. unavailable = session_unavailable_error(name, session_tool_names)
  525. if unavailable:
  526. return None, {}, unavailable
  527. if not is_deferrable_tool_name(name, load_config_readonly().effective_defer_tools):
  528. return None, {}, not_deferrable_error(name, session_tool_names)
  529. return name, raw_args, None
  530. __all__ = [
  531. "BRIDGE_TOOL_NAMES",
  532. "CONNECTOR_BATCH_SENTINEL",
  533. "TOOL_CALL_NAME",
  534. "TOOL_DESCRIBE_NAME",
  535. "TOOL_SEARCH_NAME",
  536. "AssemblyResult",
  537. "CatalogEntry",
  538. "ToolSearchConfig",
  539. "assemble_tool_defs",
  540. "bridge_tool_schemas",
  541. "build_catalog",
  542. "build_catalog_listing_with_form",
  543. "classify_tools",
  544. "dispatch_tool_describe",
  545. "dispatch_tool_search",
  546. "estimate_tokens_from_schemas",
  547. "is_bridge_tool",
  548. "is_connector_name",
  549. "is_deferrable_tool_name",
  550. "listing_token_budget",
  551. "load_config",
  552. "normalize_tool_call_entries",
  553. "out_of_scope_reason",
  554. "resolve_underlying_call",
  555. "scope_block_reason",
  556. "scoped_deferrable_names",
  557. "search_catalog",
  558. "should_activate",
  559. "validate_deferred_call_args",
  560. ]