@zbruceli/openclaw-dchat 0.2.0 → 0.3.0

package/.claude/settings.local.json

@@ -4,7 +4,9 @@
       "WebFetch(domain:docs.openclaw.ai)",
       "Bash(node:*)",
       "Bash(ls:*)",
-      "Bash(npm test:*)"
+      "Bash(npm test:*)",
+      "Bash(npm run:*)",
+      "Bash(openclaw status:*)"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zbruceli/openclaw-dchat",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenClaw D-Chat/nMobile channel plugin — decentralized E2E encrypted messaging over the NKN relay network",
   "type": "module",
   "main": "index.ts",

package/src/channel.ts

@@ -438,6 +438,39 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
       const seenTracker = new SeenTracker();
       seenMap.set(account.accountId, seenTracker);
 
+      // Listen for heartbeat events
+      bus.on("heartbeat", ({ success, failures }: { success: boolean; failures: number }) => {
+        if (!success) {
+          logger.warn(`[${account.accountId}] heartbeat echo failed (${failures} consecutive)`);
+        }
+      });
+      bus.on("heartbeatReconnect", ({ failures }: { failures: number }) => {
+        logger.warn(
+          `[${account.accountId}] heartbeat failed ${failures} times, reconnecting...`,
+        );
+        ctx.setStatus({ accountId: account.accountId, connected: false });
+      });
+      let initialConnectDone = false;
+      bus.on("stateChange", (state: string) => {
+        if (state === "connected" && initialConnectDone) {
+          ctx.setStatus({
+            accountId: account.accountId,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          });
+          logger.info(`[${account.accountId}] reconnected as ${bus.getAddress()}`);
+        }
+      });
+      bus.on("reconnectFailed", (err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`[${account.accountId}] reconnect failed: ${msg}`);
+        ctx.setStatus({
+          accountId: account.accountId,
+          connected: false,
+          lastError: `reconnect failed: ${msg}`,
+        });
+      });
+
       try {
         const address = await bus.connect(
           { seed: account.seed, numSubClients: account.numSubClients },
@@ -453,6 +486,7 @@ export const dchatPlugin: ChannelPlugin<ResolvedDchatAccount> = {
           lastConnectedAt: Date.now(),
         });
         logger.info(`[${account.accountId}] connected as ${address}`);
+        initialConnectDone = true;
 
         // Register inbound message handler
         bus.onMessage((rawSrc, rawPayload) => {

package/src/nkn-bus.ts

@@ -5,12 +5,20 @@ import { NKN_SEED_RPC_SERVERS, type NknConnectionState } from "./types.js";
 export interface NknBusOptions {
   seed: string;
   numSubClients?: number;
+  /** Heartbeat echo-test interval in ms (default 60 000). Set 0 to disable. */
+  heartbeatIntervalMs?: number;
+  /** Consecutive heartbeat failures before reconnecting (default 3). */
+  heartbeatMaxFailures?: number;
 }
 
+/** Payload used for heartbeat echo-test messages (self → self). */
+const HEARTBEAT_ECHO_PREFIX = "__nkn_heartbeat_echo__:";
+
 /**
  * NKN MultiClient wrapper for D-Chat wire-format messaging.
- * Handles connect, send, receive, subscribe, and reconnection.
+ * Handles connect, send, receive, subscribe, heartbeat, and reconnection.
  */
+
 export class NknBus extends EventEmitter {
   private client: nkn.MultiClient | null = null;
   private state: NknConnectionState = "disconnected";
@@ -20,6 +28,14 @@ export class NknBus extends EventEmitter {
   private numSubClients: number;
   private abortSignal: AbortSignal | undefined;
 
+  private heartbeatIntervalMs: number = 60_000;
+  private heartbeatMaxFailures: number = 3;
+  private heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  private heartbeatFailures: number = 0;
+  private pendingEchoId: string | null = null;
+  private pendingEchoResolve: (() => void) | null = null;
+  private isReconnecting: boolean = false;
+
   constructor() {
     super();
     this.numSubClients = 4;
@@ -40,6 +56,8 @@ export class NknBus extends EventEmitter {
 
     this.seed = opts.seed;
     this.numSubClients = opts.numSubClients ?? 4;
+    this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 60_000;
+    this.heartbeatMaxFailures = opts.heartbeatMaxFailures ?? 3;
     this.abortSignal = abortSignal;
     this.setState("connecting");
 
@@ -86,9 +104,23 @@ export class NknBus extends EventEmitter {
         } else {
           data = payload;
         }
+
+        // Intercept heartbeat echo responses — don't emit as regular messages
+        if (data.startsWith(HEARTBEAT_ECHO_PREFIX)) {
+          const echoId = data.slice(HEARTBEAT_ECHO_PREFIX.length);
+          if (echoId === this.pendingEchoId && this.pendingEchoResolve) {
+            this.pendingEchoResolve();
+            this.pendingEchoResolve = null;
+            this.pendingEchoId = null;
+          }
+          return;
+        }
+
         this.emit("message", src, data);
       });
 
+      this.startHeartbeat();
+
       return this.address;
     } catch (err) {
       this.setState("disconnected");
@@ -105,6 +137,7 @@ export class NknBus extends EventEmitter {
   }
 
   async disconnect(): Promise<void> {
+    this.stopHeartbeat();
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -200,6 +233,185 @@ export class NknBus extends EventEmitter {
     this.on("message", handler);
   }
 
+  /** Start periodic heartbeat echo test (self → self). */
+  private startHeartbeat(): void {
+    if (this.heartbeatIntervalMs <= 0) return;
+    this.heartbeatFailures = 0;
+    this.scheduleNextHeartbeat();
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearTimeout(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    // Reject any pending echo wait
+    this.pendingEchoResolve = null;
+    this.pendingEchoId = null;
+  }
+
+  private scheduleNextHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearTimeout(this.heartbeatTimer);
+    }
+    this.heartbeatTimer = setTimeout(() => {
+      void this.runHeartbeat();
+    }, this.heartbeatIntervalMs);
+  }
+
+  private async runHeartbeat(): Promise<void> {
+    if (!this.client || this.state !== "connected" || !this.address) {
+      return;
+    }
+
+    const echoId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const echoPayload = HEARTBEAT_ECHO_PREFIX + echoId;
+
+    try {
+      const echoReceived = await new Promise<boolean>((resolve) => {
+        this.pendingEchoId = echoId;
+        // Timeout: half the heartbeat interval or 15s, whichever is smaller
+        const timeout = Math.min(this.heartbeatIntervalMs / 2, 15_000);
+        const timer = setTimeout(() => {
+          this.pendingEchoResolve = null;
+          this.pendingEchoId = null;
+          resolve(false);
+        }, timeout);
+
+        this.pendingEchoResolve = () => {
+          clearTimeout(timer);
+          resolve(true);
+        };
+
+        // Send echo to self (fire-and-forget send, we wait for the message handler)
+        this.client!.send(this.address!, echoPayload, { noReply: true });
+      });
+
+      if (echoReceived) {
+        this.heartbeatFailures = 0;
+        this.emit("heartbeat", { success: true, failures: 0 });
+      } else {
+        this.heartbeatFailures++;
+        this.emit("heartbeat", { success: false, failures: this.heartbeatFailures });
+
+        if (this.heartbeatFailures >= this.heartbeatMaxFailures) {
+          this.emit("heartbeatReconnect", { failures: this.heartbeatFailures });
+          await this.reconnect();
+          return; // reconnect starts a new heartbeat loop
+        }
+      }
+    } catch {
+      this.heartbeatFailures++;
+      this.emit("heartbeat", { success: false, failures: this.heartbeatFailures });
+
+      if (this.heartbeatFailures >= this.heartbeatMaxFailures) {
+        this.emit("heartbeatReconnect", { failures: this.heartbeatFailures });
+        await this.reconnect();
+        return;
+      }
+    }
+
+    // Schedule next heartbeat if still connected
+    if (this.state === "connected") {
+      this.scheduleNextHeartbeat();
+    }
+  }
+
+  /** Close the current connection and create a new one using stored options. */
+  private async reconnect(): Promise<void> {
+    if (this.isReconnecting || !this.seed) return;
+    this.isReconnecting = true;
+
+    try {
+      this.stopHeartbeat();
+
+      // Close existing client
+      if (this.client) {
+        try {
+          this.client.close();
+        } catch {
+          // ignore close errors
+        }
+        this.client = null;
+      }
+      this.address = undefined;
+      this.setState("connecting");
+
+      // Create a fresh client
+      this.client = new nkn.MultiClient({
+        seed: this.seed,
+        numSubClients: this.numSubClients,
+        originalClient: false,
+        rpcServerAddr: NKN_SEED_RPC_SERVERS[0],
+      });
+
+      await new Promise<void>((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(new Error("NKN reconnection timeout after 30s"));
+        }, 30_000);
+
+        if (this.abortSignal?.aborted) {
+          clearTimeout(timeout);
+          reject(new Error("Aborted"));
+          return;
+        }
+
+        const onAbort = () => {
+          clearTimeout(timeout);
+          reject(new Error("Aborted"));
+        };
+        this.abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+        this.client!.onConnect(() => {
+          clearTimeout(timeout);
+          this.abortSignal?.removeEventListener("abort", onAbort);
+          resolve();
+        });
+      });
+
+      this.address = this.client.addr;
+      this.setState("connected");
+
+      // Re-register message handler
+      this.client.onMessage(({ src, payload }: { src: string; payload: Uint8Array | string }) => {
+        let data: string;
+        if (payload instanceof Uint8Array) {
+          data = new TextDecoder().decode(payload);
+        } else {
+          data = payload;
+        }
+
+        if (data.startsWith(HEARTBEAT_ECHO_PREFIX)) {
+          const id = data.slice(HEARTBEAT_ECHO_PREFIX.length);
+          if (id === this.pendingEchoId && this.pendingEchoResolve) {
+            this.pendingEchoResolve();
+            this.pendingEchoResolve = null;
+            this.pendingEchoId = null;
+          }
+          return;
+        }
+
+        this.emit("message", src, data);
+      });
+
+      this.heartbeatFailures = 0;
+      this.startHeartbeat();
+    } catch (err) {
+      this.setState("disconnected");
+      if (this.client) {
+        try {
+          this.client.close();
+        } catch {
+          // ignore
+        }
+        this.client = null;
+      }
+      this.emit("reconnectFailed", err);
+    } finally {
+      this.isReconnecting = false;
+    }
+  }
+
   private ensureConnected(): void {
     if (!this.client || this.state !== "connected") {
       throw new Error("NKN client not connected");