exolimbs 0.4.0__py3-none-any.whl

exolimbs/__init__.py

@@ -0,0 +1,113 @@
+"""Exolimbs — Hermes plugin.
+
+Turns OpenClaw / ClawHub's mature execution substrate (skill registry, local
+sandbox, Playwright browser automation, multi-language runtimes, retry/rollback)
+into a set of structured-JSON tools for Hermes.
+
+Design:
+- Hermes is the brain (LLM/conversation/memory/UI).
+- Exolimbs is the hands/feet (deterministic execution). It NEVER calls an
+  LLM itself -> zero extra model tokens on the execution path.
+- Two interchangeable backends, switchable via config:
+    * "cli"    -> shells out to the real `openclaw` / `clawhub` CLIs.
+    * "native" -> a decoupled Python re-implementation (no Node dependency).
+    * "auto"   -> cli if the `openclaw` binary is present, else native.
+
+Every tool handler:
+  - has signature `handler(args: dict, **kwargs) -> str`
+  - ALWAYS returns a JSON string (success and error alike)
+  - NEVER raises
+"""
+
+from __future__ import annotations
+
+import logging
+
+from . import schemas, tools
+from .config import get_settings
+
+logger = logging.getLogger(__name__)
+
+__version__ = "0.4.0"
+
+
+def _cli_available() -> bool:
+    """check_fn used to hide CLI-only behaviour gracefully (never raises)."""
+    try:
+        from .backends.cli_backend import openclaw_binary
+
+        return openclaw_binary() is not None
+    except Exception:  # pragma: no cover - defensive
+        return False
+
+
+def _tools_available() -> bool:
+    """Tools are available whenever a backend can be resolved.
+
+    The CLI backend needs the `openclaw` binary; the native backend always
+    resolves. So tools are available unless the user pinned `backend: cli`
+    without installing the CLI.
+    """
+    try:
+        settings = get_settings()
+        if settings.backend == "cli":
+            return _cli_available()
+        return True
+    except Exception:  # pragma: no cover - defensive
+        return True
+
+
+def register(ctx) -> None:
+    """Entry point called once at startup. Wires schemas -> handlers.
+
+    If this function raises, Hermes disables the plugin but keeps running, so we
+    keep it defensive and side-effect-light.
+    """
+    pairs = (
+        ("claw_skill_search", schemas.CLAW_SKILL_SEARCH, tools.claw_skill_search),
+        ("claw_skill_install", schemas.CLAW_SKILL_INSTALL, tools.claw_skill_install),
+        ("claw_skill_run", schemas.CLAW_SKILL_RUN, tools.claw_skill_run),
+        ("claw_sandbox_exec", schemas.CLAW_SANDBOX_EXEC, tools.claw_sandbox_exec),
+        ("claw_browser", schemas.CLAW_BROWSER, tools.claw_browser),
+        ("claw_runtime", schemas.CLAW_RUNTIME, tools.claw_runtime),
+    )
+
+    for name, schema, handler in pairs:
+        ctx.register_tool(
+            name=name,
+            toolset="exolimbs",
+            schema=schema,
+            handler=handler,
+            check_fn=_tools_available,
+        )
+
+    # Ship an opt-in "how to drive me" skill. Not in the system-prompt index,
+    # so it costs zero standing tokens until the agent explicitly loads it.
+    try:
+        from pathlib import Path
+
+        skill_md = Path(__file__).parent / "skills" / "exolimbs" / "SKILL.md"
+        if skill_md.exists():
+            ctx.register_skill("exolimbs", skill_md)
+    except Exception as exc:  # pragma: no cover - optional
+        logger.debug("exolimbs: skill registration skipped: %s", exc)
+
+    # Diagnostics slash command: /exo status
+    try:
+        ctx.register_command(
+            "exo",
+            handler=tools.slash_claw,
+            description="Exolimbs status / backend info",
+            args_hint="[status|backend|doctor]",
+        )
+    except Exception as exc:  # pragma: no cover - optional
+        logger.debug("exolimbs: slash command skipped: %s", exc)
+
+    s = get_settings()
+    logger.info(
+        "exolimbs v%s registered (backend=%s, resolved=%s, pro=%s)",
+        __version__,
+        s.backend,
+        s.resolved_backend(),
+        s.is_pro(),
+    )

