openclaw-threema 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.6.3 (2026-05-04)
+
+### Fixed
+- **File messages now route through the Channel Inbound Pipeline** like text
+  messages, so they appear as part of the same Threema DM conversation
+  the agent is already in. Previously file inbounds were dispatched via
+  legacy `enqueueSystemEvent` against `agent:main:main`, which left them
+  invisible to the running DM session: the agent only learned about the
+  file by chance (e.g. by greping the inbound media folder later).
+  Symptom hit on 2026-05-04 when the user shipped the OpenClaw
+  2026.5.3 update protocol as a `.txt` file and the agent did not see it
+  for ~20 minutes.
+
+### Added
+- File inbounds now expose `MediaPath` / `MediaType` / `MediaUrl` to the
+  agent context (matching the convention used by the Matrix channel
+  plugin). The agent can read the saved file directly with its normal
+  tools (read / pdf / image) and reply in the same DM thread.
+- The memory briefing block is now also injected into file inbounds, so
+  the agent's acute-state context applies regardless of whether the
+  user sent text or a file.
+- Voice notes (audio file messages) get the same treatment: the
+  Whisper transcription is included in the body, the audio path in
+  `MediaPath`.
+
+### Compatibility
+- Falls back to the legacy `enqueueSystemEvent` path on older OpenClaw
+  runtimes that don't expose `channelRuntime.reply.finalizeInboundContext`,
+  or whenever the new pipeline path throws.
+
 ## 0.6.2 (2026-05-04)
 
 ### Fixed

package/dist/index.js

