@agentlayer.tech/wallet 0.1.10 → 0.1.12

package/agent-wallet/scripts/setup_evm_wallet.sh

@@ -0,0 +1,151 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+PACKAGE_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
+
+resolve_python_bin() {
+  if [ -n "${OPENCLAW_AGENT_WALLET_PYTHON:-}" ] && [ -x "${OPENCLAW_AGENT_WALLET_PYTHON}" ]; then
+    printf "%s" "${OPENCLAW_AGENT_WALLET_PYTHON}"
+    return 0
+  fi
+
+  if [ -x "/tmp/agent-wallet-venv/bin/python" ]; then
+    printf "%s" "/tmp/agent-wallet-venv/bin/python"
+    return 0
+  fi
+
+  if [ -x "$PACKAGE_ROOT/.venv/bin/python" ]; then
+    printf "%s" "$PACKAGE_ROOT/.venv/bin/python"
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    command -v python3
+    return 0
+  fi
+
+  command -v python
+}
+
+PYTHON_BIN=$(resolve_python_bin)
+export OPENCLAW_AGENT_WALLET_PYTHON="$PYTHON_BIN"
+
+has_flag() {
+  flag=$1
+  shift
+  for arg in "$@"; do
+    case "$arg" in
+      "$flag"|"$flag"=*)
+        return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+prompt_with_default() {
+  label=$1
+  default_value=$2
+  if [ -t 0 ]; then
+    printf "%s [%s]: " "$label" "$default_value" >&2
+    read -r value
+    if [ -z "${value:-}" ]; then
+      printf "%s" "$default_value"
+    else
+      printf "%s" "$value"
+    fi
+    return 0
+  fi
+  printf "%s" "$default_value"
+}
+
+normalize_network_value() {
+  case $(printf "%s" "$1" | tr '[:upper:]' '[:lower:]') in
+    1|ethereum|eth|mainnet)
+      printf "ethereum"
+      ;;
+    2|base)
+      printf "base"
+      ;;
+    3|sepolia)
+      printf "sepolia"
+      ;;
+    4|base-sepolia|base_sepolia)
+      printf "base-sepolia"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+prompt_network_choice() {
+  default_value=$1
+  if ! [ -t 0 ]; then
+    printf "%s" "$default_value"
+    return 0
+  fi
+
+  case "$default_value" in
+    ethereum) default_hint="1" ;;
+    base) default_hint="2" ;;
+    sepolia) default_hint="3" ;;
+    base-sepolia) default_hint="4" ;;
+    *) default_hint="2" ;;
+  esac
+
+  while true; do
+    printf "EVM network:\n" >&2
+    printf "  1) ethereum\n" >&2
+    printf "  2) base\n" >&2
+    printf "  3) sepolia\n" >&2
+    printf "  4) base-sepolia\n" >&2
+    printf "Choose network [%s]: " "$default_hint" >&2
+    read -r choice
+    if [ -z "${choice:-}" ]; then
+      choice=$default_hint
+    fi
+    if network=$(normalize_network_value "$choice"); then
+      printf "%s" "$network"
+      return 0
+    fi
+    printf "Invalid choice. Enter 1, 2, 3, 4, ethereum, base, sepolia, or base-sepolia.\n" >&2
+  done
+}
+
+DEFAULT_USER_ID=${OPENCLAW_EVM_USER_ID:-${USER:-openclaw-user}-local}
+DEFAULT_NETWORK=${OPENCLAW_EVM_NETWORK:-base}
+DEFAULT_SERVICE_URL=${OPENCLAW_EVM_SERVICE_URL:-http://127.0.0.1:8081}
+
+if ! has_flag --user-id "$@"; then
+  USER_ID=$(prompt_with_default "OpenClaw user id" "$DEFAULT_USER_ID")
+  set -- "$@" --user-id "$USER_ID"
+fi
+
+if ! has_flag --network "$@"; then
+  NETWORK=$(prompt_network_choice "$DEFAULT_NETWORK")
+  set -- "$@" --network "$NETWORK"
+fi
+
+if ! has_flag --service-url "$@"; then
+  set -- "$@" --service-url "$DEFAULT_SERVICE_URL"
+fi
+
+if ! has_flag --config-path "$@" && [ -n "${OPENCLAW_EVM_CONFIG_PATH:-}" ]; then
+  set -- "$@" --config-path "$OPENCLAW_EVM_CONFIG_PATH"
+fi
+
+if ! has_flag --wdk-wallet-root "$@" && [ -n "${OPENCLAW_EVM_WDK_WALLET_ROOT:-}" ]; then
+  set -- "$@" --wdk-wallet-root "$OPENCLAW_EVM_WDK_WALLET_ROOT"
+fi
+
+if ! has_flag --python-bin "$@"; then
+  set -- "$@" --python-bin "$PYTHON_BIN"
+fi
+
+if ! has_flag --package-root "$@"; then
+  set -- "$@" --package-root "$PACKAGE_ROOT"
+fi
+
+exec "$PYTHON_BIN" "$SCRIPT_DIR/bootstrap_openclaw_evm.py" "$@"

package/bin/openclaw-agent-wallet.mjs

@@ -19,6 +19,7 @@ function printHelp() {
 
 Usage:
   openclaw-agent-wallet install [options]
+  openclaw-agent-wallet hermes install [options]
   openclaw-agent-wallet update [options]
   openclaw-agent-wallet status
   openclaw-agent-wallet rollback [--to <version>]
@@ -33,6 +34,7 @@ Common install options:
 
 Examples:
   npx @agentlayer.tech/wallet install --yes
+  npx @agentlayer.tech/wallet hermes install --yes
   npx @agentlayer.tech/wallet install --backend none
   npx @agentlayer.tech/wallet update --yes
   npx @agentlayer.tech/wallet status
@@ -65,6 +67,10 @@ function resolveRuntimeBase(env = process.env) {
   return path.join(resolveOpenclawHome(env), "agent-wallet-runtime");
 }
 
+function resolveHermesHome(env = process.env) {
+  return path.resolve(expandHome(env.HERMES_HOME || "~/.hermes"));
+}
+
 function releaseRootFor(version, env = process.env) {
   return path.join(resolveRuntimeBase(env), "releases", version);
 }
@@ -73,6 +79,21 @@ function currentRuntimePath(env = process.env) {
   return path.join(resolveRuntimeBase(env), "current");
 }
 
+function resolvedCurrentRuntimeRoot(env = process.env) {
+  const currentPath = currentRuntimePath(env);
+  const currentTarget = readLinkOrNull(currentPath);
+  if (currentTarget) {
+    return path.resolve(path.dirname(currentPath), currentTarget);
+  }
+  try {
+    const stat = fs.statSync(currentPath);
+    if (stat.isDirectory()) return currentPath;
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return "";
+}
+
 function previousRuntimePath(env = process.env) {
   return path.join(resolveRuntimeBase(env), "previous");
 }
@@ -282,6 +303,31 @@ function envFileSet(pathname, updates) {
   }
 }
 
+function envFileUnset(pathname, keys) {
+  let lines = [];
+  try {
+    lines = fs.readFileSync(pathname, "utf8").split(/\r?\n/);
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  const blocked = new Set(keys);
+  const next = [];
+  for (const line of lines) {
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/);
+    if (match && blocked.has(match[1])) {
+      continue;
+    }
+    if (line.length > 0) next.push(line);
+  }
+  fs.writeFileSync(pathname, `${next.join("\n")}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(pathname, 0o600);
+  } catch {
+    // ignored
+  }
+}
+
 function readEnvFile(pathname) {
   try {
     const result = {};
@@ -297,13 +343,55 @@ function readEnvFile(pathname) {
 }
 
 function currentBootKey(env = process.env) {
-  const currentPath = currentRuntimePath(env);
-  const currentTarget = readLinkOrNull(currentPath);
-  if (!currentTarget) return "";
-  const currentRoot = path.resolve(path.dirname(currentPath), currentTarget);
+  const currentRoot = resolvedCurrentRuntimeRoot(env);
+  if (!currentRoot) return "";
   return readEnvFile(path.join(currentRoot, "agent-wallet", ".env")).AGENT_WALLET_BOOT_KEY || "";
 }
 
+function readTextIfExists(pathname) {
+  try {
+    return fs.readFileSync(pathname, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+function writeSecretFile(pathname, value) {
+  fs.mkdirSync(path.dirname(pathname), { recursive: true });
+  fs.writeFileSync(pathname, `${String(value || "").trim()}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(pathname, 0o600);
+  } catch {
+    // ignored
+  }
+}
+
+function resolveBootKeyFromFile(env = process.env) {
+  const keyFile = String(env.AGENT_WALLET_BOOT_KEY_FILE || "").trim();
+  if (!keyFile) return "";
+  return readTextIfExists(path.resolve(expandHome(keyFile))).trim();
+}
+
+function defaultBootKeyFile(env = process.env) {
+  return path.join(resolveRuntimeBase(env), "boot-key");
+}
+
+function ensureBootKeyFile(env = process.env) {
+  const configuredFile = String(env.AGENT_WALLET_BOOT_KEY_FILE || "").trim();
+  const keyFile = configuredFile ? path.resolve(expandHome(configuredFile)) : defaultBootKeyFile(env);
+  const existing = readTextIfExists(keyFile).trim();
+  if (existing) {
+    return { path: keyFile, status: "existing" };
+  }
+  const bootKey = String(env.AGENT_WALLET_BOOT_KEY || "").trim() || resolveBootKeyFromFile(env) || currentBootKey(env);
+  if (!bootKey) {
+    return { path: keyFile, status: "missing" };
+  }
+  writeSecretFile(keyFile, bootKey);
+  return { path: keyFile, status: "created" };
+}
+
 function runDoctor() {
   const requiredPaths = [
     ["setup.sh", setupPath],
@@ -380,7 +468,7 @@ function buildInstallerEnv(args) {
   const sealedKeysPath = path.join(resolveOpenclawHome(env), "sealed_keys.json");
   const sealedKeysExist = fs.existsSync(sealedKeysPath);
   if (!env.AGENT_WALLET_BOOT_KEY) {
-    const existingBootKey = currentBootKey(env);
+    const existingBootKey = resolveBootKeyFromFile(env) || currentBootKey(env);
     if (existingBootKey) {
       env.AGENT_WALLET_BOOT_KEY = existingBootKey;
     }
@@ -523,6 +611,132 @@ function runRollback(args) {
   return 0;
 }
 
+function resolveHermesPluginSource() {
+  const currentRoot = resolvedCurrentRuntimeRoot();
+  const candidates = [];
+  if (currentRoot) {
+    candidates.push(path.join(currentRoot, "hermes", "plugins", "agent_wallet"));
+  }
+  candidates.push(path.join(packageRoot, "hermes", "plugins", "agent_wallet"));
+  for (const source of candidates) {
+    if (fs.existsSync(path.join(source, "plugin.yaml"))) {
+      return source;
+    }
+  }
+  throw new Error(`Missing Hermes plugin bundle. Checked: ${candidates.join(", ")}`);
+}
+
+function resolveAgentWalletPackageRoot(env = process.env) {
+  const currentRoot = resolvedCurrentRuntimeRoot(env);
+  if (currentRoot) {
+    const runtimePackage = path.join(currentRoot, "agent-wallet");
+    if (fs.existsSync(path.join(runtimePackage, "agent_wallet", "__init__.py"))) {
+      return runtimePackage;
+    }
+  }
+  return path.join(packageRoot, "agent-wallet");
+}
+
+function resolveAgentWalletPython(packageRootPath) {
+  for (const candidate of [
+    process.env.AGENT_WALLET_PYTHON,
+    process.env.OPENCLAW_AGENT_WALLET_PYTHON,
+    path.join(packageRootPath, ".venv", "bin", "python"),
+    path.join(packageRootPath, ".runtime-venv", "bin", "python"),
+    commandPath("python3"),
+  ]) {
+    if (!candidate) continue;
+    if (path.isAbsolute(candidate) && !fs.existsSync(candidate)) continue;
+    return candidate;
+  }
+  return "python3";
+}
+
+function runHermesInstall(args) {
+  const hermesHome = resolveHermesHome();
+  const userPluginsDir = path.join(hermesHome, "plugins");
+  const pluginSource = resolveHermesPluginSource();
+  const pluginTarget = path.join(userPluginsDir, "agent_wallet");
+  const force = hasFlag(args, "--force");
+  const skipEnable = hasFlag(args, "--skip-enable");
+  const hermesBin = commandPath("hermes");
+  const agentWalletPackageRoot = resolveAgentWalletPackageRoot();
+  const agentWalletPython = resolveAgentWalletPython(agentWalletPackageRoot);
+  const hermesEnvPath = path.join(hermesHome, ".env");
+  const existingHermesEnv = readEnvFile(hermesEnvPath);
+  const bootKeyFile = ensureBootKeyFile({ ...process.env, ...existingHermesEnv });
+
+  fs.mkdirSync(userPluginsDir, { recursive: true });
+  try {
+    const existing = fs.lstatSync(pluginTarget);
+    if (!existing.isSymbolicLink()) {
+      if (!force) {
+        throw new Error(`${pluginTarget} exists and is not a symlink. Pass --force to replace it.`);
+      }
+      fs.rmSync(pluginTarget, { recursive: true, force: true });
+    } else {
+      fs.unlinkSync(pluginTarget);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  fs.symlinkSync(pluginSource, pluginTarget, "dir");
+
+  envFileSet(hermesEnvPath, {
+    AGENT_WALLET_PACKAGE_ROOT: agentWalletPackageRoot,
+    AGENT_WALLET_PYTHON: agentWalletPython,
+    AGENT_WALLET_BOOT_KEY_FILE: bootKeyFile.path,
+  });
+  if (bootKeyFile.status !== "missing") {
+    envFileUnset(hermesEnvPath, ["AGENT_WALLET_BOOT_KEY"]);
+  }
+
+  let enable = { attempted: false, ok: false, skipped: skipEnable, error: "" };
+  if (!skipEnable) {
+    if (!hermesBin) {
+      enable = {
+        attempted: false,
+        ok: false,
+        skipped: false,
+        error: "Hermes CLI was not found on PATH. Run `hermes plugins enable agent-wallet` after installing Hermes.",
+      };
+    } else {
+      const result = spawnSync(hermesBin, ["plugins", "enable", "agent-wallet"], {
+        cwd: packageRoot,
+        encoding: "utf8",
+        env: { ...process.env, HERMES_HOME: hermesHome },
+      });
+      enable = {
+        attempted: true,
+        ok: result.status === 0,
+        skipped: false,
+        error: result.status === 0 ? "" : (result.stderr || result.stdout || "").trim(),
+      };
+    }
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: enable.skipped || enable.ok,
+        hermes_home: hermesHome,
+        plugin_source: pluginSource,
+        plugin_target: pluginTarget,
+        env_path: hermesEnvPath,
+        agent_wallet_package_root: agentWalletPackageRoot,
+        agent_wallet_python: agentWalletPython,
+        boot_key_file: bootKeyFile.path,
+        boot_key_file_status: bootKeyFile.status,
+        hermes_enable: enable,
+        restart_required: true,
+      },
+      null,
+      2,
+    ),
+  );
+  return enable.skipped || enable.ok ? 0 : 1;
+}
+
 const args = process.argv.slice(2);
 const command = args[0] || "install";
 
@@ -556,6 +770,16 @@ if (command === "rollback") {
   process.exit(runRollback(args.slice(1)));
 }
 
+if (command === "hermes") {
+  const subcommand = args[1] || "install";
+  if (subcommand === "install" || subcommand === "setup") {
+    process.exit(runHermesInstall(args.slice(2)));
+  }
+  console.error(`Unknown hermes command: ${subcommand}`);
+  console.error("Run `openclaw-agent-wallet hermes install --yes` to connect Hermes Agent.");
+  process.exit(2);
+}
+
 if (command.startsWith("-")) {
   process.exit(runInstall(args, { commandName: "install" }));
 }

package/hermes/plugins/agent_wallet/README.md

@@ -0,0 +1,54 @@
+# AgentLayer Wallet Hermes Plugin
+
+This is a thin Hermes Agent bridge to the existing AgentLayer/OpenClaw wallet backend.
+
+It intentionally does not copy the OpenClaw TypeScript extension or reimplement wallet policy. Hermes gets three tools:
+
+- `agent_wallet_tools` - lists the underlying wallet tools and schemas from the Python adapter without creating or unlocking a wallet.
+- `agent_wallet_invoke` - forwards one tool call to `python -m agent_wallet.openclaw_cli invoke`.
+- `agent_wallet_approve` - issues a short-lived approval token through `python -m agent_wallet.openclaw_cli issue-approval` after explicit user confirmation of the exact preview summary.
+
+OpenClaw remains the primary local environment. This plugin only expands the same backend into Hermes.
+
+## Integration Plan
+
+1. Keep wallet behavior and safety policy in `agent-wallet/`.
+2. Keep OpenClaw as the primary environment and leave `.openclaw/extensions/agent-wallet` unchanged.
+3. Register a small Hermes bridge instead of one Hermes tool per wallet operation.
+4. Use discovery from `OpenClawWalletAdapter.list_tools()` so Hermes sees the current backend schemas without duplicated metadata.
+5. Forward execution to `agent_wallet.openclaw_cli invoke` so config validation, sealed secrets, approval-token checks, and backend dispatch stay authoritative in Python.
+6. Forward token issuance to `agent_wallet.openclaw_cli issue-approval` so Hermes can complete preview/approve/execute without learning sealed secrets.
+7. Cache successful Solana swap previews briefly in Hermes and bind the cached payload digest into the approval token. Execute can then reuse the exact Jupiter preview the user approved instead of re-quoting volatile markets.
+8. Add broader Hermes ergonomics later only where it improves safety, such as an installer wrapper or read-only status command.
+
+## Install
+
+Copy or symlink this directory into a Hermes plugin path:
+
+```bash
+mkdir -p ~/.hermes/plugins
+ln -s /absolute/path/to/openclaw_skill/hermes/plugins/agent_wallet ~/.hermes/plugins/agent_wallet
+```
+
+Set the wallet package root if Hermes is not launched from this repository:
+
+```bash
+export AGENT_WALLET_PACKAGE_ROOT=/absolute/path/to/openclaw_skill/agent-wallet
+export AGENT_WALLET_PYTHON=python3
+```
+
+Then enable or reload plugins in Hermes:
+
+```bash
+hermes plugins
+hermes chat
+```
+
+## Runtime Notes
+
+- Secrets must stay in the existing protected runtime path, especially `~/.openclaw/sealed_keys.json`.
+- Do not pass `privateKey`, `masterKey`, or `approvalSecret` through Hermes tool config.
+- Write-capable wallet tools still require preview first and an `approval_token` bound to the exact `confirmation_summary`.
+- Use `agent_wallet_approve` only after the user explicitly confirms the exact operation. Mainnet execute requires `mainnet_confirmed=true`.
+- Use `agent_wallet_tools` before invoking unfamiliar tool names.
+- Solana swap previews are cached at `~/.hermes/agent_wallet_preview_cache.json` with `0600` permissions for a short window. The cache contains unsigned preview payloads only; signing and approval checks remain in `agent-wallet/`.

package/hermes/plugins/agent_wallet/__init__.py

@@ -0,0 +1,55 @@
+"""Hermes Agent plugin bridge for AgentLayer wallet tools."""
+
+from .schemas import (
+    AGENT_WALLET_APPROVE,
+    AGENT_WALLET_EVM_SETUP,
+    AGENT_WALLET_EVM_STATUS,
+    AGENT_WALLET_INVOKE,
+    AGENT_WALLET_TOOLS,
+)
+from .tools import (
+    agent_wallet_approve,
+    agent_wallet_evm_setup,
+    agent_wallet_evm_status,
+    agent_wallet_invoke,
+    agent_wallet_tools,
+)
+
+
+def register(ctx):
+    """Register a narrow dispatcher instead of duplicating wallet tools."""
+    ctx.register_tool(
+        name=AGENT_WALLET_TOOLS["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_TOOLS,
+        handler=agent_wallet_tools,
+        description=AGENT_WALLET_TOOLS["description"],
+    )
+    ctx.register_tool(
+        name=AGENT_WALLET_INVOKE["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_INVOKE,
+        handler=agent_wallet_invoke,
+        description=AGENT_WALLET_INVOKE["description"],
+    )
+    ctx.register_tool(
+        name=AGENT_WALLET_APPROVE["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_APPROVE,
+        handler=agent_wallet_approve,
+        description=AGENT_WALLET_APPROVE["description"],
+    )
+    ctx.register_tool(
+        name=AGENT_WALLET_EVM_STATUS["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_EVM_STATUS,
+        handler=agent_wallet_evm_status,
+        description=AGENT_WALLET_EVM_STATUS["description"],
+    )
+    ctx.register_tool(
+        name=AGENT_WALLET_EVM_SETUP["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_EVM_SETUP,
+        handler=agent_wallet_evm_setup,
+        description=AGENT_WALLET_EVM_SETUP["description"],
+    )

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -0,0 +1,9 @@
+name: agent-wallet
+version: 0.1.0
+description: Thin Hermes Agent bridge to the existing AgentLayer/OpenClaw wallet backend
+provides_tools:
+  - agent_wallet_tools
+  - agent_wallet_invoke
+  - agent_wallet_approve
+  - agent_wallet_evm_status
+  - agent_wallet_evm_setup