Metadata-Version: 2.4
Name: clawhive-hermes-plugin
Version: 0.1.2
Summary: ClawHive platform adapter plugin for Hermes Agent
Author: ClawHive
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/optimalAIs/clawhive
Project-URL: Issues, https://github.com/optimalAIs/clawhive/issues
Keywords: clawhive,hermes-agent,plugin,platform-adapter
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: qr
Requires-Dist: qrcode>=7.4; extra == "qr"
Provides-Extra: realtime
Requires-Dist: websockets>=12; extra == "realtime"
Provides-Extra: all
Requires-Dist: qrcode>=7.4; extra == "all"
Requires-Dist: websockets>=12; extra == "all"

# ClawHive Hermes Plugin

This plugin lets a Hermes runtime register as a ClawHive runtime node, sync Hermes profiles into ClawHive, receive ClawHive user messages through the Hermes platform adapter connection, and write Hermes replies back through the ClawHive message API. It is shaped for the Hermes directory plugin loader: `plugin.yaml` plus a root `__init__.py` that exposes `register(ctx)`.

## Install Locally

Copy this directory into a Hermes plugin path:

```bash
mkdir -p ~/.hermes/plugins/clawhive
cp -R hermes-plugin/* ~/.hermes/plugins/clawhive/
```

## Install From a Local Wheel

The plugin is packaged as a Python distribution because Hermes plugins are
Python modules. Build and install it locally before publishing to PyPI:

```bash
cd hermes-plugin
python -m build
python -m pip install dist/clawhive_hermes_plugin-0.1.2-py3-none-any.whl
```

Hermes can discover the package when the wheel is installed into the same
Python environment that runs Hermes, through the `hermes_agent.plugins` entry
point:

```bash
python - <<'PY'
import importlib.metadata as md
print(md.entry_points().select(group="hermes_agent.plugins")["clawhive"])
PY
```

For end-user installs where the package may be installed outside the Hermes
virtual environment, use the packaged installer to create a normal Hermes
directory plugin:

```bash
clawhive-hermes install
hermes plugins enable clawhive
```

Re-run with `--force` to replace an existing `~/.hermes/plugins/clawhive`
directory.

## Authorize Locally

Enable the plugin in Hermes, then run the ClawHive authorization command:

```bash
hermes clawhive authorize
```

This starts the same ClawHive device-code authorization flow used by the OpenClaw plugin: Hermes prints a QR code and fallback code, the user scans it in the already signed-in ClawHive app and explicitly approves the displayed node, and the command stores the returned plugin token in the Hermes `.env` file. The approval also pairs the scanning phone to this node. Restart the Hermes gateway after authorization so the platform adapter can call `plugin-register` and sync agents.

Status can be checked with:

```bash
hermes clawhive status
```

To move Hermes to another ClawHive account, first preview and then confirm the
unlink:

```bash
hermes clawhive unlink
hermes clawhive unlink --yes
```

Hermes and OpenClaw share the phone's single ClawHive device record. If
OpenClaw remains linked, Hermes can be authorized again only with the same
account. Unlink every runtime that still uses the phone before authorizing
Hermes with a different account. When Hermes is the last linked runtime,
unlink releases the phone for either the original or a different account.
The command preserves project URL, anon key, node name, plugin version, and
unrelated Hermes settings while removing the revoked runtime identity.

## Required Runtime Environment

Managed-cloud installs use the built-in ClawHive Supabase URL and anon key. For local or self-hosted Supabase, override them before authorization:

```bash
export CLAWHIVE_SUPABASE_MODE="local"
export CLAWHIVE_PROJECT_URL="https://<project>.supabase.co"
export CLAWHIVE_SUPABASE_ANON_KEY="<anon key>"
```

Normally `hermes clawhive authorize` writes the resolved project URL, anon key, and plugin token to `$HERMES_HOME/.env`; set them manually only for local testing or automation.

Optional values:

```bash
export CLAWHIVE_NODE_NAME="Hermes Desktop"
export CLAWHIVE_PLUGIN_VERSION="0.1.2"
export CLAWHIVE_USER_ID="<user uuid>"
export CLAWHIVE_PLUGIN_NODE_ID="<existing node uuid>"
```

## Agent Registration

ClawHive follows the Hermes platform plugin flow. Hermes loads `plugin.yaml`, calls `register(ctx)`, and creates `ClawHivePlatformAdapter` through `ctx.register_platform(...)`. When the adapter connects, it registers the Hermes runtime node with ClawHive and syncs serviceable Hermes profiles as ClawHive agents.

Hermes profiles are discovered through Hermes profile APIs. With gateway profile multiplexing enabled, the adapter syncs all serviceable profiles. Without multiplexing, it syncs the active/default profile only.

## Message Routing

`ClawHivePlatformAdapter.send(chat_id, text)` writes an agent message with:

```text
chat_id = <session_id>:<agent_id>
```

If Hermes supplies session metadata separately, pass `session_id` and `agent_id` as keyword arguments instead of encoding them into `chat_id`.

Inbound messages are received by the platform adapter's `connect()` flow through the ClawHive Realtime bridge. The adapter converts user messages into Hermes `MessageEvent` values and dispatches them through `self.handle_message(event)`.

`poll_session(session_id)` is a local debug/fallback helper. It is not the product message receive path.

## Local Verification

From the repository root:

```bash
python3 -m pytest hermes-plugin/tests
```
