[jqUdZddlZddlZddlZddlZddlZddlZddlZddlm 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 0/home/ice/.hermes/hermes-agent/tools/registry.py_is_registry_register_callrs dCH % %Z CH-M-Mu :?D4'' ( I # ( tz38 , , ( JMZ '  module_pathc |d}n#t$rYdSwxYwd|vsd|vrdS tj|t |}n#t $rYdSwxYwt d|jDS)uReturn 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. A cheap text prefilter avoids the ``ast.parse`` cost for files that do not mention both ``registry`` and ``register`` — a necessary condition for a top-level ``registry.register()`` call to exist. zutf-8)encodingFr r )filenamec34K|]}t|VdSN)r).0stmts r z*_module_registers_tools..@s+FFD)$//FFFFFFr) read_textOSErrorrparsestr SyntaxErroranybody)rsourcetrees r_module_registers_toolsr-+s&&&88 uu:V#;#;uy#k*:*:;;; uu FFDIFFF F FFs ''#A A'&A' 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..FsK  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_toolsrHCs$-$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__`s^      (  & %:")A%%%r)NN)__name__ __module__ __qualname____doc__ __slots__rXrrrJrJWsB00IGKAAAAAArrJg>@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_entrys 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_alias"s 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_target3s 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_policy<s 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_ofEs %))*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_module]sU 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.registerms.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_definitionss/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-cxt|tr|St|trA|ddur*t|dtr|St |j}td||tj d|d||dd S) a|Enforce the result shapes supported by the agent tool pipeline. Normal tool results are strings. The sole structured exception is the multimodal envelope consumed by the agent executor. Returning every other value as a string error keeps logging, hooks, budgeting, and persistence from receiving values they cannot safely slice or size. _multimodalTcontentz4Tool %s handler returned unsupported result type: %sz/Tool handler returned unsupported result type: tool_result_contract)r error_typetool result_typeF ensure_ascii) rr'rrgrrrYrArjsondumps)r4rrs r_normalize_handler_resultz&ToolRegistry._normalize_handler_resultGs fc " " M vt $ $  =))T116::i00$772M6ll+  B     zT{TT0&     rargsc ||}|stjdd|iS |jrddlm}||j|fi|}n|j|fi|}|||S#t$r{}t d||dt|j d|} ddlm } | |} n#t$r|} YnwxYwtjd| icYd }~Sd }~wwxYw) a_Execute a tool handler by name. * Async handlers are bridged automatically via ``_run_async()``. * Handler results are normalized to a string or supported multimodal envelope before leaving the registry. * 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)rrrrQ model_toolsrrNrr@rA exceptionrrYr) rWr4rkwargsrrrrGrawr sanitizeds rdispatchzToolRegistry.dispatchfs{t$$ B:w(?(?(?@AA A 4~ 7222222#MEM$$A$A&$A$ABB&t66v6611$?? ? 4 4 4   94 C C CDDGG,<CCCCC <<<<<<0055      :w 233 3 3 3 3 3 3 4sBAA;; D6C;<C C; CC;CC;5D;Ddefaultcd||}|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$GGUejGGGGGGrrrs 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)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)rWr rrrrnenvs 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_checksrrnrs 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)r4rr)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 rrrrrrrrrrrr rrrr r^rrrurusKSS"""*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////j\<4S443:4444H)))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}' rFr)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_r!r$__annotations__r`Lockrfrprsrur r(r+r^rrr3sl     66666666666666  8 $ $ SW     GG$GGGG0htnS (AAAAAAAAp#'68heTk 223888-/T(E/*///%y~''44d4444n$$$$`&`&`&`&`&`&`&`&H <>>& 2C 2 2 2 2 2 2 2 2 2 2 2 2r