feat(discord): show commentary in progress drafts

bryanpearson · bryanpearson · commit 95c6b01edba4 · 2026-05-21T19:29:22.000-07:00
diff --git a/docs/channels/discord.md b/docs/channels/discord.md
@@ -696,6 +696,7 @@ Default slash command settings:
           maxLines: 8,
           maxLineChars: 120,
           toolProgress: true,
+          commentary: false,
         },
       },
     },
@@ -708,6 +709,7 @@ Default slash command settings:
     - Media, error, and explicit-reply finals cancel pending preview edits.
     - `streaming.preview.toolProgress` (default `true`) controls whether tool/progress updates reuse the preview message.
     - Tool/progress rows render as compact emoji + title + detail when available, for example `🛠️ Bash: run tests` or `🔎 Web Search: for "query"`.
+    - `streaming.progress.commentary` (default `false`) opts into assistant commentary/preamble text in the temporary progress draft. Commentary is cleaned before display, stays transient, and does not change final answer delivery.
     - `streaming.progress.maxLineChars` controls the per-line progress preview budget. Prose is shortened on word boundaries; command and path details keep useful suffixes.
     - `streaming.preview.commandText` / `streaming.progress.commandText` controls command/exec detail in compact progress lines: `raw` (default) or `status` (tool label only).
 
diff --git a/extensions/discord/src/config-ui-hints.ts b/extensions/discord/src/config-ui-hints.ts
@@ -89,6 +89,10 @@ export const discordChannelConfigUiHints = {
     label: "Discord Progress Tool Lines",
     help: "Show compact tool/progress lines in progress draft mode (default: true). Set false to keep only the label until final delivery.",
   },
