iTUdZddlZddlZddlZddlZddlZddlZddlmZddl 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 3/home/ubuntu/.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_charsNc ||_||_||_||_||_||_||_||_| |_| |_ dSr rK) selfr4rLrMrNrOrPrQrRrSrTs r__init__zToolEntry.__init__VsS      (  & %:"""rr )__name__ __module__ __qualname____doc__ __slots__rWrrrJrJMs:00I(, ; ; ; ; ; ;rrJg>@_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_cachedrjvsq .  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)rcr^clearr]rrinvalidate_check_fn_cacherms                     /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 d1d e de dede de dedede de deezd zfdZd e dd fdZd2dee d edeefd!Zd e d"ede fd#Zd3d e d$eezd zdeezfd%Z dee fd&Z!d e deefd'Z"d e dee fd(Z#d4d e d$e de fd*Z$dee e ffd+Z%de defd,Z&dee effd-Z'dee effd.Z(dee effd/Z)d2d efd0Z*d S)5 ToolRegistryzISingleton registry that collects tool schemas + handlers from tool files.cni|_i|_i|_tj|_d|_dS)Nr)_tools_toolset_checks_toolset_aliases threadingRLock_lock _generationrVs rrWzToolRegistry.__init__s:,. 4602_&& !"rr c|j5t|jt |jfcdddS#1swxYwYdS)zBReturn a coherent snapshot of registry entries and toolset checks.N)rwlistrrvaluesdictrsrys 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.rr~rys r_snapshot_entrieszToolRegistry._snapshot_entries##%%a((rc6|dS)z8Return a stable snapshot of toolset availability checks.rrys 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)rfr@rAdebugrVrLrs 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)rwrrrd)rVr4s r get_entryzToolRegistry.get_entrys Z ) );??4(( ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) )rncXtd|DS)z;Return sorted unique toolset names present in the registry.ch|] }|j Sr]rLr!entrys r z.sKKKu}KKKrr;rrys 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)rVrLs `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)rwrtrdrArBrx)rVrrLexistings 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)rwr}rtrys 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)rwrtrd)rVrs 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 4rnFrMrNrOrPrQrRrSrTc X|j5|j|} | r| j|kr| jdo|d} | r#t d||| jn0t d||| j ddddSt||||||pg||p|dd| |  |j|<|r||j vr ||j |<|xj dz c_ ddddS#1swxYwYdS) zARegister a tool. Called at module-import time by each tool file.zmcp-z8Tool '%s': MCP toolset '%s' overwriting MCP toolset '%s'zTool registration REJECTED: '%s' (toolset '%s') would shadow existing tool from toolset '%s'. Deregister the existing tool first if this is intentional.NrRrrKr) rwrrrdrL startswithrArerrorrJrsrx) rVr4rLrMrNrOrPrQrRrSrTrboth_mcps rr zToolRegistry.registersZ& "& "{t,,H H,77$//773**622LLRgx'7LLFgx'7  /& "& "& "& "& "& "& "& "0!*!)/R!'H6::mR+H+H&; ! ! !DK  9G4+???08$W-    !  M& "& "& "& "& "& "& "& "& "& "& "& "& "& "& "& "& "& "sBD4ADD#&D#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..*s6)))%v..6...rrzDeregistered tool: %s) rwrrpopr)r|rsrLrtitemsrxrAr)rVr4toolset_still_existsrs @r deregisterzToolRegistry.deregistersZ " "KOOD$//E} " " " " " " " " $'''''48K4F4F4H4H'''$$ ( $((===)))))-)>)D)D)F)F)))%    !  ! " " " " " " " " " " " " " " ""  ,d33333sCBCCC tool_namesquietcg}i}d|D}t|D]}||}|s|jrP|j|vrt |j||j<||js|st d|qi|jd|ji}| 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..FsSSS5:uSSSrz"Tool %s unavailable (check failed)r4function)typer) rr;rdrOrjrArrMr4r?) rVrrresult check_resultsentries_by_namer4rschema_with_names rget_definitionszToolRegistry.get_definitions6s/1 SS$:P:P:R:RSSS:&& N ND#''--E ~ >664DU^4T4TM%.1$U^4 Q %I4PPPC%,C CC  MM:;KLL M M M M rargsc ||}|stjdd|iS |jrddlm}||j|fi|S|j|fi|S#t$rT}t d||tjddt|j d|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: N) rjsondumpsrQ model_toolsrrNr@rA exceptionrrX)rVr4rkwargsrrrGs rdispatchzToolRegistry.dispatch[st$$ B:w(?(?(?@AA A \~ A222222!z-%-"?"?"?"?@@@ 5=0000 0 \ \ \   94 C C C:w(Y$q''BR(Y(YVW(Y(YZ[[ [ [ [ [ [ [ \s$#A$ A$$ C.A B=7C=Cdefaultcd||}|r|j|jS||Sddlm}|S)zBReturn per-tool max result size, or *default* (or global default).Nr)DEFAULT_RESULT_SIZE_CHARS)rrTtools.budget_configr)rVr4rrrs rget_max_result_sizez ToolRegistry.get_max_result_sizersOt$$  /U0<. .  NAAAAAA((rcXtd|DS)z0Return sorted list of all registered tool names.c3$K|] }|jV dSr rrs rr#z2ToolRegistry.get_all_tool_names..~s$GGUejGGGGGGrrrys rget_all_tool_nameszToolRegistry.get_all_tool_names|s+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)rrMrVr4rs 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)rVr4rrs 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)rrys 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)rwrsrdrrs 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])rrd)r!rLrVtoolset_checkss rrz;ToolRegistry.check_toolset_requirements..sI    T11'>;M;Mg;V;VWW   r)r~r;)rVentriestoolsetsrs` @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)r~rLrrdr?r4rP)rVrrrrrienvs 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)r~rLrdr4r?rP)rVrrrrrirs 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!rGris rr7z8ToolRegistry.check_tool_availability..s"IIIbafr)r4rr)setr~rLaddrrdr?rP) rVrr unavailableseenrrrris @rcheck_tool_availabilityz$ToolRegistry.check_tool_availabilitys  uu"&"6"6"8"8  EBTzz HHRLLL++B0B0B20F0FGG   $$$$"" % 2IIIIgIII$$ +%%r)NNFrrN)Fr )r)+rXrYrZr[rWtuplerrJrr&rr~rrrfrrrrrrrrr}r{intfloatr rrrrrrrrrrrrrrrr]rrrprpsSS " " "JtIS(]8K'K!LJJJJ )4 ?)))))$sH}*=))))s8d?t)c)hy&9)))) Md3iMMMM # $s)     "C "# "$ " " " "/S#X//// 4c4hsm4444"!484"4"4"4" 4"  4"  4"4"4"4"4" #U{T14"4"4"4"l4s4t4444<#c(4DQUJJ\S\\3\\\\.)))cEkD6H)TWZ_T_))))HDIHHHH/s/x~////00#0000 CCcCCCCCCCC Qc3hQQQQ>> tool_error("file not found") '{"error": "file not found"}' >>> tool_error("bad input", success=False) '{"error": "bad input", "success": false}' rF ensure_ascii)r&updaterr)messageextrars r tool_errorrsCs7|| $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_resultr s4 z$U3333 :f5 1 1 11rr )r N)&r[rr=rloggingrurapathlibrtypingrrrrr getLoggerrXrAASTrfrr-r&rHrJrer^rr__annotations__Lockrcrjrmrpr rrr]rrrs8    66666666666666  8 $ $ SW      G G$ G G G GhtnS (;;;;;;;;H68heTk 223888%y~''d$    Y&Y&Y&Y&Y&Y&Y&Y&z <>>& 2C 2 2 2 2 2 2 2 2 2 2 2 2r