clients/hermes: ship the plugin as an installable entry-point package

Hermes discovers pip/Nix-installed plugins by scanning the
`hermes_agent.plugins` entry-point group (importlib.metadata ->
ep.load() -> register(ctx)) — the documented recommended distribution
path. Declare that entry point so commy installs that way instead of a
per-repo git clone or an init-container extract.

- pyproject: a real installable package (build-system + commy package +
  package-data) declaring `commy-platform = "commy"`.
- flake: build the package straight from clients/hermes as a package
  output + overlay, consumed via services.hermes-agent.extraPythonPackages
  or a package .override -- no second repo, no deploy key, no mirror CI.
- imports: intra-package `from commy.X` -> relative `from .X` so the
  package loads under any module name, not only a top-level `commy`.
- test: prove the plugin advertises + loads via the entry-point path.
- README: document the entry-point mechanism + pip/Nix consumption.

Retires homelab's agent-comms-extract init-container + PYTHONPATH hack
at consume time (hl-ynhi).

comms-i8qn

Author: GraemeF

clients/hermes/.gitignore

@@ -3,3 +3,6 @@ __pycache__/
 *.pyc
 .pytest_cache/
 .ruff_cache/
+dist/
+build/
+*.egg-info/

clients/hermes/README.md

@@ -60,11 +60,13 @@ tests/
   test_adapter_connection.py
   _stub_mcp_server.py   # real stub MCP server for the transport tests
 scripts/test.sh   # build isolated env + lint + test
+pyproject.toml    # installable package + hermes_agent.plugins entry point
 ```
 
-The plugin payload is the `commy/` directory. Hermes loads it by
-directory scan (like the bundled platform plugins), not as a pip wheel — so
-this is a non-package uv project (tooling + tests only).
+The plugin payload is the `commy/` package. It ships as an installable Python
+package whose `pyproject.toml` declares the `hermes_agent.plugins` entry point
+(`commy-platform = "commy"`) — the mechanism Hermes uses to discover
+pip/Nix-installed plugins. See [Install / distribution](#install--distribution).
 
 ## Per-topic connection lifecycle (`comms-a7j.5`)
 
@@ -115,8 +117,40 @@ Tested against the latest `hermes-agent` on PyPI (range `>=0.12,<1`); the pin
 tightens to the confirmed pod Hermes version via the homelab image lane
 (`comms-v9nws`).
 
-## Pod install
+## Install / distribution
 
-Wiring the install into `~/.hermes/plugins/` is tracked separately
-(`comms-a7j.7`).
+Hermes discovers plugins by scanning the `hermes_agent.plugins` entry-point
+group (`importlib.metadata.entry_points` → `ep.load()` → `register(ctx)`), the
+[documented recommended distribution path](https://github.com/NousResearch/hermes-agent)
+for pip/Nix-installed plugins. This package declares that entry point, so it
+installs without a per-repo git clone or an init-container extract. After
+install, activate it once:
+
+```bash
+hermes plugins enable commy-platform
+```
+
+**NixOS (the supported pod path).** The repo's flake builds this package as an
+output and exposes an overlay, so a NixOS host consumes it via
+`services.hermes-agent.extraPythonPackages` — built straight from this monorepo
+subdir, no separate plugin repo:
+
+```nix
+{
+  inputs.commy.url = "github:CodeForBreakfast/commy";
+
+  # In the host config, with commy's overlay applied so `commy-hermes` lands in
+  # the same Python set as hermes-agent (version-matched):
+  nixpkgs.overlays = [ inputs.commy.overlays.default ];
+  services.hermes-agent.extraPythonPackages = ps: [ ps.commy-hermes ];
+}
 ```
+
+`nix build github:CodeForBreakfast/commy#commy-hermes` builds the wheel
+directly for inspection.
+
+**pip.** `pip install` of the built wheel into Hermes' environment works the
+same way (auto-discovered on next startup, then `hermes plugins enable
+commy-platform`). Publishing the wheel to PyPI for public `pip install
+commy-hermes` is a future option (would use PyPI Trusted Publishing / OIDC); it
+is intentionally not wired until a public consumer needs it.

clients/hermes/commy/adapter.py

@@ -40,9 +40,9 @@
 )
 from gateway.session import SessionSource
 
-from commy.connection import ConnectionSpec, SpawnConfig, TopicConnectionManager
-from commy.listener import ChannelListener
-from commy.receive import ChannelFrame, frame_from_params
+from .connection import ConnectionSpec, SpawnConfig, TopicConnectionManager
+from .listener import ChannelListener
+from .receive import ChannelFrame, frame_from_params
 
 PLATFORM_NAME = "commy"
 PLATFORM_LABEL = "Commy"
