Metadata-Version: 2.3
Name: yoooclaw-hermes-plugin
Version: 0.2.2
Summary: YoooClaw tools and APP messaging platform adapter for Hermes Agent
Author: YoooClaw
License: MIT
Requires-Dist: watchfiles>=1,<2
Requires-Dist: websockets>=14,<16
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# hermes-plugin

YoooClaw integration for [Hermes Agent](https://hermes-agent.nousresearch.com/).

This repository is the Python plugin boundary between Hermes and YoooClaw.
The existing `@yoooclaw/cli` daemon remains responsible for the shared data
plane: phone notification ingest, recordings, images, Relay tunnels,
credentials, light-rule storage, and one-shot light control. The Hermes plugin
owns the APP conversation transport and the host-side light-rule trigger
runtime.

Production plugin artifacts bundle the platform-specific `yoooclaw` executable
itself. Users do not need a preinstalled CLI, and the plugin does not download
the CLI on first run. The embedded executable is verified and installed into a
plugin-managed path before use.

The release workflow downloads the four verified native assets from the pinned
`cli-v*` release in `YoooClaw/cli`, then creates one Python wheel per
platform. Each wheel carries only its own executable and a SHA-256 manifest:

```text
darwin-arm64
darwin-x64
linux-arm64
linux-x64
```

The wheels and `cli-wheel-index.json` are attached to the matching
`YoooClaw/hermes-plugin` GitHub Release. This keeps the Git repository small
while giving Hermes a package artifact that already contains the CLI.

## One-command install

Install the plugin, store the YoooClaw API key, enable both Hermes plugins, and
restart the gateway:

```bash
curl -fsSL https://raw.githubusercontent.com/YoooClaw/hermes-plugin/main/scripts/install.sh | bash -s -- --api-key "ock_..."
```

For APP chat, authorize the users that may talk to Hermes:

```bash
curl -fsSL https://raw.githubusercontent.com/YoooClaw/hermes-plugin/main/scripts/install.sh | bash -s -- \
  --api-key "ock_..." \
  --allowed-users "u_123,u_456"
```

Use `--allow-all-users` only for a trusted single-user account. The installer
writes the shared key to `~/.yoooclaw/credentials.json`, mirrors it into
`~/.hermes/.env` as `YOOOCLAW_API_KEY` / `YOOOCLAW_APP_API_KEY`, and ensures
`yoooclaw` plus `yoooclaw_app` are present in `plugins.enabled` in
`~/.hermes/config.yaml`.

Run `scripts/install.sh --help` for local development options such as
`--skip-install`, `--package`, `--python`, and `--no-restart`.

## Manual install

Stable plugin releases also publish the platform wheels to PyPI. Hermes
discovers both entry-point plugins after a normal package install into the same
Python environment Hermes uses:

```bash
pip install yoooclaw-hermes-plugin
```

> **Enabling pip-installed plugins on Hermes 0.15.1 (and earlier).** The
> `hermes plugins enable <name>` / `disable` / `list` commands only recognize
> directory-based (`~/.hermes/plugins/`) and bundled plugins — they do not scan
> Python entry points, so `hermes plugins enable yoooclaw` fails with
> "Plugin 'yoooclaw' is not installed or bundled." The runtime loader *does*
> load entry-point plugins, but only when their names appear in the
> `plugins.enabled` allow-list. For a pip install, enable them by editing
> `~/.hermes/config.yaml` directly:
>
> ```yaml
> plugins:
>   enabled: [yoooclaw, yoooclaw_app]
> ```
>
> Then restart the gateway (`hermes gateway restart`). If a future Hermes
> release teaches `hermes plugins enable` to recognize entry-point plugins,
> the CLI commands below will work as written. The one-command installer above
> applies this config-file enablement automatically.

## Features

- General Hermes plugin: tools, hooks, slash commands, CLI subcommands, skills.
- `yoooclaw_app` platform adapter: APP messages into Hermes and Hermes replies
  back to the APP.
- Tool bridge: call `yc --format json` and the daemon localhost HTTP API.
- Embedded CLI: ship the target platform's `yoooclaw` executable in the plugin
  artifact and use PATH lookup only as a local development fallback.
- APP transport: connect the Hermes platform adapter directly to the existing
  APP conversation channel without routing messages through the CLI daemon.
- Local relay server and browser chat UI for end-to-end APP conversation tests.
- Notification watcher: use OS file notifications on the active CLI profile's
  `notifications/` directory to feed newly persisted items into the host-side
  light-rule runtime without adding a daemon event API.

The tool plugin exposes notification, recording, image, Relay, light-control,
light-rule CRUD, daemon status, and doctor tools. The APP platform adapter
connects directly to Relay and translates the existing OpenClaw-compatible
`chat.send`, `chat.history`, and `chat.abort` RPC frames into Hermes messages.

## APP Authorization

APP chat fails closed. Configure an explicit user allowlist or opt into all
users before enabling `yoooclaw_app`:

```bash
export YOOOCLAW_APP_ALLOWED_USERS="u_123,u_456"
# or, only for a trusted account:
export YOOOCLAW_APP_ALLOW_ALL_USERS=1
```

The APP adapter reuses `YOOOCLAW_API_KEY` or `~/.yoooclaw/credentials.json` by
default. Set `YOOOCLAW_APP_API_KEY` when the APP conversation connection should
use a dedicated Relay key. `YOOOCLAW_APP_RELAY_URL` overrides the Relay URL for
local or staging verification.

## Switching environments

The base daemon's Relay endpoint is per `yoooclaw` profile (`relay.url` in each
profile's `config.json`). Use `env` to switch the active profile and restart the
daemon in one step — `hermes gateway restart` alone reconnects to the running
daemon and would not pick up the new `relay.url`:

```bash
hermes yoooclaw env            # show the active environment + Relay status
hermes yoooclaw env test       # switch to the `test` profile and restart the daemon
hermes yoooclaw env default    # switch back to the `default` (prod) profile
```

`/yoooclaw env <profile>` does the same from a chat session. The switch stops the
previous profile's daemon before starting the target's, so exactly one daemon
runs; an unknown profile name fails without disturbing the running daemon. The
Relay apiKey stays account-global (`~/.yoooclaw/credentials.json`); switch it with
`yoooclaw auth set-default-api-key <label>` when an environment needs a different
key.

## Logging

The plugin uses an OpenClaw-style file logger in addition to Hermes' normal
logging pipeline. Logs are written daily under:

```text
~/.yoooclaw/plugins/yoooclaw-hermes/logs/YYYY-MM-DD.log
```

Set `YOOOCLAW_HERMES_LOG_DIR` to override the log directory. Stable releases
redact common secrets, user text, user URLs, emails, phone numbers, bearer
tokens, JWTs, and long hex tokens before writing files or passing records to
Hermes' upstream logging handlers. Versions containing `beta` keep raw logs for
debugging, matching the OpenClaw plugin behavior. Log files older than 30 days
are pruned automatically; override with
`YOOOCLAW_HERMES_LOG_RETENTION_DAYS`.

Search recent plugin logs through the Hermes plugin CLI:

```bash
hermes yoooclaw logs --keyword relay --from 2026-06-01 --to 2026-06-04 --limit 50
```

The Hermes-owned foreground daemon still writes its child-process stdout/stderr
to `~/.yoooclaw/hermes-plugin/daemon-fg.log`.

## Local Relay And Web UI

For local end-to-end testing, run the Bun/Hono relay server instead of the
production Relay, then start the Vite/React web UI:

```bash
bun install
bun run relay:dev
bun run web:dev
```

Configure Hermes to point the APP adapter at it:

```bash
export YOOOCLAW_APP_RELAY_URL="ws://127.0.0.1:8799/message/messages/ws/plugin"
export YOOOCLAW_APP_API_KEY="ock-local-dev"
export YOOOCLAW_APP_ALLOW_ALL_USERS=1
hermes gateway restart
```

Ensure `yoooclaw_app` is in the `plugins.enabled` list in
`~/.hermes/config.yaml` (see the install note above; for a linked development
checkout under `~/.hermes/plugins/` you can instead run
`hermes plugins enable yoooclaw_app`).

Open `http://127.0.0.1:5173/` to chat through the browser UI. `GET
/healthz` on `http://127.0.0.1:8799` returns `pluginConnected: true` after the
Hermes platform adapter connects.

The local relay keeps the current OpenClaw-compatible plugin path
`/message/messages/ws/plugin`, and also exposes `/app` plus `/v1/app/ws` for
browser-style clients. `POST /v1/messages` is available for simple scripted
message injection. The web UI renders Hermes events, RPC responses, typing
state, and `app.message.update` / `hermes.message.update` streaming frames in a
structured event panel powered by Vercel Labs `json-render`
(`@json-render/core` and `@json-render/react`).

## Layout

```text
yoooclaw_hermes/   # General Hermes plugin
yoooclaw_app/      # Hermes platform adapter for YoooClaw APP chat
apps/relay-server/ # Bun + Hono local Relay-compatible server
apps/web/          # Vite + React + Tailwind CSS web chat UI
tests/
```

## Development

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first, then:

```bash
uv sync --dev
uv run pytest
uv build
```

For local Hermes discovery, link the plugin directories into `~/.hermes/plugins/`
and enable them:

```bash
ln -s "$PWD/yoooclaw_hermes" ~/.hermes/plugins/yoooclaw
ln -s "$PWD/yoooclaw_app" ~/.hermes/plugins/yoooclaw_app
hermes plugins enable yoooclaw
hermes plugins enable yoooclaw_app
hermes plugins list
```

## References

- [Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/guides/build-a-hermes-plugin)
- [Adding a Platform Adapter](https://hermes-agent.nousresearch.com/docs/developer-guide/adding-platform-adapters)
