"""

Hermes Plugin System

====================

Discovers, loads, and manages plugins from four sources:

1. **Bundled plugins** – ``<repo>/plugins/<name>/`` (shipped with hermes-agent;

``memory/`` and ``context_engine/`` subdirs are excluded — they have their

own discovery paths)

2. **User plugins** – ``~/.hermes/plugins/<name>/``

3. **Project plugins** – ``./.hermes/plugins/<name>/`` (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.

"""

from __future__ import annotations

import asyncio

import importlib.metadata

import importlib.util

import inspect

import logging

import os

import sys

import threading

import types

from dataclasses import dataclass, field

from pathlib import Path

from typing import Any, Callable, Dict, List, Optional, Set, Union

from hermes_constants import get_hermes_home

from utils import env_var_enabled

from hermes_cli.config import cfg_get

from hermes_cli.middleware import OBSERVER_SCHEMA_VERSION, VALID_MIDDLEWARE

def get_bundled_plugins_dir() -> Path:

"""Locate 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.

"""

env_override = os.getenv("HERMES_BUNDLED_PLUGINS")

if env_override:

return Path(env_override)

return Path(__file__).resolve().parent.parent / "plugins"

try:

import yaml

except ImportError: # pragma: no cover – yaml is optional at import time

yaml = None # type: ignore[assignment]

logger = logging.getLogger(__name__)

# ---------------------------------------------------------------------------

# Plugin developer debug logging

# ---------------------------------------------------------------------------

#

# Set ``HERMES_PLUGINS_DEBUG=1`` to surface verbose plugin-discovery logs to

# stderr in addition to ~/.hermes/logs/agent.log. Aimed at plugin authors

# trying to figure out why their plugin isn't showing up: which directories

# were scanned, which manifests parsed, which plugins were skipped (and why),

# what each ``register(ctx)`` call registered, and full tracebacks on load

# failure.

#

# The env var is read once at import time; tests that need to flip it

# mid-process can call ``_install_plugin_debug_handler(force=True)``.

_PLUGINS_DEBUG = os.getenv("HERMES_PLUGINS_DEBUG", "").strip().lower() in {

"1", "true", "yes", "on",

}

_DEBUG_HANDLER_INSTALLED = False

def _install_plugin_debug_handler(force: bool = False) -> None:

"""When 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.

"""

global _DEBUG_HANDLER_INSTALLED, _PLUGINS_DEBUG

if force:

_PLUGINS_DEBUG = os.getenv("HERMES_PLUGINS_DEBUG", "").strip().lower() in {

"1", "true", "yes", "on",

}

if not _PLUGINS_DEBUG or _DEBUG_HANDLER_INSTALLED:

return

handler = logging.StreamHandler(sys.stderr)

handler.setLevel(logging.DEBUG)

handler.setFormatter(logging.Formatter("[plugins] %(levelname)s %(message)s"))

logger.addHandler(handler)

logger.setLevel(logging.DEBUG)

# Don't double-emit through the root logger when the central logging

# config also writes to stderr. agent.log still captures everything.

logger.propagate = True

_DEBUG_HANDLER_INSTALLED = True

logger.debug(

"HERMES_PLUGINS_DEBUG=1 — verbose plugin discovery logging enabled"

)

_install_plugin_debug_handler()

# ---------------------------------------------------------------------------

# Constants

# ---------------------------------------------------------------------------

VALID_HOOKS: Set[str] = {

"pre_tool_call",

"post_tool_call",

"transform_terminal_output",

"transform_tool_result",

# Transform LLM output before it's returned to the user.

# Plugins return a string to replace the response text, or None/empty to leave unchanged.

# First non-None string wins. Useful for vocabulary/personality transformation.

"transform_llm_output",

"pre_llm_call",

"post_llm_call",

"pre_api_request",

"post_api_request",

"api_request_error",

"on_session_start",

"on_session_end",

"on_session_finalize",

"on_session_reset",

"subagent_start",

"subagent_stop",

# Gateway pre-dispatch hook. Fired once per incoming MessageEvent

# after the internal-event guard but BEFORE auth/pairing and agent

# dispatch. Plugins may return a dict to influence flow:

# {"action": "skip", "reason": "..."} -> drop message (no reply)

# {"action": "rewrite", "text": "..."} -> replace event.text, continue

# {"action": "allow"} / None -> normal dispatch

# Kwargs: event: MessageEvent, gateway: GatewayRunner, session_store.

"pre_gateway_dispatch",

# Approval lifecycle hooks. Fired by tools/approval.py when a dangerous

# command needs user approval -- fires BOTH for CLI-interactive prompts

# and for gateway/ACP approvals (Telegram, Discord, Slack, TUI, etc.).

# Observers only: return values are ignored. Plugins cannot veto or

# pre-answer an approval from these hooks (use pre_tool_call to block

# a tool before it reaches approval).

#

# Kwargs for pre_approval_request:

# command: str, description: str, pattern_key: str, pattern_keys: list[str],

# session_key: str, surface: "cli" | "gateway"

# Kwargs for post_approval_response: same as above plus

# choice: "once" | "session" | "always" | "deny" | "timeout"

"pre_approval_request",

"post_approval_response",

}

