(GjUdZddlZddlZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z mZmZejeZdejdefdZde defd Zdd ee de efd ZGd d ZdZdZiZe e eeeffed<iZ e e efed<ej!Z"de 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 4/home/rurouni/.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..7s+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_toolsrH:s$-$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__Ws^      (  & %:")A%%%r)NN)__name__ __module__ __qualname____doc__ __slots__rXrrrJrJNsB00IGKAAAAAArrJg>@gN@_check_fn_cache_check_fn_last_goodfnc  tj}t5t|}|!|\}}||z t kr|cdddSdddn #1swxYwYd} t |}n#t$rd}d}YnwxYwt5|r$|t|<|dft|< ddddSt|}|Q||z tkrCt dt|d||rdndt ddddSt dt|d||rdnd|dft|< ddddS#1swxYwYdS) aReturn bool(fn()), TTL-cached across calls. Exceptions are swallowed as False. A transient False/exception within ``_CHECK_FN_FAILURE_GRACE_SECONDS`` of the last True is suppressed (the last-good True is returned and the failure is NOT cached, so the next call re-probes) to keep flaky external checks (Docker daemon busy, socket contention, probe timeout) from silently stripping tools mid-session. NFTzicheck_fn %s failed (%s) within %.0fs of last success; treating as transient and keeping tool(s) availabler[raisedzreturned Falsez=check_fn %s %s; dependent tools will be unavailable this turn) time monotonic_check_fn_cache_lockr_get_CHECK_FN_TTL_SECONDSboolr@r`_CHECK_FN_FAILURE_GRACE_SECONDSrArBgetattr)ranowcachedtsrrc last_goods r_check_fn_cachedrps .  C  $$R((  IBRx/// FRRTT     &)  ##&+OB   (++B//  S9_7V%V%V NNFNB//"8(8/    %,  K B + + 4HH$4   #El9sB1A%%A),A)3B BB&F A F: tt~]220@0P0P en-U^, tt urr4cx|j5|j|cdddS#1swxYwYdS)z0Return a registered tool entry by name, or None.N)r}rwrg)rWr4s r get_entryzToolRegistry.get_entry s Z ) );??4(( ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) /33cXtd|DS)z;Return sorted unique toolset names present in the registry.ch|] }|j Sr^rLr!rs r z.sKKKu}KKKrr;rrs 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    $($:$:$<$<      raliasNc|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 %sN)r}rzrgrArBr~)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)r}rrzrs rget_registered_toolset_aliasesz+ToolRegistry.get_registered_toolset_aliases%s| Z / /-.. / / / / / / / / / / / / / / / / / /s )--cx|j5|j|cdddS#1swxYwYdS)z8Return the canonical toolset name for an alias, or None.N)r}rzrg)rWrs rget_toolset_alias_targetz%ToolRegistry.get_toolset_alias_target*s Z 4 4(,,U33 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4rmodule_namespaceallowedct|j5t||j|<ddddS#1swxYwYdS)aBind a plugin module namespace to its operator opt-in for built-in override. Called once per plugin at load time. Durable: never cleared, so later (even threaded/delayed) register() calls from that module are still gated by the same policy. N)r}rirx)rWrrs rregister_plugin_override_policyz,ToolRegistry.register_plugin_override_policy3s Z K K=A']]D ()9 : K K K K K K K K K K K K K K K K K Ks -11rNc |jdd}n#t$rYdSwxYw||jvr|St |t r|dr|SdS)aSReturn the plugin module namespace that defined *handler*, or None if it was not defined in a loaded plugin module. Authorization is bound to where the handler was DEFINED (``handler.__globals__["__name__"]``), which is fixed at definition time and cannot drift with the call site, thread, or timing. Lambdas and nested functions inherit the defining module's globals, so a plugin cannot launder an override through a callback. Built-in/MCP handlers live outside the plugin namespace and return None (unchanged behavior). rYNhermes_plugins.) __globals__rgAttributeErrorrxrr& startswith)rWrNmods r_plugin_owner_ofzToolRegistry._plugin_owner_of<s %))*b99CC   44  $. . .J c3   CNN3D$E$E Jts  ,,c tjd}|jddpdS#t$rYdSwxYw)uBest-effort module name of whoever called the registry method that invoked this helper (two frames up: this helper, then the registry method itself, then the actual caller). ``deregister()`` takes only a tool name — unlike ``register()`` it has no handler argument to bind authorization to via ``_plugin_owner_of``. Frame inspection is the only way to know who is asking. rYr)sys _getframe f_globalsrgr@)frames r_caller_modulezToolRegistry._caller_moduleTsU M!$$E?&&z266<" <   22 s03 AAFrrMrOrPrQrRrSrTrUoverridec ||j5|j|} | r| j|kr| jdo|d}|r#t d||| jn| r||}|S|j|ds8t d||| jtd|d|dt d ||| jn0t d ||| j ddddSt||||||pg||p|d d | | | |j|<|r||j vr ||j |<|xjdz 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. mcp-z8Tool '%s': MCP toolset '%s' overwriting MCP toolset '%s'NFzTool registration REJECTED: plugin %r attempted to override built-in tool %r (existing toolset %r) without operator opt-in. Set plugins.entries..allow_tool_override: true in config.yaml to allow it.Plugin module z cannot override built-in tool z/ without operator opt-in (allow_tool_override).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.rRrrKr)r}rwrgrLrrAdebugrrxerrorPermissionErrorinforJryr~)rWr4rLrMrNrOrPrQrRrSrTrUrrboth_mcp_owners rr zToolRegistry.registerds.ZE "E "{t,,H- H,77$//773**622&LLRgx'7!!227;;F)$2N2R2RSY[`2a2a) : #D(*: .6V66$(666KK1gx'7LLNgx'7 _E "E "E "E "E "E "E "E "`!*!)/R!'H6::mR+H+H&;)A ! ! !DK & 9G4+???08$W-    !  KE "E "E "E "E "E "E "E "E "E "E "E "E "E "E "E "E "E "sD0F1AF11F58F5c f|j5|j| ddddSjds|}|j}d| ddd}|r0d| dddnd}t|o||k}|dr^|s\|j |dsAt d||j|td |d |d jd |j|=tfd |jD}|sJ|jjdfd|jD|_|xjdz c_dddn #1swxYwYtd|dS)uTRemove 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``. Gated by the same operator opt-in policy ``register(override=True)`` enforces. Without this, a plugin could bypass that gate entirely by deregistering a tool it doesn't own and then calling plain ``register()`` over the now-empty slot — ``register()`` only runs its override check when an ``existing`` entry is present, so removing it first skips the check altogether. MCP toolsets (``mcp-*``) are exempt: dynamic tool discovery legitimately nukes-and-repaves its own tools on every refresh and has no plugin-override concept. Nr.rrrFzTool deregistration REJECTED: plugin %r attempted to remove tool %r (toolset %r) it does not own, without operator opt-in. Set plugins.entries.%s.allow_tool_override: true in config.yaml to allow it.rz cannot deregister tool z (toolset z0) without operator opt-in (allow_tool_override).c38K|]}|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)r}rwrgrLrrrrNjoinsplitrirxrArrr)rrypoprzitemsr~r) rWr4 caller_modowner caller_root owner_root same_plugintoolset_still_existsrs @r deregisterzToolRegistry.deregisters Z0 "0 "KOOD))E}0 "0 "0 "0 "0 "0 "0 "0 "=++F33 !0022 --em<<"hhz'7'7'<')D)D)F)F)))%    !  a0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "0 "b  ,d33333sH G H  HH 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..sSSS5:uSSSrz"Tool %s unavailable (check failed)r4NzCdynamic_schema_overrides for tool %s raised %s; using static schemafunction)typer)rr;rgrOrprArrMr4rUrrupdater@rBr?) rWrrresultrentries_by_namer4rschema_with_name overridesexcs rget_definitionszToolRegistry.get_definitions s/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.dispatch>sft$$ 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_size^sOt$$  /U0<. .  NAAAAAA((rcXtd|DS)z0Return sorted list of all registered tool names.c3$K|] }|jV dSr rrs rr#z2ToolRegistry.get_all_tool_names..js$GGUejGGGGGGrrrs rget_all_tool_nameszToolRegistry.get_all_tool_nameshs+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_schemals& 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_toolus$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_emojizs+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)rrs rget_tool_to_toolset_mapz$ToolRegistry.get_tool_to_toolset_maps"PPt7M7M7O7OPPPPrc\|\}}|||S)zCheck if a toolset has at least one exposable tool. Returns False (rather than crashing) when a per-tool check raises an unexpected exception (e.g. network error, missing import, bad config). )rr)rWrLr_s ris_toolset_availablez!ToolRegistry.is_toolset_availables/ ))++ 00'BBBrc\}tdD}fd|DS)z7Return ``{toolset: available_bool}`` for every toolset.ch|] }|j Sr^rrs rrz:ToolRegistry.check_toolset_requirements..s>>>U5=>>>rc>i|]}||Sr^)r)r!rLrrWs rrz;ToolRegistry.check_toolset_requirements..s;    T66wHH   r)rr;)rWrtoolsetsrs` @rcheck_toolset_requirementsz'ToolRegistry.check_toolset_requirementsse))++ >>g>>>??     #    rcdi}|\}}|D]}|j}||vr|||gdgd||<||d|j|jr;|jD]3}|||dvr!||d|4|S)z'Return toolset metadata for UI display.r) availabletoolsrR requirementsrr)rrLrr?r4rP)rWrrrrrnenvs rget_available_toolsetsz#ToolRegistry.get_available_toolsetss$&))++  A AEB!!!%!B!B2w!O!O#%$&    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 )rrLrgr4r?rP)rWrrtoolset_checksrrnr s 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 rcRg}g}|\}}td|DD]nfd|D}||r|<||r |djngd|Ddo||fS)zDReturn (available_toolsets, unavailable_info) like the old function.ch|] }|j Sr^rrs rrz7ToolRegistry.check_tool_availability..s===E%-===rc*g|]}|jk |Sr^r)r!rrns rr7z8ToolRegistry.check_tool_availability..s%LLLE 8K8K%8K8K8Krrcg|] }|j Sr^rrs rr7z8ToolRegistry.check_tool_availability..sAAAUejAAAr)r4r r)rr;rr?rP)rWrr unavailablerr ts_entriesrns @rcheck_tool_availabilityz$ToolRegistry.check_tool_availabilitys  ))++ ==W===>>  BLLLLWLLLJ00W==   $$$$"">H P 1 : :bAAjAAA$$ +%%r)NNFrrNNF)Fr )r).rYrZr[r\rXtuplerrJrr&rrrrirrrrrrrrrr staticmethodrrrintfloatr rrrrrrrrrrrrr rrr^rrrurus SS"""*JtIS(]8K'K!LJJJJ )4 ?))))i  0)c)hy&9)))) Md3iMMMM # $s)     "C "# "$ " " " "/S#X//// 4c4hsm4444KKdKW[KKKKXc]0 C   \ *"!48-1\"\"\"\" \"  \"  \"\"\"\"\" #U{T1\"#+\"\"\"\"\"|A4sA4tA4A4A4A4N//#c(/4/DQUJ////j4S4434444@)))cEkD6H)TWZ_T_))))HDIHHHH/s/x~////00#0000 CCcCCCCCCCC Qc3hQQQQCCCDCCCC DdO    S$Y($sDy/*&&T&&&&&&rruc ~dt|i}|r||tj|dS)zReturn a JSON error string for tool handlers. >>> 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_errorr sCs7|| $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=rloggingrr{rdpathlibrtypingrrrrr getLoggerrYrAASTrirr-r&rHrJrhrjr_rr__annotations__r`Lockrfrprsrur r r#r^rrr+sl     66666666666666  8 $ $ SW      G G$ G G G GhtnS (AAAAAAAAp#'68heTk 223888-/T(E/*///%y~''44d4444n$$$$}&}&}&}&}&}&}&}&B <>>& 2C 2 2 2 2 2 2 2 2 2 2 2 2r