capsule-hermes 0.4.0__py3-none-any.whl

capsule_hermes/__init__.py

@@ -0,0 +1,146 @@
+"""Capsule plugin for the Hermes autonomous AI agent runtime.
+
+Forwards Hermes hook events to the Capsule agentsecurity service for centralized
+policy enforcement and audit.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import uuid
+from typing import Any, Mapping
+
+from .config import CapsulePluginConfig
+from .normalize import normalize
+from .transport import CapsuleTransport
+from .types import HermesHookEnvelope
+
+PLUGIN_ID = "capsule"
+PLUGIN_VERSION = "0.4.0"
+
+_BLOCKING_HOOKS = ("pre_tool_call",)
+_OBSERVATION_HOOKS = (
+    "pre_llm_call",
+    "pre_gateway_dispatch",
+    "pre_approval_request",
+    "post_tool_call",
+    "post_llm_call",
+    "post_approval_response",
+    "subagent_stop",
+    "on_session_start",
+    "on_session_end",
+    "on_session_finalize",
+    "on_session_reset",
+)
+
+logger = logging.getLogger("capsule_hermes")
+
+
+def _load_config_block() -> Mapping[str, Any]:
+    """Read the `plugins.entries.capsule` block from Hermes' config.yaml.
+
+    Returns an empty dict when the block is absent so env vars can still drive
+    configuration in CI/dev environments.
+    """
+    try:
+        from hermes_cli.config import cfg_get, load_config  # type: ignore
+    except Exception:
+        return {}
+    try:
+        cfg = load_config()
+        block = cfg_get(cfg, "plugins", "entries", PLUGIN_ID, default={})
+        return block if isinstance(block, dict) else {}
+    except Exception:
+        return {}
+
+
+def _map_verdict(body: Any, block_on_risk: bool) -> dict | None:
+    """Translate a Capsule server response into a Hermes block directive."""
+    if not isinstance(body, Mapping):
+        return None
+    if body.get("block") is True and block_on_risk:
+        return {
+            "action": "block",
+            "message": body.get("blockReason") or "Blocked by Capsule policy",
+        }
+    return None
+
+
+def register(ctx: Any) -> None:
+    """Plugin entry point — called by Hermes during discovery."""
+    try:
+        cfg = CapsulePluginConfig.load(_load_config_block())
+    except ValueError as exc:
+        logger.warning("capsule_hermes: not registering hooks — %s", exc)
+        return
+
+    transport = CapsuleTransport(cfg)
+    user = cfg.user or os.environ.get("USER") or "unknown"
+
+    def dispatch(hook_event_name: str, payload: Mapping[str, Any]):
+        correlation_id = str(uuid.uuid4())
+        envelope = HermesHookEnvelope(
+            hook=normalize(hook_event_name, payload),
+            user=user,
+            plugin_version=PLUGIN_VERSION,
+        )
+        try:
+            return transport.post(envelope, correlation_id), correlation_id
+        except Exception as exc:
+            logger.error(
+                "capsule_hermes: request failed: %s (correlation_id=%s)",
+                exc,
+                correlation_id,
+            )
+            return None, correlation_id
+
+    def make_blocking_handler(name: str):
+        def handler(**kwargs: Any):
+            response, correlation_id = dispatch(name, kwargs)
+            if response is None:
+                return None if cfg.fail_open else {
+                    "action": "block",
+                    "message": "Capsule policy unavailable",
+                }
+            if not response.ok:
+                logger.warning(
+                    "capsule_hermes: server returned %s (correlation_id=%s)",
+                    response.status,
+                    correlation_id,
+                )
+                return None if cfg.fail_open else {
+                    "action": "block",
+                    "message": "Capsule policy unavailable",
+                }
+            return _map_verdict(response.body, cfg.block_on_risk)
+
+        handler.__name__ = f"capsule_{name}"
+        return handler
+
+    def make_observation_handler(name: str):
+        def handler(**kwargs: Any):
+            t = threading.Thread(
+                target=dispatch, args=(name, kwargs), daemon=True, name=f"capsule-{name}"
+            )
+            t.start()
+            return None
+
+        handler.__name__ = f"capsule_{name}"
+        return handler
+
+    for name in _BLOCKING_HOOKS:
+        ctx.register_hook(name, make_blocking_handler(name))
+    for name in _OBSERVATION_HOOKS:
+        ctx.register_hook(name, make_observation_handler(name))
+
+    logger.info(
+        "capsule_hermes: registered (endpoint=%s, block_on_risk=%s, fail_open=%s)",
+        cfg.endpoint,
+        cfg.block_on_risk,
+        cfg.fail_open,
+    )
+
+
+__all__ = ["register", "CapsulePluginConfig", "PLUGIN_ID", "PLUGIN_VERSION"]

capsule_hermes/config.py

@@ -0,0 +1,69 @@
+"""Plugin configuration parsing for the Capsule Hermes plugin."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class CapsulePluginConfig:
+    """Validated Capsule plugin configuration.
+
+    Source precedence (highest first): env vars `CAPSULE_HERMES_*`, then the
+    `plugins.entries.capsule.*` block in Hermes' config.yaml.
+    """
+
+    endpoint: str
+    token: str
+    block_on_risk: bool = True
+    fail_open: bool = True
+    timeout_ms: int = 5000
+    user: str | None = None
+
+    @classmethod
+    def load(cls, raw: Mapping[str, Any] | None = None) -> "CapsulePluginConfig":
+        raw = raw or {}
+        endpoint = os.environ.get("CAPSULE_HERMES_ENDPOINT") or raw.get("endpoint")
+        token = os.environ.get("CAPSULE_HERMES_TOKEN") or raw.get("token")
+        if not isinstance(endpoint, str) or not endpoint:
+            raise ValueError(
+                "capsule_hermes: endpoint missing (set CAPSULE_HERMES_ENDPOINT or "
+                "plugins.entries.capsule.endpoint in config.yaml)"
+            )
+        if not isinstance(token, str) or not token:
+            raise ValueError(
+                "capsule_hermes: token missing (set CAPSULE_HERMES_TOKEN or "
+                "plugins.entries.capsule.token in config.yaml)"
+            )
+
+        def _bool(key: str, default: bool) -> bool:
+            env = os.environ.get(f"CAPSULE_HERMES_{key.upper()}")
+            if env is not None:
+                return env.strip().lower() in {"1", "true", "yes", "on"}
+            v = raw.get(key, default)
+            return bool(v)
+
+        def _int(key: str, default: int) -> int:
+            env = os.environ.get(f"CAPSULE_HERMES_{key.upper()}")
+            if env is not None:
+                try:
+                    return int(env)
+                except ValueError:
+                    return default
+            v = raw.get(key, default)
+            try:
+                return int(v)
+            except (TypeError, ValueError):
+                return default
+
+        user_raw = raw.get("user")
+        return cls(
+            endpoint=endpoint,
+            token=token,
+            block_on_risk=_bool("block_on_risk", True),
+            fail_open=_bool("fail_open", True),
+            timeout_ms=_int("timeout_ms", 5000),
+            user=user_raw if isinstance(user_raw, str) else None,
+        )

