Apus has two independent streaming layers, and there is no true token-delta streaming to channel messages:

• Block streaming (channels): emit completed blocks as the assistant writes. These are normal channel messages, not token deltas.
• Preview streaming (Telegram/Discord/Slack/Matrix/Mattermost/MS Teams): update a temporary preview message while generating (send + edits/appends).

Control UI startup status

After chat.send acknowledges an active run, the Gateway can send a typed, coarse startup status before assistant text or tool activity is visible. The Control UI shows this status beside the working indicator, with stages for workspace preparation, environment provisioning, context preparation, and model startup.

The first assistant delta or tool start permanently replaces startup status for that run. Approval status takes precedence while a tool is waiting for operator action. Worktree creation and initial cloud dispatch happen before a chat run exists, so their pre-run RPC progress is not presented as run startup status; environment provisioning appears here only when an active run reprovisions a reclaimed worker.

Block streaming (channel messages)

Block streaming sends assistant output in coarse chunks as it becomes available.

Model output
  └─ text_delta/events
       ├─ (blockStreamingBreak=text_end)
       │    └─ chunker emits blocks as buffer grows
       └─ (blockStreamingBreak=message_end)
            └─ chunker flushes at message_end
                   └─ channel send (block replies)

• text_delta/events: model stream events (may be sparse for non-streaming models).
• chunker: EmbeddedBlockChunker applying min/max bounds + break preference.
• channel send: actual outbound messages (block replies).

Controls (all under agents.defaults unless noted):

streaming.chunkMode: "newline" splits on blank lines (paragraph boundaries), not every newline, before falling back to length chunking once the text exceeds the limit.

Bundled channels spell these overrides as channels.<id>.streaming.{chunkMode,block.enabled,block.coalesce}. The flat *.chunkMode / *.blockStreaming / *.blockStreamingCoalesce spellings are rejected by validation. Run apus doctor --fix to migrate legacy configs into the nested shape before starting the Gateway. See the Doctor migration guidance.

Boundary semantics for blockStreamingBreak:

• text_end: stream blocks as soon as the chunker emits; flush on each text_end.
• message_end: wait until the assistant message finishes, then flush buffered output. Still uses the chunker if the buffered text exceeds maxChars, so it can emit multiple chunks at the end.

Pending text phases

Transports that resolve commentary at the tool boundary withhold durable block replies until the phase is known. Chat Completions and native Ollama (api: "ollama", /api/chat) wait until the assistant message finishes, including with blockStreamingBreak: "text_end": earlier text can still become tool narration. A long tool-free answer therefore produces no durable chunks during generation.

Ordinary final answers and length-limited partial answers remain deliverable. The independent live assistant/preview stream can still update while generating when enabled and supported by the channel.

Media delivery with block streaming

When a plugin uses before_agent_finalize to validate the built-in runtime's answer, assistant replies stay deferred until that decision completes. A later answer supersedes deferred text from earlier tool turns, including when the final answer is NO_REPLY. This applies to both reply blocks and preview updates; it does not retract replies that were already sent. Commentary remains live, and media, reasoning, and completed answers to earlier user inputs are preserved. Each steered user input gets its own delivered answer, even when its pending tools were skipped. Media from a superseded answer is delivered without its old caption.

With block streaming off, media-bearing assistant messages can still be sent at message boundaries, with their captions attached. Preview updates do not count as separately delivered captions.

Streaming media must use structured payload fields such as mediaUrl or mediaUrls; streamed text is not parsed as an attachment command. When block streaming sends media early, Apus remembers that delivery for the turn. If the final assistant payload repeats the same media URL, final delivery strips the duplicate media instead of sending the attachment again.

Exact duplicate final payloads are suppressed. If the final payload adds distinct text around media that was already streamed, Apus still sends the new text while keeping the media single-delivery. This prevents duplicate voice notes or files on channels such as Telegram.

Chunking algorithm (low/high bounds)

Block chunking is implemented by EmbeddedBlockChunker:

• Low bound: don't emit until buffer >= minChars (unless forced).
• High bound: prefer splits before maxChars; if forced, split at maxChars.
• Break preference chain: paragraph -> newline -> sentence -> whitespace -> hard break.
• Code fences: never split inside fences; when forced at maxChars, close and reopen the fence to keep Markdown valid.
• Tables: a Markdown table that fits in maxChars is kept in one chunk, even if that means breaking before it below minChars, so channels that render tables see the header and rows together. Larger tables split at row boundaries.

