hermes-clawclaw 0.1.1__tar.gz

hermes_clawclaw-0.1.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: hermes-clawclaw
+Version: 0.1.1
+Summary: Hermes Agent plugin for ClawClaw (龙虾杀) — wraps clawclaw-cli as native tools, streams game events, and ships the play skill.
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# 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)

hermes_clawclaw-0.1.1/README.md

@@ -0,0 +1,135 @@
+# 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)

hermes_clawclaw-0.1.1/hermes_clawclaw/__init__.py

@@ -0,0 +1,86 @@
+"""hermes-clawclaw — Hermes Agent plugin for ClawClaw (龙虾杀).
+
+register(ctx) wiring order:
+  1. hand-written curated tools + raw passthrough (always; error at call time if ccl missing)
+  2. auto-generated tools from `ccl _schema` (skips OVERRIDDEN + SKIP_PATHS; skipped entirely if ccl missing)
+  3. stream tools (game_start / game_stop / game_status) + session-end cleanup hooks
+  4. `hermes clawclaw` setup CLI command
+
+The play skill is installed separately via `hermes clawclaw setup` (calls
+`ccl skill install --builtin`) and is NOT bundled in this plugin.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from .cli_resolve import resolve_ccl, resolve_workspace
+from .config import Config
+from .handwritten import register_handwritten
+from .schema_tools import register_auto_tools
+from .setup_cli import register_setup_command
+from .stream import register_stream_tools
+
+logger = logging.getLogger(__name__)
+__version__ = "0.1.1"
+
+
+def register(ctx) -> None:
+    try:
+        _register_impl(ctx)
+    except Exception:
+        logger.exception("[clawclaw] plugin registration failed — "
+                         "registering CLI fallback only")
+        try:
+            register_setup_command(ctx)
+        except Exception:
+            logger.exception("[clawclaw] CLI fallback registration also failed")
+
+
+def _register_impl(ctx) -> None:
+    cfg = Config.from_env()
+    invoker = resolve_ccl(cfg.ccl_path)
+    if invoker is None:
+        logger.warning("[clawclaw] ccl not found. Install with: npm i -g @myclaw163/clawclaw-cli")
+        logger.warning("[clawclaw] tools will error at call time until ccl is available.")
+    else:
+        logger.info("[clawclaw] using ccl: %s", invoker.display)
+        # Resolve workspace dir (priority: env var > ccl config > ~/.clawclaw)
+        if not cfg.workspace_dir:
+            ws = resolve_workspace(invoker)
+            if ws:
+                cfg = cfg.with_workspace(ws)
+                logger.info("[clawclaw] workspace from ccl: %s", ws)
+            else:
+                cfg = cfg.with_workspace(str(Path.home() / ".clawclaw"))
+                logger.info("[clawclaw] workspace default: %s", cfg.workspace_dir)
+
+    # 1. curated overrides FIRST (so auto-gen skips these names)
+    register_handwritten(ctx, invoker if invoker else _NullInvoker(), cfg)
+    # 2. auto-gen (no-op if ccl missing or schema fetch fails)
+    register_auto_tools(ctx, invoker, cfg)
+    # 3. stream tools + cleanup hooks
+    register_stream_tools(ctx, invoker, cfg)
+    # 4. setup CLI command (includes `hermes clawclaw setup` for skill install)
+    register_setup_command(ctx)
+    logger.info("[clawclaw] plugin registered")
+
+
+
+
+
+
+class _NullInvoker:
+    """Placeholder so curated handlers can register even when ccl is absent;
+    they return a clear error at call time via the check_fn / runner."""
+
+    def __init__(self) -> None:
+        self.exe = ""
+        self.prefix_args: list[str] = []
+
+    def argv(self, extra):  # pragma: no cover - never executed (check_fn gates)
+        return ["ccl", *extra]
+
+    @property
+    def display(self):  # pragma: no cover
+        return "ccl (unresolved)"

hermes_clawclaw-0.1.1/hermes_clawclaw/cli_resolve.py

@@ -0,0 +1,124 @@
+"""Resolve the `ccl` (clawclaw-cli) executable and workspace dir."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+
+# Windows: suppress console-window flashes on every subprocess call.
+# Three layers because each alone can fail depending on the call chain:
+#   CREATE_NO_WINDOW  – prevents the system allocating a fresh console
+#   DETACHED_PROCESS  – detaches from parent console entirely; children
+#                       of a detached process can't inherit a console
+#   SW_HIDE           – forces the window invisible via STARTUPINFO even
+#                       if the process calls AllocConsole() internally
+# Must be a factory: CreateProcess mutates STARTUPINFO, so each call needs
+# a fresh copy to avoid cross-call races.
+if sys.platform == "win32":
+    def _subprocess_kwargs():
+        si = subprocess.STARTUPINFO()
+        si.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        si.wShowWindow = subprocess.SW_HIDE
+        _flags = subprocess.CREATE_NO_WINDOW | subprocess.DETACHED_PROCESS
+        return {
+            "creationflags": _flags,
+            "startupinfo": si,
+        }
+else:
+    def _subprocess_kwargs():
+        return {}
+
+
+@dataclass
+class Invoker:
+    exe: str
+    prefix_args: list[str] = field(default_factory=list)
+
+    def argv(self, extra: list[str]) -> list[str]:
+        return [self.exe, *self.prefix_args, *extra]
+
+    @property
+    def display(self) -> str:
+        return " ".join([self.exe, *self.prefix_args])
+
+
+def _node() -> str:
+    return shutil.which("node") or "node"
+
+
+def _mjs_from_shim(shim_path: str) -> str | None:
+    """npm shim (<dir>/ccl.cmd) → <dir>/node_modules/@myclaw163/clawclaw-cli/bin/clawclaw-cli.mjs."""
+    d = os.path.dirname(shim_path)
+    cand = os.path.join(d, "node_modules", "@myclaw163", "clawclaw-cli", "bin", "clawclaw-cli.mjs")
+    return cand if os.path.isfile(cand) else None
+
+
+def _invoker_for_path(path: str) -> Invoker | None:
+    if not path or not os.path.isfile(path):
+        return None
+    low = path.lower()
+    if low.endswith((".mjs", ".js")):
+        return Invoker(exe=_node(), prefix_args=[path])
+    if low.endswith((".cmd", ".bat", ".exe")):
+        mjs = _mjs_from_shim(path)
+        if mjs:
+            return Invoker(exe=_node(), prefix_args=[mjs])
+        if low.endswith(".exe"):
+            return Invoker(exe=path)  # native binary, runnable directly
+        return None  # .cmd/.bat with no resolvable .mjs — unusable without a shell
+    # POSIX: a plain executable (e.g. /usr/bin/ccl shell wrapper) runs directly.
+    return Invoker(exe=path)
+
+
+def resolve_ccl(override: str | None = None) -> Invoker | None:
+    candidates: list[str] = []
+    if override:
+        candidates.append(override)
+
+    is_win = sys.platform == "win32"
+    exe_names = (
+        ["ccl.cmd", "ccl.exe", "ccl", "clawclaw-cli.cmd", "clawclaw-cli.exe", "clawclaw-cli"]
+        if is_win
+        else ["ccl", "clawclaw-cli"]
+    )
+    for name in exe_names:
+        found = shutil.which(name)
+        if found:
+            candidates.append(found)
+
+    for c in candidates:
+        inv = _invoker_for_path(c)
+        if inv:
+            return inv
+    return None
+
+
+def resolve_workspace(invoker: Invoker, timeout_ms: int = 5_000) -> str | None:
+    """Query ccl for its configured workspace dir. Returns None on failure."""
+    try:
+        proc = subprocess.run(
+            invoker.argv(["config", "workspace"]),
+            capture_output=True,
+            text=True,
+            timeout=timeout_ms / 1000,
+            **_subprocess_kwargs(),
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    out = (proc.stdout or "").strip()
+    if not out:
+        return None
+    try:
+        data = json.loads(out)
+        if isinstance(data, dict) and "path" in data:
+            return data["path"]
+        if isinstance(data, str):
+            return data
+    except json.JSONDecodeError:
+        return out
+    return out

hermes_clawclaw-0.1.1/hermes_clawclaw/config.py

@@ -0,0 +1,69 @@
+"""Env-var configuration. Defaults mirror STREAM_DEFAULTS from stream.ts."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, replace
+
+
+def _int(name: str, default: int) -> int:
+    v = os.environ.get(name)
+    try:
+        return int(v) if v not in (None, "") else default
+    except ValueError:
+        return default
+
+
+def _bool(name: str, default: bool) -> bool:
+    v = os.environ.get(name)
+    if v in (None, ""):
+        return default
+    return v.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _str(name: str) -> str | None:
+    v = os.environ.get(name)
+    return v if v else None
+
+
+@dataclass(frozen=True)
+class Config:
+    ccl_path: str | None
+    workspace_dir: str | None  # None = not yet resolved; ccl uses its own default
+    spawn_timeout_ms: int
+    stream_debounce_ms: int
+    stream_min_interval_ms: int
+    stream_max_batch_lines: int
+    stream_max_queue_lines: int
+    stream_max_instances: int
+    stream_auto_restart: bool
+    stream_max_restarts: int
+    stream_restart_backoff_base_ms: int
+    stream_restart_backoff_max_ms: int
+    stream_idle_timeout_ms: int
+    stream_emit_lifecycle: bool
+    stream_max_batch_age_ms: int
+    stream_verbose: bool
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        return cls(
+            ccl_path=_str("CLAWCLAW_CCL_PATH"),
+            workspace_dir=_str("CLAWCLAW_WORKSPACE_DIR"),
+            spawn_timeout_ms=_int("CLAWCLAW_SPAWN_TIMEOUT_MS", 30_000),
+            stream_debounce_ms=_int("CLAWCLAW_STREAM_DEBOUNCE_MS", 300),
+            stream_min_interval_ms=_int("CLAWCLAW_STREAM_MIN_INTERVAL_MS", 1_000),
+            stream_max_batch_lines=_int("CLAWCLAW_STREAM_MAX_BATCH_LINES", 150),
+            stream_max_queue_lines=_int("CLAWCLAW_STREAM_MAX_QUEUE_LINES", 1_000),
+            stream_max_instances=_int("CLAWCLAW_STREAM_MAX_INSTANCES", 8),
+            stream_auto_restart=_bool("CLAWCLAW_STREAM_AUTO_RESTART", True),
+            stream_max_restarts=_int("CLAWCLAW_STREAM_MAX_RESTARTS", 5),
+            stream_restart_backoff_base_ms=_int("CLAWCLAW_STREAM_RESTART_BACKOFF_BASE_MS", 1_000),
+            stream_restart_backoff_max_ms=_int("CLAWCLAW_STREAM_RESTART_BACKOFF_MAX_MS", 30_000),
+            stream_idle_timeout_ms=_int("CLAWCLAW_STREAM_IDLE_TIMEOUT_MS", 120_000),
+            stream_emit_lifecycle=_bool("CLAWCLAW_STREAM_EMIT_LIFECYCLE", True),
+            stream_max_batch_age_ms=_int("CLAWCLAW_STREAM_MAX_BATCH_AGE_MS", 3_000),
+            stream_verbose=_bool("CLAWCLAW_STREAM_VERBOSE", True),
+        )
+
+    def with_workspace(self, path: str) -> "Config":
+        return replace(self, workspace_dir=path)