karma-openclaw 0.4.0__tar.gz

karma_openclaw-0.4.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: karma-openclaw
+Version: 0.4.0
+Summary: Karma ↔ OpenClaw — stdio MCP server bridging to Karma public HTTP API
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp<2,>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# karma-openclaw — OpenClaw MCP proof plugin
+
+Stdio MCP server that attaches verifiable execution receipts and evidence bundles to OpenClaw agent workflows. Karma acts as a proof layer for paid agent actions — it does not replace payment or tool execution, it records proof after actions happen.
+
+**P0 proof tools:** execution receipt construction, evidence bundle submission, verification and handoff validation. High-risk settlement actions (voucher create/accept, Runtime Key mint) remain manual in the Karma Console. See [Advanced OpenClaw Workflows](../../docs/OPENCLAW_P1_DUAL_AGENT.md) and [`examples/openclaw-dual-agent/`](../../examples/openclaw-dual-agent/).
+
+**Runtime Key access is agent-bound.** A `KRM_RT_…` key is a bearer token — whoever holds it could spend the owner's money — so Karma mints every key against a named agent, pins it to that agent's Ed25519 public key and requires the agent to sign every `/runtime/*` request with the matching private key. The private key never leaves the agent machine, so a copied key string is useless.
+
+**Pairing activates the key by itself.** `karma_connect` generates this machine's Ed25519 key on first use and sends its public key with the pairing request, so the owner's approval *is* the activation: `karma_connect_claim` returns a key that is already live — nothing to type, no matching code. (Without a local key, or if the declared key is malformed, the older two-step path still applies: `karma_runtime_bind_key` hands the owner an 8-character `activation_code`, then `karma_runtime_await_activation`.) Keys have no fixed expiry by default; the owner revokes them in the Console. Set `KARMA_RUNTIME_KEY`, `KARMA_AGENT_ID` and `KARMA_AGENT_PRIVATE_KEY` (Ed25519, stays on this machine). See [Runtime Key 指南](../../docs/runtime-key-guide.md).
+
+---
+
+## Install
+
+```bash
+pip install ./packages/karma-openclaw
+# or dev mode:
+pip install -e ./packages/karma-openclaw
+# no clone? one line, from the public repo:
+pip install "karma-openclaw @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-openclaw"
+```
+
+Not on PyPI yet (`pip install karma-openclaw` returns 404); see
+[`docs/mcp/karma-mcp-integration.md`](../../docs/mcp/karma-mcp-integration.md).
+
+## Run (stdio MCP)
+
+```bash
+export KARMA_RUNTIME_URL=http://localhost:8000
+export KARMA_API_KEY=***karma_worker-001_***
+export KARMA_OPENCLAW_HANDOFF_PATH=./handoff.json
+
+# /runtime/* tools (agent-bound key):
+export KARMA_RUNTIME_KEY=KRM_RT_…
+export KARMA_AGENT_ID=<the agent this key names>
+export KARMA_AGENT_PRIVATE_KEY=<base64(32 bytes) or 64-char hex>
+
+karma-openclaw-mcp
+```
+
+## MCP Proof Tools
+
+| Tool | Purpose |
+|------|---------|
+| `karma_build_execution_receipt_step` | Generate a signed receipt for one tool call |
+| `karma_submit_evidence_bundle` | Package receipts into a verifiable bundle |
+| `karma_get_evidence_bundle` | Retrieve a previously submitted bundle |
+| `karma_validate_handoff` | Verify operator handoff for high-risk actions |
+| `karma_connect` | **No key yet?** Ask to be connected; returns the `user_code` for your owner |
+| `karma_connect_claim` | Collect the credentials as soon as the owner approves; writes `~/.karma/agent.env` (0600) — including the local Ed25519 seed — and returns fingerprints only. Also answers "where is this pairing now": while it is unapproved it returns status only and consumes nothing |
+| `karma_connect_status` | What this machine holds: pending pairings + credential fingerprints. Local only — it never calls the backend |
+| `karma_pairing_*` | Deprecated aliases of the three above (same code path, each return carries a `deprecated` note). **Removal date: 2026-12-01** (next minor release); see `docs/AGENT_PAIRING_V1.md` |
+| `karma_runtime_bind_key` | Bind this agent's Ed25519 public key; returns the matching code for the owner |
+| `karma_runtime_await_activation` | Wait for the owner to enter the code; then signs every request |
+| `karma_runtime_binding_status` | Where this key stands (pending / active / bearer) |
+| `karma_check_automation_readiness` | Check if automation policy allows this action |
+| `karma_get_settlement` | (Optional) Read settlement status |
+
+## Onboarding with no key at all
+
+An agent that holds nothing can still get itself connected — and the credentials never
+travel through the chat:
+
+```text
+karma_connect(agent_name="claw-001", requested_side="seller", requested_vertical="food")
+  -> user_code "QKFS-3J5Z" + verification_uri + agent_fingerprint
+     # hand these to your owner: they compare agent_fingerprint with the Console card,
+     # so "the request in the Console" is provably "this machine's public key"
+  ... owner reviews it in Karma Console, sets the allowance, and approves — that is the delivery
+karma_connect_claim()
+  -> credentials written to ~/.karma/agent.env (0600); only sha256 fingerprints returned
+karma_connect_status()
+  -> what this machine holds; local only, no network
+```
+
+The direction is fixed: the agent produces the code, the owner types it in, approval releases
+the credentials. The agent's own `pairing_code` (256-bit, returned once, stored as SHA-256) is
+the only thing that redeems them — so a `user_code` on a screenshot, or a whole chat transcript,
+is worth nothing. If the owner wants one more hand-to-hand confirmation they can *optionally*
+issue a `handoff_code` (3 minutes, single use); then — and only then — the claim has to carry
+it too. See [Agent 配对接入 v1](../../docs/AGENT_PAIRING_V1.md).
+
+## Quick Demo
+
+```bash
+pip install -e ".[dev]"
+uvicorn api.app:app --reload &
+export KARMA_RUNTIME_URL=http://127.0.0.1:8000
+export KARMA_API_KEY=***
+
+karma-openclaw-mcp
+```
+
+Then connect OpenClaw to the MCP server and call `karma_build_execution_receipt_step`.
+
+---
+
+## License
+
+AGPL-3.0-only — see [LICENSE](../../LICENSE).

