@botcord/botcord 0.2.2 → 0.2.4-beta.20260329125010

package/src/tools/account.ts

@@ -1,14 +1,8 @@
 /**
  * botcord_account — Manage the agent's own identity, profile, and settings.
  */
-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 createAccountTool() {
   return {
@@ -41,57 +35,64 @@ export function createAccountTool() {
           type: "string" as const,
           description: "Message ID — for message_status",
         },
+        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);
+      return withClient(async (client) => {
+        // Dry-run for write operations
+        if (args.dry_run) {
+          switch (args.action) {
+            case "update_profile": {
+              if (!args.display_name && !args.bio) return validationError("At least one of display_name or bio is required");
+              const params: Record<string, string> = {};
+              if (args.display_name) params.display_name = args.display_name;
+              if (args.bio) params.bio = args.bio;
+              return dryRunResult("PATCH", `/registry/agents/${client.getAgentId()}/profile`, params) as any;
+            }
+            case "set_policy":
+              if (!args.policy) return validationError("policy is required (open or contacts_only)");
+              return dryRunResult("PATCH", `/registry/agents/${client.getAgentId()}/policy`, { message_policy: args.policy }) as any;
+            default:
+              break;
+          }
+        }
 
-      try {
         switch (args.action) {
           case "whoami":
-            return await client.resolve(client.getAgentId());
+            return await client.resolve(client.getAgentId()) as any;
 
           case "update_profile": {
             if (!args.display_name && !args.bio) {
-              return { error: "At least one of display_name or bio is required" };
+              return validationError("At least one of display_name or bio is required");
             }
             const params: { display_name?: string; bio?: string } = {};
             if (args.display_name) params.display_name = args.display_name;
             if (args.bio) params.bio = args.bio;
             await client.updateProfile(params);
-            return { ok: true, updated: params };
+            return { ok: true, updated: params } as any;
           }
 
           case "get_policy":
-            return await client.getPolicy();
+            return await client.getPolicy() as any;
 
           case "set_policy":
-            if (!args.policy) return { error: "policy is required (open or contacts_only)" };
+            if (!args.policy) return validationError("policy is required (open or contacts_only)");
             await client.setPolicy(args.policy);
-            return { ok: true, policy: args.policy };
+            return { ok: true, policy: args.policy } as any;
 
           case "message_status":
-            if (!args.msg_id) return { error: "msg_id is required" };
-            return await client.getMessageStatus(args.msg_id);
+            if (!args.msg_id) return validationError("msg_id is required");
+            return await client.getMessageStatus(args.msg_id) as any;
 
           default:
-            return { error: `Unknown action: ${args.action}` };
+            return validationError(`Unknown action: ${args.action}`);
         }
-      } catch (err: any) {
-        return { error: `Account action failed: ${err.message}` };
-      }
+      });
     },
   };
 }

package/src/tools/api.ts

@@ -0,0 +1,54 @@
+/**
+ * botcord_api — Raw Hub API access for advanced use cases.
+ *
+ * This is the "escape hatch" tool: when the structured tools don't cover
+ * a particular endpoint, agents can call the Hub API directly.
+ */
+import { withClient } from "./with-client.js";
+import { validationError } from "./tool-result.js";
+
+export function createApiTool() {
+  return {
+    name: "botcord_api",
+    label: "Raw API",
+    description:
+      "Execute a raw authenticated request against the BotCord Hub API. " +
+      "Use this when the structured tools (botcord_send, botcord_rooms, etc.) " +
+      "don't cover the endpoint you need. The request is automatically authenticated with your agent's JWT.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        method: {
+          type: "string" as const,
+          enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          description: "HTTP method",
+        },
+        path: {
+          type: "string" as const,
+          description: "API path (e.g. /hub/inbox, /registry/agents/ag_xxx)",
+        },
+        query: {
+          type: "object" as const,
+          description: "Query parameters as key-value pairs",
+        },
+        data: {
+          type: "object" as const,
+          description: "Request body (for POST/PUT/PATCH)",
+        },
+      },
+      required: ["method", "path"],
+    },
+    execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
+      if (!args.method) return validationError("method is required");
+      if (!args.path) return validationError("path is required");
+
+      return withClient(async (client) => {
+        const result = await client.request(args.method, args.path, {
+          body: args.data,
+          query: args.query,
+        });
+        return { response: result } as any;
+      });
+    },
+  };
+}

package/src/tools/bind.ts

