feat(telegram): show commentary in progress drafts

obviyus · obviyus · commit bcc6093f4b4e · 2026-06-03T14:09:49.000+05:30
diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md
@@ -319,6 +319,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `progress` keeps one editable status draft for tool progress, clears it at completion, and sends the final answer as a normal message
     - `streaming.preview.toolProgress` controls whether tool/progress updates reuse the same edited preview message (default: `true` when preview streaming is active)
     - `streaming.preview.commandText` controls command/exec detail inside those tool-progress lines: `raw` (default, preserves released behavior) or `status` (tool label only)
+    - `streaming.progress.commentary` (default: `false`) opts into assistant commentary/preamble text in the temporary progress draft
     - legacy `channels.telegram.streamMode` and boolean `streaming` values are detected; run `openclaw doctor --fix` to migrate them to `channels.telegram.streaming.mode`
 
     Tool-progress preview updates are the short status lines shown while tools run, for example command execution, file reads, planning updates, patch summaries, or Codex preamble/commentary text in Codex app-server mode. Telegram keeps these enabled by default to match released OpenClaw behavior from `v2026.4.22` and later.
diff --git a/extensions/telegram/src/bot-message-dispatch.test.ts b/extensions/telegram/src/bot-message-dispatch.test.ts
@@ -2338,6 +2338,60 @@ describe("dispatchTelegramMessage draft streaming", () => {
     expect(draftStream.update).toHaveBeenCalledWith("Shelling\n\n`🛠️ Exec`\n• _Checking files_");
   });
 
