@oracle-agent/oracle 0.3.5 → 0.4.0

package/README.md

@@ -20,11 +20,11 @@ alongside it — same split we run ourselves.
 
 ## Start in 5 steps
 
-Latest: **oracle `0.3.1`** · **operator `0.6.1`**
+Latest: **oracle `0.3.6`** · **operator `0.6.1`**
 
 ```bash
 # 1) install both packages
-npm i @oracle-agent/oracle@0.3.1 @oracle-agent/operator@0.6.1
+npm i @oracle-agent/oracle@0.3.6 @oracle-agent/operator@0.6.1
 
 # 2) put keys ONLY on your machine (example: HL/EVM hex key file)
 mkdir -p ~/.config/oracle/keys && chmod 700 ~/.config/oracle/keys
@@ -161,12 +161,12 @@ oracle-scan risk  base 0x8335...2913  # structural checks + sell simulation
 oracle-scan sell  base 0x8335...2913  # round trip: can you actually exit?
 ```
 
-**7 of 11 chains ship verified venues** — Ethereum, Optimism, BNB, Polygon, Base,
-Arbitrum, Avalanche — so they have all 10 capabilities including live quotes,
-round-trip sell simulation, and unsigned swap preparation. The remaining four
-(Stable, HyperEVM, Abstract, Robinhood) are at 7 and **fail-closed for routing
-value** until someone verifies a venue: read and research work, moving money does
-not. That is a safe default, not a gap.
+**8 of 11 chains ship verified venues**: Ethereum, Optimism, BNB, Polygon, Base,
+Arbitrum, Avalanche, and Robinhood Chain. They have all 10 capabilities including
+live quotes, round-trip sell simulation, and unsigned swap preparation. The remaining
+three (Stable, HyperEVM, Abstract) are at 7 and **fail-closed for routing value** until
+someone verifies a venue: read and research work, moving money does not. That is a safe
+default, not a gap.
 
 Every venue address was verified **functionally, not by codesize** — a re-runnable
 prober (`scripts/verify-v3-venues.mjs`) asks each candidate to price a pair with a
@@ -199,10 +199,14 @@ Oracle's default pack is deliberately broad but disarmed:
 
 - **Trader** — best-execution route comparison, quote/prepare, simulation, and
   receipt checks; no set-and-forget custody.
-- **Builder** — protocol, NFT, gacha, DEX, and launchpad scaffolds with unsigned
-  deploy/admin transactions.
+- **Builder** - chain-family fungible-token and NFT-collection launch plans,
+  protocol, gacha, DEX, and launchpad scaffolds with unsigned deploy/admin actions.
+  Unsupported chain adapters fail closed instead of pretending one deploy fits all.
 - **Analyzer** — token, contract, venue, portfolio, market, and risk research with
-  evidence labels.
+  evidence labels. `/balance` or plain `balance` runs one deterministic snapshot
+  across every configured EVM chain plus Solana, Bitcoin, Hyperliquid, and
+  discoverable NFTs. Profile-local observations power history and SVG value graphs;
+  unavailable values stay null instead of becoming fake zeroes.
 - **On-chain scanner** — chain-config scanners for tokens, pools, launches,
   risk, exits, and smart-wallet boards.
 - **Meme-token sniper** — fast launch/liquidity monitoring across configured
@@ -253,6 +257,19 @@ owner-local source lane.** The short version:
 - User wallets authorize prepared actions outside the public data plane.
 - Owner-local signing is shipped separately as `@oracle-agent/operator`; its agent-facing daemon supports only policy-bounded Hyperliquid and Polymarket execution.
 
+### Action vocabulary and execution planes
+
+Oracle keeps capability and authorization separate:
+
+- Public Oracle reads, quotes, simulates, and prepares unsigned artifacts.
+- The generic unattended signer remains limited to `hl` and `poly`.
+- Ordinary EVM preparation remains user-wallet signed.
+- A deployment may separately install a same-host, owner-gated EVM executor. Oracle must verify that executor before describing bounded EVM execution as available. Missing deployment capability means "unavailable here," not "Oracle can never execute EVM."
+- `watch`, `watch this`, and `ping me` always create `active: true, actionMode: alert_only`.
+- `arm` creates `active: true, actionMode: execute` only for one exact owner-authorized action. It is never inferred from a watch.
+
+The package exports this binding as `@oracle-agent/oracle/action-semantics`. Legacy watch stores can migrate `status: watching|armed` with `migrateLegacyWatchRecord()`; because it is specifically a watch-store migration, both statuses become `alert_only`, never execution authority.
+
 Run the read-only data plane:
 
 ```bash
@@ -273,7 +290,8 @@ Oracle is a library. Drive it with Claude, GPT, Gemini, Grok, a local model, or
 a plain script — the tools are ordinary functions plus an MCP server:
 
 ```bash
