feat: add send_message tool for Telegram — messages, files, and keyboards

The agent can now send intermediate messages mid-task instead of being
limited to a single final answer. This replaces the MEDIA: prefix hack
with a proper tool.

send_message tool:
  - text: message body (MarkdownV2)
  - file: absolute path to attachment (photo/document/voice auto-detected)
  - buttons: inline keyboard rows with cb: prefix convention

Wired only in Telegram mode. Non-blocking — returns immediately,
doesn't wait for user response (use clarify for interactive prompts).

13 tests covering text-only, file attachment, button rendering,
callback_data prefix normalization, error paths, and schema validation.

Updated runtime.go system prompt to reflect actual tool availability.

Author: molty3000

cmd/odek/telegram.go

@@ -1072,6 +1072,31 @@ func handleChatMessage(
 		}
 	}))
 
+	// ── Send Message Tool ──────────────────────────────────────────
+	// Wire the send_message tool so the agent can send intermediate
+	// messages, files, and interactive keyboards mid-task — not just
+	// at the final answer.
+	agentTools = append(agentTools, toolpkg.NewSendMessageTool(
+		func(text string, file string, buttons [][]map[string]string) error {
+			if file != "" {
+				// Detect media type from extension.
+				mediaType := mediaTypeFromExt(file)
+				return sendTelegramMedia(bot, chatID, mediaType, file, text, buttons)
+			}
+			if len(buttons) > 0 {
+				markup := buttonsToMarkup(buttons)
+				_, err := bot.SendMessage(chatID, text, &telegram.SendOpts{
+					ParseMode:   telegram.ParseModeMarkdownV2,
+					ReplyMarkup: markup,
+				})
+				return err
+			}
+			_, err := bot.SendMessage(chatID, text, &telegram.SendOpts{
+				ParseMode: telegram.ParseModeMarkdownV2,
+			})
+			return err
+		}))
+
 	// Resolve skills config (same logic as main.go run command).
 	var skillsCfg *skills.SkillsConfig
 	if resolved.Skills.Learn {
@@ -1567,3 +1592,60 @@ func acquireLock() (*instanceLock, error) {
 func (l *instanceLock) release() {
 	os.Remove(l.pidFile)
 }
+
+// ── send_message helpers ──────────────────────────────────────────────
+
+// mediaTypeFromExt returns the Telegram media type for a file extension.
+func mediaTypeFromExt(path string) string {
+	ext := strings.ToLower(filepath.Ext(path))
+	switch ext {
+	case ".png", ".jpg", ".jpeg", ".webp", ".gif":
+		return "photo"
+	case ".ogg", ".mp3", ".wav", ".opus":
+		return "voice"
+	default:
+		return "document"
+	}
+}
+
+// sendTelegramMedia sends a file as a Telegram media message with caption
+// and optional inline keyboard. Detects the media type from file extension.
+func sendTelegramMedia(bot *telegram.Bot, chatID int64, mediaType, path, caption string, buttons [][]map[string]string) error {
+	var replyMarkup *telegram.InlineKeyboardMarkup
+	if len(buttons) > 0 {
+		replyMarkup = buttonsToMarkup(buttons)
+	}
+	opts := &telegram.SendOpts{
+		ParseMode:   telegram.ParseModeMarkdownV2,
+		ReplyMarkup: replyMarkup,
+	}
+	switch mediaType {
+	case "photo":
+		_, err := bot.SendPhoto(chatID, path, caption, opts)
+		return err
+	case "voice":
+		_, err := bot.SendVoice(chatID, path, caption, opts)
+		return err
+	default:
+		_, err := bot.SendDocument(chatID, path, caption, opts)
+		return err
+	}
+}
+
+// buttonsToMarkup converts the tool's button format to Telegram's
+// InlineKeyboardMarkup type.
+func buttonsToMarkup(buttons [][]map[string]string) *telegram.InlineKeyboardMarkup {
+	markup := &telegram.InlineKeyboardMarkup{
+		InlineKeyboard: make([][]telegram.InlineKeyboardButton, len(buttons)),
+	}
+	for i, row := range buttons {
+		markup.InlineKeyboard[i] = make([]telegram.InlineKeyboardButton, len(row))
+		for j, btn := range row {
+			markup.InlineKeyboard[i][j] = telegram.InlineKeyboardButton{
+				Text:         btn["text"],
+				CallbackData: btn["callback_data"],
+			}
+		}
+	}
+	return markup
+}

internal/tool/send_message.go

@@ -0,0 +1,156 @@
+// Package tool provides the send_message tool — send intermediate messages,
+// files, or interactive prompts to the Telegram chat during an agent run.
+package tool
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+// SendMessageTool lets the agent send arbitrary messages to the Telegram
+// chat with optional inline keyboards and file attachments. Unlike the
+// final answer (which flows through the handler's SendResponse), this tool
+// sends messages immediately mid-task.
+type SendMessageTool struct {
+	// Sender delivers the message. Called synchronously — returns nil on
+	// success or an error if delivery failed. The tool does NOT wait for
+	// user response; use clarify for interactive prompts.
+	Sender func(text string, file string, buttons [][]map[string]string) error
+}
+
+// sendMessageArgs is the JSON schema for send_message tool arguments.
+type sendMessageArgs struct {
+	Text    string                   `json:"text"`
+	File    string                   `json:"file,omitempty"`
+	Buttons [][]sendMessageButtonArg `json:"buttons,omitempty"`
+}
+
+type sendMessageButtonArg struct {
+	Text         string `json:"text"`
+	CallbackData string `json:"callback_data"`
+}
+
+// ── Tool interface ─────────────────────────────────────────────────────
+
+func (t *SendMessageTool) Name() string { return "send_message" }
+
+func (t *SendMessageTool) Description() string {
+	return `Send an intermediate message, file, or interactive prompt to the Telegram chat.
+Use this for:
+- Multi-step progress updates (before the final answer)
+- Sending generated files (images, CSVs, zip archives)
+- Asking questions with custom inline keyboard buttons
+- Showing notifications or warnings mid-task
+
+For simple Yes/No questions, prefer the clarify tool.
+For final answers, just return the text — no need to use send_message.
+
+File type is auto-detected from extension:
+  .png/.jpg/.webp → photo   .ogg/.mp3 → voice   everything else → document`
+}
+
+func (t *SendMessageTool) Schema() any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"text": map[string]any{
+				"type":        "string",
+				"description": "Message text (MarkdownV2). Can be empty if only sending a file.",
+			},
+			"file": map[string]any{
+				"type":        "string",
+				"description": "Absolute path to a file to send as attachment (photo/document/voice/zip).",
+			},
+			"buttons": map[string]any{
+				"type": "array",
+				"items": map[string]any{
+					"type": "array",
+					"items": map[string]any{
+						"type": "object",
+						"properties": map[string]any{
+							"text": map[string]any{
+								"type":        "string",
+								"description": "Button label shown to the user.",
+							},
+							"callback_data": map[string]any{
+								"type":        "string",
+								"description": "Callback data sent when user clicks. Must start with 'cb:' for agent-routed callbacks.",
+							},
+						},
+						"required": []string{"text", "callback_data"},
+					},
+				},
+				"description": "Inline keyboard button rows. Each inner array is one row of buttons.",
+			},
+		},
+		"required": []string{"text"},
+	}
+}
+
+// Call sends the message via the injected Sender function.
+func (t *SendMessageTool) Call(argsJSON string) (string, error) {
+	if t.Sender == nil {
+		return "", fmt.Errorf("send_message: Sender not configured (platform must wire it)")
+	}
+
+	var args sendMessageArgs
+	if err := json.Unmarshal([]byte(argsJSON), &args); err != nil {
+		return "", fmt.Errorf("send_message: parse args: %w", err)
+	}
+
+	// Validate file path if provided.
+	if args.File != "" {
+		if !filepath.IsAbs(args.File) {
+			return "", fmt.Errorf("send_message: file path must be absolute: %s", args.File)
+		}
+		if _, err := os.Stat(args.File); err != nil {
+			return "", fmt.Errorf("send_message: file not found: %s: %w", args.File, err)
+		}
+	}
+
+	// Normalise buttons to the expected format.
+	buttons := make([][]map[string]string, len(args.Buttons))
+	for i, row := range args.Buttons {
+		buttons[i] = make([]map[string]string, len(row))
+		for j, btn := range row {
+			// Validate callback_data prefix convention.
+			cd := btn.CallbackData
+			if !strings.HasPrefix(cd, "cb:") && !strings.HasPrefix(cd, "apr:") && !strings.HasPrefix(cd, "den:") && !strings.HasPrefix(cd, "trs:") {
+				cd = "cb:" + cd
+			}
+			buttons[i][j] = map[string]string{
+				"text":          btn.Text,
+				"callback_data": cd,
+			}
+		}
+	}
+
+	if err := t.Sender(args.Text, args.File, buttons); err != nil {
+		return "", fmt.Errorf("send_message: %w", err)
+	}
+
+	// Build a short confirmation.
+	parts := []string{}
+	if args.File != "" {
+		parts = append(parts, "file sent")
+	}
+	if len(args.Buttons) > 0 {
+		parts = append(parts, "buttons sent")
+	}
+	if len(parts) == 0 {
+		parts = append(parts, "message sent")
+	}
+	return "✅ " + strings.Join(parts, ", "), nil
+}
+
+// ── Convenience ────────────────────────────────────────────────────────
+
+// NewSendMessageTool creates a SendMessageTool with the given sender function.
+func NewSendMessageTool(sender func(text string, file string, buttons [][]map[string]string) error) *SendMessageTool {
+	return &SendMessageTool{Sender: sender}
+}