+  it("renders configured Telegram commentary progress from preamble item events", async () => {
+    const draftStream = createSequencedDraftStream(2001);
+    createTelegramDraftStream.mockReturnValue(draftStream);
+    dispatchReplyWithBufferedBlockDispatcher.mockImplementation(async ({ replyOptions }) => {
+      await replyOptions?.onReplyStart?.();
+      await replyOptions?.onItemEvent?.({
+        kind: "preamble",
+        itemId: "preamble-1",
+        progressText: "Checking recent context",
+      });
+      return { queuedFinal: false };
+    });
+
+    await dispatchWithContext({
+      context: createContext(),
+      streamMode: "progress",
+      telegramCfg: {
+        streaming: {
+          mode: "progress",
+          progress: { label: "Shelling", commentary: true },
+        },
+      },
+    });
+
+    expect(draftStream.update).toHaveBeenCalledWith("Shelling\n\n_Checking recent context_");
+  });
+
+  it("suppresses Telegram preamble progress when commentary is disabled", async () => {
+    const draftStream = createSequencedDraftStream(2001);
+    createTelegramDraftStream.mockReturnValue(draftStream);
+    dispatchReplyWithBufferedBlockDispatcher.mockImplementation(async ({ replyOptions }) => {
+      await replyOptions?.onReplyStart?.();
+      await replyOptions?.onItemEvent?.({
+        kind: "preamble",
+        itemId: "preamble-1",
+        progressText: "Checking recent context",
+      });
+      return { queuedFinal: false };
+    });
+
+    await dispatchWithContext({
+      context: createContext(),
+      streamMode: "progress",
+      telegramCfg: {
+        streaming: {
+          mode: "progress",
+          progress: { label: "Shelling" },
+        },
+      },
+    });
+
+    expect(draftStream.update).not.toHaveBeenCalledWith(expect.stringContaining("Checking recent"));
+  });
+
   it("keeps the progress draft label when tool progress lines are hidden", async () => {
     const draftStream = createSequencedDraftStream(2001);
     createTelegramDraftStream.mockReturnValue(draftStream);
diff --git a/extensions/telegram/src/bot-message-dispatch.ts b/extensions/telegram/src/bot-message-dispatch.ts
@@ -1958,6 +1958,12 @@ export const dispatchTelegramMessage = async ({
                     await progressPromise;
                   },
                   onItemEvent: async (payload) => {
+                    if (payload.kind === "preamble") {
+                      await progressDraft.pushCommentaryProgress(payload.progressText, {
+                        itemId: payload.itemId,
+                      });
+                      return;
+                    }
                     await pushStreamToolProgress(
                       buildChannelProgressDraftLineForEntry(telegramCfg, {
                         event: "item",
diff --git a/extensions/telegram/src/config-schema.test.ts b/extensions/telegram/src/config-schema.test.ts
@@ -106,6 +106,22 @@ describe("telegram custom commands schema", () => {
     });
   });
 
+  it("accepts Telegram progress commentary config", () => {
+    expectTelegramConfigValid({
+      streaming: {
+        mode: "progress",
+        progress: { commentary: true },
+      },
+      accounts: {
+        ops: {
+          streaming: {
+            progress: { commentary: true },
+          },
+        },
+      },
+    });
+  });
+
   it("rejects removed DM thread reply policy keys", () => {
     expectTelegramConfigIssue({ dm: { threadReplies: "off" } }, "");
     expectTelegramConfigIssue(
diff --git a/extensions/telegram/src/config-ui-hints.ts b/extensions/telegram/src/config-ui-hints.ts
@@ -109,6 +109,10 @@ export const telegramChannelConfigUiHints = {
     label: "Telegram Progress Command Text",
     help: 'Command/exec detail in progress draft lines: "raw" preserves released behavior; "status" shows only the tool label.',
   },
+  "streaming.progress.commentary": {
+    label: "Telegram Progress Commentary",
+    help: "Show assistant commentary/preamble text in the temporary progress draft. Final answer delivery is unchanged.",
+  },
   "retry.attempts": {
     label: "Telegram Retry Attempts",
     help: "Max retry attempts for outbound Telegram API calls (default: 3).",
diff --git a/src/config/bundled-channel-config-metadata.generated.ts b/src/config/bundled-channel-config-metadata.generated.ts
diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts
@@ -284,7 +284,7 @@ describe("config schema", () => {
     expect(progressPropsFor("discord")).not.toHaveProperty("nativeTaskCards");
     expect(progressPropsFor("telegram")).not.toHaveProperty("nativeTaskCards");
     expect(progressPropsFor("discord")).toHaveProperty("commentary");
-    expect(progressPropsFor("telegram")).not.toHaveProperty("commentary");
+    expect(progressPropsFor("telegram")).toHaveProperty("commentary");
     expect(res.uiHints["channels.matrix"]?.label).toBe("Matrix");
     expect(res.uiHints["channels.matrix.accessToken"]?.sensitive).toBe(true);
     expect(res.uiHints["channels.matrix.streaming.progress.label"]?.label).toBe(
@@ -298,7 +298,9 @@ describe("config schema", () => {
     expect(res.uiHints["channels.discord.streaming.progress.toolProgress"]?.label).toBe(
       "Discord Progress Tool Lines",
     );
-    expect(res.uiHints["channels.telegram.streaming.progress.commentary"]).toBeUndefined();
+    expect(res.uiHints["channels.telegram.streaming.progress.commentary"]?.label).toBe(
+      "Telegram Progress Commentary",
+    );
     expect(res.uiHints["channels.mattermost.streaming.progress.label"]?.label).toBe(
       "Mattermost Progress Label",
     );
@@ -456,7 +458,7 @@ describe("config schema", () => {
     ).toBe(false);
   });
 
-  it("accepts progress commentary only for Discord streaming config", () => {
+  it("accepts progress commentary for Discord and Telegram streaming config", () => {
     expect(
       DiscordConfigSchema.safeParse({
         streaming: {
@@ -473,7 +475,7 @@ describe("config schema", () => {
           progress: { commentary: true },
         },
       }).success,
-    ).toBe(false);
+    ).toBe(true);
   });
 
   it("keeps per-agent model overrides limited to model selection", () => {
diff --git a/src/config/types.telegram.ts b/src/config/types.telegram.ts
@@ -1,5 +1,6 @@
 import type {
   ChannelPreviewStreamingConfig,
+  ChannelStreamingProgressConfig,
   ChannelStreamingPreviewConfig,
   ContextVisibilityMode,
   DmPolicy,
@@ -76,6 +77,12 @@ export type TelegramStreamingPreviewConfig = ChannelStreamingPreviewConfig & {
 
 export type TelegramPreviewStreamingConfig = Omit<ChannelPreviewStreamingConfig, "preview"> & {
   preview?: TelegramStreamingPreviewConfig;
+  progress?: TelegramStreamingProgressConfig;
+};
+
+export type TelegramStreamingProgressConfig = ChannelStreamingProgressConfig & {
+  /** Include assistant commentary/preamble text in the progress draft. Default: false. */
+  commentary?: boolean;
 };
 
 export type TelegramExecApprovalConfig = {
diff --git a/src/config/zod-schema.providers-core.ts b/src/config/zod-schema.providers-core.ts
@@ -103,7 +103,7 @@ const ChannelStreamingProgressSchema = z
     commandText: z.enum(["raw", "status"]).optional(),
   })
   .strict();
-const DiscordStreamingProgressSchema = ChannelStreamingProgressSchema.extend({
+const ChannelCommentaryStreamingProgressSchema = ChannelStreamingProgressSchema.extend({
   commentary: z.boolean().optional(),
 }).strict();
 const SlackStreamingProgressSchema = ChannelStreamingProgressSchema.extend({
@@ -122,7 +122,7 @@ const TelegramPreviewStreamingConfigSchema = ChannelPreviewStreamingConfigSchema
   preview: TelegramStreamingPreviewSchema.optional(),
 }).strict();
 const DiscordPreviewStreamingConfigSchema = ChannelPreviewStreamingConfigSchema.extend({
-  progress: DiscordStreamingProgressSchema.optional(),
+  progress: ChannelCommentaryStreamingProgressSchema.optional(),
 }).strict();
 const SlackStreamingConfigSchema = ChannelPreviewStreamingConfigSchema.extend({
   nativeTransport: z.boolean().optional(),
@@ -1704,3 +1704,7 @@ export const MSTeamsConfigSchema = z
     // so we cannot require them in the config object itself.
     // Runtime validation happens in resolveMSTeamsCredentials().
   });
+
+// Keep this runtime-only widening out of exported schema declarations.
+TelegramPreviewStreamingConfigSchema.shape.progress =
+  ChannelCommentaryStreamingProgressSchema.optional();