ENTRY_POINTS_GROUP = "hermes_agent.plugins"

_NS_PARENT = "hermes_plugins"

def _env_enabled(name: str) -> bool:

"""Return True when an env var is set to a truthy opt-in value."""

return env_var_enabled(name)

def _get_disabled_plugins() -> set:

"""Read the disabled plugins list from config.yaml.

Kept for backward compat and explicit deny-list semantics. A plugin

name in this set will never load, even if it appears in

``plugins.enabled``.

"""

try:

from hermes_cli.config import load_config

config = load_config()

disabled = cfg_get(config, "plugins", "disabled", default=[])

return set(disabled) if isinstance(disabled, list) else set()

except Exception:

return set()

def _get_enabled_plugins() -> Optional[set]:

"""Read the enabled-plugins allow-list from config.yaml.

Plugins are opt-in by default — only plugins whose name appears in

this set are loaded. Returns:

* ``None`` — the key is missing or malformed. Callers should treat

this as "nothing enabled yet" (the opt-in default); the first

``migrate_config`` run populates the key with a grandfathered set

of currently-installed user plugins so existing setups don't

break on upgrade.

* ``set()`` — an empty list was explicitly set; nothing loads.

* ``set(...)`` — the concrete allow-list.

"""

try:

from hermes_cli.config import load_config

config = load_config()

plugins_cfg = config.get("plugins")

if not isinstance(plugins_cfg, dict):

return None

if "enabled" not in plugins_cfg:

return None

enabled = plugins_cfg.get("enabled")

if not isinstance(enabled, list):

return None

return set(enabled)

except Exception:

return None

# ---------------------------------------------------------------------------

# Data classes

# ---------------------------------------------------------------------------

_VALID_PLUGIN_KINDS: Set[str] = {"standalone", "backend", "exclusive", "platform", "model-provider"}

@dataclass

class PluginManifest:

"""Parsed representation of a plugin.yaml manifest."""

name: str

version: str = ""

description: str = ""

author: str = ""

requires_env: List[Union[str, Dict[str, Any]]] = field(default_factory=list)

provides_tools: List[str] = field(default_factory=list)

provides_hooks: List[str] = field(default_factory=list)

source: str = "" # "user", "project", or "entrypoint"

path: Optional[str] = None

# Plugin kind — see plugins.py module docstring for semantics.

# ``standalone`` (default): hooks/tools of its own; opt-in via

# ``plugins.enabled``.

# ``backend``: pluggable backend for an existing core tool (e.g.

# image_gen). Built-in (bundled) backends auto-load;

# user-installed still gated by ``plugins.enabled``.

# ``exclusive``: category with exactly one active provider (memory).

# Selection via ``<category>.provider`` config key; the

# category's own discovery system handles loading and the

# general scanner skips these.

# ``platform``: gateway messaging platform adapter (e.g. IRC). Bundled

# platform plugins auto-load so every shipped platform is

# available out of the box; user-installed platform plugins

# in ~/.hermes/plugins/ still gated by ``plugins.enabled``

# (untrusted code).

kind: str = "standalone"

# Registry key — path-derived, used by ``plugins.enabled``/``disabled``

# lookups and by ``hermes plugins list``. For a flat plugin at

# ``plugins/disk-cleanup/`` the key is ``disk-cleanup``; for a nested

# category plugin at ``plugins/image_gen/openai/`` the key is

# ``image_gen/openai``. When empty, falls back to ``name``.

key: str = ""

@dataclass

class LoadedPlugin:

"""Runtime state for a single loaded plugin."""

manifest: PluginManifest

module: Optional[types.ModuleType] = None

tools_registered: List[str] = field(default_factory=list)

hooks_registered: List[str] = field(default_factory=list)

middleware_registered: List[str] = field(default_factory=list)

commands_registered: List[str] = field(default_factory=list)

enabled: bool = False

error: Optional[str] = None

# ---------------------------------------------------------------------------

