tool_search_validation.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265
  1. """Local argument validation for ``tool_call`` against a deferred tool's schema."""
  2. from __future__ import annotations
  3. import copy
  4. import json
  5. import logging
  6. import re
  7. from typing import Any, Dict, Iterable, List, Optional, Tuple
  8. from tools.registry import tool_error
  9. from tools.tool_search_catalog import BRIDGE_TOOL_NAMES, _registry_entry
  10. logger = logging.getLogger("tools.tool_search")
  11. _SCHEMA_LITERAL_KEYS = frozenset({"const", "default", "enum", "example", "examples"})
  12. def _schema_for_local_validation(node: Any) -> Any:
  13. """JSON-Schema-compatible copy honoring OpenAPI ``nullable: true`` (the normal coercion
  14. path accepts that shape, so local validation must too)."""
  15. if isinstance(node, list):
  16. return [_schema_for_local_validation(item) for item in node]
  17. if not isinstance(node, dict):
  18. return node
  19. # Literal keywords hold instance data, not schemas: copy byte-for-byte.
  20. normalized = {key: (copy.deepcopy(value) if key in _SCHEMA_LITERAL_KEYS
  21. else _schema_for_local_validation(value))
  22. for key, value in node.items() if key != "nullable"}
  23. if node.get("nullable") is not True:
  24. return normalized
  25. schema_type = normalized.get("type")
  26. if isinstance(schema_type, str):
  27. schema_type = [schema_type]
  28. if isinstance(schema_type, list):
  29. if "null" not in schema_type:
  30. normalized["type"] = [*schema_type, "null"]
  31. return normalized
  32. # No ``type`` to extend ($ref/combinator): wrap so local refs still resolve from the
  33. # root while null stays an explicit alternative.
  34. return {"anyOf": [normalized, {"type": "null"}]}
  35. def _schema_has_external_ref(node: Any) -> bool:
  36. """True when *node* contains a non-local ``$ref`` — local validation must never turn a
  37. tool call into an implicit network/file fetch (fail open)."""
  38. if isinstance(node, list):
  39. return any(_schema_has_external_ref(item) for item in node)
  40. if not isinstance(node, dict):
  41. return False
  42. ref = node.get("$ref")
  43. return (isinstance(ref, str) and not ref.startswith("#")) or any(
  44. _schema_has_external_ref(value) for key, value in node.items()
  45. if key not in _SCHEMA_LITERAL_KEYS)
  46. def _validation_path(error: Any) -> str:
  47. """Format a jsonschema error path as a compact argument path."""
  48. path = "arguments"
  49. for part in getattr(error, "absolute_path", ()):
  50. if isinstance(part, str) and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", part):
  51. path += f".{part}"
  52. else:
  53. path += f"[{part if isinstance(part, int) else json.dumps(part, ensure_ascii=False)}]"
  54. return path
  55. def _validation_error(message: str, *, path: str, constraint: str, parameters: Any) -> str:
  56. return tool_error(
  57. message, path=path, constraint=constraint, parameters=parameters,
  58. hint="Retry tool_call with 'arguments' matching the parameters schema above.")
  59. def validate_deferred_call_args(name: str, args: dict[str, Any]) -> Optional[str]:
  60. """Validate ``tool_call`` arguments against the deferred tool's schema. Models invoke
  61. deferred tools "blind" (schema unseen) and omit required args; without this, the opaque
  62. downstream failure makes cheap models loop. Required-field probe first, then the same
  63. schema-guided coercion normal dispatch applies, then jsonschema on the repaired copy.
  64. Missing/malformed schemas, no validator, and external refs all fail OPEN. Returns a JSON
  65. error string when invalid, ``None`` when the call should dispatch.
  66. This restores the concrete-schema checks that the provider cannot perform through the generic
  67. ``arguments: object`` bridge. See #5149.
  68. """
  69. try:
  70. from tools.registry import registry as _registry
  71. schema = _registry.get_schema(name)
  72. if not isinstance(schema, dict):
  73. return None
  74. fn = schema.get("function") if schema.get("type") == "function" else schema
  75. params = fn.get("parameters") if isinstance(fn, dict) else None
  76. if not isinstance(params, dict):
  77. return None
  78. required = params.get("required")
  79. missing = ([r for r in required if isinstance(r, str) and r not in args]
  80. if isinstance(required, list) else [])
  81. if missing:
  82. return _validation_error(
  83. f"tool_call to '{name}' is missing required argument(s): "
  84. f"{', '.join(missing)}. The tool was NOT invoked.",
  85. path="arguments", constraint="required", parameters=params)
  86. validation_schema = _schema_for_local_validation(params)
  87. if _schema_has_external_ref(validation_schema):
  88. logger.debug("Skipping local deferred-argument validation for %s: external $ref", name)
  89. return None
  90. # Validate the repaired shape dispatch will see; copy because coerce_tool_args may
  91. # normalize in place (dispatch re-coerces canonically).
  92. try:
  93. from model_tools import coerce_tool_args
  94. candidate_args = coerce_tool_args(name, dict(args))
  95. except Exception:
  96. logger.debug("Deferred-argument coercion failed for %s", name, exc_info=True)
  97. candidate_args = dict(args)
  98. try:
  99. from jsonschema.exceptions import best_match
  100. from jsonschema.validators import validator_for
  101. except ImportError:
  102. logger.debug("jsonschema unavailable; keeping required-only validation for %s", name)
  103. return None
  104. validator_cls = validator_for(validation_schema)
  105. validator_cls.check_schema(validation_schema)
  106. validation_error = best_match(validator_cls(validation_schema).iter_errors(candidate_args))
  107. if validation_error is None:
  108. return None
  109. path = _validation_path(validation_error)
  110. constraint = str(getattr(validation_error, "validator", None) or "schema")
  111. detail = re.sub(r"\s+", " ", str(validation_error.message)).strip()
  112. if len(detail) > 600:
  113. detail = detail[:597] + "..."
  114. return _validation_error(
  115. f"tool_call to '{name}' failed argument validation at {path} "
  116. f"({constraint}): {detail}. The tool was NOT invoked.",
  117. path=path, constraint=constraint, parameters=params)
  118. except Exception: # pragma: no cover — never block dispatch on validator bugs
  119. logger.debug("validate_deferred_call_args failed for %s", name, exc_info=True)
  120. return None
  121. def normalize_tool_call_entries(args: dict[str, Any]) -> tuple[list[dict[str, Any]], Optional[str]]:
  122. """Normalize ``tool_call`` arguments into a ``calls[]`` list of entries.
  123. Accepts the advertised batch shape ``{"calls": [{"name", "arguments"}, ...]}``
  124. and, tolerantly, the legacy single shape ``{"name": ..., "arguments": ...}``
  125. (a single call is a batch of one). Each entry's ``arguments`` is coerced to
  126. a dict (JSON strings parsed, ``None`` → ``{}``). Returns ``(entries, None)``
  127. or ``([], error_message)``.
  128. """
  129. raw_calls = args.get("calls")
  130. if raw_calls is None:
  131. # Legacy single shape.
  132. if not str(args.get("name") or "").strip():
  133. return [], "tool_call requires 'calls' (an array of {name, arguments})"
  134. raw_calls = [{"name": args.get("name"), "arguments": args.get("arguments")}]
  135. if isinstance(raw_calls, str):
  136. # Tolerate the model emitting the batch envelope as a JSON string —
  137. # mirror the per-entry `arguments` handling below (#114484).
  138. try:
  139. raw_calls = json.loads(raw_calls)
  140. except json.JSONDecodeError as e:
  141. return [], f"tool_call 'calls' is not valid JSON: {e}"
  142. if isinstance(raw_calls, dict):
  143. raw_calls = [raw_calls]
  144. if not isinstance(raw_calls, list) or not raw_calls:
  145. return [], "tool_call 'calls' must be a non-empty array of {name, arguments}"
  146. entries: list[dict[str, Any]] = []
  147. for position, raw in enumerate(raw_calls):
  148. if not isinstance(raw, dict):
  149. return [], f"tool_call calls[{position}] must be an object with 'name' and 'arguments'"
  150. name = str(raw.get("name") or "").strip()
  151. if not name:
  152. return [], f"tool_call calls[{position}] requires a 'name'"
  153. if name in BRIDGE_TOOL_NAMES:
  154. return [], f"tool_call cannot invoke '{name}' (it is itself a bridge tool)"
  155. raw_args = raw.get("arguments")
  156. if raw_args is None or (isinstance(raw_args, str) and not raw_args.strip()):
  157. # "" / whitespace is how some OpenAI-compatible gateways spell "no arguments" for a
  158. # parameterless tool (#83937); the loop already treats an empty outer arguments string
  159. # as {} (turn_tool_validation), and a missing required param still surfaces below via
  160. # validate_deferred_call_args instead of an opaque JSON parse error.
  161. raw_args = {}
  162. if isinstance(raw_args, str):
  163. try:
  164. raw_args = json.loads(raw_args)
  165. except json.JSONDecodeError as e:
  166. return [], f"tool_call calls[{position}].arguments is not valid JSON: {e}"
  167. if not isinstance(raw_args, dict):
  168. return [], f"tool_call calls[{position}].arguments must be an object"
  169. entries.append({"name": name, "arguments": raw_args})
  170. return entries, None
  171. _ECHO_ARGS_MAX_CHARS = 1500
  172. def local_batch_error(entries: list[dict[str, Any]]) -> str:
  173. """Rejection for a multi-entry batch that names a local tool. Restates the valid
  174. shape with the caller's OWN first entry: small models re-send an identical batch
  175. when told only the constraint, and the echoed payload is what gets them unstuck."""
  176. first = entries[0]
  177. args = json.dumps(first.get("arguments", {}), ensure_ascii=False, separators=(",", ":"))
  178. if len(args) > _ECHO_ARGS_MAX_CHARS:
  179. args = "{...}" # keep the correction readable; the model still has its own arguments
  180. retry = '{{"calls":[{{"name":{},"arguments":{}}}]}}'.format(json.dumps(first["name"], ensure_ascii=False), args)
  181. remaining = (f" then issue the remaining {len(entries) - 1} call(s) as separate tool_call invocations"
  182. if len(entries) > 1 else "")
  183. return (
  184. f"tool_call takes exactly one entry for local tools; you sent {len(entries)}. "
  185. f"Retry with only: {retry}{remaining}. Only connectors__ names may be batched together."
  186. )
  187. def unavailable_in_session_reason(name: str) -> str:
  188. """Why a registered tool absent from THIS session cannot be reached, whatever its door.
  189. Deferral is a property of the tool, availability one of the session: a deferred tool the
  190. session does not carry (``defer: [delegate_task]`` in a worker) is no more findable through
  191. ``tool_search`` than a stripped core tool is callable directly."""
  192. return (f"'{name}' is not available in this execution context. "
  193. "Don't retry it — state the assumption and proceed with the work.")
  194. def session_unavailable_error(name: str, session_tool_names: Optional[Iterable[str]]) -> Optional[str]:
  195. """The unavailability message when a core tool is missing from the session's own tool list,
  196. whether or not ``defer:`` moved it behind the bridge; None without session context, when
  197. the session carries it, or for MCP/plugin/unregistered names (an absent one may be a stale
  198. catalog that ``tool_search`` can still refresh). A missing GUI surface keeps its own reason."""
  199. if session_tool_names is None or name in set(session_tool_names):
  200. return None
  201. from tools.tool_search import _core_tool_names, out_of_scope_reason # late: imports this module
  202. if name not in _core_tool_names() or _registry_entry(name) is None:
  203. return None
  204. return out_of_scope_reason(name) or unavailable_in_session_reason(name)
  205. def not_deferrable_error(name: str, session_tool_names: Optional[Iterable[str]] = None) -> str:
  206. """Rejection for a ``tool_call`` naming something that is not a deferred tool.
  207. Two different mistakes reach here and need opposite corrections: a directly-listed
  208. tool (call it without the bridge) vs. an unknown name — typically a deferred MCP tool
  209. cited by its bare suffix instead of the full ``mcp__<server>__{tool}`` name. Telling
  210. the second group 'call it directly' is the opposite of what they must do.
  211. ``_HERMES_CORE_TOOLS`` is a *static* list, so a core tool stripped from this session's
  212. toolset (clarify in a subagent, kanban worker) otherwise gets told "call it directly"
  213. — an instruction that can never resolve, burning a turn on a confident wrong answer.
  214. When the caller passes the session-scoped names, absence is reported as unavailability
  215. instead. Stays None for callers with no session context; deliberately never consults the
  216. global blocklist, because a top-level session legitimately has these tools.
  217. """
  218. from tools.tool_search import _core_tool_names # late: tool_search imports this module
  219. if name in _core_tool_names() or _registry_entry(name) is not None:
  220. if session_tool_names is not None and name not in set(session_tool_names):
  221. return unavailable_in_session_reason(name)
  222. return (f"'{name}' is a directly-listed tool, not a deferred one. "
  223. "Call it directly instead of via tool_call.")
  224. suffix = f"__{name}"
  225. try:
  226. from tools.registry import registry
  227. candidates = sorted(n for n in registry.get_all_tool_names() if n.endswith(suffix))
  228. except Exception:
  229. candidates = []
  230. hint = (f" Did you mean {', '.join(repr(c) for c in candidates)}?" if candidates
  231. else " Use tool_search to find the exact name.")
  232. return (f"'{name}' is not a known tool name. Deferred tools must be invoked through tool_call "
  233. f"by the exact name tool_search returns (e.g. mcp__<server>__{{tool}}).{hint}")