@agentlayer.tech/wallet 0.1.10 → 0.1.11

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,29 @@
+"""Hermes Agent plugin bridge for AgentLayer wallet tools."""
+
+from .schemas import AGENT_WALLET_APPROVE, AGENT_WALLET_INVOKE, AGENT_WALLET_TOOLS
+from .tools import agent_wallet_approve, 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"],
+    )

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -0,0 +1,7 @@
+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

package/hermes/plugins/agent_wallet/schemas.py

@@ -0,0 +1,134 @@
+"""Tool schemas exposed to Hermes Agent."""
+
+AGENT_WALLET_TOOLS = {
+    "name": "agent_wallet_tools",
+    "description": (
+        "List AgentLayer wallet capabilities available through the Hermes bridge. "
+        "Use this before agent_wallet_invoke when you need the exact underlying "
+        "wallet tool names, JSON schemas, or safety levels. This is read-only and "
+        "does not create, unlock, or modify wallets."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "backend": {
+                "type": "string",
+                "enum": ["all", "solana_local", "wdk_btc_local", "wdk_evm_local"],
+                "description": "Optional backend filter. Defaults to all.",
+            },
+        },
+        "additionalProperties": False,
+    },
+}
+
+AGENT_WALLET_INVOKE = {
+    "name": "agent_wallet_invoke",
+    "description": (
+        "Invoke one existing AgentLayer/OpenClaw wallet tool through the local "
+        "Python wallet backend. Prefer read-only tools and preview modes first. "
+        "Execute modes require an approval_token from agent_wallet_approve bound "
+        "to the exact previewed operation after explicit user confirmation."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "tool_name": {
+                "type": "string",
+                "description": "Underlying wallet tool name, for example get_wallet_address or transfer_sol.",
+            },
+            "arguments": {
+                "type": "object",
+                "description": "JSON arguments for the underlying wallet tool.",
+                "additionalProperties": True,
+            },
+            "backend": {
+                "type": "string",
+                "enum": ["solana_local", "wdk_btc_local", "wdk_evm_local"],
+                "description": "Optional backend override for this invocation.",
+            },
+            "network": {
+                "type": "string",
+                "description": "Optional network override, such as devnet, mainnet, bitcoin, ethereum, or base.",
+            },
+            "user_id": {
+                "type": "string",
+                "description": "Optional local wallet owner id. Defaults to AGENT_WALLET_USER_ID, USER, or hermes-local-user.",
+            },
+            "config": {
+                "type": "object",
+                "description": (
+                    "Optional non-secret wallet config overrides. Do not include privateKey, "
+                    "masterKey, or approvalSecret."
+                ),
+                "additionalProperties": True,
+            },
+        },
+        "required": ["tool_name"],
+        "additionalProperties": False,
+    },
+}
+
+AGENT_WALLET_APPROVE = {
+    "name": "agent_wallet_approve",
+    "description": (
+        "Issue a short-lived AgentLayer/OpenClaw approval_token for one exact "
+        "wallet execute operation after the user explicitly confirms the previewed "
+        "confirmation_summary. Use only after agent_wallet_invoke preview/prepare "
+        "returns the exact confirmation_summary. Mainnet approvals require "
+        "mainnet_confirmed=true."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "tool_name": {
+                "type": "string",
+                "description": "Underlying wallet tool name that will be executed.",
+            },
+            "confirmation_summary": {
+                "type": "object",
+                "description": (
+                    "Exact confirmation_summary from the preview or prepare result. "
+                    "Do not edit or summarize it."
+                ),
+                "additionalProperties": True,
+            },
+            "user_confirmed": {
+                "type": "boolean",
+                "description": "Must be true only after the user explicitly approves this exact operation.",
+            },
+            "mainnet_confirmed": {
+                "type": "boolean",
+                "description": "Must be true for mainnet execute operations after explicit mainnet confirmation.",
+            },
+            "ttl_seconds": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 3600,
+                "description": "Optional approval token lifetime in seconds.",
+            },
+            "backend": {
+                "type": "string",
+                "enum": ["solana_local", "wdk_btc_local", "wdk_evm_local"],
+                "description": "Optional backend override matching the planned execute invocation.",
+            },
+            "network": {
+                "type": "string",
+                "description": "Optional network override matching the planned execute invocation.",
+            },
+            "user_id": {
+                "type": "string",
+                "description": "Optional local wallet owner id. Defaults to AGENT_WALLET_USER_ID, USER, or hermes-local-user.",
+            },
+            "config": {
+                "type": "object",
+                "description": (
+                    "Optional non-secret wallet config overrides matching the planned execute invocation. "
+                    "Do not include privateKey, masterKey, or approvalSecret."
+                ),
+                "additionalProperties": True,
+            },
+        },
+        "required": ["tool_name", "confirmation_summary", "user_confirmed"],
+        "additionalProperties": False,
+    },
+}