-npx oracle-data-mcp     # works with any MCP client
+npx oracle-data         # local read plane on 127.0.0.1:8787
+npx oracle-data-mcp     # MCP stdio server (any MCP client); needs oracle-data up
 ```
 
 It is better under [Hermes](https://claude-code.nousresearch.com/docs), because
@@ -294,7 +312,9 @@ Oracle ships an installable 8-lane mesh for Hermes:
 
 ```bash
 oracle-init            # dry run -- shows exactly what it would do
-oracle-init --apply    # create profiles, install SOULs + skills, wire MCP
+oracle-init --apply    # create profiles, install SOULs + skills, wire MCP config
+npx oracle-data        # keep running — MCP tools call the local read plane on :8787
+hermes -p oracle chat  # router lane; inherits whatever model Hermes already uses
 ```
 
 Lanes: `oracle` (router), `polymarket-agent`, `hyperliquid-agent`,

package/SETUP.md

@@ -38,6 +38,30 @@ environment. The npm artifact excludes the key vault and live signer modules.
 Wallet signing, submission, receipt confirmation, and revocation happen outside
 that public surface.
 
+### Capability is not authorization
+
+The public Oracle profile must report these as separate planes:
+
+| Plane | Default capability |
+|---|---|
+| Public Oracle package | read, quote, simulate, unsigned prepare |
+| Generic `oracle-signer` daemon | policy-bounded `hl` and `poly` only |
+| Ordinary EVM | unsigned preparation, user-wallet signature |
+| Optional owner-gated EVM executor | one exact bounded action after explicit `arm` |
+
+The optional EVM executor is not bundled into this public package and must never be exposed over LAN or a tailnet. A profile may describe bounded EVM execution as available only after verifying that separate local executor and its owner gate. Otherwise say the current deployment is prepare-only. Do not claim EVM execution is universally impossible.
+
+Action records require explicit fields:
+
+```json
+{
+  "active": true,
+  "actionMode": "alert_only"
+}
+```
+
+`watch`, `watch this`, and `ping me` always use `alert_only`. `arm` uses `execute` only for one exact owner-authorized action. A legacy `status: armed` field is not execution authority.
+
 ---
 
 ## Source-only operator credentials
@@ -103,6 +127,39 @@ export BASE_RPC_URL=https://...
 export SOLANA_RPC_URL=https://...
 ```
 
+`/balance` and plain `balance` need only public addresses. Set any families the
+wallet uses, then start `oracle-data` from the same environment:
+
+```bash
+export ORACLE_EVM_ADDRESS=0x...
+export ORACLE_SOLANA_ADDRESS=...
+export ORACLE_BITCOIN_ADDRESS=bc1...
+export ORACLE_HYPERLIQUID_ADDRESS=0x...  # optional, defaults to EVM address
+npx oracle-data
+```
+
+Missing address families are reported as `not-configured`, failed providers as
+`unavailable`, and unsupported chain families as `unsupported`. They are never
+reported as zero. EVM native balances cover every configured EVM chain. Solana
+adds SPL and Token-2022 accounts, Bitcoin adds Runes and inscriptions when an
+address indexer is configured, Hyperliquid adds spot and perp account state, and
+NFT inventory adds OpenSea-supported EVM/Solana collections plus Bitcoin
+inscriptions where owner indexers are available.
+
+Every `portfolio_snapshot` call appends one compact observation to
+`$HERMES_HOME/state/oracle/portfolio-history.jsonl` with mode `0600`. It stores a
+public-address fingerprint, coverage, value breakdown, and warnings, not keys,
+prepared transactions, or raw NFT metadata. Override the internal location only
+when needed:
+
+```bash
+export ORACLE_PORTFOLIO_HISTORY_FILE="$HOME/.local/state/oracle/portfolio-history.jsonl"
+```
+
+`portfolio_history` reads those observations. `portfolio_value_graph` returns an
+SVG chart of known priced value and omits unavailable observations instead of
+plotting them as zero.
+
 ---
 
 ## Where keys are stored
