@blockrun/mcp 0.23.2 → 0.24.0

package/dist/index.js

@@ -7,8 +7,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/utils/wallet.ts
 import fs from "fs";
-import path from "path";
-import os from "os";
+import path2 from "path";
+import os2 from "os";
 import {
   LLMClient,
   ImageClient,
@@ -23,10 +23,39 @@ import {
   formatNeedsFundingMessage,
   SOLANA_WALLET_FILE_PATH
 } from "@blockrun/llm";
-var BLOCKRUN_DIR = path.join(os.homedir(), ".blockrun");
+
+// src/utils/constants.ts
+import * as path from "path";
+import * as os from "os";
+var WALLET_DIR = path.join(os.homedir(), ".blockrun");
+var WALLET_FILE = path.join(WALLET_DIR, ".session");
+var QR_FILE = path.join(WALLET_DIR, "qr.png");
+var USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var BASE_CHAIN_ID = "8453";
+var BASE_RPC_URLS = [
+  "https://mainnet.base.org",
+  "https://base.llamarpc.com",
+  "https://1rpc.io/base"
+];
+var MODEL_TIERS = {
+  fast: ["google/gemini-3.5-flash", "google/gemini-2.5-flash", "google/gemini-3.1-flash-lite", "openai/gpt-5-mini", "deepseek/deepseek-chat", "google/gemini-3-flash-preview"],
+  balanced: ["openai/gpt-5.5", "anthropic/claude-sonnet-4.6", "google/gemini-3.1-pro", "moonshot/kimi-k2.6", "openai/gpt-5.3", "openai/gpt-5.4"],
+  powerful: ["anthropic/claude-opus-4.8", "openai/gpt-5.4-pro", "anthropic/claude-opus-4.7", "anthropic/claude-opus-4.6", "openai/o3", "openai/gpt-5.4"],
+  cheap: ["zai/glm-5", "zai/glm-5-turbo", "nvidia/gpt-oss-120b", "nvidia/deepseek-v4-flash", "google/gemini-2.5-flash", "deepseek/deepseek-chat", "openai/gpt-5.4-nano"],
+  reasoning: ["anthropic/claude-opus-4.8", "openai/o3", "openai/o1", "openai/o3-mini", "deepseek/deepseek-reasoner", "moonshot/kimi-k2.6", "openai/gpt-5.3-codex"],
+  // 2026-06-07 sweep: dropped qwen3-next (NVIDIA EOL, 410), mistral-small-4-119b
+  // (timing out), deepseek-v3.2 + glm-4.7 (NIM hung). All redirect server-side
+  // anyway; these are the free models actually serving themselves.
+  free: ["nvidia/llama-4-maverick", "nvidia/qwen3-coder-480b", "nvidia/deepseek-v4-flash", "nvidia/gpt-oss-120b", "nvidia/gpt-oss-20b"],
+  coding: ["anthropic/claude-opus-4.8", "zai/glm-5", "openai/gpt-5.3-codex", "moonshot/kimi-k2.6", "nvidia/qwen3-coder-480b", "anthropic/claude-sonnet-4.6", "openai/gpt-5.4"],
+  glm: ["zai/glm-5", "zai/glm-5-turbo"]
+};
+
+// src/utils/wallet.ts
+var BLOCKRUN_DIR = path2.join(os2.homedir(), ".blockrun");
 var CHAIN_PREFERENCE_FILES = [
-  path.join(BLOCKRUN_DIR, ".chain"),
-  path.join(BLOCKRUN_DIR, "payment-chain")
+  path2.join(BLOCKRUN_DIR, ".chain"),
+  path2.join(BLOCKRUN_DIR, "payment-chain")
 ];
 var _evmClient = null;
 var _imageClient = null;
@@ -56,7 +85,7 @@ function getChain() {
   }
   return "base";
 }
-var CHAIN_FILE = path.join(BLOCKRUN_DIR, ".chain");
+var CHAIN_FILE = path2.join(BLOCKRUN_DIR, ".chain");
 function resetChainCaches() {
   _evmClient = null;
   _solanaClient = null;
@@ -185,17 +214,15 @@ async function getSolanaUsdcBalance() {
     return null;
   }
 }
+function parseBaseUsdcCallResult(raw) {
+  if (typeof raw !== "string" || !/^0x[0-9a-fA-F]+$/.test(raw)) return null;
+  return Number(BigInt(raw)) / 1e6;
+}
 async function getBaseUsdcBalance(address) {
-  const USDC_ADDRESS2 = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
-  const BASE_RPC_URLS = [
-    "https://mainnet.base.org",
-    "https://base.llamarpc.com",
-    "https://1rpc.io/base"
-  ];
   const data = {
     jsonrpc: "2.0",
     method: "eth_call",
-    params: [{ to: USDC_ADDRESS2, data: `0x70a08231000000000000000000000000${address.slice(2)}` }, "latest"],
+    params: [{ to: USDC_ADDRESS, data: `0x70a08231000000000000000000000000${address.slice(2)}` }, "latest"],
     id: 1
   };
   for (const rpcUrl of BASE_RPC_URLS) {
@@ -206,7 +233,8 @@ async function getBaseUsdcBalance(address) {
         body: JSON.stringify(data)
       });
       const result = await response.json();
-      if (result.result) return parseInt(result.result, 16) / 1e6;
+      const usd = parseBaseUsdcCallResult(result.result);
+      if (usd !== null) return usd;
     } catch {
       continue;
     }
@@ -255,6 +283,25 @@ function checkBudget(budget, agentId, estimatedCost = 1e-3) {
   }
   return { allowed: true };
 }
