Metadata-Version: 2.4
Name: clawhive-hermes-plugin
Version: 0.1.0
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.0-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 \
  --project-url "https://<project>.supabase.co" \
  --anon-key "<anon key>"
```

This starts the same ClawHive device-code authorization flow used by the OpenClaw plugin: Hermes prints an approval URL and user code, the user approves with their ClawHive account, and the command stores the returned plugin token in the Hermes `.env` file. 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
```

## Required Runtime Environment

```bash
export CLAWHIVE_PROJECT_URL="https://<project>.supabase.co"
export CLAWHIVE_SUPABASE_ANON_KEY="<anon key>"
export CLAWHIVE_PLUGIN_TOKEN="<plugin token>"
```

Normally `hermes clawhive authorize` writes these values 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.0"
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
```
