@botcord/botcord 0.2.1 → 0.2.2

package/index.ts

@@ -14,11 +14,13 @@ import { createSubscriptionTool } from "./src/tools/subscription.js";
 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 { createHealthcheckCommand } from "./src/commands/healthcheck.js";
 import { createTokenCommand } from "./src/commands/token.js";
 import { createBindCommand } from "./src/commands/bind.js";
 import { createEnvCommand } from "./src/commands/env.js";
 import { createRegisterCli } from "./src/commands/register.js";
+import { createResetCredentialCommand } from "./src/commands/reset-credential.js";
 import {
   buildBotCordLoopRiskPrompt,
   clearBotCordLoopRiskSession,
@@ -55,6 +57,7 @@ export default {
     api.registerTool(createNotifyTool() as any);
     api.registerTool(createBindTool() as any);
     api.registerTool(createRegisterTool() as any);
+    api.registerTool(createResetCredentialTool() as any);
 
     // Hooks
     api.on("after_tool_call", async (event: any, ctx: any) => {
@@ -93,6 +96,7 @@ export default {
     api.registerCommand(createHealthcheckCommand());
     api.registerCommand(createTokenCommand());
     api.registerCommand(createBindCommand());
+    api.registerCommand(createResetCredentialCommand());
     api.registerCommand(createEnvCommand());
 
     // CLI

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.1",
+  "version": "0.2.2",
   "channels": [
     "botcord"
   ],

package/package.json

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

package/skills/botcord/SKILL.md

@@ -420,7 +420,7 @@ BotCord channel config lives in `openclaw.json` under `channels.botcord`:
       "enabled": true,
       "credentialsFile": "~/.botcord/credentials/ag_xxxxxxxxxxxx.json",
       "deliveryMode": "websocket",   // "websocket" (recommended) or "polling"
-      "notifySession": "agent:pm:telegram:direct:7904063707"
+      "notifySession": "botcord:owner:main"
     }
   }
 }
@@ -428,7 +428,9 @@ BotCord channel config lives in `openclaw.json` under `channels.botcord`:
 
 ### `notifySession`
 
-When BotCord receives notification-type messages (contact requests, contact responses, contact removals), the plugin sends a push notification directly to the channel specified by this session key — **without triggering an agent turn**. This lets the owner see incoming events in real time on their preferred messaging app.
+When BotCord receives notification-type messages (contact requests, contact responses, contact removals), the plugin sends a push notification directly to the channel(s) specified by this session key — **without triggering an agent turn**. This lets the owner see incoming events in real time on their preferred messaging app.
+
+`notifySession` accepts a single string or an array of strings to notify multiple sessions simultaneously.
 
 **Format:** `agent:<agentName>:<channel>:<chatType>:<peerId>`
 

package/src/channel.ts

@@ -51,6 +51,7 @@ import type {
 // Heavy deps (client, poller, ws-client) are lazy-loaded so that setup-entry.ts
 // can import botCordPlugin without pulling in ws at module level.
 import { getBotCordRuntime } from "./runtime.js";
+import { attachTokenPersistence } from "./credentials.js";
 const lazyClient = () => import("./client.js").then((m) => m.BotCordClient);
 const lazyPoller = () => import("./poller.js");
 const lazyWsClient = () => import("./ws-client.js");
@@ -148,8 +149,11 @@ const botCordConfigSchema = {
       items: { type: "string" as const },
     },
     notifySession: {
-      type: "string" as const,
-      description: "Session key to notify when inbound messages arrive (e.g. agent:main:main)",
+      oneOf: [
+        { type: "string" as const },
+        { type: "array" as const, items: { type: "string" as const } },
+      ],
+      description: "Session key(s) to notify when inbound messages arrive (e.g. botcord:owner:main)",
     },
     accounts: {
       type: "object" as const,
@@ -325,6 +329,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       try {
         const Client = await lazyClient();
         const client = new Client(account.config);
+        attachTokenPersistence(client, account.config);
         const info = await client.resolve(account.agentId);
         return { kind: "user", id: info.agent_id, name: info.display_name || info.agent_id };
       } catch {
@@ -337,6 +342,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       try {
         const Client = await lazyClient();
         const client = new Client(account.config);
+        attachTokenPersistence(client, account.config);
         const contacts = await client.listContacts();
         const q = query?.trim().toLowerCase() ?? "";
         return contacts
@@ -362,6 +368,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       try {
         const Client = await lazyClient();
         const client = new Client(account.config);
+        attachTokenPersistence(client, account.config);
         const rooms = await client.listMyRooms();
         const q = query?.trim().toLowerCase() ?? "";
         return rooms
@@ -382,6 +389,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       const account = resolveBotCordAccount({ cfg: cfg as CoreConfig, accountId: accountId ?? undefined });
       const Client = await lazyClient();
       const client = new Client(account.config);
+      attachTokenPersistence(client, account.config);
       const result = await client.sendMessage(to, text);
       return {
         channel: "botcord",
@@ -393,6 +401,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
       const account = resolveBotCordAccount({ cfg: cfg as CoreConfig, accountId: accountId ?? undefined });
       const Client = await lazyClient();
       const client = new Client(account.config);
+      attachTokenPersistence(client, account.config);
       const attachments: MessageAttachment[] = [];
       if (mediaUrl) {
         const filename = mediaUrl.split("/").pop() || "attachment";
@@ -441,6 +450,7 @@ export const botCordPlugin: ChannelPlugin<ResolvedBotCordAccount> = {
 
       const Client = await lazyClient();
       const client = new Client(account.config);
+      attachTokenPersistence(client, account.config);
       const mode = account.deliveryMode || "websocket";
 
       if (mode === "websocket") {

package/src/client.ts

@@ -36,6 +36,13 @@ export class BotCordClient {
   private jwtToken: string | null = null;
   private tokenExpiresAt = 0;
 
+  /**
+   * Called synchronously after a token refresh so credentials can be persisted.
+   * Must be a synchronous function — async persistence should be dispatched
+   * internally (e.g. fire-and-forget) by the callback itself.
+   */
+  onTokenRefresh?: (token: string, expiresAt: number) => void;
+
   constructor(config: BotCordAccountConfig) {
     if (!config.hubUrl || !config.agentId || !config.keyId || !config.privateKey) {
       throw new Error("BotCord client requires hubUrl, agentId, keyId, and privateKey");
@@ -44,12 +51,16 @@ export class BotCordClient {
     this.agentId = config.agentId;
     this.keyId = config.keyId;
     this.privateKey = config.privateKey;
+    if (config.token) {
+      this.jwtToken = config.token;
+      this.tokenExpiresAt = config.tokenExpiresAt ?? 0;
+    }
   }
 
   // ── Token management ──────────────────────────────────────────
 
-  async ensureToken(): Promise<string> {
-    if (this.jwtToken && Date.now() / 1000 < this.tokenExpiresAt - 60) {
+  async ensureToken(forceRefresh = false): Promise<string> {
+    if (!forceRefresh && this.jwtToken && Date.now() / 1000 < this.tokenExpiresAt - 60) {
       return this.jwtToken;
     }
     return this.refreshToken();
@@ -81,13 +92,18 @@ export class BotCordClient {
     this.jwtToken = data.agent_token || data.token!;
     // Default 24h expiry if not provided
     this.tokenExpiresAt = data.expires_at ?? Date.now() / 1000 + 86400;
+    try {
+      this.onTokenRefresh?.(this.jwtToken, this.tokenExpiresAt);
+    } catch {
+      // Token persistence is best-effort — never block the request path
+    }
     return this.jwtToken;
   }
 
   // ── Authenticated fetch with rate-limit retry ─────────────────
 
   private async hubFetch(path: string, init: RequestInit = {}): Promise<Response> {
-    const token = await this.ensureToken();
+    let token = await this.ensureToken();
 
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       const headers: Record<string, string> = {
@@ -107,9 +123,9 @@ export class BotCordClient {
 
       if (resp.ok) return resp;
 
-      // Token expired — refresh and retry
+      // Token expired — refresh and retry with the new token
       if (resp.status === 401 && attempt === 0) {
-        await this.refreshToken();
+        token = await this.refreshToken();
         continue;
       }
 
@@ -286,6 +302,14 @@ export class BotCordClient {
     return (await resp.json()) as InboxPollResponse;
   }
 
+  async ackMessages(messageIds: string[]): Promise<void> {
+    if (messageIds.length === 0) return;
+    await this.hubFetch("/hub/inbox/ack", {
+      method: "POST",
+      body: JSON.stringify({ message_ids: messageIds }),
+    });
+  }
+
   async getHistory(options?: {
     peer?: string;
     roomId?: string;

package/src/commands/healthcheck.ts

@@ -9,6 +9,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { normalizeAndValidateHubUrl } from "../hub-url.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
@@ -97,6 +98,7 @@ export function createHealthcheckCommand() {
       let client: BotCordClient;
       try {
         client = new BotCordClient(acct);
+        attachTokenPersistence(client, acct);
       } catch (err: any) {
         error(err.message);
         lines.push("", `── Summary ──`);

package/src/commands/register.ts

@@ -95,7 +95,7 @@ function buildNextConfig(
             : "websocket",
         notifySession:
           currentBotcord.notifySession ||
-          "agent:main:main",
+          "botcord:owner:main",
       },
     },
     session: {

package/src/commands/reset-credential.ts

@@ -0,0 +1,42 @@
+/**
+ * /botcord_reset_credential — regenerate local credentials for an existing agent.
+ */
+import { getConfig as getAppConfig } from "../runtime.js";
+import { resetCredential } from "../reset-credential.js";
+
+export function createResetCredentialCommand() {
+  return {
+    name: "botcord_reset_credential",
+    description:
+      "Reset BotCord credentials for an existing agent using a one-time reset code or reset ticket.",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const rawArgs = String(ctx.args || "").trim();
+      const parts = rawArgs.split(/\s+/).filter(Boolean);
+      if (parts.length < 2) {
+        return { text: "[FAIL] Usage: /botcord_reset_credential <agent_id> <reset_code_or_ticket> [hub_url]" };
+      }
+
+      const [agentId, resetCodeOrTicket, hubUrl] = parts;
+      const cfg = getAppConfig();
+      if (!cfg) return { text: "[FAIL] No OpenClaw configuration available" };
+
+      try {
+        const result = await resetCredential({
+          config: cfg,
+          agentId,
+          resetCodeOrTicket,
+          hubUrl,
+        });
+        return {
+          text:
+            `[OK] Reset credentials for ${result.displayName} (${result.agentId}). ` +
+            `Saved to ${result.credentialsFile}. Restart OpenClaw to activate.`,
+        };
+      } catch (err: any) {
+        return { text: `[FAIL] ${err.message}` };
+      }
+    },
+  };
+}

package/src/commands/token.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createTokenCommand() {
@@ -32,6 +33,7 @@ export function createTokenCommand() {
 
       try {
         const client = new BotCordClient(acct);
+        attachTokenPersistence(client, acct);
         const token = await client.ensureToken();
         return { text: token };
       } catch (err: any) {

package/src/credentials.ts

@@ -1,9 +1,10 @@
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { derivePublicKey } from "./crypto.js";
 import { normalizeAndValidateHubUrl } from "./hub-url.js";
 import type { BotCordAccountConfig } from "./types.js";
+import type { BotCordClient as BotCordClientType } from "./client.js";
 
 export interface StoredBotCordCredentials {
   version: 1;
@@ -14,6 +15,8 @@ export interface StoredBotCordCredentials {
   publicKey: string;
   displayName?: string;
   savedAt: string;
+  token?: string;
+  tokenExpiresAt?: number;
 }
 
 function normalizeCredentialValue(raw: any, keys: string[]): string | undefined {
@@ -57,6 +60,12 @@ export function loadStoredCredentials(credentialsFile: string): StoredBotCordCre
   const publicKey = normalizeCredentialValue(raw, ["publicKey", "public_key"]);
   const displayName = normalizeCredentialValue(raw, ["displayName", "display_name"]);
   const savedAt = normalizeCredentialValue(raw, ["savedAt", "saved_at"]);
+  const token = normalizeCredentialValue(raw, ["token"]);
+  const tokenExpiresAt = typeof raw.tokenExpiresAt === "number"
+    ? raw.tokenExpiresAt
+    : typeof raw.token_expires_at === "number"
+      ? raw.token_expires_at
+      : undefined;
 
   if (!hubUrl) throw new Error(`BotCord credentials file "${resolved}" is missing hubUrl`);
   if (!agentId) throw new Error(`BotCord credentials file "${resolved}" is missing agentId`);
@@ -86,6 +95,8 @@ export function loadStoredCredentials(credentialsFile: string): StoredBotCordCre
     publicKey: publicKey || derivedPublicKey,
     displayName,
     savedAt: savedAt || new Date().toISOString(),
+    token,
+    tokenExpiresAt,
   };
 }
 
@@ -100,6 +111,8 @@ export function readCredentialFileData(credentialsFile?: string): Partial<BotCor
       keyId: raw.keyId,
       privateKey: raw.privateKey,
       publicKey: raw.publicKey,
+      token: raw.token,
+      tokenExpiresAt: raw.tokenExpiresAt,
     };
   } catch {
     return {};
@@ -123,3 +136,46 @@ export function writeCredentialsFile(
   chmodSync(resolved, 0o600);
   return resolved;
 }
+
+/**
+ * Atomically update only the token fields in an existing credentials file.
+ * Reads current file, merges new token/expiresAt, writes back.
+ * Returns false if the file does not exist or the write fails.
+ */
+export function updateCredentialsToken(
+  credentialsFile: string,
+  token: string,
+  tokenExpiresAt: number,
+): boolean {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  try {
+    if (!existsSync(resolved)) return false;
+    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+    raw.token = token;
+    raw.tokenExpiresAt = tokenExpiresAt;
+    writeFileSync(resolved, JSON.stringify(raw, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    chmodSync(resolved, 0o600);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Attach token persistence to a BotCordClient.
+ * If the account was loaded from a credentialsFile, refreshed tokens
+ * are automatically written back to that file.
+ */
+export function attachTokenPersistence(
+  client: BotCordClientType,
+  acct: BotCordAccountConfig,
+): void {
+  if (!acct.credentialsFile) return;
+  const credFile = acct.credentialsFile;
+  client.onTokenRefresh = (token, expiresAt) => {
+    updateCredentialsToken(credFile, token, expiresAt);
+  };
+}

package/src/inbound.ts

@@ -4,6 +4,7 @@
  */
 import { getBotCordRuntime } from "./runtime.js";
 import { resolveAccountConfig } from "./config.js";
+import { attachTokenPersistence } from "./credentials.js";
 import { buildSessionKey } from "./session-key.js";
 import { readFileSync } from "node:fs";
 
@@ -24,6 +25,12 @@ import { BotCordClient } from "./client.js";
 import { createBotCordReplyDispatcher } from "./reply-dispatcher.js";
 import type { InboxMessage, MessageType } from "./types.js";
 
+/** Normalize notifySession (string | string[] | undefined) to a flat array. */
+export function normalizeNotifySessions(ns?: string | string[]): string[] {
+  if (!ns) return [];
+  return Array.isArray(ns) ? ns : [ns];
+}
+
 // Envelope types that count as notifications rather than normal messages
 const NOTIFICATION_TYPES: ReadonlySet<string> = new Set([
   "contact_request",
@@ -128,7 +135,9 @@ async function handleDashboardUserChat(
   const content = rawContent;
 
   const replyTarget = msg.room_id || "";
-  const sessionKey = buildSessionKey(msg.room_id, undefined, senderId);
+  // All dashboard user-chat sessions share a single fixed key so the
+  // conversation context persists across rooms.
+  const sessionKey = "botcord:owner:main";
 
   const route = core.channel.routing.resolveAgentRoute({
     cfg,
@@ -143,7 +152,7 @@ async function handleDashboardUserChat(
   const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
   const formattedBody = core.channel.reply.formatAgentEnvelope({
     channel: "BotCord",
-    from: "Owner",
+    from: msg.source_user_name || "Owner",
     timestamp: new Date(),
     envelope: envelopeOptions,
     body: content,
@@ -159,7 +168,7 @@ async function handleDashboardUserChat(
     SessionKey: route.sessionKey || sessionKey,
     AccountId: accountId,
     ChatType: "direct",
-    SenderName: "Owner",
+    SenderName: msg.source_user_name || "Owner",
     SenderId: senderId,
     Provider: "botcord" as const,
     Surface: "botcord" as const,
@@ -169,12 +178,13 @@ async function handleDashboardUserChat(
     CommandAuthorized: true,
     OriginatingChannel: "botcord" as const,
     OriginatingTo: to,
-    ConversationLabel: "Owner Chat",
+    ConversationLabel: msg.source_user_name ? `${msg.source_user_name} Chat` : "Owner Chat",
   });
 
   // Create the reply dispatcher that sends replies back to the chat room
   const acct = resolveAccountConfig(cfg, accountId);
   const client = new BotCordClient(acct);
+  attachTokenPersistence(client, acct);
   const replyDispatcher = createBotCordReplyDispatcher({
     client,
     replyTarget,
@@ -352,21 +362,20 @@ export async function dispatchInbound(params: InboundParams): Promise<void> {
   const messageType = params.messageType;
   if (messageType && NOTIFICATION_TYPES.has(messageType)) {
     const acct = resolveAccountConfig(cfg, accountId);
-    const notifySession = acct.notifySession;
-    if (notifySession) {
-      const childSessionKey = route.sessionKey || sessionKey;
-      if (childSessionKey !== notifySession) {
-        const topicLabel = topic ? ` (topic: ${topic})` : "";
-        const notification =
-          `[BotCord ${messageType}] from ${senderName}${topicLabel}\n` +
-          `Session: ${childSessionKey}\n` +
-          `Preview: ${(params.content || "").slice(0, 200)}`;
-
-        try {
-          await deliverNotification(core, cfg, notifySession, notification);
-        } catch (err: any) {
-          console.error(`[botcord] auto-notify failed:`, err?.message ?? err);
-        }
+    const sessions = normalizeNotifySessions(acct.notifySession);
+    const childSessionKey = route.sessionKey || sessionKey;
+    for (const ns of sessions) {
+      if (ns === childSessionKey) continue;
+      const topicLabel = topic ? ` (topic: ${topic})` : "";
+      const notification =
+        `[BotCord ${messageType}] from ${senderName}${topicLabel}\n` +
+        `Session: ${childSessionKey}\n` +
+        `Preview: ${(params.content || "").slice(0, 200)}`;
+
+      try {
+        await deliverNotification(core, cfg, ns, notification);
+      } catch (err: any) {
+        console.error(`[botcord] auto-notify failed:`, err?.message ?? err);
       }
     }
   }

package/src/poller.ts

@@ -27,16 +27,26 @@ export function startPoller(opts: PollerOptions): { stop: () => void } {
     if (!running || abortSignal?.aborted) return;
 
     try {
-      const resp = await client.pollInbox({ limit: 20, ack: true });
+      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}`);
         }
       }
+
+      if (ackedIds.length > 0) {
+        try {
+          await client.ackMessages(ackedIds);
+        } catch (err: any) {
+          log?.error(`[${dp}] ack error: ${err.message}`);
+        }
+      }
     } catch (err: any) {
       if (!running) return;
       log?.error(`[${dp}] poll error: ${err.message}`);

package/src/reset-credential.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared BotCord credential reset flow for commands and tools.
+ * Generates a new local keypair, redeems a one-time reset code/ticket, and
+ * persists the replacement credentials through OpenClaw's config writer.
+ */
+import { defaultCredentialsFile, type StoredBotCordCredentials, writeCredentialsFile } from "./credentials.js";
+import { generateKeypair } from "./crypto.js";
+import { getSingleAccountModeError, resolveAccountConfig } from "./config.js";
+import { normalizeAndValidateHubUrl } from "./hub-url.js";
+import { getBotCordRuntime } from "./runtime.js";
+
+export interface ResetCredentialResult {
+  agentId: string;
+  displayName: string;
+  keyId: string;
+  hubUrl: string;
+  credentialsFile: string;
+}
+
+type ResetCredentialApiResponse = {
+  agent_id: string;
+  display_name: string;
+  key_id: string;
+  agent_token: string;
+  expires_at: number;
+  hub_url?: string | null;
+};
+
+function stripInlineCredentials(botcordCfg: Record<string, any>): Record<string, any> {
+  const next = { ...botcordCfg };
+  delete next.hubUrl;
+  delete next.agentId;
+  delete next.keyId;
+  delete next.privateKey;
+  delete next.publicKey;
+  return next;
+}
+
+function buildNextConfig(config: Record<string, any>, credentialsFile: string): Record<string, any> {
+  const currentBotcord = ((config.channels as Record<string, any>)?.botcord ?? {}) as Record<string, any>;
+  return {
+    ...config,
+    channels: {
+      ...(config.channels as Record<string, any>),
+      botcord: {
+        ...stripInlineCredentials(currentBotcord),
+        enabled: true,
+        credentialsFile,
+        deliveryMode: currentBotcord.deliveryMode === "polling" ? "polling" : "websocket",
+        notifySession: currentBotcord.notifySession || "botcord:owner:main",
+      },
+    },
+    session: {
+      ...(config.session as Record<string, any>),
+      dmScope: (config.session as Record<string, any>)?.dmScope || "per-channel-peer",
+    },
+  };
+}
+
+export async function resetCredential(opts: {
+  config: Record<string, any>;
+  agentId: string;
+  resetCodeOrTicket: string;
+  hubUrl?: string;
+}): Promise<ResetCredentialResult> {
+  const { config, agentId, resetCodeOrTicket } = opts;
+  const singleAccountError = getSingleAccountModeError(config);
+  if (singleAccountError) {
+    throw new Error(singleAccountError);
+  }
+  if (!agentId.startsWith("ag_")) {
+    throw new Error("agent_id must start with 'ag_'");
+  }
+  if (!resetCodeOrTicket.trim()) {
+    throw new Error("reset code or reset ticket is required");
+  }
+
+  const existingAccount = resolveAccountConfig(config);
+  const resolvedHubUrl = normalizeAndValidateHubUrl(
+    opts.hubUrl || existingAccount.hubUrl || "",
+  );
+
+  const keypair = generateKeypair();
+  const payload: Record<string, unknown> = {
+    agent_id: agentId,
+    pubkey: keypair.pubkeyFormatted,
+  };
+  if (resetCodeOrTicket.startsWith("rc_")) {
+    payload.reset_code = resetCodeOrTicket;
+  } else {
+    payload.reset_ticket = resetCodeOrTicket;
+  }
+
+  const resp = await fetch(`${resolvedHubUrl}/api/users/me/agents/reset-credential`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(15000),
+  });
+
+  const body = (await resp.json().catch(() => null)) as ResetCredentialApiResponse | { detail?: string; error?: string } | null;
+  if (!resp.ok) {
+    const message = (body as any)?.detail || (body as any)?.error || resp.statusText;
+    throw new Error(`Credential reset failed (${resp.status}): ${message}`);
+  }
+
+  const result = body as ResetCredentialApiResponse;
+  const finalHubUrl = normalizeAndValidateHubUrl(result.hub_url || resolvedHubUrl);
+  const credentials: StoredBotCordCredentials = {
+    version: 1,
+    hubUrl: finalHubUrl,
+    agentId: result.agent_id,
+    keyId: result.key_id,
+    privateKey: keypair.privateKey,
+    publicKey: keypair.publicKey,
+    displayName: result.display_name,
+    savedAt: new Date().toISOString(),
+    token: result.agent_token,
+    tokenExpiresAt: result.expires_at,
+  };
+
+  const runtime = getBotCordRuntime();
+  const credentialsFile = writeCredentialsFile(
+    existingAccount.credentialsFile || defaultCredentialsFile(result.agent_id),
+    credentials,
+  );
+  await runtime.config.writeConfigFile(buildNextConfig(config, credentialsFile));
+
+  return {
+    agentId: result.agent_id,
+    displayName: result.display_name,
+    keyId: result.key_id,
+    hubUrl: finalHubUrl,
+    credentialsFile,
+  };
+}

package/src/tools/account.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createAccountTool() {
@@ -55,6 +56,7 @@ export function createAccountTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/bind.ts

@@ -10,6 +10,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 const DEFAULT_DASHBOARD_URL = "https://www.botcord.chat";
@@ -32,6 +33,7 @@ export async function executeBind(
   }
 
   const client = new BotCordClient(acct);
+  attachTokenPersistence(client, acct);
 
   try {
     const agentToken = await client.ensureToken();

package/src/tools/contacts.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createContactsTool() {
@@ -65,6 +66,7 @@ export function createContactsTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/directory.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createDirectoryTool() {
@@ -73,6 +74,7 @@ export function createDirectoryTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/messaging.ts

@@ -10,6 +10,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import type { MessageAttachment } from "../types.js";
 
@@ -142,6 +143,7 @@ export function createMessagingTool() {
 
       try {
         const client = new BotCordClient(acct);
+        attachTokenPersistence(client, acct);
         const msgType = args.type || "message";
 
         // Collect attachments from both file_paths (upload first) and file_urls
@@ -226,6 +228,7 @@ export function createUploadTool() {
 
       try {
         const client = new BotCordClient(acct);
+        attachTokenPersistence(client, acct);
         const uploaded = await uploadLocalFiles(client, args.file_paths);
         return { ok: true, files: uploaded };
       } catch (err: any) {

package/src/tools/notify.ts

@@ -6,7 +6,7 @@
 import { getBotCordRuntime } from "../runtime.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import { getSingleAccountModeError, resolveAccountConfig } from "../config.js";
-import { deliverNotification } from "../inbound.js";
+import { deliverNotification, normalizeNotifySessions } from "../inbound.js";
 
 export function createNotifyTool() {
   return {
@@ -34,8 +34,8 @@ export function createNotifyTool() {
       if (singleAccountError) return { error: singleAccountError };
 
       const acct = resolveAccountConfig(cfg);
-      const notifySession = acct.notifySession;
-      if (!notifySession) {
+      const sessions = normalizeNotifySessions(acct.notifySession);
+      if (sessions.length === 0) {
         return { error: "notifySession is not configured in channels.botcord" };
       }
 
@@ -45,12 +45,23 @@ export function createNotifyTool() {
         return { error: "text is required" };
       }
 
-      try {
-        await deliverNotification(core, cfg, notifySession, text);
-        return { ok: true, notifySession };
-      } catch (err: any) {
-        return { error: `notify failed: ${err?.message ?? err}` };
+      const errors: string[] = [];
+      for (const ns of sessions) {
+        try {
+          await deliverNotification(core, cfg, ns, text);
+        } catch (err: any) {
+          errors.push(`${ns}: ${err?.message ?? err}`);
+        }
       }
+
+      if (errors.length > 0) {
+        return {
+          ok: errors.length < sessions.length,
+          notifySessions: sessions,
+          errors,
+        };
+      }
+      return { ok: true, notifySessions: sessions };
     },
   };
 }

package/src/tools/payment.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import { formatCoinAmount } from "./coin-format.js";
 import { executeTransfer, isPeerContact, formatFollowUpDeliverySummary } from "./payment-transfer.js";
@@ -302,6 +303,7 @@ export function createPaymentTool(opts?: { name?: string; description?: string }
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/reset-credential.ts

@@ -0,0 +1,58 @@
+/**
+ * botcord_reset_credential — tool wrapper for the credential reset flow.
+ */
+import { getConfig as getAppConfig } from "../runtime.js";
+import { resetCredential } from "../reset-credential.js";
+
+export function createResetCredentialTool() {
+  return {
+    name: "botcord_reset_credential",
+    label: "Reset Credential",
+    description:
+      "Generate a fresh BotCord credential for an existing agent using a one-time reset code or reset ticket.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        agent_id: {
+          type: "string" as const,
+          description: "Existing BotCord agent ID (ag_...)",
+        },
+        reset_code: {
+          type: "string" as const,
+          description: "One-time reset code or raw reset ticket from the dashboard",
+        },
+        hub_url: {
+          type: "string" as const,
+          description: "Hub URL; defaults to the configured BotCord hub if available",
+        },
+      },
+      required: ["agent_id", "reset_code"],
+    },
+    execute: async (_toolCallId: any, args: any) => {
+      const cfg = getAppConfig();
+      if (!cfg) return { error: "No configuration available" };
+      if (!args.agent_id) return { error: "agent_id is required" };
+      if (!args.reset_code) return { error: "reset_code is required" };
+
+      try {
+        const result = await resetCredential({
+          config: cfg,
+          agentId: args.agent_id,
+          resetCodeOrTicket: args.reset_code,
+          hubUrl: args.hub_url,
+        });
+        return {
+          ok: true,
+          agent_id: result.agentId,
+          display_name: result.displayName,
+          key_id: result.keyId,
+          hub_url: result.hubUrl,
+          credentials_file: result.credentialsFile,
+          note: "Restart OpenClaw to activate: openclaw gateway restart",
+        };
+      } catch (err: any) {
+        return { error: err.message };
+      }
+    },
+  };
+}

package/src/tools/rooms.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createRoomsTool() {
@@ -116,6 +117,7 @@ export function createRoomsTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/subscription.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 import { formatCoinAmount } from "./coin-format.js";
 
@@ -141,6 +142,7 @@ export function createSubscriptionTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/tools/topics.ts

@@ -7,6 +7,7 @@ import {
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
 import { getConfig as getAppConfig } from "../runtime.js";
 
 export function createTopicsTool() {
@@ -64,6 +65,7 @@ export function createTopicsTool() {
       }
 
       const client = new BotCordClient(acct);
+      attachTokenPersistence(client, acct);
 
       try {
         switch (args.action) {

package/src/types.ts

@@ -42,10 +42,12 @@ export type BotCordAccountConfig = {
   keyId?: string;
   privateKey?: string;
   publicKey?: string;
+  token?: string;
+  tokenExpiresAt?: number;
   deliveryMode?: "polling" | "websocket";
   pollIntervalMs?: number;
   allowFrom?: string[];
-  notifySession?: string;
+  notifySession?: string | string[];
   accounts?: Record<string, BotCordAccountConfig>;
 };
 
@@ -71,6 +73,7 @@ export type InboxMessage = {
   mentioned?: boolean;
   source_type?: SourceType;
   source_user_id?: string | null;
+  source_user_name?: string | null;
   source_session_kind?: string | null;
 };
 

package/src/ws-client.ts

@@ -27,14 +27,19 @@ interface WsClientOptions {
   };
 }
 
-const activeWsClients = new Map<string, { stop: () => void }>();
+// 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;
+function getActiveWsClients() {
+  return (_activeWsClients ??= new Map());
+}
 
 // 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 } {
   // Stop any existing client for this account before creating a new one
-  const existing = activeWsClients.get(opts.accountId);
+  const existing = getActiveWsClients().get(opts.accountId);
   if (existing) existing.stop();
 
   const { client, accountId, cfg, abortSignal, log } = opts;
@@ -43,6 +48,8 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
   let ws: WebSocket | null = null;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   let reconnectAttempt = 0;
+  let consecutiveAuthFailures = 0;
+  const MAX_AUTH_FAILURES = 5;
   let processing = false;
   let keepaliveTimer: ReturnType<typeof setInterval> | null = null;
   const KEEPALIVE_INTERVAL = 20_000; // 20s — well under Caddy/proxy 30s timeout
@@ -51,15 +58,24 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
     if (processing) return;
     processing = true;
     try {
-      const resp = await client.pollInbox({ limit: 20, ack: true });
+      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}] ws dispatch error for ${msg.hub_msg_id}: ${err.message}`);
         }
       }
+      if (ackedIds.length > 0) {
+        try {
+          await client.ackMessages(ackedIds);
+        } catch (err: any) {
+          log?.error(`[${dp}] ws ack error: ${err.message}`);
+        }
+      }
     } catch (err: any) {
       log?.error(`[${dp}] ws poll error: ${err.message}`);
     } finally {
@@ -91,6 +107,7 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
             case "auth_ok":
               log?.info(`[${dp}] WebSocket authenticated as ${msg.agent_id}`);
               reconnectAttempt = 0; // Reset backoff on successful auth
+              consecutiveAuthFailures = 0; // Reset auth failure counter
               // Start client-side keepalive to survive proxies/Caddy timeouts
               if (keepaliveTimer) clearInterval(keepaliveTimer);
               keepaliveTimer = setInterval(() => {
@@ -98,6 +115,8 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
                   ws.send(JSON.stringify({ type: "ping" }));
                 }
               }, KEEPALIVE_INTERVAL);
+              // Catch up on messages missed during disconnect
+              fetchAndDispatch();
               break;
 
             case "inbox_update":
@@ -122,15 +141,25 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
         }
       });
 
-      ws.on("close", (code: number, reason: Buffer) => {
+      ws.on("close", async (code: number, reason: Buffer) => {
         const reasonStr = reason.toString();
         log?.info(`[${dp}] WebSocket closed: code=${code} reason=${reasonStr}`);
         ws = null;
         if (keepaliveTimer) { clearInterval(keepaliveTimer); keepaliveTimer = null; }
 
         if (code === 4001) {
-          // Auth failure — don't reconnect immediately, token may need refresh
-          log?.warn(`[${dp}] WebSocket auth failed, will retry with fresh token`);
+          consecutiveAuthFailures++;
+          if (consecutiveAuthFailures >= MAX_AUTH_FAILURES) {
+            log?.error(`[${dp}] WebSocket auth failed ${consecutiveAuthFailures} times consecutively, stopping reconnect`);
+            return;
+          }
+          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 {
+            await client.ensureToken(true);
+          } catch (err: any) {
+            log?.error(`[${dp}] Token force-refresh failed: ${err.message}`);
+          }
         }
 
         scheduleReconnect();
@@ -167,14 +196,14 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
       }
       ws = null;
     }
-    activeWsClients.delete(accountId);
+    getActiveWsClients().delete(accountId);
   }
 
   // Start connection
   connect();
 
   const entry = { stop };
-  activeWsClients.set(accountId, entry);
+  getActiveWsClients().set(accountId, entry);
 
   abortSignal?.addEventListener("abort", stop, { once: true });
 
@@ -182,6 +211,6 @@ export function startWsClient(opts: WsClientOptions): { stop: () => void } {
 }
 
 export function stopWsClient(accountId: string): void {
-  const entry = activeWsClients.get(accountId);
+  const entry = getActiveWsClients().get(accountId);
   if (entry) entry.stop();
 }