@@ -202,7 +259,8 @@ Gemini, Grok, a local Llama, or your own script at it. The tools are plain
 functions and an MCP server.
 
 ```bash
-npx oracle-data-mcp     # MCP stdio server, works with any MCP client
+npx oracle-data         # local read plane on 127.0.0.1:8787
+npx oracle-data-mcp     # MCP stdio server, works with any MCP client (needs oracle-data up)
 ```
 
 **Why [Hermes](https://claude-code.nousresearch.com/docs) is the better host: per-profile routing.**

package/artifacts/specialist-packs/oracle-full-crypto.json

@@ -1,9 +1,9 @@
 {
   "id": "oracle-full-crypto",
   "name": "Oracle Full Crypto Pack",
-  "version": 1,
+  "version": 4,
   "audience": "public-users",
-  "description": "Default capability set for public Oracle: trader, builder, analyzer, multichain scanner, meme-token sniping, RFQ routing, tokenized-asset buys, NFT mint gas-war limits, Solana, Bitcoin inscriptions, NFT/gacha/DEX launches, and protocol build under bound grants. User signs everything.",
+  "description": "Default capability set for public Oracle: trader, builder, analyzer, deterministic /balance aggregation, multichain scanner, meme-token sniping, RFQ routing, tokenized-asset buys, NFT mint gas-war limits, Solana, Bitcoin inscriptions, chain-family token/NFT collections, gacha/DEX launches, and protocol build under bound grants. User signs everything.",
   "posture": {
     "default": "DISARMED",
     "custody": "self-custodial",
@@ -62,6 +62,8 @@
       "oracle-protocol-builder",
       "oracle-contract-research",
       "oracle-protocol-security",
+      "oracle-multichain-token-launch",
+      "oracle-multichain-nft-launch",
       "oracle-nft-gacha-launch",
       "oracle-dex-launch",
       "protocol-api-key-integration",
@@ -80,6 +82,8 @@
       "oracle-nft-gacha-launch",
       "oracle-dex-launch",
       "oracle-protocol-security",
+      "oracle-multichain-token-launch",
+      "oracle-multichain-nft-launch",
       "oracle-nft-mint-gas-war"
     ],
     "analysis": [
@@ -88,6 +92,7 @@
       "oracle-smart-wallet-scanner",
       "oracle-meme-token-sniper",
       "oracle-best-execution",
+      "balance",
       "oracle-chain-graphs-telegram-cards",
       "oracle-rfq-tokenized-assets"
     ]
@@ -109,7 +114,9 @@
       "write-deploy-scripts",
       "prepare-unsigned-deploy-txs",
       "security-checklist",
-      "launchpad-public-surface"
+      "launchpad-public-surface",
+      "multichain-token-launch",
+      "multichain-nft-collection-launch"
     ],
     "user_signs": true,
     "grant_actions_example": [
@@ -119,7 +126,7 @@
       "prepare:verify"
     ],
     "targets": "user-provided factory/router/implementations only unless added to destination allowlist",
-    "copy": "Oracle can design and prepare protocol, NFT/gacha, and DEX launches. You still sign. Grants bind chain, spend, and destinations."
+    "copy": "Oracle can classify and prepare chain-family token, NFT collection, protocol, gacha, and DEX launches. Unsupported adapters fail closed. You still sign every side effect."
   },
   "profiles": [
     {
@@ -201,10 +208,12 @@
         "oracle-protocol-security",
         "oracle-nft-gacha-launch",
         "oracle-dex-launch",
-        "oracle-receipts"
+        "oracle-receipts",
+        "oracle-multichain-token-launch",
+        "oracle-multichain-nft-launch"
       ],
       "label": "protocol builder",
-      "description": "Scaffold, review, and prepare deploys for NFT, gacha, DEX, and protocol launches."
+      "description": "Classify by chain family, then scaffold, review, and prepare unsigned token, NFT collection, gacha, DEX, and protocol launches."
     }
   ],
   "default_tools": {
@@ -216,7 +225,14 @@
       "btc_health",
       "btc_fees",
       "btc_inscription_info",
-      "solana_balance"
+      "solana_balance",
+      "portfolio_balance",
+      "portfolio_snapshot",
+      "portfolio_history",
+      "portfolio_value_graph",
+      "nft_inventory",
+      "nft_gallery",
+      "nft_pnl"
     ],
     "prepare": [
       "evm_prepare",
@@ -224,7 +240,8 @@
       "evm_protocol_quote",
       "jupiter_quote",
       "jupiter_prepare",
-      "bitcoin_inscribe_prepare"
+      "bitcoin_inscribe_prepare",
+      "nft_prepare_list"
     ],
     "never_public_default": [
       "evm_sign",
@@ -268,6 +285,11 @@
     "solana-nft-marketplace",
     "solana-nft-mint",
     "hypercore-hype-staking",
-    "hypercore-validator-delegation"
+    "hypercore-validator-delegation",
+    "multichain-token-launch",
+    "multichain-nft-collection-launch",
+    "multichain-balance",
+    "nft-inventory-gallery-pnl",
+    "portfolio-balance-history-graph"
   ]
 }

