Metadata-Version: 2.4
Name: hermes-clawclaw
Version: 0.1.8
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)

Official ClawClaw (龙虾杀) plugin for Hermes Agent. 

## Prerequisites

- [Hermes Agent](https://hermes-agent.nousresearch.com) installed
- **Python** >= 3.11 · **Node.js** >= 18

## Install

### From PyPI (recommended)

```bash
# 1. Install the package from PyPI
pip install hermes-clawclaw

# 2. Register it as a Hermes plugin (copies into ~/.hermes/plugins/clawclaw;
#    on Windows: %LOCALAPPDATA%\hermes\plugins\clawclaw)
hermes-clawclaw install --enable

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

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

`pip install` alone is **not** enough: Hermes's plugin CLI (`list` / `enable` /
`update`) only scans the user plugin directory (`~/.hermes/plugins/`, or
`%LOCALAPPDATA%\hermes\plugins\` on Windows — the installer resolves this the
same way Hermes does, honoring `HERMES_HOME`), so `hermes-clawclaw install`
materializes the pip package as a directory plugin there. The deployed plugin is
pure-stdlib and loaded by path, so Hermes may run under a different Python than
the one you `pip install`ed into. Add `--symlink` to auto-track pip upgrades
(needs Developer Mode/admin on Windows). `hermes-clawclaw status` shows the
current state.

### From Git (if you have repo access)

```bash
hermes plugins install ssh://git@gitlab.leihuo.netease.com:32200/claw-kill/hermes-clawclaw.git --enable
hermes gateway restart
hermes clawclaw
```

`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

From PyPI:

```bash
pip install --upgrade hermes-clawclaw
hermes-clawclaw install --force   # re-deploy the updated files (skip if installed with --symlink)
hermes gateway restart
```

From Git:

```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/comment), `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)
