fix: add provider retry policy

docs/concepts/retry.md

@@ -0,0 +1,58 @@
+---
+summary: "Retry policy for outbound provider calls"
+read_when:
+  - Updating provider retry behavior or defaults
+  - Debugging provider send errors or rate limits
+---
+# Retry policy
+
+## Goals
+- Retry per HTTP request, not per multi-step flow.
+- Preserve ordering by retrying only the current step.
+- Avoid duplicating non-idempotent operations.
+
+## Defaults
+- Attempts: 3
+- Max delay cap: 30000 ms
+- Jitter: 0.1 (10 percent)
+- Provider defaults:
+  - Telegram min delay: 400 ms
+  - Discord min delay: 500 ms
+
+## Behavior
+### Discord
+- Retries only on rate-limit errors (HTTP 429).
+- Uses Discord `retry_after` when available, otherwise exponential backoff.
+
+### Telegram
+- Retries on transient errors (429, timeout, connect/reset/closed, temporarily unavailable).
+- Uses `retry_after` when available, otherwise exponential backoff.
+- Markdown parse errors are not retried; they fall back to plain text.
+
+## Configuration
+Set retry policy per provider in `~/.clawdbot/clawdbot.json`:
+
+```json5
+{
+  telegram: {
+    retry: {
+      attempts: 3,
+      minDelayMs: 400,
+      maxDelayMs: 30000,
+      jitter: 0.1
+    }
+  },
+  discord: {
+    retry: {
+      attempts: 3,
+      minDelayMs: 500,
+      maxDelayMs: 30000,
+      jitter: 0.1
+    }
+  }
+}
+```
+
+## Notes
+- Retries apply per request (message send, media upload, reaction, poll, sticker).
+- Composite flows do not retry completed steps.

docs/gateway/configuration.md

@@ -493,6 +493,12 @@ Set `telegram.enabled: false` to disable automatic startup.
     streamMode: "partial",               // off | partial | block (draft streaming)
     actions: { reactions: true },        // tool action gates (false disables)
     mediaMaxMb: 5,
+    retry: {                             // outbound retry policy
+      attempts: 3,
+      minDelayMs: 400,
+      maxDelayMs: 30000,
+      jitter: 0.1
+    },
     proxy: "socks5://localhost:9050",
     webhookUrl: "https://example.com/telegram-webhook",
     webhookSecret: "secret",
@@ -505,6 +511,7 @@ Draft streaming notes:
 - Uses Telegram `sendMessageDraft` (draft bubble, not a real message).
 - Requires **private chat topics** (message_thread_id in DMs; bot has topics enabled).
 - `/reasoning stream` streams reasoning into the draft, then sends the final answer.
+Retry policy defaults and behavior are documented in [Retry policy](/concepts/retry).
 
 ### `discord` (bot transport)
 
@@ -559,7 +566,13 @@ Configure the Discord bot by setting the bot token and optional gating:
         }
       }
     },
-    historyLimit: 20                        // include last N guild messages as context
+    historyLimit: 20,                       // include last N guild messages as context
+    retry: {                                // outbound retry policy
+      attempts: 3,
+      minDelayMs: 500,
+      maxDelayMs: 30000,
+      jitter: 0.1
+    }
   }
 }
 ```
@@ -571,6 +584,7 @@ Reaction notification modes:
 - `own`: reactions on the bot's own messages (default).
 - `all`: all reactions on all messages.
 - `allowlist`: reactions from `guilds.<id>.users` on all messages (empty list disables).
+Retry policy defaults and behavior are documented in [Retry policy](/concepts/retry).
 
 ### `slack` (socket mode)
 

docs/providers/discord.md

@@ -5,7 +5,7 @@ read_when:
 ---
 # Discord (Bot API)
 
-Updated: 2025-12-07
+Updated: 2026-01-07
 
 Status: ready for DM and guild text channels via the official Discord bot gateway.
 
@@ -122,6 +122,12 @@ Example “single server, only allow me, only allow #help”:
           help: { allow: true, requireMention: true }
         }
       }
+    },
+    retry: {
+      attempts: 3,
+      minDelayMs: 500,
+      maxDelayMs: 30000,
+      jitter: 0.1
     }
   }
 }
@@ -154,6 +160,9 @@ Notes:
 - Reply context is injected when a message references another message (quoted content + ids).
 - Native reply threading is **off by default**; enable with `discord.replyToMode` and reply tags.
 
+## Retry policy
+Outbound Discord API calls retry on rate limits (429) using Discord `retry_after` when available, with exponential backoff and jitter. Configure via `discord.retry`. See [Retry policy](/concepts/retry).
+
 ## Config
 
 ```json5
@@ -235,6 +244,7 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 - `guilds.<id>.reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`).
 - `mediaMaxMb`: clamp inbound media saved to disk.
 - `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20, `0` disables).
+- `retry`: retry policy for outbound Discord API calls (attempts, minDelayMs, maxDelayMs, jitter).
 - `actions`: per-action tool gates; omit to allow all (set `false` to disable).
   - `reactions` (covers react + read reactions)
   - `stickers`, `polls`, `permissions`, `messages`, `threads`, `pins`, `search`

docs/providers/telegram.md

@@ -162,6 +162,9 @@ Reasoning stream (Telegram only):
 - If `telegram.streamMode` is `off`, reasoning stream is disabled.
 More context: [Streaming + chunking](/concepts/streaming).
 
+## Retry policy
+Outbound Telegram API calls retry on transient network/429 errors with exponential backoff and jitter. Configure via `telegram.retry`. See [Retry policy](/concepts/retry).
+
 ## Agent tool (reactions)
 - Tool: `telegram` with `react` action (`chatId`, `messageId`, `emoji`).
 - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
@@ -215,6 +218,7 @@ Provider options:
 - `telegram.textChunkLimit`: outbound chunk size (chars).
 - `telegram.streamMode`: `off | partial | block` (draft streaming).
 - `telegram.mediaMaxMb`: inbound/outbound media cap (MB).
+- `telegram.retry`: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).
 - `telegram.proxy`: proxy URL for Bot API calls (SOCKS/HTTP).
 - `telegram.webhookUrl`: enable webhook mode.
 - `telegram.webhookSecret`: webhook secret (optional).