Metadata-Version: 2.4
Name: hermes-plugin-stagewhisper
Version: 0.12.0
Summary: StageWhisper BYO AI relay plugin for Hermes Agent
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: cryptography>=42

## StageWhisper Hermes Plugin

Hermes plugin that connects to StageWhisper's encrypted reasoning relay. Receives live call reasoning jobs, executes them via your configured LLM provider, and returns results.

### Install

```bash
pipx run --spec hermes-plugin-stagewhisper stagewhisper-hermes-install
```

The installer finds the active `hermes` command, copies the plugin into `~/.hermes/plugins/stagewhisper`, and enables it.

If you use `uv`, this equivalent command is faster:

```bash
uvx --from hermes-plugin-stagewhisper stagewhisper-hermes-install
```

If neither `pipx` nor `uv` is installed:

```bash
python3 -m venv /tmp/stagewhisper-hermes-install
/tmp/stagewhisper-hermes-install/bin/python -m pip install -U hermes-plugin-stagewhisper
/tmp/stagewhisper-hermes-install/bin/stagewhisper-hermes-install
```

On Ubuntu, install `python3-venv` first if `python3 -m venv` is unavailable.

For local development, copy or symlink `hermes_stagewhisper_plugin/` into `~/.hermes/plugins/stagewhisper/`.

Configure these in your shell or `~/.hermes/.env`:
- `OPENAI_API_KEY` — Your LLM provider API key
- `OPENAI_BASE_URL` — API base URL (default: `https://api.openai.com/v1`)
- `STAGEWHISPER_REASONING_MODEL` — Model override (default: `gpt-4o`)
- `STAGEWHISPER_API_URL` — StageWhisper backend override (normally set by pairing)

### Pair

1. In StageWhisper desktop → Settings → Assistant → Hermes → **Generate Pairing Code**
2. On your Hermes host:

```bash
stagewhisper-hermes pair --code <CODE>
```

The plugin exchanges X25519 keys and stores the relay config.

The pair command restarts the Hermes gateway after a successful pair. If that restart fails, run:

```bash
hermes gateway restart
```

### Verify

```bash
stagewhisper-hermes status
```

### BYO mode (end-to-end encrypted reasoning)

When the desktop is in BYO reasoning mode, all analysis prompts are encrypted end-to-end between the desktop and the plugin. The plugin decrypts, runs the prompt through your LLM, encrypts the result, and posts it back.

### Unpair

```bash
stagewhisper-hermes unpair
```

### Tools for the LLM

The plugin registers three tools Hermes's LLM can call:
- `stagewhisper_pair(code, label, api_url)` — Pair with StageWhisper desktop
- `stagewhisper_relay(action)` — Start/stop/status/restart the relay
- `stagewhisper_unpair()` — Unpair and clear config

### Architecture

```
Desktop (E2EE) ↔ StageWhisper Backend (blind relay) ↔ Hermes Plugin (this)
                                                          ├── SSE stream consumer
                                                          ├── XChaCha20-Poly1305 crypto
                                                          └── OpenAI-compatible LLM provider
```
