v0.43.0: Telegram narrator upgrade — Hermes-parity tool progress

molty3000 · molty3000 · commit b9ceff279890 · 2026-05-24T14:34:11.000+02:00
- Smart previews: render.ToolPreview() extracts meaningful context
  from tool call args (filename, command, URL, query, etc.)
- Edit throttling: 1.5s min between edits to avoid flood control
- Tool dedup: consecutive same-tool collapses into (×N) counter
- Flood fallback: switches to new messages on 429 errors
- Content reset: send_message mid-run resets progress bubble
- tool_progress config: all|new|verbose|off (independent from
  interaction_mode)
- tool_progress_cleanup: configurable progress message deletion
- render.ToolEmoji() exported for Telegram bot use
- narrate.Narrator deprecated (absorbed into telegram.go+render.go)
- docs: CHANGELOG v0.43.0, TELEGRAM.md tool_progress section,
  CONFIG.md env var reference
diff --git a/AGENTS.md b/AGENTS.md
@@ -12,7 +12,7 @@ It provides context about the project's architecture, conventions, and how to up
 - **Binary:** `odek` — single static binary, ~12 MB, instant startup.
 - **Config:** Five-layer priority: `~/.odek/secrets.env` → `~/.odek/config.json` → `./odek.json` → `ODEK_*` env vars → CLI flags.
 - **Benchmark:** AIEB v2.0 — 80.3% (highest published agent score on the Autonomous Intelligence Engineering Benchmark).
-- **Version:** v0.42.1 — see latest tag at https://github.com/BackendStack21/odek/releases
+- **Version:** v0.43.0 — see latest tag at https://github.com/BackendStack21/odek/releases
 
 ## Source Layout
 
