feat(telegram): per-response stats with cache tracking and code-block formatting

- Add IterationInfo/IterationCallback to loop engine for progress reporting
- Wire iteration callback in Telegram handler to collect per-run stats
- Show compact stats after each response: turns, tokens, cache, latency, tools
- Format stats as MarkdownV2 code block for clear visual distinction
- Always show cache line (cache: Xcr+Yrd+Zct) even when zero
- Send stats via Bot.SendMessage directly (bypass FormatResponse conversion)
- Add EditMessageText method to Bot for future progress editing

Author: jkyberneees

cmd/odek/telegram.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"os/signal"
+	"sort"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -14,6 +15,7 @@ import (
 	"github.com/BackendStack21/kode"
 	"github.com/BackendStack21/kode/internal/config"
 	"github.com/BackendStack21/kode/internal/llm"
+	"github.com/BackendStack21/kode/internal/loop"
 	"github.com/BackendStack21/kode/internal/render"
 	"github.com/BackendStack21/kode/internal/session"
 	"github.com/BackendStack21/kode/internal/telegram"
@@ -102,7 +104,7 @@ func telegramCmd(args []string) error {
 	// dispatch prevents deadlock.
 	handler.OnTextMessage = func(chatID int64, text string) (string, error) {
 		go handleChatMessage(chatID, text, bot, handler, sessionManager,
-			resolved, systemMessage)
+			resolved, systemMessage, handlerLog)
 		return "", nil
 	}
 
@@ -158,13 +160,13 @@ func telegramCmd(args []string) error {
 
 	handler.OnVoiceMessage = func(chatID int64, fileID string) (string, error) {
 		go handleChatMessage(chatID, "[voice message: "+fileID+"]",
-			bot, handler, sessionManager, resolved, systemMessage)
+			bot, handler, sessionManager, resolved, systemMessage, handlerLog)
 		return "", nil
 	}
 
 	handler.OnPhotoMessage = func(chatID int64, fileIDs []string) (string, error) {
 		go handleChatMessage(chatID, "[photo message: "+strings.Join(fileIDs, ",")+"]",
-			bot, handler, sessionManager, resolved, systemMessage)
+			bot, handler, sessionManager, resolved, systemMessage, handlerLog)
 		return "", nil
 	}
 
