feat(extensions): add mqtt-hooks plugin scaffold

[Will-Water]

Motivation

• Provide a lightweight, plugin-scoped MQTT Hooks integration so external MQTT events can be ingested into OpenClaw without polluting core dependencies.
• Focus the first iteration on semantic enrichment and simple dispatch (subscribe → explain → dispatch) rather than a rules/automation engine.

Description

• Add a new plugin scaffold under extensions/mqtt-hooks/ implementing connection, subscription, payload parsing, templating, and action dispatch to agent / wake / webhook (files: extensions/mqtt-hooks/index.ts, extensions/mqtt-hooks/openclaw.plugin.json, extensions/mqtt-hooks/README.md, extensions/mqtt-hooks/package.json).
• Implement simple topic matching, JSON payload auto-parse with string fallback, template rendering (renderTemplate), and a context-enriched fallback envelope builder (buildDefaultMessage) (see extensions/mqtt-hooks/index.ts).
• Dispatch logic uses the plugin runtime APIs to run a subagent (api.runtime.subagent.run), enqueue a system event / request heartbeat (api.runtime.system.enqueueSystemEvent / requestHeartbeatNow), or POST to an external webhook; concurrency bounding and per-message timeout protections are included.
• Load the mqtt runtime package via dynamic import and emit a clear runtime warning if mqtt is not installed to avoid failing pnpm install in locked-down environments, and add a labeler entry in .github/labeler.yml for the new extension.

Testing

• Ran unit tests for the new plugin with bunx vitest run extensions/mqtt-hooks/test/index.test.ts, and the test file passed (2 tests passed).
• Attempted pnpm build in this environment but it failed in an unrelated step (canvas:a2ui:bundle) that is not introduced by this change; the plugin code and its tests are unaffected.
• Note: runtime npm fetch for mqtt failed in this environment (403), so the plugin intentionally does a runtime dynamic import and logs if the package is absent.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 47de37e508

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Stop importing core src from npm plugin entry

This entrypoint hard-imports ../../src/routing/resolve-route.js, but plugin discovery loads extensions from their package directory (including npm-installed plugins under the extensions install root), so this relative path resolves outside the plugin package and becomes a module-not-found at startup in standalone installs. In practice, that prevents @openclaw/mqtt-hooks from loading when installed via the plugin installer.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Require sessionKey before enqueueing wake events

The wake path forwards sub.sessionKey directly into enqueueSystemEvent, but enqueueSystemEvent requires a non-empty session key and throws otherwise (requireSessionKey in src/infra/system-events.ts). Because sessionKey is optional in this plugin config, any wake subscription that omits it will fail on every message (and the subsequent heartbeat request is skipped due to the throw), so the wake action is effectively broken by default.

Useful? React with 👍 / 👎.