package/bin/oracle-data-mcp.mjs

@@ -2,15 +2,19 @@
 // Oracle data MCP — read-only multichain market/discovery plane.
 // Loaded by an Oracle/Hermes profile. Never expose signing or broadcast here.
 //
-// Every tool is a READ. No key, no signing, no broadcast. Routes to the Oracle
-// data server read plane (/data/call), which is unauthenticated on loopback.
+// Every tool is a READ or a prepared unsigned action. No key handling, signing,
+// or broadcast. Routes to the Oracle data server read/prepare plane (/data/call),
+// which is unauthenticated on loopback.
 // This is the "scan all public APIs" surface: DeFiLlama protocol TVL, DexScreener
 // token/search, LI.FI + Uniswap quotes, multi-chain RPC balances/blocks.
 //
 // Mirrors the Oracle exec MCP stdio JSON-RPC shape.
 
+import fs from "node:fs";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 import { env } from "../src/oracle-env.mjs";
+import { listAddresses, lookupAddress, rememberAddress, forgetAddress } from "../src/address-book.mjs";
 
 const DATA_URL = (env("ORACLE_DATA_URL", "MAD_DESK_URL", "http://127.0.0.1:8787")).replace(/\/$/, "");
 
@@ -96,6 +100,201 @@ const tools = [
       },
     },
   },
