@agentlayer.tech/wallet 0.1.53 → 0.1.58

package/codex/plugins/agent-wallet/server.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
+import atexit
 import asyncio
 import copy
 import base64
 import hashlib
 import json
 import os
+import selectors
+import signal
 import subprocess
 import sys
 import threading
@@ -75,15 +78,21 @@ APPROVAL_CONTEXT_MISSING_MESSAGE = (
     "operation again, wait for explicit user confirmation, then retry execute. Do not ask the "
     "user for a manual approval token."
 )
+RESIDENT_READ_ONLY_TOOLS = {
+    "get_wallet_balance",
+    "get_wallet_portfolio",
+}
 
 selected_wallet_backend: str | None = None
 selected_solana_network: str | None = None
 selected_evm_network: str | None = None
 selected_btc_network: str | None = None
 approval_preview_cache: dict[str, dict[str, Any]] = {}
+resident_read_workers: dict[str, "_ResidentReadWorker"] = {}
 # Guards approval_preview_cache against races once wallet calls run concurrently
 # via asyncio.to_thread. Reentrant so prune helpers can be nested under writers.
 _approval_cache_lock = threading.RLock()
+_resident_worker_lock = threading.RLock()
 
 
 class WalletCliError(RuntimeError):
@@ -93,6 +102,10 @@ class WalletCliError(RuntimeError):
         self.details = details or {}
 
 
+class ResidentReadWorkerTransportError(RuntimeError):
+    """Raised when the long-lived read worker transport fails."""
+
+
 def _plugin_root() -> Path:
     return Path(__file__).resolve().parent
 
@@ -361,6 +374,15 @@ def _normalize_selectable_evm_network(value: Any) -> str:
     return network
 
 
+def _implied_evm_network_from_backend_alias(value: Any) -> str | None:
+    normalized = str(value or "").strip().lower()
+    if normalized in {"base", "base-mainnet"}:
+        return "base"
+    if normalized in {"ethereum", "eth", "mainnet", "eth-mainnet"}:
+        return "ethereum"
+    return None
+
+
 def _normalize_solana_network(value: Any) -> str | None:
     network = str(value or "").strip().lower()
     if not network:
@@ -492,12 +514,17 @@ def _reject_secret_config_json(config: dict[str, Any]) -> None:
 
 
 def _base_config(args: dict[str, Any], *, tool_name: str = "") -> dict[str, Any]:
+    requested_backend = args.get("backend")
     backend = (
-        _normalize_wallet_backend(args.get("backend"))
-        if args.get("backend") is not None
+        _normalize_wallet_backend(requested_backend)
+        if requested_backend is not None
         else _active_backend_for_tool(tool_name)
     )
     config = _effective_config_for_backend(backend)
+    if backend == "wdk_evm_local":
+        implied_evm_network = _implied_evm_network_from_backend_alias(requested_backend)
+        if implied_evm_network and args.get("network") is None:
+            config["network"] = implied_evm_network
     if "config" in args:
         extra = args.get("config")
         if not isinstance(extra, dict):
