@agentlayer.tech/wallet 0.1.89 → 0.1.91

package/agent-wallet/agent_wallet/providers/x402.py

@@ -1600,6 +1600,90 @@ def _reusable_approved_preview(
     return dict(approved_preview)
 
 
+#: USD amount below which an x402 payment never requires host/session/
+#: permission approval, regardless of network (including mainnet) -- the
+#: same rationale as in-person card payments skipping a signature/PIN below
+#: a floor limit. Only ever applies when the payment asset is confidently
+#: identified as USDC (see _looks_like_usdc); any other asset always
+#: requires approval, since its USD value can't be determined here.
+DE_MINIMIS_USD_THRESHOLD = 2.0
+
+
+def de_minimis_usd_amount(preview: dict[str, Any]) -> float | None:
+    """Return *preview*'s payment amount in USD, or None if it isn't confidently USDC.
+
+    ``x402_amount_display`` is only populated by normalize_payment_requirement
+    when the asset is recognized as USDC (see _looks_like_usdc) -- for any
+    other asset it's None, since its USD value is unknown here.
+    """
+    amount_display = preview.get("x402_amount_display")
+    if not isinstance(amount_display, str) or not amount_display.strip():
+        return None
+    try:
+        return float(amount_display)
+    except ValueError:
+        return None
+
+
+def is_de_minimis_payment(
+    preview: dict[str, Any],
+    *,
+    threshold_usd: float | None = None,
+) -> bool:
+    """Whether *preview*'s payment is small enough to skip approval entirely.
+
+    threshold_usd defaults to the current DE_MINIMIS_USD_THRESHOLD, read at
+    call time (not bound at import time) so tests can monkeypatch the module
+    attribute directly.
+    """
+    usd_amount = de_minimis_usd_amount(preview)
+    if usd_amount is None:
+        return False
+    effective_threshold = DE_MINIMIS_USD_THRESHOLD if threshold_usd is None else threshold_usd
+    return usd_amount < effective_threshold
+
+
+async def resolve_payment_preview(
+    *,
+    backend: AgentWalletBackend,
+    url: str,
+    method: str = "GET",
+    headers: dict[str, Any] | None = None,
+    query: dict[str, Any] | None = None,
+    json_body: Any | None = None,
+    text_body: str | None = None,
+    approved_preview: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return the payment preview for this exact request.
+
+    Reuses *approved_preview* when it still matches (same fingerprint check
+    ``pay_and_fetch`` applies before deciding whether to skip a fresh probe),
+    otherwise makes a fresh unpaid probe. Callers that need a summary to bind
+    an approval token to -- before paying -- can call this instead of
+    duplicating the reuse-or-probe logic ``pay_and_fetch`` already has.
+    """
+    request = _build_request_metadata(
+        url=url,
+        method=method,
+        headers=headers,
+        query=query,
+        json_body=json_body,
+        text_body=text_body,
+    )
+    reused = _reusable_approved_preview(approved_preview, request=request)
+    if reused is not None:
+        return reused
+    return await preview_request(
+        backend=backend,
+        url=url,
+        method=method,
+        headers=headers,
+        query=query,
+        json_body=json_body,
+        text_body=text_body,
+    )
+
+
 async def pay_and_fetch(
     *,
     backend: AgentWalletBackend,

package/agent-wallet/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-wallet",
   "name": "Agent Wallet",
   "description": "Plugin-friendly wallet backend for OpenClaw agents with safe wallet tools and runtime instructions across Solana, local BTC, and local EVM.",
-  "version": "0.1.89",
+  "version": "0.1.91",
   "skills": ["skills/wallet-operator"],
   "configSchema": {
     "type": "object",

package/agent-wallet/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openclaw-agent-wallet"
-version = "0.1.89"
+version = "0.1.91"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [

package/agent-wallet/scripts/install_agent_wallet.py

@@ -7,13 +7,20 @@ import hashlib
 import json
 import os
 import platform
+import re
 import shutil
 import subprocess
 import sys
 import tempfile
+import urllib.error
+import urllib.request
 import venv
 from pathlib import Path
 
+WELCOME_INVITE_PATTERN = re.compile(r"^alw_[A-Za-z0-9_-]{43}$")
+DEFAULT_ONBOARDING_BIND_URL = "https://www.agent-layer.tech/api/onboarding/bind-wallet"
+ONBOARDING_HTTP_TIMEOUT_SECONDS = 5.0
+
 INCLUDED_RUNTIME_ROOT_FILES = [
     ".env.example",
     "AGENTS.md",
@@ -192,9 +199,16 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--network", default="mainnet")
     parser.add_argument("--rpc-url", default="")
     parser.add_argument("--rpc-urls", default="")
+    parser.add_argument("--invite", default="")
     parser.add_argument("--sign-only", action=argparse.BooleanOptionalAction, default=False)
     parser.add_argument("--sync-runtime", action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument("--install-from-runtime", action=argparse.BooleanOptionalAction, default=False)
+    parser.add_argument(
+        "--configure-openclaw",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Patch openclaw.json during install (disabled by the universal host orchestrator).",
+    )
     parser.add_argument("--skip-python-setup", action=argparse.BooleanOptionalAction, default=False)
     parser.add_argument("--skip-node-setup", action=argparse.BooleanOptionalAction, default=False)
     parser.add_argument("--dry-run", action=argparse.BooleanOptionalAction, default=False)
@@ -856,6 +870,149 @@ def _bootstrap_evm_wallet(
     }
 
 
+def _onboarding_bind_url() -> str:
+    return (
+        os.getenv("AGENTLAYER_ONBOARDING_BIND_URL", "").strip()
+        or DEFAULT_ONBOARDING_BIND_URL
+    )
+
+
+def _onboarding_error_code(payload: object, fallback: str) -> str:
+    if not isinstance(payload, dict):
+        return fallback
+    code = str(payload.get("error") or "").strip().lower()
+    allowed = {
+        "address_already_used",
+        "internal_error",
+        "invalid_base_address",
+        "invalid_invite",
+        "invite_already_bound",
+        "invite_expired",
+        "invite_revoked",
+        "request_too_large",
+    }
+    return code if code in allowed else fallback
+
+
+def _decode_onboarding_response(raw: bytes) -> object:
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return {}
+
+
+def _bind_welcome_invite(
+    invite: str,
+    address: str,
+    *,
+    api_url: str | None = None,
+    timeout_seconds: float = ONBOARDING_HTTP_TIMEOUT_SECONDS,
+    opener: object = urllib.request.urlopen,
+    attempts: int = 2,
+) -> dict[str, object]:
+    normalized_invite = invite.strip()
+    normalized_address = address.strip()
+    if not WELCOME_INVITE_PATTERN.fullmatch(normalized_invite):
+        return {"ok": False, "status": "invalid_invite", "retryable": False}
+    if not re.fullmatch(r"0x[0-9a-fA-F]{40}", normalized_address):
+        return {"ok": False, "status": "invalid_base_address", "retryable": False}
+
+    body = json.dumps({"address": normalized_address}).encode("utf-8")
+    request = urllib.request.Request(
+        api_url or _onboarding_bind_url(),
+        data=body,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {normalized_invite}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "AgentLayer-Wallet-Installer",
+        },
+    )
+    max_attempts = max(1, min(int(attempts), 3))
+    for attempt in range(max_attempts):
+        try:
+            with opener(request, timeout=timeout_seconds) as response:  # type: ignore[operator]
+                status_code = int(getattr(response, "status", 200))
+                payload = _decode_onboarding_response(response.read(65_536))
+            if status_code < 200 or status_code >= 300 or not isinstance(payload, dict):
+                if status_code >= 500 and attempt + 1 < max_attempts:
+                    continue
+                return {
+                    "ok": False,
+                    "status": _onboarding_error_code(payload, "service_error"),
+                    "retryable": status_code >= 500,
+                }
+            binding_status = str(payload.get("status") or "")
+            response_address = str(payload.get("address") or "")
+            if (
+                payload.get("ok") is not True
+                or binding_status not in {"bound", "already_bound"}
+                or response_address.lower() != normalized_address.lower()
+            ):
+                return {"ok": False, "status": "invalid_response", "retryable": True}
+            return {
+                "ok": True,
+                "status": binding_status,
+                "network": "base",
+                "address": response_address,
+            }
+        except urllib.error.HTTPError as exc:
+            payload = _decode_onboarding_response(exc.read(65_536))
+            if exc.code >= 500 and attempt + 1 < max_attempts:
+                continue
+            return {
+                "ok": False,
+                "status": _onboarding_error_code(payload, "service_error"),
+                "retryable": exc.code >= 500,
+            }
+        except (urllib.error.URLError, TimeoutError, OSError):
+            if attempt + 1 < max_attempts:
+                continue
+            return {"ok": False, "status": "network_error", "retryable": True}
+    return {"ok": False, "status": "network_error", "retryable": True}
+
+
+def _bind_invite_after_evm_onboard(
+    invite: str,
+    evm_onboard_result: dict[str, object] | None,
+    *,
+    api_url: str | None = None,
+    opener: object = urllib.request.urlopen,
+) -> dict[str, object] | None:
+    if not invite.strip():
+        return None
+    if not isinstance(evm_onboard_result, dict) or not evm_onboard_result.get("ok"):
+        return {"ok": False, "status": "pending_evm_wallet", "retryable": True}
+    address = str(evm_onboard_result.get("address") or "").strip()
+    if not address:
+        return {"ok": False, "status": "pending_evm_wallet", "retryable": True}
+    return _bind_welcome_invite(
+        invite,
+        address,
+        api_url=api_url,
+        opener=opener,
+    )
+
+
+def _invite_binding_warning(binding_result: dict[str, object]) -> str:
+    """Describe a failed invite bind without claiming it can always be retried."""
+    status = str(binding_result.get("status") or "unknown")
+    if status == "invite_already_bound":
+        return (
+            "warning: the welcome invite is already bound to a different Base "
+            "wallet and cannot be used with this wallet. Status: "
+            + status
+        )
+    if binding_result.get("retryable") is True:
+        return (
+            "warning: the welcome invite was not bound; the invite remains "
+            "available for a safe retry. Status: "
+            + status
+        )
+    return "warning: the welcome invite was not bound and cannot be retried. Status: " + status
+
+
 def main() -> None:
     args = build_parser().parse_args()
     source_package_root = Path(args.package_root).expanduser().resolve()
@@ -909,6 +1066,7 @@ def main() -> None:
         wdk_evm_root = source_wdk_evm_root
 
     install_config_script = package_root / "scripts" / "install_openclaw_local_config.py"
+    install_sealed_keys_script = package_root / "scripts" / "install_openclaw_sealed_keys.py"
     if args.install_from_runtime:
         default_source_env_path = source_package_root / ".env"
         default_source_venv_path = source_package_root / ".venv"
@@ -923,7 +1081,7 @@ def main() -> None:
     env_created = _ensure_env_file(env_path, env_example_path)
     boot_key_file_env_updated = _ensure_runtime_boot_key_file_env(env_path)
     flash_bridge_env = _ensure_flash_bridge_env(env_path, package_root)
-    config_created = _ensure_openclaw_config(config_path)
+    config_created = _ensure_openclaw_config(config_path) if args.configure_openclaw else False
 
     python_bin = Path(sys.executable)
     venv_created = False
@@ -988,23 +1146,33 @@ def main() -> None:
     pending_env = _pending_env_names() if backend_enabled else []
     configured = False
     configure_stdout = ""
+    sealed_keys_result: dict[str, object] | None = None
     solana_onboard_result: dict[str, object] | None = None
     evm_onboard_result: dict[str, object] | None = None
+    invite_binding_result: dict[str, object] | None = None
     if backend_enabled and not pending_env and not args.dry_run:
-        result = subprocess.run(
-            _build_next_steps(
-                python_bin,
-                install_config_script,
-                args,
-                package_root=package_root,
-                extension_path=extension_path,
-            ),
+        sealed_result = subprocess.run(
+            [str(python_bin), str(install_sealed_keys_script)],
             capture_output=True,
             text=True,
             check=True,
         )
-        configured = True
-        configure_stdout = result.stdout
+        sealed_keys_result = json.loads(sealed_result.stdout)
+        if args.configure_openclaw:
+            result = subprocess.run(
+                _build_next_steps(
+                    python_bin,
+                    install_config_script,
+                    args,
+                    package_root=package_root,
+                    extension_path=extension_path,
+                ),
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            configured = True
+            configure_stdout = result.stdout
         solana_onboard_result = _bootstrap_solana_wallet(
             python_bin,
             package_root,
@@ -1027,6 +1195,21 @@ def main() -> None:
                 file=sys.stderr,
             )
 
+    if args.invite.strip():
+        if args.dry_run:
+            invite_binding_result = {
+                "ok": False,
+                "status": "skipped_dry_run",
+                "retryable": True,
+            }
+        else:
+            invite_binding_result = _bind_invite_after_evm_onboard(
+                args.invite,
+                evm_onboard_result,
+            )
+        if invite_binding_result and not invite_binding_result.get("ok"):
+            print(_invite_binding_warning(invite_binding_result), file=sys.stderr)
+
     print(
         json.dumps(
             {
@@ -1037,6 +1220,7 @@ def main() -> None:
                 "flash_bridge_env": flash_bridge_env,
                 "config_path": str(config_path),
                 "config_created": config_created,
+                "configure_openclaw": bool(args.configure_openclaw),
                 "package_root": str(package_root),
                 "extension_path": str(extension_path),
                 "wdk_btc_root": str(wdk_btc_root),
@@ -1051,8 +1235,10 @@ def main() -> None:
                 "runtime_sync": runtime_sync,
                 "configured": configured,
                 "pending_env": pending_env,
+                "sealed_keys": sealed_keys_result,
                 "solana_wallet": solana_onboard_result,
                 "evm_wallet": evm_onboard_result,
+                "invite_binding": invite_binding_result,
                 "next_configure_command": _build_next_steps(
                     python_bin,
                     install_config_script,

package/agent-wallet/scripts/install_openclaw_local_config.py

@@ -271,7 +271,10 @@ def _maybe_install_sealed_keys() -> str | None:
         updates["wdk_evm_wallet_password"] = secrets.token_urlsafe(24)
     if not updates:
         return None
-    return str(seal_keys(boot_key, {**existing, **updates}))
+    merged = {**existing, **updates}
+    if merged == existing:
+        return str(sealed_path)
+    return str(seal_keys(boot_key, merged))
 
 
 def _require_hardened_runtime_secrets(backend: str) -> str | None:

package/agent-wallet/scripts/install_openclaw_sealed_keys.py

@@ -94,15 +94,19 @@ def main() -> None:
             "and/or SOLANA_AGENT_PRIVATE_KEY in the environment."
         )
 
-    path = seal_keys(boot_key, secrets)
+    changed = not sealed_path.exists() or secrets != existing
+    path = seal_keys(boot_key, secrets) if changed else sealed_path
     print(
         json.dumps(
             {
                 "ok": True,
                 "path": str(path),
                 "stored_keys": sorted(secrets.keys()),
-                "updated_keys": sorted(set(updates.keys()) | set(generated_keys)),
+                "updated_keys": (
+                    sorted(set(updates.keys()) | set(generated_keys)) if changed else []
+                ),
                 "replaced": bool(args.replace),
+                "changed": changed,
             },
             indent=2,
         )

package/bin/lib/host-detection.mjs

@@ -0,0 +1,236 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const HOST_NAMES = Object.freeze([
+  "openclaw",
+  "codex",
+  "claude-code",
+  "hermes",
+]);
+
+const HOST_ALIASES = Object.freeze({
+  openclaw: "openclaw",
+  codex: "codex",
+  claude: "claude-code",
+  "claude-code": "claude-code",
+  claudecode: "claude-code",
+  hermes: "hermes",
+});
+
+function expandHome(value, env) {
+  const home = env.HOME || os.homedir();
+  if (value === "~") return home;
+  if (value.startsWith("~/")) return path.join(home, value.slice(2));
+  return value;
+}
+
+function existingEvidence(candidates, exists = fs.existsSync) {
+  return candidates.filter((candidate) => {
+    try {
+      return exists(candidate);
+    } catch {
+      return false;
+    }
+  });
+}
+
+function detectedHost(name, displayName, binary, configCandidates, commandPath, exists) {
+  const binaryPath = commandPath(binary);
+  const configPaths = existingEvidence(configCandidates, exists);
+  const evidence = [
+    ...(binaryPath ? [{ type: "cli", path: binaryPath }] : []),
+    ...configPaths.map((configPath) => ({ type: "config", path: configPath })),
+  ];
+  return {
+    name,
+    display_name: displayName,
+    detected: evidence.length > 0,
+    confidence: evidence.length > 0 ? "high" : "none",
+    evidence,
+  };
+}
+
+export function detectHosts({
+  env = process.env,
+  commandPath,
+  exists = fs.existsSync,
+} = {}) {
+  if (typeof commandPath !== "function") {
+    throw new TypeError("detectHosts requires commandPath(name)");
+  }
+  const home = env.HOME || os.homedir();
+  const openclawHome = path.resolve(expandHome(env.OPENCLAW_HOME || "~/.openclaw", env));
+  const codexHome = path.resolve(expandHome(env.CODEX_HOME || "~/.codex", env));
+  const hermesHome = path.resolve(expandHome(env.HERMES_HOME || "~/.hermes", env));
+  const claudeHome = path.resolve(expandHome(env.CLAUDE_CONFIG_DIR || "~/.claude", env));
+
+  return [
+    detectedHost(
+      "openclaw",
+      "OpenClaw",
+      "openclaw",
+      [path.join(openclawHome, "openclaw.json")],
+      commandPath,
+      exists,
+    ),
+    detectedHost(
+      "codex",
+      "Codex",
+      "codex",
+      [path.join(codexHome, "config.toml")],
+      commandPath,
+      exists,
+    ),
+    detectedHost(
+      "claude-code",
+      "Claude Code",
+      "claude",
+      [
+        path.join(claudeHome, "settings.json"),
+        path.join(home, ".claude.json"),
+      ],
+      commandPath,
+      exists,
+    ),
+    detectedHost(
+      "hermes",
+      "Hermes",
+      "hermes",
+      [
+        path.join(hermesHome, "config.yaml"),
+        path.join(hermesHome, "config.yml"),
+        path.join(hermesHome, "settings.json"),
+      ],
+      commandPath,
+      exists,
+    ),
+  ];
+}
+
+function flagValues(args, name) {
+  const values = [];
+  const prefix = `${name}=`;
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === name) {
+      const next = args[index + 1] || "";
+      if (!next || next.startsWith("--")) {
+        throw new Error(`${name} requires a value.`);
+      }
+      values.push(next);
+      index += 1;
+    } else if (value.startsWith(prefix)) {
+      values.push(value.slice(prefix.length));
+    }
+  }
+  return values;
+}
+
+function normalizeHostToken(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return HOST_ALIASES[normalized] || normalized;
+}
+
+function parseHostSet(values, { detected, managed }) {
+  const selected = new Set();
+  for (const rawValue of values) {
+    for (const rawToken of String(rawValue).split(",")) {
+      const token = normalizeHostToken(rawToken);
+      if (!token) continue;
+      if (token === "none" || token === "runtime-only") {
+        selected.clear();
+        continue;
+      }
+      if (token === "all") {
+        HOST_NAMES.forEach((name) => selected.add(name));
+        continue;
+      }
+      if (token === "detected") {
+        detected.forEach((name) => selected.add(name));
+        continue;
+      }
+      if (token === "managed") {
+        managed.forEach((name) => selected.add(name));
+        continue;
+      }
+      if (!HOST_NAMES.includes(token)) {
+        throw new Error(
+          `Unknown host '${rawToken}'. Expected: ${HOST_NAMES.join(", ")}, detected, managed, all, or none.`,
+        );
+      }
+      selected.add(token);
+    }
+  }
+  return selected;
+}
+
+export function buildInstallPlan({
+  args,
+  detections,
+  managedHosts = [],
+  runtimeInstalled,
+}) {
+  const detected = detections.filter((entry) => entry.detected).map((entry) => entry.name);
+  const managed = managedHosts.filter((name) => HOST_NAMES.includes(name));
+  const hostValues = flagValues(args, "--hosts");
+  const explicitHosts = hostValues.length > 0;
+  const runtimeOnly = args.includes("--runtime-only");
+  const managedOnly = args.includes("--managed-only");
+
+  let selected;
+  let selectionReason;
+  if (runtimeOnly) {
+    selected = new Set();
+    selectionReason = "runtime_only";
+  } else if (managedOnly) {
+    selected = new Set(managed);
+    selectionReason = "managed_only";
+  } else if (explicitHosts) {
+    selected = parseHostSet(hostValues, { detected, managed });
+    selectionReason = "explicit";
+  } else if (runtimeInstalled) {
+    selected = new Set(managed);
+    selectionReason = "existing_runtime_managed_only";
+  } else {
+    selected = new Set(detected);
+    selectionReason = "fresh_install_detected";
+  }
+
+  const excluded = parseHostSet(flagValues(args, "--exclude"), { detected, managed });
+  excluded.forEach((name) => selected.delete(name));
+
+  return {
+    schema_version: 1,
+    runtime_installed_before: Boolean(runtimeInstalled),
+    selection_reason: selectionReason,
+    explicit_hosts: explicitHosts,
+    detected_hosts: detected,
+    managed_hosts: managed,
+    selected_hosts: HOST_NAMES.filter((name) => selected.has(name)),
+    excluded_hosts: HOST_NAMES.filter((name) => excluded.has(name)),
+    detections,
+  };
+}
+
+export function stripUniversalInstallerArgs(args) {
+  const output = [];
+  const valueFlags = new Set(["--hosts", "--exclude"]);
+  const booleanFlags = new Set([
+    "--runtime-only",
+    "--managed-only",
+    "--no-prompt",
+    "--json",
+  ]);
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (booleanFlags.has(value)) continue;
+    if (valueFlags.has(value)) {
+      index += 1;
+      continue;
+    }
+    if ([...valueFlags].some((name) => value.startsWith(`${name}=`))) continue;
+    output.push(value);
+  }
+  return output;
+}