@botcord/botcord 0.1.1

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/bind.ts

@@ -0,0 +1,96 @@
+/**
+ * botcord_bind — Bind this BotCord agent to a user's web dashboard account.
+ *
+ * Also exports `executeBind()` shared helper used by both the tool and the
+ * `/botcord_bind` command.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+const DEFAULT_DASHBOARD_URL = "https://www.botcord.chat";
+
+/**
+ * Shared bind logic used by both the tool and the command.
+ */
+export async function executeBind(
+  bindTicket: 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);
+
+  try {
+    const agentToken = await client.ensureToken();
+    const agentId = client.getAgentId();
+
+    const resolved = (await client.resolve(agentId)) as Record<string, unknown>;
+    const displayName = (resolved.display_name as string) || agentId;
+
+    const baseUrl = (dashboardUrl || DEFAULT_DASHBOARD_URL).replace(/\/+$/, "");
+
+    const res = await fetch(`${baseUrl}/api/users/me/agents/bind`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        agent_id: agentId,
+        display_name: displayName,
+        agent_token: agentToken,
+        bind_ticket: bindTicket,
+      }),
+      signal: AbortSignal.timeout(15000),
+    });
+
+    const body = await res.json().catch(() => null);
+
+    if (!res.ok) {
+      const msg = body?.error || body?.message || res.statusText;
+      return { error: `Dashboard bind failed (${res.status}): ${msg}` };
+    }
+
+    return { ok: true, ...body };
+  } catch (err: any) {
+    return { error: `Bind failed: ${err.message}` };
+  }
+}
+
+export function createBindTool() {
+  return {
+    name: "botcord_bind",
+    description:
+      "Bind this BotCord agent to a user's web dashboard account using a bind ticket.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        bind_ticket: {
+          type: "string" as const,
+          description: "The bind ticket from the BotCord web dashboard",
+        },
+        dashboard_url: {
+          type: "string" as const,
+          description: `Dashboard base URL (defaults to ${DEFAULT_DASHBOARD_URL})`,
+        },
+      },
+      required: ["bind_ticket"],
+    },
+    execute: async (toolCallId: any, args: any, signal?: any, onUpdate?: any) => {
+      if (!args.bind_ticket) {
+        return { error: "bind_ticket is required" };
+      }
+      return executeBind(args.bind_ticket, args.dashboard_url);
+    },
+  };
+}

package/src/tools/coin-format.ts

@@ -0,0 +1,12 @@
+export function formatCoinAmount(minorValue: string | number | null | undefined): string {
+  const minor = typeof minorValue === "number"
+    ? minorValue
+    : Number.parseInt(minorValue ?? "0", 10);
+
+  if (!Number.isFinite(minor)) return "0.00 COIN";
+
+  return `${(minor / 100).toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  })} COIN`;
+}

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,104 @@
+/**
+ * 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",
+        },
+        topic_id: {
+          type: "string" as const,
+          description: "Topic ID — for history",
+        },
+        before: {
+          type: "string" as const,
+          description: "Return messages before this hub message ID — for history",
+        },
+        after: {
+          type: "string" as const,
+          description: "Return messages after this hub message ID — 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,
+              topicId: args.topic_id,
+              before: args.before,
+              after: args.after,
+              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}` };
+      }
+    },
+  };
+}