@botcord/botcord 0.3.6 → 0.3.7

package/src/tools/payment.ts

@@ -1,14 +1,8 @@
 /**
  * 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 { 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";
 
@@ -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,10 +312,11 @@ 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) return { error: "amount 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 { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
+            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) {
@@ -355,9 +341,11 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "topup": {
-            if (!args.amount) return { error: "amount is required" };
+            if (!args.amount) return validationError("amount is required");
             const topupMinor = parseCoinToMinor(args.amount);
-            if (topupMinor === null) return { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
+            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: topupMinor,
               channel: args.channel,
@@ -368,14 +356,16 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
           }
 
           case "withdraw": {
-            if (!args.amount) return { error: "amount is required" };
+            if (!args.amount) return validationError("amount is required");
             const withdrawMinor = parseCoinToMinor(args.amount);
-            if (withdrawMinor === null) return { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
+            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 { error: "fee must be a valid number (e.g. \"1\" or \"0.50\")" };
+              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: withdrawMinor,
               fee_minor: feeMinor,
@@ -387,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,8 @@
  * 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 {
@@ -89,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,
@@ -121,9 +102,9 @@ export function createRoomContextTool() {
           }
 
           case "room_search": {
-            if (!args.room_id) return { error: "room_id is required for room_search" };
+            if (!args.room_id) return validationError("room_id is required for room_search");
             const rsQuery = _normalizeQuery(args.query);
-            if (!rsQuery) return { error: "query is required for room_search" };
+            if (!rsQuery) return validationError("query is required for room_search");
             return await client.roomSearch(args.room_id, rsQuery, {
               limit: args.limit,
               before: args.before,
@@ -138,7 +119,7 @@ export function createRoomContextTool() {
 
           case "global_search": {
             const gsQuery = _normalizeQuery(args.query);
-            if (!gsQuery) return { error: "query is required for global_search" };
+            if (!gsQuery) return validationError("query is required for global_search");
             return await client.globalSearch(gsQuery, {
               limit: args.limit,
               roomId: args.room_id,
@@ -149,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}` };
-      }
+      });
     },
   };
 }

package/src/tools/rooms.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_rooms — Room lifecycle and membership management.
  */