+  {
+    name: "portfolio_balance",
+    description:
+      "Read-only balance aggregation across every configured EVM chain plus Solana, Bitcoin, and Hyperliquid. Reports native assets, supported token/collectible reads, failed or missing providers, unverified assets, timestamps, and known priced value without pretending it is a complete total. Public addresses only; never signs or broadcasts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          description: "Optional public wallet addresses by family. Omit configured families to use ORACLE_*_ADDRESS defaults.",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        evmChainIds: {
+          type: "array",
+          items: { type: "number" },
+          description: "Optional EVM chain subset. Default is every configured EVM chain.",
+        },
+        includeTokens: { type: "boolean", description: "Include supported token reads. Default true." },
+        includeCollectibles: { type: "boolean", description: "Include supported collectible reads. Default true." },
+        includePrices: { type: "boolean", description: "Fetch current DeFiLlama native prices. Default true." },
+      },
+    },
+  },
+  {
+    name: "portfolio_snapshot",
+    description:
+      "Query the current multichain balance and NFT inventory, then append one compact profile-local observation for historical tracking. Stores public-address fingerprint, coverage, breakdown, and known priced value only; no keys, signatures, executable payloads, or raw NFT metadata. Returns the live balance, NFT result, and recorded snapshot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        evmChainIds: { type: "array", items: { type: "number" } },
+        includeTokens: { type: "boolean" },
+        includeCollectibles: { type: "boolean" },
+        includePrices: { type: "boolean" },
+        includeNfts: { type: "boolean", description: "Include provider-estimated NFT value. Default true." },
+      },
+    },
+  },
+  {
+    name: "portfolio_history",
+    description:
+      "Read profile-local portfolio observations in a time range. Unknown or unavailable values remain null and are never converted to zero. Defaults to the configured public-address portfolio fingerprint.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        portfolioId: { type: "string" },
+        allPortfolios: { type: "boolean", description: "Return observations for every public-address fingerprint in this profile." },
+        since: { type: "string", description: "Inclusive ISO 8601 lower bound." },
+        until: { type: "string", description: "Inclusive ISO 8601 upper bound." },
+        limit: { type: "number", description: "1-1000, default 100." },
+        order: { type: "string", enum: ["asc", "desc"] },
+      },
+    },
+  },
+  {
+    name: "portfolio_value_graph",
+    description:
+      "Render a static SVG line graph from profile-local portfolio snapshots. Plots known priced value only, labels incomplete coverage, includes provider-estimated NFT values when recorded, and omits unavailable observations instead of plotting fake zeroes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        portfolioId: { type: "string" },
+        allPortfolios: { type: "boolean" },
+        since: { type: "string" },
+        until: { type: "string" },
+        limit: { type: "number", description: "Historical observations to consider, max 1000." },
+        maxPoints: { type: "number", description: "Rendered point cap, 2-500, default 200." },
+      },
+    },
+  },
+  {
+    name: "nft_inventory",
+    description:
+      "Read all discoverable NFTs for configured EVM, Solana, and Bitcoin addresses. Returns normalized assets, image URLs, estimated values, per-chain partial failures, flagged/NSFW items separated from visible items, listing coverage, and explicit unsupported chains. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+          },
+        },
+        chains: { type: "array", items: { type: "string" }, description: "Optional chain slug subset." },
+        pageSize: { type: "number", description: "OpenSea items per page, max 200." },
+        maxPages: { type: "number", description: "Maximum pages per chain, max 25." },
+        bitcoinLimit: { type: "number" },
+        includePnl: { type: "boolean", description: "Include OpenSea-indexed account PnL when available. Default true." },
+        costBasis: { type: "object", description: "Optional user-supplied assetKey -> {costUsd,feesUsd,acquiredAt,source}. Missing basis stays unavailable, never zero." },
+      },
+    },
+  },
+  {
+    name: "nft_gallery",
+    description:
+      "Generate one static NFT contact-sheet image page from wallet inventory or supplied normalized items. External metadata is never rendered as HTML; only allowlisted JPEG/PNG/WebP bytes are embedded and unsafe or missing media becomes a placeholder.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: { evm: { type: "string" }, solana: { type: "string" }, bitcoin: { type: "string" } },
+        },
+        chains: { type: "array", items: { type: "string" } },
+        items: { type: "array", items: { type: "object" }, description: "Optional normalized inventory items. Omit to scan configured wallets." },
+        page: { type: "number", description: "1-based gallery page." },
+        pageSize: { type: "number", description: "1-12 items per page." },
+      },
+    },
+  },
+  {
+    name: "nft_pnl",
+    description:
+      "NFT PnL with explicit methodology. Returns OpenSea-indexed account-level PnL where available plus per-item unrealized estimates only when both user-supplied acquisition cost and provider estimated current value exist. Missing history is unavailable, never zero.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: { evm: { type: "string" }, solana: { type: "string" }, bitcoin: { type: "string" } },
+        },
+        chains: { type: "array", items: { type: "string" } },
+        costBasis: { type: "object" },
+      },
+    },
+  },
+  {
+    name: "nft_prepare_list",
+    description:
+      "Prepare an NFT listing for OpenSea EVM, Magic Eden Solana, or Satflow Bitcoin after explicit user review. Requires userConfirmed=true plus asset, marketplace, price, currency where applicable, and future expiry. Returns approval/signing actions, an unsigned Solana transaction, or an unsigned Bitcoin PSBT. Never signs, submits, or broadcasts.",
+    inputSchema: {
+      type: "object",
+      required: ["marketplace", "userConfirmed"],
+      properties: {
+        marketplace: { type: "string", enum: ["opensea", "magiceden", "magiceden-sol", "satflow"] },
+        userConfirmed: { type: "boolean" },
+        chain: { type: "string" },
+        seller: { type: "string" },
+        contract: { type: "string" },
+        tokenId: { type: "string" },
+        quantity: { type: "number" },
+        priceAmount: { type: "string" },
+        currency: { type: "string" },
+        endTime: { type: "string" },
+        useCreatorFee: { type: "boolean" },
+        taker: { type: "string" },
+        tokenMint: { type: "string" },
+        tokenATA: { type: "string" },
+        auctionHouse: { type: "string" },
+        priceSol: { type: "string" },
+        expiry: { description: "Future ISO 8601 timestamp or Unix seconds." },
+        inscriptionId: { type: "string" },
+        runesOutput: { type: "string" },
+        ordAddress: { type: "string" },
+        receiveAddress: { type: "string" },
+        priceSats: { type: "string" },
+        tapKey: { type: "string" },
+        collectionSlug: { type: "string" },
+      },
+    },
+  },
   {
     name: "rpc_balance",
     description:
@@ -341,6 +540,57 @@ const tools = [
       required: ["chainId", "address"],
     },
   },
