@turquoisebay/mqtt 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.15] - 2026-02-03
+
+### Added
+- Echo `correlationId` from inbound JSON in outbound replies
+
+### Docs
+- Clarify how `senderId` maps to sessions vs `correlationId`
+
+## [0.1.14] - 2026-02-03
+
+### Fixed
+- Robust reconnection logic (handles broker down at startup and restarts)
+- Clean reconnect scheduling + shutdown cleanup
+
 ## [0.1.13] - 2026-02-03
 
 ### Fixed

package/README.md

@@ -10,6 +10,7 @@ MQTT channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) — bid
 
 - 🔌 **Bidirectional messaging** — subscribe and publish to MQTT topics
 - 🏠 **Home automation ready** — integrates with Home Assistant, Mosquitto, EMQX
+- 🔁 **Robust reconnection** — recovers from broker restarts and cold starts
 - 🔒 **TLS support** — secure connections to cloud brokers
 - 📊 **Service monitoring** — receive alerts from Uptime Kuma, healthchecks, etc.
 - ⚡ **QoS levels** — configurable delivery guarantees (0, 1, 2)
@@ -59,6 +60,13 @@ openclaw gateway restart
 
 ## Usage
 
+### Sessions & correlation IDs (important)
+
+- **Sessions are keyed by `senderId`** → OpenClaw uses `mqtt:{senderId}` as the SessionKey, so memory and conversation history are grouped by sender.
+- **`correlationId` is request‑level only** → if you include it in inbound JSON, it’s echoed back in the outbound reply for client-side matching. It does **not** create a new session or change memory.
+
+If you want separate conversations, use distinct `senderId`s.
+
 ### Receiving messages (inbound)
 
 Messages published to your `inbound` topic will be processed by OpenClaw.
@@ -69,7 +77,7 @@ You can send either plain text or JSON (recommended):
 mosquitto_pub -t "openclaw/inbound" -m "Alert: Service down on playground"
 
 # JSON (recommended)
