openclaw-threema 0.5.1 → 0.6.0

package/README.md

@@ -1,4 +1,4 @@
-# @openclaw/threema
+# openclaw-threema
 
 Threema Gateway channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) — privacy-focused E2E encrypted messaging via the [Threema Gateway API](https://gateway.threema.ch/).
 
@@ -8,24 +8,25 @@ Threema Gateway channel plugin for [OpenClaw](https://github.com/openclaw/opencl
 - **Media send/receive** — images, files, audio (E2E encrypted blobs)
 - **Voice transcription** — automatic speech-to-text via local Whisper
 - **Instant wake** — webhook-based message delivery (no polling)
+- **Slash commands** — `/status`, `/compact`, etc. work natively via Threema (v0.6.0+)
 - **CLI tools** — `openclaw threema send|send-file|status|keygen`
 
 ## Requirements
 
 - A [Threema Gateway](https://gateway.threema.ch/) account (E2E mode)
-- OpenClaw v0.30+ with channel plugin support
+- OpenClaw 2026.3.2+ with channel plugin support
 - For voice transcription: [OpenAI Whisper](https://github.com/openai/whisper) installed locally
 
-Please keep in mind that the use of the Threema Gateway is not for free.
-At the time of writing these lines you have to pay 1.600 "Credits" to get an ID. 
-Every Message costs another Credit (roughly EUR 0,02).
-2.500 Credits are about EUR 55,00
+> **Note:** Threema Gateway usage is not free. At the time of writing, you need ~1,600 credits to register a Gateway ID, and each message costs 1 credit (~€0.02). 2,500 credits cost approximately €55.
 
 ## Installation
 
 ```bash
-# From npm (when published)
-npm install @openclaw/threema
+# From npm
+npm install openclaw-threema
+
+# From ClawHub
+openclaw plugins install clawhub:threema
 
 # Or as a local extension
 cp -r . ~/.openclaw/extensions/threema/
@@ -77,7 +78,7 @@ https://your-host:18789/threema/webhook
 
 The default port is `18789` (OpenClaw Gateway). The path matches `webhookPath` in your config (default: `/threema/webhook`).
 
-**Note:** If you're behind a reverse proxy, adjust the URL accordingly. The plugin registers the endpoint at the configured `webhookPath`.
+**Note:** If you're behind a reverse proxy (Cloudflare Tunnel, nginx, etc.), adjust the URL accordingly. The plugin registers the endpoint at the configured `webhookPath`.
 
 ### 3. Restart OpenClaw
 
@@ -96,7 +97,7 @@ openclaw threema send ABCD1234 "Hello from OpenClaw!"
 
 | Policy | Description |
 |--------|-------------|
-| `allowlist` | Only IDs in `allowFrom` array (default) |
+| `allowlist` | Only IDs in `allowFrom` array (default, recommended) |
 | `open` | Accept from anyone |
 | `disabled` | Reject all DMs |
 
@@ -104,7 +105,7 @@ openclaw threema send ABCD1234 "Hello from OpenClaw!"
 
 When a voice message is received, the plugin automatically transcribes it using local Whisper (no API key needed). The transcription is included in the message delivered to the agent.
 
-Whisper must be installed and accessible in PATH (e.g., via `pip install openai-whisper` or Homebrew).
+Whisper must be installed and accessible in PATH (e.g., `pip install openai-whisper`).
 
 ## Message Types Supported
 
@@ -119,8 +120,26 @@ Whisper must be installed and accessible in PATH (e.g., via `pip install openai-
 - Private keys never leave the host
 - Webhook verification via HMAC-SHA256 (mandatory, verified before decryption)
 - SSRF protection: redirect blocking, DNS rebinding checks, private IP filtering
+- Secrets are redacted in all log output
+
+## Changelog
+
+### v0.6.0 (2026-04-17)
+- **Channel Inbound Pipeline** — messages now go through OpenClaw's native channel pipeline instead of raw `enqueueSystemEvent`. This enables slash commands (`/status`, `/compact`, etc.) directly from Threema.
+- **Graceful fallback** — automatically falls back to `enqueueSystemEvent` if the channel pipeline is unavailable (e.g., older OpenClaw versions).
+- **Long message chunking** — replies exceeding 3,500 chars are split at newline boundaries.
+
+### v0.5.2 (2026-03-30)
+- OpenClaw 2026.3.2 compatibility fixes
+- Health monitor improvements
+- ClawHub publishing support (`compat.pluginApi`, `build.openclawVersion`)
+
+### v0.4.5 (2026-02-17)
+- Initial npm release
+- Full E2E text + media support
+- Voice transcription via Whisper
+- Security hardening (SSRF protection, path restrictions, PII log reduction)
 
 ## License
 
 MIT
-

package/index.ts

@@ -1109,6 +1109,28 @@ function getMimeFromPath(filePath: string): string {
 // Channel Plugin Definition
 // ============================================================================
 
+// Shared status updater — allows the webhook handler (registered outside the
+// channel adapter) to update the channel's health-monitor status on inbound events.
+// startAccount populates this; the webhook handler calls updateActivity().
+const channelStatus = {
+  _getStatus: null as (() => ChannelAccountSnapshot) | null,
+  _setStatus: null as ((s: ChannelAccountSnapshot) => void) | null,
+  bind(getStatus: () => ChannelAccountSnapshot, setStatus: (s: ChannelAccountSnapshot) => void) {
+    this._getStatus = getStatus;
+    this._setStatus = setStatus;
+  },
+  updateActivity() {
+    if (this._getStatus && this._setStatus) {
+      const now = Date.now();
+      this._setStatus({
+        ...this._getStatus(),
+        lastEventAt: now,
+        lastInboundAt: now,
+      });
+    }
+  },
+};
+
 const threemaChannel = {
   id: "threema" as const,
 
@@ -1549,18 +1571,34 @@ const threemaChannel = {
         log?.info?.(`E2E public key: ${client.ownPublicKey}`);
       }
 
+      // Bind shared status so the webhook handler can report activity
+      channelStatus.bind(getStatus, setStatus);
+
       setStatus({
         ...getStatus(),
         running: true,
         connected: true,
         lastConnectedAt: Date.now(),
+        lastEventAt: Date.now(),
       });
 
+      // Periodic health heartbeat — update lastEventAt every 15 min so the
+      // health-monitor doesn't think we're stuck (webhook channels are passive).
+      const heartbeatInterval = setInterval(() => {
+        setStatus({
+          ...getStatus(),
+          lastEventAt: Date.now(),
+        });
+      }, 15 * 60 * 1000);
+
       // Keep the promise alive until abortSignal fires — resolving immediately
       // causes the gateway to treat the channel as "exited" and restart it.
       await new Promise<void>((resolve) => {
         if (abortSignal.aborted) return resolve();
-        abortSignal.addEventListener("abort", () => resolve(), { once: true });
+        abortSignal.addEventListener("abort", () => {
+          clearInterval(heartbeatInterval);
+          resolve();
+        }, { once: true });
       });
 
       log?.info?.("Threema Gateway stopped via abort signal");
@@ -1584,7 +1622,7 @@ const threemaChannel = {
 
 export const id = "threema";
 export const name = "Threema Gateway";
-export const version = "0.5.0";
+export const version = "0.6.0";
 export const description =
   "Threema messaging channel via Threema Gateway API (E2E encrypted, with media support)";
 
@@ -1594,6 +1632,12 @@ export default function register(api: any) {
     const threemaCfg = getThreemaConfig(config);
     const runtime = api.runtime;
 
+    // Store runtime reference for wakeAgent() to use requestHeartbeatNow
+    _runtimeApi = runtime;
+
+    // Debug: check if requestHeartbeatNow is available
+    api.logger?.info?.(`Threema wake API: runtime.system.requestHeartbeatNow=${typeof runtime?.system?.requestHeartbeatNow}`);
+
     // Register the channel plugin
     api.registerChannel({ plugin: threemaChannel });
     api.logger?.info?.("Threema channel plugin registered");
@@ -1606,17 +1650,16 @@ export default function register(api: any) {
     const dmPolicy = threemaCfg.dmPolicy ?? "allowlist";
     const allowFrom = threemaCfg.allowFrom ?? [];
 
-    // Use registerHttpHandler (not registerHttpRoute) so the webhook is NOT
-    // behind gateway auth — Threema's API needs to POST without our token.
-    // The webhook has its own MAC-based authentication.
-    api.registerHttpHandler?.(async (req: any, res: any): Promise<boolean> => {
-      const url = new URL(req.url ?? "/", "http://localhost");
-      if (url.pathname !== webhookPath) return false;
-
+    // Webhook handler — Threema's API POSTs without our gateway token,
+    // so we need an unauthenticated route. The webhook has its own MAC-based auth.
+    //
+    // Forward-compatible: use registerHttpRoute with auth:"none" (2026.3.2+),
+    // fall back to registerHttpHandler for 2026.3.1.
+    const webhookHandler = async (req: any, res: any): Promise<void> => {
       if (req.method !== "POST") {
         res.writeHead(405, { "Content-Type": "text/plain" });
         res.end("Method Not Allowed");
-        return true;
+        return;
       }
 
       try {
@@ -1669,11 +1712,13 @@ export default function register(api: any) {
             return;
           }
 
-          // 4. Validate date (not older than 10 minutes)
+          // 4. Validate date (not older than 60 minutes)
+          // Threema retries delivery on webhook errors, so messages can arrive late.
+          // 60 min is generous enough for retries while still rejecting stale replays.
           if (date) {
             const msgTimestamp = parseInt(date, 10) * 1000; // Convert to ms
             const now = Date.now();
-            const maxAge = 10 * 60 * 1000; // 10 minutes in ms
+            const maxAge = 60 * 60 * 1000; // 60 minutes in ms
             if (now - msgTimestamp > maxAge) {
               api.logger?.warn?.(`Threema webhook: message too old (date=${date})`);
               res.writeHead(400, { "Content-Type": "text/plain" });
@@ -1719,6 +1764,9 @@ export default function register(api: any) {
 
           // === PROCESSING PHASE ===
 
+          // Report activity to health-monitor (prevents "stuck" restarts)
+          channelStatus.updateActivity();
+
           // Decrypt the message
           const senderPubKey = await client.getPublicKey(from);
           const decrypted = client.decryptMessage(
@@ -1734,25 +1782,138 @@ export default function register(api: any) {
             api.logger?.info?.("Threema text message received");
             api.logger?.debug?.(`Threema text from=${from} messageId=${messageId}`);
 
-            // Dispatch to OpenClaw via enqueueSystemEvent
-            const enqueue = runtime?.system?.enqueueSystemEvent;
-            if (enqueue) {
-              const envelope = `[Threema message from ${senderLabel} (${from})]\n${decrypted.text}`;
-              enqueue(envelope, {
-                sessionKey: "agent:main:main",
-                deliveryContext: {
+            // Dispatch through the proper Channel Inbound Pipeline
+            // This enables slash-command parsing (/status, /compact, etc.)
+            const channelRuntime = runtime?.channel;
+            if (channelRuntime?.routing?.resolveAgentRoute && channelRuntime?.reply?.finalizeInboundContext && channelRuntime?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+              try {
+                const currentCfg = runtime.config.loadConfig();
+
+                // 1. Resolve the agent route and session key
+                const route = channelRuntime.routing.resolveAgentRoute({
+                  cfg: currentCfg,
                   channel: "threema",
-                  to: from,
-                  from: from,
                   accountId: "default",
-                },
-              });
-              api.logger?.info?.("Threema message dispatched via enqueueSystemEvent");
+                  peer: { kind: "direct", id: from },
+                });
 
-              // Wake the agent
-              wakeAgent(config);
+                const sessionKey = channelRuntime.routing.buildAgentSessionKey({
+                  agentId: route.agentId,
+                  channel: "threema",
+                  accountId: "default",
+                  peer: { kind: "direct", id: from },
+                  dmScope: "per-account-channel-peer",
+                });
+
+                // 2. Check if sender is command-authorized (in allowFrom list)
+                const senderAllowed = allowFrom.length === 0 || allowFrom.includes(from);
+
+                // 3. Build the finalized inbound context
+                const msgCtx = channelRuntime.reply.finalizeInboundContext({
+                  Body: decrypted.text,
+                  RawBody: decrypted.text,
+                  CommandBody: decrypted.text,
+                  From: `threema:${from}`,
+                  To: `threema:${ownGatewayId}`,
+                  SessionKey: sessionKey,
+                  AccountId: "default",
+                  OriginatingChannel: "threema",
+                  OriginatingTo: `threema:${from}`,
+                  ChatType: "direct" as const,
+                  SenderName: senderLabel,
+                  SenderId: from,
+                  Provider: "threema",
+                  Surface: "threema",
+                  ConversationLabel: senderLabel || from,
+                  Timestamp: Date.now(),
+                  CommandAuthorized: senderAllowed,
+                });
+
+                // 4. Dispatch through the full pipeline (command parsing + agent)
+                const replyClient = new ThreemaClient(getThreemaConfig(currentCfg)!);
+                await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+                  ctx: msgCtx,
+                  cfg: currentCfg,
+                  dispatcherOptions: {
+                    deliver: async (payload: any) => {
+                      const text = payload.text ?? payload.body;
+                      if (!text) return;
+                      // Chunk long replies if needed
+                      const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
+                      if (text.length <= limit) {
+                        if (replyClient.isE2EEnabled) {
+                          await replyClient.sendE2E(from, text);
+                        } else {
+                          await replyClient.sendSimple(from, text);
+                        }
+                      } else {
+                        // Split into chunks at newline boundaries
+                        const chunks: string[] = [];
+                        let remaining = text;
+                        while (remaining.length > 0) {
+                          if (remaining.length <= limit) {
+                            chunks.push(remaining);
+                            break;
+                          }
+                          let splitIdx = remaining.lastIndexOf("\n", limit);
+                          if (splitIdx <= 0) splitIdx = limit;
+                          chunks.push(remaining.slice(0, splitIdx));
+                          remaining = remaining.slice(splitIdx).replace(/^\n/, "");
+                        }
+                        for (const chunk of chunks) {
+                          if (replyClient.isE2EEnabled) {
+                            await replyClient.sendE2E(from, chunk);
+                          } else {
+                            await replyClient.sendSimple(from, chunk);
+                          }
+                        }
+                      }
+                    },
+                    onReplyStart: () => {
+                      api.logger?.info?.(`Threema: agent reply started for ${from}`);
+                    },
+                  },
+                });
+                api.logger?.info?.("Threema message dispatched via Channel Inbound Pipeline");
+              } catch (pipelineErr: any) {
+                api.logger?.error?.(`Threema inbound pipeline error: ${pipelineErr.message}`);
+                // Fallback to enqueueSystemEvent if pipeline fails
+                const enqueue = runtime?.system?.enqueueSystemEvent;
+                if (enqueue) {
+                  const envelope = `[Threema message from ${senderLabel} (${from})]\n${decrypted.text}`;
+                  enqueue(envelope, {
+                    sessionKey: "agent:main:main",
+                    deliveryContext: {
+                      channel: "threema",
+                      to: from,
+                      from: from,
+                      accountId: "default",
+                    },
+                  });
+                  api.logger?.info?.("Threema message dispatched via enqueueSystemEvent (fallback)");
+                  wakeAgent(config);
+                }
+              }
             } else {
-              api.logger?.warn?.("enqueueSystemEvent not available");
+              // Fallback: use enqueueSystemEvent if channel runtime not available
+              api.logger?.warn?.("Channel inbound pipeline not available, falling back to enqueueSystemEvent");
+              const enqueue = runtime?.system?.enqueueSystemEvent;
+              if (enqueue) {
+                const envelope = `[Threema message from ${senderLabel} (${from})]\n${decrypted.text}`;
+                enqueue(envelope, {
+                  sessionKey: "agent:main:main",
+                  deliveryContext: {
+                    channel: "threema",
+                    to: from,
+                    from: from,
+                    accountId: "default",
+                  },
+                });
+                api.logger?.info?.("Threema message dispatched via enqueueSystemEvent (legacy)");
+                wakeAgent(config);
+              } else {
+                api.logger?.warn?.("Neither channel pipeline nor enqueueSystemEvent available");
+              }
             }
           } else if (decrypted?.type === 0x17 && decrypted?.fileMessage) {
             // File message - PII only on debug level
@@ -1834,9 +1995,37 @@ export default function register(api: any) {
             res.end("Internal Server Error");
           }
         }
+        return;
+    };
+
+    // Register the webhook — Threema's callback server POSTs without our
+    // gateway auth token, so we need an unauthenticated route.
+    //
+    // Strategy: prefer registerHttpHandler (available in 2026.3.1, removed in 2026.3.2)
+    // because it bypasses gateway auth. Fall back to registerHttpRoute with auth:"none"
+    // (supported from 2026.3.2+). The order matters: registerHttpRoute in 2026.3.1
+    // silently ignores auth:"none" and applies gateway auth, breaking external webhooks.
+    if (api.registerHttpHandler) {
+      // 2026.3.1: registerHttpHandler with manual path matching (no gateway auth)
+      api.registerHttpHandler(async (req: any, res: any): Promise<boolean> => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (url.pathname !== webhookPath) return false;
+        await webhookHandler(req, res);
         return true;
-    });
-    api.logger?.info?.(`Threema webhook registered at ${webhookPath}`);
+      });
+      api.logger?.info?.(`Threema webhook registered via registerHttpHandler at ${webhookPath}`);
+    } else if (api.registerHttpRoute) {
+      // 2026.3.2+: registerHttpHandler removed, use registerHttpRoute with auth:"plugin"
+      // auth:"plugin" = no gateway auth, plugin handles its own auth (MAC verification)
+      api.registerHttpRoute({
+        path: webhookPath,
+        auth: "plugin",
+        handler: webhookHandler,
+      });
+      api.logger?.info?.(`Threema webhook registered via registerHttpRoute (auth:plugin) at ${webhookPath}`);
+    } else {
+      api.logger?.error?.("No HTTP registration method available — Threema webhook NOT registered!");
+    }
   }
 
   // Register CLI commands
@@ -1962,10 +2151,21 @@ export default function register(api: any) {
 /**
  * Wake the agent to process new messages
  */
+// Shared reference to runtime API — set during register(), used by wakeAgent()
+let _runtimeApi: any = null;
+
 function wakeAgent(config: any) {
+  // Prefer the new requestHeartbeatNow API (2026.3.2+) — direct, no HTTP roundtrip
+  if (_runtimeApi?.system?.requestHeartbeatNow) {
+    try {
+      _runtimeApi.system.requestHeartbeatNow({ sessionKey: "agent:main:main" });
+      return;
+    } catch {}
+  }
+
+  // Fallback: HTTP wake call for older versions
   const gatewayPort = config?.gateway?.port || 18789;
   
-  // Try ENV first, fallback to config file (security: ENV is preferred)
   let hooksToken: string | undefined = process.env.OPENCLAW_HOOKS_TOKEN;
   
   if (!hooksToken) {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "threema",
   "name": "Threema Gateway",
   "description": "Threema messaging channel via Threema Gateway API (E2E encrypted)",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "channels": [
     "threema"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-threema",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Threema Gateway channel plugin for OpenClaw",
   "type": "module",
   "main": "index.ts",
@@ -19,7 +19,13 @@
         "threema-gateway"
       ]
     },
-    "id": "threema"
+    "id": "threema",
+    "compat": {
+      "pluginApi": ">=1.0.0"
+    },
+    "build": {
+      "openclawVersion": "2026.3.28"
+    }
   },
   "dependencies": {
     "tweetnacl": "^1.0.3",