PL j`UdZddlZddlZddlZddlZddlZddlZddlmZddl m Z m Z m Z m Z mZejeZdejdefdZdedefd Zdd e ede efd ZGd d ZdZiZe e eeeffed<ejZde defdZ ddZ!GddZ"e"Z#defdZ$ddefdZ%dS)aVCentral registry for all hermes-agent tools. Each tool file calls ``registry.register()`` at module level to declare its schema, handler, toolset membership, and availability check. ``model_tools.py`` queries the registry instead of maintaining its own parallel data structures. Import chain (circular-import safe): tools/registry.py (no imports from model_tools or tool files) ^ tools/*.py (import from tools.registry at module level) ^ model_tools.py (imports tools.registry + all tool modules) ^ run_agent.py, cli.py, batch_runner.py, etc. N)Path)CallableDictListOptionalSetnodereturnc8t|tjrt|jtjsdS|jj}t|tjo9|jdko.t|jtjo|jj dkS)zHReturn True when *node* is a ``registry.register(...)`` call expression.Fregisterregistry) isinstanceastExprvalueCallfunc AttributeattrNameid)r rs 2/home/kuhnn/.hermes/hermes-agent/tools/registry.py_is_registry_register_callrs dCH % %Z CH-M-Mu :?D4'' ( I # ( tz38 , , ( JMZ '  module_pathc |d}tj|t|}n#tt f$rYdSwxYwt d|jDS)zReturn True when the module contains a top-level ``registry.register(...)`` call. Only inspects module-body statements so that helper modules which happen to call ``registry.register()`` inside a function are not picked up. zutf-8)encoding)filenameFc34K|]}t|VdSN)r).0stmts r z*_module_registers_tools..6s+FFD)$//FFFFFFr) read_textrparsestrOSError SyntaxErroranybody)rsourcetrees r_module_registers_toolsr-*s &&&88y#k*:*:;;; [ !uu FFDIFFF F FFs9<AA tools_dirc|t|n*ttj}dt |dD}g}|D]_} t j|||-#t$r&}t d||Yd}~Xd}~wwxYw|S)zLImport built-in self-registering tool modules and return their module names.NcRg|]$}|jdv t|d|j%S)> __init__.py mcp_tool.py registry.pyztools.)namer-stem)r!paths r z*discover_builtin_tools..<sK  9I I I #D ) ) J  I I Irz*.pyz#Could not import tool module %s: %s) r__file__resolveparentsortedglob importlib import_moduleappend Exceptionloggerwarning)r. tools_path module_namesimportedmod_namees rdiscover_builtin_toolsrH9s$-$9itH~~?U?U?W?W?^J:??62233LH OO O  #H - - - OOH % % % % O O O NN@(A N N N N N N N N O Os0)B C $CC c eZdZdZdZ ddZdS) ToolEntryz&Metadata for a single registered tool. r4toolsetschemahandlercheck_fn requires_envis_async descriptionemojimax_result_size_charsdynamic_schema_overridesNc ||_||_||_||_||_||_||_||_| |_| |_ | |_ dSr rK) selfr4rLrMrNrOrPrQrRrSrTrUs r__init__zToolEntry.__init__Vs^      (  & %:")A%%%r)NN)__name__ __module__ __qualname____doc__ __slots__rXrrrJrJMsB00IGKAAAAAArrJg>@_check_fn_cachefnctj}t5t|}|!|\}}||z t kr|cdddSdddn #1swxYwY t |}n#t$rd}YnwxYwt5||ft|<dddn #1swxYwY|S)zIReturn bool(fn()), TTL-cached across calls. Swallows exceptions as False.NF)time monotonic_check_fn_cache_lockr_get_CHECK_FN_TTL_SECONDSboolr@)r`nowcachedtsrs r_check_fn_cachedrk~sq .  C  $$R((  IBRx///  RRTT   ++"El+++++++++++++++ Ls51A%%A),A)1B BB" B;;B?B?cxt5tddddS#1swxYwYdS)zDrop all cached ``check_fn`` results. Call after config changes that affect tool availability (e.g. ``hermes tools enable``).N)rdr_clearr^rrinvalidate_check_fn_cacherns                     /33ceZdZdZdZdeeeee e fffdZ deefdZ dee e ffdZ de de d zdefd Zd e deefd Zdee fd Zde dee fdZde de dd fdZdee e ffdZde dee fdZ d3d e de dede de dedede de deezd zde defdZd e dd fd Zd4d!ee d"edeefd#Zd e d$ede fd%Zd5d e d&eezd zdeezfd'Z dee fd(Z!d e deefd)Z"d e dee fd*Z#d6d e d&e de fd,Z$dee e ffd-Z%de defd.Z&dee effd/Z'dee effd0Z(dee effd1Z)d4d"efd2Z*d S)7 ToolRegistryzISingleton registry that collects tool schemas + handlers from tool files.cni|_i|_i|_tj|_d|_dS)Nr)_tools_toolset_checks_toolset_aliases threadingRLock_lock _generationrWs rrXzToolRegistry.__init__s:,. 4602_&& !"rr c|j5t|jt |jfcdddS#1swxYwYdS)zBReturn a coherent snapshot of registry entries and toolset checks.N)rxlistrsvaluesdictrtrzs r_snapshot_statezToolRegistry._snapshot_states Z J J **,,--tD4H/I/II J J J J J J J J J J J J J J J J J Js:AAAc6|dS)z4Return a stable snapshot of registered tool entries.rrrzs r_snapshot_entrieszToolRegistry._snapshot_entries##%%a((rc6|dS)z8Return a stable snapshot of toolset availability checks.rrzs r_snapshot_toolset_checksz%ToolRegistry._snapshot_toolset_checksrrrLcheckNc|sdS t|S#t$rtd|YdSwxYw)zQRun a toolset check, treating missing or failing checks as unavailable/available.Tz,Toolset %s check raised; marking unavailableF)rgr@rAdebugrWrLrs r_evaluate_toolset_checkz$ToolRegistry._evaluate_toolset_checks] 4 ==     LLG Q Q Q55 s%AAr4cx|j5|j|cdddS#1swxYwYdS)z0Return a registered tool entry by name, or None.N)rxrsre)rWr4s r get_entryzToolRegistry.get_entrys Z ) );??4(( ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) )rocXtd|DS)z;Return sorted unique toolset names present in the registry.ch|] }|j Sr^rLr!entrys r z.sKKKu}KKKrr;rrzs rget_registered_toolset_namesz)ToolRegistry.get_registered_toolset_namess+KK$2H2H2J2JKKKLLLrc^tfd|DS)z:Return sorted tool names registered under a given toolset.c3<K|]}|jk |jVdSr rLr4)r!rrLs rr#z:ToolRegistry.get_tool_names_for_toolset..s>   }'' J''''  rr)rWrLs `rget_tool_names_for_toolsetz'ToolRegistry.get_tool_names_for_toolsetsG    $($:$:$<$<      raliasc|j5|j|}|r#||krtd|||||j|<|xjdz c_ddddS#1swxYwYdS)z8Register an explicit alias for a canonical toolset name.z4Toolset alias collision: '%s' (%s) overwritten by %srN)rxrurerArBry)rWrrLexistings rregister_toolset_aliasz#ToolRegistry.register_toolset_aliass Z " ",0077H H//J8W,3D !% (    !   " " " " " " " " " " " " " " " " " "sAA//A36A3cl|j5t|jcdddS#1swxYwYdS)z=Return a snapshot of ``{alias: canonical_toolset}`` mappings.N)rxr~rurzs rget_registered_toolset_aliasesz+ToolRegistry.get_registered_toolset_aliasess| Z / /-.. / / / / / / / / / / / / / / / / / /s )--cx|j5|j|cdddS#1swxYwYdS)z8Return the canonical toolset name for an alias, or None.N)rxrure)rWrs rget_toolset_alias_targetz%ToolRegistry.get_toolset_alias_targets Z 4 4(,,U33 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4roFrMrNrOrPrQrRrSrTrUoverridec |j5|j|} | r| j|kr| jdo|d}|r#t d||| jnU| r#t d||| jn0t d||| j ddddSt||||||pg||p|dd| | |  |j|<|r||j vr ||j |<|xj d z c_ ddddS#1swxYwYdS) aRegister a tool. Called at module-import time by each tool file. ``override=True`` is an explicit opt-in for plugins that intend to replace an existing built-in tool implementation (e.g. swap the default browser tool for a headed-Chrome CDP backend). Without it, registrations that would shadow an existing tool from a different toolset are rejected to prevent accidental overwrites. zmcp-z8Tool '%s': MCP toolset '%s' overwriting MCP toolset '%s'zOTool '%s': toolset '%s' overriding existing toolset '%s' (override=True opt-in)zTool registration REJECTED: '%s' (toolset '%s') would shadow existing tool from toolset '%s'. Pass override=True to register() if the replacement is intentional, or deregister the existing tool first.NrRrrKr) rxrsrerL startswithrArinfoerrorrJrtry)rWr4rLrMrNrOrPrQrRrSrTrUrrboth_mcps rr zToolRegistry.registers.Z0 "0 "{t,,H H,77$//773**622LLRgx'7KK1gx'7LLNgx'7 A0 "0 "0 "0 "0 "0 "0 "0 "B!*!)/R!'H6::mR+H+H&;)A ! ! !DK  9G4+???08$W-    !  a0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "sCEAEE  E c|j5|j|d ddddStfd|jD}|sJ|jjdfd|jD|_|xj dz c_ dddn #1swxYwYt d|dS)aRemove a tool from the registry. Also cleans up the toolset check if no other tools remain in the same toolset. Used by MCP dynamic tool discovery to nuke-and-repave when a server sends ``notifications/tools/list_changed``. Nc38K|]}|jjkVdSr r)r!rGrs rr#z*ToolRegistry.deregister..@s=''/0 U]*''''''rc2i|]\}}|jk||Sr^r)r!rtargetrs r z+ToolRegistry.deregister..Es6)))%v..6...rrzDeregistered tool: %s) rxrspopr)r}rtrLruitemsryrAr)rWr4toolset_still_existsrs @r deregisterzToolRegistry.deregister3sZ " "KOOD$//E} " " " " " " " " $'''''48K4F4F4H4H'''$$ ( $((===)))))-)>)D)D)F)F)))%    !  ! " " " " " " " " " " " " " " ""  ,d33333sCBCCC tool_namesquietcg}i}d|D}t|D]}||}|s|jrP|j|vrt |j||j<||js|st d|ri|jd|ji}|j s | } t| tr| | n3#t$r&} t d|| Yd} ~ nd} ~ wwxYw|d|d|S)a"Return OpenAI-format tool schemas for the requested tool names. Only tools whose ``check_fn()`` returns True (or have no check_fn) are included. ``check_fn()`` results are cached for ~30 s via :func:`_check_fn_cached` to amortize repeat probes (check_terminal_ requirements probes modal/docker, browser checks probe playwright, etc.); TTL chosen so env-var changes (``hermes tools enable foo``) still take effect in near-real-time without forcing a full cache flush on every call. ci|] }|j| Sr^r4rs rrz0ToolRegistry.get_definitions..asSSS5:uSSSrz"Tool %s unavailable (check failed)r4NzCdynamic_schema_overrides for tool %s raised %s; using static schemafunction)typer)rr;rerOrkrArrMr4rUrr~updater@rBr?) rWrrresult check_resultsentries_by_namer4rschema_with_name overridesexcs rget_definitionszToolRegistry.get_definitionsQs/1 SS$:P:P:R:RSSS:&& N ND#''--E ~ >664DU^4T4TM%.1$U^4 Q %I4PPPC%,C CC  -9  % > > @ @I!)T22;(// ::: NN.c MM:;KLL M M M M s>>C== D-D((D-argsc ||}|stjdd|iS |jrddlm}||j|fi|S|j|fi|S#t$r{}t d||dt|j d|} ddlm }||} n#t$r|} YnwxYwtjd| icYd }~Sd }~wwxYw) zExecute a tool handler by name. * Async handlers are bridged automatically via ``_run_async()``. * All exceptions are caught and returned as ``{"error": "..."}`` for consistent error format. rzUnknown tool: r) _run_asynczTool %s dispatch error: %szTool execution failed: z: )_sanitize_tool_errorN) rjsondumpsrQ model_toolsrrNr@rA exceptionrrYr) rWr4rkwargsrrrGrawr sanitizeds rdispatchzToolRegistry.dispatchsft$$ B:w(?(?(?@AA A 4~ A222222!z-%-"?"?"?"?@@@ 5=0000 0 4 4 4   94 C C CDDGG,<CCCCC <<<<<<0055      :w 233 3 3 3 3 3 3 4sG#A$ A$$ C).6C$%B76C$7 CC$CC$C)$C)defaultcd||}|r|j|jS||Sddlm}|S)zBReturn per-tool max result size, or *default* (or global default).Nr)DEFAULT_RESULT_SIZE_CHARS)rrTtools.budget_configr)rWr4rrrs rget_max_result_sizez ToolRegistry.get_max_result_sizesOt$$  /U0<. .  NAAAAAA((rcXtd|DS)z0Return sorted list of all registered tool names.c3$K|] }|jV dSr rrs rr#z2ToolRegistry.get_all_tool_names..s$GGUejGGGGGGrrrzs rget_all_tool_nameszToolRegistry.get_all_tool_namess+GGd.D.D.F.FGGGGGGrcB||}|r|jndS)uReturn a tool's raw schema dict, bypassing check_fn filtering. Useful for token estimation and introspection where availability doesn't matter — only the schema content does. N)rrMrWr4rs r get_schemazToolRegistry.get_schemas& t$$$.u||$.rcB||}|r|jndS)z.Return the toolset a tool belongs to, or None.N)rrLrs rget_toolset_for_toolz!ToolRegistry.get_toolset_for_tools$t$$ %/u}}4/r⚡cP||}|r|jr|jn|S)z3Return the emoji for a tool, or *default* if unset.)rrS)rWr4rrs r get_emojizToolRegistry.get_emojis+t$$$AA 'Brc>d|DS)z?Return ``{tool_name: toolset_name}`` for every registered tool.c(i|]}|j|jSr^)r4rLrs rrz8ToolRegistry.get_tool_to_toolset_map..sPPPe EMPPPr)rrzs rget_tool_to_toolset_mapz$ToolRegistry.get_tool_to_toolset_maps"PPt7M7M7O7OPPPPrc|j5|j|}dddn #1swxYwY|||S)zCheck if a toolset's requirements are met. Returns False (rather than crashing) when the check function raises an unexpected exception (e.g. network error, missing import, bad config). N)rxrtrerrs ris_toolset_availablez!ToolRegistry.is_toolset_availables Z 6 6(,,W55E 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6++GU;;;s /33c\}td|D}fd|DS)z7Return ``{toolset: available_bool}`` for every toolset.ch|] }|j Sr^rrs rrz:ToolRegistry.check_toolset_requirements..s>>>U5=>>>rc di|],}|||-Sr^)rre)r!rLrWtoolset_checkss rrz;ToolRegistry.check_toolset_requirements..sI    T11'>;M;Mg;V;VWW   r)rr;)rWentriestoolsetsrs` @rcheck_toolset_requirementsz'ToolRegistry.check_toolset_requirementssf"&"6"6"8"8>>g>>>??     #    rci}|\}}|D]}|j}||vr1||||gdgd||<||d|j|jr;|jD]3}|||dvr!||d|4|S)z'Return toolset metadata for UI display.r) availabletoolsrR requirementsrr)rrLrrer?r4rP)rWrrrrrjenvs rget_available_toolsetsz#ToolRegistry.get_available_toolsetss$&"&"6"6"8"8 A AEB!!!%!=!=N..r22"" #%$&     RL ! ( ( 4 4 4! A -AAC(2,~">>>  ^4;;C@@@rci}|\}}|D]}|j}||vr|g||dgd||<|j||dvr&||d|j|jD]3}|||dvr!||d|4|S)zABuild a TOOLSET_REQUIREMENTS-compatible dict for backward compat.N)r4env_varsrO setup_urlrrr)rrLrer4r?rP)rWrrrrrjrs rget_toolset_requirementsz%ToolRegistry.get_toolset_requirementss"$"&"6"6"8"8 7 7EB " . 2 22 6 6!% r zG!444r 7#**5:666) 7 7fRj4442Jz*11#666 7 rc|g}g}t}|\}}|D]}|j|vr|||r|b||jfd|Dd||fS)zDReturn (available_toolsets, unavailable_info) like the old function.c4g|]}|jk |jSr^r)r!rGrjs rr7z8ToolRegistry.check_tool_availability..s"IIIbafr)r4rr)setrrLaddrrer?rP) rWrr unavailableseenrrrrjs @rcheck_tool_availabilityz$ToolRegistry.check_tool_availability s  uu"&"6"6"8"8  EBTzz HHRLLL++B0B0B20F0FGG   $$$$"" % 2IIIIgIII$$ +%%r)NNFrrNNF)Fr )r)+rYrZr[r\rXtuplerrJrr&rrrrrgrrrrrrrrr~r|intfloatr rrrrrrrrrrrrrrrr^rrrqrqsSS " " "JtIS(]8K'K!LJJJJ )4 ?)))))$sH}*=))))s8d?t)c)hy&9)))) Md3iMMMM # $s)     "C "# "$ " " " "/S#X//// 4c4hsm4444"!48-1G"G"G"G" G"  G"  G"G"G"G"G" #U{T1G"#+G"G"G"G"G"R4s4t4444>> tool_error("file not found") '{"error": "file not found"}' >>> tool_error("bad input", success=False) '{"error": "bad input", "success": false}' rF ensure_ascii)r&rrr)messageextrars r tool_errorr3sCs7|| $F  e :f5 1 1 11rc ^|tj|dStj|dS)aReturn a JSON result string for tool handlers. Accepts a dict positional arg *or* keyword arguments (not both): >>> tool_result(success=True, count=42) '{"success": true, "count": 42}' >>> tool_result({"key": "value"}) '{"key": "value"}' NFr)rr)datars r tool_resultrAs4 z$U3333 :f5 1 1 11rr )r N)&r\rr=rloggingrvrbpathlibrtypingrrrrr getLoggerrYrAASTrgrr-r&rHrJrfr_rr__annotations__Lockrdrkrnrqr rrr^rrr s@    66666666666666  8 $ $ SW      G G$ G G G GhtnS (AAAAAAAAX68heTk 223888%y~''d$    E&E&E&E&E&E&E&E&R <>>& 2C 2 2 2 2 2 2 2 2 2 2 2 2r