@@ -239,6 +241,7 @@ func handleChatMessage(
 	sessionManager *telegram.SessionManager,
 	resolved	config.ResolvedConfig,
 	systemMessage string,
+	log telegram.Logger,
 ) {
 	// Serialize per chat: only one agent loop runs per chat at a time.
 	// Prevents same-chat message racing that would corrupt session history.
@@ -272,7 +275,12 @@ func handleChatMessage(
 
 	rend := render.New(os.Stderr, false).WithModel(modelLabel)
 
-	agent, err := odek.New(odek.Config{
+	// Collect agent run stats via the iteration callback.
+	var runInfo loop.IterationInfo
+	var allToolsMu sync.Mutex
+	allTools := make(map[string]int)
+
+	agentCfg := odek.Config{
 		Model:         resolved.Model,
 		BaseURL:       resolved.BaseURL,
 		APIKey:        resolved.APIKey,
@@ -282,7 +290,23 @@ func handleChatMessage(
 		Thinking:      resolved.Thinking,
 		Tools:         tools,
 		Renderer:      rend,
-	})
+		IterationCallback: func(info loop.IterationInfo) {
+			allToolsMu.Lock()
+			for _, name := range info.ToolNames {
+				if _, ok := allTools[name]; !ok {
+					allTools[name] = 0
+				}
+				allTools[name]++
+			}
+			allToolsMu.Unlock()
+
+			if info.HasFinalAnswer {
+				runInfo = info
+			}
+		},
+	}
+
+	agent, err := odek.New(agentCfg)
 	if err != nil {
 		reportError(bot, chatID, "Failed to create agent: "+err.Error())
 		return
@@ -317,9 +341,30 @@ func handleChatMessage(
 		fmt.Fprintf(os.Stderr, "odek telegram: session save: %v\n", err)
 	}
 
-	// Send the response.
+	// Send the response, then append compact stats as a separate message.
 	if response != "" {
 		handler.SendResponse(chatID, response)
+
+		// Send run stats as a separate message directly via Bot.SendMessage
+		// (bypassing SendResponse/FormatResponse) so MarkdownV2 backtick code
+		// formatting is handled natively by Telegram's parser.
+		if runInfo.Turn > 0 {
+			allToolsMu.Lock()
+			toolList := sortedToolKeys(allTools)
+			allToolsMu.Unlock()
+
+			statsLine := formatTelegramStats(runInfo, toolList)
+			if _, err := bot.SendMessage(chatID, statsLine, &telegram.SendOpts{
+				ParseMode: telegram.ParseModeMarkdownV2,
+			}); err != nil {
+				// Fallback: send as plain text so the info isn't lost
+				if _, err2 := bot.SendMessage(chatID, statsLine, nil); err2 != nil {
+					fmt.Fprintf(os.Stderr, "odek telegram: stats send fallback failed: %v (orig: %v)\n", err2, err)
+				}
+			}
+		} else {
+			fmt.Fprintf(os.Stderr, "odek telegram: stats skipped (runInfo.Turn=%d)\n", runInfo.Turn)
+		}
 	}
 }
 
@@ -342,6 +387,42 @@ func formatStats(cs *telegram.ChatSession) string {
 	)
 }
 
+// ── Progress Callback Helpers ──────────────────────────────────────────
+
+// sortedToolKeys returns the keys of a map sorted alphabetically.
+func sortedToolKeys(m map[string]int) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// formatTelegramStats formats the final agent run statistics for Telegram.
+// Returns a compact Markdown code-formatted line.
+func formatTelegramStats(info loop.IterationInfo, toolList []string) string {
+	toolStr := "none"
+	if len(toolList) > 0 {
+		toolStr = strings.Join(toolList, ", ")
+	}
+
+	latency := info.TotalLatency.Truncate(time.Second)
+	iters := fmt.Sprintf("%d turn", info.Turn)
+	if info.Turn != 1 {
+		iters += "s"
+	}
+
+	// Always include cache stats so the user can see them even when zero.
+	cacheStr := fmt.Sprintf(" · cache: %dcr+%drd+%dct",
+		info.CacheCreationTokens, info.CacheReadTokens, info.CachedTokens)
+
+	return fmt.Sprintf(
+		"```\n✅ Done · %s · %d in / %d out%s · %s — tools: %s\n```",
+		iters, info.InputTokens, info.OutputTokens, cacheStr, latency.String(), toolStr,
+	)
+}
+
 // reportError sends an error message to the given chat and logs to stderr.
 func reportError(bot *telegram.Bot, chatID int64, msg string) {
 	fmt.Fprintf(os.Stderr, "odek telegram: %s\n", msg)

internal/loop/loop.go

@@ -23,6 +23,25 @@ type SkillLoader func(userInput string) string
 // each tool invocation. Used by the WebUI for live streaming of tool events.
 type ToolEventHandler func(event string, name string, data string)
 
+// IterationInfo holds data about a single agent loop iteration, passed to
+// the IterationCallback after each turn. Used for progress reporting.
+type IterationInfo struct {
+	Turn                  int           // current iteration (1-indexed)
+	MaxTurns              int           // max iterations configured
+	ToolNames             []string      // tools called this turn (duplicates possible)
+	InputTokens           int           // cumulative input tokens
+	OutputTokens          int           // cumulative output tokens
+	CacheCreationTokens   int           // cumulative cache creation tokens
+	CacheReadTokens       int           // cumulative cache read tokens
+	CachedTokens          int           // cumulative cached tokens (OpenAI)
+	TotalLatency          time.Duration // cumulative wall time
+	HasFinalAnswer        bool          // true when the agent reached a final answer
+}
+
+// IterationCallback is an optional callback invoked after each iteration
+// of the agent loop. Used by Telegram/WebUI for progress reporting.
+type IterationCallback func(info IterationInfo)
+
 // Engine runs the agent loop: observe → think → act → repeat.
 type Engine struct {
 	client      *llm.Client
@@ -36,6 +55,9 @@ type Engine struct {
 
 	toolEventHandler ToolEventHandler // optional: fires during tool execution
 
+	// iterationCallback is an optional callback fired after each iteration.
+	iterationCallback IterationCallback
+
 	// PromptCaching enables Anthropic/OpenAI/DeepSeek prompt caching markers.
 	// When enabled, the system prompt and first user message are annotated
 	// with cache_control markers, and the system prompt is moved to the
@@ -73,6 +95,10 @@ func (e *Engine) SetSkillLoader(sl SkillLoader) { e.skillLoader = sl }
 // SetToolEventHandler sets the optional tool event callback for live streaming.
 func (e *Engine) SetToolEventHandler(cb ToolEventHandler) { e.toolEventHandler = cb }
 
+// SetIterationCallback sets the iteration progress callback.
+// If nil, no callback is fired.
+func (e *Engine) SetIterationCallback(cb IterationCallback) { e.iterationCallback = cb }
+
 // ── Token Estimation ─────────────────────────────────────────────────
 //
 // Zero-dependency heuristic: 1 token ≈ 4 chars for English text.
@@ -230,6 +256,7 @@ func (e *Engine) RunWithMessages(ctx context.Context, messages []llm.Message) (s
 // answer plus the complete updated message history.
 func (e *Engine) runLoop(ctx context.Context, messages []llm.Message) (string, []llm.Message, error) {
 	tools := e.buildToolDefs()
+	startTime := time.Now()
 
 	for i := 0; i < e.maxIter; i++ {
 		select {
@@ -323,6 +350,22 @@ func (e *Engine) runLoop(ctx context.Context, messages []llm.Message) (string, [
 					e.TotalCachedTokens,
 				)
 			}
+
+			// Fire iteration callback with final answer signal
+			if e.iterationCallback != nil {
+				e.iterationCallback(IterationInfo{
+					Turn:                i + 1,
+					MaxTurns:            e.maxIter,
+					ToolNames:           nil,
+					InputTokens:         e.TotalInputTokens,
+					OutputTokens:        e.TotalOutputTokens,
+					CacheCreationTokens: e.TotalCacheCreationTokens,
+					CacheReadTokens:     e.TotalCacheReadTokens,
+					CachedTokens:        e.TotalCachedTokens,
+					TotalLatency:        time.Since(startTime),
+					HasFinalAnswer:      true,
+				})
+			}
 			// Append final assistant message so callers (e.g. WebUI) get
 			// the final text in the messages slice and can stream it.
 			messages = append(messages, llm.Message{
@@ -348,7 +391,9 @@ func (e *Engine) runLoop(ctx context.Context, messages []llm.Message) (string, [
 		messages = append(messages, assistantMsg)
 
 		// ACT: execute each tool call
+		toolNames := make([]string, 0, len(result.ToolCalls))
 		for _, tc := range result.ToolCalls {
+			toolNames = append(toolNames, tc.Function.Name)
 			if e.renderer != nil {
 				e.renderer.ToolCall(tc.Function.Name, tc.Function.Arguments)
 			}
@@ -392,6 +437,22 @@ func (e *Engine) runLoop(ctx context.Context, messages []llm.Message) (string, [
 				ToolCallID: tc.ID,
 			})
 		}
+
+		// Fire iteration callback with tool call results
+		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,
+			})
+		}
 	}
 
 	return "", messages, fmt.Errorf("reached max iterations (%d) without final answer", e.maxIter)

internal/telegram/bot.go

@@ -220,6 +220,22 @@ func (b *Bot) SendMessage(chatID int64, text string, opts *SendOpts) (*Message,
 	return &msg, nil
 }
 
+// EditMessageText edits a previously sent message in the given chat.
+// The messageID must identify an existing message sent by the bot.
+// Supports SendOpts for parse_mode. Returns an error if the message
+// hasn't changed (Telegram "Bad Request: message is not modified").
+func (b *Bot) EditMessageText(chatID int64, messageID int, text string, opts *SendOpts) error {
+	params := map[string]any{
+		"chat_id":    chatID,
+		"message_id": messageID,
+		"text":       text,
+	}
+	if opts != nil && opts.ParseMode != "" {
+		params["parse_mode"] = opts.ParseMode
+	}
+	return b.doJSON("editMessageText", params, nil)
+}
+
 // SendPhoto sends a photo from a file path to the specified chat.
 func (b *Bot) SendPhoto(chatID int64, path string, caption string) (*Message, error) {
 	params := map[string]any{

odek.go

@@ -96,6 +96,11 @@ type Config struct {
 	// after each tool invocation. Used by the WebUI for live streaming.
 	ToolEventHandler func(event string, name string, data string)
 
+	// IterationCallback, if set, is invoked after each iteration of the
+	// agent loop with progress info (turn number, tokens, tools called).
+	// Used by the Telegram handler for periodic progress updates.
+	IterationCallback loop.IterationCallback
+
 	// Skills configures the skill system. When nil, skills are disabled.
 	Skills *skills.SkillsConfig
 
@@ -404,6 +409,11 @@ func New(cfg Config) (*Agent, error) {
 		engine.SetToolEventHandler(cfg.ToolEventHandler)
 	}
 
+	// Wire iteration callback for progress reporting
+	if cfg.IterationCallback != nil {
+		engine.SetIterationCallback(cfg.IterationCallback)
+	}
+
 	agent.engine = engine
 	agent.registry = registry
 	agent.sandboxCleanup = cfg.SandboxCleanup