hermes-platform-stagewhisper 0.43.0

StageWhisper Hermes Platform Adapter

Hermes platform adapter that exposes the StageWhisper desktop app as a first-class messaging surface for your Hermes Agent. Live-call transcripts arrive on a :reasoning chat thread, in-call chat arrives on a :chat thread, and the agent's reply is delivered back to the client over an SSE reply stream it holds open, or POSTed to a callback URL if the client's request asked for one.

Install

Install into the Hermes gateway's own venv, the same one that runs hermes_cli.main gateway run. Not pipx: a pipx install is isolated, so the gateway cannot import the adapter.

uv pip install --python <hermes-venv>/bin/python hermes-platform-stagewhisper
<hermes-venv>/bin/stagewhisper-hermes-install

Hermes creates its venv with uv, so that venv has no pip binary and no pip module. Use uv pip install --python as shown, not <hermes-venv>/bin/pip.

The installer drops a minimal shim into ~/.hermes/plugins/stagewhisper/:

• PLUGIN.yaml
• adapter.py (6-line shim that re-exports the in-package adapter)

Re-running the uv pip install upgrades the adapter without re-running the installer. stagewhisper-hermes-install --uninstall removes the shim.

Configure

Required environment variables (set in ~/.hermes/.env or via hermes config):

Optional:

After setting the env vars, restart Hermes. hermes status will list StageWhisper (plugin) - connected.

Wire protocol

The client posts to http://127.0.0.1:<port>/v1/incoming with bearer auth. Three event reasons:

• transcript_chunk (only is_final: true routes through the agent) -> chat thread sw:<session>:reasoning
• chat_message -> chat thread sw:<session>:chat
• system_prelude -> stashed and prepended to the next inbound message for that session as [Context: ...], then cleared

By default the adapter writes replies to GET /v1/events?session_id=<session>. The client opens the stream with the same bearer token before dispatch and shares it across pending tasks in that session. The stream closes after the last task settles. On connect, every currently retained terminal answer for that session is replayed, oldest first; that is the whole recovery story. Typing and tool activity are live-only and never consume the retained backlog.

If the inbound event instead carries a callback block ({"url": ..., "token": ...}), the adapter POSTs the reply to <callback.url>/tasks/<task_id> with that token as bearer auth, and retries on transient failures. callback.url must be a loopback URL, or an origin listed in STAGEWHISPER_ALLOW_CALLBACK_URLS. StageWhisper's own desktop and mobile apps never send a callback block; they always read from the stream.

Local development

uv run --with pytest --with pytest-asyncio python -m pytest -v