feat(telegram): coalesce forwarded messages (#146)

docs/reference/config.md

@@ -30,6 +30,7 @@ chat_id = 123
 | `bot_token` | string | (required) | Telegram bot token from @BotFather. |
 | `chat_id` | int | (required) | Default chat id. |
 | `message_overflow` | `"trim"`\|`"split"` | `"trim"` | How to handle long final responses. |
+| `forward_coalesce_s` | float | `1.0` | Quiet window for combining a prompt with immediately-following forwarded messages; set `0` to disable. |
 | `voice_transcription` | bool | `false` | Enable voice note transcription. |
 | `voice_max_bytes` | int | `10485760` | Max voice note size (bytes). |
 | `voice_transcription_model` | string | `"gpt-4o-mini-transcribe"` | OpenAI transcription model name. |
@@ -106,4 +107,3 @@ model = "..."
 ```
 
 The shape is engine-defined.
-

docs/reference/transports/telegram.md

@@ -72,6 +72,26 @@ In group chats, changing trigger mode requires the sender to be an admin.
 State is stored in `telegram_chat_prefs_state.json` (chat default) and
 `telegram_topics_state.json` (topic overrides) alongside the config file.
 
+### Forwarded message coalescing
+
+Telegram sends a "comment + forwards" burst as separate messages, with the comment
+arriving first. Takopi waits briefly so it can attach the forwarded messages and
+run once.
+
+Behavior:
+
+- When a prompt candidate arrives, Takopi waits for `forward_coalesce_s` seconds
+  of quiet for that sender + chat/topic.
+- Forwarded messages arriving during the window are appended to the prompt
+  (separated by blank lines) and do not start their own runs.
+- Forwarded messages by themselves do not start runs.
+
+Configuration (under `[transports.telegram]`):
+
+```toml
+forward_coalesce_s = 1.0 # set 0 to disable the delay
+```
+
 ## Chat sessions (optional)
 
 If you chose the **handoff** workflow during onboarding, Takopi uses stateless mode