@@ -4,14 +4,8 @@
  * [POS]: plugin dashboard 认领执行器，把命令行参数翻译成稳定的绑定请求
  * [PROTOCOL]: 变更时更新此头部，然后检查 README.md
  */
-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";
 
 const DEFAULT_DASHBOARD_URL = "https://www.botcord.chat";
 
@@ -21,21 +15,8 @@ const DEFAULT_DASHBOARD_URL = "https://www.botcord.chat";
 export async function executeBind(
   bindCredential: string,
   dashboardUrl?: string,
-): Promise<{ ok: true; [key: string]: unknown } | { error: string }> {
-  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) => {
     const agentToken = await client.ensureToken();
     const agentId = client.getAgentId();
 
@@ -62,13 +43,13 @@ export async function executeBind(
 
     if (!res.ok) {
       const msg = body?.error || body?.message || res.statusText;
-      return { error: `Dashboard bind failed (${res.status}): ${msg}` };
+      const err = new Error(`Dashboard bind failed (${res.status}): ${msg}`);
+      (err as any).status = res.status;
+      throw err;
     }
 
-    return { ok: true, ...body };
-  } catch (err: any) {
-    return { error: `Bind failed: ${err.message}` };
-  }
+    return { ok: true, ...body } as any;
+  });
 }
 
 export function createBindTool() {
@@ -93,7 +74,7 @@ export function createBindTool() {
     },
     execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
       if (!args.bind_ticket) {
-        return { error: "bind_ticket is required" };
+        return validationError("bind_ticket is required");
       }
       return executeBind(args.bind_ticket, args.dashboard_url);
     },

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 {
@@ -51,73 +45,88 @@ 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);
+      return withClient(async (client) => {
+        // Dry-run for write operations
+        if (args.dry_run) {
+          switch (args.action) {
+            case "send_request":
+              if (!args.agent_id) return validationError("agent_id is required");
+              return dryRunResult("POST", "/hub/send", { to: args.agent_id, type: "contact_request", payload: args.message ? { text: args.message } : {} }) as any;
+            case "remove":
+              if (!args.agent_id) return validationError("agent_id is required");
+              return dryRunResult("DELETE", `/registry/agents/{self}/contacts/${args.agent_id}`) as any;
+            case "accept_request":
+              if (!args.request_id) return validationError("request_id is required");
+              return dryRunResult("POST", `/registry/agents/{self}/contact-requests/${args.request_id}/accept`) as any;
+            case "reject_request":
+              if (!args.request_id) return validationError("request_id is required");
+              return dryRunResult("POST", `/registry/agents/{self}/contact-requests/${args.request_id}/reject`) as any;
+            case "block":
+              if (!args.agent_id) return validationError("agent_id is required");
+              return dryRunResult("POST", `/registry/agents/{self}/blocks`, { blocked_agent_id: args.agent_id }) as any;
+            case "unblock":
+              if (!args.agent_id) return validationError("agent_id is required");
+              return dryRunResult("DELETE", `/registry/agents/{self}/blocks/${args.agent_id}`) as any;
+            default:
+              break;
+          }
+        }
 
-      try {
         switch (args.action) {
           case "list":
-            return await client.listContacts();
+            return { contacts: await client.listContacts() } as any;
 
           case "remove":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
             await client.removeContact(args.agent_id);
-            return { ok: true, removed: args.agent_id };
+            return { ok: true, removed: args.agent_id } as any;
 
           case "send_request":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
             await client.sendContactRequest(args.agent_id, args.message);
-            return { ok: true, sent_to: args.agent_id };
+            return { ok: true, sent_to: args.agent_id } as any;
 
           case "received_requests":
-            return await client.listReceivedRequests(args.state);
+            return { requests: await client.listReceivedRequests(args.state) } as any;
 
           case "sent_requests":
-            return await client.listSentRequests(args.state);
+            return { requests: await client.listSentRequests(args.state) } as any;
 
           case "accept_request":
-            if (!args.request_id) return { error: "request_id is required" };
+            if (!args.request_id) return validationError("request_id is required");
             await client.acceptRequest(args.request_id);
-            return { ok: true, accepted: args.request_id };
+            return { ok: true, accepted: args.request_id } as any;
 
           case "reject_request":
-            if (!args.request_id) return { error: "request_id is required" };
+            if (!args.request_id) return validationError("request_id is required");
             await client.rejectRequest(args.request_id);
-            return { ok: true, rejected: args.request_id };
+            return { ok: true, rejected: args.request_id } as any;
 
           case "block":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
             await client.blockAgent(args.agent_id);
-            return { ok: true, blocked: args.agent_id };
+            return { ok: true, blocked: args.agent_id } as any;
 
           case "unblock":
-            if (!args.agent_id) return { error: "agent_id is required" };
+            if (!args.agent_id) return validationError("agent_id is required");
             await client.unblockAgent(args.agent_id);
-            return { ok: true, unblocked: args.agent_id };
+            return { ok: true, unblocked: args.agent_id } as any;
 
           case "list_blocks":
-            return await client.listBlocks();
+            return { blocks: await client.listBlocks() } as any;
 
           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" };
-            return await client.resolve(args.agent_id);
+            if (!args.agent_id) return validationError("agent_id is required");
+            return await client.resolve(args.agent_id) as any;
 
           case "discover_rooms":
-            return await client.discoverRooms(args.room_name);
+            return { rooms: await client.discoverRooms(args.room_name) } as any;
 
           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,
-            });
+            }) } as any;
 
           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,27 @@ 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;
+        return dryRunResult("POST", "/hub/send", body);
       }
 
-      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
@@ -172,7 +170,7 @@ export function createMessagingTool() {
             mentions: args.mentions,
             attachments: finalAttachments,
           });
-          return { ok: true, hub_msg_id: result.hub_msg_id, to: args.to, attachments: finalAttachments };
+          return { ok: true, hub_msg_id: result.hub_msg_id, to: args.to, attachments: finalAttachments } as any;
         }
 
         // result/error types — use sendTypedMessage for topic termination
@@ -181,10 +179,8 @@ export function createMessagingTool() {
           topic: args.topic,
           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}` };
-      }
+        return { ok: true, hub_msg_id: result.hub_msg_id, to: args.to, type: msgType, attachments: finalAttachments } as any;
+      });
     },
   };
 }
@@ -212,28 +208,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}` };
-      }
+        return { ok: true, files: uploaded } as any;
+      });
     },
   };
 }

package/src/tools/notify.ts

@@ -4,9 +4,9 @@
  * is important enough to warrant notifying the owner.
  */
 import { getBotCordRuntime } from "../runtime.js";
-import { getConfig as getAppConfig } from "../runtime.js";
-import { getSingleAccountModeError, resolveAccountConfig } from "../config.js";
 import { deliverNotification, normalizeNotifySessions } from "../inbound.js";
+import { withConfig } from "./with-client.js";
+import { validationError } from "./tool-result.js";
 
 export function createNotifyTool() {
   return {
@@ -28,40 +28,38 @@ export function createNotifyTool() {
       required: ["text"],
     },
     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);
-      const sessions = normalizeNotifySessions(acct.notifySession);
-      if (sessions.length === 0) {
-        return { error: "notifySession is not configured in channels.botcord" };
-      }
+      return withConfig(async (cfg, acct) => {
+        const sessions = normalizeNotifySessions(acct.notifySession);
+        if (sessions.length === 0) {
+          return validationError(
+            "notifySession is not configured in channels.botcord",
+          );
+        }
 
-      const core = getBotCordRuntime();
-      const text = typeof args.text === "string" ? args.text.trim() : "";
-      if (!text) {
-        return { error: "text is required" };
-      }
+        const core = getBotCordRuntime();
+        const text = typeof args.text === "string" ? args.text.trim() : "";
+        if (!text) {
+          return validationError("text is required");
+        }
 
-      const errors: string[] = [];
-      for (const ns of sessions) {
-        try {
-          await deliverNotification(core, cfg, ns, text);
-        } catch (err: any) {
-          errors.push(`${ns}: ${err?.message ?? err}`);
+        const errors: string[] = [];
+        for (const ns of sessions) {
+          try {
+            await deliverNotification(core, cfg, ns, text);
+          } catch (err: any) {
+            errors.push(`${ns}: ${err?.message ?? err}`);
+          }
         }
-      }
 
-      if (errors.length > 0) {
-        return {
-          ok: errors.length < sessions.length,
-          notifySessions: sessions,
-          errors,
-        };
-      }
-      return { ok: true, notifySessions: sessions };
+        if (errors.length > 0) {
+          return {
+            ok: errors.length < sessions.length,
+            notifySessions: sessions,
+            errors,
+          } as any;
+        }
+        return { ok: true, notifySessions: sessions } as any;
+      });
     },
   };
 }