@@ -161,7 +161,7 @@ async def connect(self) -> bool:
         brings the listener up.
         """
         if self._connection_manager is None:
-            from commy.transport import make_listener, make_manager
+            from .transport import make_listener, make_manager
 
             config = SpawnConfig.from_env()
             self._connection_manager = make_manager(config, self.receive_channel_notification)

clients/hermes/commy/connection.py

@@ -27,7 +27,7 @@
 from dataclasses import dataclass, field
 from typing import Awaitable, Callable, Mapping, Optional, Protocol
 
-from commy.naming import deterministic_bot_name
+from .naming import deterministic_bot_name
 
 # A `{content, meta}` inbound frame — the same shape the receive path
 # (`CommyAdapter.receive_channel_notification`) consumes. It rides under

clients/hermes/commy/listener.py

@@ -22,14 +22,14 @@
 
 from typing import Awaitable, Callable, Set, Tuple
 
-from commy.connection import (
+from .connection import (
     ConnectionSpec,
     Frame,
     SpawnConfig,
     TransportFactory,
 )
-from commy.naming import deterministic_listener_name
-from commy.receive import frame_from_params
+from .naming import deterministic_listener_name
+from .receive import frame_from_params
 
 # The boot listener owns no single topic, so its ConnectionSpec.topic is empty.
 _LISTENER_TOPIC = ""

clients/hermes/commy/session.py

@@ -29,7 +29,7 @@
 from mcp import ClientSession
 from mcp.types import Notification, ServerNotificationType
 
-from commy.receive import NOTIFICATION_METHOD
+from .receive import NOTIFICATION_METHOD
 
 
 class ChannelFrameParams(pydantic.BaseModel):

clients/hermes/commy/transport.py

@@ -35,7 +35,7 @@
 from collections.abc import Mapping
 from typing import IO, Optional
 
-from commy.connection import (
+from .connection import (
     Clock,
     ConnectionSpec,
     Frame,
@@ -44,7 +44,7 @@
     TopicConnectionManager,
     TransportFactory,
 )
-from commy.listener import ChannelListener, OwnedKeys, SpawnTrigger, build_listener_spec
+from .listener import ChannelListener, OwnedKeys, SpawnTrigger, build_listener_spec
 
 _STOP_GRACE_SECONDS = 5.0
 
@@ -115,7 +115,7 @@ async def _run(self) -> None:
         from mcp import StdioServerParameters
         from mcp.client.stdio import stdio_client
 
-        from commy.session import ChannelAwareClientSession
+        from .session import ChannelAwareClientSession
 
         server = StdioServerParameters(
             command=self._spec.command,

clients/hermes/pyproject.toml

@@ -10,6 +10,27 @@ requires-python = ">=3.11"
 # bundle or pin `hermes-agent` (or its tree). See README for the test recipe.
 dependencies = []
 
+# Hermes discovers plugins by scanning this entry-point group
+# (importlib.metadata.entry_points → ep.load() → register(ctx); see
+# hermes_cli/plugins.py). The value is the importable module that exposes
+# `register`. This is the recommended distribution mechanism (comms-i8qn):
+# installed via pip or — on the pod — via `services.hermes-agent.extraPythonPackages`,
+# then activated with `hermes plugins enable commy-platform`.
+[project.entry-points."hermes_agent.plugins"]
+commy-platform = "commy"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["commy"]
+
+[tool.setuptools.package-data]
+# Ship the manifest with the wheel for introspection and the directory-install
+# fallback; entry-point discovery itself does not read it.
+commy = ["plugin.yaml"]
+
 [dependency-groups]
 # `mcp` is the MCP Python SDK the per-topic transport (connection lifecycle,
 # comms-a7j.5) drives. It is NOT a runtime dependency of the plugin: the pod's
@@ -18,11 +39,6 @@ dependencies = []
 # tests can import the real SDK and run a real stub-server subprocess.
 dev = ["pytest>=8", "pyyaml>=6", "ruff>=0.6", "mcp>=1.2"]
 
-[tool.uv]
-# Plugin payload is loaded by Hermes via directory scan, not pip-installed as a
-# wheel — so this is a non-package (virtual) uv project: deps + tooling only.
-package = false
-
 [tool.pytest.ini_options]
 pythonpath = ["."]
 testpaths = ["tests"]

clients/hermes/tests/test_install_layout.py

@@ -0,0 +1,45 @@
+"""The plugin is discoverable + loadable via Hermes's entry-point mechanism.
+
+Hermes finds pip/Nix-installed plugins by scanning the ``hermes_agent.plugins``
+entry-point group with ``importlib.metadata.entry_points`` and loading each via
+``ep.load()`` → ``register(ctx)`` (see hermes_cli/plugins.py
+``_scan_entry_points`` / ``_load_entrypoint_module``). This is the documented
+*recommended* distribution path (comms-i8qn): the package declares the entry
+point in ``pyproject.toml`` and is consumed on the pod via
+``services.hermes-agent.extraPythonPackages``. ``hermes plugins enable
+commy-platform`` then activates it.
+
+Requires the package installed in the environment (``scripts/test.sh``'s
+``uv sync`` builds it) so the entry point is present in ``importlib.metadata``.
+"""
+
+import importlib.metadata
+
+ENTRY_POINT_GROUP = "hermes_agent.plugins"
+ENTRY_POINT_NAME = "commy-platform"
+
+
+def _commy_entry_point() -> importlib.metadata.EntryPoint | None:
+    eps = importlib.metadata.entry_points(group=ENTRY_POINT_GROUP)
+    return next((ep for ep in eps if ep.name == ENTRY_POINT_NAME), None)
+
+
+def test_plugin_advertises_hermes_entry_point():
+    ep = _commy_entry_point()
+    assert ep is not None, (
+        f"no '{ENTRY_POINT_NAME}' entry point in group '{ENTRY_POINT_GROUP}'; "
+        "Hermes discovers entry-point plugins via importlib.metadata, so the "
+        "package must declare it in pyproject.toml"
+    )
+
+
+def test_entry_point_loads_and_exposes_register():
+    ep = _commy_entry_point()
+    assert ep is not None
+    loaded = ep.load()
+    register = getattr(loaded, "register", None)
+    assert callable(register), (
+        "the entry-point target must expose a callable register(ctx) — "
+        "Hermes loads the plugin with ep.load() then calls "
+        "getattr(module, 'register')(ctx)"
+    )