clawgram 2.6.1 → 2.7.1

package/dist/channel.js

@@ -12,6 +12,36 @@ const node_fs_1 = require("node:fs");
  *  a different conversation from a spoken line or a screenshot, and the
  *  transfer is not free. */
 const INBOUND_MEDIA_MAX_BYTES = 25 * 1024 * 1024;
+/**
+ * What this channel promises the Gateway.
+ *
+ * Annotated with core's own `ChannelCapabilities` on purpose: the shape is read
+ * by core (`resolveChannelTtsVoiceDelivery` reaches straight into
+ * `capabilities.tts.voice`), so a typo here would not fail — it would silently
+ * fall back to a default. With the annotation the compiler checks the promise
+ * against the version of OpenClaw we build against.
+ */
+const CHANNEL_CAPABILITIES = {
+    chatTypes: ["direct", "group"],
+    reactions: true,
+    threads: true,
+    media: true,
+    nativeCommands: false,
+    blockStreaming: false,
+    // Without this key core resolves the default "audio-file" and delivers
+    // synthesized speech as a document: a grey file card you must download
+    // before you know what it is. Advertising "voice-note" makes core mark such
+    // sends with `asVoice`, which the upload path honours.
+    //
+    // `transcodesAudio` is deliberately absent: we ship no ffmpeg and add no
+    // dependencies, so core must hand us Ogg/Opus — the only container Telegram
+    // renders as a voice bubble.
+    tts: {
+        voice: {
+            synthesisTarget: "voice-note",
+        },
+    },
+};
 const media_1 = require("./media");
 const channel_runtime_1 = require("openclaw/plugin-sdk/channel-runtime");
 const param_readers_1 = require("openclaw/plugin-sdk/param-readers");
@@ -201,14 +231,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
             blurb: "Connect your personal Telegram account to OpenClaw via MTProto. Your AI assistant responds as you.",
             aliases: ["tguserbot"],
         },
