yjY UdZddlmZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZmZddlmZddlmZmZmZmZmZmZmZmZddlmZddlmZm Z dd l!m"Z"dd l#m$Z$m%Z%dtd Z& ddl'Z'n #e($rdZ'YnwxYwGdde)Z*e j+e,Z-e j.dd/0dva1da2dudvdZ3e3hdZ4de5d<dZ6dZ7dwdZ8dxd!Z9dyd#Z:hd$Z;de5d%<dzd'ZeGd-d.Z?Gd/d0Z@Gd1d2ZAdaBd3e5d4<d|d5ZCd}d8ZDdudvd9ZEd~d>ZFdd@ZGddAZHddBZIe jJZKedCDGdEdFZL dddKZMddLZN dddWZO dddYZP ddd[ZQ ddd\ZRdddddddd]ddfZSduddgZTdhZUddjZVdkZWddmZXddoZYddqZZddsZ[dS)u 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)AnyCallableDictListMappingOptionalSetUnion)get_hermes_home)env_var_enabledfast_safe_load)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 8/home/ragecks/.hermes/hermes-agent/hermes_cli/plugins.pyget_bundled_plugins_dirr 8sM9566L"L!!! >> ! ! # # * 1I ==ceZdZdZdS)PluginToolOverrideErrorzRaised when a plugin attempts to override a built-in tool without operator opt-in via ``plugins.entries..allow_tool_override``. N)__name__ __module__ __qualname____doc__r!rr#r#Jsr!r#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_handlerrDgs  #92>>DDFFLLNNS   5#CJ//G W]### *+PQQRRR g OOGM"""F# LLMr!> pre_verify 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_skill_lifecyclekanban_task_blockedkanban_task_claimedon_session_finalizepre_approval_requestpre_gateway_dispatchtransform_llm_outputkanban_task_completedtransform_tool_resultpost_approval_responsetransform_terminal_outputzSet[str] VALID_HOOKSzhermes_agent.pluginshermes_pluginsnamestrc t|S)zbackendplatform exclusive standalonemodel-provider_VALID_PLUGIN_KINDSkeyc$dd|D}|dpd}tj|ddd}d|d |S) zGReturn a readable, collision-resistant namespace for a portable plugin.r*c3vK|]4}|r|s|dvr|ndV5dS)z_--N)isasciiisalnum).0chs r z,_portable_skill_namespace..s\ jjllD Dd r!z-_pluginutf-8Nz agent-plugin-r)joinr4r3hashlibsha256encode hexdigest)r|slugdigests r_portable_skill_namespacers 77))++  D ::d   'xD ^CJJw// 0 0 : : < .+sU  yy e        r!)r_emailurlNr*)rjr rr`)rs`r_display_authorr(sg%!! yy    1      22CJJ.r!ceZdZUdZded<dZded<dZded<dZded<ee Z d ed <ee Z d ed <ee Z d ed <dZ ded<dZded<dZded<dZded<dZded<dZded<dS)PluginManifestz0Parsed representation of a plugin.yaml manifest.r`r_r*version descriptionauthordefault_factoryz List[Union[str, Dict[str, Any]]] requires_env List[str]provides_toolsprovides_hookssourceN Optional[str]pathrykindr|Fr0portableskill_namespace)r$r%r&r'__annotations__rrrrrkrrrrrrr|rrr(r!rrr3s:: IIIGKF5:U45P5P5PLPPPP %d ; ; ;N;;;; %d ; ; ;N;;;;FD D CMMMMHOr!rceZdZUdZded<dZded<eeZded <eeZ ded <eeZ ded <eeZ ded <d Z ded<dZ ded<d Zded<dS) LoadedPluginz)Runtime state for a single loaded plugin.rmanifestNzOptional[types.ModuleType]modulerrtools_registeredhooks_registeredmiddleware_registeredcommands_registeredFr0rqrerrordeferred)r$r%r&r'rrrrkrrrrrqrrr(r!rrrZs33)-F----"'%"="="====="'%"="="=====',uT'B'B'BBBBB%*U4%@%@%@@@@@GEHr!rc:eZdZdZdQdZedRd ZedRd ZedSd Z dTdUd Z dVd"Z dWdXd&Z dYdZd*Z d[d\d,Z d]d.Zd^d/Zd^d0Zd^d1Zd^d2Zd^d3Zd^d4Zd^d5Zd^d6Zd^d7Z d_d`d>ZdadAZd dBdbdGZdcdIZdddKZ dedfdPZd S)g PluginContextz=Facade given to plugins so they can register tools and hooks.rrmanager'PluginManager'c>||_||_d|_d|_dSr)r_manager_llm_subagent_lifecycle)selfrrs r__init__zPluginContext.__init__ss%    (,   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|r_)rrrs rllmzPluginContext.llm|sN 9  2 2 2 2 2 2 )?T]-?I! I666DIyr!cN|jddlm}m}|||_|jS)a(Return the public, plugin-safe subagent lifecycle service. The service only resolves the active host-owned parent agent when a child is launched. Plugins receive serializable handles and immutable snapshots; they never receive a live agent or a private registry. Nr)SubagentLifecycleServiceget_active_subagent_parent)ragent.subagent_lifecyclerr)rrrs rsubagent_lifecyclez PluginContext.subagent_lifecycles[  # +        (@'?*((D $''r!r`cF ddlm}|S#t$rYdSwxYw)uXReturn the active Hermes profile name (e.g. ``"default"``). Derived from ``HERMES_HOME`` via :func:`hermes_cli.profiles.get_active_profile_name`, so it works in every execution context — interactive CLI, gateway, and kanban-spawned worker sessions alike — without depending on ``_cli_ref`` (which is ``None`` outside an interactive CLI run). Returns ``"default"`` for the default profile, the profile id when running under ``~/.hermes/profiles/``, or ``"custom"`` when ``HERMES_HOME`` points somewhere unrecognized. r)get_active_profile_namerh)hermes_cli.profilesrrl)rrs r profile_namezPluginContext.profile_namesJ  C C C C C C**,, ,   99 s   NFr*r_toolsetschemarsrCrcheck_fnCallable | Noner list | Noneis_asyncr0remojioverrider1c | rP||s;|jjp |jj} t d|jjd|d| dddlm} | ||||||||| |  |jj |t d|jj|| rd nd d S) uSRegister 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. ``override=True`` against a built-in tool requires the operator to opt in via ``plugins.entries..allow_tool_override: true`` in config.yaml — mirrors the trust gate pattern used for ``ctx.llm`` provider/model overrides (#23194). Without that gate, any enabled plugin could silently replace a privileged built-in like ``shell_exec`` or ``write_file`` and exfiltrate everything the model invokes through it. zPlugin z cannot override built-in tool z. Set plugins.entries.zY.allow_tool_override: true in config.yaml to allow this plugin to replace built-in tools.rregistry) r_rrrCrrrrrrzPlugin %s registered tool: %s%sz (override)r*N) _tool_override_allowedrr|r_r#tools.registryrregisterr_plugin_tool_namesaddr?rB) rr_rrrCrrrrrrrrs r register_toolzPluginContext.register_tools&8  D77==  )?T]-?I)R$-,RRRR#,RRR  ,+++++%#   (,,T222 - M x&GmmR     r! tool_namect|jddpd}|dkrdS ddlm}|pi}n#t$rYdSwxYw|jjp |jj}|dpid pi}||pi}t|d dS) uReturn True if this plugin is configured to override built-in tools. Bundled plugins (shipped with Hermes core) are trusted by default — an override there is a deliberate maintainer choice, not a third-party plugin trying to elevate privilege. For every other source, require ``allow_tool_override: true`` under ``plugins.entries.`` in config.yaml. rr*bundledTrreFrentriesallow_tool_override) getattrrrirfrlr|r_rrr0)rrrrfcfgrrentrys rrz$PluginContext._tool_override_alloweds"55; Y  4  5 5 5 5 5 5+--%2CC   55 M%;); 779%%+00;;Ar I&&,"EII3U;;<< 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. / rz;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*)rCrrrz!Plugin %s registered command: /%s)r4r3lstripreplacer?rrr_hermes_cli.commandsrrlr_plugin_commandsrB)rr_rCrrcleanrs rregister_commandzPluginContext.register_commandAsH2 ""$$++C0088cBB  NNM "    F  ; ; ; ; ; ;u%%19M&  2    D &:*:m(#/r0022 1 1  &u-  8$-:LeTTTTTs87B22 B?>B?argsc 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_toolysu ,+++++  ' '-(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_enginer?rrr_agent.context_enginer rjinfo)renginer s 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_registryrrjr?rrr_r)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: %sr_?z7Plugin '%s' registered dashboard-auth provider: %s (%s)) hermes_cli.dashboard_authrrrjr?rrr_ TypeError ValueErrorrr display_name)rrrres r register_dashboard_auth_providerz.PluginContext.register_dashboard_auth_providers        ($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_providerr%agent.video_gen_registryrrjr?rrr_r)rrr%_register_video_providers rregister_video_gen_providerz)PluginContext.register_video_gen_providers >=====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_providerr+agent.web_search_registryrrjr?rrr_r)rrr+_register_web_providers rregister_web_search_providerz*PluginContext.register_web_search_providers @?????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_providerr1agent.browser_registryrrjr?rrr_r)rrr1_register_browser_providers rregister_browser_providerz'PluginContext.register_browser_provider2s ;:::::ZZZZZZ(O44  NN> "    F""8,,, 9 M       r!cddlm}ddlm}t ||s't d|jjdS||r-t d|jj|jdSdS)uRegister an external secret-manager backend. ``source`` must be an instance of :class:`agent.secret_sources.base.SecretSource`. Registered sources run during ``load_hermes_dotenv()`` startup — after ``~/.hermes/.env`` loads, before Hermes reads credentials — when their ``secrets.`` config section is enabled. The orchestrator (``agent.secret_sources.registry.apply_all``) owns ordering, mapped-vs-bulk precedence, conflict warnings, and provenance; the source only fetches. NOTE ON TIMING: plugin discovery happens later in startup than the first ``load_hermes_dotenv()`` call, so a plugin-registered source is not consulted by the initial env load of the process that discovers it. It IS consulted by every subsequently spawned Hermes process (gateway children, cron sessions, subagents), and immediately after a ``reset_secret_source_cache()`` re-pull. Plugin sources are therefore best for supplying credentials to the running fleet; the bundled sources cover first-process bootstrap. Contract requirements (rejected with a warning otherwise): inherit from ``SecretSource``, ``api_version`` matching ``SECRET_SOURCE_API_VERSION``, lowercase unique ``name``, ``shape`` of ``"mapped"`` or ``"bulk"``, unique ``scheme`` (when set), and a ``fetch()`` that never raises and never prompts. See the base-module docstring for the full contract. r) SecretSource)register_sourcez`Plugin '%s' tried to register a secret source that does not inherit from SecretSource. Ignoring.Nz(Plugin '%s' registered secret source: %s) agent.secret_sources.baser7agent.secret_sources.registryr8rjr?rrr_r)rrr7r8s rregister_secret_sourcez$PluginContext.register_secret_sourceRs: ;:::::AAAAAA&,//  NN; "    F ?6 " "  KK: "FK       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_providerr=agent.tts_registryrrjr?rrr_r)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_providerrCagent.transcription_registryrrjr?rrr_r)rrrC_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) uRegister a gateway platform adapter. The adapter_factory receives a ``PlatformConfig`` and returns a ``BasePlatformAdapter`` subclass instance. ``check_fn`` is a PASSIVE dependency probe — "are deps importable right now?". It must never install anything: status displays and config loading call it freely. If your platform's SDK is lazy-installable, pass the ACTIVE installer separately as ``ensure_deps_fn`` (forwarded via ``entry_kwargs``); the gateway calls it from ``create_adapter()`` when ``check_fn`` is False, right before connecting the platform. Extra keyword arguments are forwarded to ``PlatformEntry`` (e.g. ``setup_fn``, ``emoji``, ``allowed_users_env``, ``platform_hint``, ``ensure_deps_fn``). 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)r_rHrIrrJrKrLrz!Plugin %s registered platform: %sNr() gateway.platform_registryrOrP setdefaultrr_rr_plugin_platform_namesrr?rB) rr_rHrIrrJrKrLrMrOrPrs rregister_platformzPluginContext.register_platformsP 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) callabler rr_rjr`r3r_slack_action_handlersappendr?rB)rrVrWs rregister_slack_action_handlerz+PluginContext.register_slack_action_handlersJ!! @4=-@@@   Is!;!; IOODUDU ;4=-;;;  ,33 $-"4 5     ; M       r!)defaultsr|r!r^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}, ) rYz4' tried to register auxiliary task with invalid key c3JK|]}|p|dkVdS)_N)r)rcs rrz8PluginContext.register_auxiliary_task..s388q199;;*!s(888888r!z' auxiliary task key z: must contain only alphanumeric characters and underscoresr) _AUX_TASKSch|]\}}}| Sr(r()rk_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. 'rbz').Nru# — already registered by plugin ''autor*<)rmodelbase_urlapi_keytimeout extra_body)r|r!rr^rz,Plugin %s registered auxiliary task: %s (%s))rjr`r rr_allhermes_cli.mainrdr _aux_tasksrritemsr?rB) rr|r!rr^_BUILTIN_AUX_TASKS builtin_keysexistingmerged_defaultsrfvs rregister_auxiliary_taskz%PluginContext.register_auxiliary_taskOsh *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)rzPlugin %s registered hook: %sN) r]r?rrr_rsortedr_hooksrSr\rB)rr|rWs r register_hookzPluginContext.register_hooks K ' ' NN " &--..     '' 266==hGGG 4dm6H)TTTTTr!rc 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)rz#Plugin %s registered middleware: %sN) rr?rrr_rr~r _middlewarerSr\rB)rrrWs 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 zPlugin skill 'z' is already registered)rr bare_namerrzPlugin %s registered skill: %sN)agent.skill_utilsrr rr_matchexistsFileNotFoundErrorrrr_plugin_skillsrsr?rB)rr_rrrr namespace qualifieds rregister_skillzPluginContext.register_skills& 433333 $;;:t::M&:::   =..t44 JtJJJ {{}} E#$CT$C$CDD DM1GT]5G  ))4)) = ! Ri4=3O&O&OPiPPPQQ Q& 1r22 3 3  $Y/  , M       r!)rrrr)rr)rr`)NNFr*r*F)r_r`rr`rrsrCrrrrrrr0rr`rr`rr0rr1)rr`rr0)r)rr`rr`rr0)Nr*) r_r`rr`rrrrrr`rr1)r*r*) r_r`rCrrr`rr`rr1)rr`rrsrr`rr1)NNr*)r_r`rHr`rIrrrrJrrKrrLr`rMrrr1)rVrrWrrr1) r|r`r!r`rr`r^r_rr1)r|r`rWrrr1)rr`rWrrr1)r*N) r_r`rrrr`rrrr1)r$r%r&r'rpropertyrrrrrrrrr rrr#r)r/r5r;rArGrUr]r{rrrr(r!rrrpsGG----X (((X(&X6%)$(7 7 7 7 7 v====4B'+ WWWWW: 4U4U4U4U4Up<<<<>    @    6$ $ $ $ P    6    8    @++++^" " " " L( ( ( ( d,0$(< < < < < @6 6 6 6 D.2 m m m m m m ^UUUU&VVVV237 0 0 0 0 0 0 0 r!rceZdZdZdCdZdDdEdZdCd ZdFd ZdGdZ dHdIdZ dJdZ dKdZ dFdZ dLd"Z dMd#ZdMd$ZdNd'ZdOd)ZdOd*ZdPd/ZdQd0ZdRd2ZdSd3ZdTd5ZdUd7ZdVd:ZdWd=ZdUd>ZdXd@ZdYdAZdZdBZdS)[ PluginManagerz;Central manager that discovers, loads, and invokes plugins.rr1ci|_i|_i|_t|_t|_i|_d|_i|_d|_ d|_ i|_ i|_ i|_ g|_dS)NF)_pluginsrrrcrrTrrr _discoveredrr_portable_mcp_serversrtr[rs rrzPluginManager.__init__ s13 13 68,/EE03#.0#13!& 9;@B"6846###r!Fr/r0c|jr|sdStdr#tdd|_dS|r|j|j|j|j|j |j |j |j |j |j|jd|_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. NHERMES_SAFE_MODEu/HERMES_SAFE_MODE=1 — plugin discovery skippedTF)rrr?rrclearrrrrTrrrrrtr[r_discover_and_load_inner BaseException)rr/s rdiscover_and_loadzPluginManager.discover_and_load=s   E  F - . .  KKI J J J#D  F  ( M   ! ! ! K        " " $ $ $  # ) ) + + +  ' - - / / /   $ $ & & &  ! ' ' ) ) )   % % ' ' '  & , , . . . O ! ! # # #  ' - - / / /#'D     ) ) + + + + +   $D   s #E99F c |}|}tdt |||t }t}i}|D]}|||jp|j <| D]}|jp|j }||vs |j |vr>t|d}d|_ ||j |<td|\|jdkr>t|d}d|_ ||j |<td||jd kr7t|d }||j |<td ||jd kr"|jd kr|||jd kr"|jdkr||A|duo ||vp|j |v} | sRt|d}d||_ ||j |<td||||r^tdt |j t)d|j DdSdS)u=The actual discovery sweep — see :meth:`discover_and_load`.z entrypoints: %d manifest(s)Frrqzdisabled via configzSkipping disabled plugin '%s'rxu<exclusive plugin — activate via .provider configz8Skipping '%s' (exclusive, handled by category discovery)rzTz?Skipping '%s' (model-provider, handled by providers/ discovery)rrvrwNzBnot 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)rq)rps rrz9PluginManager._discover_and_load_inner..s)CC!CACCCCCCr!)_collect_directory_manifests_scan_entry_pointsr?rBlenextendrnrur|r_valuesrrrrr _load_plugin_register_deferred_platformformatrsum) r manifests ep_manifestsrgrqwinnersr lookup_keyloaded is_enableds rrz&PluginManager._discover_and_load_innerds0*.*K*K*M*M ..00  4c,6G6GHHH&&&)**&((-/! > >H5=GHL1HM 2 2((T (T (H!6JX%%()B)B%xGGG4 ,2 j) model-providersmemory platformscontext_engine)r skip_namesz% bundled (top-level): %d manifest(s)r)rz# 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)) r r?rB_scan_directoryrrrrbrcwd) rr repo_pluginsrbundled_platformsuser_diruser_manifests project_dirproject_manifestss rrz*PluginManager._collect_directory_manifestss+- /00  3\BBB&& SSS'    /B/BCCC((( 7 8 8 (**y09.s'NNNUz%7M7MN5NNNr!rgc<h|]}t|t|Sr(rrs rriz9PluginManager.has_enabled_portable_mcp..s' I I Iu*UC2H2H IU I I Ir!r) _discover_mcp plugin-data) create_dataT)rbrrrjrsrkrcrr|r_rrhermes_cli.agent_pluginsrrrrrOSError RuntimeErrorr ) rrplugins_config enabled_valuerqdisabled_valuergrrrrs rhas_enabled_portable_mcpz&PluginManager.has_enabled_portable_mcp s * + + 5# 22.$// 5&**955 -.. 5NNmNNN'++J;;.$//  I I I I I I   5-/99;; > >H5=GHL1HM 2 2((  H$ !6JX%%()B)B((X]'-I-I BBBBBB =''#%%#$/=:? %   44 \:6    us2AE66FFNrrrr`rOptional[Set[str]]c6||||ddS)uRead ``plugin.yaml`` manifests from subdirectories of *path*. Supports two layouts, mixed freely: * **Flat** — ``//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*rrprefixdepth)_scan_directory_level)rrrrs rrzPluginManager._scan_directoryGs,*)) &Z!*   r!rrintcg}|s|St|D]=}|s|dkr |r |j|vr*|dz }|s|dz }|r0|||||} | || |dz } | s| r ddlm } | |\} } | D]#}t d||j $|r |d|jn| d }|t| d | d d | d d t| d d |t!||dt#| n3#t$$r&}t d| |Yd}~nd}~wwxYw|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.ymlNz plugin.json)read_agent_plugin_manifestzAgent Plugin '%s': %srr_rr*rrT) r_rrrrrr|rrFailed to parse %s: %srz/Skipping %s (no plugin.yaml, depth cap reached)r)is_dirr~iterdirr_r_parse_manifestr\ is_symlinkrrr?rmessagerrrrr`rrlrBrr)rrrrrrrchild manifest_filer portable_filerdata diagnostics diagnosticr|exc sub_prefixs rrz#PluginManager._scan_directory_level`s+- {{}}  DLLNN++? ? E<<>> zzjzUZ:-E-E!M1M '')) 5 % 4 ##%% //!5&&'$$X...!M1M##%% )A)A)C)C QSSSSSS(B(B5(I(I%D+&1 3!&. 7=NV22ej222$v,C$$&!%f$(HHY$;$;(,(C(C#2488Hb3I3I#J#J#)!$U #%),Ec,J,J       !QQQNN#;]CPPPPPPPPQ zz NPUVVV5;KF11UZ111J   **#%!) +    s5C$G H $HH r plugin_dirOptional[PluginManifest]c  ttd|dSt|dpi}|d|j}|r |d|jn|}|dd}t|tsd}| } | tvrDtd ||d ttd} | dkrd|vr|d z } | r| | d d dd} d| vsd| vrd} td|n%d| vr!d| vrd} td|n#t $rYnwxYwtd||| ||t#|t|dd|ddt%|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 %sr)encodingr_rrryzBPlugin %s: unknown kind '%s' (valid: %s); treating as 'standalone'r __init__.pyr)errorsri register_memory_providerMemoryProviderrxzAPlugin %s: detected memory provider, treating as kind='exclusive'rProviderProfilerzzEPlugin %s: detected model provider, treating as kind='model-provider'z9Parsed manifest: key=%s name=%s kind=%s source=%s path=%srr*rrrrr) r_rrrrrrrrrr|rexc_info)yamlr?rr read_textrrr_rjr`r3r4r{rr~rrBrlrrr5) rrrrrrr_r|raw_kindr init_file source_textrs rrzPluginManager._parse_manifests*N |H-XXXt!-"9"97"9"K"KLLRPRD88FJO44D39CV//jo///tCxx 55Hh,, ('>>##))++D...X499V4G-H-H#I#I$|##d(:(:&6 ##%%&/&9&9U\&9&]&]^c_c^c&d 6+EE/;>>#.D"LL!? # 0;>> 1[ @ @ $4D"LL!D # % LLKT4   "DHHY3344 HH]B77&txx"'='=>>!XXnb99#xx(8"==#xx(8"==__        NN(-~    44444  sC"J DJ :A*F%$J % F2/J 1F22CJ K#KKcg} 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|Sr(rENTRY_POINTS_GROUPreps r z4PluginManager._scan_entry_points.. s%PPPB=O1O1OR1O1O1Or! entrypoint)r_rrr|zEntry-point scan failed: %sN) importlibmetadata entry_pointshasattrrrrjrsrrrr_rr\rlr?rB)rreps group_epsrrrs rrz PluginManager._scan_entry_pointss%*,  =$1133CsH%% QJJ-?J@@ C&& QGG$6;; PP#PPP  + +)'    **** + = = = LL6 < < < < < < < < =sCC C7C22C7rrc|jpd}|dr|dtd S|jrt |jjS|S)aDerive the gateway platform name (e.g. ``feishu``) for a platform plugin. The platform name registered via ``register_platform(name=...)`` lives inside the adapter module (which we are explicitly trying NOT to import early). It is not carried in ``plugin.yaml``. Across every bundled platform plugin the manifest name is ``-platform`` and the plugin directory basename is ````, so we derive the name without importing: strip a trailing ``-platform`` from the manifest name, falling back to the directory basename. This is also a sensible convention for third-party platform plugins. r*z -platformN)r_endswithrrr)rrr_s r_platform_name_from_manifestz*PluginManager._platform_name_from_manifest3sb}" == % % -+3{++++, , = , &&+ + r!c|jp|j}|}t|d}d|_|j|<|fdfd } dd lm}|||t d ||d S#t$r6t d |d  |Yd SwxYw)aRegister a lazy loader for a bundled platform plugin. The platform adapter module is imported only when the gateway / cron / setup / send_message path first asks the ``platform_registry`` for this platform. Until then we record a lightweight ``LoadedPlugin`` so ``hermes plugins list`` still shows the platform as available, and we hand the registry a loader that runs the normal eager-load path. Tr _manifestrrr1c2|dSr)r)rrs r_loaderz:PluginManager._register_deferred_platform.._loaderYs   i ( ( ( ( (r!r)rOz3Registered deferred platform loader: %s (plugin=%s)z=Deferred platform registration failed for '%s'; eager-loadingrN)rrrr1) r|r_rrrrrRrOregister_deferredr?rBrlr)rrr platform_namerrrOs` rrz)PluginManager._register_deferred_platformFs+\2X] 99(CC x>>>$* j!08 ) ) ) ) ) ) ) ( C C C C C C  / / w G G G LLE       ( ( ( LLO       h ' ' ' ' ' ' (s8B rrrrzno register() functionz&Plugin '%s' has no register() functionc4i|]\}}|t|Sr(r)rhcbss r z.PluginManager._load_plugin..s1'''$*AsAs3xx'''r!c4i|]\}}|t|Sr(r)rrrs rrz.PluginManager._load_plugin..s1%%%'0tSD#c((%%%r!cg|]}|v| Sr(r()rt _tools_befores rrz.PluginManager._load_plugin..s.+++ -----r!chg|].\}}t||dk,|/Srrrr)rrr_hook_counts_befores rrz.PluginManager._load_plugin..sI+++33xx"5"9"9!Q"?"??????r!chg|].\}}t||dk,|/Sr%r&)rrr_mw_counts_befores rrz.PluginManager._load_plugin..sI000!c3xx"3"7"7a"@"@@@@@@r!cfg|]-}j|djk+|.S)r)rrrr_rrcrrs 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)rrN)rrrr_r+s rrz-PluginManager._load_plugin..sR-a044X>>(-OOOOOOr!zFailed to load plugin '%s': %sr))rr?rBr|r_rrrr_load_portable_pluginrrrregister_plugin_override_policy _NS_PARENTrr_load_directory_module_load_entrypoint_modulerrrrrcrrrurrrrrrrqrrrrlr`r5r) rrr _registry _plugin_id_slugr register_fnctxrr'r)r#s `` @@@rrzPluginManager._load_pluginosx000 ? L )HM8?HM8=       & &x 8 8 8 F888888\2X] ""3--55c3??11 # #E # # (D ) ) @ @ D D   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> hl3hm444s.G>K-- L=7>>NND"% <@LL*=99!FNN T T Ts88FL NNA:s S S S S S S S S T%+ j!!!sCBE,,CE, C9 "C4/E,4C99A2E,, F060F++F0types.ModuleTypect|j}|dz }|std|tt jvr@tjt}g|_ t|_ |t jt<|j p|j }| dd dd}td|}tj||t#|g}||jt'd |tj|} || _ t#|g| _ | t j|<|j| | S) a/Import a directory-based plugin as ``hermes_plugins.``. 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 rrrrbr)submodule_search_locationsNzCannot create module spec for )rrrrr/r9modulestypes ModuleType__path__ __package__r|r_rr utilspec_from_file_locationr`loader ImportErrormodule_from_spec exec_module) rrrrns_pkgr|r module_namespecrs rr0z$PluginManager._load_directory_modulesn(-(( . !! 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|Sr(rrs rrz9PluginManager._load_entrypoint_module..)s%LLLRX9K-K-K-K-K-Kr!z Entry point 'z' not found in group 'rj) r r r r rrrjrsrrr_loadrL)rrr rrs rr1z%PluginManager._load_entrypoint_module!s --// 3 ! ! M ); <$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``.rN)rrr)rrors rfind_plugin_skillzPluginManager.find_plugin_skills+#''77 %/uV}}4/r!rQrcr|dtfd|jDS)zCReturn sorted bare names of all skills registered by *plugin_name*.rc3XK|]$\}}||dV%dS)rN) startswith)rqnr"rs rrz3PluginManager.list_plugin_skills..sQ  A}}V$$ kN      r!r~rru)rrQrs @rlist_plugin_skillsz PluginManager.list_plugin_skillssX"""    ,2244      r!cbdt|jDS)zDReturn progressive-disclosure metadata for registered plugin skills.c g|]N\}}|t|dddt|didOS)rr*rr)r_rcategoryr)r`rrrs)rrrs rrz.sm   ! 5 ""599]B#?#?@@$#EIImR$@$@AA      r!rwrs rlist_plugin_skill_metadataz(PluginManager.list_plugin_skill_metadatas<  %+4+>+D+D+F+F$G$G    r!Dict[str, Dict[str, Any]]cHd|jDS)z?Return a defensive copy of enabled portable MCP server configs.c4i|]\}}|t|Sr()rs)rr_rms rrz:PluginManager.get_portable_mcp_servers..s4   f $v,,   r!)rrurs rget_portable_mcp_serversz&PluginManager.get_portable_mcp_serverss2  $ : @ @ B B    r!c*t|jSr)r0rrs rhas_portable_mcp_serversz&PluginManager.has_portable_mcp_serverssD.///r!c<|j|ddS)z>Remove a stale registry entry (silently ignores missing keys).N)rpop)rros rremove_plugin_skillz!PluginManager.remove_plugin_skills! 55555r!rFr/r0rr1)rrrrrr0r)rrrr`rrrr) rrrr`rrrr`rrrr) rrrrrr`rr`rr)rrrr`)rrrr1)rrrrrr1)rrrrAr|r`r rrrUr|r`rr0rr`rr0rr`r rrrUrrdrrg)ror`rrp)rQr`rr)rr})rr0)ror`rr1)r$r%r&r'rrrrrrrrrrrrr-r0r1r]r_rarcrfrnrrrxr|rrrr(r!rrrs`EE6666:%%%%%Nrrrrh1111f6666@*.      2TTTTlYYYY~<&'('('('(RV>V>V>V>p2+2+2+2+h$$$$L    ,####J000000006 1 1 1 1 40000              0000666666r!rzOptional[PluginManager]_plugin_managerc:ttatS)z>Return (and lazily create) the global PluginManager singleton.)rrr(r!rget_plugin_managerrs'// r!rrcDt|S)zReturn whether config enables a portable package with MCP servers. A fresh manager performs manifest-only scanning, so this startup gate does not mutate the process-wide plugin registry or import native plugin code. )rr)rs rhas_enabled_agent_plugin_mcprs ?? 3 3J ? ??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/Nrrrs rdiscover_pluginsrs' ***77777r!r|r rrUc 6tj|fi|S)zxInvoke a lifecycle hook on loaded plugins. Returns a list of non-``None`` return values from plugin callbacks. )rr])r|r s rr]r]s& ,    +I @ @ @ @@r!rc 6tj|fi|S)zyInvoke registered middleware callbacks. Returns a list of non-``None`` return values from middleware callbacks. )rrc)rr s rrcrcs& 2    1$ A A& A AAr!ct}t|dd}t|rt||Stt|di|S)zBReturn True when middleware callbacks are registered for ``kind``.raNr)rrrZr0rr)rrmethods rrara sm ""G W. 5 5F"FF4LL!!! 3377== > >>r!cDt|S)z0Return True when a loaded plugin handles a hook.)rr_)r|s rr_r_ s    ( ( 3 33r!T)frozenc:eZdZUdZded<dZded<dZded<dS)_PreToolCallDirectiveNractionrrule_key)r$r%r&rrrrr(r!rrr sE F    !G!!!!"H""""""r!r>Tool '{tool_name}' denied: not in this thread's tool whitelistallowedr deny_msg_fmtc6|t_|t_dSr)_thread_tool_whitelistrfmt)rrs rset_thread_tool_whitelistr s&-"!-r!cdt_dSr)rrr(r!rclear_thread_tool_whitelistr% s%)"""r!rrr_task_id session_id tool_call_idturn_idapi_request_idmiddleware_traceOptional[List[Dict[str, Any]]]c ttdd}|?||vr;ttdd} td| |Sdd lm} | d |t |tr|ni|||||t|pg } | D]} t | ts| d } | d vr2| d}t |tr|r|nd}| dkr|sk| dkr| dnd}t |tr| nd}|sd}t| ||cStS)u@Check ``pre_tool_call`` hooks for a blocking or approval directive. Plugins that need to enforce policy (rate limiting, security restrictions, approval workflows) can return one of:: {"action": "block", "message": "Reason the tool was blocked"} {"action": "approve", "message": "Why this needs human confirmation"} {"action": "approve", "message": "...", "rule_key": "write_file:ssh"} from their ``pre_tool_call`` callback. - ``block`` vetoes the tool call outright (the message becomes the tool result the model sees). - ``approve`` ESCALATES to the existing human-approval gate (``prompt_dangerous_approval`` on CLI, the approval callback on the gateway) — the same mechanism Tier-2 dangerous shell patterns use. This lets a plugin require a human ``[o]nce/[s]ession/[a]lways/[d]eny`` decision on ANY tool, not just terminal command strings. The caller is responsible for invoking the gate (see :func:`tools.approval.request_tool_approval`). - ``rule_key`` is optional and only honored for ``approve`` directives. It lets plugins choose the allowlist grain for `[a]lways` approvals. The first valid directive wins. Invalid or irrelevant hook return values are silently ignored so existing observer-only hooks are unaffected. rNrzTool '{tool_name}' deniedblock)r)rrr)r]rH)rrrrrrrrr)rapproverrr)rrr) rrrrhermes_cli.lifecycler]rjrsrkrrr`r3)rrrrrrrrrrinvoke_lifecycle_hook hook_resultsrmrrrs r$_get_pre_tool_call_directive_detailsr) sH,i>>Gy77,e5PQQ$JJJ33    JIIIII((d++ 3TT!%.4"55   LXX&$''  H%% - - - **Y'''55K'K''t W  W  -3y-@-@6::j)))d'1(C'@'@J8>>###d H$FGhWWWWWW " ""r!#tuple[Optional[str], Optional[str]]c Lt||||||||}|j|jfS)aDCheck ``pre_tool_call`` hooks for a blocking or approval directive. Backward-compatible public helper: returns ``(directive, message)`` where ``directive`` is ``"block"``, ``"approve"``, or ``None``. Internal callers that need approve-specific metadata use :func:`_get_pre_tool_call_directive_details`. rrrrrr)rrr) rrrrrrrrdetailss rget_pre_tool_call_directiverx s="34Z!7%8HG NGO ,,r!rc Jt||||||||\}} |dkr| ndS)aZBack-compat shim: return only a ``block`` message (or ``None``). Deprecated in favor of :func:`get_pre_tool_call_directive`, which also surfaces the ``approve`` escalation directive. Kept so any external caller importing the old name keeps working; ``approve`` directives are invisible to this shim (it only reports blocks). rrN)r) rrrrrrrr directivers rget_pre_tool_call_block_messager sG"54Z!7%8HIw  7**774r!c ,t||||||||}|jdkr|jS|jdkr ddlm} m} m} d} | ||} n#t$rYnwxYw | ||jpd|jp| } |  | | n5#t$rYn)wxYwn$#|  | | w#t$rYwwxYwwxYwn#t$rd |cYSwxYw| d s't| d pd |SdS)aResolve the pre_tool_call directive to a final block message (or None). Single entry point for every tool-dispatch site: fetches the plugin directive and, for an ``approve`` escalation, invokes the human-approval gate (:func:`tools.approval.request_tool_approval`). Returns the message the tool result should carry when the call is blocked, or ``None`` when the call may proceed. Centralizing this keeps the security-critical fail-closed logic in ONE place instead of copy-pasted across the concurrent/sequential/helper dispatch paths: an ``approve`` directive whose gate errors, denies, or times out is fail-closed to a block; ``block`` blocks with its message; anything else proceeds. rrrr)request_tool_approval#reset_current_observability_context!set_current_observability_contextN)rrr*)rz)BLOCKED: plugin approval gate failed for approvedrz&BLOCKED: plugin approval required for ) rrrtools.approvalrrrrlrrrr`)rrrrrrrrrrrrapproval_tokensrms rresolve_pre_tool_blockr s034Z!7%8HG ~  ~"" K           #O "C"C#!-###     ..O)r$-: #.;;OLLLL$/?.;;OLLLL$/  K K KKyJJ J J J Kzz*%%  9%%HGIGG  4s C AC ACAC"B>C B C BCBCB?" B.-B?. B;8B?:B;;B??CCCrrwrmcodingattemptfinal_response changed_pathsrwrmrrrrrOptional[List[str]]c td||||||t|pg}|D]}t|tst |dp|dpd} | dvrz|dp|d} t| tr*| r| cSd S) u9Check user ``pre_verify`` hooks for a directive to keep the agent going. Fired once per turn when the agent edited code and is about to verify/finish. A hook keeps the turn going (run a check, defer it, tidy the diff) by returning:: {"action": "continue", "message": ""} The Claude-Code Stop shape ``{"decision": "block", "reason": "..."}`` (block the stop == keep going) is accepted too. The first directive carrying a non-empty message wins; any other return lets the turn finish. Mirrors :func:`get_pre_tool_call_block_message` — the call site stays a one-liner. ``coding`` / ``attempt`` let a hook scope itself (``if not coding`` …) and self-throttle (``if attempt`` …), the same way a ``pre_tool_call`` hook scopes on ``tool_name``. rErrdecisionr*)continuerrreasonN)r]rkrjrsr`rrr3r4) rrwrmrrrrrrmrrs rget_pre_verify_continue_messager s6%=.B//   L##&$''  VZZ))IVZZ -C-CIrJJPPRRXXZZ . . . **Y''?6::h+?+? gs # # #  #==?? " " " 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$ s+ !""G E*** Nr!c(tjS)z5Return the plugin-registered context engine, or None.)rrr(r!rget_plugin_context_enginer. s % ' ' 77r!Optional[Callable]cftj|}|r|dndS)zFReturn the handler for a plugin-registered slash command, or ``None``.rCN)rrrr)r_rs rget_plugin_command_handlerr3 s3 & ( ( 9 = =d C CE$ .5  $.r!g>@rmctjsS 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. rr1c tjd<n#t$r}|d<Yd}~nd}~wwxYwdS#wxYw)Nrr)asynciorunrrc)rdonefailureoutcomerms r_runnerz.resolve_plugin_command_result.._runnerR sv &{622GG   ! ! ! GENNNNNN ! HHJJJJJDHHJJJJs%A 4/A 4A A#zhermes-plugin-command-awaitT)targetr_daemon)rpz5Plugin command async handler did not complete within z.0fsrrr)inspect isawaitablerget_running_looprr threadingEventThreadstartwait"_PLUGIN_COMMAND_AWAIT_TIMEOUT_SECS TimeoutErrorrr)rmrthreadrrrs` @@@rresolve_plugin_command_resultr< sK  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. )rrr(r!rget_plugin_commandsrj s & ' ' 88r!rgc`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()rt)rrfrs rrz.get_plugin_auxiliary_tasks.. s! F F FaG q ! F F Fr!)rr~rt)rs@rget_plugin_auxiliary_tasksrs s5)**G F F F F6'2D+E+E F F FFr!rdcDt}|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🔌 rbrr)rrrrrl get_entryrrSr\r_rrurr~rrrtitlerrr)rr toolset_toolstoolset_pluginrrtsrgrrmts_keyrrHdescs rget_plugin_toolsetsr s !""G  % +++++++  +-M.0N/<< ""9--   ]  R((// ;;;;!)//11AA v0 A AI&&y11E A-77))%-@@@ A F''--##F++:sC006688::  r sB#"""""  ((((((((KKKKKKKKKKKKKKKKKKKK,,,,,,11111111%%%%%%KKKKKKKK > > > >KKKK DDDo  8 $ $"1266<<>>DDFFK!6 SSS SSSSj,  !!!!     D!e d ddddd + + + +//// ####### #L  *f f f f f f f f Zt6t6t6t6t6t6t6t6v,0////@@@@88888AAAABBBB????4444 )** $########Y.....****7;L#L#L#L#L#d7;-----87;5555587;DDDDDR)-000000f888 //// &*"+ + + + \9999 G G G G******s5A::BB