+  {
+    name: "address_book_remember",
+    description:
+      "Remember a wallet address with a label. Call this whenever someone states their address " +
+      "or an agent/counterparty wallet is discovered, so it survives the conversation. " +
+      "Stores labels only — never private keys, seeds, or passphrases.",
+    inputSchema: {
+      type: "object",
+      required: ["address", "label"],
+      properties: {
+        address: { type: "string", description: "0x address" },
+        label: { type: "string", description: "short name, e.g. carlo-agent" },
+        who: { type: "string", description: "person or entity the wallet belongs to" },
+        role: { type: "string", description: "agent | owner | person | counterparty | venue" },
+        chainIds: { type: "array", items: { type: "number" } },
+        notes: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "address_book_list",
+    description:
+      "List remembered wallets (owner, agent, people, counterparties). Read-only. " +
+      "Check this before sending or bridging to a person.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "search across label, who, address, notes" },
+        role: { type: "string" },
+        who: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "address_book_lookup",
+    description: "Look up one 0x address in the durable address book. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" } },
+    },
+  },
+  {
+    name: "address_book_forget",
+    description: "Remove a remembered address, optionally only one label for it.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" }, label: { type: "string" } },
+    },
+  },
   {
     name: "best_swap_route",
     description:
@@ -464,6 +714,24 @@ const ROUTES = {
       fromAddress: a.fromAddress || DEFAULT_ADDRESS || undefined,
     },
   }),
+  portfolio_balance: (a) => ({
+    provider: "portfolio",
+    op: "balances",
+    args: {
+      addresses: a.addresses,
+      evmChainIds: a.evmChainIds,
+      includeTokens: a.includeTokens,
+      includeCollectibles: a.includeCollectibles,
+      includePrices: a.includePrices,
+    },
+  }),
+  portfolio_snapshot: (a) => ({ provider: "portfolio", op: "snapshot", args: a }),
+  portfolio_history: (a) => ({ provider: "portfolio", op: "history", args: a }),
+  portfolio_value_graph: (a) => ({ provider: "portfolio", op: "valueGraph", args: a }),
+  nft_inventory: (a) => ({ provider: "nft-portfolio", op: "inventory", args: a }),
+  nft_gallery: (a) => ({ provider: "nft-portfolio", op: "gallery", args: a }),
+  nft_pnl: (a) => ({ provider: "nft-portfolio", op: "pnl", args: a }),
+  nft_prepare_list: (a) => ({ provider: "nft-portfolio", op: "prepareList", args: a }),
   rpc_balance: (a) => {
     const addr = a.address || DEFAULT_ADDRESS;
     if (!addr) throw new Error("address required (set ORACLE_DEFAULT_ADDRESS to supply a default)");
@@ -601,6 +869,15 @@ async function callTool(name, args = {}) {
     const token = args.token ? await sc.tokenBalance(args.address, args.token).catch(() => null) : null;
     return { chainId: Number(args.chainId), address: args.address, native, token };
   }
+  if (name === "address_book_remember") {
+    return rememberAddress({
+      address: args.address, label: args.label, who: args.who,
+      role: args.role, chainIds: args.chainIds, notes: args.notes, source: "oracle-data-mcp",
+    });
+  }
+  if (name === "address_book_list") return listAddresses({ q: args.q, role: args.role, who: args.who });
+  if (name === "address_book_lookup") return lookupAddress(args.address);
+  if (name === "address_book_forget") return forgetAddress(args.address, args.label || null);
   if (name === "data_catalog") return httpJson(`${DATA_URL}/data/catalog`);
   if (name === "data_health") return httpJson(`${DATA_URL}/data/health`);
   if (name === "data_call") {
@@ -637,7 +914,21 @@ async function handle(request) {
   if (method === "tools/call") {
     try {
       const result = await callTool(params?.name, params?.arguments || {});
-      send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } });
+      if (result?.dataBase64 && /^image\/(?:svg\+xml|png|jpeg|webp)$/.test(String(result.mimeType || ""))) {
+        const { dataBase64, ...metadata } = result;
+        send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [
+              { type: "image", data: dataBase64, mimeType: result.mimeType },
+              { type: "text", text: JSON.stringify(metadata, null, 2) },
+            ],
+          },
+        });
+      } else {
+        send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } });
+      }
     } catch (err) {
       send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: err.message }] } });
     }
@@ -666,7 +957,20 @@ function startStdioLoop() {
   });
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+// npm bin wrappers are symlinks. Comparing import.meta.url to argv[1] as strings
+// fails for `npx oracle-data-mcp` / node_modules/.bin/oracle-data-mcp and the
+// process exits without ever starting the stdio loop (Hermes sees Connection closed).
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
   startStdioLoop();
 }