+function reserveBudget(budget, agentId, estimatedCost = 1e-3) {
+  const check = checkBudget(budget, agentId, estimatedCost);
+  if (!check.allowed) return { allowed: false, reason: check.reason, release: () => {
+  } };
+  const cost = Math.max(0, estimatedCost);
+  budget.spent += cost;
+  const agentBudget = agentId ? budget.agents.get(agentId) : void 0;
+  if (agentBudget) agentBudget.spent += cost;
+  let released = false;
+  return {
+    allowed: true,
+    release: () => {
+      if (released) return;
+      released = true;
+      budget.spent -= cost;
+      if (agentBudget) agentBudget.spent -= cost;
+    }
+  };
+}
 function recordSpending(budget, cost, agentId) {
   budget.spent += cost;
   budget.calls += 1;
@@ -289,30 +336,6 @@ import QRCode from "qrcode";
 import open from "open";
 import * as fs2 from "fs";
 import * as path3 from "path";
-
-// src/utils/constants.ts
-import * as path2 from "path";
-import * as os2 from "os";
-var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
-var WALLET_FILE = path2.join(WALLET_DIR, ".session");
-var QR_FILE = path2.join(WALLET_DIR, "qr.png");
-var USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
-var BASE_CHAIN_ID = "8453";
-var MODEL_TIERS = {
-  fast: ["google/gemini-3.5-flash", "google/gemini-2.5-flash", "google/gemini-3.1-flash-lite", "openai/gpt-5-mini", "deepseek/deepseek-chat", "google/gemini-3-flash-preview"],
-  balanced: ["openai/gpt-5.5", "anthropic/claude-sonnet-4.6", "google/gemini-3.1-pro", "moonshot/kimi-k2.6", "openai/gpt-5.3", "openai/gpt-5.4"],
-  powerful: ["anthropic/claude-opus-4.8", "openai/gpt-5.4-pro", "anthropic/claude-opus-4.7", "anthropic/claude-opus-4.6", "openai/o3", "openai/gpt-5.4"],
-  cheap: ["zai/glm-5", "zai/glm-5-turbo", "nvidia/gpt-oss-120b", "nvidia/deepseek-v4-flash", "google/gemini-2.5-flash", "deepseek/deepseek-chat", "openai/gpt-5.4-nano"],
-  reasoning: ["anthropic/claude-opus-4.8", "openai/o3", "openai/o1", "openai/o3-mini", "deepseek/deepseek-reasoner", "moonshot/kimi-k2.6", "openai/gpt-5.3-codex"],
-  // 2026-06-07 sweep: dropped qwen3-next (NVIDIA EOL, 410), mistral-small-4-119b
-  // (timing out), deepseek-v3.2 + glm-4.7 (NIM hung). All redirect server-side
-  // anyway; these are the free models actually serving themselves.
-  free: ["nvidia/llama-4-maverick", "nvidia/qwen3-coder-480b", "nvidia/deepseek-v4-flash", "nvidia/gpt-oss-120b", "nvidia/gpt-oss-20b"],
-  coding: ["anthropic/claude-opus-4.8", "zai/glm-5", "openai/gpt-5.3-codex", "moonshot/kimi-k2.6", "nvidia/qwen3-coder-480b", "anthropic/claude-sonnet-4.6", "openai/gpt-5.4"],
-  glm: ["zai/glm-5", "zai/glm-5-turbo"]
-};
-
-// src/utils/qr.ts
 var SOLANA_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
 var sharpModule;
 async function loadSharp() {
@@ -423,9 +446,13 @@ ${parts.join("\n")}`;
   }
   return base;
 }
+function isPaymentRejectionError(message) {
+  const m = message.toLowerCase();
+  return m.includes("insufficient") || m.includes("balance") || m.includes("rejected");
+}
 function formatError(message, opts) {
   const msgLower = message.toLowerCase();
-  const hasStatus = (code) => new RegExp(`(^|[^0-9.])${code}([^0-9]|$)`).test(msgLower);
+  const hasStatus = (code) => new RegExp(`(^|[^0-9.])${code}($|[^0-9.])`).test(msgLower);
   const isPaymentError = hasStatus("402") || msgLower.includes("balance") || msgLower.includes("insufficient") || msgLower.includes("payment") && !hasStatus("500");
   const isModelUnavailable = msgLower.includes("not active for requested provider") || msgLower.includes("not found or not active");
   const isServerError = hasStatus("500") || msgLower.includes("api error after payment");
@@ -814,6 +841,7 @@ async function handleAnthropicNative(args) {
     temperature,
     stop,
     thinking,
+    responseFormat,
     budget,
     agentId,
     estimatedCost
@@ -829,6 +857,9 @@ async function handleAnthropicNative(args) {
     }
     apiMessages.push({ role: m.role, content: toAnthropicContent(m.content) });
   }
+  if (responseFormat?.type === "json_object") {
+    systemParts.push("Respond with only valid JSON. Do not wrap it in markdown code fences or add any prose before or after.");
+  }
   if (message.trim()) apiMessages.push({ role: "user", content: message });
   if (apiMessages.length === 0) {
     return { content: [{ type: "text", text: "No message content to send." }], isError: true };
@@ -898,7 +929,6 @@ ${thinkingText}` });
 function estimateChatCost(maxTokens, mode, model, routing, routingProfile) {
   if (mode === "free") return 0;
   if (model?.startsWith("nvidia/")) return 0;
-  if (routing === "smart" && routingProfile === "free") return 0;
   const out = Math.max(maxTokens ?? 1024, 256);
   const frontierReserve = Math.max(0.01, out / 1e6 * 20);
   if (routing === "smart") {
@@ -944,7 +974,7 @@ Run blockrun_models to see all available models with pricing.`,
         model: z2.string().optional().describe("Specific model ID (e.g., 'zai/glm-5', 'openai/o3')"),
         mode: z2.enum(["fast", "balanced", "powerful", "cheap", "reasoning", "free", "coding", "glm"]).optional().describe("Routing mode: glm = Zhipu GLM-5/GLM-5-Turbo ($0.001/call, great for coding), coding = GLM-5 + code models, cheap = GLM-5 + budget, free = NVIDIA only (ignored if model specified)"),
         routing: z2.enum(["smart"]).optional().describe('Set to "smart" to auto-select the optimal model via ClawRouter (14-dimension AI routing)'),
-        routing_profile: z2.enum(["free", "eco", "auto", "premium"]).optional().default("auto").describe('Cost/quality profile for ClawRouter: "free" (zero cost NVIDIA), "eco" (budget), "auto" (balanced, default), "premium" (best quality) (only applies when routing: "smart")'),
+        routing_profile: z2.enum(["free", "eco", "auto", "premium"]).optional().default("auto").describe('Cost/quality profile for ClawRouter: "eco" (budget), "auto" (balanced, default), "premium" (best quality). Note: "free" maps to "auto" (the SDK dropped the free profile) and still settles a PAID model \u2014 for zero-cost generation use mode:"free" or model:"nvidia/...". Only applies when routing:"smart".'),
         system: z2.string().optional().describe("Optional system prompt"),
         max_tokens: z2.number().optional().default(1024).describe("Max tokens in response"),
         temperature: z2.number().optional().default(1).describe("Creativity 0-2"),
@@ -971,141 +1001,152 @@ Run blockrun_models to see all available models with pricing.`,
       const llm = getClient();
       const responseFormat = response_format ? { type: response_format } : void 0;
       const estimatedCost = estimateChatCost(max_tokens, mode, model, routing, routing_profile);
-      const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-      if (!budgetCheck.allowed) {
+      const gate = reserveBudget(budget, agent_id, estimatedCost);
+      if (!gate.allowed) {
         return {
-          content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet with action: "report" to see usage, or action: "delegate" to increase agent budget.` }],
+          content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet with action: "report" to see usage, or action: "delegate" to increase agent budget.` }],
           isError: true
         };
       }
-      if (model && isAnthropicModel(model)) {
-        const solanaBlock = baseOnlyMessage("Native Anthropic (claude-*) calls");
-        if (solanaBlock) {
-          return { content: [{ type: "text", text: solanaBlock }], isError: true };
-        }
-        return handleAnthropicNative({
-          client: getAnthropicClient(),
-          model,
-          message,
-          system,
-          messages,
-          maxTokens: max_tokens,
-          temperature,
-          stop,
-          thinking,
-          budget,
-          agentId: agent_id,
-          estimatedCost
-        });
-      }
-      if (routing === "smart") {
-        if (!(llm instanceof LLMClient2)) {
-          return {
-            content: [{ type: "text", text: "Smart routing (ClawRouter) is not available on Solana. Use a specific model or mode instead." }],
-            isError: true
-          };
-        }
-        try {
-          const { result, settledUsd } = await withSettledCost(llm, () => llm.smartChat(message, {
+      try {
+        if (model && isAnthropicModel(model)) {
+          const solanaBlock = baseOnlyMessage("Native Anthropic (claude-*) calls");
+          if (solanaBlock) {
+            return { content: [{ type: "text", text: solanaBlock }], isError: true };
+          }
+          return await handleAnthropicNative({
+            client: getAnthropicClient(),
+            model,
+            message,
             system,
+            messages,
             maxTokens: max_tokens,
-            maxOutputTokens: max_tokens,
             temperature,
-            // @blockrun/llm 2.x dropped the "free" routing profile; the gateway
-            // already routes to the most cost-effective model by default, so we
-            // omit it and let ClawRouter pick (matches the SDK upgrade path).
-            routingProfile: routing_profile === "free" ? void 0 : routing_profile,
+            stop,
+            thinking,
             responseFormat,
-            stop
-          }));
-          recordActualSpend(budget, settledUsd, result.routing.costEstimate || estimatedCost, agent_id);
-          return {
-            content: [{ type: "text", text: `[${result.model} | ${result.routing.tier} | $${result.routing.costEstimate.toFixed(4)} | ${Math.round((result.routing.savings ?? 0) * 100)}% savings]
+            budget,
+            agentId: agent_id,
+            estimatedCost
+          });
+        }
+        if (routing === "smart") {
+          if (messages && messages.length > 0) {
+            return {
+              content: [{ type: "text", text: formatError('routing:"smart" does not support multi-turn `messages` \u2014 smart routing answers a single prompt. Send the conversation via `messages` with an explicit `model`/`mode` (no routing), or send a single `message` with routing:"smart".') }],
+              isError: true
+            };
+          }
+          if (!(llm instanceof LLMClient2)) {
+            return {
+              content: [{ type: "text", text: "Smart routing (ClawRouter) is not available on Solana. Use a specific model or mode instead." }],
+              isError: true
+            };
+          }
+          try {
+            const { result, settledUsd } = await withSettledCost(llm, () => llm.smartChat(message, {
+              system,
+              maxTokens: max_tokens,
+              maxOutputTokens: max_tokens,
+              temperature,
+              // @blockrun/llm 2.x dropped the "free" routing profile; the gateway
+              // already routes to the most cost-effective model by default, so we
+              // omit it and let ClawRouter pick (matches the SDK upgrade path).
+              routingProfile: routing_profile === "free" ? void 0 : routing_profile,
+              responseFormat,
+              stop
+            }));
+            recordActualSpend(budget, settledUsd, result.routing.costEstimate || estimatedCost, agent_id);
+            return {
+              content: [{ type: "text", text: `[${result.model} | ${result.routing.tier} | $${result.routing.costEstimate.toFixed(4)} | ${Math.round((result.routing.savings ?? 0) * 100)}% savings]
 
 ${result.response}` }],
-            structuredContent: {
-              model_used: result.model,
-              response: result.response,
-              routing: result.routing
-            }
-          };
-        } catch (error) {
-          return { content: [{ type: "text", text: formatError(extractErrorMessage(error)) }], isError: true };
+              structuredContent: {
+                model_used: result.model,
+                response: result.response,
+                routing: result.routing
+              }
+            };
+          } catch (error) {
+            return { content: [{ type: "text", text: formatError(extractErrorMessage(error)) }], isError: true };
+          }
         }
-      }
-      if (messages && messages.length > 0) {
-        const targetModel = model || MODEL_TIERS[mode ?? "balanced"]?.[0] || "openai/gpt-5.5";
-        const fullMessages = [
-          ...system ? [{ role: "system", content: system }] : [],
-          ...messages,
-          { role: "user", content: message }
-        ];
-        try {
-          const { result, settledUsd } = await withSettledCost(llm, () => llm.chatCompletion(targetModel, fullMessages, {
-            maxTokens: max_tokens,
-            temperature,
-            responseFormat,
-            stop
-          }));
-          const reply = result.choices?.[0]?.message?.content || "";
-          recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
-          return {
-            content: [{ type: "text", text: `[${targetModel} | ${fullMessages.length} msgs]
+        if (messages && messages.length > 0) {
+          const targetModel = model || MODEL_TIERS[mode ?? "balanced"]?.[0] || "openai/gpt-5.5";
+          const fullMessages = [
+            ...system ? [{ role: "system", content: system }] : [],
+            ...messages,
+            { role: "user", content: message }
+          ];
+          try {
+            const { result, settledUsd } = await withSettledCost(llm, () => llm.chatCompletion(targetModel, fullMessages, {
+              maxTokens: max_tokens,
+              temperature,
+              responseFormat,
+              stop
+            }));
+            const reply = result.choices?.[0]?.message?.content || "";
+            recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
+            return {
+              content: [{ type: "text", text: `[${targetModel} | ${fullMessages.length} msgs]
 
 ${reply}` }],
-            structuredContent: { model_used: targetModel, response: reply, message_count: fullMessages.length }
-          };
-        } catch (error) {
-          return { content: [{ type: "text", text: formatError(extractErrorMessage(error)) }], isError: true };
+              structuredContent: { model_used: targetModel, response: reply, message_count: fullMessages.length }
+            };
+          } catch (error) {
+            return { content: [{ type: "text", text: formatError(extractErrorMessage(error)) }], isError: true };
+          }
         }
-      }
-      if (model) {
-        try {
-          const { result: response, settledUsd } = await withSettledCost(llm, () => llm.chat(model, message, {
-            system,
-            maxTokens: max_tokens,
-            temperature,
-            responseFormat,
-            stop
-          }));
-          recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
-          return { content: [{ type: "text", text: response }] };
-        } catch (error) {
-          return {
-            content: [{ type: "text", text: formatError(extractErrorMessage(error)) }],
-            isError: true
-          };
+        if (model) {
+          try {
+            const { result: response, settledUsd } = await withSettledCost(llm, () => llm.chat(model, message, {
+              system,
+              maxTokens: max_tokens,
+              temperature,
+              responseFormat,
+              stop
+            }));
+            recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
+            return { content: [{ type: "text", text: response }] };
+          } catch (error) {
+            return {
+              content: [{ type: "text", text: formatError(extractErrorMessage(error)) }],
+              isError: true
+            };
+          }
         }
-      }
-      const routingMode = mode || "balanced";
-      const models = MODEL_TIERS[routingMode];
-      let lastError = null;
-      for (const m of models) {
-        try {
-          const { result: response, settledUsd } = await withSettledCost(llm, () => llm.chat(m, message, {
-            system,
-            maxTokens: max_tokens,
-            temperature,
-            responseFormat,
-            stop
-          }));
-          recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
-          return {
-            content: [{ type: "text", text: `[${m}]
+        const routingMode = mode || "balanced";
+        const models = MODEL_TIERS[routingMode];
+        let lastError = null;
+        for (const m of models) {
+          try {
+            const { result: response, settledUsd } = await withSettledCost(llm, () => llm.chat(m, message, {
+              system,
+              maxTokens: max_tokens,
+              temperature,
+              responseFormat,
+              stop
+            }));
+            recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
+            return {
+              content: [{ type: "text", text: `[${m}]
 
 ${response}` }],
-            structuredContent: { model_used: m, response }
-          };
-        } catch (error) {
-          lastError = error;
-          continue;
+              structuredContent: { model_used: m, response }
+            };
+          } catch (error) {
+            lastError = error;
+            continue;
+          }
         }
+        const errorMessage = lastError ? extractErrorMessage(lastError) : "All models failed";
+        return {
+          content: [{ type: "text", text: formatError(errorMessage) }],
+          isError: true
+        };
+      } finally {
+        gate.release();
       }
-      const errorMessage = lastError ? extractErrorMessage(lastError) : "All models failed";
-      return {
-        content: [{ type: "text", text: formatError(errorMessage) }],
-        isError: true
-      };
     }
   );
 }
@@ -1193,6 +1234,10 @@ async function toImageDataUri(ref) {
       if (!res.ok) throw new Error(`fetch failed: ${res.status} ${res.statusText}`);
       const mime2 = (res.headers.get("content-type") || "").toLowerCase().split(";")[0].trim();
       if (!mime2.startsWith("image/")) throw new Error(`URL returned non-image content-type: ${mime2 || "(none)"}`);
+      const advertised = Number(res.headers.get("content-length"));
+      if (Number.isFinite(advertised) && advertised > REFERENCE_IMAGE_MAX_BYTES) {
+        throw new Error(`image too large: ${(advertised / 1e6).toFixed(1)}MB > ${REFERENCE_IMAGE_MAX_BYTES / 1e6}MB cap`);
+      }
       const buffer2 = Buffer.from(await res.arrayBuffer());
       if (buffer2.byteLength > REFERENCE_IMAGE_MAX_BYTES) {
         throw new Error(`image too large: ${(buffer2.byteLength / 1e6).toFixed(1)}MB > ${REFERENCE_IMAGE_MAX_BYTES / 1e6}MB cap`);
@@ -1349,34 +1394,42 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
             };
           }
           const estimatedCost = estimateCost(selectedModel, size);
-          const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-          if (!budgetCheck.allowed) {
+          const gate = reserveBudget(budget, agent_id, estimatedCost);
+          if (!gate.allowed) {
             return {
-              content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+              content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
               isError: true
             };
           }
-          response = await getImageClient().edit(prompt, normalizedImage, {
-            model: selectedModel,
-            size,
-            ...normalizedMask ? { mask: normalizedMask } : {}
-          });
-          recordSpending(budget, estimatedCost, agent_id);
+          try {
+            response = await getImageClient().edit(prompt, normalizedImage, {
+              model: selectedModel,
+              size,
+              ...normalizedMask ? { mask: normalizedMask } : {}
+            });
+            recordSpending(budget, estimatedCost, agent_id);
+          } finally {
+            gate.release();
+          }
         } else {
           const estimatedCost = estimateCost(selectedModel, size);
-          const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-          if (!budgetCheck.allowed) {
+          const gate = reserveBudget(budget, agent_id, estimatedCost);
+          if (!gate.allowed) {
             return {
-              content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+              content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
               isError: true
             };
           }
-          response = await getImageClient().generate(prompt, {
-            model: selectedModel,
-            size,
-            quality
-          });
-          recordSpending(budget, estimatedCost, agent_id);
+          try {
+            response = await getImageClient().generate(prompt, {
+              model: selectedModel,
+              size,
+              quality
+            });
+            recordSpending(budget, estimatedCost, agent_id);
+          } finally {
+            gate.release();
+          }
         }
         const imageUrl = response.data?.[0]?.url;
         if (!imageUrl) {
@@ -1417,11 +1470,7 @@ async function fetchWithTimeout(url, options, timeoutMs) {
   const controller = new AbortController();
   const id = setTimeout(() => controller.abort(), timeoutMs);
   id.unref?.();
-  try {
-    return await fetch(url, { ...options, signal: controller.signal });
-  } finally {
-    clearTimeout(id);
-  }
+  return await fetch(url, { ...options, signal: controller.signal });
 }
 function isTimeoutError(err) {
   const name = err instanceof Error ? err.name : "";
@@ -1460,6 +1509,7 @@ Returns a time-limited CDN URL \u2014 download immediately if you need to keep t
       }
     },
     async ({ prompt, instrumental, lyrics, model, agent_id }) => {
+      let gate;
       try {
         if (getChain() !== "base") {
           return {
@@ -1473,10 +1523,10 @@ Returns a time-limited CDN URL \u2014 download immediately if you need to keep t
             isError: true
           };
         }
-        const budgetCheck = checkBudget(budget, agent_id, MUSIC_COST);
-        if (!budgetCheck.allowed) {
+        gate = reserveBudget(budget, agent_id, MUSIC_COST);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
@@ -1491,8 +1541,8 @@ Returns a time-limited CDN URL \u2014 download immediately if you need to keep t
           body: JSON.stringify(body)
         }, 15e3);
         if (resp402.status !== 402) {
-          const data2 = await resp402.json();
-          throw new Error(`Expected 402, got ${resp402.status}: ${JSON.stringify(data2)}`);
+          const data2 = await resp402.json().catch(() => ({}));
+          throw new Error(`Unexpected status ${resp402.status} (the endpoint did not return a quote): ${JSON.stringify(data2)}`);
         }
         const prHeader = resp402.headers.get("payment-required") || resp402.headers.get("PAYMENT-REQUIRED");
         if (!prHeader) throw new Error("No PAYMENT-REQUIRED header in 402 response");
@@ -1553,7 +1603,7 @@ Returns a time-limited CDN URL \u2014 download immediately if you need to keep t
         };
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        if (errMsg.includes("balance") || errMsg.includes("payment") || errMsg.includes("402") || errMsg.includes("rejected")) {
+        if (isPaymentRejectionError(errMsg)) {
           return {
             content: [{ type: "text", text: `Music generation requires payment. Run blockrun_wallet with action: "setup" for funding instructions.
 Error: ${errMsg}` }],
@@ -1571,6 +1621,8 @@ Error: ${errMsg}` }],
           content: [{ type: "text", text: formatError(`Music generation failed: ${errMsg}`) }],
           isError: true
         };
+      } finally {
+        gate?.release();
       }
     }
   );
@@ -1640,6 +1692,7 @@ Returns a hosted audio URL \u2014 download immediately if you need to keep the f
       }
     },
     async ({ action, input, voice, model, response_format, speed, duration_seconds, prompt_influence, agent_id }) => {
+      let gate;
       try {
         if (action === "voices") {
           return await listVoices();
@@ -1684,10 +1737,10 @@ Returns a hosted audio URL \u2014 download immediately if you need to keep the f
           if (speed !== void 0) body.speed = speed;
           cost = speechCost(model, input.length);
         }
-        const budgetCheck = checkBudget(budget, agent_id, cost);
-        if (!budgetCheck.allowed) {
+        gate = reserveBudget(budget, agent_id, cost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
@@ -1700,7 +1753,7 @@ Returns a hosted audio URL \u2014 download immediately if you need to keep the f
         }, 15e3);
         if (resp402.status !== 402) {
           const data2 = await resp402.json().catch(() => ({}));
-          throw new Error(`Expected 402, got ${resp402.status}: ${JSON.stringify(data2)}`);
+          throw new Error(`Unexpected status ${resp402.status} (the endpoint did not return a quote): ${JSON.stringify(data2)}`);
         }
         const prHeader = resp402.headers.get("payment-required") || resp402.headers.get("PAYMENT-REQUIRED");
         if (!prHeader) throw new Error("No PAYMENT-REQUIRED header in 402 response");
@@ -1766,7 +1819,7 @@ Returns a hosted audio URL \u2014 download immediately if you need to keep the f
         };
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        if (errMsg.includes("balance") || errMsg.includes("payment") || errMsg.includes("402") || errMsg.includes("rejected")) {
+        if (isPaymentRejectionError(errMsg)) {
           return {
             content: [{ type: "text", text: `Speech generation requires payment. Run blockrun_wallet with action: "setup" for funding instructions.
 Error: ${errMsg}` }],
@@ -1784,6 +1837,8 @@ Error: ${errMsg}` }],
           content: [{ type: "text", text: formatError(`Speech generation failed: ${errMsg}`) }],
           isError: true
         };
+      } finally {
+        gate?.release();
       }
     }
   );
@@ -1884,6 +1939,7 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
       }
     },
     async ({ prompt, image_url, real_face_asset_id, duration_seconds, generate_audio, resolution, aspect_ratio, last_frame_url, model, agent_id }) => {
+      let gate;
       try {
         if (getChain() !== "base") {
           return {
@@ -1924,10 +1980,10 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
         const hasImageInput = Boolean(image_url || real_face_asset_id);
         const perSecond = (hasImageInput ? VIDEO_PRICE_PER_SECOND_IMAGE[selectedModel] : void 0) ?? VIDEO_PRICE_PER_SECOND[selectedModel] ?? 0.05;
         const estimatedCost = perSecond * billedSeconds;
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
@@ -1948,8 +2004,8 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
           body: JSON.stringify(body)
         }, 15e3);
         if (resp402.status !== 402) {
-          const data = await resp402.json();
-          throw new Error(`Expected 402, got ${resp402.status}: ${JSON.stringify(data)}`);
+          const data = await resp402.json().catch(() => ({}));
+          throw new Error(`Unexpected status ${resp402.status} (the endpoint did not return a quote): ${JSON.stringify(data)}`);
         }
         const prHeader = resp402.headers.get("payment-required") || resp402.headers.get("PAYMENT-REQUIRED");
         if (!prHeader) throw new Error("No PAYMENT-REQUIRED header in 402 response");
@@ -2053,7 +2109,7 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
         };
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        if (errMsg.includes("balance") || errMsg.includes("payment") || errMsg.includes("402") || errMsg.includes("rejected")) {
+        if (isPaymentRejectionError(errMsg)) {
           return {
             content: [{ type: "text", text: `Video generation requires payment. Run blockrun_wallet with action: "setup" for funding instructions.
 Error: ${errMsg}` }],
@@ -2071,6 +2127,8 @@ Error: ${errMsg}` }],
           content: [{ type: "text", text: formatError(`Video generation failed: ${errMsg}`, { altModels: "bytedance/seedance-2.0, azure/sora-2" }) }],
           isError: true
         };
+      } finally {
+        gate?.release();
       }
     }
   );
@@ -2096,7 +2154,7 @@ async function payAndPostJson(url, reqBody, fallbackDescription) {
   }, 15e3);
   if (resp402.status !== 402) {
     const data2 = await resp402.json().catch(() => ({}));
-    throw new Error(`Expected 402, got ${resp402.status}: ${data2.message || data2.error || JSON.stringify(data2)}`);
+    throw new Error(`Unexpected status ${resp402.status} (the endpoint did not return a quote): ${data2.message || data2.error || JSON.stringify(data2)}`);
   }
   const prHeader = resp402.headers.get("payment-required") || resp402.headers.get("PAYMENT-REQUIRED");
   if (!prHeader) throw new Error("No PAYMENT-REQUIRED header in 402 response");
@@ -2157,6 +2215,7 @@ Privacy: BlockRun does not store face/liveness data \u2014 only the asset id, na
       }
     },
     async ({ action, name, group_id, image_url, agent_id }) => {
+      let gate;
       try {
         if (action === "init") {
           if (!name) {
@@ -2283,9 +2342,9 @@ Enroll one: blockrun_realface action:"init" name:"\u2026" (real person) or actio
           if (!name || !image_url) {
             return { content: [{ type: "text", text: formatError("portrait requires name and image_url (public HTTPS URL of an AI-generated character image).") }], isError: true };
           }
-          const budgetCheck = checkBudget(budget, agent_id, ENROLLMENT_PRICE_USD);
-          if (!budgetCheck.allowed) {
-            return { content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }], isError: true };
+          gate = reserveBudget(budget, agent_id, ENROLLMENT_PRICE_USD);
+          if (!gate.allowed) {
+            return { content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }], isError: true };
           }
           const { status, data, settledUsd } = await payAndPostJson(
             `${BLOCKRUN_API4}/v1/portrait/enroll`,
@@ -2333,61 +2392,26 @@ Enroll one: blockrun_realface action:"init" name:"\u2026" (real person) or actio
           if (!name || !image_url || !group_id) {
             return { content: [{ type: "text", text: formatError("enroll requires name, image_url, and group_id (from init, after the group is active).") }], isError: true };
           }
-          const budgetCheck = checkBudget(budget, agent_id, ENROLLMENT_PRICE_USD);
-          if (!budgetCheck.allowed) {
-            return { content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }], isError: true };
+          gate = reserveBudget(budget, agent_id, ENROLLMENT_PRICE_USD);
+          if (!gate.allowed) {
+            return { content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }], isError: true };
           }
