feat: add typing mode controls

docs/concepts/typing-indicators.md

@@ -0,0 +1,58 @@
+---
+summary: "When Clawdbot shows typing indicators and how to tune them"
+read_when:
+  - Changing typing indicator behavior or defaults
+---
+# Typing indicators
+
+Typing indicators are sent to the chat provider while a run is active. Use
+`agent.typingMode` to control **when** typing starts and `typingIntervalSeconds`
+to control **how often** it refreshes.
+
+## Defaults
+When `agent.typingMode` is **unset**, Clawdbot keeps the legacy behavior:
+- **Direct chats**: typing starts immediately once the model loop begins.
+- **Group chats with a mention**: typing starts immediately.
+- **Group chats without a mention**: typing starts only when message text begins streaming.
+- **Heartbeat runs**: typing is disabled.
+
+## Modes
+Set `agent.typingMode` to one of:
+- `never` — no typing indicator, ever.
+- `instant` — start typing **as soon as the model loop begins**, even if the run
+  later returns only the silent reply token.
+- `thinking` — start typing on the **first reasoning delta** (requires
+  `reasoningLevel: "stream"` for the run).
+- `message` — start typing on the **first non-silent text delta** (ignores
+  the `NO_REPLY` silent token).
+
+Order of “how early it fires”:
+`never` → `message` → `thinking` → `instant`
+
+## Configuration
+```json5
+{
+  agent: {
+    typingMode: "thinking",
+    typingIntervalSeconds: 6
+  }
+}
+```
+
+You can override the refresh cadence per session:
+```json5
+{
+  session: {
+    typingIntervalSeconds: 4
+  }
+}
+```
+
+## Notes
+- `message` mode won’t show typing for silent-only replies (e.g. the `NO_REPLY`
+  token used to suppress output).
+- `thinking` only fires if the run streams reasoning; if the model doesn’t emit
+  reasoning deltas, typing won’t start.
+- Heartbeats never show typing, regardless of mode.
+- `typingIntervalSeconds` controls the **refresh cadence**, not the start time.
+  The default is 6 seconds.

docs/docs.json

@@ -554,6 +554,7 @@
           "concepts/provider-routing",
           "concepts/groups",
           "concepts/group-messages",
+          "concepts/typing-indicators",
           "concepts/queue",
           "concepts/models",
           "concepts/model-failover",

docs/gateway/configuration.md

@@ -993,6 +993,13 @@ Block streaming:
   ```
 See [/concepts/streaming](/concepts/streaming) for behavior + chunking details.
 
+Typing indicators:
+- `agent.typingMode`: `"never" | "instant" | "thinking" | "message"`. Defaults to
+  `instant` for direct chats / mentions and `message` for unmentioned group chats.
+- `agent.typingIntervalSeconds`: how often the typing signal is refreshed (default: 6s).
+- `session.typingIntervalSeconds`: per-session override for the refresh interval.
+See [/concepts/typing-indicators](/concepts/typing-indicators) for behavior details.
+
 `agent.model.primary` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`).
 Aliases come from `agent.models.*.alias` (e.g. `Opus`).
 If you omit the provider, CLAWDBOT currently assumes `anthropic` as a temporary