diff --git a/cmd/odek/telegram.go b/cmd/odek/telegram.go
@@ -21,7 +21,6 @@ import (
 	"github.com/BackendStack21/kode/internal/llm"
 	"github.com/BackendStack21/kode/internal/loop"
 	"github.com/BackendStack21/kode/internal/render"
-	"github.com/BackendStack21/kode/internal/narrate"
 	"github.com/BackendStack21/kode/internal/session"
 	"github.com/BackendStack21/kode/internal/skills"
 	"github.com/BackendStack21/kode/internal/telegram"
@@ -1032,53 +1031,120 @@ func handleChatMessage(
 	}()
 	
 	// ── Progress Mode Setup ───────────────────────────────────────
-	// Send an instant "working on it" message so the user sees feedback
-	// within milliseconds, not seconds.
+	// The tool_progress config controls Telegram progress bubbles:
+	//   "all"     — single editable bubble with smart previews, throttled edits,
+	//               dedup counter, and flood-control fallback (recommended default)
+	//   "new"     — like "all" but only updates when the tool name changes
+	//   "verbose" — raw tool args in per-tool messages with result replacement
+	//   "off"     — no per-tool progress (just thinking + final answer)
 	//
-	//   engaging: updated with narrated tool descriptions (edits), then
-	//             deleted when the final answer arrives.
-	//   enhance:  kept as a per-iteration header; narrated tool messages
-	//             are appended below it as new messages (no edits).
-	//   verbose:  no progress message — uses raw tool traces instead.
-	var narrator *narrate.Narrator
-	isEngaging := resolved.InteractionMode == "engaging"
+	// When interaction_mode is "enhance", the old per-tool narrated-message
+	// behavior is used regardless of tool_progress (preserves existing UX).
+	toolProgress := resolved.ToolProgress
 	isEnhance := resolved.InteractionMode == "enhance"
-	if isEngaging || isEnhance {
-		narrator = narrate.New(true)
+	if isEnhance {
+		toolProgress = "enhance"
 	}
+
 	var progressMsgID int
-	if isEngaging || isEnhance {
+	var progressLines []string
+	var lastProgressMsg string
+	var repeatCount int
+	var canEdit = true
+	var lastEditTime time.Time
+	const editThrottle = 1500 * time.Millisecond
+
+	// Send an initial "working on it" message for all modes except "off".
+	if toolProgress != "off" {
 		msg, err := bot.SendMessage(chatID, "🤔 Looking into that...",
 			&telegram.SendOpts{ReplyToMessageID: messageID})
 		if err == nil {
 			progressMsgID = msg.ID
 		}
 	}
+	// Cleanup progress messages when the task finishes.
 	defer func() {
-		// Clean up the progress message when the task finishes.
-		// In engaging mode, deletes the stale "thinking" message.
-		// In enhance mode, preserves it as a per-iteration header
-		// with the narrated tool messages below it.
-		if progressMsgID != 0 && isEngaging {
+		if progressMsgID != 0 && resolved.ToolProgressCleanup {
 			bot.DeleteMessage(chatID, progressMsgID)
 		}
 	}()
 
-	// ── Tool Tracing ───────────────────────────────────────────────
-	// Individual messages per tool call so the user can follow the
-	// agent's journey step by step. Reasoning is shown before tool
-	// calls. All trace messages are deleted after the agent responds.
-	// toolMsgIDs tracks per-turn tool message IDs for editing on result.
+	// ── Tool Tracing (legacy verbose mode fallback) ──────────────
+	// Used when interaction_mode is "verbose" AND tool_progress is NOT set
+	// (or set to something other than "verbose"). These per-tool trace
+	// messages are preserved for the old verbose interaction mode.
 	var toolMsgIDs sync.Map // map[string]int
 
-	// truncate shortens a string for display, appending "…" if trimmed.
-	truncate := func(s string, max int) string {
-		if len(s) > max {
-			return s[:max] + "…"
+	// Helper: build a progress line for a tool call.
+	buildProgressLine := func(name, data string) string {
+		emoji := render.ToolEmoji(name)
+		preview := render.ToolPreview(name, data)
+		if preview != "" {
+			return fmt.Sprintf("%s %s: \"%s\"", emoji, name, preview)
+		}
+		return fmt.Sprintf("%s %s...", emoji, name)
+	}
+
+	// Helper: send or edit the progress bubble.
+	sendProgress := func(line string) {
+		if toolProgress == "off" || progressMsgID == 0 {
+			return
+		}
+
+		// "new" mode: only show a new message when the tool changes.
+		if toolProgress == "new" && len(progressLines) > 0 && line == lastProgressMsg {
+			return
+		}
+
+		// Dedup: collapse consecutive identical messages.
+		if line == lastProgressMsg {
+			repeatCount++
+			if len(progressLines) > 0 {
+				progressLines[len(progressLines)-1] = fmt.Sprintf("%s (×%d)", line, repeatCount+1)
+			}
+		} else {
+			lastProgressMsg = line
+			repeatCount = 0
+			progressLines = append(progressLines, line)
+		}
+
+		fullText := strings.Join(progressLines, "\n")
+
+		// Throttle edits to avoid Telegram flood control.
+		if time.Since(lastEditTime) < editThrottle {
+			return // will be flushed on next non-throttled tick
+		}
+
+		if canEdit {
+			err := bot.EditMessageText(chatID, progressMsgID, fullText, nil)
+			if err != nil {
+				errStr := err.Error()
+				if strings.Contains(errStr, "flood") || strings.Contains(errStr, "retry after") {
+					canEdit = false
+					// Fallback: send as new message
+					msg, err2 := bot.SendMessage(chatID, line,
+						&telegram.SendOpts{ReplyToMessageID: messageID})
+					if err2 == nil {
+						progressMsgID = msg.ID
+					}
+				}
+			}
+			lastEditTime = time.Now()
+		} else {
+			// Editing failed previously — send new messages
+			msg, err := bot.SendMessage(chatID, line,
+				&telegram.SendOpts{ReplyToMessageID: messageID})
+			if err == nil {
+				progressMsgID = msg.ID
+			}
 		}
-		return s
 	}
 
+	// Collect agent run stats via the iteration callback.
+	var runInfo loop.IterationInfo
+	var allToolsMu sync.Mutex
+	allTools := make(map[string]int)
+
 	// truncateWords limits text to maxWords, appending "…" if trimmed.
 	truncateWords := func(s string, maxWords int) string {
 		words := strings.Fields(s)
@@ -1088,11 +1154,6 @@ func handleChatMessage(
 		return strings.Join(words[:maxWords], " ") + "…"
 	}
 
-	// Collect agent run stats via the iteration callback.
-	var runInfo loop.IterationInfo
-	var allToolsMu sync.Mutex
-	allTools := make(map[string]int)
-
 	// ── Clarify Tool ───────────────────────────────────────────────
 	// Wire the clarify tool with a Telegram-native answer function.
 	// When the agent calls clarify(question), the bot sends an inline
@@ -1178,62 +1239,60 @@ func handleChatMessage(
 		Renderer:        rend,
 		ToolEventHandler: func(event string, name string, data string) {
 			// Enhance mode: send new messages with narrated descriptions.
-			// Each tool call gets its own message (no edits, no cleanup).
 			if isEnhance {
+				// Content reset: interim messages reset the progress bubble.
+				if event == "tool_call" && name == "send_message" {
+					progressMsgID = 0
+					progressLines = nil
+					lastProgressMsg = ""
+					repeatCount = 0
+					return
+				}
 				switch event {
 				case "tool_call":
-					if narrator != nil {
-						if msg := narrator.ToolCallMessage(name, data); msg != "" {
-							escapedMsg := telegram.EscapeMarkdown(msg)
-							bot.SendMessage(chatID, escapedMsg,
-								&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
-						}
-					}
-				case "tool_result":
-					// silent in enhance mode -- the narrated tool_call
-					// message already describes what's happening.
-				}
-				return
-			}
-
-			// Engaging mode: update the progress message with narrated tool
-			// descriptions instead of raw traces.
-			if isEngaging {
-				if progressMsgID != 0 && event == "tool_call" && narrator != nil {
-					if msg := narrator.ToolCallMessage(name, data); msg != "" {
-						bot.EditMessageText(chatID, progressMsgID, msg, nil)
-					}
+					line := buildProgressLine(name, data)
+					bot.SendMessage(chatID, telegram.EscapeMarkdown(line),
+						&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
 				}
 				return
 			}
 
-			// Verbose mode: individual messages per tool call so the user
-			// can follow the agent's journey step by step.
+			// Progress modes: "all", "new", "verbose", "off".
 			switch event {
 			case "tool_call":
-				args := truncate(data, 150)
-				line := fmt.Sprintf("%s `%s` %s", render.ToolEmoji(name), name, args)
-				line = telegram.EscapeMarkdown(line)
-				if msg, err := bot.SendMessage(chatID, line, &telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2}); err == nil {
-					toolMsgIDs.Store(name, msg.ID)
+				// Content reset: if send_message fires mid-run, reset the
+				// progress bubble so it appears below the sent message.
+				if name == "send_message" {
+					progressMsgID = 0
+					progressLines = nil
+					lastProgressMsg = ""
+					repeatCount = 0
+					return
 				}
 
-			case "tool_result":
-				// Send a new message for the result so the full timeline
-				// is preserved in chat history.
-				sizeLabel := fmt.Sprintf("%dB", len(data))
-				if len(data) > 1024 {
-					sizeLabel = fmt.Sprintf("%dKB", len(data)/1024)
+				if toolProgress == "verbose" {
+					line := fmt.Sprintf("%s `%s` %s", render.ToolEmoji(name), name, data)
+					line = telegram.EscapeMarkdown(line)
+					bot.SendMessage(chatID, line,
+						&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
+				} else {
+					line := buildProgressLine(name, data)
+					sendProgress(line)
 				}
-				line := fmt.Sprintf("%s `%s` ✅ (%s)", render.ToolEmoji(name), name, sizeLabel)
-				line = telegram.EscapeMarkdown(line)
-				bot.SendMessage(chatID, line,
-					&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
-				// Clean up the initial tool_call message — it's stale now.
-				if msgIDVal, ok := toolMsgIDs.Load(name); ok {
-					bot.DeleteMessage(chatID, msgIDVal.(int))
+
+			case "tool_result":
+				if toolProgress == "verbose" {
+					sizeLabel := fmt.Sprintf("%dB", len(data))
+					if len(data) > 1024 {
+						sizeLabel = fmt.Sprintf("%dKB", len(data)/1024)
+					}
+					line := fmt.Sprintf("%s `%s` ✅ (%s)", render.ToolEmoji(name), name, sizeLabel)
+					line = telegram.EscapeMarkdown(line)
+					bot.SendMessage(chatID, line,
+						&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
 				}
-				toolMsgIDs.Delete(name)
+				// "all"/"new" modes: tool_result is silent (progress
+				// bubble already shows the narrated tool call).
 			}
 		},
 		IterationCallback: func(info loop.IterationInfo) {
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,5 +1,40 @@
 # Changelog
 
+## v0.43.0 (2026-05-24) — Telegram Narrator Upgrade
+
+### New Features
+- **Telegram tool progress system** — completely rewritten progress display with Hermes-parity features:
+  - **Smart previews** — `📝 read_file: "main.go"` instead of generic narrated templates. Extracts meaningful context from tool args (filename, command, URL, query, etc.)
+  - **Edit throttling** — 1.5s minimum between edits to avoid Telegram flood control (no more 429 errors)
+  - **Tool dedup** — consecutive same-tool calls collapse into `(×N)` counter, reducing chat noise
+  - **Flood control fallback** — when edit hits a rate limit, automatically switches to new messages
+  - **Content reset** — when `send_message` fires mid-run, progress bubble resets below the sent content
+- **`tool_progress` config** — new independent config field with four modes:
+  - `"all"` (default) — single editable progress bubble with smart previews, throttling, dedup
+  - `"new"` — only updates when the tool name changes
+  - `"verbose"` — raw tool args in per-tool messages
+  - `"off"` — no per-tool progress (just thinking + final answer)
+- **`tool_progress_cleanup` config** — whether to delete progress messages after the final answer (default: `true`)
+- **`render.ToolPreview()`** — exported function extracts meaningful previews from tool call JSON args. Covers all 20+ native tools (read_file, shell, browser, memory, transcribe, send_message, etc.)
+- **`render.ToolEmoji()`** — now exported for use by Telegram bot (was internal-only)
+
+### Breaking Changes
+- `narrate.Narrator` package is deprecated — all functionality absorbed into `telegram.go` + `render.go`. The package is kept for build compatibility but no longer used by Telegram bot
+
+### Config
+```json
+{
+  "tool_progress": "all",
+  "tool_progress_cleanup": true
+}
+```
+
+### Stats
+- 120+ insertions across 3 files (telegram.go, render.go, loader.go)
+- All 19 packages pass with `-race`
+
+---
+
 ## v0.42.1 (2026-05-24) — OGG Opus Transcribe Fix
 
 ### Bug Fixes
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
@@ -102,6 +102,7 @@ Every config knob has a `ODEK_*` counterpart:
 | `ODEK_SYSTEM` | `--system` | string |
 | `ODEK_SKILLS_LEARN` | `skills.learn` | bool |
 | `ODEK_PROMPT_CACHING` | `prompt_caching` | bool |
+| `ODEK_TOOL_PROGRESS` | `tool_progress` | string (all\|new\|verbose\|off) |
 | `ODEK_SANDBOX_IMAGE` | `--sandbox-image` | string |
 | `ODEK_SANDBOX_NETWORK` | `--sandbox-network` | string |
 | `ODEK_SANDBOX_READONLY` | `--sandbox-readonly` | bool |
diff --git a/docs/TELEGRAM.md b/docs/TELEGRAM.md
@@ -307,6 +307,33 @@ Voice message received → DownloadVoice (OGG Opus to disk)
 
 **Fallback:** If auto-transcribe fails (ffmpeg unavailable, corrupt audio, whisper error), the agent receives the file path with a suggestion to use the `transcribe()` tool manually.
 
+### Tool Progress (Narrator)
+
+Tool progress shows what the agent is doing in real time. Controlled by the `tool_progress` config field (independent from `interaction_mode`):
+
+| Mode | Behavior |
+|------|----------|
+| `all` (default) | Single editable progress bubble with smart previews — e.g. `📝 read_file: "main.go"`. With edit throttling (1.5s), dedup (`×N` counter), and flood-control fallback |
+| `new` | Like `all` but only updates when the tool name changes — skips consecutive same-tool repeats |
+| `verbose` | Raw tool arguments as separate messages — `📝 `read_file` {"path":"main.go"}` then `📝 `read_file` ✅ (2KB)` on completion |
+| `off` | No per-tool progress messages — just the thinking preamble and final answer |
+
+**Key features:**
+- **Smart previews** — extracts meaningful context: filename for file tools, command for shell, URL for browser, query for memory, filename for transcribe
+- **Edit throttling** — 1.5s minimum between edits prevents Telegram flood control (429 errors)
+- **Tool dedup** — if the same tool runs N times in a row (common with parallel batches), shows `📝 read_file: "main.go" (×5)` instead of 5 identical lines
+- **Flood fallback** — if an edit fails with "flood" or "retry after", automatically switches to sending new messages
+- **Content reset** — when `send_message` fires mid-run, the progress bubble resets below the sent content
+- **Cleanup** — progress message deleted after final answer (configurable via `tool_progress_cleanup: false`)
+
+Config example:
+```json
+{
+  "tool_progress": "all",
+  "tool_progress_cleanup": true
+}
+```
+
 ## Types (`types.go`)
 
 The package defines Telegram API types used throughout:
diff --git a/internal/config/loader.go b/internal/config/loader.go
diff --git a/internal/render/render.go b/internal/render/render.go
