Metadata-Version: 2.3
Name: yoooclaw-hermes-plugin
Version: 0.2.5
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 pipeline 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 build job emits the wheels, `cli-wheel-index.json`, and `SHA256SUMS` once,
then promotes that exact `dist/` bundle through the release flow: test OSS
first, production OSS after approval, and finally PyPI / GitHub Release for
stable versions. Installers and channel markers remain environment-specific and
are regenerated at deploy time. This keeps the Git repository small while
guaranteeing that QA verifies the same bytes we later ship.

## One-command install

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

```bash
curl -fsSL https://artifact.yoooclaw.com/hermes-plugin/install.sh | bash -s -- --api-key "ock_..."
```

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

```bash
curl -fsSL https://artifact.yoooclaw.com/hermes-plugin/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`, `--oss-base-url`, `--version`, `--python`, and
`--no-restart`. The source-tree installer defaults to PyPI; the installer
uploaded by CI is rendered with the OSS base URL from `.env` / GitHub Secrets
and installs the matching platform wheel directly from OSS.

## 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.

## Release flow

This repository now uses artifact promotion instead of rebuilding at each
environment boundary:

1. Push to `release/**` runs `test-oss.yml` and uploads a cache-busted build to
   the test OSS bucket. A second upload refreshes the stable test update
   channel without replacing the unique install URL. Pure `pyproject.toml`
   version bumps are ignored so a release commit does not double-publish.
2. Push tag `v*` runs `release.yml`: `build` creates the wheels once, writes
   `SHA256SUMS`, and stores the bundle as a GitHub Actions artifact.
   `deploy-test` promotes that bundle to the stable test OSS prefix and sends
   an "RC pending manual promotion" notification with the exact version number
   to pass into the next step.
3. After QA signs off, run `promote-prod.yml` manually (`workflow_dispatch`)
   from GitHub Actions. It auto-discovers the successful `release.yml` run for
   `v{version}`, downloads that exact artifact, re-verifies `SHA256SUMS`, then
   promotes it to production OSS. Stable releases continue on to PyPI through
   the existing `pypi` environment and then publish the GitHub Release.
4. `rollback.yml` is a manual `workflow_dispatch` rollback. It repoints the
   `latest` or `beta` marker to a previous version and restores the archived
   installer from `v{version}/installer/install.sh` when that archive exists.

Repository settings still matter:

- `test` / `production` environment secrets hold the OSS credentials used by
  the deploy and rollback workflows; `OPENCLAW_RELEASE_TOKEN` stays build-only.
- The manual approval fallback is the `promote-prod.yml` dispatch itself, so it
  works even when private-repository required reviewers are unavailable on the
  current GitHub plan.
- The `pypi` environment remains the OIDC boundary for trusted publishing.

## 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`, `chat.abort`, and `sessions.*` RPC frames into
Hermes messages and APP-owned session state.

## 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 resolves its Relay key from `~/.yoooclaw/credentials.json` by
default — the same source the `yoooclaw` cli / base daemon reads, so the plugin
and the cli stay on the same key. Set `YOOOCLAW_APP_API_KEY` to override it with a
dedicated key for local or staging verification; `YOOOCLAW_API_KEY` is only a
fallback used when `credentials.json` is absent. `YOOOCLAW_APP_RELAY_URL`
overrides the Relay URL for local or staging verification.

The APP Relay endpoint follows `PHONE_NOTIFICATIONS_ENV`, matching the CLI's
environment switch:

| `PHONE_NOTIFICATIONS_ENV` | Relay host |
| --- | --- |
| `development` | `broker-test.yoooclaw.com` |
| `test` | `broker-test.yoooclaw.com` |
| `production` (default) | `broker.yoooclaw.com` |

`development` and `test` share `broker-test` for now. Unset or unknown values
fall back to `production`. `YOOOCLAW_APP_RELAY_URL` still wins over the env-based
selection when set.

## 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)
