clawmes 0.1.0__py3-none-any.whl

clawmes/__init__.py

@@ -0,0 +1,142 @@
+"""Clawmes — Hermes Agent for crypto.
+
+A crypto-native plugin for Hermes Agent. Registers tools, commands, hooks,
+skills, and CLI subcommands via Hermes' standard ``register(ctx)`` plugin
+contract.
+
+The ``register`` function is the single entry point invoked by
+``hermes_cli.plugins.PluginManager`` at process startup. It is sync and must
+return quickly. Heavy work (RPC warmup, key validation) is deferred to first
+use or to background threads started by ``services.start_all()``.
+"""
+
+from __future__ import annotations
+
+# When Hermes loads us via ``importlib.util.spec_from_file_location``
+# (e.g. ``hermes plugins install <git>`` path), the module name is a
+# namespaced ``hermes_plugins.clawmes`` rather than the bare
+# ``clawmes``. The rest of this package uses absolute imports
+# (``from clawmes.X import Y``) — without aliasing, those would fail
+# with ``cannot import name 'X' from 'clawmes' (unknown location)``.
+#
+# Aliasing here makes the namespaced module also reachable as
+# ``clawmes``, so subsequent absolute imports resolve to THIS same
+# module instance (no double-load, singletons stay singleton). When
+# loaded via ``pip install`` (canonical bare name from the start),
+# the alias check sees ``clawmes`` already present and skips.
+import sys as _sys
+
+if "clawmes" not in _sys.modules:
+    _sys.modules["clawmes"] = _sys.modules[__name__]
+
+import atexit
+import signal
+
+from clawmes import (
+    cli,
+    commands,
+    hooks,
+    persona,
+    services,
+    skills,
+    tools,
+)
+from clawmes._version import __version__
+from clawmes.lib.logger import logger_for
+
+__all__ = ["__version__", "register"]
+
+_log = logger_for("plugin")
+
+
+def register(ctx) -> None:
+    """Plugin entry point called by Hermes at startup.
+
+    Stages, in order:
+
+    1. **Idempotent first-run setup.** ``persona.ensure_soul_md()`` copies
+       the bundled SOUL.md into ``${HERMES_HOME}/SOUL.md`` if absent. Never
+       overwrites a user-edited file.
+    2. **Surface registration.** Tools, commands, hooks, skills, and CLI
+       subcommands are wired through the corresponding ``register_all(ctx)``
+       calls. Each subsystem's stub is filled in across subsequent
+       milestones; calling them now is a no-op except for ``tools`` once
+       individual tool modules land.
+    3. **Service start.** ``services.start_all()`` brings up wallet, RPC,
+       price, plan-scheduler, etc. in topological order.
+    4. **Cleanup hooks.** ``atexit`` + SIGTERM/SIGINT handlers ensure
+       ``services.stop_all()`` runs on graceful shutdown.
+
+    Errors during ``register()`` are caught and logged so a clawmes failure
+    never crashes Hermes' boot — the plugin manager will mark the plugin
+    disabled and surface the error in ``hermes plugins list``.
+    """
+    _log.info("clawmes %s registering with Hermes", __version__)
+
+    # 1. First-run setup. If this fails we still continue to surface
+    # registration — a missing SOUL.md is a degraded state, not a hard
+    # failure.
+    _safe("persona.ensure_soul_md", persona.ensure_soul_md)
+
+    # 2. Register surface — each subsystem is isolated so a buggy
+    # commands module can't take down tools, hooks, skills, or the CLI.
+    # Hermes shows a partial-feature plugin instead of a fully-disabled
+    # one.
+    _safe("tools.register_all", tools.register_all, ctx)
+    _safe("commands.register_all", commands.register_all, ctx)
+    _safe("hooks.register_all", hooks.register_all, ctx)
+    _safe("skills.register_all", skills.register_all, ctx)
+    _safe("cli.register_all", cli.register_all, ctx)
+
+    # 3. Background services. start_all itself wraps each service in
+    # try/except, so partial failure here means partial feature loss
+    # rather than total plugin failure.
+    _safe("services.start_all", services.start_all)
+
+    # 4. Cleanup
+    try:
+        atexit.register(services.stop_all)
+        _install_signal_handlers()
+    except Exception:
+        _log.exception("failed to install cleanup hooks")
+
+    _log.info("clawmes register() complete")
+
+
+def _safe(label: str, fn, *args, **kwargs) -> None:
+    """Run ``fn(*args, **kwargs)`` and log any exception without re-raising.
+
+    Used to isolate register-time failures: a broken module in one
+    subsystem (e.g. ``commands``) shouldn't disable every other
+    subsystem. If something fails here the user gets a partially-
+    functional plugin and a clear log entry instead of a fully-
+    disabled plugin and a stack trace in ``hermes plugins list``.
+    """
+    try:
+        fn(*args, **kwargs)
+    except Exception:
+        _log.exception("clawmes register: %s failed; continuing", label)
+
+
+def _install_signal_handlers() -> None:
+    """Attach SIGTERM/SIGINT handlers for clean service shutdown.
+
+    Falls through to whatever Hermes already installed — we re-raise after
+    stopping our own services so the parent's handlers still fire.
+    """
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        prev = signal.getsignal(sig)
+
+        def _handler(signum, frame, _prev=prev):
+            try:
+                services.stop_all()
+            finally:
+                if callable(_prev) and _prev not in (signal.SIG_DFL, signal.SIG_IGN):
+                    _prev(signum, frame)
+
+        try:
+            signal.signal(sig, _handler)
+        except ValueError:
+            # Signal handlers can only be set in the main thread — Hermes
+            # may have already done this, fine to skip.
+            pass

