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.
