`gjjPdZddlmZddlZddlZddlZddlZddlmZm Z ddl m Z m Z m Z mZmZmZej"dZdZdZd ZeeeehZd Zed Gd dZd-dZd.dZd/dZd0dZd1dZd2dZd3dZ d4dZ!eGddZ"ejFdZ$d5dZ%d6dZ&d7dZ'd8dZ( d9 d:dZ)d;dd$Z-d1d%Z.d?d&Z/dd' d@d(Z0 dAd)Z1dBd*Z2dCd+Z3gd,Z4y)DuProgressive tool disclosure ("tool search") for Hermes Agent. When enabled, MCP and non-core plugin tools are replaced in the model-visible tools array by three bridge tools — ``tool_search``, ``tool_describe``, ``tool_call`` — and surfaced on demand. Core Hermes tools never defer. Design constraints this module is built around (see ``openclaw-tool-search-report`` for the full rationale): * Core tools defined in ``toolsets._HERMES_CORE_TOOLS`` are *never* deferred. Always-load means always-load. No exceptions. * The threshold gate runs every assembly: when deferrable tools would consume less than ``threshold_pct`` of the model's context window (default 10%), tool search is a no-op and the tools array passes through unchanged. * The catalog is stateless across turns and tools-array assemblies. It is rebuilt from the current tool-defs list every time. This is the lesson from OpenClaw's cron regression (openclaw/openclaw#84141): a session-keyed catalog that drifts out of sync with the live tool registry produces silent tool dropouts. * Bridge tools route through ``model_tools.handle_function_call`` exactly like a direct call, so guardrails, plugin pre/post hooks, approval flows, and tool-result truncation all fire identically. * Display and trajectory unwrap is implemented here so the user (CLI activity feed, gateway, saved trajectories) always sees the underlying tool, not the bridge. ) annotationsN) dataclassfield)AnyDictIterableListOptionalTupleztools.tool_search tool_search tool_describe tool_callg@T)frozencLeZdZUdZded<ded<ded<ded<ed d Zy ) ToolSearchConfigzDResolved, validated tool-search configuration for a single assembly.strenabledfloat threshold_pctintsearch_default_limitmax_search_limitc L|dur |ddddS|dur |ddddSt|ts |ddddSt|jd dj j }|d vrd }n|d vrd}n |d vr|}nd}t |jdd}tdtd|}tdtdt|jdd}tdt|t|jdd}|||||S)ayBuild a config from a raw dict / bool / None. Accepts the legacy bool shape (``tools.tool_search: true``) and the dict shape (``tools.tool_search: {enabled: auto, ...}``). Validates and clamps every numeric field; unknown values fall back to safe defaults rather than raising, so a typo in user config does not break the agent. Tautog$@)rrrrFoffr)true1yeson)false0no)rr!rrY@2rr) isinstancedictrgetstriplower _safe_floatmaxmin _safe_int)clsraw enabled_rawrrrrs D/root/.hermes/venv/lib/python3.12/site-packages/tools/tool_search.pyfrom_rawzToolSearchConfig.from_rawHsS $;vT,-D D %<uD,-D D#t$vT,-D D#'')V45;;=CCE . .G 0 0G 1 1!GG#CGGO$V-A-AE-IJK  0 00r7c`eZdZUdZded<ded<ded<ded<ded<ee Zd ed <y ) CatalogEntryzEOne deferrable tool, in a form the bridge tools can search and serve.rrd descriptionDict[str, Any]schemasource source_name)default_factory List[str]_tokensN)r9r:r;r<r=rlistrr?r7r5rr s2O I  Kt4GY4r7rz [A-Za-z0-9]+cv|sgStj|Dcgc]}|jc}Scc}wrA) _TOKEN_REfindallr-)textts r5 _tokenizers/  (006 7!AGGI 77 7s6c|jdxsi}|jdd}|jddxsd}|jdxsijdxsi}dj|j}|jddjd djd djd d}|d|d|S) uXBuild the search-text blob for a deferrable tool. Includes the tool name (with underscores broken into words so BM25 can match against query terms), the description, and the names of the top-level parameters. Schema bodies are deliberately excluded — indexing them adds noise without improving recall in our measurement. rhrdrir parameters properties _.-rs)r+joinkeysreplace)rnrorddescparams param_names name_wordss r5_entry_search_textr!s   !rB 66&" D 66- $ *Dvvl#)r..|<BF((6;;=)Kc3'//S9AA#sKSSTWY\]J\4&+ //r7c ddlm}|j|}|y|jj drd|jfSd|jfS#t $rYywxYw)z=Return (source_kind, source_name) for a registered tool name.rr[)otherrir]mcpplugin)r_r\r`rarbrMrcs r5_classify_sourcer3sd +""4( = == # #F +5==) )%--(( sA(A A AAc g}|D]}|jdxsi}|jdd}|s-|jddxsd}t|\}}t|||||tt |}|j ||S)zBuild the deferred-tool catalog from a tool-defs list. Caller is expected to pass only the deferrable subset (``classify_tools`` returns it as the second element). rhrdrir)rdrrrrr)r+rrrrrj) rkcatalogrnrordrrrres r5 build_catalogrAs #%G VVJ  %2vvfb! vvmR(.B.t4 #045   u Nr7c ||syd}t|} i} |D]} | j| ddz| | <|D]} |j| d} | dk(rtjd|| z dz| dzz z}| j| d}|dk(rW||dzz||d|z || zt |dz zzzz }|||zz }|S)uStandard BM25 score for one query against one document. Inlined small implementation rather than adding a dependency. Performance is fine — the catalog is bounded by N (tools) typically < 500, and we score against the in-memory tokens list. r%rr'g?g?)rvr+rylogr/) query_tokens doc_tokens doc_lengthsavg_dldoc_freqn_docsk1bscoredldoc_tfrqdfidftfnorms r5 _bm25_scorer[s  E ZBF )JJq!$q(q )   \\!Q  7 hhqFRK#-"s(;;< ZZ1  7 R!V}R1q51r6Cz search_catalog..s adr7T)keyreverseN) rrvrsumr/setr+rrjr-rdsort)rquerylimitrrSrrrseenrrscoredresqlrs r5search_catalogrzsq eqj U#L  ,33a3qyy>3K3  C $4a 8 8F!H 1199~ 1A",,q!,q0HQK 11\F/1F&  emm[& & * q5 MM1e* % &  [[] ,EUZZ%%'' sEl+ , KKNDK1 %. )$!QA ))140 *s E Ec d|dtdtd}dtdtd}dtd }d t|d d d ddddddgdddd t|d dd ddidgdddd t|d d ddd dddddgdddgS)uBuild the bridge tool schemas to inject in place of deferred tools. The schemas are intentionally short — every byte added here is a byte the user pays on every turn. Descriptions are tuned to be unambiguous about the call sequence the model should follow. zSearch zu additional tools that are loaded on demand. Returns up to ``limit`` matches with name and description. Follow with `z0` to load a tool's full parameter schema, then `zs` to invoke it. Tools listed at the top of this system prompt are already available and do not need to be searched.z4Load the full JSON schema for one tool returned by `z`. Required before `z'` if the tool's parameters are unknown.zhInvoke a deferred tool by name with the given arguments. Argument shape matches the tool's schema (see `zM`). Policy, hooks, and approvals run exactly as for any directly-listed tool.rhobjectstringzIKeywords describing the capability you need (e.g. 'create github issue').)typerintegerz/Maximum number of results to return. Default 5.)rrr)rrrequiredrdrr)rrhrdz-Exact tool name (as returned by tool_search).zExact tool name to invoke.z,Arguments for the tool, matching its schema.)rd argumentsr)TOOL_DESCRIBE_NAMETOOL_CALL_NAMETOOL_SEARCH_NAME)deferred_count desc_search desc_describe desc_calls r5bridge_tool_schemasrs? .!"#$% !N N ??O>PQ*++R T  ++=*>?E E(*$%-+v" %.+\" #")   ,*,$$,+Z!# "(   $&($%-+G! %-+Y& #"( 5  O< <r7cPeZdZUdZded<ded<dZded<dZded <dZded <y ) AssemblyResultzT !::!vvmR8 ff\26" # ## ::1TFVW r7ct}|D]G}|jdxsijdd}|s+t|s7|j|It |S)aeReturn the set of deferrable tool names present in ``tool_defs``. ``tool_defs`` is expected to be the *pre-assembly* tool list for the current session's toolset scope (i.e. what ``get_tool_definitions(skip_tool_search_assembly=True)`` returns for the session's enabled/disabled toolsets). The resulting set is the universe of tools the session may legitimately reach through ``tool_call``. Used as a scoping gate by both the ``model_tools`` bridge dispatch and the ``tool_executor`` unwrap so a restricted-toolset session can never invoke an out-of-scope tool via the bridge. rhrdri)rr+rfaddrX)rknamesrnrds r5scoped_deferrable_namesrs]eEz"(b--fb9 +D1 IIdO U r7ct|jdxsdj}|sdidfS|tvr did|dfS|jd}|i}t |tr t j |}t |tsdid fSt|s did |d fS||dfS#t j$r}did|fcYd}~Sd}~wwxYw) a?Parse a ``tool_call`` invocation into (underlying_name, args, error_msg). Used by: * the dispatcher in ``model_tools.handle_function_call``, * the display layer (so the activity feed shows the underlying tool), * the trajectory recorder. On parse error, returns ``(None, {}, error_message)``. rdriNz$tool_call requires a 'name' argumentztool_call cannot invoke 'z' (it is itself a bridge tool)rz)tool_call 'arguments' is not valid JSON: z'tool_call 'arguments' must be an objectrz|' is not a deferrable tool. If it appears in the model-facing tools list already, call it directly instead of via tool_call.) rr+r,r^r)rwloadsJSONDecodeErrorr*rf)rrdraw_argsrSs r5resolve_underlying_callrs txx%2 & , , .D R???   R4TF:XYYYxx $H(C  Mzz(+H h %RBBB "4 (RvG G   4 ## MHLL L Ms+B..CCCC)rrrr^rrrrJrfrpr}rrrrrrrrrr)rErrFrr8r)rErrFrr8r)r8r)r8frozenset[str])rdrr8r)rkrr8z1Tuple[List[Dict[str, Any]], List[Dict[str, Any]]])rkzIterable[Dict[str, Any]]r8r)rrrrr Optional[int]r8r)rrr8r)rnrr8r)rdrr8zTuple[str, str])rkrr8List[CatalogEntry])g?g?)rrrrrz List[int]rrrzDict[str, int]rrrrrrr8r)r)rr rrrrr8r )rrr8r)rkrrrrOptional[ToolSearchConfig]r8r)rerr8r)rrrrrr r8r)rrrrr8r)rkrr8r)rrr8z3Tuple[Optional[str], Dict[str, Any], Optional[str]])5r< __future__rrwloggingryre dataclassesrrtypingrrrr r r getLoggerrNrrrrXr^r{rr1r.rJrYrfrpr}rrcompilerrrrrrrrrrrrrrrr__all__r?r7r5rs 6#  (==   . / !$/1C^TU $2 2 2 j /& 489"1 11"1 1@  5 5  5 BJJ ' 8 0$ :-1&05(25%*6;>(*`Tx  %))- 6#6"6 ' 6  6|%?C,@"<HK6.BGJ8( B r7