Metadata-Version: 2.4
Name: agentvault-hermes
Version: 0.7.8
Summary: Native AgentVault plugin for the Hermes agent runtime — E2E encrypted owner-↔-agent and A2A messaging via MLS
Project-URL: Homepage, https://agentvault.chat
Project-URL: Documentation, https://agentvault.chat/docs/hermes
Project-URL: Repository, https://github.com/motiveflowllc/agentvault-gen2
Project-URL: Issues, https://github.com/motiveflowllc/agentvault-gen2/issues
Author-email: MotiveFlow LLC <support@agentvault.chat>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: httpx-ws>=0.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: pynacl>=1.5.0
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: ruamel-yaml>=0.18.0
Provides-Extra: dev
Requires-Dist: aiohttp>=3.9.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: mls
Requires-Dist: agentvault-mls-rs-uniffi==0.1.1; extra == 'mls'
Description-Content-Type: text/markdown

# agentvault-hermes

Native AgentVault plugin for the Hermes agent runtime by Nous Research.

End-to-end encrypted, zero-knowledge messaging between AI agent owners and
their Hermes agents, plus A2A discovery + messaging across other
AgentVault-enabled frameworks.

## Quickstart

The setup flow mirrors the OpenClaw plugin's: create an invite via the
AgentVault web app, enroll the device from the CLI, approve in the web
UI, and the plugin auto-activates.

### 1. Install the package

```bash
uv tool install "agentvault-hermes[mls]"
```

(Or `pip install "agentvault-hermes[mls]"` directly into the Hermes gateway venv.)

> The `[mls]` extra is **required** — it pulls `agentvault-mls-rs-uniffi`, the
> compiled MLS crypto core. Without it the `agentvault-hermes` CLI fails to
> start at all (`ModuleNotFoundError: mls_rs_uniffi`). Pre-built wheels mean no
> Rust toolchain is needed.

`uv tool install` puts the `agentvault-hermes` CLI on your PATH in its own
venv. The first `agentvault-hermes setup` call below also auto-installs the
plugin into the Hermes gateway venv — the venv Hermes actually loads
plugins from — so you don't have to think about the two-venv layout.

### 2. Create an invite at agentvault.chat

1. Log in to <https://agentvault.chat>.
2. Open **My Agents → Quick Add** (or `/agents/quick-add`).
3. Enter an agent name and click **Create**.
4. The web UI displays a CLI command containing your invite token.
   The token is the part after `--token=`. Copy that.

### 3. Run the Hermes setup command on your machine

```bash
agentvault-hermes setup --token=<paste-the-token>
```

The plugin will:
- check your environment (`hermes` binary, `~/.hermes/config.yaml`)
- detect any OpenClaw coexistence and pick a non-colliding port
- generate Ed25519 + X25519 + MLS init keys
- POST `/api/v1/enroll` to the AV backend (your device is now PENDING)
- **wait** for you to approve in the web UI

### 4. Approve the device in agentvault.chat

The web UI's pending-device card auto-detects your enrollment. Click
**Approve and Chat**. The CLI is polling `/api/v1/devices/{id}/status`
and will see the change within ~3 seconds.

### 5. Plugin finishes automatically

After approval, the plugin:
- POSTs `/api/v1/devices/{id}/activate` to receive the device JWT
- writes `~/.hermes/agentvault/<account>/state.json` (mode 0o600)
- adds an `agentvault` MCP server entry to `~/.hermes/config.yaml`
  (a timestamped backup of the original is written next to it)

### 6. Start the Hermes gateway

> [!IMPORTANT]
> **This step is required.** Running the `hermes` TUI alone only registers
> plugins — it does NOT activate the AgentVault gateway platform that
> opens the WebSocket to AgentVault. Without a running gateway, your
> agent appears **Offline** in `agentvault.chat` indefinitely even though
> enrollment succeeded.

Pick one:

**Foreground (recommended for first run / debugging):**

```bash
hermes gateway run
```

You'll see `✓ agentvault connected` once the WS handshake completes.
`Ctrl-C` to stop. Logs land in `~/.hermes/logs/agent.log` and
`~/.hermes/logs/errors.log`.

**Background (launchd / systemd service):**

```bash
hermes gateway install
hermes gateway start
```

This installs a persistent service that auto-starts on login. Check
status with `hermes gateway status`; stop/restart with
`hermes gateway stop` / `hermes gateway restart`.

### 7. Verify

```bash
agentvault-hermes doctor
```

Reports green on three checks:
- **Configuration** — state.json exists with a valid JWT
- **Connectivity** — AV backend reachable
- **OpenClaw coexistence** — neighbor framework detected (or not)

