@botcord/botcord 0.2.3 → 0.3.0-beta.20260401151650

package/index.ts

@@ -7,6 +7,7 @@ import { createMessagingTool, createUploadTool } from "./src/tools/messaging.js"
 import { createRoomsTool } from "./src/tools/rooms.js";
 import { createContactsTool } from "./src/tools/contacts.js";
 import { createDirectoryTool } from "./src/tools/directory.js";
+import { createRoomContextTool } from "./src/tools/room-context.js";
 import { createTopicsTool } from "./src/tools/topics.js";
 import { createAccountTool } from "./src/tools/account.js";
 import { createPaymentTool } from "./src/tools/payment.js";
@@ -27,6 +28,9 @@ import {
   recordBotCordOutboundText,
   shouldRunBotCordLoopRiskCheck,
 } from "./src/loop-risk.js";
+import { buildRoomContextHookResult, clearSessionRoom } from "./src/room-context.js";
+import { activeOwnerChatStreams } from "./src/owner-chat-stream.js";
+import { buildWorkingMemoryHookResult } from "./src/memory-hook.js";
 
 // Inline replacement for defineChannelPluginEntry from openclaw/plugin-sdk/core.
 // Avoids missing dist artifacts in npm-installed openclaw (see openclaw#53685).
@@ -51,6 +55,7 @@ export default {
     api.registerTool(createContactsTool() as any);
     api.registerTool(createAccountTool() as any);
     api.registerTool(createDirectoryTool() as any);
+    api.registerTool(createRoomContextTool() as any);
     api.registerTool(createPaymentTool() as any);
     api.registerTool(createSubscriptionTool() as any);
     api.registerTool(createNotifyTool() as any);
@@ -60,6 +65,43 @@ export default {
 
     // Hooks
     api.on("after_tool_call", async (event: any, ctx: any) => {
+      // Stream tool blocks to Hub for active owner-chat sessions
+      const stream = activeOwnerChatStreams.get(ctx.sessionKey);
+      if (stream) {
+        try {
+          const toolName = ctx.toolName ?? "unknown";
+          const paramsSummary: Record<string, unknown> = {};
+          if (event.params && typeof event.params === "object") {
+            // Include only safe summary fields, not full payloads
+            for (const [k, v] of Object.entries(event.params)) {
+              paramsSummary[k] = typeof v === "string" && v.length > 200
+                ? v.slice(0, 200) + "..."
+                : v;
+            }
+          }
+          await stream.client.postStreamBlock(stream.traceId, stream.seq++, {
+            kind: "tool_call",
+            payload: { name: toolName, params: paramsSummary },
+          });
+
+          if (event.result != null) {
+            const resultStr = typeof event.result === "string"
+              ? event.result
+              : JSON.stringify(event.result);
+            await stream.client.postStreamBlock(stream.traceId, stream.seq++, {
+              kind: "tool_result",
+              payload: {
+                name: toolName,
+                result: resultStr.length > 500 ? resultStr.slice(0, 500) + "..." : resultStr,
+              },
+            });
+          }
+        } catch (err) {
+          console.warn("[botcord] owner-chat stream block error:", err);
+        }
+      }
+
+      // Existing loop-risk tracking
       if (ctx.toolName !== "botcord_send") return;
       if (!didBotCordSendSucceed(event.result, event.error)) return;
       recordBotCordOutboundText({
@@ -68,6 +110,19 @@ export default {
       });
     });
 
+    // Room context injection — highest priority among BotCord hooks, so its
+    // prependContext is placed farther from the user prompt.
+    api.on("before_prompt_build", async (_event: any, ctx: any) => {
+      return buildRoomContextHookResult(ctx.sessionKey);
+    }, { priority: 60 });
+
+    // Working memory injection — between room context and loop-risk.
+    api.on("before_prompt_build", async (_event: any, ctx: any) => {
+      return buildWorkingMemoryHookResult(ctx.sessionKey);
+    }, { priority: 50 });
+
+    // Loop-risk guard — lower priority = runs later, so its prependContext
+    // ends up closest to the user prompt where it's most effective.
     api.on("before_prompt_build", async (event: any, ctx: any) => {
       if (!shouldRunBotCordLoopRiskCheck({
         channelId: ctx.channelId,
@@ -85,10 +140,11 @@ export default {
 
       if (!prependContext) return;
       return { prependContext };
-    }, { priority: 10 });
+    }, { priority: 50 });
 
     api.on("session_end", async (_event: any, ctx: any) => {
       clearBotCordLoopRiskSession(ctx.sessionKey);
+      clearSessionRoom(ctx.sessionKey);
     });
 
     // Commands

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "botcord",
   "name": "BotCord",
   "description": "Secure agent-to-agent messaging via the BotCord A2A protocol (Ed25519 signed envelopes)",
-  "version": "0.2.3",
+  "version": "0.3.0-beta.20260401151650",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.2.3",
+  "version": "0.3.0-beta.20260401151650",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",

package/src/client.ts

@@ -171,6 +171,24 @@ export class BotCordClient {
     return data;
   }
 
+  // ── Stream blocks (owner-chat WS) ────────────────────────────
+
+  async postStreamBlock(
+    traceId: string,
+    seq: number,
+    block: { kind: string; payload: Record<string, unknown> },
+  ): Promise<void> {
+    try {
+      await this.hubFetch("/hub/stream-block", {
+        method: "POST",
+        body: JSON.stringify({ trace_id: traceId, seq, block }),
+      });
+    } catch (err) {
+      // Stream blocks are best-effort; log but don't throw
+      console.warn(`[botcord] postStreamBlock failed (trace=${traceId} seq=${seq}):`, err);
+    }
+  }
+
   // ── Messaging ─────────────────────────────────────────────────
 
   async sendMessage(
@@ -764,6 +782,86 @@ export class BotCordClient {
     return (await resp.json()) as Subscription;
   }
 
+  // ── Room Context (retrieve / search) ──────────────────────────
+
+  async roomSummary(roomId: string, recentLimit?: number): Promise<any> {
+    const params = new URLSearchParams();
+    if (recentLimit) params.set("recent_limit", String(recentLimit));
+    const q = params.toString();
+    const resp = await this.hubFetch(`/hub/rooms/${roomId}/summary${q ? `?${q}` : ""}`);
+    return await resp.json();
+  }
+
+  async roomMessages(
+    roomId: string,
+    opts?: {
+      limit?: number;
+      before?: string;
+      after?: string;
+      topicId?: string;
+      senderId?: string;
+    },
+  ): Promise<any> {
+    const params = new URLSearchParams();
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.before) params.set("before", opts.before);
+    if (opts?.after) params.set("after", opts.after);
+    if (opts?.topicId) params.set("topic_id", opts.topicId);
+    if (opts?.senderId) params.set("sender_id", opts.senderId);
+    const q = params.toString();
+    const resp = await this.hubFetch(`/hub/rooms/${roomId}/messages${q ? `?${q}` : ""}`);
+    return await resp.json();
+  }
+
+  async roomSearch(
+    roomId: string,
+    query: string,
+    opts?: {
+      limit?: number;
+      before?: string;
+      topicId?: string;
+      senderId?: string;
+    },
+  ): Promise<any> {
+    const params = new URLSearchParams();
+    params.set("q", query);
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.before) params.set("before", opts.before);
+    if (opts?.topicId) params.set("topic_id", opts.topicId);
+    if (opts?.senderId) params.set("sender_id", opts.senderId);
+    const resp = await this.hubFetch(`/hub/rooms/${roomId}/search?${params.toString()}`);
+    return await resp.json();
+  }
+
+  async roomsOverview(limit?: number): Promise<any> {
+    const params = new URLSearchParams();
+    if (limit) params.set("limit", String(limit));
+    const q = params.toString();
+    const resp = await this.hubFetch(`/hub/rooms/overview${q ? `?${q}` : ""}`);
+    return await resp.json();
+  }
+
+  async globalSearch(
+    query: string,
+    opts?: {
+      limit?: number;
+      roomId?: string;
+      topicId?: string;
+      senderId?: string;
+      before?: string;
+    },
+  ): Promise<any> {
+    const params = new URLSearchParams();
+    params.set("q", query);
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.roomId) params.set("room_id", opts.roomId);
+    if (opts?.topicId) params.set("topic_id", opts.topicId);
+    if (opts?.senderId) params.set("sender_id", opts.senderId);
+    if (opts?.before) params.set("before", opts.before);
+    const resp = await this.hubFetch(`/hub/search?${params.toString()}`);
+    return await resp.json();
+  }
+
   // ── Invites ──────────────────────────────────────────────────
 
   async previewInvite(code: string): Promise<any> {

package/src/constants.ts

@@ -9,7 +9,7 @@
 
 export type ReleaseChannel = "stable" | "beta";
 
-export const RELEASE_CHANNEL: ReleaseChannel = "stable";
+export const RELEASE_CHANNEL: ReleaseChannel = "beta";
 
 const HUB_URLS: Record<ReleaseChannel, string> = {
   stable: "https://api.botcord.chat",

package/src/inbound.ts

@@ -6,6 +6,8 @@ import { getBotCordRuntime } from "./runtime.js";
 import { resolveAccountConfig } from "./config.js";
 import { attachTokenPersistence } from "./credentials.js";
 import { buildSessionKey } from "./session-key.js";
+import { registerSessionRoom } from "./room-context.js";
+import { processOutboundMemory } from "./memory-hook.js";
 import { readFileSync } from "node:fs";
 
 // Simplified inline replacement for loadSessionStore from openclaw/plugin-sdk/mattermost.
@@ -23,6 +25,7 @@ function loadSessionStore(storePath: string): Record<string, any> {
 import { sanitizeUntrustedContent, sanitizeSenderName } from "./sanitize.js";
 import { BotCordClient } from "./client.js";
 import { createBotCordReplyDispatcher } from "./reply-dispatcher.js";
+import { activeOwnerChatStreams } from "./owner-chat-stream.js";
 import type { InboxMessage, MessageType } from "./types.js";
 
 /** Normalize notifySession (string | string[] | undefined) to a flat array. */
@@ -91,6 +94,76 @@ export interface InboundParams {
   mentioned?: boolean;
 }
 
+/**
+ * Batch handler for InboxMessages — groups messages by session key and
+ * dispatches each group as a single combined message to OpenClaw.
+ * Same-session A2A messages are merged into one dispatch to avoid
+ * triggering multiple AI inference calls for the same conversation.
+ *
+ * Returns the hub_msg_ids of successfully handled messages.
+ */
+export async function handleInboxMessageBatch(
+  messages: InboxMessage[],
+  accountId: string,
+  cfg: any,
+): Promise<string[]> {
+  if (messages.length === 0) return [];
+
+  // Separate dashboard user chat messages (not batchable — single fixed session)
+  // and group A2A messages by computed session key.
+  const dashboardMsgs: InboxMessage[] = [];
+  const a2aGroups = new Map<string, InboxMessage[]>();
+
+  for (const msg of messages) {
+    if (msg.source_type === "dashboard_user_chat") {
+      dashboardMsgs.push(msg);
+      continue;
+    }
+    const envelope = msg.envelope;
+    const senderId = envelope.from || "unknown";
+    const roomId = msg.room_id;
+    const topic = msg.topic;
+    const key = buildSessionKey(roomId, topic, senderId);
+    // For group rooms, use roomId+topic as the group key (ignoring sender)
+    // so messages from different senders in the same room are batched.
+    const isGroupRoom = !!roomId && !roomId.startsWith("rm_dm_");
+    const groupKey = isGroupRoom
+      ? buildSessionKey(roomId, topic)
+      : key;
+    const group = a2aGroups.get(groupKey) || [];
+    group.push(msg);
+    a2aGroups.set(groupKey, group);
+  }
+
+  const handledIds: string[] = [];
+
+  // Handle dashboard user chat messages one by one (they share a fixed session)
+  for (const msg of dashboardMsgs) {
+    try {
+      await handleInboxMessage(msg, accountId, cfg);
+      handledIds.push(msg.hub_msg_id);
+    } catch {
+      // Error logged inside handleInboxMessage
+    }
+  }
+
+  // Handle A2A groups — single messages dispatched normally, batches merged
+  for (const [, group] of a2aGroups) {
+    try {
+      if (group.length === 1) {
+        await handleA2AMessage(group[0], accountId, cfg);
+      } else {
+        await handleA2AMessageBatch(group, accountId, cfg);
+      }
+      for (const msg of group) handledIds.push(msg.hub_msg_id);
+    } catch {
+      // Error logged inside handlers
+    }
+  }
+
+  return handledIds;
+}
+
 /**
  * Shared handler for InboxMessage — used by both WebSocket and Poller paths.
  * Normalizes InboxMessage into InboundParams and dispatches to OpenClaw.
@@ -190,27 +263,56 @@ async function handleDashboardUserChat(
     replyTarget,
   });
 
+  // Register owner-chat stream so after_tool_call hook can stream blocks
+  const effectiveSessionKey = route.sessionKey || sessionKey;
+  const traceId = msg.hub_msg_id;
+  if (traceId) {
+    activeOwnerChatStreams.set(effectiveSessionKey, {
+      traceId,
+      client,
+      seq: 1,
+    });
+  }
+
   // Use buffered block dispatcher with auto-delivery to the chat room.
   // The deliver callback receives a ReplyPayload object (not a plain string).
-  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx: ctxPayload,
-    cfg,
-    dispatcherOptions: {
-      deliver: async (payload: any) => {
-        const text = payload?.text ?? "";
-        const mediaUrl = payload?.mediaUrl;
-        if (mediaUrl) {
-          await replyDispatcher.sendMedia(text, mediaUrl);
-        } else if (text) {
-          await replyDispatcher.sendText(text);
-        }
-      },
-      onError: (err: any, info: any) => {
-        console.error(`[botcord] user-chat ${info?.kind ?? "unknown"} reply error:`, err);
+  // Memory extraction: strip <memory_update> blocks and persist before sending.
+  try {
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload: any) => {
+          const rawText = payload?.text ?? "";
+          const text = processOutboundMemory(rawText, sessionKey);
+          const mediaUrl = payload?.mediaUrl;
+
+          // Stream assistant block to Hub before sending the final reply
+          if (traceId && text) {
+            const stream = activeOwnerChatStreams.get(effectiveSessionKey);
+            if (stream) {
+              await client.postStreamBlock(traceId, stream.seq++, {
+                kind: "assistant",
+                payload: { text },
+              });
+            }
+          }
+
+          if (mediaUrl) {
+            await replyDispatcher.sendMedia(text, mediaUrl);
+          } else if (text) {
+            await replyDispatcher.sendText(text);
+          }
+        },
+        onError: (err: any, info: any) => {
+          console.error(`[botcord] user-chat ${info?.kind ?? "unknown"} reply error:`, err);
+        },
       },
-    },
-    replyOptions: {},
-  });
+      replyOptions: {},
+    });
+  } finally {
+    activeOwnerChatStreams.delete(effectiveSessionKey);
+  }
 }
 
 /**
@@ -274,6 +376,89 @@ async function handleA2AMessage(
   });
 }
 
+/**
+ * Handle a batch of A2A messages that share the same session (room + topic).
+ * Combines individual <agent-message> blocks into a single dispatch.
+ */
+async function handleA2AMessageBatch(
+  msgs: InboxMessage[],
+  accountId: string,
+  cfg: any,
+): Promise<void> {
+  // Use the first message for shared room context
+  const first = msgs[0];
+  const isGroupRoom = !!first.room_id && !first.room_id.startsWith("rm_dm_");
+  const chatType = isGroupRoom ? "group" : "direct";
+  const roomName = isGroupRoom ? (first.room_name || first.room_id) : undefined;
+
+  // Build individual <agent-message> blocks for each message
+  const messageBlocks: string[] = [];
+  let anyMentioned = false;
+  let hasContactRequest = false;
+  let contactRequestSender = "";
+
+  for (const msg of msgs) {
+    const envelope = msg.envelope;
+    const senderId = envelope.from || "unknown";
+    const rawContent =
+      msg.text ||
+      (typeof envelope.payload === "string"
+        ? envelope.payload
+        : (envelope.payload?.text as string) ?? JSON.stringify(envelope.payload));
+
+    const sanitizedSender = sanitizeSenderName(senderId);
+    const sanitizedContent = sanitizeUntrustedContent(rawContent);
+    messageBlocks.push(
+      `<agent-message sender="${sanitizedSender}">\n${sanitizedContent}\n</agent-message>`,
+    );
+
+    if (msg.mentioned) anyMentioned = true;
+    if (envelope.type === "contact_request") {
+      hasContactRequest = true;
+      contactRequestSender = sanitizedSender;
+    }
+  }
+
+  // Shared header — indicate batch count
+  const header = `[BotCord Messages (${msgs.length} new)]` +
+    (roomName ? ` | room: ${roomName}` : "") +
+    ` | to: ${accountId}`;
+
+  const silentHint =
+    chatType === "group"
+      ? '\n\n[In group chats, do NOT reply unless you are explicitly mentioned or addressed. If no response is needed, reply with exactly "NO_REPLY" and nothing else.]'
+      : '\n\n[If the conversation has naturally concluded or no response is needed, reply with exactly "NO_REPLY" and nothing else.]';
+
+  const notifyOwnerHint = hasContactRequest
+    ? `\n\n[You received a contact request from ${contactRequestSender}. Use the botcord_notify tool to inform your owner about this request so they can decide whether to accept or reject it. Include the sender's agent ID and any message they attached.]`
+    : "";
+
+  const content = `${header}\n${messageBlocks.join("\n")}${silentHint}${notifyOwnerHint}`;
+  const contentWithRule = isGroupRoom ? appendRoomRule(content, first.room_rule) : content;
+
+  // Use the last message's metadata for dispatch (most recent)
+  const last = msgs[msgs.length - 1];
+  const lastEnvelope = last.envelope;
+  const lastSenderId = lastEnvelope.from || "unknown";
+
+  await dispatchInbound({
+    cfg,
+    accountId,
+    senderName: lastSenderId,
+    senderId: lastSenderId,
+    content: contentWithRule,
+    messageId: lastEnvelope.msg_id,
+    messageType: lastEnvelope.type,
+    chatType,
+    groupSubject: isGroupRoom ? (first.room_name || first.room_id) : undefined,
+    replyTarget: isGroupRoom ? first.room_id! : (lastEnvelope.from || ""),
+    roomId: first.room_id,
+    topic: first.topic,
+    topicId: first.topic_id,
+    mentioned: anyMentioned,
+  });
+}
+
 /**
  * Dispatch an inbound message into OpenClaw's channel routing system.
  */
@@ -307,6 +492,24 @@ export async function dispatchInbound(params: InboundParams): Promise<void> {
     },
   });
 
+  // Track session → room mapping for cross-session context injection.
+  // Register under the *effective* session key (what OpenClaw passes as
+  // ctx.sessionKey in hooks).  When routing overrides the key, use that;
+  // otherwise fall back to the deterministic BotCord key.
+  // Note: if routing merges multiple rooms into one session, last-writer-wins
+  // is intentional — the session context already mixes messages from all rooms.
+  // Also register DM sessions without a roomId so they appear in digests.
+  const effectiveSessionKey = route.sessionKey || sessionKey;
+  const peerId = roomId || senderId;
+  if (peerId) {
+    registerSessionRoom(effectiveSessionKey, {
+      roomId: roomId || `rm_dm_${senderId}`,
+      roomName: groupSubject || roomId || senderName,
+      accountId,
+      lastActivityAt: Date.now(),
+    });
+  }
+
   const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
   const formattedBody = core.channel.reply.formatAgentEnvelope({
     channel: "BotCord",
@@ -348,7 +551,11 @@ export async function dispatchInbound(params: InboundParams): Promise<void> {
     dispatcherOptions: {
       // A2A replies are sent explicitly via botcord_send tool.
       // Suppress automatic delivery to avoid leaking agent narration.
-      deliver: async () => {},
+      // Still extract <memory_update> blocks from the suppressed text.
+      deliver: async (payload: any) => {
+        const rawText = payload?.text ?? "";
+        if (rawText) processOutboundMemory(rawText, effectiveSessionKey);
+      },
       onError: (err: any, info: any) => {
         console.error(`[botcord] ${info?.kind ?? "unknown"} reply error:`, err);
       },

package/src/memory-hook.ts

@@ -0,0 +1,71 @@
+/**
+ * Memory hook — glue between OpenClaw hooks and the memory subsystem.
+ *
+ * - buildWorkingMemoryHookResult(): before_prompt_build handler
+ * - processOutboundMemory(): extract <memory_update> from outbound text,
+ *   persist to disk, return cleaned text
+ */
+import { readWorkingMemory, writeWorkingMemory } from "./memory.js";
+import { buildWorkingMemoryPrompt, extractMemoryUpdate } from "./memory-protocol.js";
+import { getSessionRoom } from "./room-context.js";
+
+// ── before_prompt_build handler ────────────────────────────────────
+
+/**
+ * Build the working memory hook result for injection into the agent prompt.
+ * Returns prependContext so it appears close to the user message.
+ */
+export async function buildWorkingMemoryHookResult(
+  sessionKey: string | undefined,
+): Promise<{ prependContext?: string } | null> {
+  if (!sessionKey) return null;
+
+  // Inject for registered BotCord sessions and the owner-chat session.
+  // Owner-chat uses a fixed key and is never registered via inbound dispatch,
+  // but still needs working memory for cross-session continuity.
+  const isOwnerChat = sessionKey === "botcord:owner:main";
+  if (!isOwnerChat && !getSessionRoom(sessionKey)) return null;
+
+  try {
+    const wm = readWorkingMemory();
+    const prompt = buildWorkingMemoryPrompt({ workingMemory: wm });
+    return { prependContext: prompt };
+  } catch (err: any) {
+    console.warn("[botcord] memory-hook: failed to read working memory:", err?.message ?? err);
+    return null;
+  }
+}
+
+// ── Outbound memory extraction ─────────────────────────────────────
+
+/**
+ * Process outbound text for <memory_update> blocks.
+ *
+ * - Extracts the memory content and persists to working-memory.json
+ * - Returns the cleaned text (without <memory_update> blocks)
+ *
+ * Safe to call on any text — returns the original if no memory blocks found.
+ */
+export function processOutboundMemory(
+  text: string,
+  sessionKey?: string,
+): string {
+  if (!text) return text;
+
+  const { cleanedText, memoryContent } = extractMemoryUpdate(text);
+
+  if (memoryContent !== null) {
+    try {
+      writeWorkingMemory({
+        version: 1,
+        content: memoryContent,
+        updatedAt: new Date().toISOString(),
+        sourceSessionKey: sessionKey,
+      });
+    } catch (err: any) {
+      console.error("[botcord] memory-hook: failed to write working memory:", err?.message ?? err);
+    }
+  }
+
+  return cleanedText;
+}