karma_openclaw-0.4.0/README.md

@@ -0,0 +1,100 @@
+# karma-openclaw — OpenClaw MCP proof plugin
+
+Stdio MCP server that attaches verifiable execution receipts and evidence bundles to OpenClaw agent workflows. Karma acts as a proof layer for paid agent actions — it does not replace payment or tool execution, it records proof after actions happen.
+
+**P0 proof tools:** execution receipt construction, evidence bundle submission, verification and handoff validation. High-risk settlement actions (voucher create/accept, Runtime Key mint) remain manual in the Karma Console. See [Advanced OpenClaw Workflows](../../docs/OPENCLAW_P1_DUAL_AGENT.md) and [`examples/openclaw-dual-agent/`](../../examples/openclaw-dual-agent/).
+
+**Runtime Key access is agent-bound.** A `KRM_RT_…` key is a bearer token — whoever holds it could spend the owner's money — so Karma mints every key against a named agent, pins it to that agent's Ed25519 public key and requires the agent to sign every `/runtime/*` request with the matching private key. The private key never leaves the agent machine, so a copied key string is useless.
+
+**Pairing activates the key by itself.** `karma_connect` generates this machine's Ed25519 key on first use and sends its public key with the pairing request, so the owner's approval *is* the activation: `karma_connect_claim` returns a key that is already live — nothing to type, no matching code. (Without a local key, or if the declared key is malformed, the older two-step path still applies: `karma_runtime_bind_key` hands the owner an 8-character `activation_code`, then `karma_runtime_await_activation`.) Keys have no fixed expiry by default; the owner revokes them in the Console. Set `KARMA_RUNTIME_KEY`, `KARMA_AGENT_ID` and `KARMA_AGENT_PRIVATE_KEY` (Ed25519, stays on this machine). See [Runtime Key 指南](../../docs/runtime-key-guide.md).
+
+---
+
+## Install
+
+```bash
+pip install ./packages/karma-openclaw
+# or dev mode:
+pip install -e ./packages/karma-openclaw
+# no clone? one line, from the public repo:
+pip install "karma-openclaw @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-openclaw"
+```
+
+Not on PyPI yet (`pip install karma-openclaw` returns 404); see
+[`docs/mcp/karma-mcp-integration.md`](../../docs/mcp/karma-mcp-integration.md).
+
+## Run (stdio MCP)
+
+```bash
+export KARMA_RUNTIME_URL=http://localhost:8000
+export KARMA_API_KEY=***karma_worker-001_***
+export KARMA_OPENCLAW_HANDOFF_PATH=./handoff.json
+
+# /runtime/* tools (agent-bound key):
+export KARMA_RUNTIME_KEY=KRM_RT_…
+export KARMA_AGENT_ID=<the agent this key names>
+export KARMA_AGENT_PRIVATE_KEY=<base64(32 bytes) or 64-char hex>
+
+karma-openclaw-mcp
+```
+
+## MCP Proof Tools
+
+| Tool | Purpose |
+|------|---------|
+| `karma_build_execution_receipt_step` | Generate a signed receipt for one tool call |
+| `karma_submit_evidence_bundle` | Package receipts into a verifiable bundle |
+| `karma_get_evidence_bundle` | Retrieve a previously submitted bundle |
+| `karma_validate_handoff` | Verify operator handoff for high-risk actions |
+| `karma_connect` | **No key yet?** Ask to be connected; returns the `user_code` for your owner |
+| `karma_connect_claim` | Collect the credentials as soon as the owner approves; writes `~/.karma/agent.env` (0600) — including the local Ed25519 seed — and returns fingerprints only. Also answers "where is this pairing now": while it is unapproved it returns status only and consumes nothing |
+| `karma_connect_status` | What this machine holds: pending pairings + credential fingerprints. Local only — it never calls the backend |
+| `karma_pairing_*` | Deprecated aliases of the three above (same code path, each return carries a `deprecated` note). **Removal date: 2026-12-01** (next minor release); see `docs/AGENT_PAIRING_V1.md` |
+| `karma_runtime_bind_key` | Bind this agent's Ed25519 public key; returns the matching code for the owner |
+| `karma_runtime_await_activation` | Wait for the owner to enter the code; then signs every request |
+| `karma_runtime_binding_status` | Where this key stands (pending / active / bearer) |
+| `karma_check_automation_readiness` | Check if automation policy allows this action |
+| `karma_get_settlement` | (Optional) Read settlement status |
+
+## Onboarding with no key at all
+
+An agent that holds nothing can still get itself connected — and the credentials never
+travel through the chat:
+
+```text
+karma_connect(agent_name="claw-001", requested_side="seller", requested_vertical="food")
+  -> user_code "QKFS-3J5Z" + verification_uri + agent_fingerprint
+     # hand these to your owner: they compare agent_fingerprint with the Console card,
+     # so "the request in the Console" is provably "this machine's public key"
+  ... owner reviews it in Karma Console, sets the allowance, and approves — that is the delivery
+karma_connect_claim()
+  -> credentials written to ~/.karma/agent.env (0600); only sha256 fingerprints returned
+karma_connect_status()
+  -> what this machine holds; local only, no network
+```
+
+The direction is fixed: the agent produces the code, the owner types it in, approval releases
+the credentials. The agent's own `pairing_code` (256-bit, returned once, stored as SHA-256) is
+the only thing that redeems them — so a `user_code` on a screenshot, or a whole chat transcript,
+is worth nothing. If the owner wants one more hand-to-hand confirmation they can *optionally*
+issue a `handoff_code` (3 minutes, single use); then — and only then — the claim has to carry
+it too. See [Agent 配对接入 v1](../../docs/AGENT_PAIRING_V1.md).
+
+## Quick Demo
+
+```bash
+pip install -e ".[dev]"
+uvicorn api.app:app --reload &
+export KARMA_RUNTIME_URL=http://127.0.0.1:8000
+export KARMA_API_KEY=***
+
+karma-openclaw-mcp
+```
+
+Then connect OpenClaw to the MCP server and call `karma_build_execution_receipt_step`.
+
+---
+
+## License
+
+AGPL-3.0-only — see [LICENSE](../../LICENSE).