+  "streaming.progress.commentary": {
+    label: "Discord Progress Commentary",
+    help: "Show assistant commentary/preamble text in the temporary progress draft. Final answer delivery is unchanged.",
+  },
   "streaming.progress.commandText": {
     label: "Discord Progress Command Text",
     help: 'Command/exec detail in progress draft lines: "raw" preserves released behavior; "status" shows only the tool label.',
diff --git a/extensions/discord/src/monitor/message-handler.draft-preview.ts b/extensions/discord/src/monitor/message-handler.draft-preview.ts
@@ -8,6 +8,7 @@ import {
   normalizeChannelProgressDraftLineIdentity,
   resolveChannelProgressDraftMaxLines,
   resolveChannelStreamingBlockEnabled,
+  resolveChannelStreamingProgressCommentary,
   resolveChannelStreamingPreviewToolProgress,
   resolveChannelStreamingSuppressDefaultToolProgressMessages,
 } from "openclaw/plugin-sdk/channel-streaming";
@@ -81,6 +82,8 @@ export function createDiscordDraftPreviewController(params: {
   let finalReplyDelivered = false;
   const previewToolProgressEnabled =
     Boolean(draftStream) && resolveChannelStreamingPreviewToolProgress(params.discordConfig);
+  const commentaryProgressEnabled =
+    Boolean(draftStream) && resolveChannelStreamingProgressCommentary(params.discordConfig);
   const suppressDefaultToolProgressMessages =
     Boolean(draftStream) &&
     resolveChannelStreamingSuppressDefaultToolProgressMessages(params.discordConfig, {
@@ -140,6 +143,7 @@ export function createDiscordDraftPreviewController(params: {
   return {
     draftStream,
     previewToolProgressEnabled,
+    commentaryProgressEnabled,
     suppressDefaultToolProgressMessages,
     get isProgressMode() {
       return discordStreamMode === "progress";
@@ -266,6 +270,33 @@ export function createDiscordDraftPreviewController(params: {
         await renderProgressDraft();
       }
     },
+    async pushCommentaryProgress(text?: string, options?: { itemId?: string }) {
+      if (!draftStream || discordStreamMode !== "progress" || !commentaryProgressEnabled || !text) {
+        return;
+      }
+      if (finalReplyStarted || finalReplyDelivered) {
+        return;
+      }
+      const normalized = normalizeCommentaryProgressText(text);
+      if (!normalized) {
+        return;
+      }
+      const lineId = options?.itemId?.trim()
+        ? `commentary:${options.itemId.trim()}`
+        : `commentary:${normalized}`;
+      const line: ChannelProgressDraftLine = {
+        id: lineId,
+        kind: "item",
+        text: normalized,
+        label: "Commentary",
+        prefix: false,
+      };
+      previewToolProgressLines = mergeChannelProgressDraftLine(previewToolProgressLines, line, {
+        maxLines: resolveChannelProgressDraftMaxLines(params.discordConfig),
+      });
+      await progressDraftGate.startNow();
+      await renderProgressDraft();
+    },
     resolvePreviewFinalText(text?: string) {
       if (typeof text !== "string") {
         return undefined;
@@ -403,6 +434,24 @@ function normalizeReasoningProgressLine(text: string): string {
     .trim();
 }
 
+function normalizeCommentaryProgressText(text: string): string {
+  const cleaned = stripInlineDirectiveTagsForDelivery(text).text.trim();
+  if (!cleaned || isSilentCommentaryProgressText(cleaned)) {
+    return "";
+  }
+  return cleaned
+    .split(/\r?\n/u)
+    .map((line) => line.replace(/\s+/g, " ").trim())
+    .filter(Boolean)
+    .map((line) => `_${line}_`)
+    .join("\n");
+}
+
+function isSilentCommentaryProgressText(text: string): boolean {
+  const normalized = text.replace(/^[\s*_`~]+|[\s*_`~]+$/gu, "").trim();
+  return /^NO_REPLY$/iu.test(normalized);
+}
+
 function mergeReasoningProgressText(current: string, incoming: string): string {
   if (!current) {
     return incoming;
diff --git a/extensions/discord/src/monitor/message-handler.process.test.ts b/extensions/discord/src/monitor/message-handler.process.test.ts
@@ -111,6 +111,7 @@ type DispatchInboundParams = {
       detailMode?: "explain" | "raw";
     }) => Promise<void> | void;
     onItemEvent?: (payload: {
+      itemId?: string;
       kind?: string;
       progressText?: string;
       summary?: string;
@@ -2286,6 +2287,104 @@ describe("processDiscordMessage draft streaming", () => {
     ).toBe(true);
   });
 
+  it("shows opt-in Discord commentary progress independently from tool progress", async () => {
+    const draftStream = createMockDraftStreamForTest();
+
+    dispatchInboundMessage.mockImplementationOnce(async (params?: DispatchInboundParams) => {
+      await params?.replyOptions?.onToolStart?.({ name: "exec", phase: "start" });
+      await params?.replyOptions?.onItemEvent?.({
+        itemId: "preamble-1",
+        kind: "preamble",
+        progressText: "Checking the current weather source before summarizing.",
+      });
+      await params?.replyOptions?.onItemEvent?.({
+        itemId: "preamble-1",
+        kind: "preamble",
+        progressText: "Checking the current weather source before summarizing clearly.",
+      });
+      await params?.replyOptions?.onItemEvent?.({
+        itemId: "preamble-2",
+        kind: "preamble",
+        progressText: "[[reply_to_current]] Checking route impacts.",
+      });
+      await params?.replyOptions?.onItemEvent?.({
+        itemId: "preamble-3",
+        kind: "preamble",
+        progressText: "**NO_REPLY",
+      });
+      await params?.replyOptions?.onItemEvent?.({
+        itemId: "tool-1",
+        kind: "tool",
+        name: "exec",
+        progressText: "curl weather api",
+      });
+      return createNoQueuedDispatchResult();
+    });
+
+    const ctx = await createAutomaticSourceDeliveryContext({
+      discordConfig: {
+        streaming: {
+          mode: "progress",
+          progress: {
+            label: false,
+            toolProgress: false,
+            commentary: true,
+          },
+        },
+      },
+    });
+
+    await runProcessDiscordMessage(ctx);
+
+    expect(draftStream.update).toHaveBeenLastCalledWith(
+      "_Checking the current weather source before summarizing clearly._\n_Checking route impacts._",
+    );
+    const updates = draftStream.update.mock.calls.map((call) => call[0]).join("\n");
+    expect(updates).not.toContain("Exec");
+    expect(updates).not.toContain("curl weather api");
+    expect(updates).not.toContain("reply_to_current");
+    expect(updates).not.toContain("NO_REPLY");
+  });
+
+  it("does not update Discord commentary progress after final answer delivery starts", async () => {
+    const draftStream = createMockDraftStreamForTest();
+
+    dispatchInboundMessage.mockImplementationOnce(async (params?: DispatchInboundParams) => {
+      await params?.replyOptions?.onItemEvent?.({
+        itemId: "preamble-1",
+        kind: "preamble",
+        progressText: "Checking source data.",
+      });
+      void params?.dispatcher.sendFinalReply({ text: "done" });
+      await params?.replyOptions?.onItemEvent?.({
+        itemId: "preamble-2",
+        kind: "preamble",
+        progressText: "Late commentary should not edit the draft.",
+      });
+      await params?.dispatcher.waitForIdle();
+      return { queuedFinal: true, counts: { final: 1, tool: 0, block: 0 } };
+    });
+
+    const ctx = await createAutomaticSourceDeliveryContext({
+      discordConfig: {
+        streaming: {
+          mode: "progress",
+          progress: {
+            label: false,
+            commentary: true,
+          },
+        },
+      },
+    });
+
+    await runProcessDiscordMessage(ctx);
+
+    const updates = draftStream.update.mock.calls.map((call) => call[0]);
+    expect(updates).toEqual(["_Checking source data._"]);
+    expectPreviewEditContent("done");
+    expect(deliverDiscordReply).not.toHaveBeenCalled();
+  });
+
   it("does not start Discord progress drafts for text-only accepted turns", async () => {
     const draftStream = createMockDraftStreamForTest();
 
diff --git a/extensions/discord/src/monitor/message-handler.process.ts b/extensions/discord/src/monitor/message-handler.process.ts
@@ -856,6 +856,16 @@ export async function processDiscordMessage(
               );
             },
             onItemEvent: async (payload) => {
+              if (
+                draftPreview.commentaryProgressEnabled &&
+                payload.kind === "preamble" &&
+                payload.progressText
+              ) {
+                await draftPreview.pushCommentaryProgress(payload.progressText, {
+                  itemId: payload.itemId,
+                });
+                return;
+              }
               await draftPreview.pushToolProgress(
                 buildChannelProgressDraftLineForEntry(discordConfig, {
                   event: "item",
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/types.base.ts b/src/config/types.base.ts
@@ -48,6 +48,11 @@ export type ChannelStreamingProgressConfig = {
   render?: "text" | "rich";
   /** Include compact tool/task progress in the draft. Default: true. */
   toolProgress?: boolean;
+  /**
+   * Include assistant commentary/preamble text in the progress draft.
+   * Default: false, so interim assistant notes remain hidden unless a channel opts in.
+   */
+  commentary?: boolean;
   /** Command/exec progress detail in the draft. "raw" preserves released behavior; "status" shows only the tool label. Default: "raw". */
   commandText?: ChannelStreamingCommandTextMode;
 };
diff --git a/src/config/zod-schema.providers-core.ts b/src/config/zod-schema.providers-core.ts
@@ -100,6 +100,7 @@ const ChannelStreamingProgressSchema = z
     maxLineChars: z.number().int().positive().optional(),
     render: z.enum(["text", "rich"]).optional(),
     toolProgress: z.boolean().optional(),
+    commentary: z.boolean().optional(),
     commandText: z.enum(["raw", "status"]).optional(),
   })
   .strict();
diff --git a/src/plugin-sdk/channel-streaming.test.ts b/src/plugin-sdk/channel-streaming.test.ts
@@ -19,6 +19,7 @@ import {
   resolveChannelStreamingBlockEnabled,
   resolveChannelStreamingChunkMode,
   resolveChannelStreamingNativeTransport,
+  resolveChannelStreamingProgressCommentary,
   resolveChannelStreamingPreviewCommandText,
   resolveChannelStreamingPreviewChunk,
   resolveChannelStreamingSuppressDefaultToolProgressMessages,
@@ -98,6 +99,24 @@ describe("channel-streaming", () => {
     ).toBe(false);
   });
 
+  it("enables commentary progress only for progress-mode drafts", () => {
+    expect(
+      resolveChannelStreamingProgressCommentary({
+        streaming: { mode: "progress", progress: { commentary: true } },
+      }),
+    ).toBe(true);
+    expect(
+      resolveChannelStreamingProgressCommentary({
+        streaming: { mode: "partial", progress: { commentary: true } },
+      }),
+    ).toBe(false);
+    expect(
+      resolveChannelStreamingProgressCommentary({
+        streaming: { mode: "progress" },
+      }),
+    ).toBe(false);
+  });
+
   it("falls back to legacy flat fields when the canonical object is absent", () => {
     const entry = {
       chunkMode: "newline",
@@ -277,6 +296,19 @@ describe("channel-streaming", () => {
         lines: ["🛠️ Exec", "plain update"],
       }),
     ).toBe("🛠️ Exec\n• plain update");
+    expect(
+      formatChannelProgressDraftText({
+        entry: { streaming: { progress: { label: false } } },
+        lines: [
+          {
+            kind: "item",
+            text: "_Checking source data before summarizing._",
+            label: "Commentary",
+            prefix: false,
+          },
+        ],
+      }),
+    ).toBe("_Checking source data before summarizing._");
   });
 
   it("renders progress labels as rolling lines", () => {
diff --git a/src/plugin-sdk/channel-streaming.ts b/src/plugin-sdk/channel-streaming.ts
@@ -270,6 +270,7 @@ export type ChannelProgressDraftLine = {
   detail?: string;
   status?: string;
   toolName?: string;
+  prefix?: boolean;
 };
 
 function compactStrings(values: readonly (string | undefined | null)[]): string[] {
@@ -635,6 +636,17 @@ export function resolveChannelStreamingPreviewToolProgress(
   return asBoolean(config?.preview?.toolProgress) ?? defaultValue;
 }
 
+export function resolveChannelStreamingProgressCommentary(
+  entry: StreamingCompatEntry | null | undefined,
+  defaultValue = false,
+): boolean {
+  const config = getChannelStreamingConfigObject(entry);
+  if (resolveChannelPreviewStreamMode(entry, "partial") !== "progress") {
+    return false;
+  }
+  return asBoolean(config?.progress?.commentary) ?? defaultValue;
+}
+
 export function resolveChannelStreamingPreviewCommandText(
   entry: StreamingCompatEntry | null | undefined,
   defaultValue: ChannelStreamingCommandTextMode = "raw",
@@ -961,20 +973,27 @@ export function formatChannelProgressDraftText(params: {
   const lines = rawLines
     .map((line) => {
       const isLabelLine = typeof line === "object" && line !== null && "draftLabel" in line;
+      const prefix =
+        !isLabelLine && typeof line === "object" && line !== null ? line.prefix !== false : true;
       const rawText = isLabelLine
         ? line.draftLabel
         : typeof line === "string"
           ? line
           : getProgressDraftLineText(line);
       const text = compactChannelProgressDraftLine(rawText, maxLineChars);
-      return text ? { text, isLabelLine } : undefined;
+      return text ? { text, isLabelLine, prefix } : undefined;
     })
-    .filter((line): line is { text: string; isLabelLine: boolean } => Boolean(line))
+    .filter((line): line is { text: string; isLabelLine: boolean; prefix: boolean } =>
+      Boolean(line),
+    )
     .slice(-maxLines)
-    .map(({ text, isLabelLine }) => {
+    .map(({ text, isLabelLine, prefix }) => {
       const formatted = isLabelLine ? text : formatLine(text);
       return {
-        text: !isLabelLine && shouldPrefixProgressLine(text) ? `${bullet} ${formatted}` : formatted,
+        text:
+          !isLabelLine && prefix && shouldPrefixProgressLine(text)
+            ? `${bullet} ${formatted}`
+            : formatted,
         isLabelLine,
       };
     });