capsule_hermes/normalize.py

@@ -0,0 +1,75 @@
+"""Normalize Hermes plugin-runtime kwargs into the Capsule backend DTO shape.
+
+The Hermes Python runtime calls plugin hooks with flat kwargs (e.g.
+`tool_name`, `args`, `session_id`, `task_id`). The Capsule agentsecurity
+service expects a normalized envelope with a `context` block, `params`
+instead of `args`, and a required ISO `timestamp`. This module owns that
+translation so the rest of the plugin can stay shape-agnostic.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+
+_CONTEXT_KEYS = (
+    "agent_id",
+    "session_id",
+    "run_id",
+    "parent_session_id",
+    "gateway",
+    "gateway_channel_id",
+    "user_id",
+    "trace_id",
+    "span_id",
+)
+
+
+def _iso_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _build_context(kwargs: Mapping[str, Any]) -> dict[str, Any]:
+    """Lift known context fields out of flat kwargs into a `context` dict.
+
+    `task_id` is mapped to `run_id` to match how the backend interprets the
+    per-task scope (a Hermes task ~= one agent run).
+    """
+    ctx: dict[str, Any] = {}
+    for key in _CONTEXT_KEYS:
+        v = kwargs.get(key)
+        if isinstance(v, str) and v:
+            ctx[key] = v
+    task_id = kwargs.get("task_id")
+    if isinstance(task_id, str) and task_id and "run_id" not in ctx:
+        ctx["run_id"] = task_id
+    return ctx
+
+
+def normalize(hook_event_name: str, kwargs: Mapping[str, Any]) -> dict[str, Any]:
+    """Return the backend-shaped payload for a Hermes hook invocation.
+
+    Rules applied to every hook:
+      * `hook_event_name` is set explicitly.
+      * `timestamp` is filled with ISO-now if Hermes did not provide one.
+      * `context` collects session/run/agent/gateway identifiers so the
+        backend's `extractSessionId` / `generateAgentExternalId` work.
+
+    Per-hook rules:
+      * `pre_tool_call` / `post_tool_call`: rename `args` to `params`.
+    """
+    payload: dict[str, Any] = {
+        k: v
+        for k, v in kwargs.items()
+        if k not in _CONTEXT_KEYS and k != "task_id"
+    }
+    payload["hook_event_name"] = hook_event_name
+    payload["context"] = _build_context(kwargs)
+    payload.setdefault("timestamp", _iso_now())
+
+    if hook_event_name in {"pre_tool_call", "post_tool_call"}:
+        if "args" in payload and "params" not in payload:
+            payload["params"] = payload.pop("args")
+
+    return payload

capsule_hermes/transport.py

@@ -0,0 +1,53 @@
+"""HTTP transport for forwarding Hermes hook events to the Capsule agentsecurity service."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from .config import CapsulePluginConfig
+from .types import HermesHookEnvelope
+
+
+@dataclass(frozen=True)
+class CapsuleResponse:
+    ok: bool
+    status: int
+    body: Any
+
+
+class CapsuleTransport:
+    """Synchronous HTTP client that posts hook envelopes to Capsule.
+
+    Hermes invokes hook callbacks synchronously, so the transport is sync too.
+    Non-2xx responses are surfaced via `CapsuleResponse.ok` rather than raised
+    — the plugin's dispatch wrapper decides fail-open / fail-closed.
+    """
+
+    def __init__(self, config: CapsulePluginConfig) -> None:
+        self._config = config
+        url = config.endpoint.rstrip("/")
+        if not url.endswith("/hermes/hooks/events") and not url.endswith("/v1/hermes/hooks/events"):
+            url = f"{url}/v1/hermes/hooks/events"
+        self._url = url
+
+    def post(self, envelope: HermesHookEnvelope, correlation_id: str) -> CapsuleResponse:
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._config.token}",
+            "X-Correlation-Id": correlation_id,
+        }
+        timeout = self._config.timeout_ms / 1000.0
+        with httpx.Client(timeout=timeout) as client:
+            response = client.post(self._url, json=envelope.to_dict(), headers=headers)
+            body: Any = None
+            text = response.text
+            if text:
+                try:
+                    body = json.loads(text)
+                except json.JSONDecodeError:
+                    body = text
+            return CapsuleResponse(ok=response.is_success, status=response.status_code, body=body)