exolimbs/_ed25519.py

@@ -0,0 +1,144 @@
+"""Minimal, dependency-free Ed25519 (RFC 8032) for offline license verification.
+
+Adapted from the public-domain reference implementation by the Ed25519 authors
+(https://ed25519.cr.yp.to/software.html). Modular exponentiation uses Python's
+built-in ``pow`` for speed. This is used for one-off, offline signature checks
+(license tokens) — it is NOT constant-time and must not be used to sign secrets
+on adversarial shared hardware. Signing happens vendor-side; verification ships
+to customers with zero third-party dependencies.
+
+Public API:
+    public_from_seed(seed32) -> bytes32
+    sign(message, seed32, public_key=None) -> bytes64
+    verify(signature64, message, public_key32) -> bool
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+_b = 256
+_q = 2**255 - 19
+_l = 2**252 + 27742317777372353535851937790883648493
+
+
+def _H(m: bytes) -> bytes:
+    return hashlib.sha512(m).digest()
+
+
+def _inv(x: int) -> int:
+    return pow(x, _q - 2, _q)
+
+
+_d = -121665 * _inv(121666) % _q
+_I = pow(2, (_q - 1) // 4, _q)
+
+
+def _xrecover(y: int) -> int:
+    xx = (y * y - 1) * _inv(_d * y * y + 1)
+    x = pow(xx, (_q + 3) // 8, _q)
+    if (x * x - xx) % _q != 0:
+        x = (x * _I) % _q
+    if x % 2 != 0:
+        x = _q - x
+    return x
+
+
+_By = 4 * _inv(5) % _q
+_Bx = _xrecover(_By)
+_B = [_Bx % _q, _By % _q]
+
+
+def _edwards(P: list[int], Q: list[int]) -> list[int]:
+    x1, y1 = P
+    x2, y2 = Q
+    x3 = (x1 * y2 + x2 * y1) * _inv(1 + _d * x1 * x2 * y1 * y2)
+    y3 = (y1 * y2 + x1 * x2) * _inv(1 - _d * x1 * x2 * y1 * y2)
+    return [x3 % _q, y3 % _q]
+
+
+def _scalarmult(P: list[int], e: int) -> list[int]:
+    # Iterative double-and-add (avoids deep recursion).
+    result = [0, 1]
+    addend = P
+    while e > 0:
+        if e & 1:
+            result = _edwards(result, addend)
+        addend = _edwards(addend, addend)
+        e >>= 1
+    return result
+
+
+def _bit(h: bytes, i: int) -> int:
+    return (h[i // 8] >> (i % 8)) & 1
+
+
+def _encodeint(y: int) -> bytes:
+    return y.to_bytes(_b // 8, "little")
+
+
+def _encodepoint(P: list[int]) -> bytes:
+    x, y = P
+    val = (y & ((1 << (_b - 1)) - 1)) | ((x & 1) << (_b - 1))
+    return val.to_bytes(_b // 8, "little")
+
+
+def _decodeint(s: bytes) -> int:
+    return int.from_bytes(s, "little")
+
+
+def _Hint(m: bytes) -> int:
+    return _decodeint(_H(m)) % (1 << (2 * _b))
+
+
+def _secret_scalar(seed: bytes) -> int:
+    h = _H(seed)
+    return 2 ** (_b - 2) + sum(2**i * _bit(h, i) for i in range(3, _b - 2))
+
+
+def public_from_seed(seed: bytes) -> bytes:
+    if len(seed) != 32:
+        raise ValueError("seed must be 32 bytes")
+    a = _secret_scalar(seed)
+    return _encodepoint(_scalarmult(_B, a))
+
+
+def sign(message: bytes, seed: bytes, public_key: bytes | None = None) -> bytes:
+    if len(seed) != 32:
+        raise ValueError("seed must be 32 bytes")
+    h = _H(seed)
+    a = _secret_scalar(seed)
+    pk = public_key if public_key is not None else _encodepoint(_scalarmult(_B, a))
+    r = _Hint(h[32:64] + message)
+    R = _scalarmult(_B, r)
+    S = (r + _Hint(_encodepoint(R) + pk + message) * a) % _l
+    return _encodepoint(R) + _encodeint(S)
+
+
+def _isoncurve(P: list[int]) -> bool:
+    x, y = P
+    return (-x * x + y * y - 1 - _d * x * x * y * y) % _q == 0
+
+
+def _decodepoint(s: bytes) -> list[int]:
+    y = _decodeint(s) & ((1 << (_b - 1)) - 1)
+    x = _xrecover(y)
+    if x & 1 != _bit(s, _b - 1):
+        x = _q - x
+    P = [x, y]
+    if not _isoncurve(P):
+        raise ValueError("point not on curve")
+    return P
+
+
+def verify(signature: bytes, message: bytes, public_key: bytes) -> bool:
+    try:
+        if len(signature) != 64 or len(public_key) != 32:
+            return False
+        R = _decodepoint(signature[:32])
+        A = _decodepoint(public_key)
+        S = _decodeint(signature[32:64])
+        h = _Hint(signature[:32] + public_key + message)
+        return _scalarmult(_B, S) == _edwards(R, _scalarmult(A, h))
+    except Exception:
+        return False

exolimbs/_licensing.py

@@ -0,0 +1,132 @@
+"""Open-core licensing gate — real offline Ed25519 verification.
+
+The free tier ships all six execution tools. Pro features (audit log, curated
+skill packs, auto-update, priority support) require a signed license token.
+
+Token format (compact, JWT-like, EdDSA / Ed25519):
+
+    EXL1.<base64url(payload_json)>.<base64url(signature)>
+
+`payload_json` is a UTF-8 JSON object, e.g.:
+
+    {"sub": "alice@example.com", "tier": "pro", "exp": 1771000000,
+     "iat": 1760000000, "jti": "lic_abc123", "features": ["audit", "packs"]}
+
+The signature covers the ASCII bytes of `"EXL1." + base64url(payload)` (the
+header+payload, exactly like JWS). Verification is fully offline against the
+embedded public key — no phone-home, works air-gapped. Revoke issued licenses by
+shipping their `jti` in `_REVOKED` with a release.
+
+Signing happens vendor-side only (see scripts/issue_license.py). The private seed
+never ships and is git-ignored.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from functools import lru_cache
+
+from . import _ed25519
+
+# Vendor Ed25519 public key (hex, 32 bytes). Replace via scripts/gen_keys.py.
+_PUBLIC_KEY_HEX = "0ac58e8a93d3b09dfb5425c31e4f855dbba6b347cc1e4d001a40ba4aed288490"
+
+_PRO_TIERS = frozenset({"pro", "team", "enterprise"})
+_PREFIX = "EXL1"
+
+# License IDs (jti) revoked after issuance. Ship updates with releases.
+_REVOKED: frozenset[str] = frozenset()
+
+
+def _b64url_decode(s: str) -> bytes:
+    pad = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def b64url_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _public_key() -> bytes:
+    return bytes.fromhex(_PUBLIC_KEY_HEX)
+
+
+def decode_license(token: str) -> dict | None:
+    """Verify signature + structure. Returns the payload dict or None.
+
+    Does NOT check expiry/tier/revocation — see `license_status`.
+    """
+    if not token or not _PUBLIC_KEY_HEX:
+        return None
+    parts = token.strip().split(".")
+    if len(parts) != 3 or parts[0] != _PREFIX:
+        return None
+    _, payload_b64, sig_b64 = parts
+    try:
+        signing_input = f"{_PREFIX}.{payload_b64}".encode("ascii")
+        signature = _b64url_decode(sig_b64)
+        if not _ed25519.verify(signature, signing_input, _public_key()):
+            return None
+        payload = json.loads(_b64url_decode(payload_b64).decode("utf-8"))
+        return payload if isinstance(payload, dict) else None
+    except Exception:
+        return None
+
+
+def license_status(token: str | None) -> dict:
+    """Full evaluation -> {valid, tier, reason, ...}. Never raises."""
+    import os
+
+    token = (token or os.environ.get("EXOLIMBS_LICENSE") or "").strip()
+    if not token:
+        return {"valid": False, "tier": "free", "reason": "no license"}
+    payload = decode_license(token)
+    if payload is None:
+        return {"valid": False, "tier": "free", "reason": "invalid signature"}
+    jti = payload.get("jti")
+    if jti and jti in _REVOKED:
+        return {"valid": False, "tier": "free", "reason": "revoked", "jti": jti}
+    exp = payload.get("exp")
+    if exp is not None and time.time() > float(exp):
+        return {"valid": False, "tier": "free", "reason": "expired", "exp": exp}
+    tier = str(payload.get("tier", "")).lower()
+    if tier not in _PRO_TIERS:
+        return {"valid": False, "tier": tier or "free", "reason": "non-pro tier"}
+    return {
+        "valid": True,
+        "tier": tier,
+        "reason": "ok",
+        "sub": payload.get("sub"),
+        "exp": exp,
+        "features": payload.get("features", []),
+        "jti": jti,
+    }
+
+
+@lru_cache(maxsize=16)
+def is_pro(key: str | None = None) -> bool:
+    return license_status(key)["valid"]
+
+
+def require_pro(feature: str, key: str | None = None) -> dict | None:
+    """Return an error dict if the feature needs Pro and the license is invalid."""
+    if is_pro(key):
+        return None
+    return {
+        "ok": False,
+        "error": f"'{feature}' requires an Exolimbs Pro license",
+        "upgrade": "https://your-store.example.com",
+    }
+
+
+def describe(key: str | None = None) -> str:
+    st = license_status(key)
+    if st["valid"]:
+        exp = st.get("exp")
+        when = time.strftime("%Y-%m-%d", time.gmtime(exp)) if exp else "perpetual"
+        return f"Pro ({st['tier']}, expires {when})"
+    if st["reason"] == "no license":
+        return "Free"
+    return f"Free (license {st['reason']})"