maxChars is clamped to the channel textChunkLimit, so you cannot exceed per-channel caps.

Coalescing (merge streamed blocks)

When block streaming is enabled, Apus can merge consecutive block chunks before sending them, reducing single-line spam while still providing progressive output.

• Coalescing waits for idle gaps (idleMs) before flushing.
• Buffers are capped by maxChars and flush if they exceed it.
• minChars prevents tiny fragments from sending until enough text accumulates (final flush always sends remaining text).
• Joiner is derived from blockStreamingChunk.breakPreference: paragraph -> \n\n, newline -> \n, sentence -> space.
• Channel overrides are available via *.streaming.block.coalesce (including per-account configs).
• Discord, Signal, and Slack default coalesce to { minChars: 1500, idleMs: 1000 } unless overridden.

Human-like pacing between blocks

When block streaming is enabled, add a randomized pause between block replies, after the first block, so multi-bubble responses feel more natural.

Override per agent via agents.entries.*.humanDelay. Applies only to block replies, not final replies or tool summaries.

"Stream chunks or everything"

• Stream chunks: blockStreamingDefault: "on" + blockStreamingBreak: "text_end" (emit as you go). Non-Telegram channels also need *.streaming.block.enabled: true.
• Stream everything at end: blockStreamingBreak: "message_end" (flush once, possibly multiple chunks if very long).
• No block streaming: blockStreamingDefault: "off" (final text replies; media-bearing messages can still be sent at message boundaries).

Block streaming follows agents.defaults.blockStreamingDefault unless a channel or account sets *.streaming.block.enabled explicitly. QQ Bot has no streaming.block keys and streams block replies unless channels.qqbot.streaming.mode is "off". Channels can stream a live preview (channels.<channel>.streaming.mode) without block replies. The blockStreaming* defaults live under agents.defaults, not the config root.

For Discord and Telegram, an explicitly configured non-off preview mode takes precedence over inherited agents.defaults.blockStreamingDefault: "on". Set that channel's streaming.block.enabled: true when block replies should override its preview. For ordinary single-agent turns, if a reply-modifying hook prevents Telegram previews, completed blocks use normal hooked delivery unless block streaming is explicitly disabled globally or for Telegram. Configured multi-agent group-thread turns do not use this forced fallback; like other turns without a preview, they retain the configured block delivery policy.

Preview streaming modes

Canonical key: channels.<channel>.streaming (nested { mode, ... }; legacy top-level boolean/string spellings are rewritten by apus doctor --fix).

streaming.mode: "block" is a preview-streaming mode for edit-capable channels such as Discord and Telegram; it does not by itself enable channel block delivery there. Use streaming.block.enabled for normal block replies. Microsoft Teams is the exception: it has no draft-preview block transport, so streaming.mode: "block" disables native streaming entirely and the reply lands as regular block delivery instead of native partial/progress streaming. Mattermost also differs: in block mode it rotates the preview between completed text and tool-activity blocks, so earlier blocks stay visible as separate posts instead of being overwritten in one editable draft.

Channel mapping

Discord, Telegram, and Slack default to progress when streaming is unset. Mattermost and MS Teams default to partial. Explicitly configured modes remain unchanged; off disables previews.

Preview chunk config (streaming.preview.chunk.*, e.g. under channels.discord.streaming or channels.telegram.streaming) defaults to minChars: 200, maxChars: 800 (clamped to the channel textChunkLimit), and breakPreference: "paragraph".

Slack-only:

• channels.slack.streaming.nativeTransport toggles Slack native streaming API calls (chat.startStream/chat.appendStream/chat.stopStream) when channels.slack.streaming.mode="partial" (nativeTransport defaults to true).
• Slack native streaming and Slack assistant thread status require a reply thread target. Top-level DMs do not show that thread-style preview, but can still use Slack draft preview posts and edits.

Legacy key migration

Runtime behavior

Telegram

