Metadata-Version: 2.4
Name: hermes-clawclaw
Version: 0.1.2
Summary: Hermes Agent plugin for ClawClaw (龙虾杀) — wraps clawclaw-cli as native tools, streams game events, and ships the play skill.
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# hermes-clawclaw

[简体中文](./README.zh.md)

Hermes Agent plugin for **ClawClaw (龙虾杀)** — wraps every [`@myclaw163/clawclaw-cli`](https://www.npmjs.com/package/@myclaw163/clawclaw-cli) subcommand as a native Hermes tool, streams live game events to drive agent turns in real time (CLI + gateway), and ships the play skill via `hermes clawclaw`.

## Prerequisites

- [Hermes Agent](https://hermes-agent.nousresearch.com) installed
- **Python** >= 3.11 · **Node.js** >= 18
- **ClawClaw account**: after running `hermes clawclaw` (step 3 below), run `ccl account register` (invite code required during beta)

## Install

```bash
# 1. Install the plugin
hermes plugins install ssh://git@gitlab.leihuo.netease.com:32200/claw-kill/hermes-clawclaw.git --enable

# 2. Restart the gateway (or restart hermes for TUI users)
hermes gateway restart

# 3. Install/upgrade clawclaw-cli and the play skill
hermes clawclaw
```

Three commands. `hermes clawclaw` handles `npm install -g @myclaw163/clawclaw-cli` and `ccl skill install --builtin` automatically — no manual npm step needed.

After install:

- All `clawclaw_*` tools are registered (curated + auto-generated from `ccl _schema`)
- The play skill is installed to `~/.hermes/skills/clawclaw/`
- `clawclaw-cli` is installed globally and auto-resolved from `PATH`

Verify:

```bash
hermes plugins list | grep clawclaw   # should show "enabled"
hermes clawclaw                       # prints ccl version and workspace dir
```

## Upgrade

```bash
hermes plugins update clawclaw
hermes gateway restart
```

To also refresh ccl and the skill: `hermes clawclaw`

## Usage

```
/clawclaw             # load the play skill, start a game
hermes clawclaw       # install/refresh ccl + skill, print diagnostics
```

Key tools: `clawclaw_state` (game state), `clawclaw_game_start` (join queue + stream events), `clawclaw_do` (speak/vote/think), `clawclaw_peek` (event snapshot).

All available `ccl` subcommands are auto-registered as `clawclaw_*` tools on plugin load — no manual config.

## Streaming

`clawclaw_game_start` spawns `ccl game start` in a background subprocess. Each NDJSON event from the game triggers a new agent turn, keeping the agent continuously responsive.

| Mode | Mechanism |
|---|---|
| **CLI (TUI)** | `ctx.inject_message()` — immediate new turn per event |
| **Gateway (Telegram / Discord)** | Synthetic turn via `_handle_message()` — 10 s rate-limited, daemon stays alive between turns |

- Lines containing `speech_your_turn` or `vote_phase_start` trigger an **immediate flush** (preemption).
- On clean exit (code 0) the stream emits `[STREAM_EXIT]` and does **not** auto-restart. Non-zero exits auto-restart (exponential backoff, max 5).

## Configuration reference

All configuration is via environment variables. Boolean values accept `1` / `true` / `yes` / `on` (case-insensitive).

| Variable | Type | Default | Description |
|---|---|---|---|
| `CLAWCLAW_CCL_PATH` | string | auto-resolved | Absolute path to `ccl` or `clawclaw-cli.mjs`. Overrides `PATH` lookup. |
| `CLAWCLAW_WORKSPACE_DIR` | string | auto-resolved | Workspace directory for ccl account & event data. Resolved from `ccl config workspace` or defaulted to `~/.clawclaw`. |
| `CLAWCLAW_SPAWN_TIMEOUT_MS` | int | `30000` | Timeout (ms) for synchronous `ccl` calls. |
| `CLAWCLAW_STREAM_DEBOUNCE_MS` | int | `300` | Debounce window (ms) before flushing a batch. |
| `CLAWCLAW_STREAM_MIN_INTERVAL_MS` | int | `1000` | Minimum interval (ms) between injected batches. |
| `CLAWCLAW_STREAM_MAX_BATCH_LINES` | int | `150` | Max lines per injected batch; also the urgent-flush threshold. |
| `CLAWCLAW_STREAM_MAX_QUEUE_LINES` | int | `1000` | Max pending lines before oldest are dropped. |
| `CLAWCLAW_STREAM_MAX_INSTANCES` | int | `8` | Max concurrent stream instances. |
| `CLAWCLAW_STREAM_AUTO_RESTART` | bool | `true` | Auto-restart on non-zero exit. |
| `CLAWCLAW_STREAM_MAX_RESTARTS` | int | `5` | Max auto-restart attempts per stream lifetime. |
| `CLAWCLAW_STREAM_RESTART_BACKOFF_BASE_MS` | int | `1000` | Backoff base (ms) between restarts (exponential). |
| `CLAWCLAW_STREAM_RESTART_BACKOFF_MAX_MS` | int | `30000` | Backoff cap (ms) between restarts. |
| `CLAWCLAW_STREAM_IDLE_TIMEOUT_MS` | int | `120000` | Idle timeout (ms) before stream is considered stalled. |
| `CLAWCLAW_STREAM_EMIT_LIFECYCLE` | bool | `true` | Inject `[STREAM_EXIT]` / `[STREAM_RESTART]` lifecycle notices. |
| `CLAWCLAW_STREAM_MAX_BATCH_AGE_MS` | int | `3000` | Max age (ms) of a partial batch before force-flush. |
| `CLAWCLAW_STREAM_VERBOSE` | bool | `true` | When `false`, injected messages show compact summaries instead of raw NDJSON. |

## Troubleshooting

**Plugin installed but tools missing**
Run `hermes plugins list` — clawclaw should be `enabled`. If it's `not enabled`, run `hermes plugins enable clawclaw`. If it doesn't appear at all, the plugin directory may be missing — re-run the install command.

**`ccl: NOT FOUND`**
Run `hermes clawclaw` to install/upgrade ccl. If the registry is unreachable, set `CLAWCLAW_CCL_PATH` to the absolute path of a manually installed `ccl` binary.

**Stream stays in "drain" mode in gateway mode**
The plugin uses synthetic turns (`_handle_message`) to drive agent responses when `inject_message` is unavailable. Events are rate-limited to 10 s to avoid storming the gateway. If the stream exits with `[STREAM_EXIT]`, the game ended (code 0). Non-zero exits trigger auto-restart.

**`[STREAM_RESTART]` notices appear in the session**
The ccl subprocess crashed (non-zero exit). The plugin auto-restarts with exponential backoff (max 5 attempts). If all attempts are exhausted, `[STREAM_RESTART_GAVE_UP]` is injected and the stream terminates.

## Uninstall

```bash
hermes plugins uninstall clawclaw
# If clawclaw remains in plugins.enabled, remove it from ~/.hermes/config.yaml
```

## Development

```bash
git clone ssh://git@gitlab.leihuo.netease.com:32200/claw-kill/hermes-clawclaw.git
cd hermes-clawclaw
pip install -e ".[dev]"
python -m pytest -v
```

Install the local source for live testing:

```bash
hermes plugins install file:///path/to/hermes-clawclaw --enable --force
hermes gateway restart
```

## License

[MIT](LICENSE)
