@agentlayer.tech/wallet 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Added an optional Hermes Agent bridge plugin under `hermes/plugins/agent_wallet`
+  that forwards into the existing Python wallet CLI instead of duplicating
+  OpenClaw wallet tools or policy.
+- Added `wallet hermes install --yes` and `AGENT_WALLET_BOOT_KEY_FILE` support
+  for smoother Hermes onboarding without manual `.env` editing.
 - Replaced the repo license with `PolyForm Small Business 1.0.0`.
 - Clarified in `README.md` that individuals can audit, fork, run, and modify
   the code for themselves, and that company use follows the PolyForm small

package/README.md

@@ -1,13 +1,16 @@
 ![AgentLayer](logo+name.png)
-
 # AgentLayer
 
+```bash
+npx @agentlayer.tech/wallet install --yes
+```
 AgentLayer is a beta local-first wallet and finance stack for agents.
 
 The repository includes:
 
 - `agent-wallet/` - the main wallet backend for AgentLayer
 - `.openclaw/` - the local AgentLayer bridge layer
+- `hermes/` - optional Hermes Agent plugin bridge for the same wallet backend
 - `wdk-btc-wallet/` - the local Bitcoin wallet service
 - `wdk-evm-wallet/` - the local EVM wallet service
 - `provider-gateway/` - shared provider access for Solana RPC, Bags, and related finance reads
@@ -33,12 +36,6 @@ System prerequisites:
 - `node`
 - `npm`
 
-Install from the latest GitHub release bundle:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/lopushok9/Agent-Layer/main/install-from-github.sh | sh
-```
-
 Install through npm:
 
 ```bash
@@ -66,6 +63,7 @@ Useful npm CLI commands:
 ```bash
 wallet status
 wallet doctor
+wallet hermes install --yes
 wallet update --yes
 wallet rollback
 ```
@@ -143,9 +141,25 @@ Without those secrets, the installer still lays down the runtime and installs de
 }
 ```
 
+## Connect Hermes Agent
+
+OpenClaw remains the primary local environment, but the repo also ships an optional Hermes Agent bridge at:
+
+```bash
+hermes/plugins/agent_wallet
+```
+
+It exposes only two Hermes tools: `agent_wallet_tools` for discovery and `agent_wallet_invoke` for forwarding a single call into the existing Python wallet CLI. Install it by symlinking the plugin directory into Hermes:
+
+```bash
+npx @agentlayer.tech/wallet hermes install --yes
+```
+
+That command installs the Hermes plugin, runs `hermes plugins enable agent-wallet`, writes non-secret runtime paths into `~/.hermes/.env`, and points Hermes at a local boot-key file. Secrets stay in the existing protected OpenClaw runtime paths, especially `~/.openclaw/sealed_keys.json`; do not put wallet secrets into Hermes tool config.
+
 ## What you get after install
 
-If you install from GitHub release, the bundle is extracted under:
+If you install through npm, the runtime is extracted under:
 
 ```bash
 ~/.openclaw/agent-wallet-runtime/current
@@ -159,6 +173,7 @@ The installer then does the following:
 - creates a minimal `~/.openclaw/openclaw.json` if one does not exist
 - if the required secrets are already present, writes or updates `~/.openclaw/sealed_keys.json`
 - if the required secrets are already present, patches `~/.openclaw/openclaw.json` to load the `agent-wallet` extension and point it at the installed runtime
+- `wallet hermes install --yes` additionally connects Hermes Agent to the same runtime without copying wallet tools or policy
 
 When the installer reaches the final config step, the default plugin config is:
 

package/RELEASING.md

@@ -1,217 +1,216 @@
 # Releasing
 
-## npm installer package
-
-The production installer is published as:
+This repo publishes the npm installer as:
 
 ```text
 @agentlayer.tech/wallet
 ```
 
-Expected user install path:
+The public install command is:
 
 ```bash
 npx @agentlayer.tech/wallet install --yes
 ```
 
-The npm package ships source and installer scripts only. It must not ship local
-state such as `node_modules/`, `.venv/`, `__pycache__/`, wallet files, or
-OpenClaw secrets.
+## When npm Publishes
 
-Before publishing a tag, verify locally:
+Normal commits and pushes do not publish new npm versions. They only run the
+GitHub Actions verification job.
 
-```bash
-npm run check
-npm run check:release-version
-python3 agent-wallet/tests/smoke_npm_installer.py
-python3 agent-wallet/tests/smoke_install_agent_wallet.py
-npm --cache /tmp/npm-cache pack --dry-run
-```
+An npm publish happens only when you push a git tag that starts with `v`, for
+example `v0.1.10`.
 
