feat(telegram): add document/file message support

Users can now send documents/files to the bot via Telegram. Documents
are downloaded to ~/.odek/media/ and injected as context for the agent
(via OnDocumentMessage callback). Falls back to generated filename
if the document has no name.

Adds: DownloadDocument, OnDocumentMessage callback, handleMessage routing,
telegram.go wiring. 3 new tests.

Author: molty3000

cmd/odek/telegram.go

@@ -436,6 +436,21 @@ func telegramCmd(args []string) error {
 		return "", nil
 	}
 
+	handler.OnDocumentMessage = func(chatID int64, messageID int, fileID string, fileName string) (string, error) {
+		localPath, err := telegram.DownloadDocument(bot, fileID, fileName)
+		if err != nil {
+			handlerLog.Warn("document download failed", "chat_id", chatID, "file_name", fileName, "error", err)
+			go handleChatMessage(chatID, messageID,
+				fmt.Sprintf("[document received — download failed: %v]", err),
+				bot, handler, sessionManager, resolved, systemMessage, handlerLog)
+			return "", nil
+		}
+		go handleChatMessage(chatID, messageID,
+			fmt.Sprintf("📄 Document received and saved to %q. Use shell tools to analyze and respond.", localPath),
+			bot, handler, sessionManager, resolved, systemMessage, handlerLog)
+		return "", nil
+	}
+
 	handler.OnError = func(chatID int64, err error) {
 		handlerLog.Error("handler error", "chat_id", chatID, "error", err)
 	}

internal/telegram/download.go

@@ -121,6 +121,50 @@ func DownloadPhoto(bot *Bot, fileIDs []string) (string, error) {
 	return localPath, nil
 }
 
+// ── Document Download ─────────────────────────────────────────────────────
+
+// DownloadDocument downloads a document/file from Telegram and saves it
+// to the media directory. Returns the local file path. The file preserves
+// the original filename from the Telegram Document metadata.
+func DownloadDocument(bot *Bot, fileID, fileName string) (string, error) {
+	dir, err := MediaDir()
+	if err != nil {
+		return "", err
+	}
+
+	// Get file metadata from Telegram.
+	f, err := bot.GetFile(fileID)
+	if err != nil {
+		return "", fmt.Errorf("telegram document: get file: %w", err)
+	}
+	if f.FilePath == "" {
+		return "", fmt.Errorf("telegram document: no file path returned")
+	}
+
+	// Download raw bytes.
+	data, err := bot.DownloadFile(f.FilePath)
+	if err != nil {
+		return "", fmt.Errorf("telegram document: download: %w", err)
+	}
+
+	// Use original filename or generate one from file ID.
+	safeName := fileName
+	if safeName == "" {
+		ext := filepath.Ext(f.FilePath)
+		if ext == "" {
+			ext = ".bin"
+		}
+		safeName = "doc_" + fileID[:min(16, len(fileID))] + ext
+	}
+	localPath := filepath.Join(dir, safeName)
+
+	if err := os.WriteFile(localPath, data, 0600); err != nil {
+		return "", fmt.Errorf("telegram document: save: %w", err)
+	}
+
+	return localPath, nil
+}
+
 // ── Media Cleanup ──────────────────────────────────────────────────────────
 
 // CleanupMedia removes media files older than maxAge from the downloaded

internal/telegram/handler.go

@@ -58,6 +58,12 @@ type Handler struct {
 	// Callers should use DownloadPhoto with the last element.
 	OnPhotoMessage func(chatID int64, messageID int, fileIDs []string) (string, error)
 
+	// OnDocumentMessage is called when a document/file message is received.
+	// Returns the response text (may be empty).
+	// fileID is the Telegram file ID. Callers should use DownloadDocument
+	// and pass the document's fileName to save the file locally.
+	OnDocumentMessage func(chatID int64, messageID int, fileID string, fileName string) (string, error)
+
 	// OnError is called when a processing error occurs.
 	OnError func(chatID int64, err error)
 }
@@ -98,6 +104,7 @@ func NewHandler(bot *Bot) *Handler {
 		OnCommand:       defaultCommandHandler(),
 		OnVoiceMessage:  defaultVoiceHandler(bot),
 		OnPhotoMessage:  defaultPhotoHandler(bot),
+		OnDocumentMessage: defaultDocumentHandler(bot),
 	}
 }
 
@@ -155,6 +162,18 @@ func defaultPhotoHandler(bot *Bot) func(int64, int, []string) (string, error) {
 	}
 }
 