karma_openclaw-0.4.0/karma_openclaw/__init__.py

@@ -0,0 +1,21 @@
+"""Karma ↔ OpenClaw MCP bridge package.
+
+Keep package import light: handoff/helpers must work without pulling FastMCP
+(mcp v1). Server entrypoints are exported lazily.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["build_app", "main"]
+
+__version__ = "0.4.0"
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("build_app", "main"):
+        from karma_openclaw.server import build_app, main
+
+        return build_app if name == "build_app" else main
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

karma_openclaw-0.4.0/karma_openclaw/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m karma_openclaw``."""
+
+from karma_openclaw.server import main
+
+if __name__ == "__main__":
+    main()

karma_openclaw-0.4.0/karma_openclaw/agent_binding.py

@@ -0,0 +1,180 @@
+"""Agent-side Runtime Key binding: the Ed25519 key + the per-request signature.
+
+Why this exists. A Runtime Key is a bearer token: whoever holds ``KRM_RT_...`` can spend
+the owner's money within its limits. Karma therefore refuses to serve *any* key that is
+not bound to an agent public key and activated by the owner with the 8-character
+matching code. So an agent process must be able to
+
+  (a) present its Ed25519 public key (``POST /runtime/bind-key``), and
+  (b) sign every ``/runtime/*`` request (``X-Karma-Agent-Signature`` + timestamp + nonce).
+
+This mirrors ``sdk/runtime_client.py`` and, on the server side,
+``services/runtime_wallet.build_agent_request_message``. Both sides are pinned against
+each other by tests so the format cannot drift.
+
+Env:
+  KARMA_AGENT_PRIVATE_KEY  base64(32 raw bytes) or 64-char hex -- never leaves this process
+  KARMA_AGENT_ID           the agent id the owner authorized (falls back to what the key was minted for)
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import uuid
+from datetime import UTC, datetime, timezone
+from typing import Any
+
+
+def runtime_key_id(token: str) -> str:
+    """Pull the key_id out of ``KRM_RT_<key_id>_<secret>`` (the signature message needs it)."""
+    raw = (token or "").strip()
+    if not raw.startswith("KRM_RT_"):
+        return ""
+    head, _, _ = raw[len("KRM_RT_") :].partition("_")
+    return head
+
+
+def agent_key_from_seed(seed: str):
+    """base64(raw 32 bytes) or 64-char hex -> Ed25519PrivateKey."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    text = (seed or "").strip()
+    if not text:
+        raise ValueError("agent private key is empty")
+    if len(text) == 64 and all(c in "0123456789abcdefABCDEF" for c in text):
+        raw = bytes.fromhex(text)
+    else:
+        raw = base64.b64decode(text, validate=True)
+    if len(raw) != 32:
+        raise ValueError("agent private key must be 32 raw bytes (base64 or hex seed)")
+    return Ed25519PrivateKey.from_private_bytes(raw)
+
+
+def agent_key_from_env() -> Any | None:
+    """The agent's Ed25519 key, or None when no seed is configured.
+
+    Reads the env var first, then the on-disk credential file -- the same file
+    ``karma_connect_claim`` writes, so a freshly paired process can sign without
+    waiting for its host to restart it.
+    """
+    from karma_openclaw.agent_env import credential
+
+    seed = credential("KARMA_AGENT_PRIVATE_KEY")
+    if not seed:
+        return None
+    return agent_key_from_seed(seed)
+
+
+def ensure_local_agent_key() -> Any | None:
+    """本机 agent 私钥：有就用，没有就现生成一把并落盘（0600）。
+
+    为什么由 agent 自己生成：这把私钥是「光有钥匙字符串花不了钱」的全部依据，
+    它必须只存在于 agent 本机 —— Karma 服务端从头到尾看不到它，只收到公钥，
+    用来把 Runtime Key 钉在这次的 agent 身上。
+    """
+    existing = agent_key_from_env()
+    if existing is not None:
+        return existing
+    try:
+        import base64 as _b64
+
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+        from karma_openclaw.agent_env import upsert_credential
+
+        key = Ed25519PrivateKey.generate()
+        raw = key.private_bytes(
+            serialization.Encoding.Raw,
+            serialization.PrivateFormat.Raw,
+            serialization.NoEncryption(),
+        )
+        upsert_credential("KARMA_AGENT_PRIVATE_KEY", _b64.b64encode(raw).decode())
+        return key
+    except Exception:  # noqa: BLE001 - 落不了盘就当没有，退回「领取时再绑」那条老路
+        return None
+
+
+def agent_id_from_env() -> str:
+    from karma_openclaw.agent_env import credential
+
+    return credential("KARMA_AGENT_ID")
+
+
+def agent_public_key_b64(key: Any) -> str:
+    """Ed25519 public key as base64 of the raw 32 bytes -- the shape the server stores."""
+    from cryptography.hazmat.primitives import serialization
+
+    raw = key.public_key().public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+    return base64.b64encode(raw).decode()
+
+
+def build_agent_request_message(
+    *, key_id: str, method: str, path: str, timestamp: str, nonce: str, body_sha256: str
+) -> str:
+    """The exact text the server recomputes. Do not reorder these lines."""
+    return "\n".join(
+        [
+            "Karma Runtime Request",
+            "key_id:" + key_id,
+            "method:" + method.upper(),
+            "path:" + path,
+            "timestamp:" + timestamp,
+            "nonce:" + nonce,
+            "body_sha256:" + body_sha256,
+        ]
+    )
+
+
+def build_agent_pairing_request_message(
+    *, agent_name: str, public_key: str, nonce: str, timestamp: str
+) -> str:
+    """与 services/runtime_wallet.build_agent_pairing_request_message 逐字一致。"""
+    return "\n".join(
+        [
+            "Karma Agent Pairing Request",
+            "agent_name:" + agent_name,
+            "public_key:" + public_key,
+            "nonce:" + nonce,
+            "timestamp:" + timestamp,
+        ]
+    )
+
+
+def sign_pairing_request(*, key: Any, agent_name: str, public_key: str) -> dict[str, str]:
+    """申请接入要带的三件套：证明申请方真的持有这把公钥对应的私钥。"""
+    timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    nonce = uuid.uuid4().hex
+    message = build_agent_pairing_request_message(
+        agent_name=agent_name, public_key=public_key, nonce=nonce, timestamp=timestamp
+    )
+    return {
+        "signature": base64.b64encode(key.sign(message.encode("utf-8"))).decode(),
+        "nonce": nonce,
+        "timestamp": timestamp,
+    }
+
+
+def sign_runtime_request(
+    *, key: Any, key_id: str, method: str, path: str, body: bytes
+) -> dict[str, str]:
+    """The three headers a bound key has to carry on every request."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    nonce = uuid.uuid4().hex
+    message = build_agent_request_message(
+        key_id=key_id,
+        method=method,
+        path=path,
+        timestamp=timestamp,
+        nonce=nonce,
+        body_sha256=hashlib.sha256(body or b"").hexdigest(),
+    )
+    signature = base64.b64encode(key.sign(message.encode("utf-8"))).decode()
+    return {
+        "X-Karma-Agent-Signature": signature,
+        "X-Karma-Runtime-Timestamp": timestamp,
+        "X-Karma-Runtime-Nonce": nonce,
+    }

karma_openclaw-0.4.0/karma_openclaw/agent_env.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""凭据落在哪、以及怎么把它读回来。
+
+`karma_connect_claim` 把凭据写到 ``~/.karma/agent.env``（0600）。但在此之前没有任何
+代码会把它读回 ``os.environ`` —— 也就是说：**已经跑着的 MCP 进程永远看不到刚领到的
+凭据**，非要宿主把 MCP server 重启一次才生效。而「宿主重启」恰恰是我们不能假设用户
+做得到的那一步（OpenClaw 的 config 重载链路本身就可能坏着）。
+
+所以路径解析放在这一个模块里，写盘和读盘共用；HTTP 层每次要用凭据时按文件
+mtime+size 判断是否需要重读，文件变了就立刻生效。
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+#: 这两把钥匙在 agent 侧的用途不同：API key 调公共 API，Runtime key 调 /runtime/*。
+CREDENTIAL_KEYS = (
+    "KARMA_API_KEY",
+    "KARMA_RUNTIME_KEY",
+    "KARMA_RUNTIME_URL",
+    "KARMA_AGENT_ID",
+    "KARMA_AGENT_PRIVATE_KEY",
+)
+
+
+def agent_env_path() -> Path:
+    """凭据文件位置：``KARMA_AGENT_ENV_PATH`` 覆盖，否则 ``~/.karma/agent.env``。"""
+    override = os.environ.get("KARMA_AGENT_ENV_PATH", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".karma" / "agent.env"
+
+
+def read_agent_env() -> dict:
+    """把文件解析成 dict；文件不存在或读不动时返回空 dict（不抛）。"""
+    path = agent_env_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    values: dict = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key:
+            values[key] = value.strip()
+    return values
+
+
+_cache: dict = {"stamp": None, "values": {}}
+
+
+def _stamp():
+    path = agent_env_path()
+    try:
+        st = path.stat()
+    except OSError:
+        return (str(path), None, None)
+    return (str(path), st.st_mtime_ns, st.st_size)
+
+
+def load_agent_env(force: bool = False) -> dict:
+    """磁盘上的凭据；文件变了就重读，没变就吃缓存（每次工具调用都会走这里）。"""
+    stamp = _stamp()
+    if force or _cache["stamp"] != stamp:
+        _cache["stamp"] = stamp
+        _cache["values"] = read_agent_env()
+    return _cache["values"]
+
+
+def invalidate_agent_env() -> None:
+    """刚写完文件时调用，避免同一进程里还吃旧缓存。"""
+    _cache["stamp"] = None
+    load_agent_env(force=True)
+
+
+def upsert_credential(name: str, value: str) -> Path:
+    """把一对键值并进凭据文件（0600），同名行就地替换。
+
+    agent 自己的 Ed25519 私钥要先落盘再上报：进程崩了、宿主重启了，它还得在。
+    """
+    path = agent_env_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        lines = []
+    prefix = name + "="
+    out: list = []
+    replaced = False
+    for line in lines:
+        if line.strip().startswith(prefix):
+            if not replaced:
+                out.append(prefix + value)
+                replaced = True
+            continue
+        out.append(line)
+    if not replaced:
+        out.append(prefix + value)
+    text = "\n".join(out).rstrip("\n") + "\n"
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    os.replace(tmp, path)
+    invalidate_agent_env()
+    return path
+
+
+def credential(name: str) -> str:
+    """环境变量优先（宿主显式注入的压过文件），否则回落到凭据文件。"""
+    value = (os.environ.get(name) or "").strip()
+    if value:
+        return value
+    return str(load_agent_env().get(name) or "").strip()

karma_openclaw-0.4.0/karma_openclaw/bilateral_tools.py

@@ -0,0 +1,104 @@
+"""KarmaBilateral MCP tools for OpenClaw — lock/bind/settle via BFF API."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+from karma_openclaw.http_client import api_get, api_post
+
+
+def register_bilateral_tools(mcp):
+    """Register KarmaBilateral tools on the MCP server."""
+
+    @mcp.tool()
+    async def karma_bilateral_lock(token: str, amount: str, role: str = "buyer") -> dict[str, Any]:
+        """Lock USDC into KarmaBilateral and mint a Bill Token.
+
+        Both buyer AND agent must call this before any task begins.
+        This replaces the old lockFunds flow.
+
+        Args:
+            token: ERC-20 token address (use USDC address for testnet)
+            amount: Amount in base units, e.g. '10000000' for 10 USDC
+            role: 'buyer' or 'agent'
+        """
+        return await api_post("/v1/bilateral/lock", {
+            "token": token,
+            "amount": int(amount),
+            "role": role,
+        })
+
+    @mcp.tool()
+    async def karma_bilateral_bind(buyer_bill_id: int, agent_bill_id: int, scope_description: str) -> dict[str, Any]:
+        """Bilaterally bind buyer + agent Bill Tokens. Both sides freeze.
+
+        Must be called AFTER both parties have locked (karma_bilateral_lock).
+        This enters the BOUND state — bills cannot be withdrawn until settled.
+
+        Args:
+            buyer_bill_id: The bill ID from buyer's lock call
+            agent_bill_id: The bill ID from agent's lock call
+            scope_description: Human-readable task scope, e.g. 'search:latest-pricing'
+        """
+        import hashlib
+        scope_hash = "0x" + hashlib.sha256(scope_description.encode()).hexdigest()
+        return await api_post("/v1/bilateral/bind", {
+            "buyer_bill_id": buyer_bill_id,
+            "agent_bill_id": agent_bill_id,
+            "scope_hash": scope_hash,
+        })
+
+    @mcp.tool()
+    async def karma_bilateral_settle(binding_id: int, proof_description: str) -> dict[str, Any]:
+        """Submit settlement proof for a binding. Enters FINALIZING state.
+
+        After the settle delay and dispute window pass, call
+        karma_bilateral_finalize to complete settlement.
+
+        Args:
+            binding_id: The binding ID from the bind call
+            proof_description: What was delivered, e.g. 'ipfs://Qm...evidence'
+        """
+        import hashlib
+        proof_hash = "0x" + hashlib.sha256(proof_description.encode()).hexdigest()
+        return await api_post("/v1/bilateral/settle", {
+            "binding_id": binding_id,
+            "proof_hash": proof_hash,
+        })
+
+    @mcp.tool()
+    async def karma_bilateral_finalize(binding_id: int) -> dict[str, Any]:
+        """Finalize settlement after dispute window closes. Burns bills, releases USDC.
+
+        Can only be called after the dispute window has passed since settle().
+        """
+        return await api_post(f"/v1/bilateral/finalize/{binding_id}", {})
+
+    @mcp.tool()
+    async def karma_bilateral_status(binding_id: int) -> dict[str, Any]:
+        """Query the full status of a binding — state, bill states, USDC locked.
+
+        Returns:
+            binding_id, state, bill_states (list), can_settle, can_dispute,
+            can_finalize, usdc_locked, settle_after
+        """
+        return await api_get(f"/v1/bilateral/status/{binding_id}")
+
+    @mcp.tool()
+    async def karma_bilateral_dispute(binding_id: int, reason: str) -> dict[str, Any]:
+        """Raise a dispute on a binding in FINALIZING state.
+
+        Only the buyer can dispute. Must be within the dispute window.
+
+        Args:
+            binding_id: The binding to dispute
+            reason: Human-readable reason for dispute
+        """
+        import hashlib
+        evidence_hash = "0x" + hashlib.sha256(reason.encode()).hexdigest()
+        # Dispute via direct contract call through BFF
+        return await api_post(f"/v1/bilateral/dispute/{binding_id}", {
+            "evidence_hash": evidence_hash,
+        })