-mosquitto_pub -t "openclaw/inbound" -m '{"senderId":"pg-cli","text":"hello"}'
+mosquitto_pub -t "openclaw/inbound" -m '{"senderId":"pg-cli","text":"hello","correlationId":"abc-123"}'
 ```
 
 ### Sending messages (outbound)

package/dist/src/__mocks__/mqtt.d.ts

@@ -21,6 +21,7 @@ export declare class MockMqttClient extends EventEmitter {
     simulateMessage(topic: string, payload: Buffer | string): void;
     simulateError(err: Error): void;
     simulateDisconnect(): void;
+    reconnect(): this;
     simulateReconnect(): void;
 }
 export declare function connect(url: string, opts?: unknown): MockMqttClient;

package/dist/src/__mocks__/mqtt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mqtt.d.ts","sourceRoot":"","sources":["../../../src/__mocks__/mqtt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC;;GAEG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,SAAS,UAAS;IAClB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAa;IACxD,SAAS,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAM;IAEzE,SAAS,CACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EACrB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI;IAOxC,OAAO,CACL,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI;IAOxC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI;IAQxD,eAAe;IAKf,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAKvD,aAAa,CAAC,GAAG,EAAE,KAAK;IAIxB,kBAAkB;IAKlB,iBAAiB;CAGlB;AAKD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAKnE;AAGD,wBAAgB,aAAa,IAAI,cAAc,GAAG,IAAI,CAErD;AAGD,wBAAgB,SAAS,SAExB;;;;;;AAED,wBAAqD"}
+{"version":3,"file":"mqtt.d.ts","sourceRoot":"","sources":["../../../src/__mocks__/mqtt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC;;GAEG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,SAAS,UAAS;IAClB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAa;IACxD,SAAS,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAM;IAEzE,SAAS,CACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EACrB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI;IAOxC,OAAO,CACL,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI;IAOxC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI;IAQxD,eAAe;IAKf,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAKvD,aAAa,CAAC,GAAG,EAAE,KAAK;IAIxB,kBAAkB;IAKlB,SAAS;IAMT,iBAAiB;CAGlB;AAKD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAKnE;AAGD,wBAAgB,aAAa,IAAI,cAAc,GAAG,IAAI,CAErD;AAGD,wBAAgB,SAAS,SAExB;;;;;;AAED,wBAAqD"}

package/dist/src/__mocks__/mqtt.js

@@ -38,6 +38,11 @@ export class MockMqttClient extends EventEmitter {
         this.connected = false;
         this.emit("close");
     }
+    reconnect() {
+        this.emit("reconnect");
+        setTimeout(() => this.simulateConnect(), 10);
+        return this;
+    }
     simulateReconnect() {
         this.emit("reconnect");
     }

package/dist/src/channel.js

@@ -67,12 +67,12 @@ export const mqttPlugin = {
     gateway: {
         startAccount: async (ctx) => {
             const { cfg, account, accountId, abortSignal, log } = ctx;
-            const runtime = getMqttRuntime();
             const mqtt = cfg.channels?.mqtt;
             if (!mqtt?.brokerUrl) {
                 log?.debug?.("MQTT channel not configured, skipping");
                 return;
             }
+            const runtime = getMqttRuntime();
             log?.info?.(`[${accountId}] starting MQTT provider (${mqtt.brokerUrl})`);
             // Create and connect client
             mqttClient = createMqttClient(mqtt, {
@@ -85,8 +85,7 @@ export const mqttPlugin = {
                 await mqttClient.connect();
             }
             catch (err) {
-                log?.error?.(`MQTT connection failed: ${err}`);
-                throw err;
+                log?.error?.(`MQTT connection failed (will keep retrying): ${err}`);
             }
             // Subscribe to inbound topic
             const inboundTopic = mqtt.topics?.inbound ?? "openclaw/inbound";
@@ -145,6 +144,7 @@ async function handleInboundMessage(opts) {
         // Extract message body and sender from payload
         let messageBody;
         let senderId;
+        let correlationId;
         if (parsedPayload && typeof parsedPayload === "object") {
             messageBody =
                 parsedPayload.message ??
@@ -160,6 +160,10 @@ async function handleInboundMessage(opts) {
                     parsedPayload.from ??
                     parsedPayload.service ??
                     topic.replace(/\//g, "-");
+            correlationId =
+                parsedPayload.correlationId ??
+                    parsedPayload.requestId ??
+                    undefined;
         }
         else {
             messageBody = text;
@@ -203,6 +207,7 @@ async function handleInboundMessage(opts) {
                                 text: payload.text,
                                 kind: info.kind,
                                 ts: Date.now(),
+                                ...(correlationId ? { correlationId } : {}),
                             });
                             await mqttClient.publish(outboundTopic, outboundPayload, qos);
                             log?.info?.(`MQTT: sent reply to ${outboundTopic}`);

package/dist/src/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,MAAM,WAAW,iBAAiB;IAChC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxD,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtE,UAAU,MAAM;IACd,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAKD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,EAC9B,MAAM,EAAE,MAAM,GACb,iBAAiB,CAoLnB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,MAAM,WAAW,iBAAiB;IAChC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxD,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtE,UAAU,MAAM;IACd,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,EAC9B,MAAM,EAAE,MAAM,GACb,iBAAiB,CA4QnB"}

package/dist/src/client.js

@@ -2,6 +2,8 @@ import mqtt from "mqtt";
 import { mergeWithEnv } from "./env.js";
 const DEFAULT_RECONNECT_MS = 5000;
 const MAX_RECONNECT_MS = 60000;
+const INITIAL_CONNECT_GRACE_MS = 5000;
+const RECONNECT_JITTER = 0.2;
 /**
  * MQTT Client Manager
  *
@@ -12,12 +14,15 @@ export function createMqttClient(rawConfig, logger) {
     let client = null;
     let messageHandlers = new Map();
     let reconnectAttempts = 0;
+    let reconnectTimer = null;
+    let connectPromise = null;
+    let manualDisconnect = false;
     function getClientOptions() {
         const options = {
             clientId: config.clientId ?? `openclaw-${Math.random().toString(36).slice(2, 10)}`,
             clean: true,
             connectTimeout: 10000,
-            reconnectPeriod: DEFAULT_RECONNECT_MS,
+            reconnectPeriod: 0,
         };
         // Auth
         if (config.username) {
@@ -36,80 +41,156 @@ export function createMqttClient(rawConfig, logger) {
         }
         return options;
     }
+    function clearReconnectTimer() {
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+    }
+    function getBackoffDelay(attempt) {
+        const base = Math.min(DEFAULT_RECONNECT_MS * Math.pow(2, Math.max(0, attempt - 1)), MAX_RECONNECT_MS);
+        const jitter = base * RECONNECT_JITTER * Math.random();
+        return Math.round(base + jitter);
+    }
+    function scheduleReconnect(reason) {
+        if (manualDisconnect)
+            return;
+        if (reconnectTimer)
+            return;
+        reconnectAttempts += 1;
+        const delay = getBackoffDelay(reconnectAttempts);
+        logger.warn(`MQTT reconnect scheduled in ${delay}ms (${reason})`);
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            if (manualDisconnect)
+                return;
+            if (!client) {
+                connect().catch((err) => logger.error(`MQTT reconnect failed: ${err}`));
+                return;
+            }
+            try {
+                logger.info("MQTT reconnecting...");
+                client.reconnect();
+            }
+            catch (err) {
+                logger.error(`MQTT reconnect error: ${err}`);
+                scheduleReconnect("reconnect error");
+            }
+        }, delay);
+    }
+    function attachClientHandlers(activeClient) {
+        activeClient.on("connect", () => {
+            logger.info("MQTT connected");
+            reconnectAttempts = 0;
+            clearReconnectTimer();
+            // Resubscribe to all topics
+            for (const topic of messageHandlers.keys()) {
+                activeClient.subscribe(topic, { qos: config.qos }, (err) => {
+                    if (err) {
+                        logger.error(`Failed to subscribe to ${topic}: ${err.message}`);
+                    }
+                    else {
+                        logger.debug(`Subscribed to ${topic}`);
+                    }
+                });
+            }
+        });
+        activeClient.on("message", (topic, payload) => {
+            logger.debug(`Received message on ${topic}: ${payload.length} bytes`);
+            const handlers = [...(messageHandlers.get(topic) ?? [])];
+            // Also check wildcard subscriptions (skip exact match to avoid duplicates)
+            for (const [pattern, patternHandlers] of messageHandlers) {
+                if (pattern === topic)
+                    continue;
+                if (topicMatches(pattern, topic)) {
+                    handlers.push(...patternHandlers);
+                }
+            }
+            for (const handler of handlers) {
+                try {
+                    handler(topic, payload);
+                }
+                catch (err) {
+                    logger.error(`Message handler error: ${err}`);
+                }
+            }
+        });
+        activeClient.on("error", (err) => {
+            logger.error(`MQTT error: ${err.message}`);
+            scheduleReconnect("error");
+        });
+        activeClient.on("close", () => {
+            logger.warn("MQTT connection closed");
+            scheduleReconnect("close");
+        });
+        activeClient.on("reconnect", () => {
+            logger.info("MQTT reconnect event");
+        });
+        activeClient.on("offline", () => {
+            logger.warn("MQTT client offline");
+            scheduleReconnect("offline");
+        });
+    }
     async function connect() {
         if (client?.connected) {
             logger.debug("MQTT already connected");
             return;
         }
-        return new Promise((resolve, reject) => {
+        if (connectPromise) {
+            return connectPromise;
+        }
+        manualDisconnect = false;
+        if (!client) {
             logger.info(`Connecting to MQTT broker: ${config.brokerUrl}`);
             const options = getClientOptions();
             client = mqtt.connect(config.brokerUrl, options);
-            client.on("connect", () => {
-                logger.info("MQTT connected");
-                reconnectAttempts = 0;
-                // Resubscribe to all topics
-                for (const topic of messageHandlers.keys()) {
-                    client?.subscribe(topic, { qos: config.qos }, (err) => {
-                        if (err) {
-                            logger.error(`Failed to subscribe to ${topic}: ${err.message}`);
-                        }
-                        else {
-                            logger.debug(`Subscribed to ${topic}`);
-                        }
-                    });
-                }
+            attachClientHandlers(client);
+        }
+        else {
+            logger.info("MQTT connect requested; reconnecting existing client");
+            try {
+                client.reconnect();
+            }
+            catch (err) {
+                logger.error(`MQTT reconnect error: ${err}`);
+                scheduleReconnect("reconnect error");
+            }
+        }
+        connectPromise = new Promise((resolve) => {
+            let settled = false;
+            const settle = () => {
+                if (settled)
+                    return;
+                settled = true;
+                connectPromise = null;
                 resolve();
+            };
+            if (client?.connected) {
+                settle();
+                return;
+            }
+            const timer = setTimeout(() => {
+                logger.warn(`MQTT initial connect not ready after ${INITIAL_CONNECT_GRACE_MS}ms; continuing retries in background`);
+                settle();
+            }, INITIAL_CONNECT_GRACE_MS);
+            client?.once("connect", () => {
+                clearTimeout(timer);
+                settle();
             });
-            client.on("message", (topic, payload) => {
-                logger.debug(`Received message on ${topic}: ${payload.length} bytes`);
-                const handlers = [...(messageHandlers.get(topic) ?? [])];
-                // Also check wildcard subscriptions (skip exact match to avoid duplicates)
-                for (const [pattern, patternHandlers] of messageHandlers) {
-                    if (pattern === topic)
-                        continue;
-                    if (topicMatches(pattern, topic)) {
-                        handlers.push(...patternHandlers);
-                    }
-                }
-                for (const handler of handlers) {
-                    try {
-                        handler(topic, payload);
-                    }
-                    catch (err) {
-                        logger.error(`Message handler error: ${err}`);
-                    }
-                }
-            });
-            client.on("error", (err) => {
-                logger.error(`MQTT error: ${err.message}`);
-                reject(err);
-            });
-            client.on("close", () => {
-                logger.warn("MQTT connection closed");
-            });
-            client.on("reconnect", () => {
-                reconnectAttempts++;
-                const backoff = Math.min(DEFAULT_RECONNECT_MS * Math.pow(2, reconnectAttempts), MAX_RECONNECT_MS);
-                logger.info(`MQTT reconnecting (attempt ${reconnectAttempts}, backoff ${backoff}ms)`);
-            });
-            client.on("offline", () => {
-                logger.warn("MQTT client offline");
-            });
-            // Timeout for initial connection
-            setTimeout(() => {
-                if (!client?.connected) {
-                    reject(new Error("MQTT connection timeout"));
-                }
-            }, 15000);
         });
+        return connectPromise;
     }
     async function disconnect() {
         if (!client)
             return;
+        manualDisconnect = true;
+        clearReconnectTimer();
+        reconnectAttempts = 0;
+        connectPromise = null;
         return new Promise((resolve) => {
             logger.info("Disconnecting from MQTT broker");
             client?.end(false, {}, () => {
+                client?.removeAllListeners();
                 client = null;
                 messageHandlers.clear();
                 logger.info("MQTT disconnected");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turquoisebay/mqtt",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "MQTT channel plugin for OpenClaw - bidirectional messaging via MQTT brokers",
   "type": "module",
   "main": "dist/index.js",