fix(auto-reply): coalesce block replies and document streaming toggles (#536) (thanks @mcinteerj)

docs/concepts/agent.md

@@ -88,6 +88,8 @@ via `agents.defaults.blockStreamingDefault: "off"` if you only want the final re
 Tune the boundary via `agents.defaults.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end).
 Control soft block chunking with `agents.defaults.blockStreamingChunk` (defaults to
 800–1200 chars; prefers paragraph breaks, then newlines; sentences last).
+Coalesce streamed chunks with `agents.defaults.blockStreamingCoalesce` to reduce
+single-line spam (idle-based merging before send).
 Verbose tool summaries are emitted at tool start (no debounce); Control UI
 streams tool output via agent events when available.
 More details: [Streaming + chunking](/concepts/streaming).

docs/concepts/streaming.md

@@ -33,8 +33,10 @@ Legend:
 
 **Controls:**
 - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (default on).
+- Provider overrides: `*.blockStreaming` (and per-account variants) to force `"on"`/`"off"` per provider.
 - `agents.defaults.blockStreamingBreak`: `"text_end"` or `"message_end"`.
 - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
+- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (merge streamed blocks before send).
 - Provider hard cap: `*.textChunkLimit` (e.g., `whatsapp.textChunkLimit`).
 - Discord soft cap: `discord.maxLinesPerMessage` (default 17) splits tall replies to avoid UI clipping.
 
@@ -54,6 +56,20 @@ Block chunking is implemented by `EmbeddedBlockChunker`:
 
 `maxChars` is clamped to the provider `textChunkLimit`, so you can’t exceed per-provider caps.
 
+## Coalescing (merge streamed blocks)
+
+When block streaming is enabled, Clawdbot can **merge consecutive block chunks**
+before sending them out. This reduces “single-line spam” while still providing
+progressive output.
+
+- Coalescing waits for **idle gaps** (`idleMs`) before flushing.
+- Buffers are capped by `maxChars` and will 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).
+- Provider overrides are available via `*.blockStreamingCoalesce` (including per-account configs).
+
 ## “Stream chunks or everything”
 
 This maps to:

docs/gateway/configuration-examples.md

@@ -215,6 +215,9 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
         maxChars: 1200,
         breakPreference: "paragraph"
       },
+      blockStreamingCoalesce: {
+        idleMs: 400
+      },
       timeoutSeconds: 600,
       mediaMaxMb: 5,
       typingIntervalSeconds: 5,

docs/gateway/configuration.md

@@ -1142,6 +1142,7 @@ See [/concepts/session-pruning](/concepts/session-pruning) for behavior details.
 
 Block streaming:
 - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (default on).
+- Provider overrides: `*.blockStreaming` (and per-account variants) to force block streaming on/off.
 - `agents.defaults.blockStreamingBreak`: `"text_end"` or `"message_end"` (default: text_end).
 - `agents.defaults.blockStreamingChunk`: soft chunking for streamed blocks. Defaults to
   800–1200 chars, prefers paragraph breaks (`\n\n`), then newlines, then sentences.
@@ -1151,6 +1152,12 @@ Block streaming:
     agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } }
   }
   ```
+- `agents.defaults.blockStreamingCoalesce`: merge streamed blocks before sending.
+  Defaults to `{ idleMs: 400 }` and inherits `minChars` from `blockStreamingChunk`
+  with `maxChars` capped to the provider text limit.
+  Provider overrides: `whatsapp.blockStreamingCoalesce`, `telegram.blockStreamingCoalesce`,
+  `discord.blockStreamingCoalesce`, `slack.blockStreamingCoalesce`, `signal.blockStreamingCoalesce`,
+  `imessage.blockStreamingCoalesce`, `msteams.blockStreamingCoalesce` (and per-account variants).
 See [/concepts/streaming](/concepts/streaming) for behavior + chunking details.
 
 Typing indicators: