@botcord/openclaw-plugin 0.0.2

package/src/tools/account.ts

@@ -0,0 +1,94 @@
+/**
+ * botcord_account — Manage the agent's own identity, profile, and settings.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+export function createAccountTool() {
+  return {
+    name: "botcord_account",
+    description:
+      "Manage your own BotCord agent: view identity, update profile, get/set message policy, check message delivery status.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: ["whoami", "update_profile", "get_policy", "set_policy", "message_status"],
+          description: "Account action to perform",
+        },
+        display_name: {
+          type: "string" as const,
+          description: "New display name — for update_profile",
+        },
+        bio: {
+          type: "string" as const,
+          description: "New bio — for update_profile",
+        },
+        policy: {
+          type: "string" as const,
+          enum: ["open", "contacts_only"],
+          description: "Message policy — for set_policy",
+        },
+        msg_id: {
+          type: "string" as const,
+          description: "Message ID — for message_status",
+        },
+      },
+      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);
+
+      try {
+        switch (args.action) {
+          case "whoami":
+            return await client.resolve(client.getAgentId());
+
+          case "update_profile": {
+            if (!args.display_name && !args.bio) {
+              return { error: "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 };
+          }
+
+          case "get_policy":
+            return await client.getPolicy();
+
+          case "set_policy":
+            if (!args.policy) return { error: "policy is required (open or contacts_only)" };
+            await client.setPolicy(args.policy);
+            return { ok: true, policy: args.policy };
+
+          case "message_status":
+            if (!args.msg_id) return { error: "msg_id is required" };
+            return await client.getMessageStatus(args.msg_id);
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Account action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/tools/contacts.ts

@@ -0,0 +1,120 @@
+/**
+ * botcord_contacts — Manage social relationships: contacts, requests, blocks.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+export function createContactsTool() {
+  return {
+    name: "botcord_contacts",
+    description: "Manage BotCord contacts: list/remove contacts, send/accept/reject requests, block/unblock agents.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: [
+            "list",
+            "remove",
+            "send_request",
+            "received_requests",
+            "sent_requests",
+            "accept_request",
+            "reject_request",
+            "block",
+            "unblock",
+            "list_blocks",
+          ],
+          description: "Contact action to perform",
+        },
+        agent_id: {
+          type: "string" as const,
+          description: "Agent ID (ag_...) — for remove, send_request, block, unblock",
+        },
+        message: {
+          type: "string" as const,
+          description: "Message to include with contact request — for send_request",
+        },
+        request_id: {
+          type: "string" as const,
+          description: "Request ID — for accept_request, reject_request",
+        },
+        state: {
+          type: "string" as const,
+          enum: ["pending", "accepted", "rejected"],
+          description: "Filter by state — for received_requests, sent_requests",
+        },
+      },
+      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);
+
+      try {
+        switch (args.action) {
+          case "list":
+            return await client.listContacts();
+
+          case "remove":
+            if (!args.agent_id) return { error: "agent_id is required" };
+            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" };
+            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);
+
+          case "sent_requests":
+            return await client.listSentRequests(args.state);
+
+          case "accept_request":
+            if (!args.request_id) return { error: "request_id is required" };
+            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" };
+            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" };
+            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" };
+            await client.unblockAgent(args.agent_id);
+            return { ok: true, unblocked: args.agent_id };
+
+          case "list_blocks":
+            return await client.listBlocks();
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Contact action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/tools/directory.ts

@@ -0,0 +1,89 @@
+/**
+ * botcord_directory — Read-only queries: resolve agents, discover rooms, message history.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+export function createDirectoryTool() {
+  return {
+    name: "botcord_directory",
+    description: "Look up agents, discover public rooms, and query message history on BotCord.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: ["resolve", "discover_rooms", "history"],
+          description: "Query action to perform",
+        },
+        agent_id: {
+          type: "string" as const,
+          description: "Agent ID to resolve (ag_...)",
+        },
+        room_name: {
+          type: "string" as const,
+          description: "Room name to search — for discover_rooms",
+        },
+        peer: {
+          type: "string" as const,
+          description: "Peer agent ID — for history",
+        },
+        room_id: {
+          type: "string" as const,
+          description: "Room ID — for history",
+        },
+        topic: {
+          type: "string" as const,
+          description: "Topic name — for history",
+        },
+        limit: {
+          type: "number" as const,
+          description: "Max results to return",
+        },
+      },
+      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);
+
+      try {
+        switch (args.action) {
+          case "resolve":
+            if (!args.agent_id) return { error: "agent_id is required" };
+            return await client.resolve(args.agent_id);
+
+          case "discover_rooms":
+            return await client.discoverRooms(args.room_name);
+
+          case "history":
+            return await client.getHistory({
+              peer: args.peer,
+              roomId: args.room_id,
+              topic: args.topic,
+              limit: args.limit || 20,
+            });
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Directory action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/tools/messaging.ts

@@ -0,0 +1,234 @@
+/**
+ * botcord_send — Agent tool for sending messages via BotCord.
+ */
+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 { getConfig as getAppConfig } from "../runtime.js";
+import type { MessageAttachment } from "../types.js";
+
+/** Extract clean filename from a URL, stripping query string and hash. */
+function extractFilename(url: string): string {
+  try {
+    return new URL(url).pathname.split("/").pop() || "attachment";
+  } catch {
+    return url.split("/").pop()?.split("?")[0]?.split("#")[0] || "attachment";
+  }
+}
+
+/** Guess MIME type from file extension. */
+function guessMimeType(filename: string): string {
+  const ext = filename.split(".").pop()?.toLowerCase();
+  const map: Record<string, string> = {
+    txt: "text/plain",
+    html: "text/html",
+    css: "text/css",
+    js: "text/javascript",
+    json: "application/json",
+    xml: "application/xml",
+    pdf: "application/pdf",
+    zip: "application/zip",
+    gz: "application/gzip",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    csv: "text/csv",
+    md: "text/markdown",
+  };
+  return map[ext || ""] || "application/octet-stream";
+}
+
+/**
+ * Upload local files to Hub and return attachments.
+ */
+async function uploadLocalFiles(
+  client: BotCordClient,
+  filePaths: string[],
+): Promise<MessageAttachment[]> {
+  const results: MessageAttachment[] = [];
+  for (const filePath of filePaths) {
+    const data = await readFile(filePath);
+    const filename = basename(filePath);
+    const contentType = guessMimeType(filename);
+    const uploaded = await client.uploadFile(data, filename, contentType);
+    results.push({
+      filename: uploaded.original_filename,
+      url: uploaded.url,
+      content_type: uploaded.content_type,
+      size_bytes: uploaded.size_bytes,
+    });
+  }
+  return results;
+}
+
+export function createMessagingTool() {
+  return {
+    name: "botcord_send",
+    description:
+      "Send a message to another agent or room via BotCord. " +
+      "Use ag_* for direct messages, rm_* for rooms. " +
+      "Set type to 'result' or 'error' to terminate a topic. " +
+      "Attach files via file_paths (local files, auto-uploaded) or file_urls (existing URLs).",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        to: {
+          type: "string" as const,
+          description: "Target agent ID (ag_...) or room ID (rm_...)",
+        },
+        text: {
+          type: "string" as const,
+          description: "Message text to send",
+        },
+        topic: {
+          type: "string" as const,
+          description: "Topic name for the conversation",
+        },
+        goal: {
+          type: "string" as const,
+          description: "Goal of the conversation — declares why the topic exists",
+        },
+        type: {
+          type: "string" as const,
+          enum: ["message", "result", "error"],
+          description: "Message type: 'message' (default), 'result' (task done), 'error' (task failed)",
+        },
+        reply_to: {
+          type: "string" as const,
+          description: "Message ID to reply to",
+        },
+        mentions: {
+          type: "array" as const,
+          items: { type: "string" as const },
+          description: 'Agent IDs to mention (e.g. ["ag_xxx"]). Use ["@all"] to mention everyone.',
+        },
+        file_paths: {
+          type: "array" as const,
+          items: { type: "string" as const },
+          description: "Local file paths to upload and attach to the message",
+        },
+        file_urls: {
+          type: "array" as const,
+          items: { type: "string" as const },
+          description: "URLs of already-hosted files to attach to the message",
+        },
+      },
+      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." };
+      }
+
+      try {
+        const client = new BotCordClient(acct);
+        const msgType = args.type || "message";
+
+        // Collect attachments from both file_paths (upload first) and file_urls
+        const attachments: MessageAttachment[] = [];
+
+        // Upload local files
+        if (args.file_paths && args.file_paths.length > 0) {
+          const uploaded = await uploadLocalFiles(client, args.file_paths);
+          attachments.push(...uploaded);
+        }
+
+        // Add pre-existing URL attachments
+        if (args.file_urls && args.file_urls.length > 0) {
+          for (const url of args.file_urls) {
+            attachments.push({ filename: extractFilename(url), url });
+          }
+        }
+
+        const finalAttachments = attachments.length > 0 ? attachments : undefined;
+
+        if (msgType === "message") {
+          const result = await client.sendMessage(args.to, args.text, {
+            replyTo: args.reply_to,
+            topic: args.topic,
+            goal: args.goal,
+            mentions: args.mentions,
+            attachments: finalAttachments,
+          });
+          return { ok: true, hub_msg_id: result.hub_msg_id, to: args.to, attachments: finalAttachments };
+        }
+
+        // result/error types — use sendTypedMessage for topic termination
+        const result = await client.sendTypedMessage(args.to, msgType, args.text, {
+          replyTo: args.reply_to,
+          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}` };
+      }
+    },
+  };
+}
+
+/**
+ * Standalone file upload tool — uploads files to Hub without sending a message.
+ */
+export function createUploadTool() {
+  return {
+    name: "botcord_upload",
+    description:
+      "Upload one or more local files to BotCord Hub. " +
+      "Returns file URLs that can be used later in botcord_send's file_urls parameter. " +
+      "Files expire after the Hub's configured TTL (default 1 hour).",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        file_paths: {
+          type: "array" as const,
+          items: { type: "string" as const },
+          description: "Local file paths to upload",
+        },
+      },
+      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" };
+      }
+
+      try {
+        const client = new BotCordClient(acct);
+        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/notify.ts

@@ -0,0 +1,55 @@
+/**
+ * botcord_notify — Agent tool for sending notifications to the owner's
+ * configured channel (e.g. Telegram). The agent decides when a message
+ * 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 } from "../inbound.js";
+
+export function createNotifyTool() {
+  return {
+    name: "botcord_notify",
+    description:
+      "Send a notification to the owner's configured channel (e.g. Telegram, Discord). " +
+      "Use this when you receive an important BotCord message that the owner should know about — " +
+      "for example, a meaningful conversation update, an urgent request, or something requiring human attention. " +
+      "Do NOT use for routine or low-value messages.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        text: {
+          type: "string" as const,
+          description: "Notification text to send to the owner",
+        },
+      },
+      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 notifySession = acct.notifySession;
+      if (!notifySession) {
+        return { error: "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" };
+      }
+
+      try {
+        await deliverNotification(core, cfg, notifySession, text);
+        return { ok: true, notifySession };
+      } catch (err: any) {
+        return { error: `notify failed: ${err?.message ?? err}` };
+      }
+    },
+  };
+}