@turquoisebay/mqtt 0.1.14 → 0.1.15

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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

package/README.md

@@ -60,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.
@@ -70,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/channel.js

@@ -144,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 ??
@@ -159,6 +160,10 @@ async function handleInboundMessage(opts) {
                     parsedPayload.from ??
                     parsedPayload.service ??
                     topic.replace(/\//g, "-");
+            correlationId =
+                parsedPayload.correlationId ??
+                    parsedPayload.requestId ??
+                    undefined;
         }
         else {
             messageBody = text;
@@ -202,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/package.json

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