Progress drafts turn one channel message into a live status line while an agent works, instead of a stack of temporary "still working" replies. Set channels.<channel>.streaming.mode: "progress" and Apus creates the message once real work starts, edits it as the agent reads, plans, calls tools, or waits for approval, then delivers the final answer.

Checking the streaming behavior and running the focused tests.
✅ Read the channel docs
▸ Run the focused tests
▢ Summarize the result

The default draft shows a status headline, authored plan steps, and approval requests. On Discord and Telegram, it also keeps the current operation and delegated task status visible without a detailed tool log or utility model. Intermediate tool failures and nonzero command exits stay out of the draft. Set streaming.progress.toolProgress: true to add a rolling tool log, including tool failures, with rows such as Bash: run tests. Discord and Telegram prefix each tool row with a text glyph for its tool, such as 📖 Read: from docs/index.md; other channels keep plain rows. Channel plugins opt in through the toolIcons option of createChannelProgressDraftCompositor.

Quick start

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
      },
    },
  },
}

Defaults from here: a start delay of 1.5 seconds, a quiet status draft while useful work happens, and suppression of the older standalone progress messages for that turn. Raw tool-line drafts use an automatic one-word label; a status headline omits that redundant title unless you configure one explicitly.

This page covers the progress-draft experience and its config knobs. For the full streaming-mode matrix, per-channel runtime notes, and legacy key migration, see Streaming and chunking.

What users see

The status headline sits above the progress lines. With progress.toolProgress: true, tool rows remain visible underneath it.

For raw tool progress, the label appears once the agent starts meaningful work and stays busy for the initial delay. It sits at the top of the rolling progress-line list, so it scrolls away once enough concrete work lines appear. The implicit label is hidden while a status headline is present unless you configure one explicitly. Plain text-only replies never show a progress draft; a line appears only for real work updates, for example Bash: run tests, Web Search: for "discord edit message", or Write: to /tmp/file.

Final delivery depends on the channel and transport. Apus either finalizes the draft or sends a separate answer and cleans up or stops updating the draft (see Finalization).

Choose a mode

channels.<channel>.streaming.mode controls the visible in-progress behavior:

Pick progress when users care more about "what is happening" than watching answer text stream token by token; partial when the answer text itself is the progress signal; block for larger preview chunks. On Discord and Telegram, streaming.mode: "block" is still preview streaming, not normal block-reply delivery — use streaming.block.enabled for that.

Configure labels

Progress labels live under channels.<channel>.streaming.progress. The default raw tool-line label is "auto", which uses the plain built-in Working label. A status headline hides that implicit label; set label: "auto" explicitly if you want a label above it too:

Working

Use a fixed label:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: "Investigating",
        },
      },
    },
  },
}

Use your own label pool (still picked at random/by seed when label: "auto"):

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: "auto",
          labels: ["Checking", "Reading", "Testing", "Finishing"],
        },
      },
    },
  },
}

Hide the label and show only progress lines:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: false,
        },
      },
    },
  },
}

Control progress lines

Progress lines come from real run events: tool starts, item updates, task plans, approvals, command output, patch summaries, and similar agent activity. progress.toolProgress decides whether ordinary tool calls become rolling rows underneath the status headline. It defaults to false on every channel, which keeps the draft quiet: the headline, enabled commentary and reasoning, plan milestones, and approval requests still appear. Intermediate tool failures and nonzero command exits are hidden along with other tool rows; failures that prevent the turn from completing still appear through normal error delivery. Set it to true for the rolling tool log. Successful background-process polls and internal waits do not add routine rows. Failed calls still follow the selected tool-progress policy; /verbose retains their diagnostic summaries.

On Discord and Telegram, the quiet draft keeps one current-operation status and bounded delegated-task status rows. These use public operation names and task labels, never command text, arguments, child prose, or results. A late completion for an older operation cannot replace the currently displayed one. Other progress channels retain their existing presentation. With the tool log enabled, lifecycle updates reuse a row for each worker. Messages to workers get separate entries because sending a message does not prove that a worker started running. Delegation prompts are not included in these progress rows.

Tools can also emit typed progress while a single call is still running. That is how a slow fetch or search updates the visible draft before the tool returns its final result. The progress update is a partial tool result with empty model content and explicit public channel metadata:

{
  "content": [],
  "progress": {
    "text": "Fetching page content...",
    "visibility": "channel",
    "privacy": "public",
    "id": "web_fetch:fetching"
  }
}

Apus renders only progress.text in the channel progress UI. The normal tool result still arrives later as content/details and is the only part returned to the model.

When adding progress to a tool, emit a short, generic message and delay it until the operation has been pending long enough to be useful. web_fetch does exactly this with a 5-second delay:

const clearProgressTimer = scheduleToolProgress(
  onUpdate,
  { text: "Fetching page content...", id: "web_fetch:fetching" },
  5_000,
  { signal },
);

try {
  return await runToolWork();
} finally {
  clearProgressTimer();
}

Fast calls show no progress line; long calls show one while still pending; canceled calls clear the timer before stale progress can appear. Progress text is a public UI side channel, so it must never include secrets, raw arguments, fetched content, command output, or page text.

Detail mode

Apus uses the same formatter for progress drafts and /verbose:

{
  agents: {
    defaults: {
      toolProgressDetail: "explain", // explain | raw
    },
  },
}

"explain" is the default and keeps drafts stable with concise labels. "raw" appends underlying tool detail when available. Command text also requires the explicit streaming.progress.commandText: "raw" opt-in below. With that opt-in, a node --check /tmp/app.js call renders differently by mode:

Command/exec text