# PluginContext – handed to each plugin's ``register()`` function

# ---------------------------------------------------------------------------

class PluginContext:

"""Facade given to plugins so they can register tools and hooks."""

def __init__(self, manifest: PluginManifest, manager: "PluginManager"):

self.manifest = manifest

self._manager = manager

# Lazy-built host-owned LLM facade — see ctx.llm property below.

self._llm: Any = None

# -- host-owned LLM access ----------------------------------------------

@property

def llm(self) -> Any:

"""Return 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.<plugin_id>.llm.*`` config keys.

See :mod:`agent.plugin_llm` for the full surface."""

if self._llm is None:

from agent.plugin_llm import PluginLlm

plugin_id = self.manifest.key or self.manifest.name

self._llm = PluginLlm(plugin_id=plugin_id)

return self._llm

# -- tool registration --------------------------------------------------

def register_tool(

self,

name: str,

toolset: str,

schema: dict,

handler: Callable,

check_fn: Callable | None = None,

requires_env: list | None = None,

is_async: bool = False,

description: str = "",

emoji: str = "",

override: bool = False,

) -> None:

"""Register 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.

"""

from tools.registry import registry

registry.register(

name=name,

toolset=toolset,

schema=schema,

handler=handler,

check_fn=check_fn,

requires_env=requires_env,

is_async=is_async,

description=description,

emoji=emoji,

override=override,

)

self._manager._plugin_tool_names.add(name)

logger.debug(

"Plugin %s registered tool: %s%s",

self.manifest.name, name, " (override)" if override else "",

)

# -- message injection --------------------------------------------------

def inject_message(self, content: str, role: str = "user") -> bool:

"""Inject 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.

"""

cli = self._manager._cli_ref

if cli is None:

logger.warning("inject_message: no CLI reference (not available in gateway mode)")

return False

msg = content if role == "user" else f"[{role}] {content}"

if getattr(cli, "_agent_running", False):

# Agent is mid-turn — interrupt with the message

cli._interrupt_queue.put(msg)

else:

# Agent is idle — queue as next input

cli._pending_input.put(msg)

return True

# -- CLI command registration --------------------------------------------

def register_cli_command(

self,

name: str,

help: str,

setup_fn: Callable,

handler_fn: Callable | None = None,

description: str = "",

) -> None:

"""Register 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=...)``."""

self._manager._cli_commands[name] = {

"name": name,

"help": help,

"description": description,

"setup_fn": setup_fn,

"handler_fn": handler_fn,

"plugin": self.manifest.name,

}

logger.debug("Plugin %s registered CLI command: %s", self.manifest.name, name)

# -- slash command registration -------------------------------------------

def register_command(

self,

name: str,

handler: Callable,

description: str = "",

args_hint: str = "",

) -> None:

"""Register 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 <subcommand>``

terminal commands), this registers in-session slash commands that users

invoke during a conversation.

``args_hint`` is an optional short string (e.g. ``"<file>"`` 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.

"""

clean = name.lower().strip().lstrip("/").replace(" ", "-")

if not clean:

logger.warning(

"Plugin '%s' tried to register a command with an empty name.",

self.manifest.name,

)

return

# Reject if it conflicts with a built-in command

try:

from hermes_cli.commands import resolve_command

if resolve_command(clean) is not None:

logger.warning(

"Plugin '%s' tried to register command '/%s' which conflicts "

"with a built-in command. Skipping.",

self.manifest.name, clean,

)

return

except Exception:

pass # If commands module isn't available, skip the check

self._manager._plugin_commands[clean] = {

"handler": handler,

"description": description or "Plugin command",

"plugin": self.manifest.name,

"args_hint": (args_hint or "").strip(),

}

logger.debug("Plugin %s registered command: /%s", self.manifest.name, clean)

# -- tool dispatch -------------------------------------------------------

def dispatch_tool(self, tool_name: str, args: dict, **kwargs) -> str:

"""Dispatch 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).

"""

from tools.registry import registry

# Wire up parent agent context when available (CLI mode).

# In gateway mode _cli_ref is None — tools degrade gracefully

# (workspace hints fall back to TERMINAL_CWD, no spinner).

if "parent_agent" not in kwargs:

cli = self._manager._cli_ref

agent = getattr(cli, "agent", None) if cli else None

if agent is not None:

kwargs["parent_agent"] = agent

return registry.dispatch(tool_name, args, **kwargs)

# -- context engine registration -----------------------------------------

def register_context_engine(self, engine) -> None:

"""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``.

"""

if self._manager._context_engine is not None:

logger.warning(

"Plugin '%s' tried to register a context engine, but one is "

"already registered. Only one context engine plugin is allowed.",

self.manifest.name,

)

return

# Defer the import to avoid circular deps at module level

from agent.context_engine import ContextEngine

if not isinstance(engine, ContextEngine):

logger.warning(

"Plugin '%s' tried to register a context engine that does not "

"inherit from ContextEngine. Ignoring.",

self.manifest.name,

)

return

self._manager._context_engine = engine

logger.info(

"Plugin '%s' registered context engine: %s",

self.manifest.name, engine.name,

)

# -- image gen provider registration ------------------------------------

def register_image_gen_provider(self, provider) -> None:

"""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.

"""

from agent.image_gen_provider import ImageGenProvider

from agent.image_gen_registry import register_provider

if not isinstance(provider, ImageGenProvider):

logger.warning(

"Plugin '%s' tried to register an image_gen provider that does "

"not inherit from ImageGenProvider. Ignoring.",

self.manifest.name,

)

return

register_provider(provider)

logger.info(

"Plugin '%s' registered image_gen provider: %s",

self.manifest.name, provider.name,

)

# -- dashboard auth provider registration --------------------------------

def register_dashboard_auth_provider(self, provider) -> None:

"""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``.

"""

from hermes_cli.dashboard_auth import (

DashboardAuthProvider, register_provider,

)

if not isinstance(provider, DashboardAuthProvider):

logger.warning(

"Plugin '%s' tried to register a dashboard-auth provider "

"that does not inherit from DashboardAuthProvider. Ignoring.",

self.manifest.name,

)

return

try:

register_provider(provider)

except (TypeError, ValueError) as e:

logger.warning(

"Plugin '%s' failed to register dashboard-auth provider "

"%r: %s",

self.manifest.name, getattr(provider, "name", "?"), e,

)

return

logger.info(

"Plugin '%s' registered dashboard-auth provider: %s (%s)",

self.manifest.name, provider.name, provider.display_name,

)

# -- video gen provider registration -------------------------------------

def register_video_gen_provider(self, provider) -> None:

"""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.

"""

from agent.video_gen_provider import VideoGenProvider

from agent.video_gen_registry import register_provider as _register_video_provider

if not isinstance(provider, VideoGenProvider):

logger.warning(

"Plugin '%s' tried to register a video_gen provider that does "

"not inherit from VideoGenProvider. Ignoring.",

self.manifest.name,

)

return

_register_video_provider(provider)

logger.info(

"Plugin '%s' registered video_gen provider: %s",

self.manifest.name, provider.name,

)

# -- web search/extract provider registration ----------------------------

def register_web_search_provider(self, provider) -> None:

"""Register 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.

"""

from agent.web_search_provider import WebSearchProvider

from agent.web_search_registry import register_provider as _register_web_provider

if not isinstance(provider, WebSearchProvider):

logger.warning(

"Plugin '%s' tried to register a web provider that does "

"not inherit from WebSearchProvider. Ignoring.",

self.manifest.name,

)

return

_register_web_provider(provider)

logger.info(

"Plugin '%s' registered web provider: %s",

self.manifest.name, provider.name,

)

# -- browser provider registration ---------------------------------------

def register_browser_provider(self, provider) -> None:

"""Register 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.

"""

from agent.browser_provider import BrowserProvider

from agent.browser_registry import register_provider as _register_browser_provider

if not isinstance(provider, BrowserProvider):

logger.warning(

"Plugin '%s' tried to register a browser provider that does "

"not inherit from BrowserProvider. Ignoring.",

self.manifest.name,

)

return

_register_browser_provider(provider)

logger.info(

"Plugin '%s' registered browser provider: %s",

self.manifest.name, provider.name,

)

# -- TTS provider registration -------------------------------------------

def register_tts_provider(self, provider) -> None:

"""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.<name>: 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.

"""

from agent.tts_provider import TTSProvider

from agent.tts_registry import register_provider as _register_tts_provider

if not isinstance(provider, TTSProvider):

logger.warning(

"Plugin '%s' tried to register a TTS provider that does "

"not inherit from TTSProvider. Ignoring.",

self.manifest.name,

)

return

_register_tts_provider(provider)

logger.info(

"Plugin '%s' registered TTS provider: %s",

self.manifest.name, provider.name,

)

# -- transcription (STT) provider registration ---------------------------

def register_transcription_provider(self, provider) -> None:

"""Register 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.<name>: 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).

"""

from agent.transcription_provider import TranscriptionProvider