exolimbs/_retry.py

@@ -0,0 +1,64 @@
+"""Retry + rollback helper.
+
+`with_retry` runs an operation that returns a result dict. It retries on
+*recoverable* failures (exceptions, or dicts with a truthy `retryable` flag /
+network-ish errors) up to `retries` times with exponential backoff. The operation
+itself is responsible for being safe to retry — pass `retries=0` for
+non-idempotent operations.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+_RETRYABLE_HINTS = ("timeout", "unreachable", "temporarily", "connection", "reset", "502", "503", "504")
+
+
+def _looks_retryable(result: Any) -> bool:
+    if not isinstance(result, dict):
+        return False
+    if result.get("ok"):
+        return False
+    if result.get("retryable") is True:
+        return True
+    err = str(result.get("error", "")).lower()
+    return any(h in err for h in _RETRYABLE_HINTS)
+
+
+def with_retry(
+    op: Callable[[], dict],
+    *,
+    retries: int = 2,
+    backoff_s: float = 1.0,
+    rollback: bool = True,
+) -> dict:
+    attempt = 0
+    last: dict = {"ok": False, "error": "not executed"}
+    while True:
+        try:
+            result = op()
+            if isinstance(result, dict) and result.get("ok"):
+                if attempt:
+                    result.setdefault("attempts", attempt + 1)
+                return result
+            last = result if isinstance(result, dict) else {"ok": False, "error": str(result)}
+            if not _looks_retryable(last) or attempt >= retries:
+                if rollback and not last.get("ok"):
+                    last.setdefault("rolled_back", True)
+                last.setdefault("attempts", attempt + 1)
+                return last
+        except Exception as exc:  # treat as retryable transient
+            last = {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
+            if attempt >= retries:
+                if rollback:
+                    last.setdefault("rolled_back", True)
+                last.setdefault("attempts", attempt + 1)
+                return last
+        sleep_for = backoff_s * (2**attempt)
+        logger.debug("with_retry: attempt %s failed, sleeping %.1fs", attempt + 1, sleep_for)
+        time.sleep(min(sleep_for, 30.0))
+        attempt += 1

exolimbs/backends/__init__.py

@@ -0,0 +1,42 @@
+"""Backend resolver — picks CLI vs native per config and caches the instance."""
+
+from __future__ import annotations
+
+import threading
+
+from ..config import get_settings
+from .base import Backend
+
+_lock = threading.Lock()
+_cache: dict[str, Backend] = {}
+
+
+def get_backend() -> Backend:
+    """Resolve the active backend (thread-safe, cached by resolved name)."""
+    resolved = get_settings().resolved_backend()
+    cached = _cache.get(resolved)
+    if cached is not None:
+        return cached
+    with _lock:
+        cached = _cache.get(resolved)
+        if cached is not None:
+            return cached
+        if resolved == "cli":
+            from .cli_backend import CliBackend
+
+            backend: Backend = CliBackend()
+        else:
+            from .native_backend import NativeBackend
+
+            backend = NativeBackend()
+        _cache[resolved] = backend
+        return backend
+
+
+def reset_backend() -> None:
+    """Drop cached backends (tests / config reload)."""
+    with _lock:
+        _cache.clear()
+
+
+__all__ = ["Backend", "get_backend", "reset_backend"]

exolimbs/backends/base.py

@@ -0,0 +1,52 @@
+"""Backend abstract base class.
+
+A backend is the deterministic execution substrate. Two implementations:
+- CliBackend    : shells out to `openclaw` / `clawhub`.
+- NativeBackend : decoupled Python re-implementation (no Node dependency).
+
+All methods return a plain dict (NOT a JSON string); tools.py handles
+serialization, retry, rollback and audit. Methods may raise — the caller
+wraps them. Prefer returning {"ok": False, "error": ...} for expected
+failures and raising only for unexpected ones.
+"""
+
+from __future__ import annotations
+
+import abc
+from typing import Any
+
+
+class Backend(abc.ABC):
+    name: str = "base"
+
+    # -- skill registry ----------------------------------------------------
+    @abc.abstractmethod
+    def skill_search(self, *, query: str, limit: int) -> dict[str, Any]: ...
+
+    @abc.abstractmethod
+    def skill_install(
+        self, *, slug: str, verify: bool, global_install: bool
+    ) -> dict[str, Any]: ...
+
+    @abc.abstractmethod
+    def skill_run(
+        self, *, slug: str, entry: str, args: dict, sandbox: bool
+    ) -> dict[str, Any]: ...
+
+    # -- execution ---------------------------------------------------------
+    @abc.abstractmethod
+    def sandbox_exec(
+        self,
+        *,
+        command: str,
+        image: str,
+        timeout_s: int,
+        network: bool,
+        workdir: str | None,
+    ) -> dict[str, Any]: ...
+
+    @abc.abstractmethod
+    def browser(self, *, actions: list[dict], headless: bool) -> dict[str, Any]: ...
+
+    @abc.abstractmethod
+    def runtime(self, *, lang: str, code: str, timeout_s: int) -> dict[str, Any]: ...