@botcord/botcord 0.3.4 → 0.3.6-beta.20260413082920

package/src/tools/contacts.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_contacts — Manage social relationships: contacts, requests, blocks.
  */
-import {
-  getSingleAccountModeError,
-  resolveAccountConfig,
-  isAccountConfigured,
-} from "../config.js";
-import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
-import { getConfig as getAppConfig } from "../runtime.js";
+import { withClient } from "./with-client.js";
+import { validationError, dryRunResult } from "./tool-result.js";
 
 export function createContactsTool() {
   return {
@@ -56,69 +50,66 @@ export function createContactsTool() {
           enum: ["pending", "accepted", "rejected"],
           description: "Filter by state — for received_requests, sent_requests",
         },
+        dry_run: {
+          type: "boolean" as const,
+          description: "Preview the request without executing. Returns the API call that would be made.",
+        },
       },
       required: ["action"],
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
-
-      const acct = resolveAccountConfig(cfg);
-      if (!isAccountConfigured(acct)) {
-        return { error: "BotCord is not configured." };
-      }
-
-      const client = new BotCordClient(acct);
-      attachTokenPersistence(client, acct);
-
-      try {
+      return withClient(async (client) => {
         switch (args.action) {
           case "list":
-            return await client.listContacts();
+            return { contacts: await client.listContacts() };
 
           case "remove":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
+            if (args.dry_run) return dryRunResult("DELETE", `/registry/agents/{self}/contacts/${args.agent_id}`);
             await client.removeContact(args.agent_id);
             return { ok: true, removed: args.agent_id };
 
           case "send_request":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
+            if (args.dry_run) return dryRunResult("POST", "/hub/send", { to: args.agent_id, type: "contact_request", payload: args.message ? { text: args.message } : {} }, { note: "The actual body is a signed envelope (JCS + Ed25519), not the raw fields shown here." });
             await client.sendContactRequest(args.agent_id, args.message);
             return { ok: true, sent_to: args.agent_id };
 
           case "received_requests":
-            return await client.listReceivedRequests(args.state);
+            return { requests: await client.listReceivedRequests(args.state) };
 
           case "sent_requests":
-            return await client.listSentRequests(args.state);
+            return { requests: await client.listSentRequests(args.state) };
 
           case "accept_request":
-            if (!args.request_id) return { error: "request_id is required" };
+            if (!args.request_id) return validationError("request_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/registry/agents/{self}/contact-requests/${args.request_id}/accept`);
             await client.acceptRequest(args.request_id);
             return { ok: true, accepted: args.request_id };
 
           case "reject_request":
-            if (!args.request_id) return { error: "request_id is required" };
+            if (!args.request_id) return validationError("request_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/registry/agents/{self}/contact-requests/${args.request_id}/reject`);
             await client.rejectRequest(args.request_id);
             return { ok: true, rejected: args.request_id };
 
           case "block":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/registry/agents/{self}/blocks`, { blocked_agent_id: args.agent_id });
             await client.blockAgent(args.agent_id);
             return { ok: true, blocked: args.agent_id };
 
           case "unblock":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
+            if (args.dry_run) return dryRunResult("DELETE", `/registry/agents/{self}/blocks/${args.agent_id}`);
             await client.unblockAgent(args.agent_id);
             return { ok: true, unblocked: args.agent_id };
 
           case "list_blocks":
-            return await client.listBlocks();
+            return { blocks: await client.listBlocks() };
 
           case "redeem_invite": {
-            if (!args.invite_code) return { error: "invite_code is required" };
+            if (!args.invite_code) return validationError("invite_code is required");
             // Extract code from full URL if needed (e.g. .../invites/iv_xxx/redeem or /i/iv_xxx)
             const raw = args.invite_code as string;
             const match = raw.match(/\b(iv_[a-zA-Z0-9]+)/);
@@ -127,11 +118,9 @@ export function createContactsTool() {
           }
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Contact action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/directory.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_directory — Read-only queries: resolve agents, discover rooms, message history.
  */
-import {
-  getSingleAccountModeError,
-  resolveAccountConfig,
-  isAccountConfigured,
-} from "../config.js";
-import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
-import { getConfig as getAppConfig } from "../runtime.js";
+import { withClient } from "./with-client.js";
+import { validationError } from "./tool-result.js";
 
 export function createDirectoryTool() {
   return {
@@ -63,30 +57,17 @@ export function createDirectoryTool() {
       required: ["action"],
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
-
-      const acct = resolveAccountConfig(cfg);
-      if (!isAccountConfigured(acct)) {
-        return { error: "BotCord is not configured." };
-      }
-
-      const client = new BotCordClient(acct);
-      attachTokenPersistence(client, acct);
-
-      try {
+      return withClient(async (client) => {
         switch (args.action) {
           case "resolve":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
             return await client.resolve(args.agent_id);
 
           case "discover_rooms":
-            return await client.discoverRooms(args.room_name);
+            return await client.discoverPublicRooms(args.room_name);
 
           case "history":
-            return await client.getHistory({
+            return { history: await client.getHistory({
               peer: args.peer,
               roomId: args.room_id,
               topic: args.topic,
@@ -94,14 +75,12 @@ export function createDirectoryTool() {
               before: args.before,
               after: args.after,
               limit: args.limit || 20,
-            });
+            }) };
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Directory action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/messaging.ts

@@ -3,15 +3,9 @@
  */
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { lookup } from "node:dns";
-import {
-  getSingleAccountModeError,
-  resolveAccountConfig,
-  isAccountConfigured,
-} from "../config.js";
-import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
-import { getConfig as getAppConfig } from "../runtime.js";
+import { withClient } from "./with-client.js";
+import { validationError, dryRunResult } from "./tool-result.js";
+import type { BotCordClient } from "../client.js";
 import type { MessageAttachment } from "../types.js";
 
 /** Extract clean filename from a URL, stripping query string and hash. */
@@ -127,23 +121,30 @@ export function createMessagingTool() {
           items: { type: "string" as const },
           description: "URLs of already-hosted files to attach to the message",
         },
+        dry_run: {
+          type: "boolean" as const,
+          description: "Preview the request without sending. Returns the API call that would be made.",
+        },
       },
       required: ["to", "text"],
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
-
-      const acct = resolveAccountConfig(cfg);
-      if (!isAccountConfigured(acct)) {
-        return { error: "BotCord is not configured. Set hubUrl, agentId, keyId, and privateKey." };
+      if (args.dry_run) {
+        const msgType = args.type || "message";
+        const body: Record<string, unknown> = { to: args.to, text: args.text, type: msgType };
+        if (args.topic) body.topic = args.topic;
+        if (args.goal) body.goal = args.goal;
+        if (args.reply_to) body.reply_to = args.reply_to;
+        if (args.mentions) body.mentions = args.mentions;
+        if (args.file_paths) body.file_paths = args.file_paths;
+        if (args.file_urls) body.file_urls = args.file_urls;
+        const notes: string[] = [];
+        if (args.file_paths?.length) notes.push("Local files will be uploaded via POST /hub/upload before sending.");
+        notes.push("The actual body is a signed envelope (JCS + Ed25519), not the raw fields shown here.");
+        return dryRunResult("POST", "/hub/send", body, { note: notes.join(" ") });
       }
 
-      try {
-        const client = new BotCordClient(acct);
-        attachTokenPersistence(client, acct);
+      return withClient(async (client) => {
         const msgType = args.type || "message";
 
         // Collect attachments from both file_paths (upload first) and file_urls
@@ -182,9 +183,7 @@ export function createMessagingTool() {
           attachments: finalAttachments,
         });
         return { ok: true, hub_msg_id: result.hub_msg_id, to: args.to, type: msgType, attachments: finalAttachments };
-      } catch (err: any) {
-        return { error: `Failed to send: ${err.message}` };
-      }
+      });
     },
   };
 }
@@ -212,28 +211,14 @@ export function createUploadTool() {
       required: ["file_paths"],
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
-
-      const acct = resolveAccountConfig(cfg);
-      if (!isAccountConfigured(acct)) {
-        return { error: "BotCord is not configured. Set hubUrl, agentId, keyId, and privateKey." };
-      }
-
       if (!args.file_paths || args.file_paths.length === 0) {
-        return { error: "file_paths is required and must not be empty" };
+        return validationError("file_paths is required and must not be empty");
       }
 
-      try {
-        const client = new BotCordClient(acct);
-        attachTokenPersistence(client, acct);
+      return withClient(async (client) => {
         const uploaded = await uploadLocalFiles(client, args.file_paths);
         return { ok: true, files: uploaded };
-      } catch (err: any) {
-        return { error: `Upload failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/payment.ts

@@ -1,15 +1,9 @@
 /**
  * botcord_payment — Unified payment and transaction tool for BotCord coin flows.
  */
-import {
-  getSingleAccountModeError,
-  resolveAccountConfig,
-  isAccountConfigured,
-} from "../config.js";
-import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
-import { getConfig as getAppConfig } from "../runtime.js";
-import { formatCoinAmount } from "./coin-format.js";
+import { withClient } from "./with-client.js";
+import { validationError, dryRunResult } from "./tool-result.js";
+import { formatCoinAmount, parseCoinToMinor } from "./coin-format.js";
 import { executeTransfer, isPeerContact, formatFollowUpDeliverySummary } from "./payment-transfer.js";
 
 function sanitizeBalance(summary: any): any {
@@ -223,9 +217,9 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           type: "string" as const,
           description: "Recipient agent ID (ag_...) — for transfer",
         },
-        amount_minor: {
+        amount: {
           type: "string" as const,
-          description: "Amount in minor units (1 COIN = 100 minor units). To transfer N coins, pass N × 100. Example: 10 COIN → \"1000\" — for transfer, topup, withdraw",
+          description: "Amount in COIN (supports up to 2 decimals, e.g. \"10\" or \"9.50\") — for transfer, topup, withdraw",
         },
         memo: {
           type: "string" as const,
@@ -259,9 +253,9 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           type: "object" as const,
           description: "Withdrawal destination details — for withdraw",
         },
-        fee_minor: {
+        fee: {
           type: "string" as const,
-          description: "Optional withdrawal fee in minor units (1 COIN = 100 minor units) — for withdraw",
+          description: "Optional withdrawal fee in COIN (e.g. \"1\" or \"0.50\") — for withdraw",
         },
         withdrawal_id: {
           type: "string" as const,
@@ -287,27 +281,18 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           type: "string" as const,
           description: "Filter by transaction type — for ledger",
         },
+        dry_run: {
+          type: "boolean" as const,
+          description: "Preview the request without executing. Returns the API call that would be made.",
+        },
       },
       required: ["action"],
     },
     execute: async (_toolCallId: any, args: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
-
-      const acct = resolveAccountConfig(cfg);
-      if (!isAccountConfigured(acct)) {
-        return { error: "BotCord is not configured." };
-      }
-
-      const client = new BotCordClient(acct);
-      attachTokenPersistence(client, acct);
-
-      try {
+      return withClient(async (client) => {
         switch (args.action) {
           case "recipient_verify": {
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
             const agent = await client.resolve(args.agent_id);
             return { result: formatRecipient(agent), data: agent };
           }
@@ -327,19 +312,22 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "transfer": {
-            if (!args.to_agent_id) return { error: "to_agent_id is required" };
-            if (!args.amount_minor) return { error: "amount_minor is required" };
+            if (!args.to_agent_id) return validationError("to_agent_id is required");
+            if (!args.amount) return validationError("amount is required");
+            const transferMinor = parseCoinToMinor(args.amount);
+            if (transferMinor === null) return validationError("amount must be a valid number (e.g. \"10\" or \"9.50\")");
+            if (args.dry_run) return dryRunResult("POST", "/wallet/transfers", { to_agent_id: args.to_agent_id, amount_minor: transferMinor, memo: args.memo });
 
             const isContact = await isPeerContact(client, args.to_agent_id);
             if (!isContact && args.confirmed !== true) {
               return {
-                result: `\u26a0\ufe0f ${args.to_agent_id} is not in your contacts. This is a stranger transfer of ${formatCoinAmount(args.amount_minor)}. To proceed, call this tool again with confirmed: true. The transfer will create a chat room between you and the recipient.`,
+                result: `\u26a0\ufe0f ${args.to_agent_id} is not in your contacts. This is a stranger transfer of ${formatCoinAmount(transferMinor)}. To proceed, call this tool again with confirmed: true. The transfer will create a chat room between you and the recipient.`,
               };
             }
 
             const transfer = await executeTransfer(client, {
               to_agent_id: args.to_agent_id,
-              amount_minor: args.amount_minor,
+              amount_minor: transferMinor,
               memo: args.memo,
               reference_type: args.reference_type,
               reference_id: args.reference_id,
@@ -353,9 +341,13 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "topup": {
-            if (!args.amount_minor) return { error: "amount_minor is required" };
+            if (!args.amount) return validationError("amount is required");
+            const topupMinor = parseCoinToMinor(args.amount);
+            if (topupMinor === null) return validationError("amount must be a valid number (e.g. \"10\" or \"9.50\")");
+            if (args.dry_run) return dryRunResult("POST", "/wallet/topups", { amount_minor: topupMinor, channel: args.channel });
+
             const topup = await client.createTopup({
-              amount_minor: args.amount_minor,
+              amount_minor: topupMinor,
               channel: args.channel,
               metadata: args.metadata,
               idempotency_key: args.idempotency_key,
@@ -364,10 +356,19 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "withdraw": {
-            if (!args.amount_minor) return { error: "amount_minor is required" };
+            if (!args.amount) return validationError("amount is required");
+            const withdrawMinor = parseCoinToMinor(args.amount);
+            if (withdrawMinor === null) return validationError("amount must be a valid number (e.g. \"10\" or \"9.50\")");
+            let feeMinor: string | undefined;
+            if (args.fee) {
+              feeMinor = parseCoinToMinor(args.fee) ?? undefined;
+              if (feeMinor === undefined) return validationError("fee must be a valid number (e.g. \"1\" or \"0.50\")");
+            }
+            if (args.dry_run) return dryRunResult("POST", "/wallet/withdrawals", { amount_minor: withdrawMinor, destination_type: args.destination_type });
+
             const withdrawal = await client.createWithdrawal({
-              amount_minor: args.amount_minor,
-              fee_minor: args.fee_minor,
+              amount_minor: withdrawMinor,
+              fee_minor: feeMinor,
               destination_type: args.destination_type,
               destination: args.destination,
               idempotency_key: args.idempotency_key,
@@ -376,23 +377,23 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "cancel_withdrawal": {
-            if (!args.withdrawal_id) return { error: "withdrawal_id is required" };
+            if (!args.withdrawal_id) return validationError("withdrawal_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/wallet/withdrawals/${args.withdrawal_id}/cancel`);
+
             const withdrawal = await client.cancelWithdrawal(args.withdrawal_id);
             return { result: formatWithdrawal(withdrawal), data: sanitizeWithdrawal(withdrawal) };
           }
 
           case "tx_status": {
-            if (!args.tx_id) return { error: "tx_id is required" };
+            if (!args.tx_id) return validationError("tx_id is required");
             const tx = await client.getWalletTransaction(args.tx_id);
             return { result: formatTransaction(tx), data: sanitizeTransaction(tx) };
           }
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Payment action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/register.ts

@@ -4,6 +4,7 @@
 import { registerAgent } from "../commands/register.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import { DEFAULT_HUB } from "../constants.js";
+import { validationError, configError, classifyError } from "./tool-result.js";
 
 export function createRegisterTool() {
   return {
@@ -35,11 +36,11 @@ export function createRegisterTool() {
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
       if (!args.name) {
-        return { error: "name is required" };
+        return validationError("name is required");
       }
 
       const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
+      if (!cfg) return configError("No configuration available");
 
       try {
         const result = await registerAgent({
@@ -59,8 +60,8 @@ export function createRegisterTool() {
           claim_url: result.claimUrl,
           note: "Restart OpenClaw to activate: openclaw gateway restart",
         };
-      } catch (err: any) {
-        return { error: `Registration failed: ${err.message}` };
+      } catch (err: unknown) {
+        return classifyError(err);
       }
     },
   };

package/src/tools/reset-credential.ts

@@ -3,6 +3,7 @@
  */
 import { getConfig as getAppConfig } from "../runtime.js";
 import { resetCredential } from "../reset-credential.js";
+import { validationError, configError, classifyError } from "./tool-result.js";
 
 export function createResetCredentialTool() {
   return {
@@ -30,9 +31,9 @@ export function createResetCredentialTool() {
     },
     execute: async (_toolCallId: any, args: any) => {
       const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      if (!args.agent_id) return { error: "agent_id is required" };
-      if (!args.reset_code) return { error: "reset_code is required" };
+      if (!cfg) return configError("No configuration available");
+      if (!args.agent_id) return validationError("agent_id is required");
+      if (!args.reset_code) return validationError("reset_code is required");
 
       try {
         const result = await resetCredential({
@@ -50,8 +51,8 @@ export function createResetCredentialTool() {
           credentials_file: result.credentialsFile,
           note: "Restart OpenClaw to activate: openclaw gateway restart",
         };
-      } catch (err: any) {
-        return { error: err.message };
+      } catch (err: unknown) {
+        return classifyError(err);
       }
     },
   };

package/src/tools/room-context.ts

@@ -2,14 +2,25 @@
  * botcord_room_context — Inspect room context, recent messages, and search
  * message history within one room or across all joined rooms.
  */
-import {
-  getSingleAccountModeError,
-  resolveAccountConfig,
-  isAccountConfigured,
-} from "../config.js";
-import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
-import { getConfig as getAppConfig } from "../runtime.js";
+import { withClient } from "./with-client.js";
+import { validationError } from "./tool-result.js";
+
+/** Normalize query input: accept a string or string[] from the LLM. */
+function _normalizeQuery(raw: unknown): string | string[] | null {
+  if (Array.isArray(raw)) {
+    const parts = raw
+      .filter((v) => typeof v === "string")
+      .map((s: string) => s.trim())
+      .filter(Boolean);
+    if (parts.length === 0) return null;
+    return parts.length === 1 ? parts[0] : parts;
+  }
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    return trimmed || null;
+  }
+  return null;
+}
 
 export function createRoomContextTool() {
   return {
@@ -44,8 +55,9 @@ export function createRoomContextTool() {
             "Room ID (rm_...) — required for room_summary, room_messages, room_search; optional filter for global_search",
         },
         query: {
-          type: "string" as const,
-          description: "Search query text — required for room_search and global_search",
+          description:
+            "Search query — required for room_search and global_search. " +
+            "Pass a single string or an array of strings for OR search (e.g., ['deploy', 'release']).",
         },
         topic_id: {
           type: "string" as const,
@@ -71,28 +83,15 @@ export function createRoomContextTool() {
       required: ["action"],
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
-
-      const acct = resolveAccountConfig(cfg);
-      if (!isAccountConfigured(acct)) {
-        return { error: "BotCord is not configured." };
-      }
-
-      const client = new BotCordClient(acct);
-      attachTokenPersistence(client, acct);
-
-      try {
+      return withClient(async (client) => {
         switch (args.action) {
           case "room_summary": {
-            if (!args.room_id) return { error: "room_id is required for room_summary" };
+            if (!args.room_id) return validationError("room_id is required for room_summary");
             return await client.roomSummary(args.room_id, args.limit);
           }
 
           case "room_messages": {
-            if (!args.room_id) return { error: "room_id is required for room_messages" };
+            if (!args.room_id) return validationError("room_id is required for room_messages");
             return await client.roomMessages(args.room_id, {
               limit: args.limit,
               before: args.before,
@@ -103,9 +102,10 @@ export function createRoomContextTool() {
           }
 
           case "room_search": {
-            if (!args.room_id) return { error: "room_id is required for room_search" };
-            if (!args.query) return { error: "query is required for room_search" };
-            return await client.roomSearch(args.room_id, args.query, {
+            if (!args.room_id) return validationError("room_id is required for room_search");
+            const rsQuery = _normalizeQuery(args.query);
+            if (!rsQuery) return validationError("query is required for room_search");
+            return await client.roomSearch(args.room_id, rsQuery, {
               limit: args.limit,
               before: args.before,
               topicId: args.topic_id,
@@ -118,8 +118,9 @@ export function createRoomContextTool() {
           }
 
           case "global_search": {
-            if (!args.query) return { error: "query is required for global_search" };
-            return await client.globalSearch(args.query, {
+            const gsQuery = _normalizeQuery(args.query);
+            if (!gsQuery) return validationError("query is required for global_search");
+            return await client.globalSearch(gsQuery, {
               limit: args.limit,
               roomId: args.room_id,
               topicId: args.topic_id,
@@ -129,11 +130,9 @@ export function createRoomContextTool() {
           }
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Room context action failed: ${err.message}` };
-      }
+      });
     },
   };
 }