openclaw-elys 1.5.0 → 1.7.0

package/README.md

@@ -4,6 +4,22 @@ OpenClaw channel plugin for [Elys App](https://elys.ai) — connects your local
 
 Elys App 的 OpenClaw 频道插件 — 将本地 OpenClaw 智能体连接到 Elys 手机应用。
 
+## Requirements / 版本要求
+
+OpenClaw >= **2026.2.19**（通过 `openclaw -v` 查看当前版本）
+
+低于该版本可能导致 AI 推理无法正常工作（缺少 channelRuntime 支持）。
+
+升级方式：
+
+```bash
+npm install -g openclaw
+# 国内网络慢可使用镜像源：
+npm install -g openclaw --registry=https://registry.npmmirror.com
+```
+
+其他升级方式参考：[OpenClaw 安装文档](https://docs.openclaw.ai/install/development-channels#switching-channels)
+
 ## Install & Setup / 安装与配置
 
 ```bash

package/dist/index.js

@@ -1,4 +1,5 @@
 import { elysPlugin } from "./src/channel.js";
+import { setElysRuntime } from "./src/runtime.js";
 export { elysPlugin } from "./src/channel.js";
 export { monitorElysProvider } from "./src/monitor.js";
 export { registerDevice } from "./src/register.js";
@@ -10,6 +11,7 @@ const plugin = {
     description: "Elys App channel plugin — connects to Elys App via MQTT gateway",
     configSchema: { type: "object", properties: {} },
     register(api) {
+        setElysRuntime(api.runtime);
         api.registerChannel({ plugin: elysPlugin });
     },
 };

package/dist/src/channel.d.ts

@@ -83,7 +83,6 @@ export declare const elysPlugin: {
                 error?: (...args: unknown[]) => void;
             };
             setStatus: (status: Record<string, unknown>) => void;
-            channelRuntime?: Record<string, unknown>;
         }) => Promise<void>;
     };
 };

package/dist/src/channel.js

@@ -56,7 +56,6 @@ export const elysPlugin = {
                 runtime: ctx.runtime,
                 abortSignal: ctx.abortSignal,
                 accountId: ctx.accountId,
-                channelRuntime: ctx.channelRuntime,
             });
         },
     },

package/dist/src/monitor.d.ts

@@ -3,39 +3,8 @@ export interface MonitorElysOpts {
     runtime?: Record<string, unknown>;
     abortSignal?: AbortSignal;
     accountId?: string;
-    channelRuntime?: ChannelRuntimeReply;
+    channelRuntime?: unknown;
 }
-/** Subset of OpenClaw's PluginRuntime["channel"] that we use */
-type ReplyPayload = {
-    text?: string;
-    mediaUrl?: string;
-    audioAsVoice?: boolean;
-    [key: string]: unknown;
-};
-type ChannelRuntimeReply = {
-    reply?: {
-        dispatchReplyWithBufferedBlockDispatcher?: (params: {
-            ctx: Record<string, unknown>;
-            cfg: Record<string, unknown>;
-            dispatcherOptions: {
-                deliver: (payload: ReplyPayload, info: {
-                    kind: "tool" | "block" | "final";
-                }) => Promise<void>;
-                onError?: (err: unknown, info: {
-                    kind: string;
-                }) => void;
-            };
-            replyOptions?: Record<string, unknown>;
-        }) => Promise<{
-            queuedFinal: boolean;
-            counts: Record<string, number>;
-        }>;
-        finalizeInboundContext?: (ctx: Record<string, unknown>) => Record<string, unknown>;
-    };
-    routing?: {
-        resolveAgentRoute?: (params: Record<string, unknown>) => Record<string, unknown>;
-    };
-};
 /**
  * The main monitor loop for the Elys channel.
  * Ensures device is registered, then connects to MQTT and dispatches
@@ -43,4 +12,3 @@ type ChannelRuntimeReply = {
  * channelRuntime dispatch API (supports streaming).
  */
 export declare function monitorElysProvider(opts: MonitorElysOpts): Promise<void>;
-export {};

package/dist/src/monitor.js

@@ -1,6 +1,7 @@
 import { loadCredentials } from "./config.js";
 import { registerDevice } from "./register.js";
 import { ElysDeviceMQTTClient } from "./mqtt-client.js";
+import { getElysRuntime } from "./runtime.js";
 /**
  * The main monitor loop for the Elys channel.
  * Ensures device is registered, then connects to MQTT and dispatches
@@ -26,19 +27,18 @@ export async function monitorElysProvider(opts) {
     }
     // 2. Connect MQTT
     const mqttClient = new ElysDeviceMQTTClient(credentials, log);
-    // 3. Set up command handler
-    const channelRuntime = opts.channelRuntime;
-    const dispatchReply = channelRuntime?.reply?.dispatchReplyWithBufferedBlockDispatcher;
-    const finalizeCtx = channelRuntime?.reply?.finalizeInboundContext;
-    log(`[elys] channelRuntime available: ${!!channelRuntime}, dispatchReply: ${!!dispatchReply}, finalizeCtx: ${!!finalizeCtx}`);
-    const commandHandler = async (cmd) => {
+    // 3. Set up command handler using PluginRuntime (same pattern as feishu)
+    const core = getElysRuntime();
+    const dispatchReplyFromConfig = core?.channel?.reply?.dispatchReplyFromConfig;
+    const withReplyDispatcher = core?.channel?.reply?.withReplyDispatcher;
+    const finalizeCtx = core?.channel?.reply?.finalizeInboundContext;
+    log(`[elys] pluginRuntime available: ${!!core}, dispatchReplyFromConfig: ${!!dispatchReplyFromConfig}, finalizeCtx: ${!!finalizeCtx}`);
+    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) {
+        if (dispatchReplyFromConfig && finalizeCtx) {
             try {
                 let seq = 0;
                 let fullText = "";
-                // Build inbound context following OpenClaw protocol
                 const inboundCtx = finalizeCtx({
                     Body: formatCommandAsText(cmd),
                     BodyForAgent: formatCommandAsText(cmd),
@@ -55,35 +55,53 @@ export async function monitorElysProvider(opts) {
                     OriginatingChannel: "elys",
                     OriginatingTo: credentials.deviceId,
                 });
-                await dispatchReply({
-                    ctx: inboundCtx,
-                    cfg: opts.config,
-                    dispatcherOptions: {
-                        // Single deliver callback with kind discriminator (matches OpenClaw API)
-                        deliver: async (payload, info) => {
-                            if (payload.text) {
-                                fullText += payload.text;
-                                seq++;
-                                const done = info.kind === "final";
-                                mqttClient.publishStreamChunk(cmd.id, payload.text, seq, done, cmd.reply_to);
-                                if (info.kind === "block") {
-                                    log(`[elys] stream chunk #${seq}: ${payload.text.slice(0, 80)}...`);
-                                }
-                                else if (info.kind === "final") {
-                                    log(`[elys] final reply delivered`);
-                                }
-                            }
-                            else if (info.kind === "final") {
-                                seq++;
-                                mqttClient.publishStreamChunk(cmd.id, "", seq, true, cmd.reply_to);
-                                log(`[elys] final reply delivered (empty)`);
-                            }
-                        },
-                        onError: (err, info) => {
-                            log(`[elys] dispatch error (${info.kind}):`, err);
+                // Deliver callback: stream chunks back via MQTT
+                const deliver = async (payload, info) => {
+                    if (signal.aborted)
+                        return;
+                    if (payload.text) {
+                        fullText += payload.text;
+                        seq++;
+                        const done = info.kind === "final";
+                        mqttClient.publishStreamChunk(cmd.id, payload.text, seq, done, cmd.reply_to);
+                        if (info.kind === "block") {
+                            log(`[elys] stream chunk #${seq}: ${payload.text.slice(0, 80)}...`);
+                        }
+                        else if (info.kind === "final") {
+                            log(`[elys] final reply delivered`);
+                        }
+                    }
+                    else if (info.kind === "final") {
+                        seq++;
+                        mqttClient.publishStreamChunk(cmd.id, "", seq, true, cmd.reply_to);
+                        log(`[elys] final reply delivered (empty)`);
+                    }
+                };
+                if (withReplyDispatcher) {
+                    // Preferred path: withReplyDispatcher + dispatchReplyFromConfig (same as feishu)
+                    await withReplyDispatcher({
+                        ctx: inboundCtx,
+                        cfg: opts.config,
+                        dispatcher: { deliver },
+                        fn: (dispatchCtx) => dispatchReplyFromConfig({
+                            ctx: dispatchCtx,
+                            cfg: opts.config,
+                        }),
+                    });
+                }
+                else {
+                    // Direct dispatch fallback
+                    await dispatchReplyFromConfig({
+                        ctx: inboundCtx,
+                        cfg: opts.config,
+                        dispatcherOptions: {
+                            deliver,
+                            onError: (err, info) => {
+                                log(`[elys] dispatch error (${info.kind}):`, err);
+                            },
                         },
-                    },
-                });
+                    });
+                }
                 return {
                     id: cmd.id,
                     type: "result",
@@ -103,8 +121,8 @@ export async function monitorElysProvider(opts) {
                 };
             }
         }
-        // Fallback: echo the command back (no channelRuntime available)
-        log(`[elys] no channelRuntime — using fallback echo handler`);
+        // Fallback: echo the command back (no pluginRuntime available)
+        log(`[elys] no pluginRuntime — using fallback echo handler`);
         return {
             id: cmd.id,
             type: "result",

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/dist/src/runtime.d.ts

@@ -0,0 +1,2 @@
+export declare function setElysRuntime(next: unknown): void;
+export declare function getElysRuntime(): any;

package/dist/src/runtime.js

@@ -0,0 +1,10 @@
+// Stores the PluginRuntime passed via api.runtime during plugin registration.
+// This is the same pattern used by the built-in feishu channel plugin.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let runtime = null;
+export function setElysRuntime(next) {
+    runtime = next;
+}
+export function getElysRuntime() {
+    return runtime;
+}

package/package.json

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