• Uses sendMessage + editMessageText preview updates across DMs and group/topics; final text edits the active preview in place. Telegram ephemeral 30-second "typing" drafts (sendMessageDraft) are not used for answer streaming.
• Short initial previews are still debounced for push-notification UX, but materialize after a bounded delay so active runs do not stay visually silent.
• Long finals reuse the preview message for the first chunk and send only the remaining chunks.
• block mode rotates the preview into a new message at streaming.preview.chunk.maxChars (default 800, capped at Telegram's 4096 edit limit); other modes grow one preview up to 4096 characters.
• progress mode keeps tool progress in an editable status draft, materializes the status label when answer streaming is active but no tool line is available yet, clears the draft at completion, and sends the final answer through normal delivery. When the parent yields to accepted subagents, the same draft keeps updating until they settle; see Subagent yield handoff.
• Plan previews use native checkboxes when channels.telegram.richMessages is true; otherwise they use readable HTML checklists. Completed steps are checked, and the active step is marked "in progress".
• If the final edit fails before the completed text is confirmed, Apus 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.
• Telegram selected quote replies are an exception: when replyToMode is not "off" and selected quote text is present, Apus skips the answer preview stream for that turn (the final answer must go through the native quote-reply path) so tool-progress preview lines cannot render. Current-message replies without selected quote text still keep preview streaming. See Telegram channel docs for details.

Discord

• Uses send + edit preview messages.
• block mode updates the preview at chunk boundaries while preserving the answer's paragraph separators and code fences in the edited message.
• Preview streaming is skipped when Discord block streaming is explicitly enabled.
• progress is quiet by default: headline, authored commentary and reasoning, plan milestones, approval requests, and safe current-operation and delegated-task status. Status does not require a utility model or a model-authored preamble. Intermediate tool failures and nonzero command exits are hidden. streaming.progress.toolProgress: true adds the rolling tool log with its icons. Telegram shares the safe work-status presentation; other channels retain their existing progress layouts.
• progress mode deletes the status draft once the final answer is delivered, so busy channels keep no orphaned tool log above the reply. Error finals keep the draft as the record of the failed turn.
• Final media, error, and explicit-reply payloads cancel pending previews without flushing a new draft, then use normal delivery.

Slack

• Compact progress with streaming.progress.toolProgress: false preserves the latest model preamble. With commentary: true, label: false, and maxLines: 1, it is one italicized, temporary message without reasoning, tool icons, command failures, plans, or file-edit counters. The first post waits for a complete preamble so its Slack notification is readable; later preambles edit that message. Actionable approval requests remain visible. The final answer is a new reply, and only after Slack confirms delivery is the preview deleted. Successful silent turns also remove their preview; explicit message-tool posts remain durable.
• partial can use Slack native streaming (chat.startStream/append/stop) when available.
• block uses append-style draft previews.
• In reply threads, progress streams Slack's native agent card by default: one message carries narration, the live plan card (authored milestones, or one work-summary row until streaming.progress.toolProgress: true gives each tool call a row), and the final answer. Routine progress updates coalesce at one-second intervals; attention and completion flush immediately. The card appears only for turns that do real work, so plain questions are answered without one. streaming.progress.nativeTaskCards: false falls back to the Block Kit session card. By default, it shows commentary and text, including italic narration and reasoning, actionable approval requests, and a plain title only when explicitly configured. Finished cards keep the Open in Apus or Open work session link when available. streaming.progress.toolProgress: true adds tool activity, the plan checklist, intermediate error and recovery rows, and tool/file/time totals while working; finished detailed cards retain only file diff totals. Neither mode adds emoji, bold text, or status headings, except a plain Failed line when the turn fails. A card is posted only once it has something to show, so a default turn with only tool activity shows no card; a working or successful card whose last visible row goes away, such as a resolved approval, is deleted. The assistant's final text and error replies use normal delivery; failed turns keep their card marked Failed even without a reply.
• Cards include Open in Apus only when the session is actually openable: gateway.publicOrigin is set and gateway.controlUi.enabled is not false.
• Without a reply thread, default progress turns leave only the final answer and use a temporary hourglass_flowing_sand typing reaction during work. Configured typingReaction wins; "" disables it. Any explicit streaming.progress setting opts top-level turns into a preview, including commentary: true or a custom label. The sole exception is nativeTaskCards: true, which only affects threads. Empty progress settings stay quiet. The rule uses the merged root and account settings. This includes plain top-level DMs; Agent View and Assistant View keep their threaded behavior. Explicit off, partial, and block modes are unchanged.
• Native and draft preview streaming suppress block replies for that turn, so a Slack reply is streamed by one delivery path only.
• A successful turn with no visible reply still deletes its draft card. A failed no-reply turn keeps its progress card, marked Failed, or posts a plain Failed card if none appeared while working.

Mattermost

• In partial mode, streams thinking and partial reply text into a single draft preview post that finalizes in place when the final answer is safe to send.
• In progress mode, streams thinking and tool activity into a single status preview that finalizes in place when the final answer is safe to send.
• In block mode, rotates between completed text and tool-activity posts; parallel and consecutive tool updates share the current tool-activity post.
• Falls back to sending a fresh final post if the preview post was deleted or is otherwise unavailable at finalize time.
• Final media/error payloads cancel pending preview updates before normal delivery instead of flushing a temporary preview post.

Matrix

• Draft previews finalize in place when the final text can reuse the preview event.
• Media-only, error, and reply-target-mismatch finals cancel pending preview updates before normal delivery; an already-visible stale preview is redacted.

Tool-progress preview updates

Preview streaming can also include tool-progress updates: short status lines like "searching the web", "reading file", or "calling tool" that appear in the same preview message while tools are running, ahead of the final reply. In Codex app-server mode, Codex preamble/commentary messages use this same preview path, so short "I am checking..." progress notes can stream into the editable draft without becoming part of the final answer. This keeps multi-step tool turns visually alive instead of silent between the first thinking preview and the final answer.

Responses commentary keeps each message item's identity through tool handoffs. Later tool updates do not replay earlier commentary as an extra combined preamble.

Long-running tools may emit typed progress before they return. For example, web_fetch arms a five-second timer when it starts: if the fetch is still pending, the preview shows Fetching page content...; if the fetch finishes or is canceled before then, no progress line is emitted. The later final tool result is still delivered normally to the model.

Supported surfaces:

• Discord, Slack, Telegram, and Matrix stream tool-progress and Codex preamble updates into the live preview edit by default when preview streaming is active. Microsoft Teams uses its native progress stream in personal chats.
• Telegram has shipped with tool-progress preview updates enabled since v2026.4.22; keeping them enabled preserves that released behavior.
• Mattermost folds tool activity into one preview post in partial and progress modes, or one tool-activity post between text blocks in block mode (see above).
• Tool-progress edits follow the active preview streaming mode; they are skipped when preview streaming is off or when block streaming has taken over the message. On Telegram, streaming.mode: "off" is final-only: generic progress chatter is also suppressed instead of delivered as standalone status messages, while approval prompts, media payloads, and errors still route normally.
• streaming.preview.toolProgress (default true) controls tool-progress lines in partial and block previews; streaming.progress.toolProgress (default false) opts the progress draft into the rolling tool log. To keep tool-progress lines visible while hiding command/exec text, set streaming.preview.commandText or streaming.progress.commandText to "status" (the default). Set either option to "raw" to opt into command text. This policy is shared by draft/progress channels that use Apus's compact progress renderer, including Discord, Matrix, Microsoft Teams, Mattermost, Slack session cards, and Telegram. To disable preview edits entirely, set streaming.mode to off.

Progress draft rendering

Progress cards replace the complete plan state in partial, block, and progress previews where plan updates are enabled. Visible steps follow the channel's line limits. Clearing a card removes its checklist and status while preserving other activity; an otherwise empty draft is deleted where the channel supports deletion. Microsoft Teams replaces a cleared interim preview with its progress label. With streaming.progress.label: false, Teams retains the interim preview until the next update or final reply. Failed or blocked writes leave the previous plan in place. Active previews retain a safe failure notice.

Progress-mode drafts (streaming.progress.*) have these per-channel settings:

Slack always renders progress mode as its fixed session-card layout; these limits still bound the activity rows and plan text inside that card.

Commentary progress lane

Beyond tool-progress, the compact progress renderer can surface one more lane in the draft:

• streaming.progress.commentary - render the model's pre-tool commentary (a short "I'll check... then..." narration) interleaved with tool lines in the progress draft. On Discord and Telegram in progress mode, the same preamble supplies the status headline even when this optional lane is off; other channels keep their existing progress behavior. See Progress drafts.

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

Keep progress lines visible but hide raw command/exec text:

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

Use the same shape under another compact progress channel key, for example channels.discord, channels.matrix, channels.msteams, channels.mattermost, or Slack draft previews. For progress-draft mode, put the same policy under streaming.progress:

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

Related

• Agent loop - the turn lifecycle that emits these stream events
• Channel outbound API - shared preview, durable send, and finalization APIs
• Progress drafts - visible work-in-progress messages that update during long turns
• Messages - message lifecycle and delivery
• Retry - retry behavior on delivery failure
• Typing indicators - typing state shown while a turn is in flight
• Channels - per-channel streaming support