-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 createRoomsTool() {
   return {
@@ -102,27 +96,19 @@ export function createRoomsTool() {
           type: "boolean" as const,
           description: "Mute or unmute the current member in a room — for mute",
         },
+        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 "create":
-            if (!args.name) return { error: "name is required" };
+            if (!args.name) return validationError("name is required");
+            if (args.dry_run) return dryRunResult("POST", "/hub/rooms", { name: args.name, visibility: args.visibility || "private", join_policy: args.join_policy, member_ids: args.member_ids });
             return await client.createRoom({
               name: args.name,
               description: args.description,
@@ -138,14 +124,15 @@ export function createRoomsTool() {
             });
 
           case "list":
-            return await client.listMyRooms();
+            return { rooms: await client.listMyRooms() };
 
           case "info":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
             return await client.getRoomInfo(args.room_id);
 
           case "update":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("PATCH", `/hub/rooms/${args.room_id}`, { name: args.name, description: args.description, rule: args.rule, visibility: args.visibility, join_policy: args.join_policy, required_subscription_product_id: args.required_subscription_product_id, max_members: args.max_members, default_send: args.default_send, default_invite: args.default_invite, slow_mode_seconds: args.slow_mode_seconds });
             return await client.updateRoom(args.room_id, {
               name: args.name,
               description: args.description,
@@ -163,7 +150,8 @@ export function createRoomsTool() {
             return await client.discoverPublicRooms(args.name);
 
           case "join":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/members`, { agent_id: "{self}" });
             await client.joinRoom(args.room_id, {
               can_send: args.can_send,
               can_invite: args.can_invite,
@@ -171,21 +159,24 @@ export function createRoomsTool() {
             return { ok: true, joined: args.room_id };
 
           case "leave":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/leave`);
             await client.leaveRoom(args.room_id);
             return { ok: true, left: args.room_id };
 
           case "dissolve":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("DELETE", `/hub/rooms/${args.room_id}`);
             await client.dissolveRoom(args.room_id);
             return { ok: true, dissolved: args.room_id };
 
           case "members":
-            if (!args.room_id) return { error: "room_id is required" };
-            return await client.getRoomMembers(args.room_id);
+            if (!args.room_id) return validationError("room_id is required");
+            return { members: await client.getRoomMembers(args.room_id) };
 
           case "invite":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/members`, { agent_id: args.agent_id, can_send: args.can_send, can_invite: args.can_invite });
             await client.inviteToRoom(args.room_id, args.agent_id, {
               can_send: args.can_send,
               can_invite: args.can_invite,
@@ -193,22 +184,26 @@ export function createRoomsTool() {
             return { ok: true, invited: args.agent_id, room: args.room_id };
 
           case "remove_member":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("DELETE", `/hub/rooms/${args.room_id}/members/${args.agent_id}`);
             await client.removeMember(args.room_id, args.agent_id);
             return { ok: true, removed: args.agent_id, room: args.room_id };
 
           case "promote":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/promote`, { agent_id: args.agent_id, role: args.role || "admin" });
             await client.promoteMember(args.room_id, args.agent_id, args.role || "admin");
             return { ok: true, promoted: args.agent_id, role: args.role || "admin", room: args.room_id };
 
           case "transfer":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/transfer`, { new_owner_id: args.agent_id });
             await client.transferOwnership(args.room_id, args.agent_id);
             return { ok: true, new_owner: args.agent_id, room: args.room_id };
 
           case "permissions":
-            if (!args.room_id || !args.agent_id) return { error: "room_id and agent_id are required" };
+            if (!args.room_id || !args.agent_id) return validationError("room_id and agent_id are required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/permissions`, { agent_id: args.agent_id, can_send: args.can_send, can_invite: args.can_invite });
             await client.setMemberPermissions(args.room_id, args.agent_id, {
               can_send: args.can_send,
               can_invite: args.can_invite,
@@ -216,16 +211,15 @@ export function createRoomsTool() {
             return { ok: true, agent: args.agent_id, room: args.room_id };
 
           case "mute":
-            if (!args.room_id) return { error: "room_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/hub/rooms/${args.room_id}/mute`, { muted: args.muted ?? true });
             await client.muteRoom(args.room_id, args.muted ?? true);
             return { ok: true, room: args.room_id, muted: args.muted ?? true };
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Room action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/subscription.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_subscription — Create and manage coin-priced subscription products.
  */
-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 { formatCoinAmount, parseCoinToMinor } from "./coin-format.js";
 
 function formatProduct(product: any): string {
@@ -127,31 +121,23 @@ export function createSubscriptionTool() {
           type: "number" as const,
           description: "Slow mode interval in seconds — for create_subscription_room or bind_room_to_product",
         },
+        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 "create_product": {
-            if (!args.name) return { error: "name is required" };
-            if (!args.amount) return { error: "amount is required" };
-            if (!args.billing_interval) return { error: "billing_interval is required" };
+            if (!args.name) return validationError("name is required");
+            if (!args.amount) return validationError("amount is required");
+            if (!args.billing_interval) return validationError("billing_interval is required");
             const amountMinor = parseCoinToMinor(args.amount);
-            if (amountMinor === null) return { error: "amount must be a valid number (e.g. \"10\" or \"9.50\")" };
+            if (amountMinor === null) return validationError("amount must be a valid number (e.g. \"10\" or \"9.50\")");
+            if (args.dry_run) return dryRunResult("POST", "/subscriptions/products", { name: args.name, amount_minor: amountMinor, billing_interval: args.billing_interval });
             const product = await client.createSubscriptionProduct({
               name: args.name,
               description: args.description,
@@ -173,14 +159,16 @@ export function createSubscriptionTool() {
           }
 
           case "archive_product": {
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.product_id) return validationError("product_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/subscriptions/products/${args.product_id}/archive`);
             const product = await client.archiveSubscriptionProduct(args.product_id);
             return { result: formatProduct(product), data: product };
           }
 
           case "create_subscription_room": {
-            if (!args.product_id) return { error: "product_id is required" };
-            if (!args.name) return { error: "name is required" };
+            if (!args.product_id) return validationError("product_id is required");
+            if (!args.name) return validationError("name is required");
+            if (args.dry_run) return dryRunResult("POST", "/hub/rooms", { name: args.name, description: args.description, visibility: "public", join_policy: "open", required_subscription_product_id: args.product_id });
             const room = await client.createRoom({
               name: args.name,
               description: args.description,
@@ -200,8 +188,9 @@ export function createSubscriptionTool() {
           }
 
           case "bind_room_to_product": {
-            if (!args.room_id) return { error: "room_id is required" };
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.room_id) return validationError("room_id is required");
+            if (!args.product_id) return validationError("product_id is required");
+            if (args.dry_run) return dryRunResult("PATCH", `/hub/rooms/${args.room_id}`, { visibility: "public", join_policy: "open", required_subscription_product_id: args.product_id });
             const room = await client.updateRoom(args.room_id, {
               name: args.name,
               description: args.description,
@@ -221,7 +210,8 @@ export function createSubscriptionTool() {
           }
 
           case "subscribe": {
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.product_id) return validationError("product_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/subscriptions/products/${args.product_id}/subscribe`);
             const subscription = await client.subscribeToProduct(args.product_id, args.idempotency_key);
             return { result: formatSubscription(subscription), data: subscription };
           }
@@ -232,23 +222,22 @@ export function createSubscriptionTool() {
           }
 
           case "list_subscribers": {
-            if (!args.product_id) return { error: "product_id is required" };
+            if (!args.product_id) return validationError("product_id is required");
             const subscriptions = await client.listProductSubscribers(args.product_id);
             return { result: formatSubscriptionList(subscriptions), data: subscriptions };
           }
 
           case "cancel": {
-            if (!args.subscription_id) return { error: "subscription_id is required" };
+            if (!args.subscription_id) return validationError("subscription_id is required");
+            if (args.dry_run) return dryRunResult("POST", `/subscriptions/${args.subscription_id}/cancel`);
             const subscription = await client.cancelSubscription(args.subscription_id);
             return { result: formatSubscription(subscription), data: subscription };
           }
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Subscription action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/tool-result.ts

@@ -28,7 +28,8 @@ export interface DryRunRequest {
   method: string;
   path: string;
   body?: unknown;
-  query?: Record<string, string>;
+  query?: Record<string, string | string[]>;
+  note?: string;
 }
 
 export type DryRunResult = { ok: true; dry_run: true; request: DryRunRequest };
@@ -60,11 +61,17 @@ export function apiError(code: string, message: string, hint?: string): ToolFail
   return fail("api", code, message, hint);
 }
 
-export function dryRunResult(method: string, path: string, body?: unknown, query?: Record<string, string>): DryRunResult {
+export function dryRunResult(method: string, path: string, body?: unknown, options?: { query?: Record<string, string | string[]>; note?: string }): DryRunResult {
   return {
     ok: true,
     dry_run: true,
-    request: { method, path, ...(body !== undefined ? { body } : {}), ...(query ? { query } : {}) },
+    request: {
+      method,
+      path,
+      ...(body !== undefined ? { body } : {}),
+      ...(options?.query ? { query: options.query } : {}),
+      ...(options?.note ? { note: options.note } : {}),
+    },
   };
 }