openclaw-elys 1.5.0 → 1.6.0

package/dist/src/monitor.js

@@ -31,7 +31,7 @@ export async function monitorElysProvider(opts) {
     const dispatchReply = channelRuntime?.reply?.dispatchReplyWithBufferedBlockDispatcher;
     const finalizeCtx = channelRuntime?.reply?.finalizeInboundContext;
     log(`[elys] channelRuntime available: ${!!channelRuntime}, dispatchReply: ${!!dispatchReply}, finalizeCtx: ${!!finalizeCtx}`);
-    const commandHandler = async (cmd) => {
+    const commandHandler = async (cmd, signal) => {
         log(`[elys] executing command: ${cmd.command}`, cmd.args);
         // If we have the full OpenClaw channelRuntime, use the standard dispatch path
         if (dispatchReply && finalizeCtx) {
@@ -59,8 +59,10 @@ export async function monitorElysProvider(opts) {
                     ctx: inboundCtx,
                     cfg: opts.config,
                     dispatcherOptions: {
-                        // Single deliver callback with kind discriminator (matches OpenClaw API)
                         deliver: async (payload, info) => {
+                            // Skip publishing if this command was aborted by a newer one
+                            if (signal.aborted)
+                                return;
                             if (payload.text) {
                                 fullText += payload.text;
                                 seq++;

package/dist/src/mqtt-client.d.ts

@@ -1,8 +1,20 @@
 import type { DeviceCredentials, CommandMessage, ResultMessage } from "./types.js";
-export type CommandHandler = (cmd: CommandMessage) => Promise<ResultMessage>;
+export type CommandHandler = (cmd: CommandMessage, signal: AbortSignal) => Promise<ResultMessage>;
+export interface MQTTClientOptions {
+    /** Debounce window in ms. Rapid messages within this window are merged. Default: 500 */
+    debounceMs?: number;
+    /** Command execution timeout in ms. Default: 120000 (2 min) */
+    commandTimeoutMs?: number;
+}
 /**
  * Manages the MQTT connection to EMQX for a single device.
  * Subscribes to elys/down/{device_id}, publishes to elys/up/{device_id}.
+ *
+ * Features:
+ * - Debounce: rapid messages within a window are merged into one
+ * - Dedup: QoS 1 retransmissions are silently skipped
+ * - Abort: new command aborts the currently running one
+ * - Timeout: commands that run too long are killed
  */
 export declare class ElysDeviceMQTTClient {
     private client;
@@ -11,14 +23,25 @@ export declare class ElysDeviceMQTTClient {
     private log;
     private consecutiveFailures;
     private static readonly MAX_FAILURES_BEFORE_REVOKE_WARNING;
-    private commandQueue;
-    constructor(credentials: DeviceCredentials, log?: (...args: unknown[]) => void);
+    private readonly debounceMs;
+    private debounceTimer;
+    private debounceBuffer;
+    private recentCommandIds;
+    private static readonly DEDUP_TTL_MS;
+    private currentAbort;
+    private readonly commandTimeoutMs;
+    constructor(credentials: DeviceCredentials, log?: (...args: unknown[]) => void, options?: MQTTClientOptions);
     setCommandHandler(handler: CommandHandler): void;
     connect(abortSignal?: AbortSignal): Promise<void>;
     disconnect(): void;
     /** Send a stream chunk (for streaming AI responses) */
     publishStreamChunk(commandId: string, chunk: string, seq: number, done: boolean, replyTo?: string): void;
-    private handleMessage;
+    private onMessage;
+    private flushDebounce;
+    /** Merge multiple buffered commands into one. Joins text args with newline. */
+    private mergeCommands;
+    private executeCommand;
+    private cleanupDedup;
     private publishAck;
     private publish;
 }

package/dist/src/mqtt-client.js

@@ -2,6 +2,12 @@ import mqtt from "mqtt";
 /**
  * Manages the MQTT connection to EMQX for a single device.
  * Subscribes to elys/down/{device_id}, publishes to elys/up/{device_id}.
+ *
+ * Features:
+ * - Debounce: rapid messages within a window are merged into one
+ * - Dedup: QoS 1 retransmissions are silently skipped
+ * - Abort: new command aborts the currently running one
+ * - Timeout: commands that run too long are killed
  */
 export class ElysDeviceMQTTClient {
     client = null;
@@ -10,10 +16,21 @@ export class ElysDeviceMQTTClient {
     log;
     consecutiveFailures = 0;
     static MAX_FAILURES_BEFORE_REVOKE_WARNING = 3;
-    commandQueue = Promise.resolve();
-    constructor(credentials, log) {
+    // Debounce
+    debounceMs;
+    debounceTimer = null;
+    debounceBuffer = [];
+    // Dedup (command id → receive timestamp)
+    recentCommandIds = new Map();
+    static DEDUP_TTL_MS = 60_000;
+    // Abort & timeout
+    currentAbort = null;
+    commandTimeoutMs;
+    constructor(credentials, log, options) {
         this.credentials = credentials;
         this.log = log ?? console.log;
+        this.debounceMs = options?.debounceMs ?? 500;
+        this.commandTimeoutMs = options?.commandTimeoutMs ?? 120_000;
     }
     setCommandHandler(handler) {
         this.commandHandler = handler;
@@ -27,7 +44,7 @@ export class ElysDeviceMQTTClient {
             password: deviceToken,
             reconnectPeriod: 5000,
             keepalive: 30,
-            rejectUnauthorized: true, // verify TLS cert
+            rejectUnauthorized: true,
         });
         this.client.on("connect", () => {
             this.log(`[elys] MQTT connected as ${deviceId}`);
@@ -43,10 +60,7 @@ export class ElysDeviceMQTTClient {
             });
         });
         this.client.on("message", (_topic, payload) => {
-            // Serial queue: commands are processed one at a time in arrival order
-            this.commandQueue = this.commandQueue.then(() => this.handleMessage(payload), () => this.handleMessage(payload)).catch((err) => {
-                this.log("[elys] error handling message:", err);
-            });
+            this.onMessage(payload);
         });
         this.client.on("reconnect", () => {
             this.consecutiveFailures++;
@@ -60,7 +74,6 @@ export class ElysDeviceMQTTClient {
             }
         });
         this.client.on("error", (err) => {
-            // MQTT auth failures indicate revoked credentials
             if (err.message.includes("Not authorized") || err.message.includes("Connection refused")) {
                 this.log(`[elys] ERROR: MQTT authentication failed — device credentials may have been revoked. ` +
                     `Please re-register: npx openclaw-elys setup <gateway_url> <register_token>`);
@@ -72,13 +85,11 @@ export class ElysDeviceMQTTClient {
         this.client.on("close", () => {
             this.log("[elys] MQTT connection closed");
         });
-        // Handle abort signal for graceful shutdown
         if (abortSignal) {
             abortSignal.addEventListener("abort", () => {
                 this.disconnect();
             });
         }
-        // Wait for initial connection
         return new Promise((resolve, reject) => {
             const onConnect = () => {
                 cleanup();
@@ -97,6 +108,11 @@ export class ElysDeviceMQTTClient {
         });
     }
     disconnect() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.currentAbort?.abort();
         if (this.client) {
             this.client.end(true);
             this.client = null;
@@ -115,42 +131,122 @@ export class ElysDeviceMQTTClient {
         };
         this.publish(msg, replyTo);
     }
-    async handleMessage(payload) {
-        const raw = JSON.parse(payload.toString());
+    // ─── Inbound message pipeline: dedup → ack → debounce → abort → execute ───
+    onMessage(payload) {
+        let raw;
+        try {
+            raw = JSON.parse(payload.toString());
+        }
+        catch {
+            this.log("[elys] failed to parse MQTT message");
+            return;
+        }
         if (raw.type !== "command") {
             this.log(`[elys] ignoring non-command message type: ${raw.type}`);
             return;
         }
+        // 1. Dedup — skip QoS 1 retransmissions
+        if (this.recentCommandIds.has(raw.id)) {
+            this.log(`[elys] dedup: skipping duplicate command ${raw.id}`);
+            return;
+        }
+        this.recentCommandIds.set(raw.id, Date.now());
+        this.cleanupDedup();
         this.log(`[elys] received command: ${raw.command} (id: ${raw.id})`);
-        // ACK always goes to shared upstream topic (any gateway instance can process it)
+        // 2. ACK immediately (goes to shared upstream topic)
         this.publishAck(raw.id);
-        // Result/stream goes to reply_to if present (routes to the specific gateway instance)
-        const replyTo = raw.reply_to;
-        // Execute command
-        if (this.commandHandler) {
-            try {
-                const result = await this.commandHandler(raw);
+        // 3. Debounce — buffer and wait for more messages
+        this.debounceBuffer.push(raw);
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.flushDebounce();
+        }, this.debounceMs);
+    }
+    flushDebounce() {
+        const buffered = this.debounceBuffer;
+        this.debounceBuffer = [];
+        this.debounceTimer = null;
+        if (buffered.length === 0)
+            return;
+        // 4. Abort previous running command
+        this.currentAbort?.abort();
+        this.currentAbort = new AbortController();
+        const merged = this.mergeCommands(buffered);
+        // 5. Execute (fire-and-forget, errors handled inside)
+        this.executeCommand(merged, this.currentAbort.signal).catch((err) => {
+            this.log("[elys] unexpected error in executeCommand:", err);
+        });
+    }
+    /** Merge multiple buffered commands into one. Joins text args with newline. */
+    mergeCommands(cmds) {
+        if (cmds.length === 1)
+            return cmds[0];
+        const last = cmds[cmds.length - 1];
+        const texts = cmds
+            .map((c) => c.args?.text ?? "")
+            .filter(Boolean);
+        if (texts.length > 1) {
+            this.log(`[elys] debounce: merged ${cmds.length} commands`);
+            return {
+                ...last,
+                args: { ...last.args, text: texts.join("\n") },
+            };
+        }
+        // Can't merge non-text commands, use the latest one
+        this.log(`[elys] debounce: using latest of ${cmds.length} commands`);
+        return last;
+    }
+    async executeCommand(cmd, signal) {
+        if (!this.commandHandler)
+            return;
+        const replyTo = cmd.reply_to;
+        try {
+            const result = await Promise.race([
+                this.commandHandler(cmd, signal),
+                new Promise((_, reject) => {
+                    const timer = setTimeout(() => {
+                        reject(new Error(`command timed out after ${this.commandTimeoutMs / 1000}s`));
+                    }, this.commandTimeoutMs);
+                    // Clean up timer if command completes or is aborted
+                    signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+                }),
+            ]);
+            if (!signal.aborted) {
                 this.publish(result, replyTo);
             }
-            catch (err) {
-                const errMsg = err instanceof Error ? err.message : String(err);
-                this.publish({
-                    id: raw.id,
-                    type: "result",
-                    timestamp: Date.now() / 1000,
-                    status: "error",
-                    error: errMsg,
-                }, replyTo);
+        }
+        catch (err) {
+            if (signal.aborted) {
+                this.log(`[elys] command ${cmd.id} aborted`);
+                return;
+            }
+            const errMsg = err instanceof Error ? err.message : String(err);
+            this.publish({
+                id: cmd.id,
+                type: "result",
+                timestamp: Math.floor(Date.now() / 1000),
+                status: "error",
+                error: errMsg,
+            }, replyTo);
+        }
+    }
+    cleanupDedup() {
+        const now = Date.now();
+        for (const [id, ts] of this.recentCommandIds) {
+            if (now - ts > ElysDeviceMQTTClient.DEDUP_TTL_MS) {
+                this.recentCommandIds.delete(id);
             }
         }
     }
+    // ─── Outbound helpers ───
     publishAck(commandId) {
         const msg = {
             id: commandId,
             type: "ack",
             timestamp: Math.floor(Date.now() / 1000),
         };
-        // ACK always to default upstream topic (shared subscription)
         this.publish(msg);
     }
     publish(msg, replyTo) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-elys",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "OpenClaw Elys channel plugin — connects to Elys App",
   "type": "module",
   "main": "dist/index.js",