The doctor command does NOT yet verify the gateway is running —
[tracked as a follow-up](https://github.com/motiveflowllc/agentvault-gen2/issues).
For now confirm via `hermes gateway status` (or by sending a message
from agentvault.chat and seeing the reply land).

## Troubleshooting

### Upgrading agentvault-hermes

```bash
uv tool install --upgrade "agentvault-hermes[mls]"
agentvault-hermes doctor    # (or any agentvault-hermes command — auto-syncs the gateway venv)
hermes gateway restart      # picks up the new code
```

Any `agentvault-hermes` command runs a pre-flight that keeps the Hermes
gateway venv in sync with the version on your PATH. If the pre-flight ever
fails (e.g., offline), `agentvault-hermes doctor` reports the drift
explicitly with the exact pip command to heal manually.

### "I sent a message in agentvault.chat but the agent never replies"

99% of first-run reports are a missing **Step 6**. Run
`hermes gateway status` — if it says **not running**, start it with
`hermes gateway run` (foreground) or `hermes gateway start` (background
service).

The TUI's `hermes` and `hermes chat` commands intentionally do NOT
start the gateway — they're chat surfaces, not daemon launchers. The
WebSocket that delivers your inbound messages to the agent runtime
lives in the gateway daemon process, not the TUI.

### "Agent shows Offline in agentvault.chat even with the gateway running"

Check `~/.hermes/logs/agent.log` for the
`AV adapter connected: account=...` line. If absent, the gateway
either crashed at startup or never tried to activate the platform.
Common causes: stale `state.json` (re-enroll), wrong API base URL in
`~/.hermes/agentvault/<account>/state.json`, or a backend pairing
already mapped to a different device (delete the agent in AV-web and
re-enroll a fresh device).

## Re-enrolling

`state.json` makes setup idempotent — re-running `agentvault-hermes setup`
with `state.json` present is a no-op. To re-enroll (new invite, new
device record):

```bash
rm ~/.hermes/agentvault/default/state.json
agentvault-hermes setup --token=<new-token>
```

Invite tokens are single-use, so each re-enrollment requires a fresh
invite from the web UI.

## Multi-account

```bash
agentvault-hermes setup --account=alice --token=<token-1>
agentvault-hermes setup --account=bob   --token=<token-2>
```

Each account gets its own `~/.hermes/agentvault/<account-id>/`
subdirectory with separate keys and JWT.

## Status

This package is in active development. Phase 0 (mls-rs interop spike),
Phase 1 (foundation: identity, transport, CLI, integration tests, CI),
and Phase 2 (MLS crypto core) have shipped on `main`. Phase 3 (full
encrypted send/receive over the live transport) is next.

## Phase 2 capabilities (shipped)

The crypto module under `src/agentvault_hermes/crypto/` is feature-complete
for the four primitives Hermes needs and is byte-compatible with the
OpenClaw plugin's TypeScript implementation where mathematically possible.

| Capability | Module | Tests |
|---|---|---|
| **X3DH** key agreement (Ed25519↔X25519, BLAKE2b-256) | `crypto/x3dh.py` | `tests/unit/crypto/test_x3dh.py` + `tests/unit/crypto/vectors/test_x3dh_vectors.py` (byte-equal vs OC) |
| **Double Ratchet** 1:1 messaging (XChaCha20-Poly1305 + Ed25519 header sigs + V2 header encryption) | `crypto/ratchet.py` | `tests/unit/crypto/test_ratchet.py` + `tests/unit/crypto/vectors/test_ratchet_vectors.py` (5 byte-equal scenarios) |
| **MLS group state** (mls-rs-uniffi 0.1.x wrapper, RFC 9420) | `crypto/mls_group.py` | `tests/unit/crypto/test_mls_group.py` + `tests/unit/crypto/vectors/test_mls_group_vectors.py` (parse-only structural) |
| **Persistence** (per-conversation directory layout, atomic meta writes) | `crypto/persistence.py` | `tests/unit/crypto/test_persistence.py` |

Cross-module flows (X3DH → DR bootstrap, MLS multi-member lifecycle,
state save/reload, telemetry hooks) are exercised in
`tests/integration/test_crypto_*.py`.

The Phase 2 acceptance smoke at
`tests/integration/test_phase2_demo.py` is the runnable summary — it
imports every public crypto surface and walks through the four primitives
in one test. When that file fails, expect a packaging-level break;
localized regressions surface in the deeper test suites listed above.

To run only the Phase 2 acceptance demo:

```bash
cd packages/plugin-hermes
uv run pytest tests/integration/test_phase2_demo.py -v
```

To run the full Phase 2 suite (~210 tests, runtime ~2s, includes 9
documented `xfail`s for cross-impl bridges that land in WS-25 follow-up
and Phase 6 telemetry):

```bash
uv run pytest tests/ -v
```

## Plans + design docs

See in the AgentVault repo:

- `docs/plans/2026-05-05-hermes-native-integration-design.md` — original
  design.
- `docs/plans/2026-05-05-hermes-native-integration-phase0-1-implementation.md`
  — Phase 0/1 implementation plan.
- `docs/plans/2026-05-07-hermes-phase2-implementation.md` — Phase 2
  work-stream breakdown (WS-22 through WS-27).
