@vultisig/cli 0.12.0 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @vultisig/cli
 
+## 0.14.2
+
+### Patch Changes
+
+- [#233](https://github.com/vultisig/vultisig-sdk/pull/233) [`a0387b4`](https://github.com/vultisig/vultisig-sdk/commit/a0387b42b816c26fedf71a089fb461257d331be7) Thanks [@rcoderdev](https://github.com/rcoderdev)! - CLI agent executor now surfaces unimplemented and stub actions as failures (`success: false`) instead of returning misleading success. Removed `get_market_price` and `thorchain_query` from the local auto-execute allowlist where there is no implementation.
+
+## 0.14.0
+
+### Patch Changes
+
+- [#205](https://github.com/vultisig/vultisig-sdk/pull/205) [`99296f5`](https://github.com/vultisig/vultisig-sdk/commit/99296f5aaf3f9bfb7fe694de034037683e7435ed) Thanks [@rcoderdev](https://github.com/rcoderdev)! - Classify vault import failures with specific `VaultImportErrorCode` values (`INVALID_FILE_FORMAT`, `INVALID_PASSWORD`, `UNSUPPORTED_FORMAT`, `CORRUPTED_DATA`) instead of wrapping most errors as `CORRUPTED_DATA`. Add unit tests for import edge cases.
+
+- Updated dependencies [[`9e2ffd6`](https://github.com/vultisig/vultisig-sdk/commit/9e2ffd6f6a8e2c8ad507b6ed2e2c1232bf8a98c7), [`8bef556`](https://github.com/vultisig/vultisig-sdk/commit/8bef55651cba506a515083765d6f7745cce54abe), [`99296f5`](https://github.com/vultisig/vultisig-sdk/commit/99296f5aaf3f9bfb7fe694de034037683e7435ed)]:
+  - @vultisig/sdk@0.14.0
+  - @vultisig/rujira@9.0.0
+
+## 0.13.0
+
+### Patch Changes
+
+- Updated dependencies [[`3f46444`](https://github.com/vultisig/vultisig-sdk/commit/3f46444b2a11a41dbbb023919c2f168f9d15cff8), [`84a2950`](https://github.com/vultisig/vultisig-sdk/commit/84a295002ed7310320b584fbccb76aaf4a233b31)]:
+  - @vultisig/sdk@0.13.0
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -693,6 +693,55 @@ vultisig agent --via-agent --password "$VAULT_PASSWORD"
 - `--password-ttl <ms>` - Password cache TTL (default: 5min, 24h for `--via-agent`)
 - `--session-id <id>` - Resume an existing session
 
+#### Pipe Protocol (`--via-agent`)
+
+The pipe interface uses NDJSON (one JSON object per line) on stdin/stdout. Designed for AI agent orchestrators that need programmatic wallet control.
+
+**Input commands** (send on stdin):
+
+| Type | Fields | Purpose |
+|------|--------|---------|
+| `message` | `content: string` | Send a natural-language message |
+| `confirm` | `confirmed: boolean` | Respond to a confirmation request |
+| `password` | `password: string` | Provide vault password when requested |
+
+**Output events** (emitted on stdout):
+
+| Type | Fields | When |
+|------|--------|------|
+| `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 |
+| `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) |
+| `done` | `{}` | Response cycle complete |
+
+**Example session:**
+
+```bash
+echo '{"type":"message","content":"What is my ETH balance?"}' | vultisig agent --via-agent --password mypass --vault t1
+```
+
+```json
+{"type":"ready","vault":"t1","addresses":{"Ethereum":"0xabc...","Bitcoin":"bc1q..."}}
+{"type":"session","id":"conv_abc123"}
+{"type":"tool_call","id":"mcp-get_balances","action":"get_balances","status":"running"}
+{"type":"tool_result","id":"mcp-get_balances","action":"get_balances","success":true}
+{"type":"text_delta","delta":"Your ETH"}
+{"type":"text_delta","delta":" balance is 1.5 ETH."}
+{"type":"assistant","content":"Your ETH balance is 1.5 ETH ($3,750.00 USD)."}
+{"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.
+
 #### Session Management
 
 ```bash
@@ -811,6 +860,7 @@ Thorguard NFT holders receive a free tier upgrade (up to gold tier).
 -i, --interactive        Start interactive shell mode
 -o, --output <format>    Output format: table, json (default: table)
 --vault <nameOrId>       Specify vault by name or ID
+--server-url <url>       Base Vultisig API URL for FastVault and relay endpoints
 --silent                 Suppress informational output, show only results
 --debug                  Enable debug output
 -h, --help               Show help
@@ -933,6 +983,9 @@ VULTISIG_VAULT=MyWallet
 # Override config directory
 VULTISIG_CONFIG_DIR=/custom/path
 
+# Override FastVault and relay via a shared base URL
+VULTISIG_SERVER_URL=http://127.0.0.1:8080
+
 # Disable colored output
 VULTISIG_NO_COLOR=1
 

package/dist/index.js

@@ -2420,7 +2420,9 @@ async function executeExecute(ctx2, params) {
   const vault = await ctx2.ensureActiveVault();
   const chainConfig = COSMOS_CHAIN_CONFIG[params.chain];
   if (!chainConfig) {
-    throw new Error(`Chain ${params.chain} does not support CosmWasm execute. Supported chains: ${Object.keys(COSMOS_CHAIN_CONFIG).join(", ")}`);
+    throw new Error(
+      `Chain ${params.chain} does not support CosmWasm execute. Supported chains: ${Object.keys(COSMOS_CHAIN_CONFIG).join(", ")}`
+    );
   }
   let msg;
   try {
@@ -2441,7 +2443,9 @@ async function executeContractTransaction(vault, params, chainConfig, msg, funds
     info(`Chain:      ${params.chain}`);
     info(`From:       ${address}`);
     info(`Contract:   ${params.contract}`);
-    info(`Message:    ${JSON.stringify(msg, null, 2).substring(0, 200)}${JSON.stringify(msg).length > 200 ? "..." : ""}`);
+    info(
+      `Message:    ${JSON.stringify(msg, null, 2).substring(0, 200)}${JSON.stringify(msg).length > 200 ? "..." : ""}`
+    );
     if (funds.length > 0) {
       info(`Funds:      ${funds.map((f) => `${f.amount} ${f.denom}`).join(", ")}`);
     }
@@ -2479,13 +2483,16 @@ Or use this URL: ${qrPayload}
         signSpinner.start("Waiting for devices to join signing session...");
       }
     });
-    vault.on("deviceJoined", ({ deviceId, totalJoined, required }) => {
-      if (!isSilent()) {
-        signSpinner.text = `Device joined: ${totalJoined}/${required} (${deviceId})`;
-      } else if (!isJsonOutput()) {
-        printResult(`Device joined: ${totalJoined}/${required}`);
+    vault.on(
+      "deviceJoined",
+      ({ deviceId, totalJoined, required }) => {
+        if (!isSilent()) {
+          signSpinner.text = `Device joined: ${totalJoined}/${required} (${deviceId})`;
+        } else if (!isJsonOutput()) {
+          printResult(`Device joined: ${totalJoined}/${required}`);
+        }
       }
-    });
+    );
   }
   try {
     const cosmosChain = params.chain;
@@ -4250,9 +4257,7 @@ var AskInterface = class {
       onDone: () => {
       },
       requestPassword: async () => {
-        throw new Error(
-          "Password required but not provided. Use --password flag."
-        );
+        throw new Error("Password required but not provided. Use --password flag.");
       },
       requestConfirmation: async (_message) => {
         return true;
@@ -4302,10 +4307,7 @@ async function authenticateVault(client, vault, password, maxAttempts = 3) {
         process.stderr.write(`  Retry ${attempt}/${maxAttempts}...
 `);
       }
-      const signature = await vault.signBytes(
-        { data: Buffer.from(messageHash), chain: Chain7.Ethereum },
-        {}
-      );
+      const signature = await vault.signBytes({ data: Buffer.from(messageHash), chain: Chain7.Ethereum }, {});
       const sigHex = formatSignature65(signature.signature, signature.recovery ?? 0);
       const authResponse = await client.authenticate({
         public_key: publicKey,
@@ -4473,31 +4475,40 @@ var AgentClient = class {
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    let currentEvent = "";
+    let currentData = "";
+    const stripLeadingSpace = (v) => v.length > 0 && v[0] === " " ? v.slice(1) : v;
+    const processLine = (raw) => {
+      const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+      if (line.startsWith("event:")) {
+        currentEvent = stripLeadingSpace(line.slice(6)).trim();
+      } else if (line.startsWith("data:")) {
+        currentData += (currentData ? "\n" : "") + stripLeadingSpace(line.slice(5));
+      } else if (line === "") {
+        if (currentData) {
+          this.handleSSEEvent(currentEvent || "message", currentData, result, callbacks);
+        }
+        currentEvent = "";
+        currentData = "";
+      } else if (line[0] === ":") {
+      }
+    };
     try {
       while (true) {
         const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
+        buffer += decoder.decode(value || new Uint8Array(), { stream: !done });
         const lines = buffer.split("\n");
-        buffer = lines.pop() || "";
-        let currentEvent = "";
-        let currentData = "";
-        for (const line of lines) {
-          if (line.startsWith("event: ")) {
-            currentEvent = line.slice(7).trim();
-          } else if (line.startsWith("data: ")) {
-            currentData += (currentData ? "\n" : "") + line.slice(6);
-          } else if (line === "") {
-            if (currentEvent && currentData) {
-              this.handleSSEEvent(currentEvent, currentData, result, callbacks);
-            }
-            currentEvent = "";
-            currentData = "";
-          } else if (line.startsWith(": ")) {
-          }
+        const trailing = lines.pop() ?? "";
+        buffer = done ? "" : trailing;
+        for (const rawLine of lines) {
+          processLine(rawLine);
         }
-        if (currentEvent && currentData) {
-          this.handleSSEEvent(currentEvent, currentData, result, callbacks);
+        if (done) {
+          if (trailing) processLine(trailing);
+          if (currentData) {
+            this.handleSSEEvent(currentEvent || "message", currentData, result, callbacks);
+          }
+          break;
         }
       }
     } finally {
@@ -4510,8 +4521,10 @@ var AgentClient = class {
       const parsed = JSON.parse(data);
       switch (event) {
         case "text_delta":
-          result.fullText += parsed.delta;
-          callbacks.onTextDelta?.(parsed.delta);
+          if (typeof parsed.delta === "string") {
+            result.fullText += parsed.delta;
+            callbacks.onTextDelta?.(parsed.delta);
+          }
           break;
         case "tool_progress":
           if (this.verbose) process.stderr.write(`[SSE:tool_progress] raw: ${data.slice(0, 1e3)}
@@ -4547,8 +4560,26 @@ var AgentClient = class {
         case "done":
           break;
       }
-    } catch {
+    } catch (e) {
+      if (e instanceof SyntaxError) {
+        if (this.verbose) process.stderr.write(`[SSE] skipping malformed JSON: ${data.slice(0, 200)}
+`);
+      } else {
+        throw e;
+      }
+    }
+  }
+  // ============================================================================
+  // Calldata
+  // ============================================================================
+  async getCalldata(id) {
+    const res = await fetch(`${this.baseUrl}/agent/calldata/${id}`, {
+      headers: this.authToken ? { Authorization: `Bearer ${this.authToken}` } : {}
+    });
+    if (!res.ok) {
+      throw new Error(`Failed to resolve calldata_id ${id}: ${res.status} ${res.statusText}`);
     }
+    return res.json();
   }
   // ============================================================================
   // Private helpers
@@ -4898,7 +4929,6 @@ var AUTO_EXECUTE_ACTIONS = /* @__PURE__ */ new Set([
   "address_book_add",
   "address_book_remove",
   "get_address_book",
-  "get_market_price",
   "get_balances",
   "get_portfolio",
   "search_token",
@@ -4910,8 +4940,7 @@ var AUTO_EXECUTE_ACTIONS = /* @__PURE__ */ new Set([
   "sign_tx",
   "sign_typed_data",
   "read_evm_contract",
-  "scan_tx",
-  "thorchain_query"
+  "scan_tx"
 ]);
 var PASSWORD_REQUIRED_ACTIONS = /* @__PURE__ */ new Set(["sign_tx", "sign_typed_data", "build_custom_tx"]);
 
@@ -4954,6 +4983,8 @@ var AgentExecutor = class {
   stateStore = null;
   /** Held chain lock release functions, keyed by chain name */
   chainLockReleases = /* @__PURE__ */ new Map();
+  /** Backend client for resolving calldata_id references. */
+  backendClient = null;
   constructor(vault, verbose = false, vaultId) {
     this.vault = vault;
     this.verbose = verbose;
@@ -4964,13 +4995,19 @@ var AgentExecutor = class {
   setPassword(password) {
     this.password = password;
   }
+  setBackendClient(client) {
+    this.backendClient = client;
+  }
   /**
    * Store a server-built transaction (from tx_ready SSE event).
    * This allows sign_tx to find and sign it when the backend requests signing.
    */
   storeServerTransaction(txReadyData) {
-    if (this.verbose) process.stderr.write(`[executor] storeServerTransaction called, keys: ${Object.keys(txReadyData || {}).join(",")}
-`);
+    if (this.verbose)
+      process.stderr.write(
+        `[executor] storeServerTransaction called, keys: ${Object.keys(txReadyData || {}).join(",")}
+`
+      );
     const swapTx = txReadyData.swap_tx || txReadyData.send_tx || txReadyData.tx;
     if (!swapTx) {
       if (this.verbose) process.stderr.write(`[executor] storeServerTransaction: no swap_tx/send_tx/tx found in data
@@ -4985,8 +5022,11 @@ var AgentExecutor = class {
       chain,
       timestamp: Date.now()
     });
-    if (this.verbose) process.stderr.write(`[executor] Stored server tx for chain ${chain}, pendingPayloads size=${this.pendingPayloads.size}
-`);
+    if (this.verbose)
+      process.stderr.write(
+        `[executor] Stored server tx for chain ${chain}, pendingPayloads size=${this.pendingPayloads.size}
+`
+      );
   }
   hasPendingTransaction() {
     return this.pendingPayloads.has("latest");
@@ -5061,7 +5101,9 @@ var AgentExecutor = class {
       case "read_evm_contract":
         return this.readEvmContract(params);
       default:
-        return { message: `Action type '${action.type}' not implemented locally` };
+        throw new Error(
+          `Action type '${action.type}' is not implemented locally. The backend may handle this action server-side.`
+        );
     }
   }
   // ============================================================================
@@ -5227,7 +5269,8 @@ var AgentExecutor = class {
     }
   }
   async buildSwapTx(params) {
-    if (this.verbose) process.stderr.write(`[build_swap_tx] called with params: ${JSON.stringify(params).slice(0, 500)}
+    if (this.verbose)
+      process.stderr.write(`[build_swap_tx] called with params: ${JSON.stringify(params).slice(0, 500)}
 `);
     const fromChainName = params.from_chain || params.chain;
     const toChainName = params.to_chain;
@@ -5261,8 +5304,18 @@ var AgentExecutor = class {
       const messageHashes = await this.vault.extractMessageHashes(payload);
       this.pendingPayloads.clear();
       const payloadId = `swap_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-      this.pendingPayloads.set(payloadId, { payload, coin: { chain, address: "", decimals: 18, ticker: fromSymbol }, chain, timestamp: Date.now() });
-      this.pendingPayloads.set("latest", { payload, coin: { chain, address: "", decimals: 18, ticker: fromSymbol }, chain, timestamp: Date.now() });
+      this.pendingPayloads.set(payloadId, {
+        payload,
+        coin: { chain, address: "", decimals: 18, ticker: fromSymbol },
+        chain,
+        timestamp: Date.now()
+      });
+      this.pendingPayloads.set("latest", {
+        payload,
+        coin: { chain, address: "", decimals: 18, ticker: fromSymbol },
+        chain,
+        timestamp: Date.now()
+      });
       return {
         keysign_payload: payloadId,
         from_chain: fromChain.toString(),
@@ -5280,6 +5333,17 @@ var AgentExecutor = class {
     }
   }
   async buildTx(params) {
+    if (params.calldata_id && !params.data && this.backendClient) {
+      const id = params.calldata_id;
+      if (this.verbose) process.stderr.write(`[executor] resolving calldata_id ${id}
+`);
+      const entry = await this.backendClient.getCalldata(id);
+      params = { ...params, data: entry.data };
+      if (!params.to && entry.to) params = { ...params, to: entry.to };
+      delete params.calldata_id;
+      if (this.verbose) process.stderr.write(`[executor] calldata_id resolved, data len=${entry.data.length}
+`);
+    }
     if (params.function_name && params.contract_address) {
       return this.buildContractCallTx(params);
     }
@@ -5308,6 +5372,12 @@ var AgentExecutor = class {
         message: "Transaction built. Ready to sign."
       };
     }
+    if (params.contract_address && !params.function_name) {
+      const provided = Object.keys(params).join(", ");
+      throw new Error(
+        `build_custom_tx requires function_name and params for contract calls. Got: ${provided}. Missing: function_name, params.`
+      );
+    }
     return this.buildSendTx(params);
   }
   /**
@@ -5323,8 +5393,11 @@ var AgentExecutor = class {
     const typedParams = params.params;
     const value = params.value || "0";
     const calldata = await encodeContractCall(functionName, typedParams || []);
-    if (this.verbose) process.stderr.write(`[build_contract_tx] ${functionName}(${(typedParams || []).map((p) => p.type).join(",")}) on ${contractAddress} chain=${chain}
-`);
+    if (this.verbose)
+      process.stderr.write(
+        `[build_contract_tx] ${functionName}(${(typedParams || []).map((p) => p.type).join(",")}) on ${contractAddress} chain=${chain}
+`
+      );
     const serverTxData = {
       __serverTx: true,
       tx: {
@@ -5349,7 +5422,8 @@ var AgentExecutor = class {
   async signTx(params) {
     if (this.verbose) process.stderr.write(`[sign_tx] params: ${JSON.stringify(params).slice(0, 500)}
 `);
-    if (this.verbose) process.stderr.write(`[sign_tx] pendingPayloads keys: ${[...this.pendingPayloads.keys()].join(", ")}
+    if (this.verbose)
+      process.stderr.write(`[sign_tx] pendingPayloads keys: ${[...this.pendingPayloads.keys()].join(", ")}
 `);
     const payloadId = params.keysign_payload || params.payload_id || "latest";
     const stored = this.pendingPayloads.get(payloadId);
@@ -5363,7 +5437,8 @@ var AgentExecutor = class {
           return await this.buildAndSignSolanaSwapLocally(payload);
         } catch (e) {
           if (e._phase === "prepare") {
-            if (this.verbose) process.stderr.write(`[sign_tx] Solana local build failed (${e.message}), falling back to signServerTx
+            if (this.verbose)
+              process.stderr.write(`[sign_tx] Solana local build failed (${e.message}), falling back to signServerTx
 `);
           } else {
             throw e;
@@ -5447,8 +5522,11 @@ var AgentExecutor = class {
       };
       const amount = BigInt(swapTx.value || "0");
       const hasCalldata = !!(swapTx.data && swapTx.data !== "0x");
-      if (this.verbose) process.stderr.write(`[sign_server_tx] chain=${chain}, to=${swapTx.to}, value=${swapTx.value}, amount=${amount}, hasCalldata=${hasCalldata}
-`);
+      if (this.verbose)
+        process.stderr.write(
+          `[sign_server_tx] chain=${chain}, to=${swapTx.to}, value=${swapTx.value}, amount=${amount}, hasCalldata=${hasCalldata}
+`
+        );
       if (this.vault.isEncrypted && !this.vault.isUnlocked?.()) {
         if (this.password) {
           await this.vault.unlock?.(this.password);
@@ -5466,6 +5544,18 @@ var AgentExecutor = class {
         keysignPayload.toAmount = "0";
       }
       await this.patchEvmNonce(chain, keysignPayload);
+      if (swapTx.gas_limit) {
+        const bs = keysignPayload.blockchainSpecific;
+        if (bs?.case === "ethereumSpecific" && bs.value?.gasLimit) {
+          const serverGas = swapTx.gas_limit.toString();
+          const currentGas = bs.value.gasLimit.toString();
+          if (BigInt(serverGas) > BigInt(currentGas)) {
+            bs.value.gasLimit = serverGas;
+            if (this.verbose) process.stderr.write(`[gas] Using server gas_limit: ${serverGas} (was ${currentGas})
+`);
+          }
+        }
+      }
       await this.patchEvmGas(chain, keysignPayload);
       const messageHashes = await this.vault.extractMessageHashes(keysignPayload);
       const signature = await this.vault.sign(
@@ -5512,16 +5602,25 @@ var AgentExecutor = class {
     const toChain = toChainName ? resolveChain(toChainName) : fromChain;
     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"), { _phase: "prepare" });
+    if (!amountStr)
+      throw Object.assign(new Error("Missing amount in tx_ready data for local Solana swap build"), {
+        _phase: "prepare"
+      });
     const fromToken = serverTxData.from_address;
     const toToken = serverTxData.to_address;
     const fromDecimals = serverTxData.from_decimals;
-    if (fromDecimals == null) throw Object.assign(new Error("Missing from_decimals in tx_ready data for local Solana swap build"), { _phase: "prepare" });
+    if (fromDecimals == null)
+      throw Object.assign(new Error("Missing from_decimals in tx_ready data for local Solana swap build"), {
+        _phase: "prepare"
+      });
     const fromCoin = { chain: fromChain, token: fromToken || void 0 };
     const toCoin = { chain: toChain, token: toToken || void 0 };
     const humanAmount = Number(amountStr) / Math.pow(10, fromDecimals);
-    if (this.verbose) process.stderr.write(`[solana_local_swap] from=${fromChainName} to=${toChainName || fromChainName} amount=${amountStr}
-`);
+    if (this.verbose)
+      process.stderr.write(
+        `[solana_local_swap] from=${fromChainName} to=${toChainName || fromChainName} amount=${amountStr}
+`
+      );
     if (this.vault.isEncrypted && !this.vault.isUnlocked?.()) {
       if (this.password) {
         await this.vault.unlock?.(this.password);
@@ -5614,15 +5713,21 @@ var AgentExecutor = class {
     if (nextNonce !== rpcNonce) {
       const pendingNonce = await this.fetchEvmPendingNonce(chain);
       if (pendingNonce !== null && pendingNonce === rpcNonce) {
-        if (this.verbose) process.stderr.write(`[nonce] Stale local state for ${chain}: local=${nextNonce}, on-chain=${rpcNonce}, no pending txs \u2014 using on-chain nonce
-`);
+        if (this.verbose)
+          process.stderr.write(
+            `[nonce] Stale local state for ${chain}: local=${nextNonce}, on-chain=${rpcNonce}, no pending txs \u2014 using on-chain nonce
+`
+          );
         this.stateStore.clearEvmState(chain);
         return;
       }
       const nonceGap = nextNonce - rpcNonce;
       if (pendingNonce === null && nonceGap > 3n) {
-        if (this.verbose) process.stderr.write(`[nonce] Large nonce gap for ${chain} (${nonceGap}) and couldn't verify pending txs \u2014 using on-chain nonce ${rpcNonce}
-`);
+        if (this.verbose)
+          process.stderr.write(
+            `[nonce] Large nonce gap for ${chain} (${nonceGap}) and couldn't verify pending txs \u2014 using on-chain nonce ${rpcNonce}
+`
+          );
         this.stateStore.clearEvmState(chain);
         return;
       }
@@ -5662,8 +5767,11 @@ var AgentExecutor = class {
       const minMaxFee = baseFee * 25n / 10n + currentPriorityFee;
       if (currentMaxFee < minMaxFee) {
         bs.value.maxFeePerGasWei = minMaxFee.toString();
-        if (this.verbose) process.stderr.write(`[gas] Bumped ${chain} maxFeePerGas: ${currentMaxFee} \u2192 ${minMaxFee} (baseFee=${baseFee})
-`);
+        if (this.verbose)
+          process.stderr.write(
+            `[gas] Bumped ${chain} maxFeePerGas: ${currentMaxFee} \u2192 ${minMaxFee} (baseFee=${baseFee})
+`
+          );
       }
     } catch {
       if (this.verbose) process.stderr.write(`[gas] Failed to refresh base fee for ${chain}, keeping original
@@ -5780,7 +5888,8 @@ var AgentExecutor = class {
       data: eip712Hash,
       chain
     });
-    if (this.verbose) process.stderr.write(`[sign_typed_data] signed, format=${sigResult.format}, recovery=${sigResult.recovery}
+    if (this.verbose)
+      process.stderr.write(`[sign_typed_data] signed, format=${sigResult.format}, recovery=${sigResult.recovery}
 `);
     const { r, s } = parseDERSignature(sigResult.signature);
     const v = (sigResult.recovery ?? 0) + 27;
@@ -5800,40 +5909,45 @@ var AgentExecutor = class {
   // Address Book
   // ============================================================================
   async getAddressBook() {
-    return { entries: [], message: "Address book retrieved" };
+    throw new Error("get_address_book is not yet implemented locally. The backend may handle this action server-side.");
   }
-  async addAddressBookEntry(params) {
-    return { added: true, name: params.name, address: params.address, chain: params.chain };
+  async addAddressBookEntry(_params) {
+    throw new Error("address_book_add is not yet implemented locally. The backend may handle this action server-side.");
   }
-  async removeAddressBookEntry(params) {
-    return { removed: true, address: params.address };
+  async removeAddressBookEntry(_params) {
+    throw new Error(
+      "address_book_remove is not yet implemented locally. The backend may handle this action server-side."
+    );
   }
   // ============================================================================
   // Token Search & Other
   // ============================================================================
-  async searchToken(params) {
-    return { message: `Token search for '${params.query || params.symbol}' - delegated to backend` };
+  async searchToken(_params) {
+    throw new Error("search_token is not yet implemented locally. The backend may handle this action server-side.");
   }
   async listVaults() {
     return {
-      vaults: [{
-        name: this.vault.name,
-        id: this.vault.id,
-        type: this.vault.type,
-        chains: this.vault.chains.map((c) => c.toString())
-      }]
+      vaults: [
+        {
+          name: this.vault.name,
+          id: this.vault.id,
+          type: this.vault.type,
+          chains: this.vault.chains.map((c) => c.toString())
+        }
+      ]
     };
   }
-  async scanTx(params) {
-    return { message: `Transaction scan for ${params.tx_hash || "unknown"} - delegated to backend` };
+  async scanTx(_params) {
+    throw new Error("scan_tx is not yet implemented locally. The backend may handle this action server-side.");
   }
-  async readEvmContract(params) {
-    return { message: `EVM contract read for ${params.contract || "unknown"} - delegated to backend` };
+  async readEvmContract(_params) {
+    throw new Error("read_evm_contract is not yet implemented locally. The backend may handle this action server-side.");
   }
 };
 async function encodeContractCall(functionName, params) {
+  const baseName = functionName.includes("(") ? functionName.split("(")[0] : functionName;
   const types = params.map((p) => p.type);
-  const sig = `${functionName}(${types.join(",")})`;
+  const sig = `${baseName}(${types.join(",")})`;
   const selector = await keccak256Selector(sig);
   let encoded = "";
   for (const param of params) {
@@ -6294,6 +6408,7 @@ var PipeInterface = class {
 import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join as join2 } from "node:path";
+import { MemoryStorage, PushNotificationService } from "@vultisig/sdk";
 var AgentSession = class {
   client;
   vault;
@@ -6304,6 +6419,7 @@ var AgentSession = class {
   cachedContext = null;
   abortController = null;
   historyMessages = [];
+  pushService = null;
   constructor(vault, config) {
     this.vault = vault;
     this.config = config;
@@ -6337,6 +6453,7 @@ var AgentSession = class {
         this.client.setAuthToken(auth.token);
         saveCachedToken(this.publicKey, auth.token, auth.expiresAt);
       }
+      this.executor.setBackendClient(this.client);
     } catch (err) {
       throw new Error(`Authentication failed: ${err.message}`);
     }
@@ -6365,6 +6482,35 @@ var AgentSession = class {
       this.conversationId = conv.id;
     }
     this.cachedContext = this.config.viaAgent || this.config.askMode ? await buildMinimalContext(this.vault) : await buildMessageContext(this.vault);
+    if (this.config.notificationUrl && ui.onNotification) {
+      try {
+        if (!globalThis.WebSocket) {
+          const { WebSocket } = await import("ws");
+          globalThis.WebSocket = WebSocket;
+        }
+        const token = crypto.randomUUID();
+        this.pushService = new PushNotificationService(new MemoryStorage(), this.config.notificationUrl);
+        await this.pushService.registerDevice({
+          vaultId: this.publicKey,
+          partyName: "cli-agent",
+          token,
+          deviceType: "electron"
+        });
+        this.pushService.onSigningRequest((notification) => {
+          ui.onNotification?.(notification.vaultName, notification.qrCodeData);
+        });
+        this.pushService.connect({
+          vaultId: this.publicKey,
+          partyName: "cli-agent",
+          token
+        });
+      } catch (err) {
+        if (this.config.verbose) {
+          process.stderr.write(`[session] push notification setup failed: ${err}
+`);
+        }
+      }
+    }
   }
   getConversationId() {
     return this.conversationId;
@@ -6458,7 +6604,8 @@ var AgentSession = class {
         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"}
+            if (this.config.verbose)
+              process.stderr.write(`[session] skipping error tx_ready: ${txData.error || "unknown error"}
 `);
             return;
           }
@@ -6475,7 +6622,7 @@ var AgentSession = class {
       },
       this.abortController?.signal
     );
-    const responseText = streamResult.fullText || streamResult.message?.content || "";
+    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();
@@ -6489,11 +6636,10 @@ var AgentSession = class {
     const actions = streamResult.actions.filter((a) => a.type !== "sign_tx");
     if (actions.length > 0) {
       const results = await this.executeActions(actions, ui);
-      const hasBuildSuccess = results.some(
-        (r) => r.success && r.action.startsWith("build_")
-      );
+      const hasBuildSuccess = results.some((r) => r.success && r.action.startsWith("build_"));
       if (hasBuildSuccess && this.executor.hasPendingTransaction()) {
-        if (this.config.verbose) process.stderr.write(`[session] build_* action produced pending tx, auto-signing client-side
+        if (this.config.verbose)
+          process.stderr.write(`[session] build_* action produced pending tx, auto-signing client-side
 `);
         const signAction = {
           id: `tx_sign_${Date.now()}`,
@@ -6517,7 +6663,8 @@ var AgentSession = class {
       }
     }
     if (streamResult.transactions.length > 0 && this.executor.hasPendingTransaction()) {
-      if (this.config.verbose) process.stderr.write(`[session] ${streamResult.transactions.length} tx_ready events, signing client-side
+      if (this.config.verbose)
+        process.stderr.write(`[session] ${streamResult.transactions.length} tx_ready events, signing client-side
 `);
       const signAction = {
         id: `tx_sign_${Date.now()}`,
@@ -6588,6 +6735,8 @@ var AgentSession = class {
    */
   dispose() {
     this.cancel();
+    this.pushService?.disconnect();
+    this.pushService = null;
     this.cachedContext = null;
     this.conversationId = null;
     this.historyMessages = [];
@@ -6681,10 +6830,12 @@ var ChatTUI = class {
   rl;
   session;
   isStreaming = false;
+  isProcessing = false;
   currentStreamText = "";
   vaultName;
   stopped = false;
   verbose;
+  pendingNotifications = [];
   constructor(session, vaultName, verbose = false) {
     this.session = session;
     this.vaultName = vaultName;
@@ -6889,6 +7040,20 @@ var ChatTUI = class {
           }
         });
       },
+      onNotification: (title, deeplink) => {
+        const currentConvId = this.session.getConversationId();
+        if (currentConvId && deeplink) {
+          const segments = deeplink.split("/");
+          const deeplinkConvId = segments[segments.length - 1];
+          if (deeplinkConvId !== currentConvId) return;
+        }
+        if (this.isProcessing) {
+          this.pendingNotifications.push({ title, deeplink });
+          return;
+        }
+        this.displayNotification(title);
+        this.showPrompt();
+      },
       requestConfirmation: async (message) => {
         return new Promise((resolve) => {
           this.rl.question(chalk8.yellow(`  ${message} (y/N): `), (answer) => {
@@ -6898,9 +7063,31 @@ var ChatTUI = class {
       }
     };
   }
+  displayNotification(title) {
+    const [heading, ...bodyLines] = title.split("\n");
+    const body = bodyLines.join("\n").trim();
+    const ts = this.timestamp();
+    process.stdout.write(`
+${chalk8.gray(ts)} ${chalk8.magenta.bold("Notification")}: ${chalk8.bold(heading)}
+`);
+    if (body) {
+      process.stdout.write(`  ${body}
+`);
+    }
+    process.stdout.write("\n");
+  }
+  flushPendingNotifications() {
+    if (this.pendingNotifications.length === 0) return;
+    const queued = this.pendingNotifications.splice(0);
+    for (const { title } of queued) {
+      this.displayNotification(title);
+    }
+    this.showPrompt();
+  }
   async handleMessage(content) {
     const callbacks = this.getCallbacks();
     this.isStreaming = false;
+    this.isProcessing = true;
     try {
       await this.session.sendMessage(content, callbacks);
     } catch (err) {
@@ -6909,12 +7096,17 @@ var ChatTUI = class {
       } else {
         console.log(chalk8.red(`  Error: ${err.message}`));
       }
+    } finally {
+      this.isProcessing = false;
+      this.flushPendingNotifications();
     }
   }
   printHeader() {
     console.log("");
     console.log(chalk8.bold.cyan(`  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557`));
-    console.log(chalk8.bold.cyan(`  \u2551`) + chalk8.bold(`     Vultisig Agent - ${this.vaultName}`.padEnd(38).slice(0, 38)) + chalk8.bold.cyan(`\u2551`));
+    console.log(
+      chalk8.bold.cyan(`  \u2551`) + chalk8.bold(`     Vultisig Agent - ${this.vaultName}`.padEnd(38).slice(0, 38)) + chalk8.bold.cyan(`\u2551`)
+    );
     console.log(chalk8.bold.cyan(`  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D`));
     console.log("");
   }
@@ -6991,7 +7183,8 @@ async function executeAgent(ctx2, options) {
     password: options.password,
     viaAgent: options.viaAgent,
     sessionId: options.sessionId,
-    verbose: options.verbose
+    verbose: options.verbose,
+    notificationUrl: options.notificationUrl || process.env.VULTISIG_NOTIFICATION_URL || ""
   };
   const session = new AgentSession(vault, config);
   if (options.viaAgent) {
@@ -7153,6 +7346,49 @@ function formatDate(iso) {
   }
 }
 
+// src/core/server-endpoints.ts
+function firstNonEmpty(...values) {
+  return values.find((value) => typeof value === "string" && value.trim() !== "");
+}
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function joinEndpoint(baseUrl, path4) {
+  return `${stripTrailingSlash(baseUrl)}${path4}`;
+}
+function resolveServerEndpoints(overrides = {}) {
+  const serverUrl = firstNonEmpty(overrides.serverUrl, process.env.VULTISIG_SERVER_URL);
+  if (!serverUrl) {
+    return void 0;
+  }
+  return {
+    fastVault: stripTrailingSlash(joinEndpoint(serverUrl, "/vault")),
+    messageRelay: stripTrailingSlash(joinEndpoint(serverUrl, "/router"))
+  };
+}
+function parseServerEndpointOverridesFromArgv(args) {
+  return {
+    serverUrl: readArgValue(args, "--server-url")
+  };
+}
+function readArgValue(args, optionName) {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === optionName) {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        return void 0;
+      }
+      return next;
+    }
+    if (arg.startsWith(`${optionName}=`)) {
+      const value = arg.slice(optionName.length + 1);
+      return value.trim() === "" ? void 0 : value;
+    }
+  }
+  return void 0;
+}
+
 // src/interactive/completer.ts
 import { Chain as Chain10 } from "@vultisig/sdk";
 import fs3 from "fs";
@@ -8558,7 +8794,7 @@ var cachedVersion = null;
 function getVersion() {
   if (cachedVersion) return cachedVersion;
   if (true) {
-    cachedVersion = "0.12.0";
+    cachedVersion = "0.14.2";
     return cachedVersion;
   }
   try {
@@ -9031,7 +9267,7 @@ setupUserAgent();
   if (handled) process.exit(0);
 })();
 var ctx;
-program.name("vultisig").description("Vultisig CLI - Secure multi-party crypto wallet").version(formatVersionShort(), "-v, --version", "Show version").option("--debug", "Enable debug output").option("--silent", "Suppress informational output, show only results").option("-o, --output <format>", "Output format: table, json (default: table)", "table").option("-i, --interactive", "Start interactive shell mode").option("--vault <nameOrId>", "Specify vault by name or ID").hook("preAction", (thisCommand) => {
+program.name("vultisig").description("Vultisig CLI - Secure multi-party crypto wallet").version(formatVersionShort(), "-v, --version", "Show version").option("--debug", "Enable debug output").option("--silent", "Suppress informational output, show only results").option("-o, --output <format>", "Output format: table, json (default: table)", "table").option("-i, --interactive", "Start interactive shell mode").option("--vault <nameOrId>", "Specify vault by name or ID").option("--server-url <url>", "Base Vultisig API URL for FastVault and relay endpoints").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
   initOutputMode({ silent: opts.silent, output: opts.output });
 });
@@ -9051,8 +9287,11 @@ async function init(vaultOverride, unlockPassword, passwordTTL) {
     if (unlockPassword && vaultSelector) {
       cachePassword(vaultSelector, unlockPassword);
     }
+    const globalOptions = program.opts();
+    const serverEndpoints = resolveServerEndpoints(globalOptions);
     const sdk = new Vultisig7({
       onPasswordRequired: createPasswordCallback(),
+      ...serverEndpoints ? { serverEndpoints } : {},
       ...passwordTTL !== void 0 ? { passwordCache: { defaultTTL: passwordTTL } } : {}
     });
     await sdk.initialize();
@@ -9570,34 +9809,36 @@ rujiraCmd.command("withdraw <asset> <amount> <l1Address>").description("Withdraw
     }
   )
 );
-var agentCmd = program.command("agent").description("AI-powered chat interface for wallet operations").option("--via-agent", "Use NDJSON pipe mode for agent-to-agent communication").option("--verbose", "Show detailed tool call parameters and debug output").option("--backend-url <url>", "Agent backend URL (default: https://abe.vultisig.com)").option("--password <password>", "Vault password for signing operations").option("--password-ttl <ms>", "Password cache TTL in milliseconds (default: 300000, 86400000/24h for --via-agent)").option("--session-id <id>", "Resume an existing session").action(async (options) => {
-  const MAX_TTL = 864e5;
-  let passwordTTL;
-  if (options.passwordTtl) {
-    const parsed = parseInt(options.passwordTtl, 10);
-    if (Number.isNaN(parsed) || parsed < 0) {
-      throw new Error(`Invalid --password-ttl value: "${options.passwordTtl}". Expected a non-negative integer in milliseconds.`);
-    }
-    passwordTTL = parsed;
-  } else if (options.viaAgent) {
-    passwordTTL = MAX_TTL;
-  }
-  const context = await init(program.opts().vault, options.password, passwordTTL);
-  await executeAgent(context, {
-    viaAgent: options.viaAgent,
-    verbose: options.verbose,
-    backendUrl: options.backendUrl,
-    password: options.password,
-    sessionId: options.sessionId
-  });
-});
+var agentCmd = program.command("agent").description("AI-powered chat interface for wallet operations").option("--via-agent", "Use NDJSON pipe mode for agent-to-agent communication").option("--verbose", "Show detailed tool call parameters and debug output").option("--backend-url <url>", "Agent backend URL (default: https://abe.vultisig.com)").option("--password <password>", "Vault password for signing operations").option("--password-ttl <ms>", "Password cache TTL in milliseconds (default: 300000, 86400000/24h for --via-agent)").option("--session-id <id>", "Resume an existing session").option("--notification-url <url>", "Notification service URL for push notifications").action(
+  async (options) => {
+    const MAX_TTL = 864e5;
+    let passwordTTL;
+    if (options.passwordTtl) {
+      const parsed = parseInt(options.passwordTtl, 10);
+      if (Number.isNaN(parsed) || parsed < 0) {
+        throw new Error(
+          `Invalid --password-ttl value: "${options.passwordTtl}". Expected a non-negative integer in milliseconds.`
+        );
+      }
+      passwordTTL = parsed;
+    } else if (options.viaAgent) {
+      passwordTTL = MAX_TTL;
+    }
+    const context = await init(program.opts().vault, options.password, passwordTTL);
+    await executeAgent(context, {
+      viaAgent: options.viaAgent,
+      verbose: options.verbose,
+      backendUrl: options.backendUrl,
+      password: options.password,
+      sessionId: options.sessionId,
+      notificationUrl: options.notificationUrl
+    });
+  }
+);
 agentCmd.command("ask <message>").description("Send a single message and get the response (for AI agent integration)").option("--session <id>", "Continue an existing conversation").option("--backend-url <url>", "Agent backend URL (default: https://abe.vultisig.com)").option("--password <password>", "Vault password for signing operations").option("--verbose", "Show tool calls and debug info on stderr").option("--json", "Output structured JSON instead of text").action(
   async (message, options) => {
     const parentOpts = agentCmd.opts();
-    const context = await init(
-      program.opts().vault,
-      options.password || parentOpts.password
-    );
+    const context = await init(program.opts().vault, options.password || parentOpts.password);
     await executeAgentAsk(context, message, {
       ...options,
       backendUrl: options.backendUrl || parentOpts.backendUrl,
@@ -9664,8 +9905,10 @@ 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({
-    onPasswordRequired: createPasswordCallback()
+    onPasswordRequired: createPasswordCallback(),
+    ...serverEndpoints ? { serverEndpoints } : {}
   });
   await sdk.initialize();
   const session = new ShellSession(sdk);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vultisig/cli",
-  "version": "0.12.0",
+  "version": "0.14.2",
   "description": "Command-line wallet for Vultisig - multi-chain MPC wallet management",
   "type": "module",
   "bin": {
@@ -53,8 +53,8 @@
     "@cosmjs/proto-signing": "^0.38.1",
     "@cosmjs/stargate": "^0.38.1",
     "@noble/hashes": "^2.0.1",
-    "@vultisig/rujira": "^8.0.0",
-    "@vultisig/sdk": "^0.12.0",
+    "@vultisig/rujira": "^9.0.0",
+    "@vultisig/sdk": "^0.14.1",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",