@@ -611,6 +638,311 @@ def _invoke_tool(tool_name: str, arguments: dict[str, Any], config: dict[str, An
     )
 
 
+class _ResidentReadWorker:
+    def __init__(self, *, user_id: str, config: dict[str, Any]):
+        self.user_id = user_id
+        self.config = copy.deepcopy(config)
+        self.package_root = _resolve_package_root()
+        self._process: subprocess.Popen[str] | None = None
+        self._lock = threading.RLock()
+        self._request_id = 0
+        self._stderr_lines: list[str] = []
+        self._stderr_thread: threading.Thread | None = None
+        self._last_used = time.monotonic()
+
+    def touch(self) -> None:
+        self._last_used = time.monotonic()
+
+    def idle_seconds(self) -> float:
+        return time.monotonic() - self._last_used
+
+    def _command(self) -> list[str]:
+        return [
+            _python_bin(self.package_root),
+            "-m",
+            "agent_wallet.openclaw_cli",
+            "read-worker",
+            "--user-id",
+            self.user_id,
+            "--config-json",
+            json.dumps(self.config),
+        ]
+
+    def _drain_stderr(self) -> None:
+        process = self._process
+        if process is None or process.stderr is None:
+            return
+        try:
+            for raw_line in process.stderr:
+                line = raw_line.strip()
+                if not line:
+                    continue
+                with self._lock:
+                    self._stderr_lines.append(line)
+                    if len(self._stderr_lines) > 20:
+                        self._stderr_lines = self._stderr_lines[-20:]
+        except Exception:
+            return
+
+    def _stderr_summary(self) -> str:
+        with self._lock:
+            if not self._stderr_lines:
+                return ""
+            return " | ".join(self._stderr_lines[-5:])
+
+    def _ensure_started(self) -> subprocess.Popen[str]:
+        with self._lock:
+            process = self._process
+            if process is not None and process.poll() is None:
+                return process
+            try:
+                process = subprocess.Popen(
+                    self._command(),
+                    cwd=str(self.package_root),
+                    env=_cli_env(self.package_root),
+                    text=True,
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    bufsize=1,
+                )
+            except Exception as exc:
+                raise ResidentReadWorkerTransportError(
+                    f"Could not start resident read worker: {exc}"
+                ) from exc
+            self._process = process
+            self._stderr_lines = []
+            self._stderr_thread = threading.Thread(
+                target=self._drain_stderr,
+                name="agent-wallet-read-worker-stderr",
+                daemon=True,
+            )
+            self._stderr_thread.start()
+            return process
+
+    def warm(self) -> None:
+        """Spawn the worker eagerly, without waiting for a request/response.
+
+        Lets the interpreter boot, module imports, and read-only onboarding
+        happen off the critical path of the first real read-only tool call.
+        """
+        try:
+            self._ensure_started()
+        except ResidentReadWorkerTransportError:
+            pass
+
+    def close(self) -> None:
+        with self._lock:
+            process = self._process
+            self._process = None
+        if process is None:
+            return
+        try:
+            if process.poll() is None and process.stdin is not None:
+                process.stdin.write(json.dumps({"op": "shutdown"}) + "\n")
+                process.stdin.flush()
+        except Exception:
+            pass
+        try:
+            process.wait(timeout=1)
+        except Exception:
+            try:
+                process.terminate()
+                process.wait(timeout=1)
+            except Exception:
+                try:
+                    process.kill()
+                except Exception:
+                    pass
+
+    def invoke(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            self.touch()
+            process = self._ensure_started()
+            if process.stdin is None or process.stdout is None:
+                self.close()
+                raise ResidentReadWorkerTransportError("Resident read worker stdio is unavailable.")
+            self._request_id += 1
+            request_id = str(self._request_id)
+            request = {
+                "id": request_id,
+                "tool": tool_name,
+                "arguments": arguments,
+            }
+            try:
+                process.stdin.write(json.dumps(request) + "\n")
+                process.stdin.flush()
+            except Exception as exc:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    f"Could not write to resident read worker: {exc}"
+                ) from exc
+
+            selector = selectors.DefaultSelector()
+            selector.register(process.stdout, selectors.EVENT_READ)
+            events = selector.select(timeout=_cli_timeout_seconds())
+            selector.close()
+            if not events:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    f"Resident read worker timed out after {_cli_timeout_seconds():g}s."
+                )
+            response_line = process.stdout.readline()
+            if not response_line:
+                self.close()
+                stderr_summary = self._stderr_summary()
+                detail = f" Worker stderr: {stderr_summary}" if stderr_summary else ""
+                raise ResidentReadWorkerTransportError(
+                    "Resident read worker exited without a response." + detail
+                )
+            try:
+                response = json.loads(response_line)
+            except json.JSONDecodeError as exc:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    f"Resident read worker returned invalid JSON: {exc}"
+                ) from exc
+            if str(response.get("id") or "") != request_id:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    "Resident read worker response id did not match the request."
+                )
+            if response.get("ok") is False:
+                raise WalletCliError(
+                    str(response.get("error") or "resident read worker failed."),
+                    code=str(response.get("code") or ""),
+                    details=response.get("details")
+                    if isinstance(response.get("details"), dict)
+                    else {},
+                )
+            payload = response.get("payload")
+            if not isinstance(payload, dict):
+                raise ResidentReadWorkerTransportError(
+                    "Resident read worker returned a non-object payload."
+                )
+            return payload
+
+
+def _resident_worker_cache_key(user_id: str, config: dict[str, Any]) -> str:
+    return _canonical_json_text(
+        {
+            "user_id": user_id,
+            "config": config,
+        }
+    )
+
+
+def _resident_worker_idle_seconds() -> float:
+    """Idle threshold (seconds) after which an unused resident worker for a
+    config that is no longer the active one gets reaped. Falls back to 10
+    minutes on bad values."""
+    raw = os.getenv("AGENT_WALLET_READ_WORKER_IDLE_SECONDS", "600")
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return 600.0
+    return value if value > 0 else 600.0
+
+
+def _evict_idle_resident_read_workers(*, keep_key: str) -> None:
+    """Close resident workers other than `keep_key` that have been idle past
+    the configured threshold.
+
+    Each distinct (user_id, config) pair (e.g. switching Solana network or
+    wallet backend mid-session) keeps its own resident subprocess alive
+    indefinitely otherwise, since nothing previously evicted them. This
+    bounds that growth without adding a background timer thread: eviction
+    piggybacks on the next lookup instead.
+    """
+    idle_limit = _resident_worker_idle_seconds()
+    with _resident_worker_lock:
+        stale_keys = [
+            key
+            for key, worker in resident_read_workers.items()
+            if key != keep_key and worker.idle_seconds() > idle_limit
+        ]
+        stale_workers = [resident_read_workers.pop(key) for key in stale_keys]
+    for worker in stale_workers:
+        worker.close()
+
+
+def _resident_read_worker_for_config(user_id: str, config: dict[str, Any]) -> _ResidentReadWorker:
+    key = _resident_worker_cache_key(user_id, config)
+    _evict_idle_resident_read_workers(keep_key=key)
+    with _resident_worker_lock:
+        worker = resident_read_workers.get(key)
+        if worker is None:
+            worker = _ResidentReadWorker(user_id=user_id, config=config)
+            resident_read_workers[key] = worker
+        return worker
+
+
+def _shutdown_resident_read_workers() -> None:
+    with _resident_worker_lock:
+        workers = list(resident_read_workers.values())
+        resident_read_workers.clear()
+    for worker in workers:
+        worker.close()
+
+
+atexit.register(_shutdown_resident_read_workers)
+
+
+def _handle_termination_signal(signum: int, frame: Any) -> None:
+    """Close resident read worker subprocesses on SIGTERM, then terminate
+    normally.
+
+    atexit handlers only run on normal interpreter shutdown; Python's
+    default SIGTERM disposition terminates the process immediately without
+    unwinding to atexit. Hosts that gracefully stop this MCP server (e.g.
+    closing a Claude Code / Codex session) send SIGTERM, so without this the
+    resident worker subprocesses leaked past every normal shutdown, not just
+    an abrupt kill -9. (SIGINT is not handled here: Python's default handler
+    raises KeyboardInterrupt, which unwinds to a normal interpreter
+    shutdown and already triggers the atexit hook above.)
+    """
+    _shutdown_resident_read_workers()
+    signal.signal(signum, signal.SIG_DFL)
+    os.kill(os.getpid(), signum)
+
+
+def _install_termination_signal_handlers() -> None:
+    try:
+        signal.signal(signal.SIGTERM, _handle_termination_signal)
+    except (ValueError, OSError):
+        # e.g. signal.signal() called outside the main thread.
+        pass
+
+
+def _prewarm_resident_read_worker() -> None:
+    """Best-effort background warm-up of the default resident read worker.
+
+    server.py is a persistent stdio MCP process kept alive for the whole
+    host session, but the resident worker itself only used to spawn lazily
+    on the first read-only tool call (get_wallet_balance /
+    get_wallet_portfolio, e.g. /wallet-sol), putting interpreter boot +
+    onboarding on the critical path of that first call. Kick it off in a
+    daemon thread instead so it overlaps with the user issuing the command.
+    Failures here are silently ignored: the lazy path in
+    _invoke_read_tool_blocking remains the source of truth and will retry.
+    """
+    if os.getenv("AGENT_WALLET_PREWARM_READ_WORKER", "1").strip().lower() in {"0", "false", "no"}:
+        return
+
+    def _run() -> None:
+        try:
+            config = _base_config({}, tool_name="get_wallet_portfolio")
+            _resident_read_worker_for_config(_user_id(), config).warm()
+        except Exception:
+            pass
+
+    threading.Thread(
+        target=_run,
+        name="agent-wallet-read-worker-prewarm",
+        daemon=True,
+    ).start()
+
+
 def _issue_approval_token(
     tool_name: str,
     config: dict[str, Any],
@@ -640,6 +972,15 @@ def _issue_approval_token(
     return token
 
 
+def _invoke_resident_read_tool(tool_name: str, arguments: dict[str, Any], config: dict[str, Any]) -> dict[str, Any]:
+    worker = _resident_read_worker_for_config(_user_id(), config)
+    try:
+        return worker.invoke(tool_name, arguments)
+    except ResidentReadWorkerTransportError:
+        worker.close()
+        raise
+
+
 def _is_solana_swap_intent_execute(params: dict[str, Any]) -> bool:
     return str(params.get("mode") or "") == "intent_execute"
 
@@ -807,6 +1148,33 @@ def _sanitize_schema(schema: dict[str, Any]) -> dict[str, Any]:
 
 def _manual_tool_definitions() -> list[dict[str, Any]]:
     return [
+        {
+            "name": "get_wallet_overview",
+            "description": (
+                "Get a one-off wallet overview for a requested backend/network without changing the "
+                "active Codex wallet session. Returns the same enriched balance payload used by "
+                "get_wallet_balance."
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "backend": {
+                        "type": "string",
+                        "description": "solana, evm, base, ethereum, btc, or bitcoin.",
+                    },
+                    "network": {
+                        "type": "string",
+                        "description": "Optional network override. Use base or ethereum for EVM.",
+                    },
+                    "address": {
+                        "type": "string",
+                        "description": "Optional wallet address override.",
+                    },
+                },
+                "additionalProperties": False,
+            },
+            "read_only": True,
+        },
         {
             "name": "get_active_wallet_backend",
             "description": (
@@ -909,7 +1277,13 @@ async def _handle_set_wallet_backend(params: dict[str, Any]) -> dict[str, Any]:
     # globals after the validating wallet call succeeds, so a failed switch never
     # leaves a stale backend paired with a freshly mutated network selection.
     if backend == "wdk_evm_local":
-        implied = params.get("network") or selected_evm_network or _default_evm_network() or "ethereum"
+        implied = (
+            params.get("network")
+            or _implied_evm_network_from_backend_alias(requested)
+            or selected_evm_network
+            or _default_evm_network()
+            or "ethereum"
+        )
         resolved_network = _normalize_selectable_evm_network(implied)
     elif backend == "wdk_btc_local":
         resolved_network = _normalize_btc_network(
@@ -978,6 +1352,31 @@ async def _handle_set_evm_network(params: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+async def _handle_get_wallet_overview(params: dict[str, Any]) -> dict[str, Any]:
+    config = _base_config(params, tool_name="get_wallet_balance")
+    backend = _normalize_wallet_backend(config.get("backend"))
+
+    effective_params: dict[str, Any] = {}
+    if params.get("address") is not None:
+        effective_params["address"] = params.get("address")
+
+    payload = await asyncio.to_thread(
+        _invoke_read_tool_blocking, "get_wallet_balance", effective_params, config
+    )
+    if payload.get("ok") is False:
+        raise RuntimeError(str(payload.get("error") or "get_wallet_overview failed"))
+    data = payload.get("data", {})
+    if not isinstance(data, dict):
+        return {
+            "requested_backend": _backend_label(backend),
+            "requested_network": config.get("network"),
+            "data": data,
+        }
+    data.setdefault("requested_backend", _backend_label(backend))
+    data.setdefault("requested_network", config.get("network"))
+    return data
+
+
 def _invoke_wallet_tool_blocking(
     tool_name: str,
     config: dict[str, Any],
@@ -1002,6 +1401,19 @@ def _invoke_wallet_tool_blocking(
     return payload
 
 
+def _invoke_read_tool_blocking(
+    tool_name: str,
+    effective_params: dict[str, Any],
+    config: dict[str, Any],
+) -> dict[str, Any]:
+    if tool_name not in RESIDENT_READ_ONLY_TOOLS:
+        return _invoke_tool(tool_name, effective_params, config)
+    try:
+        return _invoke_resident_read_tool(tool_name, effective_params, config)
+    except ResidentReadWorkerTransportError:
+        return _invoke_tool(tool_name, effective_params, config)
+
+
 async def _handle_wallet_tool(tool_name: str, params: dict[str, Any]) -> dict[str, Any]:
     config = _base_config(params, tool_name=tool_name)
     backend = _normalize_wallet_backend(config.get("backend"))
@@ -1010,9 +1422,14 @@ async def _handle_wallet_tool(tool_name: str, params: dict[str, Any]) -> dict[st
         config["network"] = selected_evm_network
 
     effective_params = dict(params)
-    payload = await asyncio.to_thread(
-        _invoke_wallet_tool_blocking, tool_name, config, effective_params
-    )
+    if tool_name in RESIDENT_READ_ONLY_TOOLS:
+        payload = await asyncio.to_thread(
+            _invoke_read_tool_blocking, tool_name, effective_params, config
+        )
+    else:
+        payload = await asyncio.to_thread(
+            _invoke_wallet_tool_blocking, tool_name, config, effective_params
+        )
 
     if payload.get("ok") is False:
         raise RuntimeError(str(payload.get("error") or f"{tool_name} failed"))
@@ -1068,6 +1485,8 @@ def build_server():
 
     async def _dispatch(tool_name: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
         params = params or {}
+        if tool_name == "get_wallet_overview":
+            return await _handle_get_wallet_overview(params)
         if tool_name == "get_active_wallet_backend":
             return await _handle_get_active_wallet_backend()
         if tool_name == "set_wallet_backend":
@@ -1101,6 +1520,8 @@ def build_server():
 
 
 def main() -> None:
+    _install_termination_signal_handlers()
+    _prewarm_resident_read_worker()
     build_server().run(show_banner=False)
 
 

package/codex/plugins/agent-wallet/skills/wallet-sol/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "wallet-sol"
+description: "Show the current Solana wallet portfolio from the local AgentLayer wallet in a compact chat table. Use when the user asks for /wallet-sol or wants the Solana wallet shown directly in chat."
+---
+
+# Solana Wallet Portfolio
+
+Use the local AgentLayer wallet MCP tools only.
+
+Workflow:
+
+1. Call `set_wallet_backend` with `backend=solana`.
+2. Call `get_wallet_portfolio` with no address override.
+3. Render the result directly in chat in this shape:
+   - title: `Solana Wallet Portfolio`
+   - bullets for `Chain`, `Network`, `Address`, and `Total Value (USD)` when available
+   - one compact Markdown table with columns: `Asset | Type | Amount | USD Value`
+
+Formatting rules:
+
+- Use `assets` when present.
+- For the asset label, prefer `symbol`, then `name`, then `mint`, then `token_address`, then `asset_type`.
+- When the label came from `symbol`/`name` (not the mint/token_address itself) and a `mint` or `token_address` is present, append it shortened in parentheses next to the label as `first6…last4` (e.g. `USDC (EPjFWd…TDt1v)`) — keep the contract visible but compact, never show it twice.
+- For the asset type, use `asset_type` when present; otherwise infer `native` for the native asset and `token` for the rest.
+- For the amount, prefer `amount_ui`, then `balance_ui`, then `balance_native`, then `amount_raw`.
+- For the USD value, prefer `value_usd`, then `balance_usd`.
+- Do not include source metadata lines or extra footer fields such as `source`, `token_discovery_source`, `pricing_source`, or `pricing_errors`.
+- Keep the response concise. Do not add strategy suggestions, swap ideas, or write actions unless the user explicitly asks for them.
+- If the wallet tool fails, surface the tool error plainly and stop.

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -1,5 +1,5 @@
 name: agent-wallet
-version: 0.1.53
+version: 0.1.58
 description: Thin Hermes Agent bridge to the existing AgentLayer/OpenClaw wallet backend
 provides_tools:
   - agent_wallet_tools

package/package.json

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

package/wdk-btc-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-btc-wallet",
-  "version": "0.1.53",
+  "version": "0.1.58",
   "private": true,
   "type": "module",
   "description": "Separate BTC-only wallet service built on Tether WDK.",

package/wdk-evm-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-evm-wallet",
-  "version": "0.1.53",
+  "version": "0.1.58",
   "private": true,
   "type": "module",
   "description": "Separate EVM wallet service built on Tether WDK.",