streaming.progress.commandText (default "status") controls how much command detail shows next to exec/bash progress lines, independent of the detail mode above. Set it to "raw" to opt into command text; keep "status" to show only the tool-progress status:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          toolProgress: true,
          commandText: "raw",
        },
      },
    },
  },
}

Commentary lane

streaming.progress.commentary (default false) interleaves the model's pre-tool commentary/preamble narration (💬, for example "I'll check... then ...") with tool lines in the draft. See Streaming and chunking for the shared config shape across channels.

With the commentary lane enabled, preambles render only as those interleaved 💬 lines; the status headline below stays out of the way so the lane keeps its documented shape.

Status headline

On Discord and Telegram in progress mode, the model's typed pre-tool preamble becomes the draft's status headline whenever it is available. Other progress-mode channels keep their existing status behavior. The headline is on by default and does not bypass the normal activity gate for short turns; enabling streaming.progress.commentary hands preambles to the interleaved commentary lane instead.

On Discord, when a utility model resolves for the agent — an explicit utilityModel, or the primary provider's declared small-model default (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5) — it supplies a short plain-language filler when the model emits no preamble or has been quiet for about 20 seconds (Telegram's headline is preamble-only today):

Updating the default model in your config, then restarting the gateway to pick
it up. One agent listing call failed and is being retried.

Utility narration is on by default (streaming.progress.narration, default true) and never falls back to the primary model: it runs only with an explicit utilityModel or a provider-declared default for the agent's primary provider. Set utilityModel: "" to disable utility routing entirely. When progress.toolProgress is enabled, tool lines keep accumulating underneath. Draft edits still wait for the normal activity gate and an actual text change, which avoids flashes on fast turns and reduces edit churn in busy channels. Set narration: false to disable only the utility-model filler; model preamble headlines remain enabled:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          narration: false,
        },
      },
    },
  },
}

Narration input is bounded and redacted: the utility model receives the inbound request text plus the same compact, redacted tool summaries the draft would render — never raw command output or tool results. With commandText: "status", narration input also omits exec/bash command text, matching what the draft shows.

Narration belongs to the current turn. Ending or replacing that turn cancels its pending utility-model request and prevents late results from updating the draft. Tool activity that accumulates during a narration request is reconsidered when that request finishes, so an eligible status update needs no additional event.

Line limits

Limit how many lines stay visible (default 8):

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          maxLines: 4,
        },
      },
    },
  },
}

With toolProgress: true, command exit rows and failed item rows from any named tool use ordinary tool-log capacity. This includes built-in, plugin, and custom tools without maintaining a name list. One rolling activity slot remains visible alongside a plan, so a failed row appears when it occurs, then scrolls out as newer activity arrives. Approval requests, blocked/error states, and unnamed failures still take priority. With the tool log hidden, tool failures and nonzero exits are hidden too; approval requests remain visible.

Progress lines are compacted automatically to reduce chat-bubble reflow while the draft is edited, and Apus truncates long lines so repeated draft edits do not wrap differently on every update. The default per-line budget is 120 characters; prose cuts at a word boundary, while long details such as paths or raw commands are shortened with a middle ellipsis so the suffix stays visible.

Tune the per-line budget:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          maxLineChars: 160,
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          toolProgress: true,
        },
      },
    },
  },
}

Channels without safe edit support fall back to typing indicators or final-only delivery. See Streaming and chunking for the full runtime-behavior breakdown per channel.

Finalization

When the final answer is ready, Apus tries to keep the chat clean:

• A Telegram or Discord progress draft handed off to accepted announcing subagents stays visible after the parent yields and keeps showing child status and prepared operation names; the final answer is separate. See Subagent yield handoff.

• Otherwise, in progress mode on Discord, the final answer is sent as a fresh message and the status draft is deleted once that answer is delivered. Busy channels keep no orphaned tool log above the reply; error finals keep the draft as the visible record of the failed turn.

• If the draft can safely become the final answer (partial/block modes), Apus edits it in place.

• Slack's compact progress style posts the final answer as a new message and deletes its temporary drafts after confirmed delivery. Failed delivery keeps the draft visible.

• If the channel uses native progress streaming, Apus finalizes that stream when the native transport accepts the final text.

• Otherwise (media, an approval prompt, an explicit reply target, too many chunks, or a failed edit/send) Apus sends the final answer through the normal channel delivery path instead of overwriting the draft.

The fallback is intentional: sending a fresh final answer beats losing text, mis-threading a reply, or overwriting a draft with a payload the channel cannot represent safely.

Troubleshooting

I only see the final answer.

Check that channels.<channel>.streaming.mode is progress for the account or channel that handled the message. Some group or quote-reply paths disable draft previews for a turn when the channel cannot safely edit the right message.

I see the label but no tool lines.

Check streaming.progress.toolProgress. It defaults to false, which keeps the single draft but hides the rolling tool rows; set it to true for the full tool log.

I see a fresh final message instead of an edited draft.

That is the safety fallback described in Finalization. It can happen for media replies, long answers, explicit reply targets, old Telegram drafts, missing Slack thread targets, deleted preview messages, or failed native stream finalization.

I still see standalone progress messages.

Progress mode suppresses default standalone tool-progress messages whenever a draft is active. If standalone messages still appear, confirm the turn is actually using progress mode and not streaming.mode: "off" or a channel path that cannot create a draft for that message.

Teams behaves differently from Discord or Telegram.

Microsoft Teams uses a native stream in personal chats instead of the generic send-and-edit preview transport, and maps streaming.mode: "block" to Teams block delivery because it has no draft-preview block mode like Discord and Telegram.

Related

• Streaming and chunking
• Messages
• Channel configuration
• Discord
• Matrix
• Microsoft Teams
• Slack
• Telegram
• Mattermost