capsule-hermes 0.4.0__tar.gz

capsule_hermes-0.4.0/.gitignore

@@ -0,0 +1,278 @@
+# Local Docker data
+.docker/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!apps/portal/src/lib/
+!apps/backend-backoffice/ui/src/lib/
+!libs/ui/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+.nx/cache
+.nx/workspace-data
+vite.config.*.timestamp*
+vitest.config.*.timestamp*
+test-output
+
+# Ignore cursor IDE files, for now..
+.cursor/
+
+# TypeScript cache
+*.tsbuildinfo
+out-tsc/
+
+# Backoffice UI build output (generated by backoffice-ui:build)
+apps/backend-backoffice/public/
+
+.vscode/settings.json
+.vscode/mcp.json
+
+.github/instructions/*.instructions.md
+instructions.txt
+node_modules
+
+# Vite build output assets
+apps/backend-backoffice/public/assets/
+
+# Figma temporary assets
+figma-assets/
+tmp-figma-assets/
+apps/portal/logs
+logs
+
+# CDN assets (synced from GCS for local development)
+cdn/
+
+# Private assets / files for local development, not meant to be shared
+.local/
+
+# Claude Code (machine-specific)
+.claude/teams/*/inboxes/
+.claude/settings.local.json
+CLAUDE.local.md
+.worktrees/
+
+# Pinned protoc binary cache
+.protoc/
+
+
+.claude/scheduled_tasks.lock
+.claude/tmp/
+.claude/worktrees/
+# Test artifacts
+screenshots/
+libs/graph/src/**/__screenshots__/
+!libs/graph/src/components/__tests__/__screenshots__/
+.playwright-mcp/
+
+# Designer prototypes / scratch docs (kept local, not tracked)
+/notification-empty-state.html
+/notification-channels-empty-state.html
+/notification-popover-prototype.html
+/capsule-qr.html
+/policy-violations-empty-states.html
+/figma-prompt-notification-states.md
+/discovery-node-edge-audit.md
+
+# UI lib test CSS — built fresh by libs/ui `npm run build:test-css` before each vitest run
+libs/ui/playwright/output.css
+libs/graph/storybook-static
+
+# Codex
+.agents/
+.codex/
+AGENTS.md
+.claude/worktrees
+.nx/polygraph
+.nx/self-healing

capsule_hermes-0.4.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,44 @@
+# 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/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "capsule-hermes"
+version = "0.4.0"
+description = "Capsule plugin for Hermes — forwards hook events to the Capsule agentsecurity service for centralized policy enforcement and audit."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Capsule Security" }]
+keywords = [
+    "hermes",
+    "hermes-plugin",
+    "capsule",
+    "security",
+    "policy",
+    "agent-security",
+]
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.urls]
+Repository = "https://github.com/capsulesecurity/capsule"
+Documentation = "https://docs.capsulesecurity.io/guides/hermes"
+
+[project.entry-points."hermes_agent.plugins"]
+capsule = "capsule_hermes"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/capsule_hermes"]

capsule_hermes-0.4.0/src/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-0.4.0/src/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-0.4.0/src/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-0.4.0/src/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-0.4.0/src/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