@agentlayer.tech/wallet 0.1.19 → 0.1.21

package/.openclaw/extensions/agent-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayertech/agent-wallet-plugin",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "OpenClaw plugin bridge for the AgentLayer wallet runtime.",
   "type": "module",
   "license": "SEE LICENSE IN ../../../LICENSE",

package/README.md

@@ -3,6 +3,7 @@
 
 [![npm version](https://img.shields.io/npm/v/%40agentlayer.tech%2Fwallet)](https://www.npmjs.com/package/@agentlayer.tech/wallet)
 [![npm downloads](https://img.shields.io/npm/dm/%40agentlayer.tech%2Fwallet)](https://www.npmjs.com/package/@agentlayer.tech/wallet)
+[![docs](https://img.shields.io/badge/docs-agent--layer.tech-blue)](https://docs.agent-layer.tech/)
 [![license](https://img.shields.io/github/license/lopushok9/Agent-Layer)](https://github.com/lopushok9/Agent-Layer/blob/main/LICENSE)
 
 ```bash
@@ -82,9 +83,13 @@ wallet status
 wallet doctor
 wallet hermes install --yes
 wallet update --yes
+wallet update --yes --dry-run
 wallet rollback
 ```
 
+`wallet update --yes` now delegates to the latest published npm package and reuses shared Python and Node dependency snapshots when they have not changed, so frequent upgrades do not need to rebuild every runtime dependency from scratch.
+Use `wallet update --yes --dry-run` to inspect the target runtime version and whether Python/Node dependency snapshots will be reused or rebuilt before switching `current`.
+
 ## Native OpenClaw plugin installs
 
 Use ClawHub when you want the plugin itself to be installed through OpenClaw:
@@ -115,6 +120,111 @@ sh ./setup.sh
 
 If you want the installer to finish the OpenClaw plugin wiring in the same pass, provide the runtime secrets before running it:
 
+## Wallet capabilities through external services
+
+AgentLayer keeps keys, approvals, and signing local, but the wallet can still operate through a set of registered provider-backed tools. These tools are exposed through the OpenClaw wallet plugin as explicit service integrations rather than raw shell access, config editing, or backend switching.
+
+### x402 paid APIs
+
+The x402 bundle turns the wallet into a buyer for metered APIs and paid HTTP endpoints:
+
+- `x402_search_services` - search x402-paid services through discovery providers such as CDP Bazaar and Agentic Market without spending funds.
+- `x402_get_service_details` - resolve one discovered service or resource into a normalized detail payload before attempting payment.
+- `x402_preview_request` - make an unpaid request, detect `402 Payment Required`, and summarize payment terms and supported payment options.
+- `x402_pay_request` - prepare or execute the paid retry through the active wallet backend. The current flow executes the Solana exact-buyer path and keeps EVM as prepare-only.
+
+This gives the wallet a direct bridge from service discovery to paid API consumption while preserving approval-token checks before execution.
+
+### LI.FI cross-chain routing
+
+The LI.FI bundle covers discovery, quote inspection, transfer tracking, and routed execution across Solana, Ethereum, and Base:
+
+- `get_lifi_supported_chains` - list the chains currently allowed for LI.FI routing in the wallet surface.
+- `get_lifi_quote` - fetch a read-only cross-chain quote before any execution planning.
+- `get_lifi_transfer_status` - inspect a routed transfer by transaction hash or LI.FI step id.
+- `swap_solana_lifi_cross_chain_tokens` - preview, prepare, or execute a Solana-origin cross-chain route into Ethereum or Base.
+- `swap_evm_lifi_cross_chain_tokens` - preview, prepare, or execute an EVM-origin cross-chain route across Ethereum, Base, and Solana when LI.FI returns a route.
+
+### Jupiter trading and yield
+
+On Solana, Jupiter-backed tools cover market pricing, swaps, and Jupiter Earn vault flows:
+
+- `get_solana_token_prices` - fetch current Solana token pricing through Jupiter.
+- `swap_solana_tokens` - preview, prepare, or execute a Jupiter-routed Solana token swap.
+- `get_jupiter_earn_tokens` - list Jupiter Earn vault assets currently supported on mainnet.
+- `get_jupiter_earn_positions` - inspect wallet positions in Jupiter Earn vaults.
+- `get_jupiter_earn_earnings` - fetch earnings for one or more Jupiter Earn positions.
+- `jupiter_earn_deposit` - preview, prepare, or execute a Jupiter Earn deposit.
+- `jupiter_earn_withdraw` - preview, prepare, or execute a Jupiter Earn withdrawal.
+
+### Houdini private payouts
+
+For privacy-preserving Solana payout flows, the wallet exposes a Houdini-backed bundle:
+
+- `swap_solana_privately` - create a preview or approved private payout through Houdini routing. The current MVP supports same-token flows such as `SOL -> SOL` and `USDC -> USDC`.
+- `continue_solana_private_swap` - continue a previously created Houdini order and submit the local funding transfer to the returned deposit address.
+- `get_solana_private_swap_status` - check Houdini status for an existing private payout.
+- `list_pending_solana_private_swaps` - list cached pending Houdini orders for the current OpenClaw session.
+
+This flow is intentionally optimized for `preview -> execute` rather than adding a no-op prepare step.
+
+### Kamino lending
+
+Kamino integration gives the wallet a structured Solana lending surface:
+
+- `get_kamino_lend_markets` - list Kamino lending markets available on Solana mainnet.
+- `get_kamino_lend_market_reserves` - inspect reserve metrics for one Kamino market.
+- `get_kamino_lend_user_obligations` - inspect the wallet's obligations inside a Kamino market.
+- `get_kamino_lend_user_rewards` - fetch the wallet's Kamino rewards summary.
+- `kamino_lend_deposit` - preview, prepare, or execute a lending deposit.
+- `kamino_lend_withdraw` - preview, prepare, or execute a lending withdrawal.
+- `kamino_lend_borrow` - preview, prepare, or execute a borrow.
+- `kamino_lend_repay` - preview, prepare, or execute a repay.
+
+### Flash Trade perps
+
+Flash Trade integration adds a managed perpetuals surface on Solana mainnet:
+
+- `get_flash_trade_markets` - list currently available Flash Trade markets.
+- `get_flash_trade_positions` - inspect the wallet's open Flash Trade positions.
+- `flash_trade_open_position` - preview, prepare, or execute a perp position open.
+- `flash_trade_close_position` - preview, prepare, or execute a perp position close.
+
+### Bags launch and fee-share
+
+Bags-backed tools cover token launch and post-launch fee analytics:
+
+- `get_bags_claimable_positions` - inspect claimable Bags fee-share positions for a Solana wallet.
+- `get_bags_fee_analytics` - fetch analytics and optional claim history for a launched token.
+- `claim_bags_fees` - preview, prepare, or execute a Bags fee-share claim.
+- `launch_bags_token` - preview, prepare, or execute a Bags token launch with fee-share configuration.
+
+### EVM DeFi integrations
+
+The EVM wallet surface includes named DeFi integrations on `ethereum` and `base`, without exposing arbitrary calldata execution.
+
+Velora swap routing:
+
+- `get_evm_swap_quote` - fetch a read-only EVM swap quote.
+- `swap_evm_tokens` - preview, prepare, or execute a routed EVM token swap.
+
+Aave V3:
+
+- `get_evm_aave_account` - inspect the wallet's Aave account state.
+- `get_evm_aave_reserves` - fetch reserve data for supported Aave markets.
+- `get_evm_aave_positions` - inspect the wallet's open Aave positions.
+- `manage_evm_aave_position` - preview, prepare, or execute Aave position changes through the managed wallet flow.
+
+Lido:
+
+- `get_evm_lido_overview` - fetch Lido protocol overview data relevant to the wallet surface.
+- `get_evm_lido_positions` - inspect the wallet's Lido positions.
+- `get_evm_lido_withdrawal_requests` - inspect outstanding Lido withdrawal requests.
+- `manage_evm_lido_position` - preview, prepare, or execute a Lido staking position change.
+- `manage_evm_lido_withdrawal` - preview, prepare, or execute a Lido withdrawal management action.
+
+Across these service-backed flows, read operations remain directly callable, while write operations stay behind preview, explicit intent, and host-issued approval tokens before execution.
+
 Solana:
 
 ```bash

package/agent-wallet/pyproject.toml

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

package/agent-wallet/scripts/flash-sdk-bridge/bridge.mjs

@@ -350,14 +350,22 @@ function variantToSide(sideVariant) {
   return String(sideVariant ?? "");
 }
 
+function safeTokenSymbol(poolConfig, mintPk) {
+  try {
+    return poolConfig.getTokenFromMintPk(mintPk)?.symbol ?? null;
+  } catch {
+    return null;
+  }
+}
+
 function buildMarketSnapshot(poolConfig, marketConfig, deprecated = false) {
-  const targetToken = poolConfig.getTokenFromMintPk(marketConfig.targetMint);
-  const collateralToken = poolConfig.getTokenFromMintPk(marketConfig.collateralMint);
+  const targetSymbol = safeTokenSymbol(poolConfig, marketConfig.targetMint);
+  const collateralSymbol = safeTokenSymbol(poolConfig, marketConfig.collateralMint);
   return {
     pool_name: poolConfig.poolName,
-    symbol: targetToken.symbol,
-    market_symbol: targetToken.symbol,
-    collateral_symbol: collateralToken.symbol,
+    symbol: targetSymbol,
+    market_symbol: targetSymbol,
+    collateral_symbol: collateralSymbol,
     side: variantToSide(marketConfig.side),
     market_id: marketConfig.marketId,
     market_address: marketConfig.marketAccount.toBase58(),
@@ -374,14 +382,16 @@ function buildMarketSnapshot(poolConfig, marketConfig, deprecated = false) {
 
 function buildPositionSnapshot(poolConfig, positionAccount) {
   const marketConfig = poolConfig.getMarketConfigByPk(positionAccount.market);
-  const targetToken = poolConfig.getTokenFromMintPk(marketConfig.targetMint);
-  const collateralToken = poolConfig.getTokenFromMintPk(marketConfig.collateralMint);
+  const targetSymbol = marketConfig ? safeTokenSymbol(poolConfig, marketConfig.targetMint) : null;
+  const collateralSymbol = marketConfig
+    ? safeTokenSymbol(poolConfig, marketConfig.collateralMint)
+    : null;
   return {
     pool_name: poolConfig.poolName,
-    symbol: targetToken.symbol,
-    market_symbol: targetToken.symbol,
-    collateral_symbol: collateralToken.symbol,
-    side: variantToSide(marketConfig.side),
+    symbol: targetSymbol,
+    market_symbol: targetSymbol,
+    collateral_symbol: collateralSymbol,
+    side: variantToSide(marketConfig?.side),
     is_active: Boolean(positionAccount.isActive),
     position_address: positionAccount.pubkey.toBase58(),
     market_address: positionAccount.market.toBase58(),

package/agent-wallet/scripts/install_agent_wallet.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import os
+import platform
 import shutil
 import subprocess
 import sys
@@ -114,6 +116,21 @@ def _resolve_sealed_keys_path() -> Path:
     return _resolve_openclaw_home() / "sealed_keys.json"
 
 
+def _runtime_base_for(runtime_root: Path) -> Path:
+    resolved = runtime_root.expanduser().resolve()
+    if resolved.parent.name == "releases":
+        return resolved.parent.parent
+    return resolved.parent
+
+
+def _shared_runtime_root(runtime_root: Path) -> Path:
+    return _runtime_base_for(runtime_root) / "shared"
+
+
+def _shared_dependency_links_supported() -> bool:
+    return os.name != "nt"
+
+
 def _atomic_write_text(path: Path, content: str, *, mode: int = 0o600) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, temp_path = tempfile.mkstemp(prefix=f".{path.name}.", dir=str(path.parent))
@@ -139,6 +156,21 @@ def _chmod_if_exists(path: Path, mode: int = 0o600) -> None:
         return
 
 
+def _sha256_text(parts: list[str]) -> str:
+    digest = hashlib.sha256()
+    for part in parts:
+        digest.update(part.encode("utf-8"))
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def _file_text_or_empty(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return ""
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--config-path", default=str(_default_config_path()))
@@ -272,6 +304,14 @@ def _sync_runtime_tree(source_root: Path, runtime_root: Path) -> dict[str, objec
 def _ensure_env_file(env_path: Path, env_example_path: Path) -> bool:
     if env_path.exists():
         return False
+    if not env_example_path.exists():
+        source_candidate = _package_root() / ".env.example"
+        if source_candidate.exists():
+            env_example_path = source_candidate
+        else:
+            raise SystemExit(
+                f"Missing env example template at '{env_example_path}'."
+            )
     env_path.parent.mkdir(parents=True, exist_ok=True)
     shutil.copyfile(env_example_path, env_path)
     _chmod_if_exists(env_path, 0o600)
@@ -366,8 +406,95 @@ def _ensure_python_wrapper(venv_path: Path) -> Path:
     return wrapper
 
 
-def _ensure_python_runtime(venv_path: Path, package_root: Path) -> tuple[Path, bool]:
+def _python_runtime_fingerprint(package_root: Path, python_bin: Path) -> str:
+    version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    return _sha256_text(
+        [
+            f"python-bin:{python_bin}",
+            f"python-version:{version}",
+            f"platform:{platform.system()}",
+            f"machine:{platform.machine()}",
+            _file_text_or_empty(package_root / "pyproject.toml"),
+        ]
+    )[:24]
+
+
+def _python_runtime_plan(
+    venv_path: Path,
+    package_root: Path,
+    runtime_root: Path,
+) -> dict[str, object]:
+    if _shared_dependency_links_supported():
+        fingerprint = _python_runtime_fingerprint(package_root, Path(sys.executable))
+        shared_root = _shared_runtime_root(runtime_root) / "python" / fingerprint
+        shared_venv_path = shared_root / "venv"
+        shared_wrapper = _venv_python_wrapper(shared_venv_path)
+        return {
+            "shared": True,
+            "fingerprint": fingerprint,
+            "shared_root": str(shared_root),
+            "venv_path": str(shared_venv_path),
+            "release_link_path": str(venv_path),
+            "python_bin": str(venv_path / shared_wrapper.relative_to(shared_venv_path)),
+            "action": "reuse" if shared_venv_path.exists() else "create",
+            "exists": shared_venv_path.exists(),
+        }
+    return {
+        "shared": False,
+        "fingerprint": None,
+        "shared_root": None,
+        "venv_path": str(venv_path),
+        "release_link_path": str(venv_path),
+        "python_bin": str(_venv_python_wrapper(venv_path)),
+        "action": "install",
+        "exists": _venv_python(venv_path).exists(),
+    }
+
+
+def _replace_with_directory_symlink(link_path: Path, target_path: Path) -> None:
+    target_resolved = target_path.resolve()
+    if link_path.is_symlink():
+        existing_target = link_path.resolve()
+        if existing_target == target_resolved:
+            return
+        link_path.unlink()
+    elif link_path.exists():
+        if link_path.is_dir():
+            shutil.rmtree(link_path)
+        else:
+            link_path.unlink()
+    link_path.parent.mkdir(parents=True, exist_ok=True)
+    link_path.symlink_to(target_resolved, target_is_directory=True)
+
+
+def _ensure_python_runtime(
+    venv_path: Path,
+    package_root: Path,
+    runtime_root: Path,
+) -> tuple[Path, bool, dict[str, object]]:
     created = False
+    plan = _python_runtime_plan(venv_path, package_root, runtime_root)
+    if bool(plan["shared"]):
+        shared_root = Path(str(plan["shared_root"]))
+        shared_venv_path = Path(str(plan["venv_path"]))
+        python_bin = _venv_python(shared_venv_path)
+        if not python_bin.exists():
+            venv.EnvBuilder(with_pip=True).create(shared_venv_path)
+            created = True
+            subprocess.run(
+                [str(python_bin), "-m", "pip", "install", "-e", str(package_root)],
+                check=True,
+            )
+        shared_wrapper = _ensure_python_wrapper(shared_venv_path)
+        _replace_with_directory_symlink(venv_path, shared_venv_path)
+        plan["action"] = "create" if created else "reuse"
+        plan["exists"] = True
+        return (
+            venv_path / shared_wrapper.relative_to(shared_venv_path),
+            created,
+            plan,
+        )
+
     python_bin = _venv_python(venv_path)
     if not python_bin.exists():
         venv.EnvBuilder(with_pip=True).create(venv_path)
@@ -377,10 +504,79 @@ def _ensure_python_runtime(venv_path: Path, package_root: Path) -> tuple[Path, b
         [str(python_bin), "-m", "pip", "install", "-e", str(package_root)],
         check=True,
     )
-    return _ensure_python_wrapper(venv_path), created
+    return (
+        _ensure_python_wrapper(venv_path),
+        created,
+        plan,
+    )
 
 
-def _ensure_node_runtime(npm_bin: str, project_root: Path) -> dict[str, object]:
+def _node_version() -> str:
+    result = subprocess.run(
+        ["node", "--version"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+def _node_runtime_fingerprint(project_root: Path) -> str:
+    return _sha256_text(
+        [
+            f"node-version:{_node_version()}",
+            f"platform:{platform.system()}",
+            f"machine:{platform.machine()}",
+            _file_text_or_empty(project_root / "package.json"),
+            _file_text_or_empty(project_root / "package-lock.json"),
+        ]
+    )[:24]
+
+
+def _node_runtime_plan(project_root: Path, runtime_root: Path) -> dict[str, object]:
+    package_json = project_root / "package.json"
+    package_lock = project_root / "package-lock.json"
+    command = ["npm", "ci"] if package_lock.exists() else ["npm", "install"]
+    if _shared_dependency_links_supported():
+        fingerprint = _node_runtime_fingerprint(project_root)
+        shared_project_root = _shared_runtime_root(runtime_root) / "node" / project_root.name / fingerprint
+        shared_node_modules = shared_project_root / "node_modules"
+        return {
+            "project_root": str(project_root),
+            "package_json": str(package_json),
+            "package_lock": str(package_lock) if package_lock.exists() else None,
+            "command": command,
+            "shared": True,
+            "fingerprint": fingerprint,
+            "shared_root": str(shared_project_root),
+            "node_modules_path": str(shared_node_modules),
+            "release_link_path": str(project_root / "node_modules"),
+            "action": "reuse" if shared_node_modules.exists() else "create",
+            "exists": shared_node_modules.exists(),
+        }
+    return {
+        "project_root": str(project_root),
+        "package_json": str(package_json),
+        "package_lock": str(package_lock) if package_lock.exists() else None,
+        "command": command,
+        "shared": False,
+        "fingerprint": None,
+        "shared_root": None,
+        "node_modules_path": str(project_root / "node_modules"),
+        "release_link_path": str(project_root / "node_modules"),
+        "action": "install",
+        "exists": (project_root / "node_modules").exists(),
+    }
+
+
+def _copy_if_exists(source: Path, target: Path) -> None:
+    if not source.exists():
+        return
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+
+
+def _ensure_node_runtime(npm_bin: str, project_root: Path, runtime_root: Path) -> dict[str, object]:
     package_json = project_root / "package.json"
     if not package_json.exists():
         raise SystemExit(f"Missing package.json for Node runtime at '{project_root}'.")
@@ -394,14 +590,30 @@ def _ensure_node_runtime(npm_bin: str, project_root: Path) -> dict[str, object]:
     env["NPM_CONFIG_CACHE"] = cache_dir
     env["npm_config_cache"] = cache_dir
     Path(cache_dir).expanduser().mkdir(parents=True, exist_ok=True)
+    plan = _node_runtime_plan(project_root, runtime_root)
+    if bool(plan["shared"]):
+        shared_project_root = Path(str(plan["shared_root"]))
+        shared_node_modules = Path(str(plan["node_modules_path"]))
+        created = False
+        if not shared_node_modules.exists():
+            shared_project_root.mkdir(parents=True, exist_ok=True)
+            _copy_if_exists(package_json, shared_project_root / "package.json")
+            _copy_if_exists(package_lock, shared_project_root / "package-lock.json")
+            _copy_if_exists(project_root / ".npmrc", shared_project_root / ".npmrc")
+            subprocess.run(command, cwd=shared_project_root, check=True, env=env)
+            created = True
+        _replace_with_directory_symlink(project_root / "node_modules", shared_node_modules)
+        plan["cache_dir"] = cache_dir
+        plan["created"] = created
+        plan["action"] = "create" if created else "reuse"
+        plan["exists"] = True
+        return plan
+
     subprocess.run(command, cwd=project_root, check=True, env=env)
-    return {
-        "project_root": str(project_root),
-        "package_json": str(package_json),
-        "package_lock": str(package_lock) if package_lock.exists() else None,
-        "command": command,
-        "cache_dir": cache_dir,
-    }
+    plan["cache_dir"] = cache_dir
+    plan["created"] = True
+    plan["exists"] = True
+    return plan
 
 
 def _pending_env_names() -> list[str]:
@@ -526,13 +738,28 @@ def main() -> None:
     python_bin = Path(sys.executable)
     venv_created = False
     existing_wrapper = _venv_python_wrapper(venv_path)
+    python_runtime: dict[str, object] = {
+        "shared": False,
+        "fingerprint": None,
+        "shared_root": None,
+        "venv_path": str(venv_path),
+        "release_link_path": str(venv_path),
+        "python_bin": str(_venv_python_wrapper(venv_path)),
+        "action": "skipped",
+        "exists": existing_wrapper.exists(),
+    }
     if args.skip_python_setup and args.install_from_runtime and existing_wrapper.exists():
         python_bin = existing_wrapper
     elif not args.skip_python_setup:
         if not args.dry_run:
-            python_bin, venv_created = _ensure_python_runtime(venv_path, package_root)
+            python_bin, venv_created, python_runtime = _ensure_python_runtime(
+                venv_path,
+                package_root,
+                runtime_root,
+            )
         else:
-            python_bin = _venv_python_wrapper(venv_path)
+            python_runtime = _python_runtime_plan(venv_path, package_root, runtime_root)
+            python_bin = Path(str(python_runtime["python_bin"]))
 
     node_runtime = {
         "skipped": bool(args.skip_node_setup),
@@ -548,17 +775,22 @@ def main() -> None:
         if args.dry_run:
             node_runtime["projects"] = [
                 {
-                    "project_root": str(project_root),
+                    **_node_runtime_plan(project_root, runtime_root),
                     "command": [
                         args.npm_bin,
                         "ci" if (project_root / "package-lock.json").exists() else "install",
                     ],
+                    "cache_dir": (
+                        os.environ.get("OPENCLAW_AGENT_WALLET_NPM_CACHE")
+                        or str(_resolve_openclaw_home() / "npm-cache")
+                    ),
+                    "created": False,
                 }
                 for project_root in node_projects
             ]
         else:
             node_runtime["projects"] = [
-                _ensure_node_runtime(args.npm_bin, project_root)
+                _ensure_node_runtime(args.npm_bin, project_root, runtime_root)
                 for project_root in node_projects
             ]
 
@@ -600,6 +832,7 @@ def main() -> None:
                 "install_from_runtime": bool(args.install_from_runtime),
                 "python_bin": str(python_bin),
                 "venv_created": venv_created,
+                "python_runtime": python_runtime,
                 "node_runtime": node_runtime,
                 "runtime_sync": runtime_sync,
                 "configured": configured,

package/bin/openclaw-agent-wallet.mjs

@@ -13,6 +13,8 @@ const setupPath = path.join(packageRoot, "setup.sh");
 const packageJsonPath = path.join(packageRoot, "package.json");
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
 const packageVersion = packageJson.version;
+const UPDATE_CLI_PATH_ENV = "OPENCLAW_AGENT_WALLET_UPDATE_CLI_PATH";
+const UPDATE_PACKAGE_SPEC_ENV = "OPENCLAW_AGENT_WALLET_UPDATE_PACKAGE_SPEC";
 
 function printHelp() {
   console.log(`openclaw-agent-wallet
@@ -37,6 +39,7 @@ Examples:
   npx @agentlayer.tech/wallet hermes install --yes
   npx @agentlayer.tech/wallet install --backend none
   npx @agentlayer.tech/wallet update --yes
+  npx @agentlayer.tech/wallet update --yes --dry-run
   npx @agentlayer.tech/wallet status
 
 The installer writes a versioned runtime under:
@@ -46,7 +49,23 @@ After a successful install it switches:
   ~/.openclaw/agent-wallet-runtime/current
 
 Wallet files and sealed secrets remain under OPENCLAW_HOME and are not replaced
-by updates.`);
+by updates. The update command fetches the latest published npm package and
+reuses shared dependency snapshots when possible.`);
+}
+
+function primaryBinCommand(pkg = packageJson) {
+  const bin = pkg?.bin;
+  if (!bin) return "wallet";
+  if (typeof bin === "string") {
+    const packageName = String(pkg?.name || "").trim();
+    if (packageName) {
+      const parts = packageName.split("/");
+      return parts[parts.length - 1] || "wallet";
+    }
+    return "wallet";
+  }
+  const names = Object.keys(bin);
+  return names[0] || "wallet";
 }
 
 function expandHome(value) {
@@ -207,6 +226,80 @@ function activeVersion(env = process.env) {
   return path.basename(path.resolve(path.dirname(current), link));
 }
 
+function listDirectories(rootPath) {
+  try {
+    return fs
+      .readdirSync(rootPath, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+function activePythonRuntimeInfo(env = process.env) {
+  const currentRoot = resolvedCurrentRuntimeRoot(env);
+  if (!currentRoot) return null;
+  const linkPath = path.join(currentRoot, "agent-wallet", ".runtime-venv");
+  const exists = fs.existsSync(linkPath);
+  const symlinkTarget = readLinkOrNull(linkPath);
+  const resolvedTarget = exists ? path.resolve(path.dirname(linkPath), symlinkTarget || ".") : null;
+  return {
+    link_path: linkPath,
+    exists,
+    symlink: Boolean(symlinkTarget),
+    target: symlinkTarget || null,
+    resolved_target: resolvedTarget,
+    shared: Boolean(resolvedTarget && resolvedTarget.includes(`${path.sep}shared${path.sep}python${path.sep}`)),
+  };
+}
+
+function activeNodeRuntimeInfo(env = process.env) {
+  const currentRoot = resolvedCurrentRuntimeRoot(env);
+  if (!currentRoot) return [];
+  const projects = [
+    path.join(currentRoot, "wdk-btc-wallet"),
+    path.join(currentRoot, "wdk-evm-wallet"),
+    path.join(currentRoot, "agent-wallet", "scripts", "flash-sdk-bridge"),
+  ];
+  return projects
+    .filter((projectRoot) => fs.existsSync(path.join(projectRoot, "package.json")))
+    .map((projectRoot) => {
+      const linkPath = path.join(projectRoot, "node_modules");
+      const exists = fs.existsSync(linkPath);
+      const symlinkTarget = readLinkOrNull(linkPath);
+      const resolvedTarget = exists ? path.resolve(path.dirname(linkPath), symlinkTarget || ".") : null;
+      return {
+        project_root: projectRoot,
+        project_name: path.basename(projectRoot),
+        link_path: linkPath,
+        exists,
+        symlink: Boolean(symlinkTarget),
+        target: symlinkTarget || null,
+        resolved_target: resolvedTarget,
+        shared: Boolean(resolvedTarget && resolvedTarget.includes(`${path.sep}shared${path.sep}node${path.sep}`)),
+      };
+    });
+}
+
+function sharedSnapshotInventory(env = process.env) {
+  const runtimeBase = resolveRuntimeBase(env);
+  const sharedRoot = path.join(runtimeBase, "shared");
+  const pythonRoot = path.join(sharedRoot, "python");
+  const nodeRoot = path.join(sharedRoot, "node");
+  const nodeProjects = listDirectories(nodeRoot).map((projectName) => ({
+    project_name: projectName,
+    snapshots: listDirectories(path.join(nodeRoot, projectName)),
+  }));
+  return {
+    shared_root: sharedRoot,
+    python_snapshots: listDirectories(pythonRoot),
+    node_projects: nodeProjects,
+  };
+}
+
 function switchSymlink(linkPath, targetPath) {
   const absoluteTarget = path.resolve(targetPath);
   if (!fs.existsSync(absoluteTarget)) {
@@ -216,7 +309,7 @@ function switchSymlink(linkPath, targetPath) {
   fs.mkdirSync(path.dirname(linkPath), { recursive: true });
   const tempLink = `${linkPath}.tmp-${process.pid}`;
   try {
-    fs.rmSync(tempLink, { force: true, recursive: false });
+    fs.rmSync(tempLink, { force: true, recursive: true });
   } catch {
     // ignored
   }
@@ -225,7 +318,7 @@ function switchSymlink(linkPath, targetPath) {
   try {
     const existing = fs.lstatSync(linkPath);
     if (!existing.isSymbolicLink()) {
-      fs.rmSync(tempLink, { force: true });
+      fs.rmSync(tempLink, { force: true, recursive: true });
       throw new Error(`${linkPath} exists and is not a symlink. Refusing to replace it.`);
     }
   } catch (error) {
@@ -268,6 +361,60 @@ function withoutCliOnlyArgs(args) {
   return output;
 }
 
+function extractTrailingJson(text) {
+  const raw = String(text || "");
+  const newlineStart = raw.lastIndexOf("\n{");
+  const start = newlineStart >= 0 ? newlineStart + 1 : raw.indexOf("{");
+  if (start < 0) {
+    throw new Error("Could not find JSON payload in command output.");
+  }
+  return JSON.parse(raw.slice(start));
+}
+
+function pathVersionFromRuntimeRoot(runtimeRoot) {
+  if (!runtimeRoot) return null;
+  const normalized = path.resolve(String(runtimeRoot));
+  if (path.basename(path.dirname(normalized)) !== "releases") return null;
+  return path.basename(normalized);
+}
+
+function resolveCliPackageMeta(cliPath) {
+  try {
+    const root = path.resolve(path.dirname(cliPath), "..");
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    return {
+      name: String(pkg.name || packageJson.name),
+      version: String(pkg.version || ""),
+      root,
+    };
+  } catch {
+    return {
+      name: packageJson.name,
+      version: "",
+      root: "",
+    };
+  }
+}
+
+function summarizeDependencyPlan(payload) {
+  const python = payload?.python_runtime && typeof payload.python_runtime === "object"
+    ? {
+        action: payload.python_runtime.action || "unknown",
+        shared: Boolean(payload.python_runtime.shared),
+        fingerprint: payload.python_runtime.fingerprint || null,
+      }
+    : null;
+  const nodeProjects = Array.isArray(payload?.node_runtime?.projects)
+    ? payload.node_runtime.projects.map((project) => ({
+        project_root: project.project_root,
+        action: project.action || "unknown",
+        shared: Boolean(project.shared),
+        fingerprint: project.fingerprint || null,
+      }))
+    : [];
+  return { python, node_projects: nodeProjects };
+}
+
 function token() {
   return crypto.randomBytes(32).toString("base64url");
 }
@@ -442,24 +589,25 @@ function runDoctor() {
   return missing.length === 0 ? 0 : 1;
 }
 
-function runStatus() {
-  console.log(
-    JSON.stringify(
-      {
-        ok: true,
-        package_name: packageJson.name,
-        package_version: packageVersion,
-        openclaw_home: resolveOpenclawHome(),
-        runtime_base: resolveRuntimeBase(),
-        current_runtime: currentRuntimePath(),
-        previous_runtime: readLinkOrNull(previousRuntimePath()),
-        active_version: activeVersion(),
-        available_releases: listReleases(),
-      },
-      null,
-      2,
-    ),
-  );
+function runStatus(args = []) {
+  const payload = {
+    ok: true,
+    package_name: packageJson.name,
+    package_version: packageVersion,
+    openclaw_home: resolveOpenclawHome(),
+    runtime_base: resolveRuntimeBase(),
+    current_runtime: currentRuntimePath(),
+    previous_runtime: readLinkOrNull(previousRuntimePath()),
+    active_version: activeVersion(),
+    available_releases: listReleases(),
+  };
+  if (hasFlag(args, "--verbose")) {
+    payload.verbose = true;
+    payload.active_python_runtime = activePythonRuntimeInfo();
+    payload.active_node_runtimes = activeNodeRuntimeInfo();
+    payload.shared_snapshot_inventory = sharedSnapshotInventory();
+  }
+  console.log(JSON.stringify(payload, null, 2));
   return 0;
 }
 
@@ -467,14 +615,19 @@ function buildInstallerEnv(args) {
   const env = { ...process.env };
   const sealedKeysPath = path.join(resolveOpenclawHome(env), "sealed_keys.json");
   const sealedKeysExist = fs.existsSync(sealedKeysPath);
+  const dryRun = hasFlag(args, "--dry-run");
   if (!env.AGENT_WALLET_BOOT_KEY) {
-    const existingBootKey = resolveBootKeyFromFile(env) || currentBootKey(env);
+    const existingBootKey =
+      resolveBootKeyFromFile(env) ||
+      readTextIfExists(defaultBootKeyFile(env)).trim() ||
+      currentBootKey(env);
     if (existingBootKey) {
       env.AGENT_WALLET_BOOT_KEY = existingBootKey;
     }
   }
 
   const shouldGenerateSecrets =
+    !dryRun &&
     !hasFlag(args, "--no-auto-secrets") &&
     (hasFlag(args, "--yes") || !env.AGENT_WALLET_BOOT_KEY);
 
@@ -554,6 +707,14 @@ function runInstall(args, { commandName = "install" } = {}) {
     });
   }
 
+  const pythonInfo = activePythonRuntimeInfo(env);
+  const nodeInfo = activeNodeRuntimeInfo(env)
+    .map((item) => `${item.project_name}:${item.shared ? "shared" : item.exists ? "local" : "missing"}`)
+    .join(", ");
+  console.error(
+    `Update summary: version=${packageVersion} active=${activeVersion(env) || packageVersion} python=${pythonInfo?.shared ? "shared" : pythonInfo?.exists ? "local" : "missing"} node=[${nodeInfo}]`,
+  );
+
   console.error(
     JSON.stringify(
       {
@@ -572,6 +733,119 @@ function runInstall(args, { commandName = "install" } = {}) {
   return 0;
 }
 
+function resolveUpdatePackageSpec(env = process.env) {
+  const explicit = String(env[UPDATE_PACKAGE_SPEC_ENV] || "").trim();
+  if (explicit) return explicit;
+  return `${packageJson.name}@latest`;
+}
+
+function runDelegatedInstallForUpdate(args, { captureOutput = false } = {}) {
+  const localCliPath = String(process.env[UPDATE_CLI_PATH_ENV] || "").trim();
+  if (localCliPath) {
+    const meta = resolveCliPackageMeta(localCliPath);
+    const result = spawnSync("node", [localCliPath, "install", ...args], {
+      cwd: packageRoot,
+      stdio: captureOutput ? "pipe" : "inherit",
+      encoding: captureOutput ? "utf8" : undefined,
+      env: process.env,
+    });
+    return {
+      result,
+      delegated_via: "cli_path",
+      target_package_spec: meta.name || packageJson.name,
+      target_version_hint: meta.version || null,
+    };
+  }
+
+  const npmBin = commandPath("npm");
+  if (!npmBin) {
+    throw new Error("npm is required for `wallet update`. Install npm or run `npx @agentlayer.tech/wallet install --yes`.");
+  }
+
+  const packageSpec = resolveUpdatePackageSpec();
+  const binCommand = primaryBinCommand();
+  const result = spawnSync(
+    npmBin,
+    ["exec", "--yes", `--package=${packageSpec}`, binCommand, "--", "install", ...args],
+    {
+      cwd: packageRoot,
+      stdio: captureOutput ? "pipe" : "inherit",
+      encoding: captureOutput ? "utf8" : undefined,
+      env: process.env,
+    },
+  );
+  return {
+    result,
+    delegated_via: "npm_exec",
+    target_package_spec: packageSpec,
+    target_version_hint: null,
+  };
+}
+
+function runUpdate(args) {
+  const dryRun = hasFlag(args, "--dry-run");
+  if (dryRun) {
+    try {
+      const delegated = runDelegatedInstallForUpdate(args, { captureOutput: true });
+      const { result } = delegated;
+      if (result.error) {
+        console.error(result.error.message);
+        return 1;
+      }
+      if ((result.status ?? 1) !== 0) {
+        const stderr = String(result.stderr || "").trim();
+        const stdout = String(result.stdout || "").trim();
+        if (stderr) process.stderr.write(`${stderr}\n`);
+        if (stdout) process.stdout.write(`${stdout}\n`);
+        return result.status ?? 1;
+      }
+      const payload = extractTrailingJson(result.stdout || "");
+      const targetVersion =
+        delegated.target_version_hint ||
+        pathVersionFromRuntimeRoot(payload.runtime_root) ||
+        null;
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            command: "update",
+            dry_run: true,
+            current_version: activeVersion(),
+            installed_cli_version: packageVersion,
+            target_package_spec: delegated.target_package_spec,
+            target_version: targetVersion,
+            delegated_via: delegated.delegated_via,
+            runtime_base: resolveRuntimeBase(),
+            current_runtime: currentRuntimePath(),
+            target_runtime_root: payload.runtime_root,
+            dependency_plan: summarizeDependencyPlan(payload),
+            install_plan: payload,
+          },
+          null,
+          2,
+        ),
+      );
+      return 0;
+    } catch (error) {
+      console.error(error.message);
+      return 1;
+    }
+  }
+
+  let delegated;
+  try {
+    delegated = runDelegatedInstallForUpdate(args, { captureOutput: false });
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+  if (delegated.result.error) {
+    console.error(delegated.result.error.message);
+    return 1;
+  }
+  return delegated.result.status ?? 1;
+}
+
 function runRollback(args) {
   const requested = parseFlagValue(args, "--to");
   const current = activeVersion();
@@ -755,7 +1029,7 @@ if (command === "doctor") {
 }
 
 if (command === "status") {
-  process.exit(runStatus());
+  process.exit(runStatus(args.slice(1)));
 }
 
 if (command === "install" || command === "setup") {
@@ -763,7 +1037,7 @@ if (command === "install" || command === "setup") {
 }
 
 if (command === "update") {
-  process.exit(runInstall(args.slice(1), { commandName: "update" }));
+  process.exit(runUpdate(args.slice(1)));
 }
 
 if (command === "rollback") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayer.tech/wallet",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "NPM installer for the OpenClaw Agent Wallet local runtime.",
   "type": "module",
   "repository": {