capsule_hermes/types.py

@@ -0,0 +1,31 @@
+"""Shared payload shapes for the Capsule Hermes plugin."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class HermesHookEnvelope:
+    """Top-level envelope POSTed to `/v1/hermes/hooks/events`.
+
+    Mirrors the request DTO the Capsule agentsecurity service accepts: the raw
+    Hermes hook payload plus the user identity and plugin version captured at
+    the source.
+    """
+
+    hook: Mapping[str, Any]
+    user: str
+    plugin_version: str
+    transcript_lines: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "hook": dict(self.hook),
+            "user": self.user,
+            "plugin_version": self.plugin_version,
+        }
+        if self.transcript_lines:
+            payload["transcript_lines"] = list(self.transcript_lines)
+        return payload

capsule_hermes-0.4.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: capsule-hermes
+Version: 0.4.0
+Summary: Capsule plugin for Hermes — forwards hook events to the Capsule agentsecurity service for centralized policy enforcement and audit.
+Project-URL: Repository, https://github.com/capsulesecurity/capsule
+Project-URL: Documentation, https://docs.capsulesecurity.io/guides/hermes
+Author: Capsule Security
+License: Apache-2.0
+Keywords: agent-security,capsule,hermes,hermes-plugin,policy,security
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# capsule-hermes
+
+Capsule plugin for the [Hermes](https://nousresearch.com/hermes) autonomous AI agent runtime. Forwards Hermes hook events to the Capsule `agentsecurity` service for centralized policy enforcement and audit.
+
+## Install
+
+```bash
+pip install capsule-hermes
+```
+
+## Configure
+
+Register the plugin in your Hermes runtime config (e.g. `hermes.yaml`):
+
+```yaml
+plugins:
+  - module: capsule_hermes
+    config:
+      endpoint: "https://agents.capsulesecurity.io/v1/hermes/hooks/events"
+      token: ${CAPSULE_HERMES_TOKEN}
+```
+
+The `endpoint` and `token` values are issued by Capsule when you install the Hermes integration in the Capsule portal (**Integrations → Hermes**).
+
+### Optional config
+
+| Key             | Default | Description                                                                                              |
+| --------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `block_on_risk` | `true`  | Apply server `block` verdicts. Set to `false` to run the plugin in observe-only mode.                    |
+| `fail_open`     | `true`  | Allow the event through if Capsule is unreachable or returns a non-2xx response. Set to `false` to fail closed. |
+| `timeout_ms`    | `5000`  | Per-request HTTP timeout in milliseconds.                                                                 |
+
+## Hooks covered
+
+The plugin registers handlers for the Hermes runtime hooks Capsule supports:
+
+- **Blocking:** `pre_tool_call`, `pre_llm_call`, `pre_gateway_dispatch`, `pre_approval_request`
+- **Observation:** `post_tool_call`, `post_llm_call`, `post_approval_response`, `subagent_stop`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`
+
+Blocking hooks await Capsule's verdict and return `{"action": "block", "message": ...}` to Hermes when the server denies the action. Observation hooks dispatch fire-and-forget so telemetry never stalls the agent.
+
+## License
+
+Apache-2.0.

capsule_hermes-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+capsule_hermes/__init__.py,sha256=_pHdzkRSxuv69cOaIOnUBf396dkGJUe1cPy3AJhH83w,4540
+capsule_hermes/config.py,sha256=hx-lAATDwIj8H1gKl1a_hBijcidLbXAhmaKMx-frbnI,2413
+capsule_hermes/normalize.py,sha256=SiqUOgzCqWhK8qSGn_7Weeny-TYGXJhk-UybVe84SQU,2430
+capsule_hermes/transport.py,sha256=xTT1ADE7b0NWam_3RywSF7NrW8ZyEf9NtG65XaHW6Ls,1821
+capsule_hermes/types.py,sha256=7JTAXVUE_F2httNIod25SR0f4HnTFTEtNDoDx9oFWb4,929
+capsule_hermes-0.4.0.dist-info/METADATA,sha256=XHIxJ5RtcCkm93idvoCh0t4m87nxZg13GPf0eu93bYA,2728
+capsule_hermes-0.4.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+capsule_hermes-0.4.0.dist-info/entry_points.txt,sha256=C9gefFW5FPZ5bAXkd0WX4hh_viS5W0x3iI-wZ-t-RYM,48
+capsule_hermes-0.4.0.dist-info/RECORD,,

capsule_hermes-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

capsule_hermes-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+capsule = capsule_hermes