+// defaultDocumentHandler returns a default OnDocumentMessage callback that
+// downloads the document and returns a MEDIA: response.
+func defaultDocumentHandler(bot *Bot) func(int64, int, string, string) (string, error) {
+	return func(chatID int64, _ int, fileID string, fileName string) (string, error) {
+		path, err := DownloadDocument(bot, fileID, fileName)
+		if err != nil {
+			return "", fmt.Errorf("telegram handler: download document: %w", err)
+		}
+		return fmt.Sprintf("MEDIA:document:%s:%s", path, fileName), nil
+	}
+}
+
 // ─── Update Routing ───────────────────────────────────────────────────────
 
 // HandleUpdate routes an incoming Telegram update to the appropriate handler.
@@ -233,7 +252,21 @@ func (h *Handler) handleMessage(msg *Message) {
 				h.SendResponse(msg.Chat.ID, resp, msg.ID)
 			}
 		}
-	case msg.Text != "":
+	case msg.Document != nil:
+		if h.OnDocumentMessage != nil {
+			resp, err := h.OnDocumentMessage(msg.Chat.ID, msg.ID, msg.Document.FileID, msg.Document.FileName)
+			if err != nil {
+				h.log.Error("document message handler failed", "chat_id", msg.Chat.ID, "error", err)
+				if h.OnError != nil {
+					h.OnError(msg.Chat.ID, err)
+				}
+				return
+			}
+			if resp != "" {
+				h.SendResponse(msg.Chat.ID, resp, msg.ID)
+			}
+		}
+	case msg.Text != "": 
 		if h.OnTextMessage != nil {
 			resp, err := h.OnTextMessage(msg.Chat.ID, msg.ID, msg.Text)
 			if err != nil {

internal/telegram/handler_document_test.go

@@ -0,0 +1,106 @@
+package telegram
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestDownloadDocument_Success verifies document download with filename.
+func TestDownloadDocument_Success(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.Contains(r.URL.String(), "getFile") {
+			fmt.Fprintf(w, `{"ok":true,"result":{"file_id":"doc1","file_path":"docs/report.pdf"}}`)
+			return
+		}
+		w.Write([]byte("fake-pdf-data"))
+	}))
+	defer ts.Close()
+	bot := testBot(t, ts)
+
+	path, err := DownloadDocument(bot, "doc1", "report.pdf")
+	if err != nil {
+		t.Fatalf("DownloadDocument: %v", err)
+	}
+	if !strings.Contains(path, "report.pdf") {
+		t.Errorf("expected filename in path, got %q", path)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read file: %v", err)
+	}
+	if string(data) != "fake-pdf-data" {
+		t.Errorf("content = %q, want %q", string(data), "fake-pdf-data")
+	}
+	os.Remove(path)
+}
+
+// TestDownloadDocument_NoFileName verifies fallback when filename is empty.
+func TestDownloadDocument_NoFileName(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.Contains(r.URL.String(), "getFile") {
+			fmt.Fprintf(w, `{"ok":true,"result":{"file_id":"doc2","file_path":"docs/data"}}`)
+			return
+		}
+		w.Write([]byte("binary-data"))
+	}))
+	defer ts.Close()
+	bot := testBot(t, ts)
+
+	path, err := DownloadDocument(bot, "doc2", "")
+	if err != nil {
+		t.Fatalf("DownloadDocument: %v", err)
+	}
+	// Should have generated filename with fileID prefix
+	if !strings.Contains(filepath.Base(path), "doc_") {
+		t.Errorf("expected generated filename, got %q", path)
+	}
+	os.Remove(path)
+}
+
+// TestHandleUpdate_Document verifies document message routing.
+func TestHandleUpdate_Document(t *testing.T) {
+	var (
+		capturedFileID   string
+		capturedFileName string
+	)
+	ts := testServer(t, nil)
+	defer ts.Close()
+	bot := testBot(t, ts)
+	h := NewHandler(bot)
+
+	h.OnDocumentMessage = func(chatID int64, messageID int, fileID string, fileName string) (string, error) {
+		capturedFileID = fileID
+		capturedFileName = fileName
+		return "document received", nil
+	}
+
+	upd := Update{
+		ID: 1,
+		Message: &Message{
+			ID:   55,
+			Chat: &Chat{ID: 777},
+			From: &User{ID: 888},
+			Document: &Document{
+				FileID:   "doc_file_123",
+				FileName: "report.pdf",
+				MimeType: "application/pdf",
+				FileSize: 1024,
+			},
+		},
+	}
+
+	h.HandleUpdate(upd)
+
+	if capturedFileID != "doc_file_123" {
+		t.Errorf("fileID = %q, want %q", capturedFileID, "doc_file_123")
+	}
+	if capturedFileName != "report.pdf" {
+		t.Errorf("fileName = %q, want %q", capturedFileName, "report.pdf")
+	}
+}