@@ -1649,37 +1649,162 @@ export default function register(api) {
                         api.logger?.debug?.(`Threema file from=${from} messageId=${messageId}`);
                         // Process the file: download, decrypt, save, maybe transcribe
                         const result = await processFileMessage(client, fileMsg, from, api.logger);
-                        // Dispatch to OpenClaw
-                        const enqueue = runtime?.system?.enqueueSystemEvent;
-                        if (enqueue) {
-                            let envelope = `[Threema file from ${senderLabel} (${from})]`;
-                            if (fileMsg.d) {
-                                envelope += `\nCaption: ${fileMsg.d}`;
+                        // Build a body summarising the inbound file. The actual binary
+                        // lives at result.filePath; we expose it via MediaPath so the
+                        // agent can read/inspect it with its normal tools (read/pdf/image).
+                        const fileLines = [];
+                        const fileLabel = fileMsg.n || "unnamed";
+                        const fileMime = fileMsg.m || "application/octet-stream";
+                        const fileSize = typeof fileMsg.s === "number" ? `${fileMsg.s} bytes` : "unknown size";
+                        if (fileMsg.d) {
+                            fileLines.push(fileMsg.d);
+                        }
+                        fileLines.push(`[user sent file: ${fileLabel} (${fileMime}, ${fileSize})]`);
+                        if (result?.filePath) {
+                            fileLines.push(`Saved at: ${result.filePath}`);
+                            if (result.transcription) {
+                                fileLines.push("");
+                                fileLines.push("🎤 Audio transcription:");
+                                fileLines.push(result.transcription);
                             }
-                            envelope += `\nFile: ${fileMsg.n || "unnamed"} (${fileMsg.m}, ${fileMsg.s} bytes)`;
-                            if (result?.filePath) {
-                                envelope += `\nSaved to: ${result.filePath}`;
-                                if (result.transcription) {
-                                    envelope += `\n\n🎤 Audio transcription:\n${result.transcription}`;
+                        }
+                        else {
+                            fileLines.push("⚠️ Failed to download/decrypt file");
+                        }
+                        const fileBody = fileLines.join("\n");
+                        // Try the Channel Inbound Pipeline first (same path as text
+                        // messages). This routes the inbound to the existing Threema DM
+                        // session, runs the agent in-context, and lets us reply via
+                        // dispatchReplyWithBufferedBlockDispatcher just like text.
+                        const channelRuntime = runtime?.channel;
+                        if (channelRuntime?.reply?.finalizeInboundContext
+                            && channelRuntime?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+                            try {
+                                const currentCfg = runtime.config.loadConfig();
+                                const sessionKey = channelRuntime.reply.resolveDirectSessionKey({
+                                    channel: "threema",
+                                    accountId: "default",
+                                    peer: { kind: "direct", id: from },
+                                    dmScope: "per-account-channel-peer",
+                                });
+                                const senderAllowed = allowFrom.length === 0 || allowFrom.includes(from);
+                                const bodyForAgent = composeBodyForAgent(fileBody, currentCfg);
+                                const fileCtx = channelRuntime.reply.finalizeInboundContext({
+                                    Body: fileBody,
+                                    RawBody: fileBody,
+                                    CommandBody: fileMsg.d || "",
+                                    BodyForAgent: bodyForAgent,
+                                    From: `threema:${from}`,
+                                    To: `threema:${ownGatewayId}`,
+                                    SessionKey: sessionKey,
+                                    AccountId: "default",
+                                    OriginatingChannel: "threema",
+                                    OriginatingTo: `threema:${from}`,
+                                    ChatType: "direct",
+                                    SenderName: senderLabel,
+                                    SenderId: from,
+                                    Provider: "threema",
+                                    Surface: "threema",
+                                    ConversationLabel: senderLabel || from,
+                                    Timestamp: Date.now(),
+                                    CommandAuthorized: senderAllowed,
+                                    MediaPath: result?.filePath,
+                                    MediaUrl: result?.filePath,
+                                    MediaType: fileMime,
+                                    MessageSid: messageId,
+                                });
+                                const replyClient = new ThreemaClient(getThreemaConfig(currentCfg));
+                                await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+                                    ctx: fileCtx,
+                                    cfg: currentCfg,
+                                    dispatcherOptions: {
+                                        deliver: async (payload) => {
+                                            const text = payload.text ?? payload.body;
+                                            if (!text)
+                                                return;
+                                            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 {
+                                                const chunks = [];
+                                                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 file-reply started for ${from}`);
+                                        },
+                                    },
+                                });
+                                api.logger?.info?.("Threema file message dispatched via Channel Inbound Pipeline");
+                            }
+                            catch (pipelineErr) {
+                                api.logger?.error?.(`Threema file inbound pipeline error: ${pipelineErr.message}`);
+                                // Fallback: legacy enqueueSystemEvent so the file isn't lost.
+                                const enqueue = runtime?.system?.enqueueSystemEvent;
+                                if (enqueue) {
+                                    enqueue(`[Threema file from ${senderLabel} (${from})]\n${fileBody}`, {
+                                        sessionKey: "agent:main:main",
+                                        deliveryContext: {
+                                            channel: "threema",
+                                            to: from,
+                                            from: from,
+                                            accountId: "default",
+                                            mediaPath: result?.filePath,
+                                            transcription: result?.transcription,
+                                        },
+                                    });
+                                    api.logger?.info?.("Threema file message dispatched via enqueueSystemEvent (fallback)");
+                                    wakeAgent(config);
                                 }
                             }
+                        }
+                        else {
+                            // Fallback for older OpenClaw runtimes that don't expose the
+                            // channel inbound pipeline.
+                            const enqueue = runtime?.system?.enqueueSystemEvent;
+                            if (enqueue) {
+                                enqueue(`[Threema file from ${senderLabel} (${from})]\n${fileBody}`, {
+                                    sessionKey: "agent:main:main",
+                                    deliveryContext: {
+                                        channel: "threema",
+                                        to: from,
+                                        from: from,
+                                        accountId: "default",
+                                        mediaPath: result?.filePath,
+                                        transcription: result?.transcription,
+                                    },
+                                });
+                                api.logger?.info?.("Threema file message dispatched via enqueueSystemEvent (legacy)");
+                                wakeAgent(config);
+                            }
                             else {
-                                envelope += `\n⚠️ Failed to download/decrypt file`;
+                                api.logger?.warn?.("Threema file: neither channel pipeline nor enqueueSystemEvent available");
                             }
-                            enqueue(envelope, {
-                                sessionKey: "agent:main:main",
-                                deliveryContext: {
-                                    channel: "threema",
-                                    to: from,
-                                    from: from,
-                                    accountId: "default",
-                                    mediaPath: result?.filePath,
-                                    transcription: result?.transcription,
-                                },
-                            });
-                            api.logger?.info?.("Threema file message dispatched via enqueueSystemEvent");
-                            // Wake the agent
-                            wakeAgent(config);
                         }
                     }
                     else if (decrypted?.type === 0x80) {

package/index.ts

@@ -2093,42 +2093,157 @@ export default function register(api: any) {
               api.logger
             );
 
-            // Dispatch to OpenClaw
-            const enqueue = runtime?.system?.enqueueSystemEvent;
-            if (enqueue) {
-              let envelope = `[Threema file from ${senderLabel} (${from})]`;
-
-              if (fileMsg.d) {
-                envelope += `\nCaption: ${fileMsg.d}`;
+            // Build a body summarising the inbound file. The actual binary
+            // lives at result.filePath; we expose it via MediaPath so the
+            // agent can read/inspect it with its normal tools (read/pdf/image).
+            const fileLines: string[] = [];
+            const fileLabel = fileMsg.n || "unnamed";
+            const fileMime = fileMsg.m || "application/octet-stream";
+            const fileSize = typeof fileMsg.s === "number" ? `${fileMsg.s} bytes` : "unknown size";
+            if (fileMsg.d) {
+              fileLines.push(fileMsg.d);
+            }
+            fileLines.push(`[user sent file: ${fileLabel} (${fileMime}, ${fileSize})]`);
+            if (result?.filePath) {
+              fileLines.push(`Saved at: ${result.filePath}`);
+              if (result.transcription) {
+                fileLines.push("");
+                fileLines.push("🎤 Audio transcription:");
+                fileLines.push(result.transcription);
               }
+            } else {
+              fileLines.push("⚠️ Failed to download/decrypt file");
+            }
+            const fileBody = fileLines.join("\n");
 
-              envelope += `\nFile: ${fileMsg.n || "unnamed"} (${fileMsg.m}, ${fileMsg.s} bytes)`;
+            // Try the Channel Inbound Pipeline first (same path as text
+            // messages). This routes the inbound to the existing Threema DM
+            // session, runs the agent in-context, and lets us reply via
+            // dispatchReplyWithBufferedBlockDispatcher just like text.
+            const channelRuntime = runtime?.channel;
+            if (channelRuntime?.reply?.finalizeInboundContext
+                && channelRuntime?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+              try {
+                const currentCfg = runtime.config.loadConfig();
+                const sessionKey = channelRuntime.reply.resolveDirectSessionKey({
+                  channel: "threema",
+                  accountId: "default",
+                  peer: { kind: "direct", id: from },
+                  dmScope: "per-account-channel-peer",
+                });
 
-              if (result?.filePath) {
-                envelope += `\nSaved to: ${result.filePath}`;
+                const senderAllowed = allowFrom.length === 0 || allowFrom.includes(from);
 
-                if (result.transcription) {
-                  envelope += `\n\n🎤 Audio transcription:\n${result.transcription}`;
+                const bodyForAgent = composeBodyForAgent(fileBody, currentCfg);
+                const fileCtx = channelRuntime.reply.finalizeInboundContext({
+                  Body: fileBody,
+                  RawBody: fileBody,
+                  CommandBody: fileMsg.d || "",
+                  BodyForAgent: bodyForAgent,
+                  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,
+                  MediaPath: result?.filePath,
+                  MediaUrl: result?.filePath,
+                  MediaType: fileMime,
+                  MessageSid: messageId,
+                });
+
+                const replyClient = new ThreemaClient(getThreemaConfig(currentCfg)!);
+                await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+                  ctx: fileCtx,
+                  cfg: currentCfg,
+                  dispatcherOptions: {
+                    deliver: async (payload: any) => {
+                      const text = payload.text ?? payload.body;
+                      if (!text) return;
+                      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 {
+                        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 file-reply started for ${from}`);
+                    },
+                  },
+                });
+                api.logger?.info?.("Threema file message dispatched via Channel Inbound Pipeline");
+              } catch (pipelineErr: any) {
+                api.logger?.error?.(`Threema file inbound pipeline error: ${pipelineErr.message}`);
+                // Fallback: legacy enqueueSystemEvent so the file isn't lost.
+                const enqueue = runtime?.system?.enqueueSystemEvent;
+                if (enqueue) {
+                  enqueue(`[Threema file from ${senderLabel} (${from})]\n${fileBody}`, {
+                    sessionKey: "agent:main:main",
+                    deliveryContext: {
+                      channel: "threema",
+                      to: from,
+                      from: from,
+                      accountId: "default",
+                      mediaPath: result?.filePath,
+                      transcription: result?.transcription,
+                    },
+                  });
+                  api.logger?.info?.("Threema file message dispatched via enqueueSystemEvent (fallback)");
+                  wakeAgent(config);
                 }
+              }
+            } else {
+              // Fallback for older OpenClaw runtimes that don't expose the
+              // channel inbound pipeline.
+              const enqueue = runtime?.system?.enqueueSystemEvent;
+              if (enqueue) {
+                enqueue(`[Threema file from ${senderLabel} (${from})]\n${fileBody}`, {
+                  sessionKey: "agent:main:main",
+                  deliveryContext: {
+                    channel: "threema",
+                    to: from,
+                    from: from,
+                    accountId: "default",
+                    mediaPath: result?.filePath,
+                    transcription: result?.transcription,
+                  },
+                });
+                api.logger?.info?.("Threema file message dispatched via enqueueSystemEvent (legacy)");
+                wakeAgent(config);
               } else {
-                envelope += `\n⚠️ Failed to download/decrypt file`;
+                api.logger?.warn?.("Threema file: neither channel pipeline nor enqueueSystemEvent available");
               }
-
-              enqueue(envelope, {
-                sessionKey: "agent:main:main",
-                deliveryContext: {
-                  channel: "threema",
-                  to: from,
-                  from: from,
-                  accountId: "default",
-                  mediaPath: result?.filePath,
-                  transcription: result?.transcription,
-                },
-              });
-              api.logger?.info?.("Threema file message dispatched via enqueueSystemEvent");
-
-              // Wake the agent
-              wakeAgent(config);
             }
           } else if (decrypted?.type === 0x80) {
             // Delivery receipt - PII only on debug level

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.6.2",
+  "version": "0.6.3",
   "channels": [
     "threema"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-threema",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Threema Gateway channel plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",