-The GitHub workflow `.github/workflows/npm-installer.yml` verifies the package
-on pull requests and publishes tagged releases to npm through npm Trusted
-Publishing. Configure the npm package's trusted publisher before publishing:
+The same tag workflow also creates a GitHub Release on the repository's
+Releases page after npm publish succeeds.
+
+The tag version must match both source version files:
 
 ```text
-Provider: GitHub Actions
-Organization or user: lopushok9
-Repository: Agent-Layer
-Workflow filename: npm-installer.yml
+package.json
+agent-wallet/pyproject.toml
 ```
 
-The `repository.url` field in `package.json` must exactly match the GitHub
-repository URL, for example `https://github.com/lopushok9/Agent-Layer.git`.
-Do not use the `git+https://` npm shorthand for Trusted Publishing releases.
+If those versions do not match the tag, the workflow fails before publishing.
 
-Do not use `NPM_TOKEN` for publishing unless Trusted Publishing is unavailable.
-Token-based publishes can fail with `EOTP` when package or account policy
-requires two-factor authentication.
+## Stable Release
 
-Publish stable releases from version tags. The tag must match both
-`package.json` and `agent-wallet/pyproject.toml`:
+Use a stable release when users should get it from the default install command.
 
-```bash
-git tag v0.1.6
-git push origin v0.1.6
-```
+Example: publish `0.1.10` as npm `latest`.
 
-The workflow runs:
+1. Update `package.json`:
 
-```bash
-npm publish --access public --tag latest
+```json
+"version": "0.1.10"
 ```
 
-For pre-release tags, use a semver prerelease version in both package files,
-then push the matching tag. The workflow publishes those with npm tag `beta`:
+2. Update `agent-wallet/pyproject.toml`:
 
-```bash
-git tag v0.1.7-beta.1
-git push origin v0.1.7-beta.1
+```toml
+version = "0.1.10"
 ```
 
-Runtime updates are versioned under:
+3. Run local checks:
 
-```text
-~/.openclaw/agent-wallet-runtime/releases/<version>
-~/.openclaw/agent-wallet-runtime/current
+```bash
+npm run check
+GITHUB_REF_NAME=v0.1.10 npm run check:release-version
+python3 agent-wallet/tests/smoke_npm_installer.py
+python3 agent-wallet/tests/smoke_install_agent_wallet.py
+npm --cache /tmp/npm-cache pack --dry-run
 ```
 
-The CLI switches `current` only after a successful install/update. `rollback`
-switches `current` back to the recorded previous runtime or to a specific
-installed version.
-
-This repository's `v0.1.0-beta.2` public release should be framed around six repo-owned deliverables:
+4. Commit the version change:
 
-1. `mcp-server/` - the finance and crypto MCP server
-2. `agent-wallet/` - the Python wallet backend
-3. `.openclaw/extensions/agent-wallet/` - the repo-shipped OpenClaw extension bridge
-4. `wdk-btc-wallet/` - the BTC-only wallet service built on Tether WDK
-5. `provider-gateway/` - the shared non-custodial provider access layer
-6. `docs/` - the Starlight-based documentation site
-
-### Release title
-
-```text
-AgentLayer Beta v0.1.0-beta.2
+```bash
+git add package.json agent-wallet/pyproject.toml
+git commit -m "Release npm installer 0.1.10"
 ```
 
-### Release body
+5. Create and push the release tag:
 
