@vultisig/cli 0.15.0 → 0.15.4

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @vultisig/cli
 
+## 0.15.4
+
+### Patch Changes
+
+- [#276](https://github.com/vultisig/vultisig-sdk/pull/276) [`59382c1`](https://github.com/vultisig/vultisig-sdk/commit/59382c1859512fbd362962ede5e92b100d3a5921) Thanks [@rcoderdev](https://github.com/rcoderdev)! - feat(cli): structured machine-readable errors for agent ask, pipe, and executor
+  - `agent ask --json` failures include stable `code` with existing `error` string
+  - NDJSON pipe `error` events and failed `tool_result` lines include `code`
+  - executor `ActionResult` failures carry `AgentErrorCode`; SSE errors accept optional backend `code`
+  - document error codes in CLI README
+
+- Updated dependencies [[`59382c1`](https://github.com/vultisig/vultisig-sdk/commit/59382c1859512fbd362962ede5e92b100d3a5921)]:
+  - @vultisig/sdk@0.15.4
+  - @vultisig/rujira@10.0.0
+
+## 0.15.2
+
+### Patch Changes
+
+- [#263](https://github.com/vultisig/vultisig-sdk/pull/263) [`6585c38`](https://github.com/vultisig/vultisig-sdk/commit/6585c38431db063f600e133d1a23f84b7c19e934) Thanks [@rcoderdev](https://github.com/rcoderdev)! - fix(cli): align agent executor with backend payloads and harden action handling
+  - model `tx_ready` / non-streaming transaction payloads with `TxReadyPayload`
+  - optional `vultisig` on agent config for shared SDK state (e.g. address book)
+  - executor improvements (chain locks, calldata resolution, EVM gas refresh) and unit tests
+
+- Updated dependencies [[`6585c38`](https://github.com/vultisig/vultisig-sdk/commit/6585c38431db063f600e133d1a23f84b7c19e934)]:
+  - @vultisig/sdk@0.15.2
+  - @vultisig/rujira@10.0.0
+
 ## 0.15.0
 
 ### Patch Changes

package/README.md

@@ -658,7 +658,7 @@ explorer:https://etherscan.io/tx/0x9f8e7d6c...
   "session_id": "abc123-def456",
   "response": "Your ETH balance is 1.5 ETH ($3,750.00 USD).",
   "tool_calls": [
-    { "action": "getBalance", "success": true, "data": { "chain": "ethereum", "balance": "1.5" } }
+    { "action": "get_balances", "success": true, "data": { "balances": [{ "chain": "Ethereum", "symbol": "ETH", "amount": "1.5", "decimals": 18, "raw_amount": "1500000000000000000" }] } }
   ],
   "transactions": [
     { "hash": "0x9f8e7d6c...", "chain": "ethereum", "explorerUrl": "https://etherscan.io/tx/0x9f8e7d6c..." }
@@ -666,6 +666,36 @@ explorer:https://etherscan.io/tx/0x9f8e7d6c...
 }
 ```
 
+On failure, stdout is a single JSON object with both a human `error` string and a stable `code` (the `error` field is unchanged for older parsers):
+
+```json
+{ "error": "Agent backend unreachable at https://example.invalid", "code": "BACKEND_UNREACHABLE" }
+```
+
+Each entry in `tool_calls` may include `code` when `success` is false (same values as below).
+
+##### Error codes (`agent ask --json`, `--via-agent`, executor)
+
+Orchestrators should branch on `code`. The message in `error` / `message` stays human-readable and may change between releases.
+
+| Code | Typical meaning |
+|------|-----------------|
+| `BACKEND_UNREACHABLE` | Agent health check failed or backend not responding |
+| `AUTH_FAILED` | Auth/token failure, HTTP 401/403, or wrong vault password |
+| `VAULT_LOCKED` | Encrypted vault needs unlock (password) |
+| `PASSWORD_REQUIRED` | Password was not supplied when required (e.g. pipe mode or signing) |
+| `CONFIRMATION_REQUIRED` | User confirmation needed (pipe mode; message prefix `CONFIRMATION_REQUIRED:`) |
+| `ACTION_NOT_IMPLEMENTED` | Local executor does not implement this action type |
+| `INVALID_INPUT` | Bad parameters, unknown chain, malformed NDJSON input, etc. |
+| `NETWORK_ERROR` | RPC/fetch connectivity (includes many SDK `VaultError` network cases) |
+| `TIMEOUT` | Deadline exceeded, or abort where the message indicates a timeout |
+| `TRANSACTION_FAILED` | Build/broadcast/gas errors mapped from the SDK |
+| `SIGNING_FAILED` | MPC/signing failed |
+| `SESSION_NOT_INITIALIZED` | Internal session state error |
+| `UNKNOWN_ERROR` | Unclassified failure (default for opaque SSE `error` events). Plain `AbortError` without “timeout” in the message maps here. |
+
+SSE `error` events may optionally include a `code` field from the backend; if it matches one of the values above, it is passed through unchanged. Otherwise the CLI infers a code from the message.
+
 **Agent ask options:**
 - `--session <id>` - Continue an existing conversation
 - `--backend-url <url>` - Agent backend URL (default: https://abe.vultisig.com)
@@ -712,15 +742,13 @@ The pipe interface uses NDJSON (one JSON object per line) on stdin/stdout. Desig
 | `ready` | `vault, addresses` | Session initialized, addresses for all chains |
 | `session` | `id` | Conversation ID for resuming later |
 | `history` | `messages[]` | Previous messages when resuming a session |
-| `auth` | `status, error?` | Authentication result (`authenticated` or `failed`) |
-| `conversation` | `id` | Conversation created or resumed |
 | `text_delta` | `delta` | Streaming text chunk from the agent |
 | `tool_call` | `id, action, params?, status` | Action started (`running`) |
-| `tool_result` | `id, action, success, data?, error?` | Action completed |
+| `tool_result` | `id, action, success, data?, error?, code?` | Action completed (`code` when `success` is false) |
 | `tx_status` | `tx_hash, chain, status, explorer_url?` | Transaction broadcast/confirmed/failed |
 | `assistant` | `content` | Full assistant response |
 | `suggestions` | `suggestions[]` | Suggested follow-up actions |
-| `error` | `message` | Error (includes `PASSWORD_REQUIRED` and `CONFIRMATION_REQUIRED` signals) |
+| `error` | `message, code` | Error or control signal (`PASSWORD_REQUIRED`, `CONFIRMATION_REQUIRED: …`; always includes stable `code`) |
 | `done` | `{}` | Response cycle complete |
 
 **Example session:**
@@ -740,7 +768,7 @@ echo '{"type":"message","content":"What is my ETH balance?"}' | vultisig agent -
 {"type":"done"}
 ```
 
-When the agent needs a password mid-session (e.g. for signing), it emits `{"type":"error","message":"PASSWORD_REQUIRED"}`. Respond with `{"type":"password","password":"..."}` on stdin.
+When the agent needs a password mid-session (e.g. for signing), it emits `{"type":"error","message":"PASSWORD_REQUIRED","code":"PASSWORD_REQUIRED"}`. Respond with `{"type":"password","password":"..."}` on stdin.
 
 #### Session Management
 

package/dist/index.js

@@ -1452,7 +1452,7 @@ var init_formatUnits = __esm({
 // src/index.ts
 import "dotenv/config";
 import { promises as fs4 } from "node:fs";
-import { parseKeygenQR, Vultisig as Vultisig7 } from "@vultisig/sdk";
+import { parseKeygenQR, Vultisig as Vultisig6 } from "@vultisig/sdk";
 import chalk15 from "chalk";
 import { program } from "commander";
 import inquirer8 from "inquirer";
@@ -3934,7 +3934,12 @@ Address Book${options.chain ? ` (${options.chain})` : ""}:
 }
 
 // src/commands/rujira.ts
-import { getRoutesSummary, listEasyRoutes, RujiraClient, VultisigRujiraProvider } from "@vultisig/rujira";
+import {
+  getRoutesSummary,
+  listEasyRoutes,
+  RujiraClient,
+  VultisigRujiraProvider
+} from "@vultisig/rujira";
 async function createRujiraClient(ctx2, options = {}) {
   const vault = await ctx2.ensureActiveVault();
   const provider = new VultisigRujiraProvider(vault);
@@ -4221,6 +4226,122 @@ function displayDiscountTier(tierInfo) {
 import chalk9 from "chalk";
 import Table from "cli-table3";
 
+// src/agent/agentErrors.ts
+import { VaultError, VaultErrorCode, VaultImportError, VaultImportErrorCode } from "@vultisig/sdk";
+var AgentErrorCode = /* @__PURE__ */ ((AgentErrorCode3) => {
+  AgentErrorCode3["BACKEND_UNREACHABLE"] = "BACKEND_UNREACHABLE";
+  AgentErrorCode3["AUTH_FAILED"] = "AUTH_FAILED";
+  AgentErrorCode3["VAULT_LOCKED"] = "VAULT_LOCKED";
+  AgentErrorCode3["PASSWORD_REQUIRED"] = "PASSWORD_REQUIRED";
+  AgentErrorCode3["CONFIRMATION_REQUIRED"] = "CONFIRMATION_REQUIRED";
+  AgentErrorCode3["ACTION_NOT_IMPLEMENTED"] = "ACTION_NOT_IMPLEMENTED";
+  AgentErrorCode3["INVALID_INPUT"] = "INVALID_INPUT";
+  AgentErrorCode3["NETWORK_ERROR"] = "NETWORK_ERROR";
+  AgentErrorCode3["TIMEOUT"] = "TIMEOUT";
+  AgentErrorCode3["TRANSACTION_FAILED"] = "TRANSACTION_FAILED";
+  AgentErrorCode3["SIGNING_FAILED"] = "SIGNING_FAILED";
+  AgentErrorCode3["SESSION_NOT_INITIALIZED"] = "SESSION_NOT_INITIALIZED";
+  AgentErrorCode3["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+  return AgentErrorCode3;
+})(AgentErrorCode || {});
+var AGENT_ERROR_CODE_VALUES = new Set(Object.values(AgentErrorCode));
+function isAgentErrorCode(value) {
+  return AGENT_ERROR_CODE_VALUES.has(value);
+}
+function mapVaultError(err) {
+  if (err.code === VaultErrorCode.InvalidConfig && /failed to unlock vault/i.test(err.message)) {
+    return "AUTH_FAILED" /* AUTH_FAILED */;
+  }
+  switch (err.code) {
+    case VaultErrorCode.Timeout:
+      return "TIMEOUT" /* TIMEOUT */;
+    case VaultErrorCode.NetworkError:
+    case VaultErrorCode.BalanceFetchFailed:
+      return "NETWORK_ERROR" /* NETWORK_ERROR */;
+    case VaultErrorCode.SigningFailed:
+      return "SIGNING_FAILED" /* SIGNING_FAILED */;
+    case VaultErrorCode.BroadcastFailed:
+    case VaultErrorCode.GasEstimationFailed:
+      return "TRANSACTION_FAILED" /* TRANSACTION_FAILED */;
+    case VaultErrorCode.NotImplemented:
+      return "ACTION_NOT_IMPLEMENTED" /* ACTION_NOT_IMPLEMENTED */;
+    case VaultErrorCode.InvalidAmount:
+    case VaultErrorCode.UnsupportedChain:
+    case VaultErrorCode.UnsupportedToken:
+    case VaultErrorCode.ChainNotSupported:
+    case VaultErrorCode.InvalidVault:
+    case VaultErrorCode.InvalidPublicKey:
+    case VaultErrorCode.InvalidChainCode:
+    case VaultErrorCode.AddressDerivationFailed:
+      return "INVALID_INPUT" /* INVALID_INPUT */;
+    case VaultErrorCode.InvalidConfig:
+      return "INVALID_INPUT" /* INVALID_INPUT */;
+    default:
+      return "UNKNOWN_ERROR" /* UNKNOWN_ERROR */;
+  }
+}
+function mapVaultImportError(err) {
+  switch (err.code) {
+    case VaultImportErrorCode.PASSWORD_REQUIRED:
+      return "PASSWORD_REQUIRED" /* PASSWORD_REQUIRED */;
+    case VaultImportErrorCode.INVALID_PASSWORD:
+      return "AUTH_FAILED" /* AUTH_FAILED */;
+    default:
+      return "INVALID_INPUT" /* INVALID_INPUT */;
+  }
+}
+function networkishMessage(msg) {
+  return /ECONNREFUSED|ENOTFOUND|ETIMEDOUT|network|fetch failed|socket/i.test(msg) || /getaddrinfo|certificate|TLS|SSL/i.test(msg);
+}
+function inferAgentErrorCodeFromMessage(message) {
+  const m = message.trim();
+  if (!m) return "UNKNOWN_ERROR" /* UNKNOWN_ERROR */;
+  if (/agent backend unreachable/i.test(m)) return "BACKEND_UNREACHABLE" /* BACKEND_UNREACHABLE */;
+  if (/authentication failed|^auth failed/i.test(m)) return "AUTH_FAILED" /* AUTH_FAILED */;
+  if (m === "PASSWORD_REQUIRED") return "PASSWORD_REQUIRED" /* PASSWORD_REQUIRED */;
+  if (/^CONFIRMATION_REQUIRED:/i.test(m)) return "CONFIRMATION_REQUIRED" /* CONFIRMATION_REQUIRED */;
+  if (/password required|password not provided|use --password/i.test(m)) return "PASSWORD_REQUIRED" /* PASSWORD_REQUIRED */;
+  if (/session not initialized/i.test(m)) return "SESSION_NOT_INITIALIZED" /* SESSION_NOT_INITIALIZED */;
+  if (/not implemented locally|is not yet implemented|is not implemented locally|action type .*not implemented/i.test(m)) {
+    return "ACTION_NOT_IMPLEMENTED" /* ACTION_NOT_IMPLEMENTED */;
+  }
+  if (/\(401\)|\(403\)|\b401\b|\b403\b|unauthorized|forbidden/i.test(m)) return "AUTH_FAILED" /* AUTH_FAILED */;
+  if (/failed to unlock vault/i.test(m)) return "AUTH_FAILED" /* AUTH_FAILED */;
+  if (/vault.*locked|must unlock|unlock.*vault/i.test(m)) return "VAULT_LOCKED" /* VAULT_LOCKED */;
+  if (/timed out|timeout/i.test(m)) return "TIMEOUT" /* TIMEOUT */;
+  if (networkishMessage(m)) return "NETWORK_ERROR" /* NETWORK_ERROR */;
+  if (/unknown chain|unknown from_chain|unknown to_chain/i.test(m) || /\bis required\b|\bmissing\b|\brequires\b/i.test(m) || /no pending transaction|invalid or empty tx|could not stage calldata|server transaction missing/i.test(m) || /build_custom_tx requires|incomplete for a contract call|invalid der:/i.test(m)) {
+    return "INVALID_INPUT" /* INVALID_INPUT */;
+  }
+  return "UNKNOWN_ERROR" /* UNKNOWN_ERROR */;
+}
+function nodeErrCode(err) {
+  if (err && typeof err === "object" && "code" in err && typeof err.code === "string") {
+    return err.code;
+  }
+  return void 0;
+}
+function normalizeAgentError(err) {
+  if (err instanceof VaultError) {
+    return { code: mapVaultError(err), message: err.message };
+  }
+  if (err instanceof VaultImportError) {
+    return { code: mapVaultImportError(err), message: err.message };
+  }
+  const name = err instanceof Error ? err.name : "";
+  if (name === "AbortError") {
+    const message2 = err instanceof Error ? err.message : "Aborted";
+    const code = /timed out|timeout/i.test(message2) ? "TIMEOUT" /* TIMEOUT */ : "UNKNOWN_ERROR" /* UNKNOWN_ERROR */;
+    return { code, message: message2 };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const nc = nodeErrCode(err);
+  if (nc === "ECONNREFUSED" || nc === "ENOTFOUND" || nc === "ETIMEDOUT") {
+    return { code: "NETWORK_ERROR" /* NETWORK_ERROR */, message };
+  }
+  return { code: inferAgentErrorCodeFromMessage(message), message };
+}
+
 // src/agent/ask.ts
 var AskInterface = class {
   session;
@@ -4247,10 +4368,10 @@ var AskInterface = class {
 `);
         }
       },
-      onToolResult: (_id, action, success2, data, error2) => {
-        this.toolCalls.push({ action, success: success2, data, error: error2 });
+      onToolResult: (_id, action, success2, data, error2, code) => {
+        this.toolCalls.push({ action, success: success2, data, error: error2, code });
         if (this.verbose) {
-          const status = success2 ? "ok" : `error: ${error2}`;
+          const status = success2 ? "ok" : `error: ${error2}${code ? ` [${code}]` : ""}`;
           process.stderr.write(`[tool] ${action}: ${status}
 `);
         }
@@ -4269,8 +4390,8 @@ var AskInterface = class {
 `);
         }
       },
-      onError: (message) => {
-        process.stderr.write(`[error] ${message}
+      onError: (message, code) => {
+        process.stderr.write(`[error] ${message} [${code}]
 `);
       },
       onDone: () => {
@@ -4401,6 +4522,17 @@ function padTo32Bytes(buf) {
 }
 
 // src/agent/client.ts
+function sseErrorToMessage(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+  if (value instanceof Error) return value.message;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
 var AgentClient = class {
   baseUrl;
   authToken = null;
@@ -4455,7 +4587,9 @@ var AgentClient = class {
     return this.post(`/agent/conversations/${conversationId}`, req);
   }
   async deleteConversation(conversationId, publicKey) {
-    await this.delete(`/agent/conversations/${conversationId}`, { public_key: publicKey });
+    await this.delete(`/agent/conversations/${conversationId}`, {
+      public_key: publicKey
+    });
   }
   // ============================================================================
   // Messages - JSON mode
@@ -4566,16 +4700,22 @@ var AgentClient = class {
         case "tx_ready":
           if (this.verbose) process.stderr.write(`[SSE:tx_ready] raw: ${data.slice(0, 2e3)}
 `);
-          result.transactions.push(parsed);
-          callbacks.onTxReady?.(parsed);
+          {
+            const txReady = parsed;
+            result.transactions.push(txReady);
+            callbacks.onTxReady?.(txReady);
+          }
           break;
         case "message":
           result.message = parsed.message || parsed;
           callbacks.onMessage?.(result.message);
           break;
-        case "error":
-          callbacks.onError?.(parsed.error);
+        case "error": {
+          const msg = sseErrorToMessage(parsed.error);
+          const codeFromBackend = typeof parsed.code === "string" && isAgentErrorCode(parsed.code) ? parsed.code : inferAgentErrorCodeFromMessage(msg);
+          callbacks.onError?.(msg, codeFromBackend);
           break;
+        }
         case "done":
           break;
       }
@@ -4782,7 +4922,7 @@ function getNativeTokenDecimals(chain) {
 }
 
 // src/agent/executor.ts
-import { Chain as Chain9, Vultisig as Vultisig6 } from "@vultisig/sdk";
+import { Chain as Chain9, evmCall, fiatCurrencies as fiatCurrencies3, Vultisig as VultisigSdk } from "@vultisig/sdk";
 
 // node_modules/viem/_esm/index.js
 init_formatUnits();
@@ -4999,6 +5139,8 @@ var EVM_GAS_RPC = {
 };
 var AgentExecutor = class {
   vault;
+  /** Owning SDK (optional); used for address book backed by app storage */
+  vultisig;
   pendingPayloads = /* @__PURE__ */ new Map();
   password = null;
   verbose;
@@ -5007,9 +5149,10 @@ var AgentExecutor = class {
   chainLockReleases = /* @__PURE__ */ new Map();
   /** Backend client for resolving calldata_id references. */
   backendClient = null;
-  constructor(vault, verbose = false, vaultId) {
+  constructor(vault, verbose = false, vaultId, vultisig) {
     this.vault = vault;
     this.verbose = verbose;
+    this.vultisig = vultisig;
     if (vaultId) {
       this.stateStore = new VaultStateStore(vaultId);
     }
@@ -5023,6 +5166,8 @@ var AgentExecutor = class {
   /**
    * Store a server-built transaction (from tx_ready SSE event).
    * This allows sign_tx to find and sign it when the backend requests signing.
+   *
+   * @returns true when a signable payload was stored; false for MCP errors or missing tx body
    */
   storeServerTransaction(txReadyData) {
     if (this.verbose)
@@ -5030,11 +5175,17 @@ var AgentExecutor = class {
         `[executor] storeServerTransaction called, keys: ${Object.keys(txReadyData || {}).join(",")}
 `
       );
-    const swapTx = txReadyData.swap_tx || txReadyData.send_tx || txReadyData.tx;
-    if (!swapTx) {
+    const nestedTx = txReadyData?.swap_tx || txReadyData?.send_tx || txReadyData?.tx;
+    if (nestedTx?.status === "error" || nestedTx?.error) {
+      if (this.verbose)
+        process.stderr.write(`[executor] skipping error tx_ready: ${nestedTx.error || "unknown error"}
+`);
+      return false;
+    }
+    if (!nestedTx) {
       if (this.verbose) process.stderr.write(`[executor] storeServerTransaction: no swap_tx/send_tx/tx found in data
 `);
-      return;
+      return false;
     }
     const chain = resolveChainFromTxReady(txReadyData) || Chain9.Ethereum;
     this.pendingPayloads.clear();
@@ -5049,6 +5200,7 @@ var AgentExecutor = class {
         `[executor] Stored server tx for chain ${chain}, pendingPayloads size=${this.pendingPayloads.size}
 `
       );
+    return true;
   }
   hasPendingTransaction() {
     return this.pendingPayloads.has("latest");
@@ -5072,11 +5224,13 @@ var AgentExecutor = class {
         data
       };
     } catch (err) {
+      const { code, message } = normalizeAgentError(err);
       return {
         action: action.type,
         action_id: action.id,
         success: false,
-        error: err.message || String(err)
+        error: message,
+        code
       };
     }
   }
@@ -5107,7 +5261,7 @@ var AgentExecutor = class {
       case "sign_tx":
         return this.signTx(params);
       case "get_address_book":
-        return this.getAddressBook();
+        return this.getAddressBook(params);
       case "address_book_add":
         return this.addAddressBookEntry(params);
       case "address_book_remove":
@@ -5153,15 +5307,34 @@ var AgentExecutor = class {
     }
     return { balances: entries };
   }
-  async getPortfolio(_params) {
-    const balanceRecord = await this.vault.balances();
-    const entries = Object.entries(balanceRecord).map(([key, b]) => ({
-      chain: b.chainId || key.split(":")[0] || "",
+  async getPortfolio(params) {
+    const currencyRaw = String(params.currency ?? "USD").trim().toLowerCase();
+    const fiatCurrency = fiatCurrencies3.includes(currencyRaw) ? currencyRaw : "usd";
+    const portfolio = await this.vault.portfolio(fiatCurrency);
+    const chainFilter = params.chain;
+    const tickerFilter = params.ticker;
+    let rows = portfolio.balances.map((b) => ({
+      chain: b.chainId || "",
       symbol: b.symbol || "",
       amount: b.formattedAmount || b.amount?.toString() || "0",
-      decimals: b.decimals || 18
+      decimals: b.decimals ?? 18,
+      raw_amount: b.amount,
+      fiatValue: b.fiatValue,
+      fiatCurrency: b.fiatCurrency ?? portfolio.currency
     }));
-    return { balances: entries };
+    if (chainFilter) {
+      const chain = resolveChain(chainFilter);
+      if (!chain) throw new Error(`Unknown chain: ${chainFilter}`);
+      rows = rows.filter((r) => r.chain.toLowerCase() === chain.toLowerCase());
+    }
+    if (tickerFilter) {
+      rows = rows.filter((r) => r.symbol.toLowerCase() === String(tickerFilter).toLowerCase());
+    }
+    return {
+      balances: rows,
+      totalValue: portfolio.totalValue,
+      currency: portfolio.currency
+    };
   }
   // ============================================================================
   // Chain & Token Management
@@ -5261,13 +5434,28 @@ var AgentExecutor = class {
       };
       const amount = parseAmount(amountStr, balance.decimals);
       const memo = params.memo;
-      const payload = await this.vault.prepareSendTx({ coin, receiver: toAddress, amount, memo });
+      const payload = await this.vault.prepareSendTx({
+        coin,
+        receiver: toAddress,
+        amount,
+        memo
+      });
       await this.patchEvmNonce(chain, payload);
       const messageHashes = await this.vault.extractMessageHashes(payload);
       this.pendingPayloads.clear();
       const payloadId = `tx_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-      this.pendingPayloads.set(payloadId, { payload, coin, chain, timestamp: Date.now() });
-      this.pendingPayloads.set("latest", { payload, coin, chain, timestamp: Date.now() });
+      this.pendingPayloads.set(payloadId, {
+        payload,
+        coin,
+        chain,
+        timestamp: Date.now()
+      });
+      this.pendingPayloads.set("latest", {
+        payload,
+        coin,
+        chain,
+        timestamp: Date.now()
+      });
       return {
         keysign_payload: payloadId,
         from_chain: chain.toString(),
@@ -5307,7 +5495,10 @@ var AgentExecutor = class {
       const fromToken = params.from_contract || params.from_token_id;
       const toToken = params.to_contract || params.to_token_id;
       const fromCoin = { chain: fromChain, token: fromToken || void 0 };
-      const toCoin = { chain: toChain || fromChain, token: toToken || void 0 };
+      const toCoin = {
+        chain: toChain || fromChain,
+        token: toToken || void 0
+      };
       const quote = await this.vault.getSwapQuote({
         fromCoin,
         toCoin,
@@ -5377,11 +5568,14 @@ var AgentExecutor = class {
         chain: params.chain,
         chain_id: params.chain_id
       };
-      this.storeServerTransaction({
+      const stored = this.storeServerTransaction({
         tx: txData,
         chain: params.chain,
         from_chain: params.chain
       });
+      if (!stored) {
+        throw new Error("Could not stage calldata transaction for signing (invalid or empty tx payload)");
+      }
       const chain = resolveChain(params.chain) || Chain9.Ethereum;
       const address = await this.vault.address(chain);
       return {
@@ -5454,9 +5648,10 @@ var AgentExecutor = class {
     }
     const { payload, chain } = stored;
     if (payload.__serverTx) {
+      let result;
       if (chain === "Solana" && (payload.swap_tx || payload.provider)) {
         try {
-          return await this.buildAndSignSolanaSwapLocally(payload);
+          result = await this.buildAndSignSolanaSwapLocally(payload);
         } catch (e) {
           if (e._phase === "prepare") {
             if (this.verbose)
@@ -5467,7 +5662,9 @@ var AgentExecutor = class {
           }
         }
       }
-      return this.signServerTx(payload, chain, params);
+      if (!result) result = await this.signServerTx(payload, chain, params);
+      if (payload.sequence_id) result.sequence_id = payload.sequence_id;
+      return result;
     }
     return this.signSdkTx(payload, chain, payloadId);
   }
@@ -5503,7 +5700,7 @@ var AgentExecutor = class {
       }
       await this.releaseEvmLock(chain);
       this.pendingPayloads.clear();
-      const explorerUrl = Vultisig6.getTxExplorerUrl(chain, txHash);
+      const explorerUrl = VultisigSdk.getTxExplorerUrl(chain, txHash);
       return {
         tx_hash: txHash,
         chain: chain.toString(),
@@ -5600,7 +5797,7 @@ var AgentExecutor = class {
       }
       await this.releaseEvmLock(chain);
       this.pendingPayloads.clear();
-      const explorerUrl = Vultisig6.getTxExplorerUrl(chain, txHash);
+      const explorerUrl = VultisigSdk.getTxExplorerUrl(chain, txHash);
       return {
         tx_hash: txHash,
         chain: chain.toString(),
@@ -5625,9 +5822,15 @@ var AgentExecutor = class {
     const fromChainName = serverTxData.from_chain || serverTxData.chain || "Solana";
     const toChainName = serverTxData.to_chain;
     const fromChain = resolveChain(fromChainName);
-    if (!fromChain) throw Object.assign(new Error(`Unknown from_chain: ${fromChainName}`), { _phase: "prepare" });
+    if (!fromChain)
+      throw Object.assign(new Error(`Unknown from_chain: ${fromChainName}`), {
+        _phase: "prepare"
+      });
     const toChain = toChainName ? resolveChain(toChainName) : fromChain;
-    if (!toChain) throw Object.assign(new Error(`Unknown to_chain: ${toChainName}`), { _phase: "prepare" });
+    if (!toChain)
+      throw Object.assign(new Error(`Unknown to_chain: ${toChainName}`), {
+        _phase: "prepare"
+      });
     const amountStr = serverTxData.amount;
     if (!amountStr)
       throw Object.assign(new Error("Missing amount in tx_ready data for local Solana swap build"), {
@@ -5694,7 +5897,7 @@ var AgentExecutor = class {
       signature
     });
     this.pendingPayloads.clear();
-    const explorerUrl = Vultisig6.getTxExplorerUrl(chain, txHash);
+    const explorerUrl = VultisigSdk.getTxExplorerUrl(chain, txHash);
     return {
       tx_hash: txHash,
       chain: chain.toString(),
@@ -5942,8 +6145,18 @@ var AgentExecutor = class {
   // ============================================================================
   // Address Book
   // ============================================================================
-  async getAddressBook() {
-    throw new Error("get_address_book is not yet implemented locally. The backend may handle this action server-side.");
+  async getAddressBook(params) {
+    if (!this.vultisig) {
+      throw new Error(
+        "get_address_book requires the CLI SDK instance. Ensure AgentConfig.vultisig is set when creating the session."
+      );
+    }
+    const chainName = params.chain || params.chain_name;
+    const chain = chainName ? resolveChain(chainName) : void 0;
+    if (chainName && !chain) {
+      throw new Error(`Unknown chain: ${chainName}`);
+    }
+    return await this.vultisig.getAddressBook(chain);
   }
   async addAddressBookEntry(_params) {
     throw new Error("address_book_add is not yet implemented locally. The backend may handle this action server-side.");
@@ -5956,8 +6169,34 @@ var AgentExecutor = class {
   // ============================================================================
   // Token Search & Other
   // ============================================================================
-  async searchToken(_params) {
-    throw new Error("search_token is not yet implemented locally. The backend may handle this action server-side.");
+  async searchToken(params) {
+    const query = String(params.query ?? params.q ?? "").trim().toLowerCase();
+    if (!query) {
+      return { tokens: [] };
+    }
+    const limit = 20;
+    const chainName = params.chain;
+    const tokenMatchesQuery = (t) => {
+      const tick = t.ticker.toLowerCase();
+      const addr = (t.contractAddress ?? "").toLowerCase();
+      const pid = (t.priceProviderId ?? "").toLowerCase();
+      return tick.includes(query) || addr.includes(query) || pid.includes(query);
+    };
+    if (chainName) {
+      const chain = resolveChain(chainName);
+      if (!chain) throw new Error(`Unknown chain: ${chainName}`);
+      const tokens = VultisigSdk.getKnownTokens(chain).filter(tokenMatchesQuery).slice(0, limit);
+      return { tokens };
+    }
+    const out = [];
+    for (const c of Object.values(Chain9)) {
+      for (const t of VultisigSdk.getKnownTokens(c)) {
+        if (!tokenMatchesQuery(t)) continue;
+        out.push(t);
+        if (out.length >= limit) return { tokens: out };
+      }
+    }
+    return { tokens: out };
   }
   async listVaults() {
     return {
@@ -5974,8 +6213,25 @@ var AgentExecutor = class {
   async scanTx(_params) {
     throw new Error("scan_tx is not yet implemented locally. The backend may handle this action server-side.");
   }
-  async readEvmContract(_params) {
-    throw new Error("read_evm_contract is not yet implemented locally. The backend may handle this action server-side.");
+  async readEvmContract(params) {
+    const chainName = params.chain;
+    if (!chainName) throw new Error("read_evm_contract requires chain");
+    const contractRaw = params.contract_address || params.contractAddress;
+    if (!contractRaw) throw new Error("read_evm_contract requires contract_address");
+    const functionName = params.function_name || params.functionName;
+    if (!functionName) throw new Error("read_evm_contract requires function_name");
+    const chain = resolveChain(chainName);
+    if (!chain) throw new Error(`Unknown chain: ${chainName}`);
+    if (!EVM_CHAINS.has(chain)) {
+      throw new Error(`read_evm_contract only supports EVM chains (got ${chain})`);
+    }
+    const callParams = params.params ?? [];
+    const data = await encodeContractCall(functionName, callParams);
+    const addr = contractRaw.startsWith("0x") ? contractRaw : `0x${contractRaw}`;
+    const to = addr;
+    const from = params.from;
+    const result = await evmCall(chain, { to, data, from });
+    return { result };
   }
 };
 async function encodeContractCall(functionName, params) {
@@ -6249,7 +6505,10 @@ function parseDERSignature(sigHex) {
   }
   let offset = 0;
   if (raw.slice(offset, offset + 2) !== "30") {
-    return { r: raw.slice(0, 64).padStart(64, "0"), s: raw.slice(64).padStart(64, "0") };
+    return {
+      r: raw.slice(0, 64).padStart(64, "0"),
+      s: raw.slice(64).padStart(64, "0")
+    };
   }
   offset += 2;
   offset += 2;
@@ -6324,7 +6583,12 @@ var PipeInterface = class {
             const cmd = JSON.parse(nextLine);
             await this.handleCommand(cmd);
           } catch (err) {
-            this.emit({ type: "error", message: `Invalid input: ${err.message}` });
+            const { message, code } = normalizeAgentError(err);
+            this.emit({
+              type: "error",
+              message: `Invalid input: ${message}`,
+              code: code === "UNKNOWN_ERROR" /* UNKNOWN_ERROR */ ? "INVALID_INPUT" /* INVALID_INPUT */ : code
+            });
           }
         }
         processing = false;
@@ -6365,8 +6629,16 @@ var PipeInterface = class {
       onToolCall: (id, action, params) => {
         this.emit({ type: "tool_call", id, action, params, status: "running" });
       },
-      onToolResult: (id, action, success2, data, error2) => {
-        this.emit({ type: "tool_result", id, action, success: success2, data, error: error2 });
+      onToolResult: (id, action, success2, data, error2, code) => {
+        this.emit({
+          type: "tool_result",
+          id,
+          action,
+          success: success2,
+          data,
+          error: error2,
+          ...!success2 && code ? { code } : {}
+        });
       },
       onAssistantMessage: (content) => {
         this.emit({ type: "assistant", content });
@@ -6383,8 +6655,8 @@ var PipeInterface = class {
           explorer_url: explorerUrl
         });
       },
-      onError: (message) => {
-        this.emit({ type: "error", message });
+      onError: (message, code) => {
+        this.emit({ type: "error", message, code });
       },
       onDone: () => {
         this.emit({ type: "done" });
@@ -6392,13 +6664,17 @@ var PipeInterface = class {
       requestPassword: async () => {
         return new Promise((resolve) => {
           this.pendingPasswordResolve = resolve;
-          this.emit({ type: "error", message: "PASSWORD_REQUIRED" });
+          this.emit({ type: "error", message: "PASSWORD_REQUIRED", code: "PASSWORD_REQUIRED" /* PASSWORD_REQUIRED */ });
         });
       },
       requestConfirmation: async (message) => {
         return new Promise((resolve) => {
           this.pendingConfirmResolve = resolve;
-          this.emit({ type: "error", message: `CONFIRMATION_REQUIRED: ${message}` });
+          this.emit({
+            type: "error",
+            message: `CONFIRMATION_REQUIRED: ${message}`,
+            code: "CONFIRMATION_REQUIRED" /* CONFIRMATION_REQUIRED */
+          });
         });
       }
     };
@@ -6410,7 +6686,8 @@ var PipeInterface = class {
         try {
           await this.session.sendMessage(cmd.content, callbacks);
         } catch (err) {
-          this.emit({ type: "error", message: err.message });
+          const { message, code } = normalizeAgentError(err);
+          this.emit({ type: "error", message, code });
           this.emit({ type: "done" });
         }
         break;
@@ -6430,7 +6707,11 @@ var PipeInterface = class {
         break;
       }
       default:
-        this.emit({ type: "error", message: `Unknown command type: ${cmd.type}` });
+        this.emit({
+          type: "error",
+          message: `Unknown command type: ${cmd.type}`,
+          code: "INVALID_INPUT" /* INVALID_INPUT */
+        });
     }
   }
   emit(event) {
@@ -6459,7 +6740,7 @@ var AgentSession = class {
     this.config = config;
     this.client = new AgentClient(config.backendUrl);
     this.client.verbose = !!config.verbose;
-    this.executor = new AgentExecutor(vault, !!config.verbose, vault.publicKeys.ecdsa);
+    this.executor = new AgentExecutor(vault, !!config.verbose, vault.publicKeys.ecdsa, config.vultisig);
     this.publicKey = vault.publicKeys.ecdsa;
     if (config.password) {
       this.executor.setPassword(config.password);
@@ -6613,9 +6894,11 @@ var AgentSession = class {
         action_id: result.action_id,
         success: result.success,
         data: result.data || {},
-        error: result.error || ""
+        error: result.error || "",
+        ...!result.success && result.code ? { code: result.code } : {}
       };
     }
+    let serverTxStoredFromStream = 0;
     const streamResult = await this.client.sendMessageStream(
       this.conversationId,
       request,
@@ -6636,36 +6919,25 @@ var AgentSession = class {
           ui.onSuggestions(suggestions);
         },
         onTxReady: (tx) => {
-          const txData = tx?.swap_tx || tx?.send_tx || tx?.tx;
-          if (txData?.status === "error" || txData?.error) {
-            if (this.config.verbose)
-              process.stderr.write(`[session] skipping error tx_ready: ${txData.error || "unknown error"}
-`);
-            return;
-          }
-          this.executor.storeServerTransaction(tx);
-          if (this.config.password) {
-            this.executor.setPassword(this.config.password);
+          if (this.executor.storeServerTransaction(tx)) {
+            serverTxStoredFromStream++;
+            if (this.config.password) {
+              this.executor.setPassword(this.config.password);
+            }
           }
         },
         onMessage: (_msg) => {
         },
-        onError: (error2) => {
-          ui.onError(error2);
+        onError: (error2, code) => {
+          ui.onError(error2, code);
         }
       },
       this.abortController?.signal
     );
     const responseText = streamResult.message?.content || streamResult.fullText || "";
-    const inlineActions = parseInlineToolCalls(responseText);
-    if (inlineActions.length > 0) {
-      const cleanText = responseText.replace(/<invoke\s+name="[^"]*">[\s\S]*?<\/invoke>/g, "").replace(/<\/?minimax:tool_call>/g, "").trim();
-      if (cleanText) {
-        ui.onAssistantMessage(cleanText);
-      }
-      streamResult.actions.push(...inlineActions);
-    } else if (responseText) {
-      ui.onAssistantMessage(responseText);
+    const displayText = stripLeakedToolCallTags(responseText);
+    if (displayText) {
+      ui.onAssistantMessage(displayText);
     }
     const actions = streamResult.actions.filter((a) => a.type !== "sign_tx");
     if (actions.length > 0) {
@@ -6696,10 +6968,12 @@ var AgentSession = class {
         return;
       }
     }
-    if (streamResult.transactions.length > 0 && this.executor.hasPendingTransaction()) {
+    if (serverTxStoredFromStream > 0) {
       if (this.config.verbose)
-        process.stderr.write(`[session] ${streamResult.transactions.length} tx_ready events, signing client-side
-`);
+        process.stderr.write(
+          `[session] ${serverTxStoredFromStream} stored server tx from tx_ready, signing client-side
+`
+        );
       const signAction = {
         id: `tx_sign_${Date.now()}`,
         type: "sign_tx",
@@ -6737,7 +7011,8 @@ var AgentSession = class {
               action: action.type,
               action_id: action.id,
               success: false,
-              error: "Password not provided"
+              error: "Password not provided",
+              code: "PASSWORD_REQUIRED" /* PASSWORD_REQUIRED */
             });
             continue;
           }
@@ -6746,7 +7021,7 @@ var AgentSession = class {
       ui.onToolCall(action.id, action.type, action.params);
       const result = await this.executor.executeAction(action);
       results.push(result);
-      ui.onToolResult(action.id, action.type, result.success, result.data, result.error);
+      ui.onToolResult(action.id, action.type, result.success, result.data, result.error, result.code);
       if (action.type === "sign_tx" && result.success && result.data) {
         const txHash = result.data.tx_hash;
         const chain = result.data.chain;
@@ -6776,34 +7051,12 @@ var AgentSession = class {
     this.historyMessages = [];
   }
 };
-function parseInlineToolCalls(text) {
-  const actions = [];
-  const invokeRegex = /<invoke\s+name="([^"]+)">([\s\S]*?)<\/invoke>/g;
-  let match;
-  while ((match = invokeRegex.exec(text)) !== null) {
-    const actionType = match[1];
-    const body = match[2];
-    const params = {};
-    const paramRegex = /<parameter\s+name="([^"]+)">([\s\S]*?)<\/parameter>/g;
-    let paramMatch;
-    while ((paramMatch = paramRegex.exec(body)) !== null) {
-      const key = paramMatch[1];
-      const value = paramMatch[2];
-      try {
-        params[key] = JSON.parse(value);
-      } catch {
-        params[key] = value;
-      }
-    }
-    actions.push({
-      id: `inline_${actionType}_${Date.now()}`,
-      type: actionType,
-      title: actionType,
-      params,
-      auto_execute: true
-    });
+function stripLeakedToolCallTags(text) {
+  if (!text) return "";
+  if (!/<invoke\s+name="[^"]*">/.test(text) && !text.includes("minimax:tool_call")) {
+    return text;
   }
-  return actions;
+  return text.replace(/<invoke\s+name="[^"]*">[\s\S]*?<\/invoke>/g, "").replace(/<\/?minimax:tool_call>/g, "").replace(/\n{3,}/g, "\n\n").trim();
 }
 function getTokenCachePath() {
   const dir = process.env.VULTISIG_CONFIG_DIR ?? join2(homedir2(), ".vultisig");
@@ -6979,7 +7232,7 @@ var ChatTUI = class {
           console.log(`  ${chalk8.yellow("\u26A1")} ${chalk8.yellow(action)} ${chalk8.gray("...")}`);
         }
       },
-      onToolResult: (_id, action, success2, data, error2) => {
+      onToolResult: (_id, action, success2, data, error2, code) => {
         if (success2) {
           if (this.verbose) {
             const summary = data ? summarizeData(data) : "";
@@ -6988,7 +7241,8 @@ var ChatTUI = class {
             console.log(`  ${chalk8.green("\u2713")} ${chalk8.green(action)}`);
           }
         } else {
-          console.log(`  ${chalk8.red("\u2717")} ${chalk8.red(action)}: ${chalk8.red(error2 || "failed")}`);
+          const suffix = code && this.verbose ? chalk8.gray(` (${code})`) : "";
+          console.log(`  ${chalk8.red("\u2717")} ${chalk8.red(action)}: ${chalk8.red(error2 || "failed")}${suffix}`);
         }
       },
       onAssistantMessage: (content) => {
@@ -7016,12 +7270,13 @@ var ChatTUI = class {
           console.log(`     ${chalk8.blue.underline(explorerUrl)}`);
         }
       },
-      onError: (message) => {
+      onError: (message, code) => {
         if (this.isStreaming) {
           process.stdout.write("\n");
           this.isStreaming = false;
         }
-        console.log(`  ${chalk8.red("Error")}: ${message}`);
+        const suffix = this.verbose ? chalk8.gray(` (${code})`) : "";
+        console.log(`  ${chalk8.red("Error")}: ${message}${suffix}`);
       },
       onDone: () => {
         if (this.isStreaming) {
@@ -7214,6 +7469,7 @@ async function executeAgent(ctx2, options) {
   const config = {
     backendUrl: options.backendUrl || process.env.VULTISIG_AGENT_URL || "https://abe.vultisig.com",
     vaultName: vault.name,
+    vultisig: ctx2.sdk,
     password: options.password,
     viaAgent: options.viaAgent,
     sessionId: options.sessionId,
@@ -7229,7 +7485,8 @@ async function executeAgent(ctx2, options) {
       const addresses = session.getVaultAddresses();
       await pipe.start(vault.name, addresses);
     } catch (err) {
-      process.stdout.write(JSON.stringify({ type: "error", message: err.message }) + "\n");
+      const { code, message } = normalizeAgentError(err);
+      process.stdout.write(JSON.stringify({ type: "error", message, code }) + "\n");
       process.exit(1);
     }
   } else {
@@ -7239,7 +7496,8 @@ async function executeAgent(ctx2, options) {
       await session.initialize(callbacks);
       await tui.start();
     } catch (err) {
-      console.error(`Agent error: ${err.message}`);
+      const { message } = normalizeAgentError(err);
+      console.error(`Agent error: ${message}`);
       process.exit(1);
     }
   }
@@ -7255,6 +7513,7 @@ async function executeAgentAsk(ctx2, message, options) {
     const config = {
       backendUrl: options.backendUrl || process.env.VULTISIG_AGENT_URL || "https://abe.vultisig.com",
       vaultName: vault.name,
+      vultisig: ctx2.sdk,
       password: options.password,
       sessionId: options.session,
       verbose: options.verbose,
@@ -7293,10 +7552,11 @@ tx:${tx.chain}:${tx.hash}
       }
     }
   } catch (err) {
+    const { code, message: message2 } = normalizeAgentError(err);
     if (options.json) {
-      process.stdout.write(JSON.stringify({ error: err.message }) + "\n");
+      process.stdout.write(JSON.stringify({ error: message2, code }) + "\n");
     } else {
-      process.stderr.write(`Error: ${err.message}
+      process.stderr.write(`Error: ${message2} [${code}]
 `);
     }
     process.exit(1);
@@ -7759,7 +8019,7 @@ var EventBuffer = class {
 };
 
 // src/interactive/session.ts
-import { fiatCurrencies as fiatCurrencies3 } from "@vultisig/sdk";
+import { fiatCurrencies as fiatCurrencies4 } from "@vultisig/sdk";
 import chalk12 from "chalk";
 import ora3 from "ora";
 import * as readline3 from "readline";
@@ -8577,9 +8837,9 @@ Error: ${error2.message}`));
         i++;
       }
     }
-    if (!fiatCurrencies3.includes(currency)) {
+    if (!fiatCurrencies4.includes(currency)) {
       console.log(chalk12.red(`Invalid currency: ${currency}`));
-      console.log(chalk12.yellow(`Supported currencies: ${fiatCurrencies3.join(", ")}`));
+      console.log(chalk12.yellow(`Supported currencies: ${fiatCurrencies4.join(", ")}`));
       return;
     }
     const raw = args.includes("--raw");
@@ -8828,7 +9088,7 @@ var cachedVersion = null;
 function getVersion() {
   if (cachedVersion) return cachedVersion;
   if (true) {
-    cachedVersion = "0.15.0";
+    cachedVersion = "0.15.4";
     return cachedVersion;
   }
   try {
@@ -9323,7 +9583,7 @@ async function init(vaultOverride, unlockPassword, passwordTTL) {
     }
     const globalOptions = program.opts();
     const serverEndpoints = resolveServerEndpoints(globalOptions);
-    const sdk = new Vultisig7({
+    const sdk = new Vultisig6({
       onPasswordRequired: createPasswordCallback(),
       ...serverEndpoints ? { serverEndpoints } : {},
       ...passwordTTL !== void 0 ? { passwordCache: { defaultTTL: passwordTTL } } : {}
@@ -9940,7 +10200,7 @@ program.command("update").description("Check for updates and show update command
 setupCompletionCommand(program);
 async function startInteractiveMode() {
   const serverEndpoints = resolveServerEndpoints(parseServerEndpointOverridesFromArgv(process.argv.slice(2)));
-  const sdk = new Vultisig7({
+  const sdk = new Vultisig6({
     onPasswordRequired: createPasswordCallback(),
     ...serverEndpoints ? { serverEndpoints } : {}
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vultisig/cli",
-  "version": "0.15.0",
+  "version": "0.15.4",
   "description": "Command-line wallet for Vultisig - multi-chain MPC wallet management",
   "type": "module",
   "bin": {
@@ -55,7 +55,7 @@
     "@cosmjs/stargate": "^0.38.1",
     "@noble/hashes": "^2.0.1",
     "@vultisig/rujira": "^10.0.0",
-    "@vultisig/sdk": "^0.15.1",
+    "@vultisig/sdk": "^0.15.4",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",