o PL j`@s2UdZddlZddlZddlZddlZddlZddlZddlmZddl m Z m Z m Z m Z mZeeZdejdefddZd edefd d Zdd e ede efd dZGdddZdZiZe e eeeffed<eZde defddZ dddZ!GdddZ"e"Z#defddZ$ddefddZ%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)CallableDictListOptionalSetnodereturncCsVt|tjr t|jtjsdS|jj}t|tjo*|jdko*t|jtjo*|jj dkS)zHReturn True when *node* is a ``registry.register(...)`` call expression.Fregisterregistry) isinstanceastExprvalueCallfunc AttributeattrNameid)rrr2/home/kuhnn/.hermes/hermes-agent/tools/registry.py_is_registry_register_calls   r module_pathc CsPz|jdd}tj|t|d}Wn ttfyYdSwtdd|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)filenameFcss|]}t|VqdSN)r).0stmtrrr 6sz*_module_registers_tools..) read_textr parsestrOSError SyntaxErroranybody)rsourcetreerrr_module_registers_tools*s r) tools_dirc Cs|durt|nttj}ddt|dD}g}|D]'}z t|||Wqt yF}z t d||WYd}~qd}~ww|S)zLImport built-in self-registering tool modules and return their module names.NcSs*g|]}|jdvrt|rd|jqS)> __init__.py mcp_tool.py registry.pyztools.)namer)stem)rpathrrr <s  z*discover_builtin_tools..z*.pyz#Could not import tool module %s: %s) r__file__resolveparentsortedglob importlib import_moduleappend Exceptionloggerwarning)r* tools_path module_namesimportedmod_nameerrrdiscover_builtin_tools9s  rBc@s eZdZdZdZ dddZdS) ToolEntryz&Metadata for a single registered tool. r.toolsetschemahandlercheck_fn requires_envis_async descriptionemojimax_result_size_charsdynamic_schema_overridesNc CsF||_||_||_||_||_||_||_||_| |_| |_ | |_ dSrrD) selfr.rErFrGrHrIrJrKrLrMrNrrr__init__Vs zToolEntry.__init__)NN)__name__ __module__ __qualname____doc__ __slots__rPrrrrrCMs rCg>@_check_fn_cachefncCst}t$t|}|dur#|\}}||tkr#|WdSWdn1s-wYzt|}Wn tyDd}Ynwt||ft|<Wd|S1sYwY|S)zIReturn bool(fn()), TTL-cached across calls. Swallows exceptions as False.NF)time monotonic_check_fn_cache_lockrVget_CHECK_FN_TTL_SECONDSboolr:)rWnowcachedtsrrrr_check_fn_cached~s*    racCs2t tWddS1swYdS)zDrop all cached ``check_fn`` results. Call after config changes that affect tool availability (e.g. ``hermes tools enable``).N)rZrVclearrrrrinvalidate_check_fn_caches "rcc@seZdZdZddZdeeeee e fffddZ deefddZ dee e ffd d Z d e d e d BdefddZde deefddZdee fddZd e dee fddZde d e dd fddZdee e ffddZde dee fddZ    dMde d e d ed!e d"e d#ed$ed%e d&e d'eeBd Bd(e d)efd*d+Zde dd fd,d-ZdNd.ee d/edeefd0d1Zde d2ede fd3d4ZdOde d5eeBd BdeeBfd6d7Z dee fd8d9Z!de deefd:d;Z"de dee fdz.r5rsrlrrrget_registered_toolset_namesz)ToolRegistry.get_registered_toolset_namescstfdd|DS)z:Return sorted tool names registered under a given toolset.c3s |] }|jkr|jVqdSrrEr.rrrrrs z:ToolRegistry.get_tool_names_for_toolset..r)rOrErrrget_tool_names_for_toolsets z'ToolRegistry.get_tool_names_for_toolsetaliascCsl|j)|j|}|r||krtd|||||j|<|jd7_WddS1s/wYdS)z8Register an explicit alias for a canonical toolset name.z4Toolset alias collision: '%s' (%s) overwritten by %sruN)rjrgr[r;r<rk)rOrrEexistingrrrregister_toolset_aliass   "z#ToolRegistry.register_toolset_aliascCs4|j t|jWdS1swYdS)z=Return a snapshot of ``{alias: canonical_toolset}`` mappings.N)rjrorgrlrrrget_registered_toolset_aliasess$z+ToolRegistry.get_registered_toolset_aliasescCr{)z8Return the canonical toolset name for an alias, or None.N)rjrgr[)rOrrrrget_toolset_alias_targetr}z%ToolRegistry.get_toolset_alias_targetFrFrGrHrIrJrKrLrMrNoverridec Cs |jx|j|} | rF| j|krF| jdo|d}|r(td||| jn| r4td||| jntd||| j WddSt ||||||pOg||pW|dd| | | d |j|<|rl||j vrl||j |<|j d 7_ WddS1s~wYdS) 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.NrKrrDru) rjrer[rE startswithr;rxinfoerrorrCrfrk)rOr.rErFrGrHrIrJrKrLrMrNrrboth_mcprrrr sN  !  "zToolRegistry.registercs|jH|j|ddur WddStfdd|jD}|s=|jjdfdd|jD|_|j d7_ Wdn1sNwYt 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``. Nc3s|] }|jjkVqdSrrrrArrrr@s  z*ToolRegistry.deregister..cs i|] \}}|jkr||qSrr)rrtargetrrr Es  z+ToolRegistry.deregister..ruzDeregistered tool: %s) rjrepopr%rnrfrErgitemsrkr;rx)rOr.toolset_still_existsrrr deregister3s   zToolRegistry.deregister tool_namesquietc Csg}i}dd|D}t|D]i}||}|sq|jr9|j|vr+t|j||j<||js9|s8td|qi|jd|ji}|j durrz| } t | t rW| | Wnt yq} z td|| WYd} ~ nd} ~ ww|d|dq|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. cSsi|]}|j|qSrr.rrrrrasz0ToolRegistry.get_definitions..z"Tool %s unavailable (check failed)r.NzCdynamic_schema_overrides for tool %s raised %s; using static schemafunction)typer)rsr5r[rHrar;rxrFr.rNr roupdater:r<r9) rOrrresult check_resultsentries_by_namer.rschema_with_name overridesexcrrrget_definitionsQs<         zToolRegistry.get_definitionsargsc Ks||}|stdd|iSz|jr'ddlm}||j|fi|WS|j|fi|WStys}z7t d||dt |j d|}z ddlm }||} Wn tya|} Ynwtd| iWYd }~Sd }~ww) 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) r|jsondumpsrJ model_toolsrrGr:r; exceptionrrQr) rOr.rkwargsrrrArawr sanitizedrrrdispatchs(     zToolRegistry.dispatchdefaultcCs:||}|r|jdur|jS|dur|Sddlm}|S)zBReturn per-tool max result size, or *default* (or global default).Nr)DEFAULT_RESULT_SIZE_CHARS)r|rMtools.budget_configr)rOr.rrrrrrget_max_result_sizes  z ToolRegistry.get_max_result_sizecCr~)z0Return sorted list of all registered tool names.css|]}|jVqdSrrrrrrrsz2ToolRegistry.get_all_tool_names..rrlrrrget_all_tool_namesrzToolRegistry.get_all_tool_namescC||}|r |jSdS)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)r|rFrOr.rrrr get_schemas zToolRegistry.get_schemacCr)z.Return the toolset a tool belongs to, or None.N)r|rErrrrget_toolset_for_tools z!ToolRegistry.get_toolset_for_tool⚡cCs||}|r |jr |jS|S)z3Return the emoji for a tool, or *default* if unset.)r|rL)rOr.rrrrr get_emojis zToolRegistry.get_emojicCsdd|DS)z?Return ``{tool_name: toolset_name}`` for every registered tool.cSsi|]}|j|jqSr)r.rErrrrrsz8ToolRegistry.get_tool_to_toolset_map..)rsrlrrrget_tool_to_toolset_mapsz$ToolRegistry.get_tool_to_toolset_mapcCs>|j|j|}Wdn1swY|||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)rjrfr[rzryrrris_toolset_availables z!ToolRegistry.is_toolset_availablecs2\}tdd|D}fdd|DS)z7Return ``{toolset: available_bool}`` for every toolset.cSrrrrrrrrrz:ToolRegistry.check_toolset_requirements..c s i|] }|||qSr)rzr[)rrErOtoolset_checksrrrsz;ToolRegistry.check_toolset_requirements..)rpr5)rOentriestoolsetsrrrcheck_toolset_requirementss  z'ToolRegistry.check_toolset_requirementscCsi}|\}}|D]=}|j}||vr#||||gdgd||<||d|j|jrG|jD]}|||dvrF||d|q3q |S)z'Return toolset metadata for UI display.r) availabletoolsrK requirementsrr)rprErzr[r9r.rI)rOrrrrr`envrrrget_available_toolsetss&    z#ToolRegistry.get_available_toolsetscCsi}|\}}|D]@}|j}||vr |g||dgd||<|j||dvr3||d|j|jD]}|||dvrI||d|q6q |S)zABuild a TOOLSET_REQUIREMENTS-compatible dict for backward compat.N)r.env_varsrH setup_urlrrr)rprEr[r.r9rI)rOrrrrr`rrrrget_toolset_requirementss&   z%ToolRegistry.get_toolset_requirementscsg}g}t}|\}}|D]/}|j|vrq|||r-|q||jfdd|Ddq||fS)zDReturn (available_toolsets, unavailable_info) like the old function.csg|] }|jkr|jqSrrrr`rrr1sz8ToolRegistry.check_tool_availability..)r.rr)setrprEaddrzr[r9rI)rOrr unavailableseenrrrrrrcheck_tool_availability s"    z$ToolRegistry.check_tool_availability)NNFrrNNF)Fr)r)+rQrRrSrTrPtuplerrCrr"rrprsrvr]rzrr|rrrrrrormintfloatr rrrrrrrrrrrrrrrrrrrrdsx"       I 5$     rdcKs(dt|i}|r ||tj|ddS)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)messageextrarrrr tool_error3s  rcKs$|dur tj|ddStj|ddS)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)datarrrr tool_resultAs rr)r N)&rTr r7rloggingrhrXpathlibrtypingrrrrr getLoggerrQr;ASTr]rr)r"rBrCr\rVrr__annotations__LockrZrarcrdr rrrrrrs4   ,