-```md
-This is the second public beta release of the OpenClaw finance stack.
+```bash
+git tag -a v0.1.10 -m "v0.1.10"
+git push origin main
+git push origin v0.1.10
+```
 
-This release keeps the original beta foundation and adds three new repo-owned components:
+6. Check npm after GitHub Actions finishes:
 
-- `mcp-server/` - finance and crypto MCP server
-- `agent-wallet/` - Python wallet backend
-- `.openclaw/extensions/agent-wallet/` - OpenClaw extension bridge for the wallet backend
-- `wdk-btc-wallet/` - BTC-only wallet service for local Bitcoin operations
-- `provider-gateway/` - shared provider access for hosted Solana RPC defaults, Bags, and Jupiter Earn
-- `docs/` - documentation app for setup, architecture, and capability reference
+```bash
+npm view @agentlayer.tech/wallet dist-tags
+npm view @agentlayer.tech/wallet@latest version
+```
 
-## Highlights
+Expected result:
 
-- Expands the beta stack with a dedicated local BTC wallet service
-- Adds a non-custodial shared provider gateway for Solana RPC, Bags, and Jupiter Earn
-- Adds a separate documentation app for onboarding and reference material
-- Keeps the MCP server, wallet backend, and OpenClaw extension bridge as the core beta foundation
+```text
+latest: 0.1.10
+```
 
-## Included in this release
+The GitHub Releases page should also contain a new release named `v0.1.10`.
 
-### New in `v0.1.0-beta.2`
+## Beta Release
 
-#### `wdk-btc-wallet/`
+Use a beta release when you want to test npm publishing without changing the
+default user install command.
 
-- Separate BTC-only wallet service built on top of Tether WDK
-- Local encrypted wallet vault, localhost-only HTTP surface, and local bearer-token auth
-- Covers Bitcoin network selection, wallet lifecycle, balances, transfers, fees, and spendability
+Example: publish `0.1.11-beta.1` as npm `beta`.
 
-#### `provider-gateway/`
+1. Set both version files to the beta version:
 
-- Shared non-custodial provider layer for onboarding-friendly defaults
-- Hosted Solana RPC gateway with method allowlist
-- Shared Bags launch and fees access plus shared Jupiter Earn relay
+```json
+"version": "0.1.11-beta.1"
+```
 
-#### `docs/`
+```toml
+version = "0.1.11-beta.1"
+```
 
-- Separate Starlight-based documentation app for AgentLayer
-- Covers getting started, infrastructure boundaries, wallet architecture, and capabilities
-- Gives the beta stack a repo-owned documentation surface for onboarding and review
+2. Run checks:
 
-### Existing beta foundation
+```bash
+npm run check
+GITHUB_REF_NAME=v0.1.11-beta.1 npm run check:release-version
+npm --cache /tmp/npm-cache pack --dry-run
+```
 
-#### `mcp-server/`
+3. Commit, tag, and push:
 
-- MCP server for crypto, DeFi, gas, on-chain, and agent identity workflows
-- Structured tools for market data, protocol analytics, and blockchain lookups
-- Self-hostable base for OpenClaw or other MCP-compatible clients
+```bash
+git add package.json agent-wallet/pyproject.toml
+git commit -m "Release npm installer 0.1.11-beta.1"
+git tag -a v0.1.11-beta.1 -m "v0.1.11-beta.1"
+git push origin main
+git push origin v0.1.11-beta.1
+```
 
-#### `agent-wallet/`
+4. Test the beta package:
 
-- Local Solana wallet backend for OpenClaw-connected agents
-- Read, preview, prepare, and approval-gated execute flows
-- Local secret handling and explicit operator approval model for risky actions
+```bash
+npx @agentlayer.tech/wallet@beta --version
+npx @agentlayer.tech/wallet@beta doctor
+```
 
-#### `.openclaw/extensions/agent-wallet/`
+The GitHub Releases page should contain a new prerelease named
+`v0.1.11-beta.1`.
 
-- Thin TypeScript bridge from OpenClaw into the Python wallet backend
-- Repo-tracked plugin manifest and config schema
-- Keeps wallet policy and execution logic in Python while exposing a small operational tool surface to OpenClaw
+## What Ships
 
-## Beta notes
+The npm package is intentionally limited to the wallet installer runtime:
 
-- This is a beta release and should not be treated as production-ready custody infrastructure
-- Mainnet use should remain cautious, explicit, and operator-controlled
-- Early feedback on usability, safety, and integration gaps is expected and welcome
+```text
+.openclaw/extensions/agent-wallet
+agent-wallet
+wdk-btc-wallet
+wdk-evm-wallet
+bin
+scripts
+setup.sh
+install-from-github.sh
+README.md
+CHANGELOG.md
+RELEASING.md
+LICENSE
 ```
 
-## Suggested release note structure
+It must not ship unrelated repo projects or generated local state:
 
-### Highlights
-
-- Expands the stack with `wdk-btc-wallet/`, `provider-gateway/`, and `docs/`
-- Keeps `mcp-server/`, `agent-wallet/`, and `.openclaw/extensions/agent-wallet/` as the base beta foundation
-- Beta release intended for testing, onboarding, and early adopters
-
-### Included in this release
-
-#### `wdk-btc-wallet/`
+```text
+landing
+solana-8004
+provider-gateway
+mcp-server
+agent-a2a-gateway
+docs
+node_modules
+.venv
+__pycache__
+.pytest_cache
+.DS_Store
+wallet files
+OpenClaw secrets
+```
 
-- Local BTC wallet service built on Tether WDK
-- Wallet lifecycle, balances, fee rates, spendability, and transfer support
-- Separate runtime from the existing Solana wallet backend
+The package allowlist lives in `package.json` under `files`.
 
-#### `provider-gateway/`
+## Runtime Layout
 
-- Hosted Solana RPC defaults through a shared gateway
-- Bags launch and fees provider access
-- Jupiter Earn provider access
+Installer releases are copied into the user's OpenClaw home:
 
-#### `docs/`
+```text
+~/.openclaw/agent-wallet-runtime/releases/<version>
+~/.openclaw/agent-wallet-runtime/current
+```
 
-- Separate documentation app for setup and architecture reference
-- Covers infrastructure and wallet capability docs
-- Repo-owned docs surface for the public beta
+The CLI switches `current` only after a successful install or update.
 
-#### `mcp-server/`
+Rollback switches `current` back to the previous runtime or to a specific
+installed version:
 
-- MCP server for crypto, DeFi, and on-chain data workflows
-- Read-oriented market, protocol, gas, and identity tooling
-- Local/self-hostable deployment path
+```bash
+npx @agentlayer.tech/wallet rollback
+```
 
-#### `agent-wallet/`
+## GitHub And npm Setup
 
-- Local Solana wallet backend for OpenClaw-connected agents
-- Read, preview, prepare, and approved execute flows
-- Encrypted local secret handling and explicit approval gating for risky actions
+Publishing uses npm Trusted Publishing through GitHub Actions. The npm package
+must have this trusted publisher configured:
 
-#### `.openclaw/extensions/agent-wallet/`
+```text
+Provider: GitHub Actions
+Organization or user: lopushok9
+Repository: Agent-Layer
+Workflow filename: npm-installer.yml
+Environment name: empty
+```
 
-- Thin TypeScript bridge from OpenClaw into the Python wallet backend
-- Plugin manifest and config schema tracked in the repo
-- Repo-local extension package for OpenClaw integration
+The `repository.url` field in `package.json` must exactly match the GitHub
+repository URL:
 
-### Beta notes
+```text
+https://github.com/lopushok9/Agent-Layer.git
+```
 
-- This is a beta release and should not be presented as production-ready custody infrastructure
-- Mainnet usage should remain cautious and operator-controlled
+Do not use `NPM_TOKEN` unless Trusted Publishing is unavailable. Token-based
+publishes can fail with `EOTP` when npm requires two-factor authentication.

package/agent-wallet/README.md

@@ -18,6 +18,7 @@ The package now includes a thin adapter for agent runtimes:
 - `agent_wallet.plugin_bundle.build_openclaw_plugin_bundle`
 - `agent_wallet.openclaw_runtime.onboard_openclaw_user_wallet`
 - `agent_wallet.openclaw_cli` for the official OpenClaw TypeScript plugin bridge
+- `hermes/plugins/agent_wallet` as an optional Hermes Agent bridge to the same CLI
 
 It provides:
 
@@ -27,6 +28,23 @@ It provides:
 - OpenClaw-style plugin manifest and skill bundle
 - explicit network-aware results so the host and agent can see `devnet` vs `mainnet`
 
+## Hermes integration
+
+The optional Hermes plugin is intentionally a bridge, not a port of the OpenClaw plugin. It registers:
+
+- `agent_wallet_tools` - read-only discovery for the underlying Python adapter tool specs.
+- `agent_wallet_invoke` - a dispatcher that calls `python -m agent_wallet.openclaw_cli invoke`.
+
+Install it with:
+
+```bash
+npx @agentlayer.tech/wallet hermes install --yes
+```
+
+That command symlinks `hermes/plugins/agent_wallet` into `~/.hermes/plugins/agent_wallet`, enables the plugin with `hermes plugins enable agent-wallet`, and writes `AGENT_WALLET_PACKAGE_ROOT`, `AGENT_WALLET_PYTHON`, and `AGENT_WALLET_BOOT_KEY_FILE` into `~/.hermes/.env`. OpenClaw remains the canonical host integration and wallet safety policy remains in Python.
+
+Hermes tool config must not contain wallet secrets. Use the existing sealed runtime path and host-issued approval tokens for execute flows. `AGENT_WALLET_BOOT_KEY_FILE` lets OpenClaw and Hermes reference one local boot-key file instead of duplicating the boot key across multiple env files.
+
 Current safe tools:
 
 - `get_wallet_capabilities`

package/agent-wallet/agent_wallet/config.py

@@ -13,6 +13,7 @@ class Settings(BaseSettings):
     agent_wallet_backend: str = "none"
     agent_wallet_sign_only: bool = False
     agent_wallet_boot_key: str = ""
+    agent_wallet_boot_key_file: str = ""
     agent_wallet_approval_ttl_seconds: int = 600
     agent_wallet_per_user_key_derivation: bool = True
     agent_wallet_encrypt_user_wallets: bool = True
@@ -297,7 +298,16 @@ def _env_bool(name: str, default: bool) -> bool:
 
 def resolve_boot_key() -> str:
     """Resolve the boot key used to unlock sealed secrets from disk."""
-    return os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
+    direct = os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
+    if direct:
+        return direct
+    key_file = os.getenv("AGENT_WALLET_BOOT_KEY_FILE", settings.agent_wallet_boot_key_file).strip()
+    if not key_file:
+        return ""
+    try:
+        return Path(key_file).expanduser().read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
 
 
 def _reject_legacy_runtime_secret_env(var_name: str) -> None:

package/agent-wallet/agent_wallet/openclaw_adapter.py

@@ -11,6 +11,14 @@ from agent_wallet.models import AgentToolResult, AgentToolSpec
 from agent_wallet.wallet_layer.base import AgentWalletBackend, WalletBackendError
 
 
+def _canonical_json_text(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+
+def preview_payload_digest(preview: dict[str, Any]) -> str:
+    return hashlib.sha256(_canonical_json_text(preview).encode("utf-8")).hexdigest()
+
+
 WALLET_RUNTIME_INSTRUCTIONS = """
 Use wallet tools only when the user explicitly asks for wallet-related actions.
 Treat any signing request as sensitive.
@@ -4398,19 +4406,76 @@ class OpenClawWalletAdapter:
                         ),
                     )
 
-                execute_preview = await self.backend.preview_swap(
-                    input_mint=input_mint.strip(),
-                    output_mint=output_mint.strip(),
-                    amount_ui=float(amount),
-                    slippage_bps=slippage_bps,
+                approval_payload = inspect_approval_token(
+                    approval_token,
+                    tool_name=tool_name,
+                    network=str(getattr(self.backend, "network", "unknown")),
+                    require_mainnet_confirmation=self._is_mainnet_for_backend(self.backend),
                 )
+                approval_summary = approval_payload.get("binding", {}).get("summary")
+                if not isinstance(approval_summary, dict):
+                    raise WalletBackendError(
+                        "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                    )
+                expected_summary = {
+                    "operation": "Swap",
+                    "network": str(getattr(self.backend, "network", "unknown")),
+                    "input_mint": input_mint.strip(),
+                    "output_mint": output_mint.strip(),
+                    "slippage_bps": slippage_bps,
+                }
+                for key, expected_value in expected_summary.items():
+                    if approval_summary.get(key) != expected_value:
+                        raise WalletBackendError(
+                            "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                        )
+                try:
+                    approved_amount = float(approval_summary.get("input_amount_ui"))
+                except (TypeError, ValueError):
+                    raise WalletBackendError(
+                        "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                    )
+                if approved_amount != float(amount):
+                    raise WalletBackendError(
+                        "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                    )
+
+                approval_summary_copy = dict(approval_summary)
+                approved_preview = args.get("_approved_preview")
+                if isinstance(approval_summary_copy.get("_preview_digest"), str):
+                    if not isinstance(approved_preview, dict):
+                        raise WalletBackendError(
+                            "Approved swap preview payload is required for execute mode. Generate a new preview and approval before execute."
+                        )
+                    if preview_payload_digest(approved_preview) != approval_summary_copy["_preview_digest"]:
+                        raise WalletBackendError(
+                            "approved preview payload does not match the approval token. Generate a new preview and approval before execute."
+                        )
+                    preview_summary = self._build_confirmation_summary(
+                        action_label="Swap",
+                        payload=approved_preview,
+                    )
+                    summary_without_digest = {
+                        key: value
+                        for key, value in approval_summary_copy.items()
+                        if key != "_preview_digest"
+                    }
+                    if preview_summary != summary_without_digest:
+                        raise WalletBackendError(
+                            "approved preview payload does not match the approval token. Generate a new preview and approval before execute."
+                        )
+                    execute_preview = dict(approved_preview)
+                else:
+                    execute_preview = await self.backend.preview_swap(
+                        input_mint=input_mint.strip(),
+                        output_mint=output_mint.strip(),
+                        amount_ui=float(amount),
+                        slippage_bps=slippage_bps,
+                    )
                 self._require_execute_approval(
                     approval_token=approval_token,
                     tool_name=tool_name,
-                    summary=self._build_confirmation_summary(
-                        action_label="Swap",
-                        payload=execute_preview,
-                    ),
+                    summary=approval_summary_copy,
                     action_label="Swap",
                 )