,jCBUdZddlmZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl mZmZddlmZddlmZmZmZmZmZmZmZddlmZddlmZdd lmZdd l m!Z!m"Z"dXd Z# ddl$Z$n #e%$rdZ$YnwxYwej&e'Z(e j)dd*+dva,da-dYdZdZ.e.hdZ/de0d<dZ1dZ2d[dZ3d\dZ4d]d!Z5hd"Z6de0d#<eGd$d%Z7eGd&d'Z8Gd(d)Z9Gd*d+Z:da;d,e0d-<d^d.Zd`d6Z?dad7Z@dbd8ZAe jBZC dcddd=ZDded>ZE dfdgdJZFdYdhdKZGdLZHdidNZIdOZJdjdQZKdkdSZLdldUZMdmdWZNdS)nu Hermes Plugin System ==================== Discovers, loads, and manages plugins from four sources: 1. **Bundled plugins** – ``/plugins//`` (shipped with hermes-agent; ``memory/`` and ``context_engine/`` subdirs are excluded — they have their own discovery paths) 2. **User plugins** – ``~/.hermes/plugins//`` 3. **Project plugins** – ``./.hermes/plugins//`` (opt-in via ``HERMES_ENABLE_PROJECT_PLUGINS``) 4. **Pip plugins** – packages that expose the ``hermes_agent.plugins`` entry-point group. Later sources override earlier ones on name collision, so a user or project plugin with the same name as a bundled plugin replaces it. Each directory plugin must contain a ``plugin.yaml`` manifest **and** an ``__init__.py`` with a ``register(ctx)`` function. Lifecycle hooks --------------- Plugins may register callbacks for any of the hooks in ``VALID_HOOKS``. The agent core calls ``invoke_hook(name, **kwargs)`` at the appropriate points. Tool registration ----------------- ``PluginContext.register_tool()`` delegates to ``tools.registry.register()`` so plugin-defined tools appear alongside the built-in tools. ) annotationsN) dataclassfield)Path)AnyCallableDictListOptionalSetUnion)get_hermes_homeenv_var_enabled)cfg_get)OBSERVER_SCHEMA_VERSIONVALID_MIDDLEWAREreturnrctjd}|rt|Sttjjdz S)zLocate the bundled ``plugins/`` directory. Honours ``HERMES_BUNDLED_PLUGINS`` (set by the Nix wrapper / packaged installs) so read-only store paths are consulted first. Falls back to the in-repo path used during development. HERMES_BUNDLED_PLUGINSplugins)osgetenvr__file__resolveparent) env_overrides 7/home/ubuntu/.hermes/hermes-agent/hermes_cli/plugins.pyget_bundled_plugins_dirr7sM9566L"L!!! >> ! ! # # * 1I ==HERMES_PLUGINS_DEBUG>1onyestrueFforceboolNonec4|r;tjdddvatrt rdSt jtj }| t j | t j dt|t t j dt_datddS)zWhen HERMES_PLUGINS_DEBUG is on, tee plugin logs to stderr at DEBUG. Idempotent: only attaches the handler once per process unless ``force`` is passed. Does not touch the root logger or other Hermes loggers. r!r">r#r$r%r&Nz#[plugins] %(levelname)s %(message)sTuCHERMES_PLUGINS_DEBUG=1 — verbose plugin discovery logging enabled)rrstriplower_PLUGINS_DEBUG_DEBUG_HANDLER_INSTALLEDlogging StreamHandlersysstderrsetLevelDEBUG setFormatter Formatterlogger addHandler propagatedebug)r'handlers r_install_plugin_debug_handlerr<_s  #92>>DDFFLLNNS   5#CJ//G W]### *+PQQRRR g OOGM"""F# LLMr > pre_llm_call post_llm_call pre_tool_call subagent_stopon_session_endpost_tool_callsubagent_startpre_api_requeston_session_reseton_session_startpost_api_requestapi_request_erroron_session_finalizepre_approval_requestpre_gateway_dispatchtransform_llm_outputtransform_tool_resultpost_approval_responsetransform_terminal_outputzSet[str] VALID_HOOKSzhermes_agent.pluginshermes_pluginsnamestrc t|S)zbackendplatform exclusive standalonemodel-provider_VALID_PLUGIN_KINDSceZdZUdZded<dZded<dZded<dZded<ee Z d ed <ee Z d ed <ee Z d ed <dZ ded<dZded<dZded<dZded<dS)PluginManifestz0Parsed representation of a plugin.yaml manifest.rSrRr"version descriptionauthordefault_factoryz List[Union[str, Dict[str, Any]]] requires_env List[str]provides_toolsprovides_hookssourceN Optional[str]pathrlkindkey)__name__ __module__ __qualname____doc____annotations__rqrrrsrr^rvrxryrzr|r}r~r rrprps:: IIIGKF5:U45P5P5PLPPPP %d ; ; ;N;;;; %d ; ; ;N;;;;FD D CMMMMMMr rpceZdZUdZded<dZded<eeZded <eeZ ded <eeZ ded <eeZ ded <d Z ded<dZ ded<dS) LoadedPluginz)Runtime state for a single loaded plugin.rpmanifestNzOptional[types.ModuleType]modulertrwtools_registeredhooks_registeredmiddleware_registeredcommands_registeredFr(rdr{error)rrrrrrrr^rrrrrdrrr rrrs33)-F----"'%"="="====="'%"="="=====',uT'B'B'BBBBB%*U4%@%@%@@@@@GEr rceZdZdZdKdZedLd Z dMdNdZdOdPd"Z dQdRd&Z dSdTd(Z dUd+Z dVd,Z dVd-Z dVd.ZdVd/ZdVd0ZdVd1ZdVd2ZdVd3Z dWdXd:ZdYd=Zd d>dZdCZd[dEZd\dGZ d]d^dJZd S)_ PluginContextz=Facade given to plugins so they can register tools and hooks.rrpmanager'PluginManager'c0||_||_d|_dSN)r_manager_llm)selfrrs r__init__zPluginContext.__init__%s    r rrc||j/ddlm}|jjp |jj}|||_|jS)aReturn the plugin's :class:`agent.plugin_llm.PluginLlm` facade. Lets trusted plugins run host-owned chat or structured completions against the user's active model and auth without bringing their own provider keys. Override capability (model, agent id, auth profile) is fail-closed by default and gated through ``plugins.entries..llm.*`` config keys. See :mod:`agent.plugin_llm` for the full surface.Nr) PluginLlm) plugin_id)ragent.plugin_llmrrr~rR)rrrs rllmzPluginContext.llm-sN 9  2 2 2 2 2 2 )?T]-?I! I666DIyr NFr"rRrStoolsetschemarfr;rcheck_fnCallable | Nonerv list | Noneis_asyncr(rremojioverrider)c ddlm} | ||||||||| |  |jj|t d|jj || rdnddS)awRegister a tool in the global registry **and** track it as plugin-provided. Pass ``override=True`` to replace an existing built-in tool with the same name (e.g. swap the default ``browser_navigate`` for a custom CDP-backed implementation). Without it, attempting to register a name already claimed by a different toolset is rejected. rregistry) rRrrr;rrvrrrrrzPlugin %s registered tool: %s%sz (override)r"N) tools.registryrregisterr_plugin_tool_namesaddr7r:rrR) rrRrrr;rrvrrrrrrs r register_toolzPluginContext.register_tool@s( ,+++++%#   (,,T222 - M x&GmmR     r usercontentrolec|jj}|tddS|dkr|nd|d|}t |ddr|j|n|j|dS) aInject a message into the active conversation. If the agent is idle (waiting for user input), this starts a new turn. If the agent is running, this interrupts and injects the message. This enables plugins (e.g. remote control viewers, messaging bridges) to send messages into the conversation from external sources. Returns True if the message was queued successfully. Nz@inject_message: no CLI reference (not available in gateway mode)Fr[z] _agent_runningT)r_cli_refr7warninggetattr_interrupt_queueput_pending_input)rrrclimsgs rinject_messagezPluginContext.inject_messagejsm$ ; NN] ^ ^ ^5gg-B-B-B-B-B 3(% 0 0 (  $ $S ) ) ) )   " "3 ' ' 'tr helpsetup_fn handler_fnc||||||jjd|jj|<td|jj|dS)aRegister a CLI subcommand (e.g. ``hermes honcho ...``). The *setup_fn* receives an argparse subparser and should add any arguments/sub-subparsers. If *handler_fn* is provided it is set as the default dispatch function via ``set_defaults(func=...)``.)rRrrrrrpluginz$Plugin %s registered CLI command: %sN)rrRr _cli_commandsr7r:)rrRrrrrrs rregister_cli_commandz"PluginContext.register_cli_commandsV& $m( - -  #D)  ;T]=OQUVVVVVr args_hintc<|ddd}|s'td|jjdS ddlm }||(td|jj|dSn#t$rYnwxYw||pd |jj|pd d |j j |<t d |jj|dS) uRegister a slash command (e.g. ``/lcm``) available in CLI and gateway sessions. The handler signature is ``fn(raw_args: str) -> str | None``. It may also be an async callable — the gateway dispatch handles both. Unlike ``register_cli_command()`` (which creates ``hermes `` terminal commands), this registers in-session slash commands that users invoke during a conversation. ``args_hint`` is an optional short string (e.g. ``""`` or ``"dias:7 formato:json"``) used by gateway adapters to surface the command with an argument field — for example Discord's native slash command picker. Plugin commands without ``args_hint`` register as parameterless in Discord and still accept trailing text when invoked as free-form chat. Names conflicting with built-in commands are rejected with a warning. / -z;Plugin '%s' tried to register a command with an empty name.Nr)resolve_commandz^Plugin '%s' tried to register command '/%s' which conflicts with a built-in command. Skipping.zPlugin commandr")r;rrrrz!Plugin %s registered command: /%s)r,r+lstripreplacer7rrrRhermes_cli.commandsrr_r_plugin_commandsr:)rrRr;rrrcleanrs rregister_commandzPluginContext.register_commandsH2 ""$$++C0088cBB  NNM "    F  ; ; ; ; ; ;u%%19M&  2    D &:*:m(#/r0022 1 1  &u-  8$-:LeTTTTTs87B22 B?>B? tool_nameargsc ddlm}d|vr(|jj}|rt |ddnd}|||d<|j||fi|S)uDispatch a tool call through the registry, with parent agent context. This is the public interface for plugin slash commands that need to call tools like ``delegate_task`` without reaching into framework internals. The parent agent (if available) is resolved automatically — plugins never need to access the agent directly. Args: tool_name: Registry name of the tool (e.g. ``"delegate_task"``). args: Tool arguments dict (same as what the model would pass). **kwargs: Extra keyword args forwarded to the registry dispatch. Returns: JSON string from the tool handler (same format as model tool calls). rr parent_agentagentN)rrrrrdispatch)rrrkwargsrrrs r dispatch_toolzPluginContext.dispatch_toolsu ,+++++  ' '-(C36@GC$///DE ).~& x D;;F;;;r cT|jj'td|jjdSddlm}t||s'td|jjdS||j_t d|jj|jdS)a%Register a context engine to replace the built-in ContextCompressor. Only one context engine plugin is allowed. If a second plugin tries to register one, it is rejected with a warning. The engine must be an instance of ``agent.context_engine.ContextEngine``. NzyPlugin '%s' tried to register a context engine, but one is already registered. Only one context engine plugin is allowed.r) ContextEnginezbPlugin '%s' tried to register a context engine that does not inherit from ContextEngine. Ignoring.z)Plugin '%s' registered context engine: %s) r_context_enginer7rrrRagent.context_enginerr]info)renginers rregister_context_enginez%PluginContext.register_context_engines = ( 4 NNQ "    F666666&-00  NN8 "    F(. % 7 M       r cddlm}ddlm}t ||s't d|jjdS||t d|jj|jdS)a=Register an image generation backend. ``provider`` must be an instance of :class:`agent.image_gen_provider.ImageGenProvider`. The ``provider.name`` attribute is what ``image_gen.provider`` in ``config.yaml`` matches against when routing ``image_generate`` tool calls. r)ImageGenProviderregister_providerzjPlugin '%s' tried to register an image_gen provider that does not inherit from ImageGenProvider. Ignoring.Nz-Plugin '%s' registered image_gen provider: %s) agent.image_gen_providerragent.image_gen_registryrr]r7rrrRr)rproviderrrs rregister_image_gen_providerz)PluginContext.register_image_gen_providers >=====>>>>>>($455  NN? "    F(### ; M       r c ddlm}m}t||s'td|jjdS ||nU#ttf$rA}td|jjt|dd|Yd}~dSd}~wwxYwt d|jj|j|j dS) u$Register a dashboard authentication provider. ``provider`` must be an instance of :class:`hermes_cli.dashboard_auth.DashboardAuthProvider`. Used by the dashboard OAuth auth gate, which engages when the dashboard binds to a non-loopback host without ``--insecure``. Misbehaving providers (wrong type, duplicate name) are logged at WARNING and silently ignored — never raised — so a broken plugin cannot crash the host. Same convention as ``register_image_gen_provider``. r)DashboardAuthProviderrzsPlugin '%s' tried to register a dashboard-auth provider that does not inherit from DashboardAuthProvider. Ignoring.Nz=Plugin '%s' failed to register dashboard-auth provider %r: %srR?z7Plugin '%s' registered dashboard-auth provider: %s (%s)) hermes_cli.dashboard_authrrr]r7rrrR TypeError ValueErrorrr display_name)rrrres r register_dashboard_auth_providerz.PluginContext.register_dashboard_auth_provider1s        ($9::  NNN "    F   h ' ' ' ':&    NN "GHfc$B$BA    FFFFF    E M  x/D     s A B6BBcddlm}ddlm}t ||s't d|jjdS||t d|jj|jdS)a<Register a video generation backend. ``provider`` must be an instance of :class:`agent.video_gen_provider.VideoGenProvider`. The ``provider.name`` attribute is what ``video_gen.provider`` in ``config.yaml`` matches against when routing ``video_generate`` tool calls. r)VideoGenProviderrziPlugin '%s' tried to register a video_gen provider that does not inherit from VideoGenProvider. Ignoring.Nz-Plugin '%s' registered video_gen provider: %s) agent.video_gen_providerragent.video_gen_registryrr]r7rrrRr)rrr_register_video_providers rregister_video_gen_providerz)PluginContext.register_video_gen_providerYs >=====ZZZZZZ($455  NN? "    F  *** ; M       r cddlm}ddlm}t ||s't d|jjdS||t d|jj|jdS)aRegister a web search/extract backend. ``provider`` must be an instance of :class:`agent.web_search_provider.WebSearchProvider`. The ``provider.name`` attribute is what ``web.search_backend`` / ``web.extract_backend`` / ``web.backend`` in ``config.yaml`` matches against when routing ``web_search`` / ``web_extract`` tool calls. r)WebSearchProviderrzdPlugin '%s' tried to register a web provider that does not inherit from WebSearchProvider. Ignoring.Nz'Plugin '%s' registered web provider: %s) agent.web_search_providerragent.web_search_registryrr]r7rrrRr)rrr_register_web_providers rregister_web_search_providerz*PluginContext.register_web_search_providerts @?????YYYYYY($566  NN@ "    Fx((( 5 M       r cddlm}ddlm}t ||s't d|jjdS||t d|jj|jdS)uQRegister a cloud browser backend. ``provider`` must be an instance of :class:`agent.browser_provider.BrowserProvider`. The ``provider.name`` attribute is what ``browser.cloud_provider`` in ``config.yaml`` matches against when routing cloud-mode ``browser_*`` tool calls. Mirrors :meth:`register_web_search_provider` exactly — same registration shape, same gating, same logging. The browser subsystem's dispatcher (:func:`tools.browser_tool._get_cloud_provider`) consults the registry built up by these calls. r)BrowserProviderrzfPlugin '%s' tried to register a browser provider that does not inherit from BrowserProvider. Ignoring.Nz+Plugin '%s' registered browser provider: %s) agent.browser_providerragent.browser_registryrr]r7rrrRr)rrr_register_browser_providers rregister_browser_providerz'PluginContext.register_browser_providers ;:::::ZZZZZZ(O44  NN> "    F""8,,, 9 M       r cddlm}ddlm}t ||s't d|jjdS||t d|jj|jdS)u|Register a text-to-speech backend. ``provider`` must be an instance of :class:`agent.tts_provider.TTSProvider`. The ``provider.name`` attribute is what ``tts.provider`` in ``config.yaml`` matches against when routing ``text_to_speech`` tool calls — **but only when**: 1. ``provider.name`` is NOT a built-in TTS provider name (``edge``, ``openai``, ``elevenlabs``, …). Built-ins always win — the registry rejects shadowing names with a warning. 2. There is NO ``tts.providers.: type: command`` entry with the same name. Command-providers (PR #17843) win on name collision because config is more local than plugin install. Coexists with the command-provider registry rather than replacing it — see issue #30398 for the full design rationale. r) TTSProviderrz^Plugin '%s' tried to register a TTS provider that does not inherit from TTSProvider. Ignoring.Nz'Plugin '%s' registered TTS provider: %s) agent.tts_providerragent.tts_registryrr]r7rrrRr)rrr_register_tts_providers rregister_tts_providerz#PluginContext.register_tts_providers( 322222RRRRRR(K00  NN: "    Fx((( 5 M       r cddlm}ddlm}t ||s't d|jjdS||t d|jj|jdS)uRegister a speech-to-text backend. ``provider`` must be an instance of :class:`agent.transcription_provider.TranscriptionProvider`. The ``provider.name`` attribute is what ``stt.provider`` in ``config.yaml`` matches against when routing :func:`tools.transcription_tools.transcribe_audio` calls — **but only when**: 1. ``provider.name`` is NOT a built-in STT provider name (``local``, ``local_command``, ``groq``, ``openai``, ``mistral``, ``xai``). Built-ins always win — the registry rejects shadowing names with a warning. 2. There is NO ``stt.providers.: type: command`` entry with the same name. Command-providers win on name collision because config is more local than plugin install — same precedence rule as TTS. Coexists with the in-tree dispatcher and the STT command-provider registry rather than replacing them. The 6 built-in STT backends keep their native implementations in ``tools/transcription_tools.py``; this hook is for *new* Python engines (OpenRouter, SenseAudio, Gemini-STT, custom proprietary backends). r)TranscriptionProviderrzrPlugin '%s' tried to register a transcription provider that does not inherit from TranscriptionProvider. Ignoring.Nz1Plugin '%s' registered transcription provider: %s) agent.transcription_providerragent.transcription_registryrr]r7rrrRr)rrr_register_stt_providers rregister_transcription_providerz-PluginContext.register_transcription_providers4 GFFFFF\\\\\\($9::  NNI "    Fx((( ? M       r labeladapter_factoryvalidate_config required_env install_hint entry_kwargsc 0ddlm} m} |d|jj| d||||||pg|dd|} | | |jj |t d|jj|dS) u Register a gateway platform adapter. The adapter_factory receives a ``PlatformConfig`` and returns a ``BasePlatformAdapter`` subclass instance. The gateway calls ``check_fn()`` before instantiation to verify dependencies. Extra keyword arguments are forwarded to ``PlatformEntry`` (e.g. ``setup_fn``, ``emoji``, ``allowed_users_env``, ``platform_hint``). Unknown keys raise TypeError from the dataclass constructor. Example:: ctx.register_platform( name="irc", label="IRC", adapter_factory=lambda cfg: IRCAdapter(cfg), check_fn=lambda: True, emoji="💬", setup_fn=irc_interactive_setup, ) r)platform_registry PlatformEntry plugin_namer)rRr rrrrrrzz!Plugin %s registered platform: %sNr) gateway.platform_registryrr setdefaultrrRrr_plugin_platform_namesrr7r:) rrRr rrrrrrrrentrys rregister_platformzPluginContext.register_platforms@ ONNNNNNN t}/ABBB  ++%+%       ""5))) ,00666 / M       r action_idcallbackct|std|jjd|)t |t r1|std|jjd|jj |||jjft d|jj|dS)uRegister a Slack Block Kit action handler from a plugin. Hermes' Slack adapter wires registered handlers into its ``slack_bolt.AsyncApp`` at connect time. The callback is invoked when a user clicks a button (or interacts with another Block Kit action element) whose ``action_id`` matches. Callback signature follows the slack_bolt convention:: async def handler(ack, body, action) -> None: await ack() # required, within 3 seconds ... Args: action_id: Whatever ``slack_bolt.App.action()`` accepts — a literal ``action_id`` string, a compiled ``re.Pattern`` for matching multiple ids, or a constraint dict (e.g. ``{"action_id": "...", "block_id": "..."}``). callback: Async callable receiving ``(ack, body, action)``. Raises: ValueError: if ``callback`` is not callable, or ``action_id`` is empty/None. Example:: async def _on_approve(ack, body, action): await ack() # apply some workflow keyed on action["value"] ctx.register_slack_action_handler("inbox_sweep_approve", _on_approve) Plugin 'zH' tried to register a Slack action handler with a non-callable callback.NzC' tried to register a Slack action handler with an empty action_id.z-Plugin %s registered Slack action handler: %s) callablerrrRr]rSr+r_slack_action_handlersappendr7r:)rrrs rregister_slack_action_handlerz+PluginContext.register_slack_action_handler:sJ!! @4=-@@@   Is!;!; IOODUDU ;4=-;;;  ,33 $-"4 5     ; M       r )defaultsr~rr$Optional[Dict[str, Any]]c D|rt|tstd|jjd|t d|Ds td|jjd|dddlm}d|D}||vr0td|jjd |d |jjd |d |jj |}|Y| d|jjkr6td|jjd |d| dddddddid}|r| D] \} } | || < |||||jjd|jj |<t d|jj||d S)uRegister a plugin-defined auxiliary LLM task. Auxiliary tasks are LLM-backed side jobs (vision analysis, web extraction, compression, smart-approval, etc.) that route through ``auxiliary_client.py``. Each task has its own ``auxiliary.`` config block where users can pin a provider/model independent of the main chat model. Plugins use this to declare their own auxiliary tasks without touching core files. After registration, the task: - Appears in the ``hermes model → Configure auxiliary models`` picker - Has its provider/model/base_url/api_key bridged from config.yaml to ``AUXILIARY__*`` env vars at gateway startup - Gets default routing fields (provider="auto", model="", etc.) merged into loaded configs so ``cfg.get("auxiliary", {}).get(key)`` works Args: key: stable task key (snake_case). Used in config ``auxiliary.`` and env vars ``AUXILIARY__*``. Must not shadow a built-in task key (vision, compression, web_extract, approval, mcp, title_generation, skills_hub, curator). display_name: human-readable name shown in the picker. description: short one-line description shown next to the name. defaults: optional dict of default routing fields. Recognized keys: ``provider`` (default "auto"), ``model`` (default ""), ``base_url`` (default ""), ``api_key`` (default ""), ``timeout`` (default 60), ``extra_body`` (default {}), plus any task-specific extras (e.g. ``download_timeout``). Unknown keys are preserved verbatim — the plugin owns the schema for its own task. Raises: ValueError: if *key* is empty, contains invalid characters, or shadows a built-in auxiliary task key. Example: ctx.register_auxiliary_task( key="memory_retain_filter", display_name="Memory retain filter", description="hindsight pre-retain dedup/extract", defaults={"provider": "auto", "timeout": 30}, ) rz4' tried to register auxiliary task with invalid key c3JK|]}|p|dkVdS)_N)isalnum).0cs r z8PluginContext.register_auxiliary_task..s388q199;;*!s(888888r z' auxiliary task key z: must contain only alphanumeric characters and underscoresr) _AUX_TASKSch|]\}}}| Srr)r*k_name_descs r z8PluginContext.register_auxiliary_task..sDDDoaDDDr z!' cannot register auxiliary task uS — that key is reserved for a built-in task. Pick a plugin-namespaced key (e.g. 'r(z').Nru# — already registered by plugin ''autor"<)rmodelbase_urlapi_keytimeout extra_body)r~rrrr$rz,Plugin %s registered auxiliary task: %s (%s))r]rSrrrRallhermes_cli.mainr-r _aux_tasksreitemsr7r:) rr~rrrr$_BUILTIN_AUX_TASKS builtin_keysexistingmerged_defaultsr/vs rregister_auxiliary_taskz%PluginContext.register_auxiliary_taskvsh *S#.. ,4=-,,$',, 88C88888 M4=-MMCMMM  EDDDDDDD1CDDD ,  U4=-UUUU7;}7IUULOUUU =+//44  HLL$:$:dm>P$P$P.4=-....LL**...  + +   ' (( ' '1%&""(&'m( ) )   %  : M         r hook_namec b|tvrLtd|jj|dt t|jj |g |t d|jj|dS)zRegister a lifecycle hook callback. Unknown hook names produce a warning but are still stored so forward-compatible plugins don't break. z4Plugin '%s' registered unknown hook '%s' (valid: %s), zPlugin %s registered hook: %sN) rPr7rrrRjoinsortedr_hooksrr"r:)rrErs r register_hookzPluginContext.register_hooks K ' ' NN " &--..     '' 266==hGGG 4dm6H)TTTTTr r}c b|tvrLtd|jj|dt t|jj |g |t d|jj|dS)aSRegister a behavior-changing middleware callback. Middleware is separate from observer hooks: request middleware may rewrite the effective payload, and execution middleware may wrap the real callback. Unknown kinds are stored for forward compatibility but warned so plugin authors can catch typos. z:Plugin '%s' registered unknown middleware '%s' (valid: %s)rGz#Plugin %s registered middleware: %sN) rr7rrrRrHrIr _middlewarerr"r:)rr}rs rregister_middlewarez!PluginContext.register_middlewares ' ' ' NN " &!12233     !,,T266==hGGG :DM:'`` via ``skill_view()``. It does **not** enter the flat ``~/.hermes/skills/`` tree and is **not** listed in the system prompt's ```` index — plugin skills are opt-in explicit loads only. Raises: ValueError: if *name* contains ``':'`` or invalid characters. FileNotFoundError: if *path* does not exist. r) _NAMESPACE_RE:z Skill name 'zG' must not contain ':' (the namespace is derived from the plugin name 'z' automatically).zInvalid skill name 'z'. Must match [a-zA-Z0-9_-]+.zSKILL.md not found at )r|r bare_namerrzPlugin %s registered skill: %sN) agent.skill_utilsrPrrrRmatchexistsFileNotFoundErrorr_plugin_skillsr7r:)rrRr|rrrP qualifieds rregister_skillzPluginContext.register_skill s0$ 433333 $;;:t::M&:::   =..t44 JtJJJ {{}} E#$CT$C$CDD D})22D22 m(& 3 3  $Y/  , M       r )rrprr)rr)NNFr"r"F)rRrSrrSrrfr;rrrrvrrr(rrrSrrSrr(rr))r)rrSrrSrr()Nr") rRrSrrSrrrrrrrSrr))r"r") rRrSr;rrrrSrrSrr))rrSrrfrrSrr))NNr")rRrSr rSrrrrrrrrrrSrrrr))rrrrrr)) r~rSrrSrrrSr$r%rr))rErSrrrr))r}rSrrrr))r")rRrSr|rrrrSrr))rrrrrpropertyrrrrrrrrrrrrrr rr#rDrKrNrYrr rrr"sNGGX0%)$(& & & & & TB'+ WWWWW: 4U4U4U4U4Up<<<<>    @    6$ $ $ $ P    6    8    @" " " " L( ( ( ( d,0$(4 4 4 4 4 p6 6 6 6 D.2 m m m m m m ^UUUU&VVVV2 + + + + + + + r rceZdZdZd6dZd7d8dZd6d Z d9d:dZd;dZddZ d?d Z d?d!Z d@d&ZdAd'ZdBd)ZdCd*ZdDd,ZdEd.ZdFd1ZdGd4ZdHd5Zd S)I PluginManagerz;Central manager that discovers, loads, and invokes plugins.rr)ci|_i|_i|_t|_t|_i|_d|_i|_d|_ d|_ i|_ i|_ g|_ dS)NF)_pluginsrJrMrVrrrrr _discoveredrrWr=r!rs rrzPluginManager.__init__Bsx13 13 68,/EE03#.0#13!& 9;6846###r Fr'r(c|jr|sdS|r|j|j|j|j|j|j|j|j |j |j d|_ d|_ | dS#t$r d|_wxYw)aScan all plugin sources and load each plugin found. When ``force`` is true, clear cached discovery state first so config changes or newly-added bundled backends become visible in long-lived sessions without requiring a full agent restart. NTF)r`r_clearrJrMrrrrrWr=r!r_discover_and_load_inner BaseException)rr's rdiscover_and_loadzPluginManager.discover_and_load^sG   E  F  ( M   ! ! ! K        " " $ $ $  # ) ) + + +  ' - - / / /   $ $ & & &  ! ' ' ) ) )   % % ' ' ' O ! ! # # #  ' - - / / /#'D     ) ) + + + + +   $D   s D..Ec * g}t}td|||dhd}tdt |||||dz d}tdt |||t d z }td |||d }td t |||td rtj dz d z }td|||d}tdt |||ntd| } tdt | || t} t} i} |D]} | | | j p| j<| D]} | j p| j}|| vs | j| vr>t!| d}d|_||j|<td|\| jdkr>t!| d}d|_||j|<td|| jdkr7t!| d}||j|<td|| jdkr | jdvr|| | duo || vp| j| v}|sRt!| d}d ||_||j|<td!|w|| |r^td"t |jt1d#|jDdSdS)$u=The actual discovery sweep — see :meth:`discover_and_load`.zScanning bundled plugins: %sbundled>model-providersmemory platformscontext_engine)rz skip_namesz% bundled (top-level): %d manifest(s)rk)rzz# bundled/platforms: %d manifest(s)rzScanning user plugins: %srz user: %d manifest(s)HERMES_ENABLE_PROJECT_PLUGINSz.hermeszScanning project plugins: %sprojectz project: %d manifest(s)zHProject plugins disabled (set HERMES_ENABLE_PROJECT_PLUGINS=1 to enable)z entrypoints: %d manifest(s)F)rrdzdisabled via configzSkipping disabled plugin '%s'rku<exclusive plugin — activate via .provider configz8Skipping '%s' (exclusive, handled by category discovery)rmTz?Skipping '%s' (model-provider, handled by providers/ discovery)>rirjNzBnot enabled in config (run `hermes plugins enable {}` to activate)z&Skipping '%s' (not in plugins.enabled)z/Plugin discovery complete: %d found, %d enabledc3(K|] }|j dVdS)N)rd)r*ps rr,z9PluginManager._discover_and_load_inner..s)CC!CACCCCCCr )rr7r:_scan_directorylenextendrrUrcwd_scan_entry_pointsrarhr~rRvaluesrrr_r}rz _load_pluginformatrsum)r manifests repo_pluginsrhbundled_platformsuser_diruser_manifests project_dirproject_manifests ep_manifestsrZrdwinnersr lookup_keyloaded is_enableds rrdz&PluginManager._discover_and_load_inners*, /00  3\BBB&& SSS'    /B/BCCC((( 7 8 8 (**y09 >H5=GHL1HM 2 2((I (I (H!6JX%%()B)B%xGGG4 ,2 j) //plugin.yaml``. Key is ```` (e.g. ``disk-cleanup``). * **Category** — ``///plugin.yaml``, where the ```` directory itself has no ``plugin.yaml``. Key is ``/`` (e.g. ``image_gen/openai``). Depth is capped at two segments. *skip_names* is an optional allow-list of names to ignore at the top level (kept for back-compat; the current call sites no longer pass it now that categories are first-class). r"rrmprefixdepth)_scan_directory_level)rr|rzrms rrszPluginManager._scan_directorys,*)) &Z!*   r rrintc ^g}|s|St|D]}|s|dkr |r |j|vr)|dz }|s|dz }|r0|||||} | || |dkrtd||r |d|jn|j} | | ||d| |dz|S) aRecursive implementation of :meth:`_scan_directory`. ``prefix`` is the category path already accumulated ("" at root, "image_gen" one level in). ``depth`` is the recursion depth; we cap at 2 so ``/a/b/c/`` is ignored. rz plugin.yamlz plugin.ymlNrqz/Skipping %s (no plugin.yaml, depth cap reached)rr) is_dirrIiterdirrRrU_parse_manifestr"r7r:rur) rr|rzrmrrr|child manifest_filer sub_prefixs rrz#PluginManager._scan_directory_level3s{+- {{}}  DLLNN++! ! E<<>> zzjzUZ:-E-E!M1M '')) 5 % 4 ##%% //!5&&'$$X... zz NPUVVV5;KF11UZ111J   **#%!) +    r r plugin_dirOptional[PluginManifest]c ~ ttd|dStj|dpi}|d|j}|r |d|jn|}|dd}t|tsd}| } | tvrDtd ||d ttd} | dkrd|vr|d z } | r{ | d dd} d| vsd| vrd} td|n%d| vr!d| vrd} td|n#t $rYnwxYwtd||| ||t#|t|dd|dd|dd|dg|dg|dg|t|| | S#t $r.} td || t$!Yd} ~ dSd} ~ wwxYw)"zParse a single ``plugin.yaml`` into a :class:`PluginManifest`. Returns ``None`` on parse failure (logs a warning). Nu'PyYAML not installed – cannot load %szutf-8)encodingrRrr}rlzBPlugin %s: unknown kind '%s' (valid: %s); treating as 'standalone'rG __init__.pyr)errorsi register_memory_providerMemoryProviderrkzAPlugin %s: detected memory provider, treating as kind='exclusive'rProviderProfilermzEPlugin %s: detected model provider, treating as kind='model-provider'z9Parsed manifest: key=%s name=%s kind=%s source=%s path=%srqr"rrrsrvrxry) rRrqrrrsrvrxryrzr|r}r~zFailed to parse %s: %sexc_info)yamlr7r safe_load read_textrerRr]rSr+r,rnrHrIrUr:r_rpr-) rrrrzrdatarRr~raw_kindr} init_file source_textexcs rrzPluginManager._parse_manifestksN |H-XXXt>-"9"97"9"K"KLLRPRD88FJO44D39CV//jo///tCxx 55Hh,, ('>>##))++D...X499V4G-H-H#I#I$|##d(:(:&6 ##%%&/&9&9&9&K&KETE&R 6+EE/;>>#.D"LL!? # 0;>> 1[ @ @ $4D"LL!D # % LLKT4   "DHHY3344 HH]B77xx"--!XXnb99#xx(8"==#xx(8"==__        NN(-~    44444  sC"JDJ?A)F)(J) F63J5F66C J J<#J77J<cg} tj}t|dr|t }n=t |tr|t g}n d|D}|D]9}t|j d|j |j }| |:n2#t$r%}td|Yd}~nd}~wwxYw|S)z7Check ``importlib.metadata`` for pip-installed plugins.selectgroupc2g|]}|jtk|SrrENTRY_POINTS_GROUPr*eps r z4PluginManager._scan_entry_points..s%PPPB=O1O1OR1O1O1Or entrypoint)rRrzr|r~zEntry-point scan failed: %sN) importlibmetadata entry_pointshasattrrrr]rfrerprRvaluer"r_r7r:)rr|eps group_epsrrrs rrwz PluginManager._scan_entry_pointss%*,  =$1133CsH%% QJJ-?J@@ C&& QGG$6;; PP#PPP  + +)'    **** + = = = LL6 < < < < < < < < =sCC C7C22C7rrpc t t}tdjpjjjj jdvr}n }||_ t|dd}|)d|_ t djnt}tj djDd jD|| fd jD|_fd jD|_fd jD|_fd jD|_d|_tdt5|jt5|jt5|jt5|jt7fdjDnS#t:$rF}t=||_ t dj|t>Yd}~nd}~wwxYw|j jpj<dS)z?Import a plugin module and call its ``register(ctx)`` function.)rz1Loading plugin '%s' (source=%s, kind=%s, path=%s)>rrhrorNzno register() functionz&Plugin '%s' has no register() functionc4i|]\}}|t|Srrt)r*hcbss r z.PluginManager._load_plugin..s1'''$*AsAs3xx'''r c4i|]\}}|t|Srr)r*r}rs rrz.PluginManager._load_plugin.. s1%%%'0tSD#c((%%%r cg|]}|v| Srr)r*t _tools_befores rrz.PluginManager._load_plugin..s.+++ -----r chg|].\}}t||dk,|/Srrtre)r*rr_hook_counts_befores rrz.PluginManager._load_plugin..sI+++33xx"5"9"9!Q"?"??????r chg|].\}}t||dk,|/Srr)r*r}r_mw_counts_befores rrz.PluginManager._load_plugin..sI000!c3xx"3"7"7a"@"@@@@@@r cfg|]-}j|djk+|.S)r)rrerRr*r+rrs rrz.PluginManager._load_plugin..sF...,Q/33H==NNNNNr Tz[ registered: %d tool(s), %d hook(s), %d middleware, %d slash command(s), %d CLI command(s)c3nK|]/}j|djk+dV0dS)rrqN)rrerRrs rr,z-PluginManager._load_plugin..'sR-a044X>>(-OOOOOOr zFailed to load plugin '%s': %sr)!rr7r:r~rRrzr}r|_load_directory_module_load_entrypoint_modulerrrrrrVrrJr>rMrrrrrrdrtr{rr_rSr-r_) rrrr register_fnctxrrrrs `` @@@rryzPluginManager._load_pluginsHx000 ? L )HM8?HM8=   B "@@@44X>>55h??"FM"&*d;;K"7 GWWWW#Hd33!$D$; < < ''.2k.?.?.A.A'''#%%484D4J4J4L4L%%%! C   ++++#6+++'++++"&+"3"3"5"5+++' 0000%)%5%;%;%=%=000, .....#4...*"& q/00/00455233#'#5      s88FL NN0 s^          8> hl3hm444sG>I J``. The module slug is derived from ``manifest.key`` so category-namespaced plugins (``image_gen/openai``) import as ``hermes_plugins.image_gen__openai`` without colliding with any future ``tts/openai``. rzNo __init__.py in r__rr(.)submodule_search_locationsNzCannot create module spec for )rr|rUrV _NS_PARENTr1modulestypes ModuleType__path__ __package__r~rRrrutilspec_from_file_locationrSloader ImportErrormodule_from_spec exec_module) rrrrns_pkgr~slug module_namespecrs rrz$PluginManager._load_directory_module6sn(-(( . !! G#$E$E$EFF F S[ ( (%j11F FO!+F &,CK #l+hm{{3%%--c377#,,d,, ~55  (+J'86   <4;.JyJJKK K0066(z??+#) K  ''' r ctj}t|dr|t }n=t |tr|t g}n d|D}|D](}|j |j kr| cS)td|j dt d)z:Load a pip-installed plugin via its entry-point reference.rrc2g|]}|jtk|Srrrs rrz9PluginManager._load_entrypoint_module..ds%LLLRX9K-K-K-K-K-Kr z Entry point 'z' not found in group 'r3) rrrrrrr]rfrerRloadr)rrrrrs rrz%PluginManager._load_entrypoint_module\s --// 3 ! ! M ); <r"rrRr~r}rqrrrzrdrtrrrrr)rresultr~rs r list_pluginszPluginManager.list_pluginss')!$-"5"5"7"788  KC MM"O0!?.F&/2F"O0%6#)?#>$o4%~ !899 !899"%f&B"C"C #F$> ? ?#\        r qualified_nameOptional[Path]cN|j|}|r|dndS)z>Return the ``Path`` to a plugin skill's SKILL.md, or ``None``.r|N)rWre)rrrs rfind_plugin_skillzPluginManager.find_plugin_skills+#''77 %/uV}}4/r rrwcr|dtfd|jDS)zCReturn sorted bare names of all skills registered by *plugin_name*.rQc3XK|]$\}}||dV%dS)rRN) startswith)r*qnrrs rr,z3PluginManager.list_plugin_skills..sQ  A}}V$$ kN      r )rIrWr>)rrrs @rlist_plugin_skillsz PluginManager.list_plugin_skillssX"""    ,2244      r c<|j|ddS)z>Remove a stale registry entry (silently ignores missing keys).N)rWpop)rrs rremove_plugin_skillz!PluginManager.remove_plugin_skills! 55555r rZFr'r(rr)r)r|rrzrSrmrrr) r|rrzrSrmrrrSrrrr) rrrrrzrSrrSrr)rr)rrprr))rrprrrErSrrrrrErSrr(r}rSrr(r}rSrrrrrrrr)rrSrr)rrSrrw)rrSrr))rrrrrrfrdrsrrrwryrrrrrrrrrr rrr rr]r]?sEE66668     DTTTT|*.      26666pYYYY~L>L>L>\$$$$L    ,####J000000006 1 1 1 1 40000     666666r r]zOptional[PluginManager]_plugin_managerc:ttatS)z>Return (and lazily create) the global PluginManager singleton.)rr]rr rget_plugin_managerrs'// r cJt|dS)zDiscover and load all plugins. Default behavior is idempotent. Pass ``force=True`` to rescan plugin manifests and reload state in the current process. r'Nrrfrs rdiscover_pluginsrs' ***77777r rErrrc 6tj|fi|S)z|Invoke a lifecycle hook on all loaded plugins. Returns a list of non-``None`` return values from plugin callbacks. )rr)rErs rrrs& ,    +I @ @ @ @@r r}c 6tj|fi|S)zyInvoke registered middleware callbacks. Returns a list of non-``None`` return values from middleware callbacks. )rr)r}rs rrrs& 2    1$ A A& A AAr ct}t|dd}t|rt||Stt|di|S)zBReturn True when middleware callbacks are registered for ``kind``.rNrM)rrr r(re)r}rmethods rrrsm ""G W. 5 5F"FF4LL!!! 3377== > >>r cDt|S)z1Return True when a hook has registered callbacks.)rr)rEs rrr(s    ( ( 3 33r >Tool '{tool_name}' denied: not in this thread's tool whitelistallowedr deny_msg_fmtc6|t_|t_dSr)_thread_tool_whitelistr&fmt)r&r's rset_thread_tool_whitelistr+0s&-"!-r cdt_dSr)r)r&rr rclear_thread_tool_whitelistr-8s%)"""r rrr%task_id session_id tool_call_idturn_idapi_request_idmiddleware_traceOptional[List[Dict[str, Any]]]r{c ttdd}|0||vr,ttdd} | |Std|t |t r|ni|||||t |pg } | D]b} t | t s| dd kr2| d } t | tr| r| cScdS) aCheck ``pre_tool_call`` hooks for a blocking directive. Plugins that need to enforce policy (rate limiting, security restrictions, approval workflows) can return:: {"action": "block", "message": "Reason the tool was blocked"} from their ``pre_tool_call`` callback. The first valid block directive wins. Invalid or irrelevant hook return values are silently ignored so existing observer-only hooks are unaffected. r&Nr*zTool '{tool_name}' denied)rr?)rrr.r/r0r1r2r3actionblockmessage) rr)rzrr]rfr^rerS) rrr.r/r0r1r2r3r&r* hook_resultsrr8s rget_pre_tool_call_block_messager:<s*,i>>Gy77,e5PQQzzIz...d++ 3TT!%.4"55   L&$''   ::h  7 * * **Y'' gs # #  NNN 4r cNt}|||S)zReturn the global manager after ensuring plugin discovery has run. Pass ``force=True`` to rescan in the current process. rr)r'rs r_ensure_plugins_discoveredr<ns+ !""G E*** Nr c(tjS)z5Return the plugin-registered context engine, or None.)r<rrr rget_plugin_context_enginer>xs % ' ' 77r Optional[Callable]cftj|}|r|dndS)zFReturn the handler for a plugin-registered slash command, or ``None``.r;N)r<rre)rRrs rget_plugin_command_handlerrA}s3 & ( ( 9 = =d C CE$ .5  $.r g>@rctjsS tjn$#t$rtjcYSwxYwiit jd fd }t j|dd}|  tstdtd d d vrd  d S)aResolve a plugin command return value, awaiting async handlers when needed. Sync CLI/TUI dispatch sites call plugin handlers from plain functions. If a handler is async, await it directly when no loop is running; if we're already inside an active loop, run it in a helper thread with its own loop so the caller still gets a concrete result synchronously. The threaded path is bounded by a 30s timeout so a hung async handler cannot wedge the terminal indefinitely. rr)c tjd<n#t$r}|d<Yd}~nd}~wwxYwdS#wxYw)Nrr)asynciorunrerV)rdonefailureoutcomers r_runnerz.resolve_plugin_command_result.._runnersv &{622GG   ! ! ! GENNNNNN ! HHJJJJJDHHJJJJs%A 4/A 4A A#zhermes-plugin-command-awaitT)targetrRdaemon)r9z5Plugin command async handler did not complete within z.0fsrrrZ)inspect isawaitablerDget_running_loop RuntimeErrorrE threadingEventThreadstartwait"_PLUGIN_COMMAND_AWAIT_TIMEOUT_SECS TimeoutErrorre)rrIthreadrFrGrHs` @@@rresolve_plugin_command_resultrYsK  v & & # """" ###{6"""""#!G(*G ?  D  *F  LLNNN 99?9 @ @  91 8 9 9 9    en ;;w  s0AADict[str, dict]c(tjS)uReturn the full plugin commands dict (name → {handler, description, plugin}). Triggers idempotent plugin discovery so callers can use plugin commands before any explicit discover_plugins() call. )r<rrr rget_plugin_commandsr\s & ' ' 88r rc`tfdtjDS)aReturn all plugin-registered auxiliary tasks as a stable-ordered list. Each entry is the registration dict from :meth:`PluginContext.register_auxiliary_task`: ``{key, display_name, description, defaults, plugin}``. Triggers idempotent plugin discovery so callers can read the registry before any explicit ``discover_plugins()`` call. Sorted by ``key`` for deterministic ordering in pickers and tests. c*g|]}j|Sr)r=)r*r/rs rrz.get_plugin_auxiliary_tasks..s! F F FaG q ! F F Fr )r<rIr=)rs@rget_plugin_auxiliary_tasksr_s5)**G F F F F6'2D+E+E F F FFr rcDt}|jsgS ddlm}n#t$rgcYSwxYwi}i}|jD]O}||}|s|j}||g|j P|j D]J\}}|j D]=}||}|r$|j|vr||j|>Kg} t|D]} || } d| dd} | r| jjr | jj} n(dt|| } | | | | f| S)zReturn plugin toolsets as ``(key, label, description)`` tuples. Used by the ``hermes tools`` TUI so plugin-provided toolsets appear alongside the built-in ones and can be toggled on/off per platform. rru🔌 r(rrG)rrrrr_ get_entryrrr"rRr_r>rrIrertitlerrrrH)rr toolset_toolstoolset_pluginrrtsr0rrts_keyrr descs rget_plugin_toolsetsrhs !""G  % +++++++  +-M.0N/<< ""9--   ]  R((// ;;;;!)//11AA v0 A AI&&y11E A-77))%-@@@ A F''--##F++:sC006688::  rArVrYr\r_rhrr rrtsB#"""""  ((((((((BBBBBBBBBBBBBBBBBB,,,,,,!!!!!!%%%%%%KKKKKKKK > > > >KKKK DDD  8 $ $"1266<<>>DDFFK!6 *** ****X,  !!!!     D!e d ddddd !!!!!!! !H            "V  V  V  V  V  V  V  V  zu 6u 6u 6u 6u 6u 6u 6u 6x,0////88888AAAABBBB????4444 )** Y.....****7;/////d888 //// &*"+ + + + \9999 G G G G******s-A22A<;A<