from agent.transcription_registry import register_provider as _register_stt_provider

if not isinstance(provider, TranscriptionProvider):

logger.warning(

"Plugin '%s' tried to register a transcription provider that "

"does not inherit from TranscriptionProvider. Ignoring.",

self.manifest.name,

)

return

_register_stt_provider(provider)

logger.info(

"Plugin '%s' registered transcription provider: %s",

self.manifest.name, provider.name,

)

# -- platform adapter registration ---------------------------------------

def register_platform(

self,

name: str,

label: str,

adapter_factory: Callable,

check_fn: Callable,

validate_config: Callable | None = None,

required_env: list | None = None,

install_hint: str = "",

**entry_kwargs: Any,

) -> None:

"""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,

)

"""

from gateway.platform_registry import platform_registry, PlatformEntry

entry_kwargs.setdefault("plugin_name", self.manifest.name)

entry = PlatformEntry(

name=name,

label=label,

adapter_factory=adapter_factory,

check_fn=check_fn,

validate_config=validate_config,

required_env=required_env or [],

install_hint=install_hint,

source="plugin",

**entry_kwargs,

)

platform_registry.register(entry)

self._manager._plugin_platform_names.add(name)

logger.debug(

"Plugin %s registered platform: %s",

self.manifest.name,

name,

)

# -- slack action handler registration ----------------------------------

def register_slack_action_handler(

self,

action_id: Any,

callback: Callable,

) -> None:

"""Register 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)

"""

if not callable(callback):

raise ValueError(

f"Plugin '{self.manifest.name}' tried to register a Slack "

f"action handler with a non-callable callback."

)

if action_id is None or (isinstance(action_id, str) and not action_id.strip()):

raise ValueError(

f"Plugin '{self.manifest.name}' tried to register a Slack "

f"action handler with an empty action_id."

)

self._manager._slack_action_handlers.append(

(action_id, callback, self.manifest.name)

)

logger.debug(

"Plugin %s registered Slack action handler: %s",

self.manifest.name,

action_id,

)

# -- hook registration --------------------------------------------------

# -- auxiliary task registration ---------------------------------------

def register_auxiliary_task(

self,

key: str,

*,

display_name: str,

description: str,

defaults: Optional[Dict[str, Any]] = None,

) -> None:

"""Register 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.<key>`` 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_<KEY_UPPER>_*`` 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.<key>``

and env vars ``AUXILIARY_<KEY_UPPER>_*``. 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},

)

"""

# Validate key shape

if not key or not isinstance(key, str):

raise ValueError(

f"Plugin '{self.manifest.name}' tried to register auxiliary task "

f"with invalid key {key!r}"

)

if not all(c.isalnum() or c == "_" for c in key):

raise ValueError(

f"Plugin '{self.manifest.name}' auxiliary task key {key!r} "

f"must contain only alphanumeric characters and underscores"

)

# Lazy import to avoid circular: hermes_cli.main imports plugins indirectly

from hermes_cli.main import _AUX_TASKS as _BUILTIN_AUX_TASKS

builtin_keys = {k for k, _name, _desc in _BUILTIN_AUX_TASKS}

if key in builtin_keys:

raise ValueError(

f"Plugin '{self.manifest.name}' cannot register auxiliary task "

f"{key!r} — that key is reserved for a built-in task. "

f"Pick a plugin-namespaced key (e.g. '{self.manifest.name}_{key}')."

)

# Reject duplicate registrations across plugins

existing = self._manager._aux_tasks.get(key)

if existing is not None and existing.get("plugin") != self.manifest.name:

raise ValueError(

f"Plugin '{self.manifest.name}' cannot register auxiliary task "

f"{key!r} — already registered by plugin "

f"'{existing.get('plugin')}'"

)

# Normalize defaults — plugin owns the schema, but we ensure routing

# fields exist with sensible types so consumers don't crash.

merged_defaults: Dict[str, Any] = {

"provider": "auto",

"model": "",

"base_url": "",

"api_key": "",

"timeout": 60,

"extra_body": {},

}

if defaults:

for k, v in defaults.items():

merged_defaults[k] = v

self._manager._aux_tasks[key] = {

"key": key,

"display_name": display_name,

"description": description,

"defaults": merged_defaults,

"plugin": self.manifest.name,

}

logger.debug(

"Plugin %s registered auxiliary task: %s (%s)",

self.manifest.name,

key,

display_name,

)

def register_hook(self, hook_name: str, callback: Callable) -> None:

"""Register a lifecycle hook callback.

Unknown hook names produce a warning but are still stored so