Metadata-Version: 2.4
Name: wishee-hermes-connector
Version: 0.1.0
Summary: Connect a Hermes agent to the Wishee bridge via reverse WebSocket
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: websockets>=12.0
Requires-Dist: qrcode>=7.4
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# wishee-hermes-connector

Connect a [Hermes](https://github.com/NousResearch/hermes) agent to the Wishee bridge
(`openclaw-bridge`) over a reverse WebSocket — the Hermes counterpart of
`@wishee-ai/openclaw-connector`. The bridge drives the agent (`chat.send` /
`chat.history` / `sessions.reset`) and receives its replies (`task-result`).

Requires no changes to the bridge or to hermes-agent core.

## How it works

The connector is a Hermes **platform adapter** (runs inside the `hermes gateway`
process). It dials the bridge, does the `hello`/`welcome` handshake, then:

- `chat.send` → mints a `runId`, answers immediately, runs the agent turn, and
  emits a `task-result` event when the turn finishes (the bridge's device-push path).
- `chat.history` / `sessions.reset` → reads / clears the Hermes session store.

From the bridge's perspective a Hermes agent is indistinguishable from an
OpenClaw instance: same `/api/bind`, same `hello`, same RPCs, same event frames.

The transport **auto-reconnects**: an unexpected socket close (bridge restart,
network drop) re-dials with capped exponential backoff and re-runs the
`hello`/`welcome` handshake. A deliberate shutdown never reconnects.

## Install

```bash
pip install wishee-hermes-connector   # into your Hermes environment
```

## Enable

1. Add `wishee` to `plugins.enabled` in your Hermes `config.yaml` (entry-point
   plugins are opt-in).
2. Optionally set `WISHEE_BRIDGE_URL` to override the default
   (`wss://ai-bridge.wishee.com.cn/ws`).
3. Run `hermes gateway`. On first run it prints a QR code — scan it to bind this
   instance to the bridge (via the bridge's `/api/bind`). Identity is stored at
   `~/.hermes/wishee-connector/binding.json`.

## Scope

v1 emits `task-result` on each completed turn (the bridge's device-push path).
Live streaming (`agent` progress events) is out of scope for v1.

## Development

```bash
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python -e /path/to/hermes-agent
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest -q
```