clawmes/_version.py

@@ -0,0 +1,10 @@
+"""Single-source-of-truth version string.
+
+Read by:
+  * ``clawmes/__init__.py`` — exposed as ``clawmes.__version__``
+  * ``clawmes/cli/version.py`` — emitted by ``hermes clawmes version``
+  * ``hermes clawmes doctor`` — reported in diagnostics output
+  * Tooling that does not want to incur a full package import
+"""
+
+__version__ = "0.1.0"

clawmes/bridges/__init__.py

@@ -0,0 +1,24 @@
+"""Node sub-process bridges.
+
+Two long-lived Node processes are spawned at plugin start:
+
+  * ``clawmes-wc-bridge`` — wraps ``@walletconnect/sign-client`` for WC v2
+    pairing, signing, and session management.
+  * ``clawmes-sa-bridge`` — wraps ``@metamask/smart-accounts-kit`` for
+    EIP-7702/7710 delegation creation, listing, and execution.
+
+Why subprocess? Both upstream JS libs are first-party reference impls
+of in-flux specs; re-implementing in Python is a 6-month project per
+bridge with continuous spec drift. Sub-process keeps the spec-tracking
+burden on upstream.
+
+Wire format: JSON-line over stdio. See PRD §21 for the full method
+catalog and protocol.
+"""
+
+from __future__ import annotations
+
+from clawmes.bridges.installer import ensure_node_bridges
+from clawmes.bridges.process import BridgeProcess
+
+__all__ = ["BridgeProcess", "ensure_node_bridges"]

clawmes/bridges/installer.py

