zetrix-agentic-wallet 0.3.4

package/README.md

@@ -0,0 +1,177 @@
+# Zetrix Agentic Wallet — OpenClaw plugin
+
+**Using the wallet?** See the
+**[user guide](https://github.com/Zetrix-Chain/zetrix-agentic-wallet/blob/main/openclaw-plugin/USER_GUIDE.md)**
+— install, first steps, spending limits and backup, written for subscribers. It also ships inside this
+package as `USER_GUIDE.md`. This file is the engineering detail: why the plugin is built the way it is,
+and what to know before changing it.
+
+---
+
+Installs the Zetrix Agentic Wallet into an OpenClaw gateway, so a subscriber gets the wallet by
+installing one package instead of hand-writing an `mcp.servers` entry — which they cannot do at all on
+a hosted gateway they do not own.
+
+```bash
+openclaw plugins install clawhub:zetrix-agentic-wallet@<version>
+openclaw plugins enable zetrix-agentic-wallet
+openclaw gateway restart
+```
+
+Nothing else is required. No `npx`, no registry access at runtime, no MCP configuration, and **no
+password**: the wallet generates and stores its own credentials.
+
+## Build
+
+```bash
+npm run build          # in the repo root — produces the wallet bundle
+npm run build          # in openclaw-plugin — bundles the plugin and vendors the wallet
+npm test               # 56 tests: registration logic, paths, and the package contract
+```
+
+## Configuration
+
+Set by the subscriber, through the gateway's plugin config UI or `plugins.entries`:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `network` | `zetrix:testnet` | Mainnet spends real funds |
+| `maxPaymentAmount` | `{"*":"0"}` | Per-asset ceiling in raw units. **Refuses every payment until set** |
+| `zetrixAddress` | *(unset)* | Pin an existing holder account instead of creating one |
+
+These defaults apply with no action from the subscriber, so a fresh install is safe but **cannot pay**
+until a cap is set. Changing config takes effect without a gateway restart:
+
+```bash
+openclaw config set plugins.entries.zetrix-agentic-wallet.config.maxPaymentAmount \
+  '{"ZTX":"1000000000","*":"0"}' --json
+openclaw mcp reload
+```
+
+⚠️ **Configure through `plugins.entries`, never by editing `mcp.servers` directly.** The plugin owns
+that entry and rewrites it from plugin config, so a hand-edit is the wrong layer in two ways. It is
+overwritten the next time the plugin registers — and if it is *not* overwritten, that is worse: the
+plugin fingerprints the entry it wrote and disowns anything that no longer matches, so a hand-edited
+entry is left permanently unmanaged and stops tracking config changes. Neither failure announces itself.
+
+Setting plugin config re-registers the entry immediately, because the CLI loads the plugin in-process
+(see [If the MCP entry goes missing](#if-the-mcp-entry-goes-missing)). Editing `openclaw.json` by hand
+does not.
+
+## Why it works the way it does
+
+Three things were tested against a live gateway (OpenClaw **2026.7.1-2**) and shaped this design. Each
+is stated here with what was observed, because the design looks odd without it — and because if any of
+them changes upstream, the corresponding workaround should be deleted rather than carried forever.
+
+**The manifest declares no `mcpServers`, and that is deliberate.** It is the documented way for a plugin
+to contribute an MCP server, but **it is not a field this OpenClaw release implements** — the ClawHub
+Plugin Inspector lists every supported `PluginManifest` field for 2026.7.1-2 and `mcpServers` is not
+among them. So a declared server is silently dropped: never spawned, no diagnostic. Native `api.registerTool` tools do register, but never
+reach a `claude-cli` harness, so an agent cannot call them. Writing the entry into `mcp.servers` from
+the registration hook is the only route that works end to end. *If the manifest route is ever fixed
+upstream, `src/index.ts` is what should be deleted.*
+
+**The wallet is vendored into the plugin, as a single CJS bundle.** `openclaw plugins install` is a
+directory copy, not an npm install: a declared dependency produced no `node_modules` in the installed
+copy, and `files` was ignored. So the wallet must ship inside the plugin.
+
+Vendoring a real `npm install` tree was the first attempt, and it is the more faithful one — the wallet
+publishes with `zetrix-sdk-nodejs` external, so that is the configuration it is tested in. It had to be
+abandoned: ~8,250 files produced a tarball **OpenClaw cannot install**.
+
+```
+failed to extract archive: Error: extract tar timed out after 120000ms
+```
+
+A tarball is how ClawHub ships, so an unextractable package is fatal rather than merely slow. One
+bundled file is 3.4 MB, packs to a 644 KB / 7-file tarball, and installs instantly.
+
+⚠️ **The bundle must be CJS.** The SDK and its dependencies use dynamic `require`, which esbuild cannot
+express in ESM output — an ESM bundle loads and then dies at first use with *"Dynamic require of
+`buffer` is not supported"*. In CJS `require` stays native, and both `account.getInfo` and the
+protobufjs-heavy `contract.call` were verified working through the bundle against a live node. A test
+asserts the format, because this fails at *call* time, not at load.
+
+**The runtime is then copied *out* of the plugin, and so is the ownership marker.** OpenClaw exposes no
+uninstall hook a plugin can use — `api.lifecycle` offers only `registerRuntimeLifecycle`, and a
+disabled plugin is never loaded, so no cleanup code of ours can ever run. Two consequences:
+
+- Pointing the config entry at the plugin's own directory would leave a **broken** server behind on
+  uninstall. Pointing it at `<gatewayStateDir>/zetrix-agentic-wallet/runtime` leaves a **working** one.
+- The ownership marker lived inside the plugin at first, and `plugins install --force` wiped it — after
+  which the plugin treated its own entry as subscriber-owned and refused to manage it, orphaning the
+  entry on every update. It now lives beside the runtime.
+
+## If the MCP entry goes missing
+
+Removing `mcp.servers["zetrix-agentic-wallet"]` by hand **stops the wallet working immediately** — the
+tools disappear, because there is no server for the agent to call. The plugin still reports as enabled;
+it just provides nothing.
+
+The entry is self-healing, but not on the trigger you would expect. Tested on 2026.7.1-2:
+
+| Action | Entry restored? |
+|---|---|
+| `openclaw gateway restart` | **No** — waited two minutes, no registration in the logs |
+| `openclaw plugins install` / `enable` | Yes |
+| `openclaw plugins inspect <id> --runtime` | Yes |
+| `openclaw agent …` | Yes |
+
+The registration hook runs when the **CLI** loads the plugin in-process, not on a gateway restart. So if
+the entry is ever lost, the fix is any plugin-loading command:
+
+```bash
+openclaw plugins inspect zetrix-agentic-wallet --runtime
+```
+
+Worth knowing for two reasons: a restart is the natural thing to reach for and it will not help, and a
+subscriber who deletes the entry to disable the wallet will find it back after the next plugin
+operation. To disable the wallet properly, disable the plugin.
+
+## Uninstalling completely
+
+Because there is no uninstall hook, removal is two steps. The wallet keeps working after step 1, which
+is intentional — it is a wallet holding an account, and silently breaking it would be worse.
+
+```bash
+openclaw plugins uninstall zetrix-agentic-wallet --force
+openclaw mcp unset zetrix-agentic-wallet
+```
+
+⚠️ **Before deleting `<gatewayStateDir>/zetrix-agentic-wallet/`, back up the wallet.** It holds the
+holder identity and the generated HSM password, and that password is the only thing that can authorize
+signing for the account. Run `npx agentic-wallet-mcp export-credentials` in an interactive terminal
+first. There is no recovery once it is gone.
+
+Two things to know if `mcp unset` fails: OpenClaw rejects config writes that shrink the file sharply
+(`Config write rejected … size-drop`), which a legitimate removal can trigger, and
+`plugins uninstall --force` may leave the plugin directory behind — OpenClaw auto-loads anything under
+`extensions/`, so the plugin keeps reporting as enabled until that directory is deleted.
+
+## Caveats for review
+
+- **This plugin writes to `mcp.servers`, which is documented as the operator's authoritative override
+  surface.** It never overwrites an entry it did not create, but the inversion is real and was a
+  deliberate choice made only after the two supported routes were shown not to work.
+- **Writing config directly bypasses OpenClaw's own write validation**, including the size-drop guard
+  above. Our writes only add keys, so they cannot shrink the file, but the bypass is worth knowing.
+- **`plugins.allow` is a whitelist, not additive trust.** If you set it, enumerate every required
+  plugin — setting it to a single id excluded the agent harness during testing and left the agent
+  unable to run at all.
+
+## Validating before publish
+
+```bash
+npm run build                 # from the repo root
+node scripts/build.mjs        # from openclaw-plugin
+clawhub package validate . --openclaw-version <target>
+```
+
+Run this before treating any plugin change as done. It extracts the real `PluginManifest` type from the
+target OpenClaw release and checks the manifest against it, which catches a class of mistake nothing else
+does: a field that is silently ignored rather than rejected. It found two in this plugin — `uiHints`
+instead of `configUiHints`, and confirmed `mcpServers` is not implemented in 2026.7.1-2 at all.
+
+Reports land in `reports/` (gitignored). `--runtime --allow-execute` additionally imports the plugin code
+in an isolated workspace.

package/USER_GUIDE.md

@@ -0,0 +1,233 @@
+# Zetrix Agentic Wallet — user guide
+
+Gives your OpenClaw agent a Zetrix wallet. It can prove who you are, collect verifiable credentials,
+and pay for pay-per-use resources — without you creating an account, choosing a password, or editing
+any configuration.
+
+**Two things to know before you start:**
+
+- The wallet **creates its own account and password**. You never type either. That also means the
+  credentials exist only on this machine — [back them up](#backing-up-your-wallet).
+- It **will not pay for anything** until you [set a spending limit](#setting-your-spending-limit).
+  That is deliberate, not a fault.
+
+---
+
+## 1. Install
+
+```bash
+openclaw plugins install clawhub:zetrix-agentic-wallet
+openclaw plugins enable zetrix-agentic-wallet
+openclaw gateway restart
+```
+
+Check it worked:
+
+```bash
+openclaw plugins list          # zetrix-agentic-wallet, enabled
+openclaw mcp doctor            # zetrix-agentic-wallet: ok
+openclaw mcp probe zetrix-agentic-wallet   # 10 tools
+```
+
+Nothing else is needed. No `npx`, no account signup, no password, no MCP configuration.
+
+The first time the wallet runs it creates a Zetrix account on **testnet** and stores it under
+`~/.openclaw/zetrix-agentic-wallet/state/`.
+
+## 2. Try it
+
+Open the dashboard and ask in plain language — you do not need to name tools:
+
+```bash
+openclaw dashboard
+```
+
+> **What is my Zetrix wallet address?**
+
+You should get an address starting `ZTX3…`, a holder DID, and the network (`zetrix:testnet`).
+
+Other things that work straight away, all free:
+
+> Do I hold any verifiable credentials?
+> What is my ZTX balance?
+> What attributes does credential template X require?
+
+## 3. What it can do
+
+| Ask for | Costs money? |
+|---|---|
+| Wallet address, DID, network, balance | no |
+| Which credentials you hold | no |
+| What a credential template requires | no |
+| Reading on-chain contract data | no |
+| Proving your identity to a service | no |
+| **Fetching a resource that charges per use** | **yes** |
+| **Obtaining a verifiable credential** | **yes** |
+| **Starting a Verified AI Birthcert check (owner identity verification via MyDigital ID)** | **yes** |
+
+The three paid actions are refused until you set a limit.
+
+---
+
+## Setting your spending limit
+
+The wallet starts at **zero** — every payment is declined. This is on purpose: a wallet that could
+spend whatever a website asked for, straight out of the box, is not a safe default.
+
+### Through the dashboard
+
+Open the plugin's settings and set **Maximum payment per call**. That is the whole change.
+
+### From the command line
+
+```bash
+openclaw config set plugins.entries.zetrix-agentic-wallet.config.maxPaymentAmount \
+  '{"ZTX":"1000000000","*":"0"}' --json
+openclaw mcp reload
+```
+
+It takes effect immediately — no gateway restart.
+
+### Reading the limit
+
+The value is a map of **token → maximum per payment**, and `"*"` is the fallback for any token you have
+not listed.
+
+```json
+{ "ZTX": "1000000000", "*": "0" }
+```
+
+- **`"ZTX": "1000000000"`** — up to 1,000,000,000 raw units of ZTX per payment
+- **`"*": "0"`** — everything else refused
+
+Amounts are in **raw units**, not whole tokens. ZTX has 6 decimals, so `1000000000` is **1,000 ZTX**.
+
+### One limit for everything, or a limit per token?
+
+Both work. Pick based on how much you care about what you are paying *in*.
+
+**One limit for everything** — simplest, and fine for testing:
+
+```json
+{ "*": "1000000000" }
+```
+
+Any token, up to 1,000,000,000 raw units per payment.
+
+**A limit per token** — safer, and what we recommend once real money is involved:
+
+```json
+{ "ZTX": "1000000000", "ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b": "5000000", "*": "0" }
+```
+
+Only those two are payable, each with its own ceiling; everything else is refused.
+
+**A ticker like `"JMYR"` works too**, for tokens the wallet knows. A payment request identifies a
+token by its contract address, so the wallet resolves the ticker to that address for you. If you
+write **both**, the contract address wins — it is the more specific of the two.
+
+A ticker the wallet does not recognise still matches nothing, and the payment falls through to `"*"`.
+If a refusal mentions the `"*"` fallback, that is what happened: no limit was set for that asset, so
+use its contract address instead.
+
+To find a token's address, ask your agent:
+
+> Look up the JMYR token contract address on this network
+
+**Why per-token is safer**, despite being more work:
+
+- **The same number is not the same value.** 1,000 ZTX and 1,000 JMYR are different amounts of money. A
+  single universal limit treats them as interchangeable, because it only counts units.
+- **Decimals vary by token.** ZTX and JMYR both use 6, but nothing guarantees the next one does. On a
+  token with 2 decimals, `1000000000` raw units would be ten million tokens.
+- **It auto-approves tokens you have never heard of.** With `{"*": "1000000000"}`, a service can quote
+  an obscure token and be paid, as long as the unit count fits. Listing tokens explicitly means you
+  decide what is acceptable currency, not the service asking for money.
+
+**Once you list any token, the limit becomes an allowlist.** A token with no entry and no `"*"` fallback
+is **denied**, not passed through. Keeping `"*": "0"` means "only the tokens I have listed".
+
+### It is a hard limit, not a prompt
+
+The limit is enforced by the wallet itself, before any payment is signed. Your agent cannot talk its way
+past it, and neither can a website. If a payment exceeds the limit it is refused, and the agent should
+tell you so rather than retrying.
+
+> ⚠️ **Set this through the plugin settings, not by editing `openclaw.json` directly.** The plugin
+> manages its own entry in that file and will either overwrite your edit or stop managing the entry
+> altogether. Neither is obvious when it happens.
+
+## Adding funds
+
+A brand-new wallet has no funds, so even with a limit set it cannot pay yet.
+
+1. Ask your agent for your wallet address
+2. Send testnet ZTX to it from another Zetrix wallet
+3. Ask **"what is my ZTX balance?"** to confirm it arrived
+
+Until the address has received anything, the wallet reports it is **not yet activated on chain** — that
+means "send it some ZTX", not "something is broken".
+
+## Backing up your wallet
+
+**Do this once, now.** The wallet generated its own password and keeps it on this machine. It is the
+only thing that can authorise payments from your account. If you lose this machine without a backup, the
+account and anything in it are **gone permanently** — nobody can recover it, including us.
+
+```bash
+npx agentic-wallet-mcp export-credentials
+```
+
+Run it in your own terminal window. It prints your address, DID and password. Store them somewhere
+private, such as a password manager.
+
+It only works in an interactive terminal, and it is deliberately **not** something your agent can do —
+so your password never appears in a conversation.
+
+## Moving to mainnet
+
+Testnet tokens are not real. To use real funds:
+
+```bash
+openclaw config set plugins.entries.zetrix-agentic-wallet.config.network zetrix:mainnet
+openclaw mcp reload
+```
+
+Before you do:
+
+- **Back up your wallet** (above) if you have not already
+- **Review your spending limit** — the same number now means real money
+- **The Verified AI Birthcert check is unavailable on mainnet through this plugin.** Its endpoint
+  was never confirmed reachable on mainnet, so the wallet refuses to use it there unless an
+  operator sets it explicitly — something this plugin does not currently expose a setting for.
+  Every other tool works normally.
+- Note that mainnet uses a **different account** from your testnet one
+
+## If something is wrong
+
+| What you see | What it means |
+|---|---|
+| Agent says the wallet tools are unavailable | Plugin not enabled, or gateway needs restarting. Check `openclaw plugins list` |
+| *"payment blocked … exceeds configured MAX_PAYMENT_AMOUNT"* | Working as intended — raise the limit if the amount is right |
+| *"not activated"* | The address has no funds yet. Send it ZTX |
+| Balance lookup fails but the wallet otherwise works | Usually a network problem reaching the Zetrix node |
+| Everything fails after connecting to a corporate VPN | Some VPNs block the Zetrix endpoints. Try disconnecting |
+
+Useful commands:
+
+```bash
+openclaw mcp doctor                        # is the wallet configured correctly?
+openclaw mcp probe zetrix-agentic-wallet   # can it start, and what tools does it offer?
+openclaw logs --limit 200                  # what did it actually say?
+```
+
+## Removing the wallet
+
+```bash
+openclaw plugins uninstall zetrix-agentic-wallet --force
+openclaw mcp unset zetrix-agentic-wallet
+```
+
+⚠️ **Back up first.** Deleting `~/.openclaw/zetrix-agentic-wallet/` destroys the account permanently.
+The wallet keeps working between those two commands — that is intentional, so an uninstall does not
+silently strand an account holding funds.

package/dist/index.js

@@ -0,0 +1,201 @@
+// src/index.ts
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join as join2 } from "node:path";
+
+// src/paths.ts
+import { join } from "node:path";
+function resolvePluginPaths(rootDir) {
+  const gatewayStateDir = join(rootDir, "..", "..");
+  const homeDir = join(gatewayStateDir, "zetrix-agentic-wallet");
+  const runtimeDir = join(homeDir, "runtime");
+  return {
+    gatewayStateDir,
+    configPath: join(gatewayStateDir, "openclaw.json"),
+    ownershipPath: join(homeDir, ".mcp-registration.json"),
+    homeDir,
+    runtimeDir,
+    shippedRuntimeDir: join(rootDir, "dist", "runtime"),
+    walletStateDir: join(homeDir, "state"),
+    walletBundlePath: join(runtimeDir, "server-bundle.cjs")
+  };
+}
+
+// src/mcp-registration.ts
+var SERVER_NAME = "zetrix-agentic-wallet";
+function buildServerEntry(walletBundlePath, config, stateDir) {
+  return {
+    command: "node",
+    args: [walletBundlePath],
+    env: {
+      ZETRIX_NETWORK: config.network ?? "zetrix:testnet",
+      // Deliberately absent when unconfigured, rather than defaulted here.
+      //
+      // The wallet's own default is network-aware — testnet allows exactly the credential fee,
+      // mainnet refuses everything, because the cap is per call and nothing limits how many calls
+      // are made. This layer cannot know the network at config time, so anything sent from here
+      // would shadow that and pin every subscriber to one behaviour.
+      //
+      // The manifest declares no `default` for the same reason: OpenClaw materialises configSchema
+      // defaults into plugin config with no operator action (SPIKE-0.4-FINDINGS.md §2.1), so a
+      // declared default would arrive here as a real value and never reach this branch.
+      ...config.maxPaymentAmount ? { MAX_PAYMENT_AMOUNT: JSON.stringify(config.maxPaymentAmount) } : {},
+      ZETRIX_WALLET_STATE_DIR: stateDir,
+      ...config.zetrixAddress ? { ZETRIX_ADDRESS: config.zetrixAddress } : {}
+    }
+  };
+}
+function readConfig(deps) {
+  let raw;
+  try {
+    raw = deps.readFile(deps.configPath);
+  } catch (e) {
+    deps.log(`could not read ${deps.configPath}: ${e.message} \u2014 skipping MCP registration`);
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      deps.log(`could not use ${deps.configPath}: not a JSON object \u2014 skipping MCP registration`);
+      return null;
+    }
+    return parsed;
+  } catch (e) {
+    deps.log(`could not parse ${deps.configPath}: ${e.message} \u2014 skipping MCP registration`);
+    return null;
+  }
+}
+function readOwnership(deps) {
+  if (!deps.exists(deps.ownershipPath)) return null;
+  try {
+    return JSON.parse(deps.readFile(deps.ownershipPath));
+  } catch {
+    return null;
+  }
+}
+function weOwnIt(deps, existing) {
+  const record = readOwnership(deps);
+  if (!record) return false;
+  if (!existing) return true;
+  if (!record.entry) return true;
+  return JSON.stringify(record.entry) === JSON.stringify(existing);
+}
+function writeOwnership(deps, entry) {
+  const record = {
+    serverName: SERVER_NAME,
+    entry,
+    note: "Created by the Zetrix Agentic Wallet plugin. The entry above is a fingerprint: the plugin only manages mcp.servers while the live entry still matches it, so a hand-edited entry is never overwritten. Deleting this file makes the plugin treat the entry as subscriber-owned."
+  };
+  deps.writeFile(deps.ownershipPath, `${JSON.stringify(record, null, 2)}
+`);
+}
+function writeConfigAtomically(deps, config) {
+  const tmp = `${deps.configPath}.zetrix-tmp`;
+  deps.writeFile(tmp, `${JSON.stringify(config, null, 2)}
+`);
+  deps.renameFile(tmp, deps.configPath);
+}
+function registerServer(deps, entry) {
+  const config = readConfig(deps);
+  if (!config) return;
+  const existing = config.mcp?.servers?.[SERVER_NAME];
+  if (existing && !weOwnIt(deps, existing)) {
+    deps.log(
+      `mcp.servers["${SERVER_NAME}"] is already present and was not created by this plugin (or was changed since) \u2014 leaving it untouched. Remove it if you want the plugin to manage the server.`
+    );
+    return;
+  }
+  if (existing && JSON.stringify(existing) === JSON.stringify(entry)) {
+    writeOwnership(deps, entry);
+    return;
+  }
+  config.mcp = config.mcp ?? {};
+  config.mcp.servers = config.mcp.servers ?? {};
+  config.mcp.servers[SERVER_NAME] = entry;
+  writeConfigAtomically(deps, config);
+  writeOwnership(deps, entry);
+  deps.log(existing ? `refreshed mcp.servers["${SERVER_NAME}"]` : `registered mcp.servers["${SERVER_NAME}"]`);
+}
+
+// src/index.ts
+function makeDeps(paths, log) {
+  return {
+    configPath: paths.configPath,
+    ownershipPath: paths.ownershipPath,
+    readFile: (p) => readFileSync(p, "utf8"),
+    writeFile: (p, c) => writeFileSync(p, c, { encoding: "utf8", mode: 384 }),
+    renameFile: (from, to) => renameSync(from, to),
+    exists: (p) => existsSync(p),
+    removeFile: (p) => rmSync(p, { force: true }),
+    log
+  };
+}
+function pathIsExpected(paths) {
+  const expectedSuffix = join2("zetrix-agentic-wallet", "runtime");
+  return paths.runtimeDir.endsWith(expectedSuffix) && paths.runtimeDir.startsWith(paths.homeDir) && paths.homeDir.length > expectedSuffix.length;
+}
+function shippedBundleMatchesDigest(paths, shippedVersion, log) {
+  const recorded = /sha256:([0-9a-f]{64})/.exec(shippedVersion)?.[1];
+  if (!recorded) return true;
+  const shippedBundle = join2(paths.shippedRuntimeDir, "server-bundle.cjs");
+  const actual = createHash("sha256").update(readFileSync(shippedBundle)).digest("hex");
+  if (actual === recorded) return true;
+  log(
+    `refusing to install the wallet runtime: the shipped bundle does not match the digest recorded in VERSION (expected ${recorded.slice(0, 12)}, got ${actual.slice(0, 12)}). The package may be corrupt or modified \u2014 reinstall it from a trusted source.`
+  );
+  return false;
+}
+function syncRuntime(paths, log) {
+  const shippedVersionFile = join2(paths.shippedRuntimeDir, "VERSION");
+  if (!existsSync(shippedVersionFile)) {
+    log(`the plugin is missing its wallet runtime at ${paths.shippedRuntimeDir} \u2014 reinstall the plugin`);
+    return false;
+  }
+  const shipped = readFileSync(shippedVersionFile, "utf8").trim();
+  const installedVersionFile = join2(paths.runtimeDir, "VERSION");
+  const installed = existsSync(installedVersionFile) ? readFileSync(installedVersionFile, "utf8").trim() : null;
+  if (installed === shipped && existsSync(paths.walletBundlePath)) return true;
+  if (!pathIsExpected(paths)) {
+    log(`refusing to install the wallet runtime: unexpected target path ${paths.runtimeDir}`);
+    return false;
+  }
+  if (!shippedBundleMatchesDigest(paths, shipped, log)) return false;
+  const describe = (v) => {
+    if (!v) return "none";
+    const [nameVersion, hashLine = ""] = v.split("\n");
+    const short = hashLine.replace("sha256:", "").slice(0, 12);
+    return short ? `${nameVersion} (${short})` : nameVersion;
+  };
+  try {
+    mkdirSync(paths.homeDir, { recursive: true });
+    rmSync(paths.runtimeDir, { recursive: true, force: true });
+    cpSync(paths.shippedRuntimeDir, paths.runtimeDir, { recursive: true });
+    log(
+      installed ? `updated the wallet runtime: ${describe(installed)} -> ${describe(shipped)}` : `installed the wallet runtime ${describe(shipped)}`
+    );
+    return true;
+  } catch (e) {
+    log(`could not install the wallet runtime into ${paths.runtimeDir}: ${e.message}`);
+    return false;
+  }
+}
+function register(api) {
+  const paths = resolvePluginPaths(api.rootDir);
+  const log = (m) => {
+    const line = `zetrix-agentic-wallet: ${m}`;
+    if (api.logger?.info) api.logger.info(line);
+    else process.stderr.write(`${line}
+`);
+  };
+  const deps = makeDeps(paths, log);
+  if (!syncRuntime(paths, log)) {
+    log("the plugin is installed but cannot provide wallet tools");
+    return;
+  }
+  registerServer(deps, buildServerEntry(paths.walletBundlePath, api.pluginConfig ?? {}, paths.walletStateDir));
+}
+var index_default = { register };
+export {
+  index_default as default,
+  register
+};

package/dist/runtime/VERSION

@@ -0,0 +1,2 @@
+agentic-wallet-mcp@0.11.0
+sha256:38c12638ea7a325ce41aafe72486db87d67a25c5054f4b89e66bc0d1e4abd717