@turquoisebay/mqtt 0.1.13

package/.env.example

@@ -0,0 +1,10 @@
+# MQTT Configuration (optional - can also use openclaw.json)
+# These override config file values
+
+MQTT_BROKER_URL=mqtt://localhost:1883
+MQTT_USERNAME=openclaw
+MQTT_PASSWORD=your-secret-password
+MQTT_CLIENT_ID=openclaw-agent
+
+# TLS (optional)
+# MQTT_CA_PATH=/path/to/ca.crt

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+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.13] - 2026-02-03
+
+### Fixed
+- Rename npm package to `@turquoisebay/mqtt` so install id matches `mqtt`
+
+## [0.1.12] - 2026-02-03
+
+### Fixed
+- Set plugin id to `mqtt` to align with channel id and auto-enable/doctor checks
+
+## [0.1.11] - 2026-02-03
+
+### Changed
+- Simplified MQTT inbound handling and reduced debug noise
+- Publish agent replies to outbound as JSON payloads
+- Align plugin id with manifest/config (`openclaw-mqtt`)
+
+## [0.1.10] - 2026-02-03
+
+### Fixed
+- Align plugin id with channel id (`mqtt`) to satisfy OpenClaw doctor auto-enable checks
+
+## [0.1.9] - 2026-02-01
+
+### Changed
+- Complete rewrite based on Telegram channel architecture analysis
+- Use `finalizeInboundContext` for proper inbound message formatting
+- Use `dispatchReplyWithBufferedBlockDispatcher` for full agent processing
+- Replies are sent back via MQTT outbound topic
+- Each MQTT sender gets their own session (mqtt:{senderId})
+
+## [0.1.8] - 2026-02-01
+
+### Fixed
+- Use `enqueueSystemEvent` for message injection (simpler, more reliable)
+- Removed complex debouncer that required additional params
+
+## [0.1.7] - 2026-02-01
+
+### Fixed
+- Use `gateway.startAccount` instead of `gateway.start` (correct OpenClaw plugin API)
+- Use `createInboundDebouncer` for proper message injection
+- Add `isEnabled` and `isConfigured` config methods
+- Return promise that resolves on abort for clean shutdown
+
+## [0.1.6] - 2026-02-01
+
+### Fixed
+- Plugin id changed from `mqtt` to `openclaw-mqtt` to match install directory name
+- Fixes "plugin not found" error during install
+
+## [0.1.5] - 2026-02-01
+
+### Added
+- Onboarding adapter for `openclaw configure channels` support
+- Interactive setup prompts for broker URL, auth, topics, QoS, TLS
+
+## [0.1.4] - 2026-02-01
+
+### Fixed
+- Package now ships pre-built JS files (consumers no longer need to compile)
+- Added `files` field to package.json for clean npm publishing
+- Added type declarations for openclaw/plugin-sdk (SDK doesn't ship .d.ts yet)
+- Fixed implicit `any` type errors in channel.ts
+
+### Changed
+- `main` now points to `dist/index.js` instead of `index.ts`
+- `openclaw.extensions` updated to reference compiled output
+- Added `prepublishOnly` script to ensure build before publish
+
+## [Unreleased]
+
+### TODO
+- [ ] TLS certificate file loading
+- [ ] Integration tests with Mosquitto container
+- [ ] GitHub Actions CI
+- [ ] Last Will and Testament support
+- [ ] Multiple topic subscriptions
+
+## [0.1.0] - Unreleased
+
+### Added
+- Initial project scaffold
+- Plugin manifest (`openclaw.plugin.json`)
+- Config schema with Zod validation
+- Channel plugin structure following OpenClaw conventions
+- README with installation and usage docs
+- TypeScript configuration
+- MQTT client manager with connection lifecycle
+- Subscribe to inbound topic, inject messages to OpenClaw
+- Publish to outbound topic via sendText
+- Reconnection with exponential backoff
+- MQTT wildcard support (+ and #)
+- Environment variable support for secrets
+- JSON message parsing for structured alerts
+- Unit tests for topic matching and config merge

package/README.md

@@ -0,0 +1,157 @@
+# @turquoisebay/mqtt
+
+[![CI](https://github.com/hughmadden/openclaw-mqtt/actions/workflows/ci.yml/badge.svg)](https://github.com/hughmadden/openclaw-mqtt/actions)
+[![npm](https://img.shields.io/npm/v/@turquoisebay/mqtt)](https://www.npmjs.com/package/@turquoisebay/mqtt)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MQTT channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) — bidirectional messaging via MQTT brokers.
+
+## Features
+
+- 🔌 **Bidirectional messaging** — subscribe and publish to MQTT topics
+- 🏠 **Home automation ready** — integrates with Home Assistant, Mosquitto, EMQX
+- 🔒 **TLS support** — secure connections to cloud brokers
+- 📊 **Service monitoring** — receive alerts from Uptime Kuma, healthchecks, etc.
+- ⚡ **QoS levels** — configurable delivery guarantees (0, 1, 2)
+
+## Installation
+
+```bash
+openclaw plugins install @turquoisebay/mqtt
+```
+
+Or manually:
+
+```bash
+git clone https://github.com/hughmadden/openclaw-mqtt ~/.openclaw/extensions/mqtt
+cd ~/.openclaw/extensions/mqtt && npm install
+```
+
+## Configuration
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  channels: {
+    mqtt: {
+      brokerUrl: "mqtt://localhost:1883",
+      // Optional auth
+      username: "openclaw",
+      password: "secret",
+      // Topics
+      topics: {
+        inbound: "openclaw/inbound",   // Subscribe to this
+        outbound: "openclaw/outbound"  // Publish responses here
+      },
+      // Quality of Service (0=fire-and-forget, 1=at-least-once, 2=exactly-once)
+      qos: 1
+    }
+  }
+}
+```
+
+Then restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+## Usage
+
+### Receiving messages (inbound)
+
+Messages published to your `inbound` topic will be processed by OpenClaw.
+You can send either plain text or JSON (recommended):
+
+```bash
+# Plain text
+mosquitto_pub -t "openclaw/inbound" -m "Alert: Service down on playground"
+
+# JSON (recommended)
+mosquitto_pub -t "openclaw/inbound" -m '{"senderId":"pg-cli","text":"hello"}'
+```
+
+### Sending messages (outbound)
+
+Agent replies are published to the `outbound` topic as JSON:
+
+```json
+{"senderId":"openclaw","text":"...","kind":"final","ts":1700000000000}
+```
+
+If you want to publish custom text via CLI, use the `message` tool:
+
+```bash
+openclaw agent --message "Send MQTT: Temperature is 23°C"
+```
+
+## Use Cases
+
+### Service Monitoring
+
+Pair with [Uptime Kuma](https://github.com/louislam/uptime-kuma) to receive alerts:
+
+1. Configure Uptime Kuma notification → MQTT
+2. Set topic to `openclaw/inbound`
+3. OpenClaw receives and can act on alerts
+
+### Home Assistant Integration
+
+```yaml
+# Home Assistant configuration.yaml
+mqtt:
+  sensor:
+    - name: "OpenClaw Status"
+      state_topic: "openclaw/outbound"
+  
+automation:
+  - trigger:
+      platform: mqtt
+      topic: "home/alerts"
+    action:
+      service: mqtt.publish
+      data:
+        topic: "openclaw/inbound"
+        payload: "{{ trigger.payload }}"
+```
+
+## Development
+
+```bash
+# Clone
+git clone turq@10.0.20.9:/opt/git/openclaw-mqtt.git
+cd openclaw-mqtt
+
+# Install deps
+npm install
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+## Architecture
+
+```
+MQTT Broker (Mosquitto/EMQX)
+     │
+     ├─► inbound topic ──► OpenClaw Gateway ──► Agent
+     │
+     └─◄ outbound topic ◄── OpenClaw Gateway ◄── Agent
+```
+
+## License
+
+MIT © Hugh Madden
+
+## See Also
+
+- [OpenClaw](https://github.com/openclaw/openclaw) — The AI assistant platform
+- [MQTT.js](https://github.com/mqttjs/MQTT.js) — MQTT client library
+- [Mosquitto](https://mosquitto.org/) — Popular MQTT broker

package/config.example.json

@@ -0,0 +1,18 @@
+{
+  "channels": {
+    "mqtt": {
+      "brokerUrl": "mqtt://localhost:1883",
+      "username": "your-username",
+      "password": "YOUR_PASSWORD_HERE",
+      "clientId": "openclaw-agent",
+      "topics": {
+        "inbound": "openclaw/inbound",
+        "outbound": "openclaw/outbound"
+      },
+      "qos": 1,
+      "tls": {
+        "enabled": false
+      }
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: any;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,QAAA,MAAM,MAAM;;;;;kBAKI,iBAAiB;CAIhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { mqttPlugin } from "./src/channel.js";
+import { setMqttRuntime } from "./src/runtime.js";
+const plugin = {
+    id: "mqtt",
+    name: "MQTT",
+    description: "MQTT channel plugin for IoT and home automation integration",
+    configSchema: emptyPluginConfigSchema(),
+    register(api) {
+        setMqttRuntime(api.runtime);
+        api.registerChannel({ plugin: mqttPlugin });
+    },
+};
+export default plugin;

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

@@ -0,0 +1,35 @@
+import { EventEmitter } from "events";
+/**
+ * Mock MQTT Client for testing
+ */
+export declare class MockMqttClient extends EventEmitter {
+    connected: boolean;
+    subscriptions: Map<string, {
+        qos: number;
+    }>;
+    published: Array<{
+        topic: string;
+        message: string;
+        opts: unknown;
+    }>;
+    subscribe(topic: string, opts: {
+        qos: number;
+    }, callback?: (err: Error | null) => void): this;
+    publish(topic: string, message: string, opts: unknown, callback?: (err: Error | null) => void): this;
+    end(force: boolean, opts: unknown, callback?: () => void): this;
+    simulateConnect(): void;
+    simulateMessage(topic: string, payload: Buffer | string): void;
+    simulateError(err: Error): void;
+    simulateDisconnect(): void;
+    simulateReconnect(): void;
+}
+export declare function connect(url: string, opts?: unknown): MockMqttClient;
+export declare function getMockClient(): MockMqttClient | null;
+export declare function resetMock(): void;
+declare const _default: {
+    connect: typeof connect;
+    getMockClient: typeof getMockClient;
+    resetMock: typeof resetMock;
+};
+export default _default;
+//# sourceMappingURL=mqtt.d.ts.map

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

@@ -0,0 +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"}

package/dist/src/__mocks__/mqtt.js

@@ -0,0 +1,61 @@
+import { EventEmitter } from "events";
+/**
+ * Mock MQTT Client for testing
+ */
+export class MockMqttClient extends EventEmitter {
+    connected = false;
+    subscriptions = new Map();
+    published = [];
+    subscribe(topic, opts, callback) {
+        this.subscriptions.set(topic, opts);
+        callback?.(null);
+        return this;
+    }
+    publish(topic, message, opts, callback) {
+        this.published.push({ topic, message, opts });
+        callback?.(null);
+        return this;
+    }
+    end(force, opts, callback) {
+        this.connected = false;
+        this.subscriptions.clear();
+        callback?.();
+        return this;
+    }
+    // Test helpers
+    simulateConnect() {
+        this.connected = true;
+        this.emit("connect");
+    }
+    simulateMessage(topic, payload) {
+        const buf = typeof payload === "string" ? Buffer.from(payload) : payload;
+        this.emit("message", topic, buf);
+    }
+    simulateError(err) {
+        this.emit("error", err);
+    }
+    simulateDisconnect() {
+        this.connected = false;
+        this.emit("close");
+    }
+    simulateReconnect() {
+        this.emit("reconnect");
+    }
+}
+// Factory function that returns mock client
+let mockClient = null;
+export function connect(url, opts) {
+    mockClient = new MockMqttClient();
+    // Auto-connect after short delay to simulate async connection
+    setTimeout(() => mockClient?.simulateConnect(), 10);
+    return mockClient;
+}
+// Test helper to get current mock client
+export function getMockClient() {
+    return mockClient;
+}
+// Reset between tests
+export function resetMock() {
+    mockClient = null;
+}
+export default { connect, getMockClient, resetMock };

package/dist/src/channel.d.ts

@@ -0,0 +1,10 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import type { MqttCoreConfig } from "./types.js";
+/**
+ * MQTT Channel Plugin for OpenClaw
+ *
+ * Provides bidirectional messaging via MQTT brokers (Mosquitto, EMQX, etc.)
+ * Useful for IoT integration, home automation alerts, and service monitoring.
+ */
+export declare const mqttPlugin: ChannelPlugin<MqttCoreConfig>;
+//# sourceMappingURL=channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAQjD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,aAAa,CAAC,cAAc,CAoIpD,CAAC"}

package/dist/src/channel.js

@@ -0,0 +1,235 @@
+import { createMqttClient } from "./client.js";
+import { mqttOnboardingAdapter } from "./onboarding.js";
+import { getMqttRuntime } from "./runtime.js";
+// Global client instance (one per gateway lifecycle)
+let mqttClient = null;
+/**
+ * MQTT Channel Plugin for OpenClaw
+ *
+ * Provides bidirectional messaging via MQTT brokers (Mosquitto, EMQX, etc.)
+ * Useful for IoT integration, home automation alerts, and service monitoring.
+ */
+export const mqttPlugin = {
+    id: "mqtt",
+    meta: {
+        id: "mqtt",
+        label: "MQTT",
+        selectionLabel: "MQTT (IoT/Home Automation)",
+        docsPath: "/channels/mqtt",
+        blurb: "Bidirectional messaging via MQTT brokers",
+        aliases: ["mosquitto"],
+    },
+    capabilities: {
+        chatTypes: ["direct"],
+        supportsMedia: false,
+        supportsReactions: false,
+        supportsThreads: false,
+    },
+    config: {
+        listAccountIds: (cfg) => {
+            return cfg.channels?.mqtt?.brokerUrl ? ["default"] : [];
+        },
+        resolveAccount: (cfg, accountId) => {
+            const mqtt = cfg.channels?.mqtt;
+            if (!mqtt)
+                return { accountId: accountId ?? "default", enabled: false };
+            return {
+                accountId: accountId ?? "default",
+                enabled: mqtt.enabled !== false,
+                brokerUrl: mqtt.brokerUrl,
+                config: mqtt,
+            };
+        },
+        isEnabled: (account) => account.enabled !== false,
+        isConfigured: (account) => Boolean(account.brokerUrl),
+    },
+    outbound: {
+        deliveryMode: "direct",
+        async sendText({ text, cfg }) {
+            const mqtt = cfg.channels?.mqtt;
+            if (!mqtt?.brokerUrl) {
+                return { ok: false, error: "MQTT not configured" };
+            }
+            if (!mqttClient || !mqttClient.isConnected()) {
+                return { ok: false, error: "MQTT not connected" };
+            }
+            try {
+                const topic = mqtt.topics?.outbound ?? "openclaw/outbound";
+                await mqttClient.publish(topic, text, mqtt.qos);
+                return { ok: true };
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                return { ok: false, error };
+            }
+        },
+    },
+    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;
+            }
+            log?.info?.(`[${accountId}] starting MQTT provider (${mqtt.brokerUrl})`);
+            // Create and connect client
+            mqttClient = createMqttClient(mqtt, {
+                debug: (msg) => log?.debug?.(`[MQTT] ${msg}`),
+                info: (msg) => log?.info?.(`[MQTT] ${msg}`),
+                warn: (msg) => log?.warn?.(`[MQTT] ${msg}`),
+                error: (msg) => log?.error?.(`[MQTT] ${msg}`),
+            });
+            try {
+                await mqttClient.connect();
+            }
+            catch (err) {
+                log?.error?.(`MQTT connection failed: ${err}`);
+                throw err;
+            }
+            // Subscribe to inbound topic
+            const inboundTopic = mqtt.topics?.inbound ?? "openclaw/inbound";
+            const outboundTopic = mqtt.topics?.outbound ?? "openclaw/outbound";
+            mqttClient.subscribe(inboundTopic, async (topic, payload) => {
+                await handleInboundMessage({
+                    topic,
+                    payload,
+                    runtime,
+                    cfg,
+                    accountId,
+                    log,
+                    outboundTopic,
+                    qos: mqtt.qos,
+                });
+            });
+            log?.info?.(`[${accountId}] MQTT channel ready, subscribed to ${inboundTopic}`);
+            // Return a promise that resolves when aborted
+            return new Promise((resolve) => {
+                const cleanup = () => {
+                    if (mqttClient) {
+                        log?.info?.(`[${accountId}] MQTT channel stopping`);
+                        mqttClient.disconnect().finally(() => {
+                            mqttClient = null;
+                            resolve();
+                        });
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+                if (abortSignal) {
+                    abortSignal.addEventListener("abort", cleanup, { once: true });
+                }
+            });
+        },
+    },
+    onboarding: mqttOnboardingAdapter,
+};
+/**
+ * Handle inbound MQTT message - process through OpenClaw agent and deliver reply
+ */
+async function handleInboundMessage(opts) {
+    const { topic, payload, runtime, cfg, accountId, log, outboundTopic, qos } = opts;
+    try {
+        const text = payload.toString("utf-8");
+        log?.info?.(`Inbound MQTT message on ${topic}: ${text.slice(0, 200)}${text.length > 200 ? "..." : ""}`);
+        // Parse JSON if possible to extract structured data
+        let parsedPayload = null;
+        try {
+            parsedPayload = JSON.parse(text);
+        }
+        catch {
+            parsedPayload = null;
+        }
+        // Extract message body and sender from payload
+        let messageBody;
+        let senderId;
+        if (parsedPayload && typeof parsedPayload === "object") {
+            messageBody =
+                parsedPayload.message ??
+                    parsedPayload.text ??
+                    parsedPayload.msg ??
+                    parsedPayload.alert ??
+                    parsedPayload.body ??
+                    text;
+            senderId =
+                parsedPayload.senderId ??
+                    parsedPayload.source ??
+                    parsedPayload.sender ??
+                    parsedPayload.from ??
+                    parsedPayload.service ??
+                    topic.replace(/\//g, "-");
+        }
+        else {
+            messageBody = text;
+            senderId = topic.replace(/\//g, "-");
+        }
+        // Build the inbound context using OpenClaw's standard format
+        const ctxPayload = runtime.channel.reply.finalizeInboundContext({
+            Body: messageBody,
+            RawBody: text,
+            CommandBody: messageBody,
+            CommandAuthorized: true,
+            From: `mqtt:${senderId}`,
+            To: `mqtt:${accountId}`,
+            SessionKey: `agent:main:mqtt:${senderId}`,
+            AccountId: accountId,
+            ChatType: "direct",
+            ConversationLabel: `mqtt:${senderId}`,
+            SenderName: senderId,
+            SenderId: senderId,
+            Provider: "mqtt",
+            Surface: "mqtt",
+            MessageSid: `mqtt-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+            Timestamp: Date.now(),
+        });
+        // inbound context logging removed
+        // Dispatch through OpenClaw's reply system and publish replies
+        await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: ctxPayload,
+            cfg,
+            dispatcherOptions: {
+                deliver: async (payload, info) => {
+                    if (!payload.text) {
+                        log?.debug?.(`MQTT: skipping empty ${info.kind} reply`);
+                        return;
+                    }
+                    log?.info?.(`MQTT reply (${info.kind}) [${payload.text.length} chars]`);
+                    if (mqttClient?.isConnected()) {
+                        try {
+                            const outboundPayload = JSON.stringify({
+                                senderId: "openclaw",
+                                text: payload.text,
+                                kind: info.kind,
+                                ts: Date.now(),
+                            });
+                            await mqttClient.publish(outboundTopic, outboundPayload, qos);
+                            log?.info?.(`MQTT: sent reply to ${outboundTopic}`);
+                        }
+                        catch (err) {
+                            log?.error?.(`MQTT: failed to send reply: ${err}`);
+                        }
+                    }
+                    else {
+                        log?.warn?.(`MQTT: not connected, cannot send reply`);
+                    }
+                },
+                onSkip: (_payload, info) => {
+                    log?.debug?.(`MQTT: skipped reply (${info.reason})`);
+                },
+                onError: (err, info) => {
+                    log?.error?.(`MQTT: ${info.kind} reply error: ${err}`);
+                },
+            },
+            replyOptions: {
+                disableBlockStreaming: true,
+            },
+        });
+        // dispatch complete
+        log?.info?.(`MQTT message processed from ${senderId}`);
+    }
+    catch (err) {
+        log?.error?.(`Failed to process MQTT message: ${err}`);
+    }
+}