-        capabilities: {
-            chatTypes: ["direct", "group"],
-            reactions: true,
-            threads: true,
-            media: true,
-            nativeCommands: false,
-            blockStreaming: false,
-        },
+        capabilities: CHANNEL_CAPABILITIES,
         agentPrompt: {
             messageToolHints: () => [
                 "Use clawgram to send Telegram replies from the connected personal account.",
@@ -758,7 +781,16 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                     // A suppressed silent reply legitimately delivers nothing, so
                                     // this fallback fires right after it. Without the same check
                                     // the token would be read back from the transcript and sent.
-                                    const visibleFallbackText = fallbackText ? (0, helpers_1.stripSilentReplyToken)(fallbackText) : "";
+                                    //
+                                    // TTS markup needs the same treatment for the same reason:
+                                    // core strips it on the normal reply path, but this text comes
+                                    // straight out of the transcript. On 2026-08-08 a group got
+                                    // `[[tts:text]]Привет, Вася!…[[/tts:text]]` verbatim. The
+                                    // spoken words are kept — a synthesis that did not happen
+                                    // should degrade to readable text, not to markup.
+                                    const visibleFallbackText = fallbackText
+                                        ? (0, helpers_1.stripTtsDirectives)((0, helpers_1.stripSilentReplyToken)(fallbackText))
+                                        : "";
                                     if (fallbackText && !visibleFallbackText) {
                                         log?.info?.("clawgram skipping silent transcript fallback", {
                                             accountId,
@@ -1346,6 +1378,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         : captionText.replaceAll("\\n", "\n");
                     const uploadReplyToId = (0, param_readers_1.readStringOrNumberParam)(params, "replyToId") ?? (0, param_readers_1.readStringOrNumberParam)(params, "replyTo");
                     const uploadThreadId = (0, param_readers_1.readStringOrNumberParam)(params, "threadId");
+                    const asVoice = (0, helpers_1.readVoiceNoteFlag)(params);
                     actionLog.info("clawgram handleAction upload-file", {
                         accountId: uploadAccountId,
                         dryRun: dryRun === true,
@@ -1353,6 +1386,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         hasCaption: Boolean(caption),
                         replyToId: uploadReplyToId ?? null,
                         threadId: uploadThreadId ?? null,
+                        asVoice,
                     });
                     if (dryRun === true) {
                         return (0, core_1.jsonResult)({
@@ -1372,6 +1406,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         caption: caption || undefined,
                         replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(rawUploadTo, uploadReplyToId),
                         messageThreadId: parseOptionalThreadId(uploadThreadId),
+                        asVoice,
                     });
                     actionLog.info("clawgram handleAction upload-file completed", {
                         accountId: uploadAccountId,
@@ -1608,25 +1643,32 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 }
                 actionLog.info("clawgram outbound sendMedia", {
                     accountId: ctx.accountId,
-                    to: ctx.to,
+                    rawTo: ctx.to,
                     replyToId: ctx.replyToId ?? null,
                     threadId: ctx.threadId ?? null,
                     filePath: ctx.filePath ?? null,
                     mediaUrl: ctx.mediaUrl ?? null,
                     hasText: Boolean(ctx.text),
                     hasCaption: Boolean(ctx.caption),
+                    asVoice: ctx.audioAsVoice === true,
                 });
                 const file = ctx.filePath ?? ctx.mediaUrl;
                 if (!file) {
                     throw new Error("clawgram: sendMedia requires filePath or mediaUrl");
                 }
                 const messageThreadId = parseOptionalThreadId(ctx.threadId);
+                // Same normalization `sendText` does two functions up. Without it the
+                // channel prefix reaches peer resolution and the send throws — which is
+                // exactly how a synthesized group reply died on 2026-08-08, silently
+                // enough that the transcript fallback posted it as raw text instead.
+                const target = (0, helpers_1.normalizeOutboundTarget)(ctx.to);
                 const sent = await gram.sendMedia({
-                    target: ctx.to,
+                    target,
                     file,
                     caption: ctx.caption ?? ctx.text,
                     replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(ctx.to, ctx.replyToId),
                     messageThreadId,
+                    asVoice: ctx.audioAsVoice === true,
                 });
                 actionLog.info("clawgram outbound sendMedia completed", {
                     accountId: ctx.accountId,

package/dist/gramjs-client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GramJsClientManager = void 0;
+exports.buildVoiceNoteParams = buildVoiceNoteParams;
 const telegram_1 = require("telegram");
 const sessions_1 = require("telegram/sessions");
 const helpers_1 = require("./helpers");
@@ -79,6 +80,22 @@ function parseTargetWithThread(rawTarget) {
         chatId: raw,
     };
 }
+/**
+ * Voice-message option for `sendFile`.
+ *
+ * GramJS branches on `voiceNote` and builds `DocumentAttributeAudio` with
+ * `voice: true` itself, so the attribute must not be assembled by hand.
+ * The key is omitted rather than set to `false`: this codebase already paid
+ * for the lesson that a key's mere presence can flip a branch (see the MTProxy
+ * note in `proxy-config.ts`).
+ *
+ * Telegram renders a voice bubble only for Ogg/Opus; core is responsible for
+ * handing us that container, which is why the channel does not advertise
+ * `transcodesAudio`.
+ */
+function buildVoiceNoteParams(asVoice) {
+    return asVoice === true ? { voiceNote: true } : {};
+}
 function buildForumReplyParams(messageThreadId, replyToMessageId) {
     const normalizedThreadId = typeof messageThreadId === "number" && Number.isFinite(messageThreadId)
         ? Math.trunc(messageThreadId)
@@ -502,6 +519,7 @@ class GramJsClientManager {
             file: args.file,
             caption: args.caption,
             ...replyParams,
+            ...buildVoiceNoteParams(args.asVoice),
         });
     }
 }

package/dist/helpers.js

@@ -15,6 +15,8 @@ exports.readLatestAssistantFallbackFromTranscript = readLatestAssistantFallbackF
 exports.resolveActionTarget = resolveActionTarget;
 exports.resolveReplyToMessageIdForTarget = resolveReplyToMessageIdForTarget;
 exports.readMessageText = readMessageText;
+exports.readVoiceNoteFlag = readVoiceNoteFlag;
+exports.stripTtsDirectives = stripTtsDirectives;
 exports.resolveAllowFrom = resolveAllowFrom;
 exports.resolveGroupPolicy = resolveGroupPolicy;
 exports.resolveGroups = resolveGroups;
@@ -193,6 +195,39 @@ function resolveReplyToMessageIdForTarget(rawTarget, replyToId) {
     }
     return undefined;
 }
+/**
+ * Разметка синтеза речи, которая не должна доехать до человека.
+ *
+ * Core вырезает `[[tts:...]]` из видимого текста сам, но только на штатном
+ * пути ответа. Аварийный путь (`readLatestAssistantFallbackFromTranscript`)
+ * читает сырой текст из стенограммы, поэтому 2026-08-08 в групповой чат
+ * ушло `[[tts:text]]Привет, Вася!…[[/tts:text]]` как есть.
+ *
+ * Блок `[[tts:text]]…[[/tts:text]]` РАЗВОРАЧИВАЕТСЯ, а не удаляется: внутри
+ * лежит то, что агент собирался сказать. Если синтез не состоялся, человек
+ * должен получить эти слова текстом — деградация в читаемое, а не в мусор
+ * и не в пустоту.
+ */
+const TTS_TEXT_BLOCK = /\[\[tts:text\]\]([\s\S]*?)\[\[\/tts:text\]\]/gi;
+const TTS_DIRECTIVE = /\[\[\s*\/?\s*(?:tts:[^\]]*|audio_as_voice)\s*\]\]/gi;
+function stripTtsDirectives(text) {
+    return text
+        .replace(TTS_TEXT_BLOCK, (_match, spoken) => spoken)
+        .replace(TTS_DIRECTIVE, "")
+        .replace(/[ \t]{2,}/g, " ")
+        .trim();
+}
+/**
+ * Whether an outbound file should become a Telegram voice message.
+ *
+ * Core emits `asVoice` and, on some paths, the older `audioAsVoice` — both
+ * carry the same meaning, so both are read. Only a real `true` counts: a
+ * string "true" or a stray truthy value must not silently turn a document
+ * into a voice bubble.
+ */
+function readVoiceNoteFlag(params) {
+    return params?.asVoice === true || params?.audioAsVoice === true;
+}
 function readMessageText(params) {
     const message = (0, core_1.readStringParam)(params, "message", { allowEmpty: true });
     if (typeof message === "string") {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawgram",
   "name": "Clawgram",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawgram",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
   "main": "./dist/index.js",
   "scripts": {