-          const privateKey = getOrCreateWalletKey();
-          const account = privateKeyToAccount4(privateKey);
-          const enrollUrl = `${BLOCKRUN_API4}/v1/realface/enroll`;
-          const reqBody = JSON.stringify({ name, image_url, group_id });
-          const resp402 = await fetchWithTimeout(enrollUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: reqBody
-          }, 15e3);
-          if (resp402.status !== 402) {
-            const data2 = await resp402.json().catch(() => ({}));
-            throw new Error(`Expected 402, got ${resp402.status}: ${data2.message || data2.error || JSON.stringify(data2)}`);
-          }
-          const prHeader = resp402.headers.get("payment-required") || resp402.headers.get("PAYMENT-REQUIRED");
-          if (!prHeader) throw new Error("No PAYMENT-REQUIRED header in 402 response");
-          const paymentRequired = parsePaymentRequired4(prHeader);
-          const details = extractPaymentDetails4(paymentRequired);
-          const settledUsd = amountToUsd(details.amount);
-          const paymentPayload = await createPaymentPayload4(
-            privateKey,
-            account.address,
-            details.recipient,
-            details.amount,
-            details.network || "eip155:8453",
-            {
-              resourceUrl: details.resource?.url || enrollUrl,
-              resourceDescription: details.resource?.description || "BlockRun RealFace enrollment",
-              maxTimeoutSeconds: Math.max(details.maxTimeoutSeconds || 0, 120),
-              extra: details.extra
-            }
+          const { status, data, settledUsd } = await payAndPostJson(
+            `${BLOCKRUN_API4}/v1/realface/enroll`,
+            JSON.stringify({ name, image_url, group_id }),
+            "BlockRun RealFace enrollment"
           );
-          const resp = await fetchWithTimeout(enrollUrl, {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              "PAYMENT-SIGNATURE": paymentPayload
-            },
-            body: reqBody
-          }, 9e4);
-          const data = await resp.json().catch(() => ({}));
-          if (resp.status === 402) {
+          if (status === 402) {
             throw new Error("Payment rejected. Check your wallet balance.");
           }
-          if (resp.status === 425) {
+          if (status === 425) {
             return { content: [{ type: "text", text: formatError(`Group not active yet \u2014 ${data.message || "finish the phone liveness check first"}. No payment taken.`) }], isError: true };
           }
-          if (resp.status === 422) {
+          if (status === 422) {
             return { content: [{ type: "text", text: formatError(`Face match failed \u2014 ${data.hint || "use a clearer front-facing photo of the same person"}. No payment taken.`) }], isError: true };
           }
-          if (!resp.ok) {
-            throw new Error(`Enroll error ${resp.status}: ${data.error || JSON.stringify(data)}`);
+          if (status < 200 || status >= 300) {
+            throw new Error(`Enroll error ${status}: ${data.error || JSON.stringify(data)}`);
           }
           const assetId = data.asset_id;
           if (!assetId) throw new Error(`Enroll response missing asset_id: ${JSON.stringify(data)}`);
@@ -2416,7 +2440,7 @@ Enroll one: blockrun_realface action:"init" name:"\u2026" (real person) or actio
         return { content: [{ type: "text", text: formatError(`Unknown action: ${action}`) }], isError: true };
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        if (errMsg.includes("balance") || errMsg.includes("payment") || errMsg.includes("402") || errMsg.includes("rejected")) {
+        if (isPaymentRejectionError(errMsg)) {
           return {
             content: [{ type: "text", text: `RealFace enrollment requires payment. Run blockrun_wallet with action: "setup" for funding instructions.
 Error: ${errMsg}` }],
@@ -2424,6 +2448,8 @@ Error: ${errMsg}` }],
           };
         }
         return { content: [{ type: "text", text: formatError(`RealFace ${action} failed: ${errMsg}`) }], isError: true };
+      } finally {
+        gate?.release();
       }
     }
   );
@@ -2447,6 +2473,19 @@ function asStructuredContent(result) {
   return typeof result === "object" && result !== null && !Array.isArray(result) ? result : { result };
 }
 
+// src/utils/path-safety.ts
+function hasPathTraversal(path5) {
+  let decoded = path5;
+  try {
+    decoded = decodeURIComponent(path5);
+  } catch {
+  }
+  return decoded.split(/[/\\]/).some((seg) => seg === ".." || seg === ".");
+}
+function isValidNetworkSlug(slug) {
+  return /^[a-z0-9-]+$/.test(slug);
+}
+
 // src/tools/search.ts
 var SEARCH_PRICE_PER_SOURCE = 0.025;
 var SEARCH_DEFAULT_MAX_RESULTS = 10;
@@ -2477,23 +2516,30 @@ Full request shape + worked examples in the \`search\` skill (\`skills/search/SK
     async ({ path: path5, body, agent_id }) => {
       try {
         body = coerceBody(body);
+        const cleanPath = (path5 ?? "").replace(/^\/+/, "").replace(/^v1\/search\/?/, "");
+        if (hasPathTraversal(cleanPath)) {
+          return { content: [{ type: "text", text: formatError(`Invalid path '${path5}'.`) }], isError: true };
+        }
         const estimatedCost = estimateSearchCost(body);
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const client = getClient();
-        const cleanPath = (path5 ?? "").replace(/^\/+/, "").replace(/^v1\/search\/?/, "");
-        const endpoint = cleanPath ? `/v1/search/${cleanPath}` : "/v1/search";
-        const result = await client.requestWithPaymentRaw(endpoint, body ?? {});
-        recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: asStructuredContent(result)
-        };
+        try {
+          const client = getClient();
+          const endpoint = cleanPath ? `/v1/search/${cleanPath}` : "/v1/search";
+          const result = await client.requestWithPaymentRaw(endpoint, body ?? {});
+          recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: asStructuredContent(result)
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
       }
@@ -2535,23 +2581,30 @@ Full request/response shapes + worked research workflows in the \`exa-research\`
     async ({ path: path5, body, agent_id }) => {
       try {
         body = coerceBody(body);
+        const cleanPath = path5.replace(/^\/+/, "").replace(/^v1\/exa\//, "");
+        if (hasPathTraversal(cleanPath)) {
+          return { content: [{ type: "text", text: formatError(`Invalid path '${path5}'.`) }], isError: true };
+        }
         const estimatedCost = estimateExaCost(path5, body);
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const client = getClient();
-        const cleanPath = path5.replace(/^\/+/, "").replace(/^v1\/exa\//, "");
-        const endpoint = `/v1/exa/${cleanPath}`;
-        const result = await client.requestWithPaymentRaw(endpoint, body ?? {});
-        recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: asStructuredContent(result)
-        };
+        try {
+          const client = getClient();
+          const endpoint = `/v1/exa/${cleanPath}`;
+          const result = await client.requestWithPaymentRaw(endpoint, body ?? {});
+          recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: asStructuredContent(result)
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
       }
@@ -2634,21 +2687,28 @@ Pass query params via 'params' (GET). Use 'body' only for POST endpoints (e.g. p
     async ({ path: path5, params, body, agent_id }) => {
       try {
         body = coerceBody(body);
+        if (hasPathTraversal(path5)) {
+          return { content: [{ type: "text", text: formatError(`Invalid path '${path5}'.`) }], isError: true };
+        }
         const estimatedCost = estimateMarketCost(path5, body);
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const llm = getClient();
-        const result = body !== void 0 ? await llm.pmQuery(path5, body) : await llm.pm(path5, params);
-        recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: asStructuredContent(result)
-        };
+        try {
+          const llm = getClient();
+          const result = body !== void 0 ? await llm.pmQuery(path5, body) : await llm.pm(path5, params);
+          recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: asStructuredContent(result)
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return {
           content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
@@ -2730,51 +2790,55 @@ Examples:
           };
         }
         const estimatedCost = paid ? 1e-3 : 0;
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const priceClient = getPriceClient(paid);
-        if (action === "price") {
-          if (!symbol) throw new Error("symbol is required for action='price'");
-          const result2 = await priceClient.price(category, symbol, {
-            market,
-            session
-          });
-          if (estimatedCost > 0) recordSpending(budget, estimatedCost, agent_id);
-          return {
-            content: [{ type: "text", text: JSON.stringify(result2, null, 2) }],
-            structuredContent: result2
-          };
-        }
-        if (action === "history") {
-          if (!symbol) throw new Error("symbol is required for action='history'");
-          if (from === void 0) throw new Error("from (unix seconds) is required for action='history'");
-          const result2 = await priceClient.history(category, symbol, {
+        try {
+          const priceClient = getPriceClient(paid);
+          if (action === "price") {
+            if (!symbol) throw new Error("symbol is required for action='price'");
+            const result2 = await priceClient.price(category, symbol, {
+              market,
+              session
+            });
+            if (estimatedCost > 0) recordSpending(budget, estimatedCost, agent_id);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2, null, 2) }],
+              structuredContent: result2
+            };
+          }
+          if (action === "history") {
+            if (!symbol) throw new Error("symbol is required for action='history'");
+            if (from === void 0) throw new Error("from (unix seconds) is required for action='history'");
+            const result2 = await priceClient.history(category, symbol, {
+              market,
+              session,
+              resolution: resolution ?? "D",
+              from,
+              to
+            });
+            if (estimatedCost > 0) recordSpending(budget, estimatedCost, agent_id);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2, null, 2) }],
+              structuredContent: result2
+            };
+          }
+          const result = await priceClient.listSymbols(category, {
             market,
-            session,
-            resolution: resolution ?? "D",
-            from,
-            to
+            query,
+            limit
           });
-          if (estimatedCost > 0) recordSpending(budget, estimatedCost, agent_id);
           return {
-            content: [{ type: "text", text: JSON.stringify(result2, null, 2) }],
-            structuredContent: result2
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result
           };
+        } finally {
+          gate.release();
         }
-        const result = await priceClient.listSymbols(category, {
-          market,
-          query,
-          limit
-        });
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: result
-        };
       } catch (err) {
         return {
           content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
@@ -2905,22 +2969,29 @@ Full action shapes + GPU type details in the \`modal\` skill.`,
       try {
         body = coerceBody(body);
         const cleanPath = path5.replace(/^\/+/, "").replace(/^v1\/modal\//, "");
+        if (hasPathTraversal(cleanPath)) {
+          return { content: [{ type: "text", text: formatError(`Invalid path '${path5}'.`) }], isError: true };
+        }
         const estimatedCost = estimateModalCost(cleanPath);
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const client = buildClientWithTimeout(modalTimeoutMs(body));
-        const endpoint = `/v1/modal/${cleanPath}`;
-        const result = await client.requestWithPaymentRaw(endpoint, body ?? {});
-        recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: asStructuredContent(result)
-        };
+        try {
+          const client = buildClientWithTimeout(modalTimeoutMs(body));
+          const endpoint = `/v1/modal/${cleanPath}`;
+          const result = await client.requestWithPaymentRaw(endpoint, body ?? {});
+          recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: asStructuredContent(result)
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
       }
@@ -2971,22 +3042,29 @@ Voice call flow + voice preset details + full body shapes in the \`phone\` skill
       try {
         body = coerceBody(body);
         const cleanPath = path5.replace(/^\/+/, "").replace(/^v1\//, "");
+        if (hasPathTraversal(cleanPath)) {
+          return { content: [{ type: "text", text: formatError(`Invalid path '${path5}'.`) }], isError: true };
+        }
         const estimatedCost = estimatePhoneCost(cleanPath, body !== void 0);
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const client = getClient();
-        const endpoint = `/v1/${cleanPath}`;
-        const result = body !== void 0 ? await client.requestWithPaymentRaw(endpoint, body) : await client.getWithPaymentRaw(endpoint);
-        if (estimatedCost > 0) recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: asStructuredContent(result)
-        };
+        try {
+          const client = getClient();
+          const endpoint = `/v1/${cleanPath}`;
+          const result = body !== void 0 ? await client.requestWithPaymentRaw(endpoint, body) : await client.getWithPaymentRaw(endpoint);
+          if (estimatedCost > 0) recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: asStructuredContent(result)
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
       }
@@ -3069,22 +3147,29 @@ Each Surf endpoint pre-validates required params before settling \u2014 you get
       try {
         body = coerceBody(body);
         const cleanPath = path5.replace(/^\/+/, "").replace(/^v1\/surf\//, "").replace(/^api\/v1\/surf\//, "");
+        if (hasPathTraversal(cleanPath)) {
+          return { content: [{ type: "text", text: formatError(`Invalid path '${path5}'.`) }], isError: true };
+        }
         const estimatedCost = estimateSurfCost(cleanPath);
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const client = getClient();
-        const endpoint = `/v1/surf/${cleanPath}`;
-        const result = body !== void 0 ? await client.requestWithPaymentRaw(endpoint, body) : await client.getWithPaymentRaw(endpoint, params);
-        recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: asStructuredContent(result)
-        };
+        try {
+          const client = getClient();
+          const endpoint = `/v1/surf/${cleanPath}`;
+          const result = body !== void 0 ? await client.requestWithPaymentRaw(endpoint, body) : await client.getWithPaymentRaw(endpoint, params);
+          recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: asStructuredContent(result)
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return {
           content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
@@ -3138,21 +3223,31 @@ Prefer blockrun_price (free quotes), blockrun_dex (free DEX data), or blockrun_s
         }
         const batchCount = Array.isArray(body) ? Math.max(body.length, 1) : 1;
         const estimatedCost = RPC_PRICE_USD * batchCount;
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const cleanNetwork = network.trim().toLowerCase().replace(/^\/+|\/+$/g, "");
+        if (!isValidNetworkSlug(cleanNetwork)) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: formatError(`Invalid network '${network}'. Use a chain slug like 'ethereum', 'base', or 'solana'.`) }],
             isError: true
           };
         }
-        const cleanNetwork = network.trim().toLowerCase().replace(/^\/+|\/+$/g, "");
-        const client = getClient();
-        const result = await client.requestWithPaymentRaw(`/v1/rpc/${cleanNetwork}`, body);
-        recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: typeof result === "object" && result !== null && !Array.isArray(result) ? result : { result }
-        };
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
+          return {
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            isError: true
+          };
+        }
+        try {
+          const client = getClient();
+          const result = await client.requestWithPaymentRaw(`/v1/rpc/${cleanNetwork}`, body);
+          recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: typeof result === "object" && result !== null && !Array.isArray(result) ? result : { result }
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return {
           content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
@@ -3195,21 +3290,28 @@ Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pai
     async ({ path: path5, agent_id }) => {
       try {
         const cleanPath = path5.replace(/^\/+/, "").replace(/^v1\/defillama\//, "").replace(/^api\/v1\/defillama\//, "");
+        if (hasPathTraversal(cleanPath)) {
+          return { content: [{ type: "text", text: formatError(`Invalid path '${path5}'.`) }], isError: true };
+        }
         const estimatedCost = estimateDefiCost(cleanPath);
-        const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
-        if (!budgetCheck.allowed) {
+        const gate = reserveBudget(budget, agent_id, estimatedCost);
+        if (!gate.allowed) {
           return {
-            content: [{ type: "text", text: `${budgetCheck.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
+            content: [{ type: "text", text: `${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.` }],
             isError: true
           };
         }
-        const client = getClient();
-        const result = await client.getWithPaymentRaw(`/v1/defillama/${cleanPath}`);
-        recordSpending(budget, estimatedCost, agent_id);
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-          structuredContent: typeof result === "object" && result !== null && !Array.isArray(result) ? result : { result }
-        };
+        try {
+          const client = getClient();
+          const result = await client.getWithPaymentRaw(`/v1/defillama/${cleanPath}`);
+          recordSpending(budget, estimatedCost, agent_id);
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: typeof result === "object" && result !== null && !Array.isArray(result) ? result : { result }
+          };
+        } finally {
+          gate.release();
+        }
       } catch (err) {
         return {
           content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
@@ -3268,7 +3370,7 @@ function resolveProfileName(argv = process.argv.slice(2), env = process.env) {
 }
 function resolveTools(argv, env) {
   const requested = resolveProfileName(argv, env);
-  const spec = PROFILES[requested];
+  const spec = Object.hasOwn(PROFILES, requested) ? PROFILES[requested] : void 0;
   if (!spec) {
     return { profile: DEFAULT_PROFILE, tools: new Set(ALL_TOOLS) };
   }
@@ -3359,6 +3461,10 @@ function looksLikeRawPrivateKey(value) {
   if (value.length >= 80 && value.length <= 100 && /^[1-9A-HJ-NP-Za-km-z]+$/.test(value)) return true;
   return false;
 }
+function looksLikeNamedSecretValue(value) {
+  if (looksLikeRawPrivateKey(value)) return true;
+  return typeof value === "string" && /^[0-9a-fA-F]{64}$/.test(value);
+}
 function looksLikeSolanaSecretKeyArray(value) {
   return Array.isArray(value) && value.length === 64 && value.every((n) => typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= 255);
 }
@@ -3373,7 +3479,7 @@ function walk(obj, file, jsonPath, out) {
   }
   for (const [k, v] of Object.entries(obj)) {
     const next = jsonPath ? `${jsonPath}.${k}` : k;
-    if (/wallet[-_ ]?key|private[-_ ]?key|secret/i.test(k) && looksLikeRawPrivateKey(v)) {
+    if (/wallet[-_ ]?key|private[-_ ]?key|secret/i.test(k) && looksLikeNamedSecretValue(v)) {
       out.push({ file, path: next });
     } else if (looksLikeRawPrivateKey(v)) {
       out.push({ file, path: next });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "mcpName": "io.github.BlockRunAI/blockrun-mcp",
   "description": "BlockRun MCP Server - Give your AI agent web search, deep research, prediction markets, crypto data, X/Twitter intelligence. Paid via x402 micropayments.",
   "type": "module",