Metadata-Version: 2.4
Name: hermes-plugin-stagewhisper
Version: 0.29.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>=43
Requires-Dist: pynacl>=1.5

## StageWhisper Hermes Plugin

Hermes plugin that connects to StageWhisper's encrypted reasoning relay. Receives live call reasoning jobs, executes them via Hermes's configured main LLM provider (the same model Hermes itself uses), 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/`.

The plugin reasoning route uses Hermes's main provider — whichever you configured with `hermes config` (Nous Portal, OpenRouter, OpenAI, Anthropic, Codex, Ollama, etc.). No additional LLM credentials are needed.

Optional overrides in `~/.hermes/.env`:
- `STAGEWHISPER_REASONING_MODEL` — Force a specific model instead of Hermes's main default
- `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
                                                          └── agent.auxiliary_client.async_call_llm(provider="main")
```
