@botcord/botcord 0.3.6 → 0.3.7

package/src/session-key.ts

@@ -1,59 +1 @@
-/**
- * Deterministic session key derivation.
- * Must match hub/forward.py build_session_key() exactly.
- */
-import { createHash } from "node:crypto";
-
-// UUID v5 namespace — must match hub/constants.py SESSION_KEY_NAMESPACE
-const SESSION_KEY_NAMESPACE = "d4e8f2a1-3b6c-4d5e-9f0a-1b2c3d4e5f6a";
-
-/**
- * RFC 4122 UUID v5 (SHA-1 based, deterministic).
- */
-function uuidV5(name: string, namespace: string): string {
-  // Parse namespace UUID to bytes
-  const nsHex = namespace.replace(/-/g, "");
-  const nsBytes = Buffer.from(nsHex, "hex");
-
-  const hash = createHash("sha1")
-    .update(nsBytes)
-    .update(Buffer.from(name, "utf-8"))
-    .digest();
-
-  // Set version (5) and variant (RFC 4122)
-  hash[6] = (hash[6] & 0x0f) | 0x50;
-  hash[8] = (hash[8] & 0x3f) | 0x80;
-
-  const hex = hash.subarray(0, 16).toString("hex");
-  return [
-    hex.slice(0, 8),
-    hex.slice(8, 12),
-    hex.slice(12, 16),
-    hex.slice(16, 20),
-    hex.slice(20, 32),
-  ].join("-");
-}
-
-/**
- * Derive a deterministic sessionKey from room_id, optional topic, and senderId.
- * Same inputs always produce the same key.
- *
- * - Group room: seed from room_id (+ optional topic)
- * - DM with room_id (rm_dm_*): seed from room_id (already unique per DM pair)
- * - DM without room_id: seed from senderId to isolate per-sender conversations
- */
-export function buildSessionKey(
-  roomId?: string,
-  topic?: string,
-  senderId?: string,
-): string {
-  let seed: string;
-  if (roomId) {
-    seed = topic ? `${roomId}:${topic}` : roomId;
-  } else if (senderId) {
-    seed = `dm:${senderId}`;
-  } else {
-    seed = "default";
-  }
-  return `botcord:${uuidV5(seed, SESSION_KEY_NAMESPACE)}`;
-}
+export * from "@botcord/protocol-core";

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,35 +35,25 @@ 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);
-
-      try {
+      return withClient(async (client) => {
         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" };
-            }
+            if (!args.display_name && !args.bio) 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;
+            if (args.dry_run) return dryRunResult("PATCH", `/registry/agents/${client.getAgentId()}/profile`, params);
             await client.updateProfile(params);
             return { ok: true, updated: params };
           }
@@ -77,21 +61,21 @@ export function createAccountTool() {
           case "get_policy":
             return await client.getPolicy();
 
-          case "set_policy":
-            if (!args.policy) return { error: "policy is required (open or contacts_only)" };
+          case "set_policy": {
+            if (!args.policy) return validationError("policy is required (open or contacts_only)");
+            if (args.dry_run) return dryRunResult("PATCH", `/registry/agents/${client.getAgentId()}/policy`, { message_policy: args.policy });
             await client.setPolicy(args.policy);
             return { ok: true, policy: args.policy };
+          }
 
           case "message_status":
-            if (!args.msg_id) return { error: "msg_id is required" };
+            if (!args.msg_id) return validationError("msg_id is required");
             return await client.getMessageStatus(args.msg_id);
 
           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,112 @@
+/**
+ * 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)",
+        },
+        confirm: {
+          type: "boolean" as const,
+          description: "Must be true for write operations (POST/PUT/PATCH/DELETE). Safety gate to prevent unintended mutations.",
+        },
+      },
+      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");
+
+      const method = (args.method as string).toUpperCase();
+      const path = args.path as string;
+
+      // Validate path to prevent SSRF / path traversal.
+      const ALLOWED_PREFIXES = ["/hub/", "/registry/", "/wallet/", "/subscriptions/", "/app/"];
+
+      // Reject absolute URLs (scheme://...) — path must be relative to Hub
+      if (/^[a-z][a-z0-9+.-]*:/i.test(path)) {
+        return validationError(
+          "Absolute URLs are not allowed — provide a path like /hub/inbox",
+          "Path traversal and arbitrary URLs are not allowed.",
+        );
+      }
+
+      // Reject query strings embedded in path — callers must use the query field.
+      // URL normalization strips ?… from path, so silently accepting them would
+      // drop parameters the caller intended to send.
+      if (path.includes("?")) {
+        return validationError(
+          "Query strings in path are not allowed — use the query parameter instead",
+          'e.g. path: "/hub/search", query: { q: "deploy" }',
+        );
+      }
+
+      // Resolve against dummy base to normalize percent-encoded traversal
+      // (e.g. /%2e%2e/ → /../ → resolved away by URL constructor)
+      let resolvedPath: string;
+      try {
+        resolvedPath = new URL(path, "http://localhost").pathname;
+      } catch {
+        return validationError("Invalid path", "Could not parse the provided path as a URL.");
+      }
+      const normalized = resolvedPath.replace(/\/+/g, "/"); // collapse duplicate slashes
+      if (normalized.includes("..") || !ALLOWED_PREFIXES.some((p) => normalized.startsWith(p))) {
+        return validationError(
+          `path must start with one of: ${ALLOWED_PREFIXES.join(", ")}`,
+          "Path traversal and arbitrary URLs are not allowed.",
+        );
+      }
+
+      // Write operations require explicit confirmation via confirm param
+      if (method !== "GET" && !args.confirm) {
+        return {
+          ok: false,
+          error: {
+            type: "validation" as const,
+            code: "confirmation_required",
+            message: `${method} ${path} is a write operation — set confirm: true to proceed`,
+            hint: "Raw API write operations bypass structured tool safeguards. Review the request carefully before confirming.",
+          },
+        };
+      }
+
+      return withClient(async (client) => {
+        // Use the normalized path so the request matches what was validated
+        const result = await client.request(method, normalized, {
+          body: args.data,
+          query: args.query,
+        });
+        return { response: result };
+      });
+    },
+  };
+}

package/src/tools/bind.ts

@@ -4,44 +4,26 @@
  * [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";
+import { HubApiError } from "../client.js";
 
 /**
  * Shared bind logic used by both the tool and the command.
  */
 export async function executeBind(
   bindCredential: 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();
 
     const resolved = (await client.resolve(agentId)) as Record<string, unknown>;
     const displayName = (resolved.display_name as string) || agentId;
 
-    const hubUrl = client.getHubUrl();
+    const baseUrl = client.getHubUrl().replace(/\/+$/, "");
 
-    const res = await fetch(`${hubUrl}/api/users/me/agents/bind`, {
+    const res = await fetch(`${baseUrl}/api/users/me/agents/bind`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -59,13 +41,11 @@ export async function executeBind(
 
     if (!res.ok) {
       const msg = body?.error || body?.detail || body?.message || res.statusText;
-      return { error: `Bind failed (${res.status}): ${msg}` };
+      throw new HubApiError(res.status, JSON.stringify({ detail: msg }), "/api/users/me/agents/bind");
     }
 
     return { ok: true, ...body };
-  } catch (err: any) {
-    return { error: `Bind failed: ${err.message}` };
-  }
+  });
 }
 
 export function createBindTool() {
@@ -86,7 +66,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);
     },

package/src/tools/contacts.ts

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

package/src/tools/directory.ts

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

package/src/tools/messaging.ts

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