feat: per-tool trace messages + LLM reasoning in Telegram bot

- Replace single edited trace message with individual messages per tool call
- Show LLM reasoning content before tool execution via IterationCallback
- Add deleteToolTraceMessages helper to clean up after response delivery
- IterationInfo gains ReasoningContent and IsPreTool fields

Author: molty3000

cmd/odek/telegram.go

@@ -1025,12 +1025,11 @@ func handleChatMessage(
 	}()
 
 	// ── Tool Tracing ───────────────────────────────────────────────
-	// Single editable message showing live tool execution progress.
-	// In verbose mode this shows raw tool names/results; in engaging
-	// mode it's replaced by the narrator progress message above.
-	var traceMsgID int
-	var traceMu sync.Mutex
-	traceLines := make([]string, 0, 8)
+	// 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.
+	var toolMsgIDs sync.Map // map[string]int
 
 	// truncate shortens a string for display, appending "…" if trimmed.
 	truncate := func(s string, max int) string {
@@ -1040,6 +1039,15 @@ func handleChatMessage(
 		return s
 	}
 
+	// truncateWords limits text to maxWords, appending "…" if trimmed.
+	truncateWords := func(s string, maxWords int) string {
+		words := strings.Fields(s)
+		if len(words) <= maxWords {
+			return s
+		}
+		return strings.Join(words[:maxWords], " ") + "…"
+	}
+
 	// Collect agent run stats via the iteration callback.
 	var runInfo loop.IterationInfo
 	var allToolsMu sync.Mutex
@@ -1127,9 +1135,7 @@ func handleChatMessage(
 		Renderer:        rend,
 		ToolEventHandler: func(event string, name string, data string) {
 			// Engaging mode: update the progress message with narrated tool
-			// descriptions instead of raw traces. We skip tool_result events
-			// here — the next tool_call will overwrite the message anyway,
-			// keeping the chat scannable and avoiding flash edits.
+			// descriptions instead of raw traces.
 			if resolved.InteractionMode != "verbose" {
 				if progressMsgID != 0 && event == "tool_call" && narrator != nil {
 					if msg := narrator.ToolCallMessage(name, data); msg != "" {
@@ -1138,41 +1144,43 @@ func handleChatMessage(
 				}
 				return
 			}
-			traceMu.Lock()
-			defer traceMu.Unlock()
-
-			// Lazy-init: create the trace message on the first tool call.
-			if traceMsgID == 0 && event == "tool_call" {
-				if msg, err := bot.SendMessage(chatID, "🔧 …", nil); err == nil {
-					traceMsgID = msg.ID
-				} else {
-					return
-				}
-			}
-			if traceMsgID == 0 {
-				return
-			}
 
+			// Verbose mode: individual messages per tool call so the user
+			// can follow the agent's journey step by step.
 			switch event {
 			case "tool_call":
 				args := truncate(data, 150)
-				line := fmt.Sprintf("%s %s(%s)  ⏳", render.ToolEmoji(name), name, args)
-				traceLines = append(traceLines, line)
-				bot.EditMessageText(chatID, traceMsgID, strings.Join(traceLines, "\n"), nil)
+				line := fmt.Sprintf("%s `%s` %s", render.ToolEmoji(name), name, args)
+				if msg, err := bot.SendMessage(chatID, line, nil); err == nil {
+					toolMsgIDs.Store(name, msg.ID)
+				}
 
 			case "tool_result":
-				sizeLabel := fmt.Sprintf("%dB", len(data))
-				if len(data) > 1024 {
-					sizeLabel = fmt.Sprintf("%dKB", len(data)/1024)
-				}
-				if len(traceLines) > 0 {
-					last := traceLines[len(traceLines)-1]
-					traceLines[len(traceLines)-1] = strings.Replace(last, " ⏳", " ✅ ("+sizeLabel+")", 1)
-					bot.EditMessageText(chatID, traceMsgID, strings.Join(traceLines, "\n"), nil)
+				if msgIDVal, ok := toolMsgIDs.Load(name); ok {
+					msgID := msgIDVal.(int)
+					sizeLabel := fmt.Sprintf("%dB", len(data))
+					if len(data) > 1024 {
+						sizeLabel = fmt.Sprintf("%dKB", len(data)/1024)
+					}
+					bot.EditMessageText(chatID, msgID,
+						fmt.Sprintf("%s `%s` ✅ (%s)", render.ToolEmoji(name), name, sizeLabel), nil)
 				}
 			}
 		},
 		IterationCallback: func(info loop.IterationInfo) {
+			// Pre-tool callback: show LLM reasoning before tools run.
+			if info.IsPreTool {
+				if info.ReasoningContent != "" {
+					reasoning := truncateWords(info.ReasoningContent, 50)
+					if reasoning != "" {
+						bot.SendMessage(chatID, "💭 "+reasoning,
+							&telegram.SendOpts{ReplyToMessageID: messageID})
+					}
+				}
+				return
+			}
+
+			// Post-tool / final-answer callback: collect tool stats.
 			allToolsMu.Lock()
 			for _, name := range info.ToolNames {
 				if _, ok := allTools[name]; !ok {
@@ -1257,11 +1265,8 @@ func handleChatMessage(
 	// Run the agent with the full message history (multi-turn).
 	response, updatedMessages, err := agent.RunWithMessages(agentCtx, cs.Messages)
 	if err != nil {
-		// Clean up trace message on error too.
-		if traceMsgID != 0 {
-			bot.DeleteMessage(chatID, traceMsgID)
-			traceMsgID = 0
-		}
+		// Clean up any tool trace messages on error.
+		deleteToolTraceMessages(bot, chatID, &toolMsgIDs)
 
 		// If the context was cancelled (by /stop or restart), save partial
 		// state and notify the user with a cancellation summary.
@@ -1314,13 +1319,8 @@ func handleChatMessage(
 	if response != "" {
 		handler.SendResponse(chatID, response, messageID)
 
-		// Clean up the tool trace message — it's stale after the response.
-		if traceMsgID != 0 {
-			if err := bot.DeleteMessage(chatID, traceMsgID); err != nil {
-				log.Debug("delete trace message failed", "chat_id", chatID, "msg_id", traceMsgID, "error", err)
-			}
-			traceMsgID = 0
-		}
+		// Clean up all tool trace messages — they're stale after the response.
+		deleteToolTraceMessages(bot, chatID, &toolMsgIDs)
 
 		// Send run stats as a separate message directly via Bot.SendMessage
 		// (bypassing SendResponse/FormatResponse) so MarkdownV2 backtick code
@@ -1659,3 +1659,17 @@ func buttonsToMarkup(buttons [][]map[string]string) *telegram.InlineKeyboardMark
 	}
 	return markup
 }
+
+// deleteToolTraceMessages deletes all individual tool trace messages for a chat.
+// Used to clean up after the agent finishes (success or error).
+func deleteToolTraceMessages(bot *telegram.Bot, chatID int64, msgIDs *sync.Map) {
+	msgIDs.Range(func(key, value any) bool {
+		if msgID, ok := value.(int); ok {
+			if err := bot.DeleteMessage(chatID, msgID); err != nil {
+				fmt.Fprintf(os.Stderr, "odek telegram: delete tool message failed: %v\n", err)
+			}
+		}
+		msgIDs.Delete(key)
+		return true
+	})
+}

internal/loop/loop.go

@@ -45,6 +45,8 @@ type IterationInfo struct {
 	CachedTokens          int           // cumulative cached tokens (OpenAI)
 	TotalLatency          time.Duration // cumulative wall time
 	HasFinalAnswer        bool          // true when the agent reached a final answer
+	ReasoningContent      string        // LLM reasoning before tool calls (empty if none)
+	IsPreTool             bool          // true when fired BEFORE tool execution (shows reasoning + tools)
 }
 
 // IterationCallback is an optional callback invoked after each iteration
@@ -582,11 +584,31 @@ func (e *Engine) runLoop(ctx context.Context, messages []llm.Message) (string, [
 
 		// ACT: execute each tool call in parallel with bounded concurrency
 		toolNames := make([]string, 0, len(result.ToolCalls))
-
-		// Phase 1: fire all tool_call events synchronously (rendering + events)
 		for _, tc := range result.ToolCalls {
 			toolNames = append(toolNames, tc.Function.Name)
+		}
+
+		// Fire iteration callback BEFORE tool execution so UIs can show
+		// the LLM's reasoning and which tools are about to run.
+		if e.iterationCallback != nil {
+			e.iterationCallback(IterationInfo{
+				Turn:                i + 1,
+				MaxTurns:            e.maxIter,
+				ToolNames:           toolNames,
+				InputTokens:         e.TotalInputTokens,
+				OutputTokens:        e.TotalOutputTokens,
+				CacheCreationTokens: e.TotalCacheCreationTokens,
+				CacheReadTokens:     e.TotalCacheReadTokens,
+				CachedTokens:        e.TotalCachedTokens,
+				TotalLatency:        time.Since(startTime),
+				HasFinalAnswer:      false,
+				ReasoningContent:    result.Content,
+				IsPreTool:           true,
+			})
+		}
 
+		// Phase 1: fire all tool_call events synchronously (rendering + events)
+		for _, tc := range result.ToolCalls {
 			if e.narrator != nil {
 				if msg := e.narrator.ToolCallMessage(tc.Function.Name, tc.Function.Arguments); msg != "" {
 					if e.renderer != nil {

notify-channel-proposal.md

@@ -0,0 +1,184 @@
+# Proposal: Default Communication Channel for odek
+
+**Goal:** Allow external systems (cron, webhooks, other tools) to invoke `odek run` and have the output/result reach the operator via a configurable communication channel. Telegram first, extensible later.
+
+---
+
+## 1. What Hermes Does
+
+Hermes has a multi-channel architecture. Each platform (Telegram, Mattermost, Matrix, WhatsApp) has its own config section with allowed chats/rooms, channel prompts, etc. When cron jobs run, `wrap_response: true` in the `cron:` section wraps the output and routes it through the configured channels to reach the operator.
+
+**Key Hermes patterns we're adopting:**
+- Top-level `notify` configuration that's platform-agnostic
+- Channel routing: "send this to the operator via channel X"
+- Non-interactive awareness: different behavior when no TTY
+
+---
+
+## 2. Proposed Design
+
+### 2.1 New `notify` config section
+
+```json
+// ~/.odek/config.json
+{
+  "notify": {
+    "channel": "telegram",
+    "telegram_chat_id": 8592463065
+  }
+}
+```
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `channel` | string | Which channel to use: `"telegram"` (default: `""` = stdout only) |
+| `telegram_chat_id` | int64 | Target chat ID for Telegram notifications |
+
+**Future channels** (not implementing now, but design accommodates):
+- `"webhook"` — POST to a URL
+- `"email"` — SMTP
+- `"discord"` — Discord webhook
+
+### 2.2 Config wiring (7-layer chain)
+
+Following odek's existing pattern (global → project → env → CLI):
+
+| Layer | Key/Flag |
+|-------|----------|
+| `~/.odek/config.json` | `notify.channel`, `notify.telegram_chat_id` |
+| `./odek.json` | same keys (project overrides) |
+| Env var | `ODEK_NOTIFY_CHANNEL`, `ODEK_NOTIFY_TELEGRAM_CHAT_ID` |
+| CLI flag | `--notify-channel`, `--notify-telegram-chat-id` |
+
+### 2.3 Go types
+
+**`internal/notify/notify.go`** (new package):
+
+```go
+package notify
+
+// Config holds the notification routing configuration.
+type Config struct {
+    Channel        string `json:"channel,omitempty"`          // "telegram" or ""
+    TelegramChatID int64  `json:"telegram_chat_id,omitempty"` // target chat
+}
+
+func DefaultConfig() Config {
+    return Config{} // channel="" means stdout only
+}
+```
+
+**Added to `FileConfig`** in `internal/config/loader.go`:
+
+```go
+Notify *notify.Config `json:"notify,omitempty"`
+```
+
+**Added to `ResolvedConfig`** in `internal/config/loader.go`:
+
+```go
+Notify notify.Config
+```
+
+### 2.4 Integration point: `odek run`
+
+In `cmd/odek/main.go` → `run()`, after the agent completes:
+
+```go
+// After agent.Run() returns:
+if !isTerminal() && resolved.Notify.Channel == "telegram" && resolved.Notify.TelegramChatID != 0 {
+    // Send the final answer to the operator via Telegram
+    sendTelegramNotification(resolved, result)
+}
+```
+
+The `sendTelegramNotification` function:
+1. Creates a minimal Bot client using the existing `Telegram.Token` from config
+2. Sends the agent's final answer as a Markdown message to the configured `TelegramChatID`
+3. Also sends any errors if the run failed
+
+### 2.5 When does notification fire?
+
+| Scenario | Notify? |
+|----------|---------|
+| `odek run` from terminal (TTY) | No — user sees output directly |
+| `odek run` from cron (no TTY) | Yes — if `notify.channel` is configured |
+| `odek run` from another script (no TTY) | Yes — same as cron |
+| `odek telegram` (bot mode) | No — already interactive via Telegram |
+| `odek repl` | No — interactive |
+
+**Detection:** Use `!isTerminal()` (we already check stdin for color disable — reuse `terminal.IsTerminal`).
+
+---
+
+## 3. Files Changed
+
+| File | Change |
+|------|--------|
+| `internal/notify/notify.go` | **NEW** — Config type + DefaultConfig |
+| `internal/notify/notify_test.go` | **NEW** — Tests for config validation |
+| `internal/config/loader.go` | Add `Notify` to `FileConfig`, `CLIFlags`, `ResolvedConfig`; wire env vars + CLI flags |
+| `cmd/odek/main.go` | Add `--notify-channel`, `--notify-telegram-chat-id` flags; add post-run notification dispatch in `run()` |
+
+---
+
+## 4. Cron Usage Example
+
+Once configured, a cron job like this:
+
+```bash
+# /etc/cron.d/odek-health
+0 9 * * * root /usr/local/bin/odek run "Check system health and report" >> /var/log/odek-cron.log 2>&1
+```
+
+Would:
+1. Run the agent task
+2. Log raw output to `/var/log/odek-cron.log`
+3. **Also** send the final answer via Telegram to chat ID `8592463065`
+
+The operator gets the report on their phone without checking logs.
+
+---
+
+## 5. What We Don't Do (Yet)
+
+- **Streaming/progress updates** — notification sends only the final answer, not intermediate tool calls
+- **Multi-channel fanout** — only one channel at a time
+- **Per-task channel override** — uses global config only
+- **Channel-specific formatting** — Telegram uses Markdown, future channels will adapt
+
+---
+
+## 6. Implementation Phases
+
+### Phase 1: Types + Config (2 files, ~80 LOC)
+- Create `internal/notify/notify.go` 
+- Wire into `loader.go` (FileConfig, ResolvedConfig, env vars, CLI flags, default overlay)
+
+### Phase 2: Dispatch logic (1 file, ~50 LOC)  
+- Add post-run notification to `cmd/odek/main.go` → `run()`
+- `sendTelegramNotification()` helper
+
+### Phase 3: Tests
+- Config loading tests (defaults, env vars, CLI override)
+- Notification dispatch test (mock Telegram server)
+
+---
+
+## 7. Verification
+
+```bash
+# Config loading
+grep -o '"notify"' ~/.odek/config.json
+
+# Manual test (with TTY — no notification fires)
+odek run --notify-channel telegram --notify-telegram-chat-id 8592463065 "Say hello"
+
+# Cron simulation (no TTY — notification SHOULD fire)
+echo "Say hello" | odek run --notify-channel telegram --notify-telegram-chat-id 8592463065
+
+# Full test suite
+go test ./internal/notify/... ./internal/config/... -count=1
+```