@botcord/botcord 0.3.6 → 0.3.8-beta.20260415044559

package/src/dynamic-context.ts

@@ -16,12 +16,13 @@
  * out of the box with zero config.
  */
 import { buildCrossRoomDigest, getSessionRoom } from "./room-context.js";
-import { readWorkingMemory } from "./memory.js";
+import { readWorkingMemory, readOrSeedWorkingMemory } from "./memory.js";
 import { buildWorkingMemoryPrompt } from "./memory-protocol.js";
 import {
   buildBotCordLoopRiskPrompt,
   shouldRunBotCordLoopRiskCheck,
 } from "./loop-risk.js";
+import type { BotCordClient as BotCordClientType } from "./client.js";
 
 /**
  * Build the dynamic context for a BotCord session.
@@ -35,8 +36,10 @@ export async function buildDynamicContext(params: {
   prompt?: string;
   messages?: unknown[];
   trigger?: string;
+  client?: BotCordClientType;
+  credentialsFile?: string;
 }): Promise<string | null> {
-  const { sessionKey, channelId, prompt, messages, trigger } = params;
+  const { sessionKey, channelId, prompt, messages, trigger, client, credentialsFile } = params;
 
   const isOwnerChat = sessionKey === "botcord:owner:main";
   const isBotCordSession = isOwnerChat || !!getSessionRoom(sessionKey);
@@ -49,9 +52,11 @@ export async function buildDynamicContext(params: {
   const digest = await buildCrossRoomDigest(sessionKey);
   if (digest) parts.push(digest);
 
-  // 2. Working memory
+  // 2. Working memory (with lazy seed from API on first read)
   try {
-    const wm = readWorkingMemory();
+    const wm = client
+      ? await readOrSeedWorkingMemory({ client, credentialsFile })
+      : readWorkingMemory();
     const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
     parts.push(memoryPrompt);
   } catch (err: unknown) {

package/src/hub-url.ts

@@ -1,41 +1 @@
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
-
-function isLoopbackHost(hostname: string): boolean {
-  const normalized = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
-  return LOOPBACK_HOSTS.has(normalized) || normalized.endsWith(".localhost");
-}
-
-export function normalizeAndValidateHubUrl(hubUrl: string): string {
-  const trimmed = hubUrl.trim();
-  if (!trimmed) {
-    throw new Error("BotCord hubUrl is required");
-  }
-
-  let parsed: URL;
-  try {
-    parsed = new URL(trimmed);
-  } catch {
-    throw new Error(`BotCord hubUrl must be a valid absolute URL: ${hubUrl}`);
-  }
-
-  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-    throw new Error("BotCord hubUrl must use http:// or https://");
-  }
-
-  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
-    throw new Error(
-      "BotCord hubUrl must use https:// unless it targets localhost, 127.0.0.1, or ::1 for local development",
-    );
-  }
-
-  return trimmed.replace(/\/$/, "");
-}
-
-export function buildHubWebSocketUrl(hubUrl: string): string {
-  const parsed = new URL(normalizeAndValidateHubUrl(hubUrl));
-  parsed.protocol = parsed.protocol === "https:" ? "wss:" : "ws:";
-  parsed.search = "";
-  parsed.hash = "";
-  parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/hub/ws`;
-  return parsed.toString();
-}
+export * from "@botcord/protocol-core";

package/src/memory.ts

@@ -12,6 +12,8 @@ import path from "node:path";
 import os from "node:os";
 import { getBotCordRuntime, getConfig } from "./runtime.js";
 import { resolveAccountConfig } from "./config.js";
+import { isLegacyOnboarded } from "./credentials.js";
+import type { BotCordClient as BotCordClientType } from "./client.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -197,6 +199,54 @@ export function writeWorkingMemory(
   writeJsonFileAtomic(workingMemoryPath(memDir), data);
 }
 
+// ── Seed (lazy init) ──────────────────────────────────────────────
+
+/**
+ * Read working memory with lazy seed from Hub API.
+ *
+ * If local memory file does not exist:
+ * 1. Check the legacy onboardedAt flag → skip seed if set (migration bridge).
+ * 2. Fetch default memory from GET /hub/memory/default.
+ * 3. Write the seed to local file and return it.
+ *
+ * This is the ONLY entry point that should be used on the "display path"
+ * (i.e., injecting memory into the agent prompt). Write-tool internal reads
+ * (read-before-update) should continue using readWorkingMemory() directly.
+ */
+export async function readOrSeedWorkingMemory(params: {
+  client: BotCordClientType;
+  credentialsFile?: string;
+  memDir?: string;
+}): Promise<WorkingMemory | null> {
+  const { client, credentialsFile, memDir } = params;
+
+  // 1. Local file exists → return as-is
+  const existing = readWorkingMemory(memDir);
+  if (existing) return existing;
+
+  // 2. Migration bridge: agent already onboarded under legacy system → skip seed
+  if (credentialsFile && isLegacyOnboarded(credentialsFile)) return null;
+
+  // 3. Fetch seed from Hub API
+  try {
+    const seed = await client.getDefaultMemory();
+    if (seed && typeof seed === "object" && seed.version === 2) {
+      const wm: WorkingMemory = {
+        version: 2,
+        goal: typeof seed.goal === "string" ? seed.goal : undefined,
+        sections: seed.sections && typeof seed.sections === "object" ? seed.sections as Record<string, string> : {},
+        updatedAt: new Date().toISOString(),
+      };
+      writeWorkingMemory(wm, memDir);
+      return wm;
+    }
+  } catch {
+    // Offline / network error → no onboarding guidance, but don't block
+  }
+
+  return null;
+}
+
 // ── Room State ─────────────────────────────────────────────────────
 
 function roomStatePath(roomId: string, memDir?: string): string {

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}` };
-      }
+      });
     },
   };
 }