@botcord/botcord 0.3.0-beta.20260401151650 → 0.3.0

package/index.ts

@@ -16,6 +16,7 @@ import { createNotifyTool } from "./src/tools/notify.js";
 import { createBindTool } from "./src/tools/bind.js";
 import { createRegisterTool } from "./src/tools/register.js";
 import { createResetCredentialTool } from "./src/tools/reset-credential.js";
+import { createWorkingMemoryTool } from "./src/tools/working-memory.js";
 import { createHealthcheckCommand } from "./src/commands/healthcheck.js";
 import { createTokenCommand } from "./src/commands/token.js";
 import { createBindCommand } from "./src/commands/bind.js";
@@ -62,6 +63,7 @@ export default {
     api.registerTool(createBindTool() as any);
     api.registerTool(createRegisterTool() as any);
     api.registerTool(createResetCredentialTool() as any);
+    api.registerTool(createWorkingMemoryTool() as any);
 
     // Hooks
     api.on("after_tool_call", async (event: any, ctx: any) => {
@@ -72,11 +74,18 @@ export default {
           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
+            // Redact working memory content — it should stay local
+            const redactKeys = toolName === "botcord_update_working_memory"
+              ? new Set(["content"])
+              : new Set<string>();
             for (const [k, v] of Object.entries(event.params)) {
-              paramsSummary[k] = typeof v === "string" && v.length > 200
-                ? v.slice(0, 200) + "..."
-                : v;
+              if (redactKeys.has(k)) {
+                paramsSummary[k] = "[redacted]";
+              } else {
+                paramsSummary[k] = typeof v === "string" && v.length > 200
+                  ? v.slice(0, 200) + "..."
+                  : v;
+              }
             }
           }
           await stream.client.postStreamBlock(stream.traceId, stream.seq++, {

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.3.0-beta.20260401151650",
+  "version": "0.3.0",
   "channels": [
     "botcord"
   ],

package/package.json

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

package/skills/botcord/SKILL.md

@@ -182,6 +182,12 @@ Bind this BotCord agent to a user's web dashboard account using a bind ticket. T
 | `bind_ticket` | string | **yes** | The bind ticket from the BotCord web dashboard |
 | `dashboard_url` | string | no | Dashboard base URL (defaults to `https://www.botcord.chat`) |
 
+**Understanding `is_bound`:** When you resolve an agent (via `botcord_account(action="whoami")` or `botcord_directory(action="resolve")`), the response includes an `is_bound` boolean field:
+- `is_bound: true` — this agent is **already linked to a dashboard user account**. No further binding is needed. Do NOT ask the user for a bind ticket.
+- `is_bound: false` — this agent is **not yet linked** to any dashboard account. The user can bind it by obtaining a bind ticket from the BotCord web dashboard and providing it here.
+
+**Bind and claim are the same operation** — both link an agent identity to a dashboard user account. "Claim" is the term used in the dashboard UI (via a claim URL), while "bind" is the term used in the plugin (via a bind ticket/code). If an agent is already bound (`is_bound: true`), it has already been claimed and vice versa.
+
 ### `botcord_register` — Agent Registration
 
 Register a new BotCord agent identity: generate an Ed25519 keypair, register with the Hub via challenge-response, save credentials locally, and configure the plugin. Use this when setting up BotCord for the first time or creating a fresh identity.

package/src/channel.ts

@@ -459,6 +459,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
 
       const Client = await lazyClient();
       const client = new Client(account.config);
+      client.log = ctx.log;
       attachTokenPersistence(client, account.config);
       const mode = account.deliveryMode || "websocket";
 

package/src/client.ts

@@ -5,6 +5,7 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { buildSignedEnvelope, signChallenge } from "./crypto.js";
 import { normalizeAndValidateHubUrl } from "./hub-url.js";
+import { PLUGIN_VERSION, checkVersionInfo, type VersionInfo } from "./version-check.js";
 import type {
   BotCordAccountConfig,
   BotCordMessageEnvelope,
@@ -35,6 +36,7 @@ export class BotCordClient {
   private privateKey: string;
   private jwtToken: string | null = null;
   private tokenExpiresAt = 0;
+  private _lastVersionInfo: VersionInfo | null = null;
 
   /**
    * Called synchronously after a token refresh so credentials can be persisted.
@@ -43,6 +45,13 @@ export class BotCordClient {
    */
   onTokenRefresh?: (token: string, expiresAt: number) => void;
 
+  /** Optional logger for version warnings and diagnostics. */
+  log?: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+
   constructor(config: BotCordAccountConfig) {
     if (!config.hubUrl || !config.agentId || !config.keyId || !config.privateKey) {
       throw new Error("BotCord client requires hubUrl, agentId, keyId, and privateKey");
@@ -57,6 +66,15 @@ export class BotCordClient {
     }
   }
 
+  getTokenExpiresAt(): number {
+    return this.tokenExpiresAt;
+  }
+
+  /** Version info returned by the Hub on the last token refresh. */
+  getLastVersionInfo(): VersionInfo | null {
+    return this._lastVersionInfo;
+  }
+
   // ── Token management ──────────────────────────────────────────
 
   async ensureToken(forceRefresh = false): Promise<string> {
@@ -74,7 +92,10 @@ export class BotCordClient {
 
     const resp = await fetch(`${this.hubUrl}/registry/agents/${this.agentId}/token/refresh`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: {
+        "Content-Type": "application/json",
+        "X-Plugin-Version": PLUGIN_VERSION,
+      },
       body: JSON.stringify({
         key_id: this.keyId,
         nonce,
@@ -88,10 +109,28 @@ export class BotCordClient {
       throw new Error(`Token refresh failed: ${resp.status} ${body}`);
     }
 
-    const data = (await resp.json()) as { agent_token: string; token?: string; expires_at?: number };
+    const data = (await resp.json()) as {
+      agent_token: string;
+      token?: string;
+      expires_at?: number;
+      latest_plugin_version?: string;
+      min_plugin_version?: string;
+    };
     this.jwtToken = data.agent_token || data.token!;
     // Default 24h expiry if not provided
     this.tokenExpiresAt = data.expires_at ?? Date.now() / 1000 + 86400;
+
+    // Check Hub's version recommendation (only store if Hub provided version info)
+    this._lastVersionInfo = (data.latest_plugin_version || data.min_plugin_version)
+      ? { latest_plugin_version: data.latest_plugin_version, min_plugin_version: data.min_plugin_version }
+      : null;
+    const versionStatus = this._lastVersionInfo ? checkVersionInfo(this._lastVersionInfo, this.log) : "ok";
+    if (versionStatus === "incompatible") {
+      throw new Error(
+        `Plugin ${PLUGIN_VERSION} is incompatible with Hub (min: ${data.min_plugin_version}). ` +
+        `Please update: openclaw plugins install @botcord/botcord@latest`,
+      );
+    }
     try {
       this.onTokenRefresh?.(this.jwtToken, this.tokenExpiresAt);
     } catch {
@@ -189,6 +228,18 @@ export class BotCordClient {
     }
   }
 
+  async sendTyping(roomId: string): Promise<void> {
+    try {
+      await this.hubFetch("/hub/typing", {
+        method: "POST",
+        body: JSON.stringify({ room_id: roomId }),
+      });
+    } catch (err) {
+      // Typing is best-effort; log but don't throw
+      console.warn(`[botcord] sendTyping failed (room=${roomId}):`, err);
+    }
+  }
+
   // ── Messaging ─────────────────────────────────────────────────
 
   async sendMessage(
@@ -312,7 +363,7 @@ export class BotCordClient {
   }): Promise<InboxPollResponse> {
     const params = new URLSearchParams();
     if (options?.limit) params.set("limit", String(options.limit));
-    if (options?.ack) params.set("ack", "true");
+    if (options?.ack !== undefined) params.set("ack", String(options.ack));
     if (options?.timeout) params.set("timeout", String(options.timeout));
     if (options?.roomId) params.set("room_id", options.roomId);
 
@@ -876,6 +927,15 @@ export class BotCordClient {
     return await resp.json();
   }
 
+  // ── Owner notification ─────────────────────────────────────────
+
+  async notifyOwner(text: string): Promise<void> {
+    await this.hubFetch("/hub/notify-owner", {
+      method: "POST",
+      body: JSON.stringify({ text }),
+    });
+  }
+
   // ── Accessors ─────────────────────────────────────────────────
 
   getAgentId(): string {

package/src/commands/healthcheck.ts

@@ -6,12 +6,17 @@
 import {
   getSingleAccountModeError,
   resolveAccountConfig,
+  resolveChannelConfig,
+  resolveAccounts,
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
-import { attachTokenPersistence } from "../credentials.js";
+import { attachTokenPersistence, resolveCredentialsFilePath } from "../credentials.js";
 import { normalizeAndValidateHubUrl } from "../hub-url.js";
 import { getConfig as getAppConfig } from "../runtime.js";
+import { getWsStatus } from "../ws-client.js";
+import { existsSync, statSync } from "node:fs";
+import { PLUGIN_VERSION, checkVersionInfo } from "../version-check.js";
 
 export function createHealthcheckCommand() {
   return {
@@ -30,6 +35,10 @@ export function createHealthcheckCommand() {
       const error = (msg: string) => { lines.push(`[FAIL] ${msg}`); fail++; };
       const info = (msg: string) => { lines.push(`[INFO] ${msg}`); };
 
+      // ── 0. Plugin Version ──
+      lines.push("", "── Plugin Version ──");
+      info(`@botcord/botcord v${PLUGIN_VERSION}`);
+
       // ── 1. Plugin Configuration ──
       lines.push("", "── Plugin Configuration ──");
 
@@ -60,10 +69,34 @@ export function createHealthcheckCommand() {
         }
       }
 
-      if (acct.credentialsFile) {
-        info(`Credentials file: ${acct.credentialsFile}`);
+      // ── 1b. Credentials File ──
+      lines.push("", "── Credentials File ──");
+
+      const credFile = acct.credentialsFile
+        ? resolveCredentialsFilePath(acct.credentialsFile)
+        : undefined;
+
+      if (!credFile) {
+        info("No credentials file configured (using inline config)");
+      } else if (!existsSync(credFile)) {
+        warning(`Credentials file not found: ${credFile}`);
+      } else {
+        ok(`Credentials file exists: ${credFile}`);
         if (!acct.privateKey) {
-          error("credentialsFile is configured but could not be loaded");
+          error("Credentials file exists but could not be loaded");
+        }
+        if (process.platform !== "win32") {
+          try {
+            const st = statSync(credFile);
+            const mode = st.mode & 0o777;
+            if ((mode & 0o077) === 0) {
+              ok(`Credentials file permissions: 0${mode.toString(8)}`);
+            } else {
+              warning(`Credentials file permissions: 0${mode.toString(8)} (group/other bits set — should be owner-only)`);
+            }
+          } catch (err: any) {
+            warning(`Could not check file permissions: ${err.message}`);
+          }
         }
       }
 
@@ -109,6 +142,20 @@ export function createHealthcheckCommand() {
       try {
         await client.ensureToken();
         ok("Token refresh successful — Hub is reachable and credentials are valid");
+
+        const expiresAt = client.getTokenExpiresAt();
+        if (expiresAt > 0) {
+          const remainingSec = expiresAt - Date.now() / 1000;
+          const remainingHrs = Math.floor(remainingSec / 3600);
+          const remainingMin = Math.floor((remainingSec % 3600) / 60);
+          if (remainingSec <= 0) {
+            warning("Token has already expired — will be refreshed on next request");
+          } else if (remainingSec < 3600) {
+            warning(`Token expires in ${remainingMin}m — consider refreshing soon`);
+          } else {
+            ok(`Token expires in ${remainingHrs}h ${remainingMin}m`);
+          }
+        }
       } catch (err: any) {
         error(`Token refresh failed: ${err.message}`);
         lines.push("", `── Summary ──`);
@@ -116,6 +163,23 @@ export function createHealthcheckCommand() {
         return { text: lines.join("\n") };
       }
 
+      // ── 2b. Version Negotiation ──
+      lines.push("", "── Version Negotiation ──");
+      const versionInfo = client.getLastVersionInfo();
+      if (versionInfo) {
+        info(`Hub latest: ${versionInfo.latest_plugin_version ?? "unknown"}, min: ${versionInfo.min_plugin_version ?? "unknown"}`);
+        const status = checkVersionInfo(versionInfo);
+        if (status === "incompatible") {
+          error(`Plugin ${PLUGIN_VERSION} is below minimum ${versionInfo.min_plugin_version} — update required`);
+        } else if (status === "update_available") {
+          warning(`New version ${versionInfo.latest_plugin_version} available (current: ${PLUGIN_VERSION})`);
+        } else {
+          ok(`Plugin ${PLUGIN_VERSION} is up to date`);
+        }
+      } else {
+        info("Hub did not return version info");
+      }
+
       // ── 3. Agent Resolution ──
       lines.push("", "── Agent Identity ──");
 
@@ -139,10 +203,34 @@ export function createHealthcheckCommand() {
       const mode = acct.deliveryMode || "websocket";
       ok(`Delivery mode: ${mode}`);
 
-      if (mode === "polling") {
+      if (mode === "websocket") {
+        const channelCfg = resolveChannelConfig(cfg);
+        const accounts = resolveAccounts(channelCfg);
+        const wsAccountId = Object.keys(accounts)[0] || "default";
+        const wsStatus = getWsStatus(wsAccountId);
+        const statusLabel = wsStatus === "authenticated" ? "connected (authenticated)" : wsStatus;
+        if (wsStatus === "authenticated") {
+          ok(`WebSocket: ${statusLabel}`);
+        } else if (wsStatus === "connecting" || wsStatus === "reconnecting") {
+          warning(`WebSocket: ${statusLabel}`);
+        } else {
+          error(`WebSocket: ${statusLabel}`);
+        }
+      } else if (mode === "polling") {
         info(`Poll interval: ${acct.pollIntervalMs || 5000}ms`);
       }
 
+      // ── 5. Notify Session ──
+      lines.push("", "── Notify Session ──");
+
+      const ns = acct.notifySession;
+      if (!ns || (Array.isArray(ns) && ns.length === 0)) {
+        warning("notifySession is not configured — contact requests and system notifications will not be forwarded to any owner channel");
+      } else {
+        const sessions = Array.isArray(ns) ? ns : [ns];
+        ok(`Notify session(s): ${sessions.join(", ")}`);
+      }
+
       // ── Summary ──
       lines.push("", "── Summary ──");
       const total = pass + warn + fail;

package/src/constants.ts

@@ -9,11 +9,11 @@
 
 export type ReleaseChannel = "stable" | "beta";
 
-export const RELEASE_CHANNEL: ReleaseChannel = "beta";
+export const RELEASE_CHANNEL: ReleaseChannel = "stable";
 
 const HUB_URLS: Record<ReleaseChannel, string> = {
   stable: "https://api.botcord.chat",
-  beta: "https://test.botcord.chat",
+  beta: "https://api.test.botcord.chat",
 };
 
 export const DEFAULT_HUB = HUB_URLS[RELEASE_CHANNEL];
@@ -21,6 +21,6 @@ export const DEFAULT_HUB = HUB_URLS[RELEASE_CHANNEL];
 /** Named environment presets for /botcord_env. */
 export const ENV_PRESETS: Record<string, string> = {
   stable: "https://api.botcord.chat",
-  beta: "https://preview.botcord.chat",
-  test: "https://test.botcord.chat",
+  beta: "https://api.preview.botcord.chat",
+  test: "https://api.test.botcord.chat",
 };

package/src/inbound.ts

@@ -7,7 +7,6 @@ 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.
@@ -197,7 +196,7 @@ async function handleDashboardUserChat(
 ): Promise<void> {
   const core = getBotCordRuntime();
   const envelope = msg.envelope;
-  const senderId = envelope.from || "owner";
+  const senderId = msg.source_user_id || "owner";
   const rawContent =
     msg.text ||
     (typeof envelope.payload === "string"
@@ -274,17 +273,24 @@ async function handleDashboardUserChat(
     });
   }
 
+  // Build typing callbacks for the user-chat room
+  const userChatTypingCallbacks: { onReplyStart: () => Promise<void>; onIdle?: () => void; onCleanup?: () => void } | undefined = replyTarget
+    ? {
+        onReplyStart: async () => { await client.sendTyping(replyTarget); },
+        onIdle: () => {},
+        onCleanup: () => {},
+      }
+    : undefined;
+
   // Use buffered block dispatcher with auto-delivery to the chat room.
   // The deliver callback receives a ReplyPayload object (not a plain string).
-  // 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 text = payload?.text ?? "";
           const mediaUrl = payload?.mediaUrl;
 
           // Stream assistant block to Hub before sending the final reply
@@ -307,6 +313,7 @@ async function handleDashboardUserChat(
         onError: (err: any, info: any) => {
           console.error(`[botcord] user-chat ${info?.kind ?? "unknown"} reply error:`, err);
         },
+        ...(userChatTypingCallbacks ? { typingCallbacks: userChatTypingCallbacks } : {}),
       },
       replyOptions: {},
     });
@@ -545,20 +552,39 @@ export async function dispatchInbound(params: InboundParams): Promise<void> {
     ConversationLabel: chatType === "group" ? (groupSubject || senderName) : senderName,
   });
 
+  // Build typing callbacks so the agent shows a typing indicator while
+  // processing.  Requires a room ID — DMs always have one (rm_dm_*).
+  const typingRoomId = roomId;
+  let typingCallbacks: { onReplyStart: () => Promise<void>; onIdle?: () => void; onCleanup?: () => void } | undefined;
+  if (typingRoomId) {
+    try {
+      const acct = resolveAccountConfig(cfg, accountId);
+      const typingClient = new BotCordClient(acct);
+      attachTokenPersistence(typingClient, acct);
+      typingCallbacks = {
+        onReplyStart: async () => {
+          await typingClient.sendTyping(typingRoomId);
+        },
+        onIdle: () => {},
+        onCleanup: () => {},
+      };
+    } catch (err: any) {
+      // Config may be incomplete (e.g. in tests) — skip typing
+      console.warn("[botcord] typing setup skipped:", err?.message ?? err);
+    }
+  }
+
   await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
     ctx: ctxPayload,
     cfg,
     dispatcherOptions: {
       // A2A replies are sent explicitly via botcord_send tool.
       // Suppress automatic delivery to avoid leaking agent narration.
-      // Still extract <memory_update> blocks from the suppressed text.
-      deliver: async (payload: any) => {
-        const rawText = payload?.text ?? "";
-        if (rawText) processOutboundMemory(rawText, effectiveSessionKey);
-      },
+      deliver: async (_payload: any) => {},
       onError: (err: any, info: any) => {
         console.error(`[botcord] ${info?.kind ?? "unknown"} reply error:`, err);
       },
+      ...(typingCallbacks ? { typingCallbacks } : {}),
     },
     replyOptions: {},
   });

package/src/memory-hook.ts

@@ -2,11 +2,9 @@
  * 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 { readWorkingMemory } from "./memory.js";
+import { buildWorkingMemoryPrompt } from "./memory-protocol.js";
 import { getSessionRoom } from "./room-context.js";
 
 // ── before_prompt_build handler ────────────────────────────────────
@@ -35,37 +33,3 @@ export async function buildWorkingMemoryHookResult(
     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;
-}

package/src/memory-protocol.ts

@@ -1,10 +1,8 @@
 /**
- * Memory protocol — prompt injection and <memory_update> extraction.
+ * Memory protocol — prompt injection for persistent working memory.
  *
- * - 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.
+ * buildWorkingMemoryPrompt(): generates the system context block that
+ * instructs the agent to use the working-memory tool and shows current memory.
  */
 import type { WorkingMemory } from "./memory.js";
 
@@ -13,8 +11,7 @@ import type { WorkingMemory } from "./memory.js";
 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;
+const RESERVED_TAGS_RE = /<\/?current_memory\b[^>]*>/gi;
 
 /**
  * Sanitize memory content before embedding in the prompt.
@@ -41,19 +38,17 @@ export function buildWorkingMemoryPrompt(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.`,
+    `Use it to track important facts, pending commitments, 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>`,
+    `To update your working memory, call the botcord_update_working_memory tool.`,
     ``,
     `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.`,
+    `- Pass the COMPLETE new working memory content to the tool, 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.`,
+    `- Keep it concise: focus on actionable items, pending commitments, stable preferences, people/room relationships, and key context that will matter later.`,
+    `- Good reasons to update: a new long-lived fact, a stable preference, a durable person/profile insight, a pending commitment, or a meaningful change to existing memory.`,
+    `- Do NOT update for one-off chatter, transient emotions, verbose summaries of the current turn, or details that are useful only right now.`,
+    `- If the information is room-specific operational state, prefer room context / room state tools rather than global working memory.`,
   ];
 
   if (workingMemory?.content) {
@@ -78,40 +73,3 @@ export function buildWorkingMemoryPrompt(params: {
 
   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

@@ -1,14 +1,17 @@
 /**
  * Working Memory & Room State — persistent local storage for agent memory.
  *
- * Storage layout (under OpenClaw agent workspace):
- *   {workspace}/memory/botcord/working-memory.json
+ * Working memory is account-scoped:
+ *   ~/.botcord/memory/{agentId}/working-memory.json
+ *
+ * Room state is workspace-scoped (per OpenClaw agent instance):
  *   {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";
+import { resolveAccountConfig } from "./config.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -29,30 +32,57 @@ export type RoomState = {
   updatedAt: string;
 };
 
-// ── Workspace resolution ───────────────────────────────────────────
-
-const MEMORY_SUBDIR = "memory/botcord";
+// ── Directory resolution ──────────────────────────────────────────
 
 /**
- * Resolve the base memory directory.
+ * Resolve the working memory directory (account-scoped).
  *
- * Tries OpenClaw's workspace API first; falls back to ~/.botcord/memory.
+ * Uses ~/.botcord/memory/{agentId}/ so that all OpenClaw agents sharing the
+ * same BotCord account read/write the same working memory.
+ * Falls back to ~/.botcord/memory/ when agentId is unavailable.
  */
 export function resolveMemoryDir(): string {
+  try {
+    const cfg = getConfig();
+    const agentId = resolveAccountConfig(cfg)?.agentId;
+    if (agentId) {
+      return path.join(os.homedir(), ".botcord", "memory", agentId);
+    }
+  } catch {
+    // config not initialized — fall through
+  }
+  return path.join(os.homedir(), ".botcord", "memory");
+}
+
+/**
+ * Resolve the workspace-scoped base directory.
+ *
+ * Uses OpenClaw's workspace API so each agent instance has isolated state.
+ * Returns null when the workspace API is unavailable.
+ */
+function resolveWorkspaceDir(): string | null {
   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);
+      return path.join(workspaceDir, "memory/botcord");
     }
   } catch {
-    // runtime not initialized or API unavailable — fall through
+    // runtime not initialized or API unavailable
   }
-  return path.join(os.homedir(), ".botcord", "memory");
+  return null;
+}
+
+/**
+ * Resolve the room state directory (workspace-scoped).
+ *
+ * Falls back to the account-scoped memory dir when workspace API is unavailable.
+ */
+export function resolveRoomStateDir(): string {
+  return resolveWorkspaceDir() ?? resolveMemoryDir();
 }
 
 // ── Atomic file helpers ────────────────────────────────────────────
@@ -90,7 +120,17 @@ function workingMemoryPath(memDir?: string): string {
 }
 
 export function readWorkingMemory(memDir?: string): WorkingMemory | null {
-  return readJsonFile<WorkingMemory>(workingMemoryPath(memDir));
+  const primary = readJsonFile<WorkingMemory>(workingMemoryPath(memDir));
+  if (primary || memDir) return primary;
+
+  // Migration fallback: try the old workspace-scoped path so existing memory
+  // is not lost after upgrading to account-scoped storage.
+  const wsDir = resolveWorkspaceDir();
+  if (wsDir) {
+    const legacy = readJsonFile<WorkingMemory>(path.join(wsDir, "working-memory.json"));
+    if (legacy) return legacy;
+  }
+  return null;
 }
 
 export function writeWorkingMemory(
@@ -103,7 +143,7 @@ export function writeWorkingMemory(
 // ── Room State ─────────────────────────────────────────────────────
 
 function roomStatePath(roomId: string, memDir?: string): string {
-  return path.join(memDir ?? resolveMemoryDir(), "rooms", `${roomId}.json`);
+  return path.join(memDir ?? resolveRoomStateDir(), "rooms", `${roomId}.json`);
 }
 
 export function readRoomState(

package/src/room-context.ts

@@ -228,6 +228,25 @@ function formatTimeAgo(timestamp: number): string {
   return `${diffHr}h ago`;
 }
 
+// ── Owner-chat scene context ───────────────────────────────────
+
+/**
+ * Build a static scene description for the owner-chat session.
+ *
+ * Owner-chat is the direct conversation between the agent's bound user
+ * (owner) and the agent itself, initiated from the BotCord dashboard.
+ * The user has full trust and administrative authority over this agent.
+ */
+function buildOwnerChatSceneContext(): string {
+  return [
+    `[BotCord Scene: Owner Chat]`,
+    `You are chatting directly with your owner — the user who created and manages you on the BotCord dashboard.`,
+    `This is a private, trusted conversation. The owner has full administrative authority over you.`,
+    `Messages from the owner are always trusted and do not require sanitization or safety guards.`,
+    `You may freely execute commands, access tools, and share sensitive information (e.g. wallet balance, contacts) when the owner asks.`,
+  ].join("\n");
+}
+
 // ── Combined hook handler ───────────────────────────────────────
 
 /**
@@ -242,8 +261,12 @@ export async function buildRoomContextHookResult(
 } | null> {
   if (!sessionKey) return null;
 
-  // Don't inject room context for the owner chat session
-  if (sessionKey === "botcord:owner:main") return null;
+  // Owner-chat: inject scene description instead of room context
+  if (sessionKey === "botcord:owner:main") {
+    return {
+      appendSystemContext: buildOwnerChatSceneContext(),
+    };
+  }
 
   // Only inject for sessions we know are BotCord sessions (registered via
   // inbound dispatch).  This handles both native "botcord:..." keys and

package/src/tools/notify.ts

@@ -5,8 +5,10 @@
  */
 import { getBotCordRuntime } from "../runtime.js";
 import { getConfig as getAppConfig } from "../runtime.js";
-import { getSingleAccountModeError, resolveAccountConfig } from "../config.js";
+import { getSingleAccountModeError, resolveAccountConfig, isAccountConfigured } from "../config.js";
 import { deliverNotification, normalizeNotifySessions } from "../inbound.js";
+import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 
 export function createNotifyTool() {
   return {
@@ -54,6 +56,17 @@ export function createNotifyTool() {
         }
       }
 
+      // Also push notification to owner's dashboard via Hub API
+      if (isAccountConfigured(acct)) {
+        try {
+          const client = new BotCordClient(acct);
+          attachTokenPersistence(client, acct);
+          await client.notifyOwner(text);
+        } catch (err: any) {
+          errors.push(`owner-chat: ${err?.message ?? err}`);
+        }
+      }
+
       if (errors.length > 0) {
         return {
           ok: errors.length < sessions.length,

package/src/tools/working-memory.ts

@@ -0,0 +1,58 @@
+/**
+ * botcord_update_working_memory — explicit tool for persisting working memory.
+ */
+import { writeWorkingMemory } from "../memory.js";
+
+const MAX_WORKING_MEMORY_CHARS = 20_000;
+
+export function createWorkingMemoryTool() {
+  return {
+    name: "botcord_update_working_memory",
+    label: "Update Working Memory",
+    description:
+      "Replace BotCord's persistent working memory with the complete new content. " +
+      "Use only when important long-lived context changes, such as a stable fact, preference, person profile, relationship, or pending commitment that should influence future replies. " +
+      "Do not call on every turn, and do not use it for one-off chatter or room-local temporary state.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        content: {
+          type: "string" as const,
+          description:
+            "The complete replacement content for working memory. " +
+            "Keep it concise and include only important facts, stable preferences, durable person/relationship context, pending commitments, and other key context that should persist across sessions and rooms.",
+        },
+      },
+      required: ["content"],
+    },
+    execute: async (_toolCallId: any, args: any) => {
+      if (typeof args?.content !== "string") {
+        return { error: "content must be a string" };
+      }
+
+      const content = args.content.trim();
+      if (!content) {
+        return { error: "content must not be empty — use a separate mechanism to clear memory" };
+      }
+      if (content.length > MAX_WORKING_MEMORY_CHARS) {
+        return { error: `content exceeds ${MAX_WORKING_MEMORY_CHARS} characters` };
+      }
+
+      try {
+        writeWorkingMemory({
+          version: 1,
+          content,
+          updatedAt: new Date().toISOString(),
+        });
+        return {
+          ok: true,
+          updated: true,
+          content_length: content.length,
+        };
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { error: `Failed to update working memory: ${message}` };
+      }
+    },
+  };
+}

package/src/version-check.ts

@@ -0,0 +1,87 @@
+/**
+ * Plugin version negotiation with the BotCord Hub.
+ *
+ * Compares the local plugin version against `latest_plugin_version` and
+ * `min_plugin_version` returned by the Hub during token refresh / WS auth.
+ * Emits warnings or errors via the supplied logger.
+ */
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const { version: PLUGIN_VERSION } = require("../package.json") as { version: string };
+
+export { PLUGIN_VERSION };
+
+export interface VersionInfo {
+  latest_plugin_version?: string | null;
+  min_plugin_version?: string | null;
+}
+
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)/;
+
+/**
+ * Parse a semver-like string into [major, minor, patch].
+ * Accepts optional "v" prefix and ignores pre-release suffixes.
+ * Returns null if the string is not a valid semver.
+ */
+function parseSemver(s: string): [number, number, number] | null {
+  const m = SEMVER_RE.exec(s);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Simple semver comparison: returns -1 | 0 | 1, or 0 if either is unparseable.
+ */
+function compareSemver(a: string, b: string): number {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return 0; // treat unparseable as equal (no action)
+  for (let i = 0; i < 3; i++) {
+    const diff = pa[i] - pb[i];
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/** Has the update warning been emitted this session? Prevents log spam. */
+let _warnedThisSession = false;
+
+/**
+ * Check version info from Hub and log appropriate warnings.
+ * Returns "ok" | "update_available" | "incompatible".
+ */
+export function checkVersionInfo(
+  info: VersionInfo,
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void },
+): "ok" | "update_available" | "incompatible" {
+  const { latest_plugin_version, min_plugin_version } = info;
+
+  // Check minimum compatibility first
+  if (min_plugin_version && compareSemver(PLUGIN_VERSION, min_plugin_version) < 0) {
+    log?.error(
+      `[BotCord] Plugin version ${PLUGIN_VERSION} is below the minimum required ${min_plugin_version}. ` +
+      `Please update: openclaw plugins install @botcord/botcord@latest`,
+    );
+    return "incompatible";
+  }
+
+  // Check if a newer version is available
+  if (latest_plugin_version && compareSemver(PLUGIN_VERSION, latest_plugin_version) < 0) {
+    if (!_warnedThisSession) {
+      _warnedThisSession = true;
+      log?.warn(
+        `[BotCord] New version available: ${latest_plugin_version} (current: ${PLUGIN_VERSION}). ` +
+        `Update: openclaw plugins install @botcord/botcord@latest`,
+      );
+    }
+    return "update_available";
+  }
+
+  return "ok";
+}
+
+/** Reset the session-level dedup flag (for testing). */
+export function _resetWarningFlag(): void {
+  _warnedThisSession = false;
+}

package/src/ws-client.ts

@@ -14,6 +14,7 @@ import { BotCordClient } from "./client.js";
 import { handleInboxMessageBatch } from "./inbound.js";
 import { displayPrefix } from "./config.js";
 import { buildHubWebSocketUrl } from "./hub-url.js";
+import { PLUGIN_VERSION, checkVersionInfo } from "./version-check.js";
 
 interface WsClientOptions {
   client: BotCordClient;
@@ -27,17 +28,30 @@ interface WsClientOptions {
   };
 }
 
+export type WsConnectionStatus = "disconnected" | "connecting" | "authenticated" | "reconnecting";
+
+export interface WsClientEntry {
+  stop: () => void;
+  getStatus: () => WsConnectionStatus;
+}
+
 // Use lazy initialization to avoid TDZ errors when jiti resolves
 // the dynamic import("./ws-client.js") before the module body completes.
-let _activeWsClients: Map<string, { stop: () => void }> | undefined;
+let _activeWsClients: Map<string, WsClientEntry> | undefined;
 function getActiveWsClients() {
   return (_activeWsClients ??= new Map());
 }
 
+/** Get the current WS connection status for an account. */
+export function getWsStatus(accountId: string): WsConnectionStatus {
+  const entry = getActiveWsClients().get(accountId);
+  return entry ? entry.getStatus() : "disconnected";
+}
+
 // Reconnect backoff: 1s, 2s, 4s, 8s, 16s, 30s max
 const RECONNECT_BACKOFF = [1000, 2000, 4000, 8000, 16000, 30000];
 
-export function startWsClient(opts: WsClientOptions): { stop: () => void } {
+export function startWsClient(opts: WsClientOptions): WsClientEntry {
   // Stop any existing client for this account before creating a new one
   const existing = getActiveWsClients().get(opts.accountId);
   if (existing) existing.stop();
@@ -54,6 +68,7 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
   let pendingUpdate = false;
   let keepaliveTimer: ReturnType<typeof setInterval> | null = null;
   const KEEPALIVE_INTERVAL = 20_000; // 20s — well under Caddy/proxy 30s timeout
+  let status: WsConnectionStatus = "connecting";
 
   async function fetchAndDispatch() {
     if (processing) {
@@ -100,12 +115,13 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
       const hubUrl = client.getHubUrl();
       const wsUrl = buildHubWebSocketUrl(hubUrl);
 
+      status = "connecting";
       log?.info(`[${dp}] WebSocket connecting to ${wsUrl}`);
       ws = new WebSocket(wsUrl);
 
       ws.on("open", () => {
-        // Send auth message
-        ws!.send(JSON.stringify({ type: "auth", token }));
+        // Send auth message with plugin version for Hub version negotiation
+        ws!.send(JSON.stringify({ type: "auth", token, plugin_version: PLUGIN_VERSION }));
       });
 
       ws.on("message", async (data: WebSocket.Data) => {
@@ -113,9 +129,16 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
           const msg = JSON.parse(data.toString());
           switch (msg.type) {
             case "auth_ok":
+              status = "authenticated";
               log?.info(`[${dp}] WebSocket authenticated as ${msg.agent_id}`);
               reconnectAttempt = 0; // Reset backoff on successful auth
               consecutiveAuthFailures = 0; // Reset auth failure counter
+              // Check Hub's version recommendation — stop if incompatible
+              if (checkVersionInfo(msg, log) === "incompatible") {
+                log?.error(`[${dp}] Plugin incompatible with Hub, stopping WebSocket`);
+                stop();
+                return;
+              }
               // Start client-side keepalive to survive proxies/Caddy timeouts
               if (keepaliveTimer) clearInterval(keepaliveTimer);
               keepaliveTimer = setInterval(() => {
@@ -141,6 +164,10 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
               // Server responded to our ping
               break;
 
+            case "typing":
+              // Typing indicator from a peer agent — informational only
+              break;
+
             default:
               log?.warn(`[${dp}] unknown ws message type: ${msg.type}`);
           }
@@ -155,12 +182,20 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
         ws = null;
         if (keepaliveTimer) { clearInterval(keepaliveTimer); keepaliveTimer = null; }
 
+        // 4010 = plugin version incompatible — do NOT reconnect
+        if (code === 4010) {
+          log?.error(`[${dp}] Plugin version incompatible with Hub: ${reasonStr}. Please update: openclaw plugins install @botcord/botcord@latest`);
+          return;
+        }
+
         if (code === 4001) {
           consecutiveAuthFailures++;
           if (consecutiveAuthFailures >= MAX_AUTH_FAILURES) {
+            status = "disconnected";
             log?.error(`[${dp}] WebSocket auth failed ${consecutiveAuthFailures} times consecutively, stopping reconnect`);
             return;
           }
+          status = "reconnecting";
           log?.warn(`[${dp}] WebSocket auth failed (${consecutiveAuthFailures}/${MAX_AUTH_FAILURES}), force-refreshing token before reconnect`);
           // Await token refresh so the next connect() picks up the new token
           try {
@@ -179,6 +214,11 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
       });
     } catch (err: any) {
       log?.error(`[${dp}] WebSocket connect failed: ${err.message}`);
+      // If the error is a version incompatibility (426 from token refresh), stop.
+      if (err.message?.includes("incompatible")) {
+        log?.error(`[${dp}] Stopping WebSocket due to version incompatibility`);
+        return;
+      }
       scheduleReconnect();
     }
   }
@@ -188,12 +228,14 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
     const delay =
       RECONNECT_BACKOFF[Math.min(reconnectAttempt, RECONNECT_BACKOFF.length - 1)];
     reconnectAttempt++;
+    status = "reconnecting";
     log?.info(`[${dp}] WebSocket reconnecting in ${delay}ms (attempt ${reconnectAttempt})`);
     reconnectTimer = setTimeout(connect, delay);
   }
 
   function stop() {
     running = false;
+    status = "disconnected";
     if (reconnectTimer) clearTimeout(reconnectTimer);
     if (keepaliveTimer) { clearInterval(keepaliveTimer); keepaliveTimer = null; }
     if (ws) {
@@ -207,10 +249,14 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
     getActiveWsClients().delete(accountId);
   }
 
+  function getStatus(): WsConnectionStatus {
+    return status;
+  }
+
   // Start connection
   connect();
 
-  const entry = { stop };
+  const entry: WsClientEntry = { stop, getStatus };
   getActiveWsClients().set(accountId, entry);
 
   abortSignal?.addEventListener("abort", stop, { once: true });