feat(telegram): persist progress in place with lossless overflow spill

anagnorisis2peripeteia · anagnorisis2peripeteia · commit c7fe3ec274d7 · 2026-06-06T16:37:17.000+01:00
Persisted progress keeps every accumulated tool/commentary line (no rolling
maxLines drop) and, when the live draft outgrows a message, rolls the overflow
into a fresh message via the existing supersede primitive (retain the filled
message) instead of truncating. At turn end the standing progress message is
finalized in place rather than deleted, and the final answer goes to a new
message. Gated on streaming.progress.persistProgress.
diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md
@@ -320,6 +320,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `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
+    - `streaming.progress.persistProgress` (default: `false`) **persists** the progress draft in place above the final answer instead of clearing it, and accumulates every tool/commentary line losslessly (spilling to a new message at the 4096-char limit rather than dropping the oldest line). Progress mode only
     - 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.
@@ -405,7 +406,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     - short DM/group/topic previews: OpenClaw keeps the same preview message and performs the final edit in place
     - long text finals that split into multiple Telegram messages reuse the existing preview as the first final chunk when possible, then send only the remaining chunks
-    - progress-mode finals clear the status draft and use normal final delivery instead of editing the draft into the answer
+    - progress-mode finals clear the status draft and use normal final delivery instead of editing the draft into the answer (unless `streaming.progress.persistProgress` is set, in which case the draft is finalized in place above the answer rather than cleared)
     - if the final edit fails before the completed text is confirmed, OpenClaw uses normal final delivery and cleans up the stale preview
 
     For complex replies (for example media payloads), OpenClaw falls back to normal final delivery and then cleans up the preview message.
diff --git a/docs/concepts/streaming.md b/docs/concepts/streaming.md
@@ -161,7 +161,7 @@ Telegram:
 
 - Uses `sendMessage` + `editMessageText` preview updates across DMs and group/topics.
 - Final text edits the active preview in place; long finals reuse that message for the first chunk and send only the remaining chunks.
-- `progress` mode keeps tool progress in an editable status draft, clears that draft at completion, and sends the final answer through normal delivery.
+- `progress` mode keeps tool progress in an editable status draft, clears that draft at completion, and sends the final answer through normal delivery. Set `streaming.progress.persistProgress: true` to instead **persist** the draft in place above the final answer (finalized, not cleared) and accumulate every tool/commentary line losslessly — spilling to a new message at the channel limit rather than dropping the oldest line. Default `false`.
 - If the final edit fails before the completed text is confirmed, OpenClaw uses normal final delivery and cleans up the stale preview.
 - Preview streaming is skipped when Telegram block streaming is explicitly enabled (to avoid double-streaming).
 - `/reasoning stream` can write reasoning to a transient preview that is deleted after final delivery.
diff --git a/extensions/telegram/src/bot-message-dispatch.test.ts b/extensions/telegram/src/bot-message-dispatch.test.ts
@@ -597,6 +597,48 @@ describe("dispatchTelegramMessage draft streaming", () => {
     expect(draftStream.clear).toHaveBeenCalledTimes(1);
   });
 
+  it("keeps persistProgress inert in partial mode (no lossless answer-lane spill)", async () => {
+    createTelegramDraftStream.mockReturnValue(createDraftStream());
+    dispatchReplyWithBufferedBlockDispatcher.mockImplementation(
+      async ({ dispatcherOptions, replyOptions }) => {
+        await replyOptions?.onPartialReply?.({ text: "Hi" });
+        await dispatcherOptions.deliver({ text: "Hi" }, { kind: "final" });
+        return { queuedFinal: true };
+      },
+    );
+    deliverReplies.mockResolvedValue({ delivered: true });
+
+    await dispatchWithContext({
+      context: createContext(),
+      streamMode: "partial",
+      telegramCfg: { streaming: { mode: "partial", progress: { persistProgress: true } } },
+    });
+
+    // Live persistProgress is progress-mode only: the answer-lane draft must not
+    // enable lossless spill in partial mode even when the flag is set.
+    expectDraftStreamParams({ losslessSpill: false });
+  });
+
+  it("enables lossless answer-lane spill only in progress mode with persistProgress", async () => {
+    createTelegramDraftStream.mockReturnValue(createDraftStream());
+    dispatchReplyWithBufferedBlockDispatcher.mockImplementation(
+      async ({ dispatcherOptions, replyOptions }) => {
+        await replyOptions?.onPartialReply?.({ text: "Hi" });
+        await dispatcherOptions.deliver({ text: "Hi" }, { kind: "final" });
+        return { queuedFinal: true };
+      },
+    );
+    deliverReplies.mockResolvedValue({ delivered: true });
+
+    await dispatchWithContext({
+      context: createContext(),
+      streamMode: "progress",
+      telegramCfg: { streaming: { mode: "progress", progress: { persistProgress: true } } },
+    });
+
+    expectDraftStreamParams({ losslessSpill: true });
+  });
+
   it("recovers forum thread context from a topic-scoped session key", async () => {
     const recordInboundSession = vi.fn(async () => undefined);
     const oldHistoryKey = "-1003774691294:topic:1";
diff --git a/extensions/telegram/src/bot-message-dispatch.ts b/extensions/telegram/src/bot-message-dispatch.ts
@@ -34,6 +34,7 @@ import {
   resolveChannelStreamingPreviewNativeToolProgress,
   resolveChannelStreamingPreviewNativeToolProgressAllowFrom,
   resolveChannelStreamingPreviewToolProgress,
+  resolveChannelStreamingProgressPersist,
   resolveTranscriptBackedChannelFinalText,
 } from "openclaw/plugin-sdk/channel-outbound";
 import type {
@@ -905,12 +906,22 @@ export const dispatchTelegramMessage = async ({
   const draftMinInitialChars = streamMode === "progress" ? 0 : DRAFT_MIN_INITIAL_CHARS;
   const progressSeed = `${route.accountId}:${chatId}:${threadSpec.id ?? ""}`;
   const mediaLocalRoots = getAgentScopedMediaLocalRoots(cfg, route.agentId);
+  const persistProgressEnabled = resolveChannelStreamingProgressPersist(telegramCfg);
   const createDraftLane = (laneName: LaneName, enabled: boolean): DraftLaneState => {
     const stream = enabled
       ? (telegramDeps.createTelegramDraftStream ?? createTelegramDraftStream)({
           api: bot.api,
           chatId,
           maxChars: draftMaxChars,
+          // Persisted progress must never drop accumulated lines: when the answer
+          // lane's live draft outgrows a message, spill into a new one losslessly.
+          // Progress mode only — in partial/block the compositor can still render
+          // tool progress into this lane, so an unguarded flag would change live
+          // preview overflow/retention for those modes. The persistProgressEnabled
+          // const stays guard-free (the stream-off accumulator needs it); only this
+          // live-draft usage is gated.
+          losslessSpill:
+            laneName === "answer" && streamMode === "progress" && persistProgressEnabled,
           thread: threadSpec,
           replyToMessageId: draftReplyToMessageId,
           minInitialChars: draftMinInitialChars,
@@ -1114,7 +1125,18 @@ export const dispatchTelegramMessage = async ({
     if (!activeAnswerDraftIsToolProgressOnly) {
       return false;
     }
-    await answerLane.stream?.clear();
+    if (streamMode === "progress" && progressDraft.persistProgressEnabled) {
+      // Persist-in-place (progress mode only): finalize the standing progress
+      // message rather than deleting it, then route the final answer into a fresh
+      // message so the tool/commentary log remains visible above the answer. The
+      // streamMode guard keeps persistProgress inert in partial/block modes —
+      // matching the skip-rotate gate below — so the flag only ever changes the
+      // live progress-draft path (stream-off persistence is handled separately by
+      // the #89890 accumulator, which has no answer-lane stream to reach here).
+      await answerLane.stream?.stop();
+    } else {
+      await answerLane.stream?.clear();
+    }
     answerLane.stream?.forceNewMessage();
     resetDraftLaneState(answerLane);
     suppressProgressDraftState();
@@ -1161,7 +1183,16 @@ export const dispatchTelegramMessage = async ({
   ) => {
     const split = splitTextIntoLaneSegments(update, isReasoning);
     for (const segment of split.segments) {
-      if (segment.lane === "answer") {
+      if (
+        segment.lane === "answer" &&
+        !(streamMode === "progress" && progressDraft.persistProgressEnabled)
+      ) {
+        // Persisted progress accumulates the live draft in ONE message: an inter-tool
+        // assistant segment must not rotate the answer lane. In progress mode the answer
+        // partial isn't streamed here anyway (updateDraftFromPartial returns early) — the
+        // text renders as commentary in the draft. Without this skip, each inter-tool
+        // commentary finalizes the draft into a separate PERSISTED message. The final
+        // answer rotates the draft separately at delivery (deliverFinalAnswerText).
         await prepareAnswerLaneForText();
       }
       if (segment.lane === "reasoning") {
diff --git a/extensions/telegram/src/config-schema.test.ts b/extensions/telegram/src/config-schema.test.ts
@@ -123,6 +123,22 @@ describe("telegram custom commands schema", () => {
     });
   });
 
+  it("accepts Telegram progress persistProgress config", () => {
+    expectTelegramConfigValid({
+      streaming: {
+        mode: "progress",
+        progress: { persistProgress: true },
+      },
+      accounts: {
+        ops: {
+          streaming: {
+            progress: { persistProgress: true },
+          },
+        },
+      },
+    });
+  });
+
   it("rejects removed DM thread reply policy keys", () => {
     expectTelegramConfigIssue({ dm: { threadReplies: "off" } }, "");
     expectTelegramConfigIssue(
diff --git a/extensions/telegram/src/draft-stream.test.ts b/extensions/telegram/src/draft-stream.test.ts
@@ -446,6 +446,34 @@ describe("createTelegramDraftStream", () => {
     expect(onSupersededPreview).not.toHaveBeenCalled();
   });
 
+  it("spills non-final overflow into a new retained message when losslessSpill is set", async () => {
+    const api = createMockDraftApi();
+    api.sendMessage
+      .mockResolvedValueOnce({ message_id: 17 })
+      .mockResolvedValueOnce({ message_id: 42 });
+    const onSupersededPreview = vi.fn();
+    const stream = createDraftStream(api, {
+      maxChars: 20,
+      losslessSpill: true,
+      onSupersededPreview,
+    });
+
+    stream.update("Hello world");
+    await stream.flush();
+    stream.update("Hello world foo bar baz qux");
+    await stream.flush();
+
+    // The filled message is kept and the overflow rolls into a fresh message
+    // while still streaming — nothing is truncated (contrast the lossy default above).
+    expect(api.sendMessage).toHaveBeenCalledTimes(2);
+    expect(api.sendMessage).toHaveBeenNthCalledWith(1, 123, "Hello world", undefined);
+    expect(api.sendMessage).toHaveBeenNthCalledWith(2, 123, "foo bar baz qux", undefined);
+    expect(onSupersededPreview).toHaveBeenCalledTimes(1);
+    const [superseded] = onSupersededPreview.mock.calls.at(0) ?? [];
+    expect(superseded.retain).toBe(true);
+    expect(superseded.messageId).toBe(17);
+  });
+
   it("continues in a new message when a final rendered preview crosses maxChars", async () => {
     const api = createMockDraftApi();
     api.sendMessage
diff --git a/extensions/telegram/src/draft-stream.ts b/extensions/telegram/src/draft-stream.ts
@@ -82,6 +82,13 @@ export function createTelegramDraftStream(params: {
   throttleMs?: number;
   /** Minimum chars before sending first message (debounce for push notifications) */
   minInitialChars?: number;
+  /**
+   * Lossless overflow handling for a still-streaming draft. When the live draft
+   * grows past `maxChars`, retain the filled message and roll the overflow into a
+   * fresh message (the same supersede-and-continue the final path uses) instead of
+   * truncating/freezing the preview. Used by persistent progress so no progress is dropped.
+   */
+  losslessSpill?: boolean;
   /** Optional preview renderer (e.g. markdown -> HTML + parse mode). */
   renderText?: (text: string) => TelegramDraftPreview;
   /** Called when a late send resolves after forceNewMessage() switched generations. */
@@ -95,6 +102,7 @@ export function createTelegramDraftStream(params: {
   );
   const throttleMs = Math.max(250, params.throttleMs ?? DEFAULT_THROTTLE_MS);
   const minInitialChars = params.minInitialChars;
+  const losslessSpill = params.losslessSpill === true;
   const chatId = params.chatId;
   const threadParams = buildTelegramThreadParams(params.thread);
   const replyToMessageId = normalizeTelegramReplyToMessageId(params.replyToMessageId);
@@ -215,6 +223,28 @@ export function createTelegramDraftStream(params: {
     if (renderedText.length > maxChars) {
       const chunkLength = findTelegramDraftChunkLength(currentText, maxChars, params.renderText);
       if (!streamState.final) {
+        if (losslessSpill && lastDeliveredText.length > deliveredTextOffset) {
+          // Lossless spill: the live draft outgrew maxChars. Retain the filled
+          // message and roll the overflow into a fresh message (the same
+          // supersede-and-continue the final path uses below) so accumulated
+          // progress is never truncated or dropped.
+          const supersededMessageId = streamMessageId;
+          const supersededTextSnapshot = lastSentText;
+          const supersededParseMode = lastSentParseMode;
+          const supersededVisibleSinceMs = streamVisibleSinceMs;
+          deliveredTextOffset = lastDeliveredText.length;
+          resetStreamToNewMessage({ keepFinal: false, keepPending: true, resetOffset: false });
+          if (typeof supersededMessageId === "number") {
+            params.onSupersededPreview?.({
+              messageId: supersededMessageId,
+              textSnapshot: supersededTextSnapshot,
+              parseMode: supersededParseMode,
+              visibleSinceMs: supersededVisibleSinceMs,
+              retain: true,
+            });
+          }
+          return await sendOrEditStreamMessage(trimmed);
+        }
         if (chunkLength > 0) {
           return await sendOrEditStreamMessage(
             trimmed.slice(0, deliveredTextOffset) + currentText.slice(0, chunkLength),
diff --git a/src/channels/progress-draft-compositor.ts b/src/channels/progress-draft-compositor.ts
@@ -14,6 +14,7 @@ import {
   resolveChannelProgressDraftMaxLineChars,
   resolveChannelProgressDraftMaxLines,
   resolveChannelStreamingProgressCommentary,
+  resolveChannelStreamingProgressPersist,
   resolveChannelStreamingPreviewToolProgress,
   resolveChannelStreamingSuppressDefaultToolProgressMessages,
   type StreamingCompatEntry,
@@ -46,6 +47,8 @@ export function createChannelProgressDraftCompositor(params: {
     params.active && resolveChannelStreamingPreviewToolProgress(params.entry);
   const commentaryProgressEnabled =
     params.active && resolveChannelStreamingProgressCommentary(params.entry);
+  const persistProgressEnabled =
+    params.active && resolveChannelStreamingProgressPersist(params.entry);
   const suppressDefaultToolProgressMessages =
     params.active &&
     resolveChannelStreamingSuppressDefaultToolProgressMessages(params.entry, {
@@ -135,9 +138,14 @@ export function createChannelProgressDraftCompositor(params: {
     }
     const progressLine = typeof line === "object" && line !== undefined ? line : normalized;
     const shouldStoreLine = previewToolProgressEnabled;
+    // Persisted progress must never drop the oldest line: keep every line and let
+    // the draft stream spill into a new message once it outgrows the char limit
+    // (lossless). Transient progress keeps the rolling maxLines cap.
     const nextLines = shouldStoreLine
       ? mergeChannelProgressDraftLine(lines, progressLine, {
-          maxLines: resolveChannelProgressDraftMaxLines(params.entry),
+          maxLines: persistProgressEnabled
+            ? Number.POSITIVE_INFINITY
+            : resolveChannelProgressDraftMaxLines(params.entry),
         })
       : lines;
     if (shouldStoreLine && nextLines === lines) {
@@ -185,6 +193,9 @@ export function createChannelProgressDraftCompositor(params: {
     get commentaryProgressEnabled() {
       return commentaryProgressEnabled;
     },
+    get persistProgressEnabled() {
+      return persistProgressEnabled;
+    },
     get suppressDefaultToolProgressMessages() {
       return suppressDefaultToolProgressMessages;
     },
@@ -284,7 +295,9 @@ export function createChannelProgressDraftCompositor(params: {
         noCompact: true,
       };
       lines = mergeChannelProgressDraftLine(lines, line, {
-        maxLines: resolveChannelProgressDraftMaxLines(params.entry),
+        maxLines: persistProgressEnabled
+          ? Number.POSITIVE_INFINITY
+          : resolveChannelProgressDraftMaxLines(params.entry),
       });
       await gate.startNow();
       return await render();
diff --git a/src/channels/streaming.ts b/src/channels/streaming.ts
@@ -729,6 +729,19 @@ export function resolveChannelStreamingProgressCommentary(
   return asBoolean(progress?.commentary) ?? defaultValue;
 }
 
+export function resolveChannelStreamingProgressPersist(
+  entry: StreamingCompatEntry | null | undefined,
+  defaultValue = false,
+): boolean {
+  const config = getChannelStreamingConfigObject(entry);
+  // No stream-mode guard: persistProgress is a user intent that applies in BOTH
+  // stream-on (persist the live draft in place) and stream-off (#89890 emits the
+  // accumulated set). Call sites that only make sense while streaming are already
+  // gated by the presence of an active draft/compositor.
+  const progress = asObjectRecord(config?.progress);
+  return asBoolean(progress?.persistProgress) ?? defaultValue;
+}
+
 export function resolveChannelStreamingPreviewCommandText(
   entry: StreamingCompatEntry | null | undefined,
   defaultValue: ChannelStreamingCommandTextMode = "raw",
@@ -1057,6 +1070,9 @@ export function formatChannelProgressDraftText(params: {
   const resolvedLabel = rawLabel;
   const maxLines = resolveChannelProgressDraftMaxLines(params.entry);
   const maxLineChars = resolveChannelProgressDraftMaxLineChars(params.entry);
+  // Persisted progress keeps EVERY line (no rolling maxLines drop); it spills to a new
+  // message at the channel char limit rather than dropping the oldest lines.
+  const persist = resolveChannelStreamingProgressPersist(params.entry);
   const formatLine = params.formatLine ?? ((line: string) => line);
   const bullet = params.bullet ?? "•";
   const rawLines: Array<string | ChannelProgressDraftLine | { draftLabel: string }> = resolvedLabel
@@ -1080,7 +1096,7 @@ export function formatChannelProgressDraftText(params: {
     .filter((line): line is { text: string; isLabelLine: boolean; prefix: boolean } =>
       Boolean(line),
     )
-    .slice(-maxLines)
+    .slice(persist ? 0 : -maxLines)
     .map(({ text, isLabelLine, prefix }) => {
       const formatted = isLabelLine ? text : formatLine(text);
       return {
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
@@ -305,6 +305,12 @@ describe("config schema", () => {
     expect(progressPropsFor("discord")).toHaveProperty("commentary");
     expect(progressPropsFor("slack")).toHaveProperty("commentary");
     expect(progressPropsFor("telegram")).toHaveProperty("commentary");
+    // persistProgress is a shared, channel-agnostic streaming.progress contract (like
+    // commentary/toolProgress): present in every channel's progress schema, not scoped to
+    // Telegram, even though Telegram is currently the only implementer.
+    expect(progressPropsFor("discord")).toHaveProperty("persistProgress");
+    expect(progressPropsFor("slack")).toHaveProperty("persistProgress");
+    expect(progressPropsFor("telegram")).toHaveProperty("persistProgress");
     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(
diff --git a/src/config/types.base.ts b/src/config/types.base.ts
diff --git a/src/config/zod-schema.providers-core.ts b/src/config/zod-schema.providers-core.ts
