@botcord/botcord 0.2.3 → 0.3.0-beta.20260401151650

package/src/memory-protocol.ts

@@ -0,0 +1,117 @@
+/**
+ * Memory protocol — prompt injection and <memory_update> extraction.
+ *
+ * - buildWorkingMemoryPrompt(): generates the system context block that
+ *   instructs the agent to use <memory_update> and shows current memory.
+ * - extractMemoryUpdate(): parses agent output, strips <memory_update>
+ *   blocks, and returns the cleaned text + extracted memory content.
+ */
+import type { WorkingMemory } from "./memory.js";
+
+// ── Constants ──────────────────────────────────────────────────────
+
+const MEMORY_SIZE_WARN_CHARS = 2000;
+
+/** Tags that must not appear literally in injected memory content. */
+const RESERVED_TAGS_RE =
+  /<\/?(current_memory|memory_update)\b[^>]*>/gi;
+
+/**
+ * Sanitize memory content before embedding in the prompt.
+ * Neutralizes reserved protocol tags to prevent prompt injection via
+ * persisted memory content.
+ */
+function sanitizeMemoryContent(content: string): string {
+  return content.replace(RESERVED_TAGS_RE, (tag) =>
+    tag.replace(/</g, "‹").replace(/>/g, "›"),
+  );
+}
+
+// ── Prompt builder ─────────────────────────────────────────────────
+
+/**
+ * Build the working memory section to inject into the agent's system prompt.
+ */
+export function buildWorkingMemoryPrompt(params: {
+  workingMemory: WorkingMemory | null;
+  warnLarge?: boolean;
+}): string {
+  const { workingMemory, warnLarge = true } = params;
+
+  const lines: string[] = [
+    `[BotCord Working Memory]`,
+    `You have a persistent working memory that survives across sessions and rooms.`,
+    `Use it to track important facts, pending tasks, and context you want to remember.`,
+    ``,
+    `To update your working memory, include a <memory_update> block in your response:`,
+    `<memory_update>`,
+    `- Complete replacement content for your working memory`,
+    `- Include everything you want to remember (this replaces, not appends)`,
+    `</memory_update>`,
+    ``,
+    `Rules:`,
+    `- The <memory_update> block will be stripped from your visible reply — it is never sent to other agents.`,
+    `- Content inside <memory_update> must be the COMPLETE new working memory, not a delta.`,
+    `- Only update when something meaningful changes. Do not update on every turn.`,
+    `- Keep it concise: focus on actionable items, pending commitments, and key context.`,
+  ];
+
+  if (workingMemory?.content) {
+    const content = sanitizeMemoryContent(workingMemory.content);
+    lines.push(``);
+    lines.push(`Current working memory (last updated: ${workingMemory.updatedAt}):`);
+    lines.push(`<current_memory>`);
+    lines.push(content);
+    lines.push(`</current_memory>`);
+
+    if (warnLarge && content.length > MEMORY_SIZE_WARN_CHARS) {
+      lines.push(``);
+      lines.push(
+        `⚠ Your working memory is ${content.length} characters. ` +
+        `Consider condensing it to keep token usage low.`,
+      );
+    }
+  } else {
+    lines.push(``);
+    lines.push(`Your working memory is currently empty.`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── Memory update extraction ───────────────────────────────────────
+
+const MEMORY_UPDATE_RE =
+  /<memory_update>([\s\S]*?)<\/memory_update>/g;
+
+/**
+ * Extract <memory_update> blocks from agent output text.
+ *
+ * Returns:
+ * - cleanedText: the text with all <memory_update> blocks removed
+ * - memoryContent: the last <memory_update> content (complete replacement),
+ *   or null if no block was found
+ */
+export function extractMemoryUpdate(text: string): {
+  cleanedText: string;
+  memoryContent: string | null;
+} {
+  let memoryContent: string | null = null;
+  let match: RegExpExecArray | null;
+
+  // Reset regex state
+  MEMORY_UPDATE_RE.lastIndex = 0;
+
+  while ((match = MEMORY_UPDATE_RE.exec(text)) !== null) {
+    // Use the last match (complete replacement semantics)
+    memoryContent = match[1].trim();
+  }
+
+  // Remove all <memory_update> blocks from the text
+  const cleanedText = text
+    .replace(MEMORY_UPDATE_RE, "")
+    .replace(/\n{3,}/g, "\n\n") // collapse excessive blank lines left by removal
+    .trim();
+
+  return { cleanedText, memoryContent };
+}

package/src/memory.ts

@@ -0,0 +1,142 @@
+/**
+ * Working Memory & Room State — persistent local storage for agent memory.
+ *
+ * Storage layout (under OpenClaw agent workspace):
+ *   {workspace}/memory/botcord/working-memory.json
+ *   {workspace}/memory/botcord/rooms/{roomId}.json
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { getBotCordRuntime, getConfig } from "./runtime.js";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export type WorkingMemory = {
+  version: 1;
+  content: string;
+  updatedAt: string;
+  sourceSessionKey?: string;
+};
+
+export type RoomState = {
+  version: 1;
+  checkpointMsgId?: string;
+  lastSeenAt?: string;
+  mentionBacklog?: number;
+  openTopicHints?: Array<{ topicId: string; title?: string; status?: string }>;
+  note?: string;
+  updatedAt: string;
+};
+
+// ── Workspace resolution ───────────────────────────────────────────
+
+const MEMORY_SUBDIR = "memory/botcord";
+
+/**
+ * Resolve the base memory directory.
+ *
+ * Tries OpenClaw's workspace API first; falls back to ~/.botcord/memory.
+ */
+export function resolveMemoryDir(): string {
+  try {
+    const runtime = getBotCordRuntime();
+    const cfg = getConfig();
+    // OpenClaw workspace API (if available)
+    const workspaceDir =
+      (runtime as any).agent?.resolveAgentWorkspaceDir?.(cfg) ??
+      (runtime as any).agent?.ensureAgentWorkspace?.(cfg);
+    if (typeof workspaceDir === "string" && workspaceDir) {
+      return path.join(workspaceDir, MEMORY_SUBDIR);
+    }
+  } catch {
+    // runtime not initialized or API unavailable — fall through
+  }
+  return path.join(os.homedir(), ".botcord", "memory");
+}
+
+// ── Atomic file helpers ────────────────────────────────────────────
+
+function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+function readJsonFile<T>(filePath: string): T | null {
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomic write: write to a unique .tmp file, then rename over the target.
+ * Uses PID + timestamp suffix to avoid collisions from concurrent writers.
+ * Prevents half-written files on crash.
+ */
+function writeJsonFileAtomic(filePath: string, data: unknown): void {
+  const dir = path.dirname(filePath);
+  ensureDir(dir);
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+  renameSync(tmp, filePath);
+}
+
+// ── Working Memory ─────────────────────────────────────────────────
+
+function workingMemoryPath(memDir?: string): string {
+  return path.join(memDir ?? resolveMemoryDir(), "working-memory.json");
+}
+
+export function readWorkingMemory(memDir?: string): WorkingMemory | null {
+  return readJsonFile<WorkingMemory>(workingMemoryPath(memDir));
+}
+
+export function writeWorkingMemory(
+  data: WorkingMemory,
+  memDir?: string,
+): void {
+  writeJsonFileAtomic(workingMemoryPath(memDir), data);
+}
+
+// ── Room State ─────────────────────────────────────────────────────
+
+function roomStatePath(roomId: string, memDir?: string): string {
+  return path.join(memDir ?? resolveMemoryDir(), "rooms", `${roomId}.json`);
+}
+
+export function readRoomState(
+  roomId: string,
+  memDir?: string,
+): RoomState | null {
+  return readJsonFile<RoomState>(roomStatePath(roomId, memDir));
+}
+
+export function writeRoomState(
+  roomId: string,
+  data: RoomState,
+  memDir?: string,
+): void {
+  writeJsonFileAtomic(roomStatePath(roomId, memDir), data);
+}
+
+/**
+ * Merge partial updates into an existing room state (or create new).
+ * Returns the merged state.
+ */
+export function updateRoomState(
+  roomId: string,
+  updates: Partial<Omit<RoomState, "version">>,
+  memDir?: string,
+): RoomState {
+  const existing = readRoomState(roomId, memDir);
+  const merged: RoomState = {
+    version: 1,
+    ...existing,
+    ...updates,
+    updatedAt: new Date().toISOString(),
+  };
+  writeRoomState(roomId, merged, memDir);
+  return merged;
+}

package/src/owner-chat-stream.ts

@@ -0,0 +1,20 @@
+/**
+ * Tracks active owner-chat streaming sessions.
+ *
+ * When the plugin processes an owner-chat message, a stream entry is created
+ * so that the after_tool_call hook can stream execution blocks back to Hub.
+ */
+import type { BotCordClient } from "./client.js";
+
+export interface OwnerChatStream {
+  traceId: string;
+  client: BotCordClient;
+  seq: number;
+}
+
+/**
+ * Map of OpenClaw session key -> active stream.
+ * Entries are added when handleDashboardUserChat starts processing and
+ * removed when dispatch completes.
+ */
+export const activeOwnerChatStreams = new Map<string, OwnerChatStream>();

package/src/poller.ts

@@ -3,7 +3,7 @@
  * Used when websocket delivery is unavailable.
  */
 import { BotCordClient } from "./client.js";
-import { handleInboxMessage } from "./inbound.js";
+import { handleInboxMessageBatch } from "./inbound.js";
 import { displayPrefix } from "./config.js";
 
 interface PollerOptions {
@@ -29,16 +29,7 @@ export function startPoller(opts: PollerOptions): { stop: () => void } {
     try {
       const resp = await client.pollInbox({ limit: 20, ack: false });
       const messages = resp.messages || [];
-      const ackedIds: string[] = [];
-
-      for (const msg of messages) {
-        try {
-          await handleInboxMessage(msg, accountId, cfg);
-          ackedIds.push(msg.hub_msg_id);
-        } catch (err: any) {
-          log?.error(`[${dp}] failed to dispatch message ${msg.hub_msg_id}: ${err.message}`);
-        }
-      }
+      const ackedIds = await handleInboxMessageBatch(messages, accountId, cfg);
 
       if (ackedIds.length > 0) {
         try {

package/src/room-context.ts

@@ -0,0 +1,269 @@
+/**
+ * Room context injection for cross-session awareness.
+ *
+ * Two layers:
+ * 1. Static layer (appendSystemContext) — room name, description, rule, members.
+ *    Cacheable by the provider prompt cache since it rarely changes.
+ * 2. Dynamic layer (prependContext) — cross-room activity digest listing
+ *    other active rooms so the agent is aware of parallel conversations.
+ */
+import { getBotCordRuntime, getConfig } from "./runtime.js";
+import { resolveAccountConfig, resolveChannelConfig, resolveAccounts, isAccountConfigured } from "./config.js";
+import { attachTokenPersistence } from "./credentials.js";
+import type { RoomInfo } from "./types.js";
+
+// ── Session ↔ Room mapping ──────────────────────────────────────
+
+export type SessionRoomEntry = {
+  roomId: string;
+  roomName?: string;
+  accountId: string;
+  lastActivityAt: number;
+};
+
+/** sessionKey → room info populated when inbound messages arrive. */
+const sessionRoomMap = new Map<string, SessionRoomEntry>();
+
+export function registerSessionRoom(
+  sessionKey: string,
+  entry: SessionRoomEntry,
+): void {
+  sessionRoomMap.set(sessionKey, entry);
+}
+
+export function getSessionRoom(sessionKey: string): SessionRoomEntry | undefined {
+  return sessionRoomMap.get(sessionKey);
+}
+
+export function clearSessionRoom(sessionKey: string): void {
+  sessionRoomMap.delete(sessionKey);
+}
+
+export function getAllSessionRooms(): ReadonlyMap<string, SessionRoomEntry> {
+  return sessionRoomMap;
+}
+
+// ── Room info cache ─────────────────────────────────────────────
+
+type CachedRoomInfo = {
+  room: RoomInfo;
+  members: { agent_id: string; display_name?: string; role?: string }[];
+  fetchedAt: number;
+};
+
+const roomInfoCache = new Map<string, CachedRoomInfo>();
+const ROOM_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+async function fetchRoomInfoCached(
+  roomId: string,
+  accountId: string,
+): Promise<CachedRoomInfo | null> {
+  // Key by accountId:roomId so multi-account setups don't cross-pollinate
+  const cacheKey = `${accountId}:${roomId}`;
+  const existing = roomInfoCache.get(cacheKey);
+  if (existing && Date.now() - existing.fetchedAt < ROOM_CACHE_TTL_MS) {
+    return existing;
+  }
+
+  try {
+    const cfg = getConfig();
+    if (!cfg) return existing ?? null;
+
+    const acct = resolveAccountConfig(cfg, accountId);
+    if (!acct || !isAccountConfigured(acct)) return existing ?? null;
+
+    const { BotCordClient } = await import("./client.js");
+    const client = new BotCordClient(acct);
+    attachTokenPersistence(client, acct);
+
+    const [room, members] = await Promise.all([
+      client.getRoomInfo(roomId),
+      client.getRoomMembers(roomId),
+    ]);
+
+    const entry: CachedRoomInfo = {
+      room,
+      members: members.map((m: any) => ({
+        agent_id: m.agent_id,
+        display_name: m.display_name,
+        role: m.role,
+      })),
+      fetchedAt: Date.now(),
+    };
+    roomInfoCache.set(cacheKey, entry);
+    return entry;
+  } catch (err: any) {
+    console.warn(`[botcord] room-context: failed to fetch room ${roomId}:`, err?.message ?? err);
+    return existing ?? null;
+  }
+}
+
+// ── Static context builder ──────────────────────────────────────
+
+/**
+ * Build cacheable system context for the current room session.
+ * Returns null if the session is not a room session.
+ */
+export async function buildRoomStaticContext(
+  sessionKey: string,
+): Promise<string | null> {
+  const entry = sessionRoomMap.get(sessionKey);
+  if (!entry?.roomId) return null;
+
+  // Skip DM sessions — no room-level static context needed
+  if (entry.roomId.startsWith("rm_dm_")) return null;
+
+  const cached = await fetchRoomInfoCached(entry.roomId, entry.accountId);
+  if (!cached) return null;
+
+  const { room, members } = cached;
+  const lines: string[] = [
+    `[BotCord Room Context]`,
+    `Room: ${room.name} (${room.room_id})`,
+  ];
+  if (room.description) {
+    lines.push(`Description: ${room.description}`);
+  }
+  if (room.rule) {
+    lines.push(`Rule: ${room.rule}`);
+  }
+  lines.push(`Visibility: ${room.visibility}, Join: ${room.join_policy}`);
+
+  const memberList = members
+    .map((m) => {
+      const name = m.display_name || m.agent_id;
+      return m.role && m.role !== "member" ? `${name} (${m.role})` : name;
+    })
+    .join(", ");
+  if (memberList) {
+    lines.push(`Members (${members.length}): ${memberList}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── Cross-room activity digest ──────────────────────────────────
+
+/**
+ * Build a brief digest of other active BotCord rooms/sessions so the
+ * agent is aware of parallel conversations happening elsewhere.
+ *
+ * Reads the last few messages from each other session via
+ * `runtime.subagent.getSessionMessages()`.
+ */
+export async function buildCrossRoomDigest(
+  currentSessionKey: string,
+): Promise<string | null> {
+  if (sessionRoomMap.size <= 1) return null;
+
+  const runtime = getBotCordRuntime();
+  const currentEntry = sessionRoomMap.get(currentSessionKey);
+  const currentAccountId = currentEntry?.accountId;
+  const otherSessions: { key: string; entry: SessionRoomEntry }[] = [];
+
+  for (const [key, entry] of sessionRoomMap) {
+    if (key === currentSessionKey) continue;
+    // Only include sessions belonging to the same BotCord account
+    if (entry.accountId !== currentAccountId) continue;
+    // Only include sessions with recent activity (last 2 hours)
+    if (Date.now() - entry.lastActivityAt > 2 * 60 * 60 * 1000) continue;
+    otherSessions.push({ key, entry });
+  }
+
+  if (otherSessions.length === 0) return null;
+
+  // Sort by most recent activity first
+  otherSessions.sort((a, b) => b.entry.lastActivityAt - a.entry.lastActivityAt);
+
+  // Limit to 5 most active sessions to avoid excessive token usage
+  const toDigest = otherSessions.slice(0, 5);
+  // Count sessions for this account only (including current)
+  const accountSessionCount = otherSessions.length + 1;
+  const digestParts: string[] = [
+    `[BotCord Cross-Room Awareness] You are active in ${accountSessionCount} BotCord sessions. Here is recent activity from other rooms:`,
+  ];
+
+  for (const { key, entry } of toDigest) {
+    const roomLabel = entry.roomName || entry.roomId;
+    const isDm = entry.roomId.startsWith("rm_dm_");
+    const typeLabel = isDm ? "DM" : "Room";
+
+    try {
+      const { messages } = await runtime.subagent.getSessionMessages({
+        sessionKey: key,
+        limit: 3,
+      });
+
+      if (messages.length === 0) {
+        digestParts.push(`\n- ${typeLabel}: ${roomLabel} — no recent messages`);
+        continue;
+      }
+
+      // Extract a brief summary from the last messages
+      const previews = messages
+        .slice(-3)
+        .map((msg: any) => {
+          const role = msg.role || "unknown";
+          const text = (msg.content || msg.text || "").slice(0, 120);
+          return `  [${role}] ${text}${text.length >= 120 ? "…" : ""}`;
+        })
+        .join("\n");
+
+      const ago = formatTimeAgo(entry.lastActivityAt);
+      digestParts.push(`\n- ${typeLabel}: ${roomLabel} (${ago}):\n${previews}`);
+    } catch {
+      digestParts.push(`\n- ${typeLabel}: ${roomLabel} — unable to read messages`);
+    }
+  }
+
+  return digestParts.join("");
+}
+
+function formatTimeAgo(timestamp: number): string {
+  const diffMs = Date.now() - timestamp;
+  const diffMin = Math.floor(diffMs / 60_000);
+  if (diffMin < 1) return "just now";
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMin / 60);
+  return `${diffHr}h ago`;
+}
+
+// ── Combined hook handler ───────────────────────────────────────
+
+/**
+ * before_prompt_build handler that injects room context.
+ * Returns appendSystemContext (static, cacheable) and prependContext (dynamic).
+ */
+export async function buildRoomContextHookResult(
+  sessionKey: string | undefined,
+): Promise<{
+  appendSystemContext?: string;
+  prependContext?: string;
+} | null> {
+  if (!sessionKey) return null;
+
+  // Don't inject room context for the owner chat session
+  if (sessionKey === "botcord:owner:main") return null;
+
+  // Only inject for sessions we know are BotCord sessions (registered via
+  // inbound dispatch).  This handles both native "botcord:..." keys and
+  // custom-routed keys that don't carry the prefix.
+  if (!sessionRoomMap.has(sessionKey)) return null;
+
+  const result: { appendSystemContext?: string; prependContext?: string } = {};
+
+  // Layer 1: Static room context (cacheable)
+  const staticCtx = await buildRoomStaticContext(sessionKey);
+  if (staticCtx) {
+    result.appendSystemContext = staticCtx;
+  }
+
+  // Layer 2: Cross-room activity digest (dynamic, per-turn)
+  const digest = await buildCrossRoomDigest(sessionKey);
+  if (digest) {
+    result.prependContext = digest;
+  }
+
+  if (!result.appendSystemContext && !result.prependContext) return null;
+  return result;
+}