@@ -0,0 +1,126 @@
+"""Bridge installer.
+
+On every plugin start we make sure the Node bridge sources are present
+and ``npm ci``-installed under ``${HERMES_HOME}/clawmes/bridges/{wc,sa}``.
+
+Strategy:
+
+  1. Locate the bundled source under
+     ``clawmes/bridges/sources/{wc,sa}/``.
+  2. Hash ``package.json`` + ``package-lock.json``.
+  3. Compare against ``${HERMES_HOME}/clawmes/bridges/{wc,sa}/.installed-hash``.
+  4. If changed (or absent):
+       a. Copy the bundled source into the install directory
+       b. Run ``npm ci --omit=dev``
+       c. Write the hash file
+  5. Return absolute paths to ``dist/index.mjs`` for each bridge.
+
+If Node is not installed, we log a clear warning and return None — the
+plugin still loads, but tools that need bridges will fail with a
+friendly error.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from clawmes.lib.logger import logger_for
+from clawmes.lib.paths import bridges_dir
+
+_log = logger_for("bridges.installer")
+
+
+_SOURCES_ROOT = Path(__file__).parent / "sources"
+
+
+@dataclass(frozen=True)
+class BridgePaths:
+    wc_entry: Path | None
+    sa_entry: Path | None
+
+
+def ensure_node_bridges(*, force: bool = False) -> BridgePaths:
+    """Idempotent installer for both bridges. Safe to call on every boot."""
+    node = shutil.which("node")
+    if not node:
+        _log.warning(
+            "Node.js not found — install Node ≥ 20 for clawmes wallet bridges. "
+            "Plugin will load but WC + SA tools will fail."
+        )
+        return BridgePaths(wc_entry=None, sa_entry=None)
+
+    wc_entry = _ensure_one("wc", force=force)
+    sa_entry = _ensure_one("sa", force=force)
+    return BridgePaths(wc_entry=wc_entry, sa_entry=sa_entry)
+
+
+def _ensure_one(name: str, *, force: bool) -> Path | None:
+    src = _SOURCES_ROOT / name
+    if not src.exists():
+        _log.debug("bridge source for %s missing at %s — not yet bundled", name, src)
+        return None
+
+    target = bridges_dir() / name
+    target.mkdir(parents=True, exist_ok=True)
+
+    pj = src / "package.json"
+    pl = src / "package-lock.json"
+    if not pj.exists() or not pl.exists():
+        _log.debug("bridge source for %s lacks package files yet — skipping install", name)
+        return None
+
+    expected_hash = _hash_files(pj, pl)
+    marker = target / ".installed-hash"
+    if (
+        not force
+        and marker.exists()
+        and marker.read_text(encoding="utf-8").strip() == expected_hash
+    ):
+        _log.debug("bridge %s already installed (hash %s)", name, expected_hash[:8])
+        return target / "dist" / "index.mjs"
+
+    _log.info("installing bridge %s …", name)
+    _copy_tree(src, target)
+    try:
+        subprocess.run(
+            ["npm", "ci", "--omit=dev"],
+            cwd=target,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        _log.error("npm ci failed for %s: %s", name, exc.stderr)
+        return None
+
+    marker.write_text(expected_hash + "\n", encoding="utf-8")
+    return target / "dist" / "index.mjs"
+
+
+def _hash_files(*paths: Path) -> str:
+    h = hashlib.sha256()
+    for p in paths:
+        h.update(p.read_bytes())
+    return h.hexdigest()
+
+
+def _copy_tree(src: Path, dst: Path) -> None:
+    """Mirror ``src`` into ``dst``, preserving file mtimes."""
+    if dst.exists():
+        # Don't blow away node_modules; just refresh source files.
+        for child in src.iterdir():
+            if child.name == "node_modules":
+                continue
+            target = dst / child.name
+            if child.is_dir():
+                if target.exists():
+                    shutil.rmtree(target)
+                shutil.copytree(child, target)
+            else:
+                shutil.copy2(child, target)
+    else:
+        shutil.copytree(src, dst, ignore=shutil.ignore_patterns("node_modules"))

clawmes/bridges/process.py

@@ -0,0 +1,263 @@
+"""``BridgeProcess`` — long-lived Node subprocess with JSON-line RPC.
+
+Manages spawn, stdio reader / writer threads, future-based request /
+response matching, notification dispatch, and graceful shutdown. Per-
+bridge clients (``wc_client``, ``sa_client``) wrap typed methods on
+top of this.
+
+Wire format (one record per line, terminated with ``\\n``):
+
+  Request:      ``{"id": "<uuid>", "method": "<name>", "params": {...}}``
+  Response OK:  ``{"id": "<uuid>", "result": <any>}``
+  Response err: ``{"id": "<uuid>", "error": {"code": "<str>", ...}}``
+  Notification: ``{"method": "<event>", "params": {...}}`` (no id)
+
+Concurrency model:
+
+  * One **reader thread** per process — pulls lines from stdout,
+    parses, dispatches to either the matching pending future
+    (response) or the notification queue.
+  * The **caller** writes to stdin under a lock, then waits on a
+    ``threading.Event`` until the reader resolves it.
+  * No event loop — callers can be sync or async; the bridge blocks
+    until response arrives or the timeout fires.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import threading
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from queue import Queue
+from typing import Any
+
+from clawmes.lib.logger import logger_for
+
+_log = logger_for("bridges.process")
+
+
+class BridgeError(RuntimeError):
+    """Raised when a bridge call fails (crash, timeout, RPC error)."""
+
+    def __init__(self, code: str, message: str, *, data: Any = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.data = data
+
+
+@dataclass
+class Notification:
+    """Server-pushed event from a bridge (no ``id`` field)."""
+
+    method: str
+    params: dict[str, Any]
+
+
+@dataclass
+class _PendingCall:
+    event: threading.Event = field(default_factory=threading.Event)
+    result: Any = None
+    error: BridgeError | None = None
+
+
+class BridgeProcess:
+    """Lifecycle wrapper around a single Node bridge subprocess."""
+
+    def __init__(
+        self,
+        name: str,
+        entry: Path,
+        *,
+        node_bin: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        self.name = name
+        self.entry = entry
+        self._node_bin = node_bin or shutil.which("node") or "node"
+        self._env = env
+        self._proc: subprocess.Popen | None = None
+        self._reader: threading.Thread | None = None
+        self._stderr_reader: threading.Thread | None = None
+        self._writer_lock = threading.Lock()
+        self._pending: dict[str, _PendingCall] = {}
+        self._pending_lock = threading.Lock()
+        self._notifications: Queue[Notification] = Queue()
+        self._lock = threading.RLock()
+        self._stopping = False
+
+    # ----- lifecycle ----------------------------------------------------
+
+    def start(self) -> None:
+        with self._lock:
+            if self._proc is not None and self._proc.poll() is None:
+                return
+            _log.info("starting bridge %s: %s %s", self.name, self._node_bin, self.entry)
+            self._stopping = False
+            self._proc = subprocess.Popen(
+                [self._node_bin, str(self.entry)],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                bufsize=1,  # line-buffered
+                text=True,
+                env=self._env,
+            )
+            self._reader = threading.Thread(
+                target=self._read_stdout,
+                name=f"{self.name}-reader",
+                daemon=True,
+            )
+            self._reader.start()
+            self._stderr_reader = threading.Thread(
+                target=self._read_stderr,
+                name=f"{self.name}-stderr",
+                daemon=True,
+            )
+            self._stderr_reader.start()
+
+    def stop(self) -> None:
+        with self._lock:
+            self._stopping = True
+            if self._proc is None:
+                return
+            if self._proc.poll() is None:
+                try:
+                    self._proc.terminate()
+                    self._proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    self._proc.kill()
+                    try:
+                        self._proc.wait(timeout=2)
+                    except subprocess.TimeoutExpired:
+                        pass
+            # Fail every pending call with a clean error
+            with self._pending_lock:
+                for call in self._pending.values():
+                    call.error = BridgeError("bridge_stopped", f"bridge {self.name} stopped")
+                    call.event.set()
+                self._pending.clear()
+            self._proc = None
+
+    def is_running(self) -> bool:
+        return self._proc is not None and self._proc.poll() is None
+
+    # ----- request / response ------------------------------------------
+
+    def call(self, method: str, params: dict[str, Any], *, timeout: float = 30.0) -> Any:
+        """Send a request, wait for the matching response."""
+        if not self.is_running():
+            raise BridgeError("not_running", f"bridge {self.name} is not running")
+
+        request_id = str(uuid.uuid4())
+        call = _PendingCall()
+        with self._pending_lock:
+            self._pending[request_id] = call
+
+        line = json.dumps({"id": request_id, "method": method, "params": params})
+        try:
+            with self._writer_lock:
+                assert self._proc is not None and self._proc.stdin is not None
+                self._proc.stdin.write(line + "\n")
+                self._proc.stdin.flush()
+        except (BrokenPipeError, OSError) as exc:
+            with self._pending_lock:
+                self._pending.pop(request_id, None)
+            raise BridgeError(
+                "write_failed", f"bridge {self.name} stdin write failed: {exc}"
+            ) from exc
+
+        if not call.event.wait(timeout):
+            with self._pending_lock:
+                self._pending.pop(request_id, None)
+            raise BridgeError(
+                "timeout", f"bridge {self.name} timeout after {timeout}s on {method!r}"
+            )
+
+        if call.error is not None:
+            raise call.error
+        return call.result
+
+    def notifications(self) -> Queue[Notification]:
+        return self._notifications
+
+    # ----- internals ---------------------------------------------------
+
+    def _read_stdout(self) -> None:
+        """Reader thread — parses each line, routes to pending future or notification queue."""
+        proc = self._proc
+        if proc is None or proc.stdout is None:
+            return
+        for raw in iter(proc.stdout.readline, ""):
+            line = raw.strip()
+            if not line:
+                continue
+            try:
+                payload = json.loads(line)
+            except json.JSONDecodeError:
+                _log.warning("%s: malformed line: %r", self.name, line[:200])
+                continue
+            self._handle_payload(payload)
+        # Reader exiting — process closed stdout. If we have pending
+        # calls and we're not in a stop() pathway, surface that as an
+        # error.
+        if not self._stopping:
+            with self._pending_lock:
+                pending = list(self._pending.items())
+                self._pending.clear()
+            for request_id, call in pending:
+                call.error = BridgeError(
+                    "bridge_crashed",
+                    f"bridge {self.name} stdout closed with pending request {request_id}",
+                )
+                call.event.set()
+
+    def _read_stderr(self) -> None:
+        """Stderr drain — tag every line with the bridge name and forward to logger."""
+        proc = self._proc
+        if proc is None or proc.stderr is None:
+            return
+        for raw in iter(proc.stderr.readline, ""):
+            line = raw.strip()
+            if line:
+                _log.warning("%s [stderr]: %s", self.name, line)
+
+    def _handle_payload(self, payload: Any) -> None:
+        if not isinstance(payload, dict):
+            _log.warning("%s: non-dict payload: %r", self.name, payload)
+            return
+        request_id = payload.get("id")
+        if request_id is None:
+            self._enqueue_notification(payload)
+            return
+        with self._pending_lock:
+            call = self._pending.pop(str(request_id), None)
+        if call is None:
+            _log.debug("%s: response for unknown id %r", self.name, request_id)
+            return
+        if "error" in payload and payload["error"]:
+            err = payload["error"]
+            if isinstance(err, dict):
+                call.error = BridgeError(
+                    code=str(err.get("code", "unknown")),
+                    message=str(err.get("message", "")),
+                    data=err.get("data"),
+                )
+            else:
+                call.error = BridgeError("unknown", str(err))
+        else:
+            call.result = payload.get("result")
+        call.event.set()
+
+    def _enqueue_notification(self, payload: dict[str, Any]) -> None:
+        method = payload.get("method")
+        if not isinstance(method, str):
+            _log.warning("%s: notification missing method: %r", self.name, payload)
+            return
+        params = payload.get("params") or {}
+        if not isinstance(params, dict):
+            params = {}
+        self._notifications.put(Notification(method=method, params=params))

clawmes/bridges/sa_client.py

@@ -0,0 +1,96 @@
+"""Python client for ``clawmes-sa-bridge`` (MetaMask Smart Accounts).
+
+Typed wrappers for EIP-7702 / 7710 delegation work and Permit2 signing.
+Methods (see PRD §21.3):
+
+  * :meth:`delegation_create`
+  * :meth:`delegation_list`
+  * :meth:`delegation_revoke`
+  * :meth:`delegation_execute` — used by the ``@write_tool`` gating
+    pipeline as stage 3 (skip handler if delegation handles it)
+  * :meth:`account_deploy`
+  * :meth:`permit2_sign`
+  * :meth:`health`
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from clawmes.bridges.process import BridgeProcess
+from clawmes.lib.logger import logger_for
+
+_log = logger_for("bridges.sa")
+
+
+class SmartAccountsClient:
+    def __init__(self, entry: Path, *, node_bin: str = "node") -> None:
+        self._proc = BridgeProcess("clawmes-sa", entry, node_bin=node_bin)
+
+    def start(self) -> None:
+        self._proc.start()
+
+    def stop(self) -> None:
+        self._proc.stop()
+
+    def delegation_create(
+        self,
+        *,
+        delegate: str,
+        permissions: list[dict[str, Any]],
+        expiry: int,
+    ) -> dict[str, Any]:
+        return self._proc.call(
+            "delegation_create",
+            {"delegate": delegate, "permissions": permissions, "expiry": expiry},
+        )
+
+    def delegation_list(self) -> list[dict[str, Any]]:
+        result = self._proc.call("delegation_list", {})
+        return list(result.get("delegations", []))
+
+    def delegation_revoke(self, delegation_id: str) -> str:
+        result = self._proc.call("delegation_revoke", {"delegation_id": delegation_id})
+        return result["tx_hash"]
+
+    def delegation_execute(
+        self,
+        *,
+        delegation_id: str,
+        calldata: str,
+        to: str,
+        value: str = "0x0",
+        chain_id: int,
+    ) -> str:
+        result = self._proc.call(
+            "delegation_execute",
+            {
+                "delegation_id": delegation_id,
+                "calldata": calldata,
+                "to": to,
+                "value": value,
+                "chain_id": chain_id,
+            },
+            timeout=60.0,
+        )
+        return result["tx_hash"]
+
+    def account_deploy(self, chain_id: int) -> dict[str, Any]:
+        return self._proc.call("account_deploy", {"chain_id": chain_id})
+
+    def permit2_sign(
+        self,
+        *,
+        token: str,
+        spender: str,
+        amount: str,
+        deadline: int,
+    ) -> dict[str, Any]:
+        return self._proc.call(
+            "permit2_sign",
+            {"token": token, "spender": spender, "amount": amount, "deadline": deadline},
+        )
+
+    def health(self) -> dict[str, Any]:
+        return self._proc.call("health", {})