opencode-telegram-bot 1.0.3 → 1.0.5

package/README.md

@@ -106,7 +106,12 @@ These are handled directly by the Telegram bot:
 | `/export` | Export the current session as a markdown file |
 | `/export full` | Export with all details (thinking, costs, steps) |
 | `/verbose` | Toggle verbose mode (show thinking and tool calls in chat) |
-| `/verbose on|off` | Explicitly enable/disable verbose mode |
+| `/verbose on\|off` | Explicitly enable/disable verbose mode |
+| `/model` | Show current model and usage hints |
+| `/model <keyword>` | Search models by keyword |
+| `/model <number>` | Switch to a model from the last search |
+| `/model default` | Reset to the default model |
+| `/usage` | Show token and cost usage for this session |
 | `/help` | Show available commands |
 
 ### Verbose Mode
@@ -129,6 +134,39 @@ Example with verbose mode on:
 Here's what I found in the auth module...
 ```
 
+### Model Switching
+
+Use `/model` to search and switch models without typing long names:
+
+```
+You:  /model sonnet
+Bot:  Models matching "sonnet":
+      1. claude-sonnet-4-5 (google-vertex-anthropic)
+      2. claude-sonnet-4 (anthropic)
+
+      Use /model <number> to select.
+
+You:  /model 1
+Bot:  Switched to claude-sonnet-4-5 (google-vertex-anthropic)
+```
+
+Other commands:
+
+- `/model` shows the current model and usage hints
+- `/model default` resets to the server default
+
+## Usage
+
+Use `/usage` to see the current session's token counts and estimated cost:
+
+```
+Session usage:
+- Assistant responses: 4
+- Tokens: 1200 total (input 600, output 500, reasoning 100)
+- Cache: read 1200, write 80
+- Cost: $0.0123
+```
+
 ### Session Export
 
 The `/export` command builds a markdown file from the current session and saves it to the directory where OpenCode is running. The file is also sent back to you as a Telegram document.
@@ -152,6 +190,13 @@ If you type an unknown command, the bot will reply with the list of available co
 
 Any other text message is forwarded to the OpenCode agent as a prompt. Follow-up messages go into the same session, so the agent has full conversation context. Use `/new` when you want a fresh conversation.
 
+### Files and Images
+
+You can send files or images to the bot. They are forwarded to OpenCode as file parts (with optional caption text). Text-based files (including markdown) are sent as text instead of file parts for better model compatibility. Supported types:
+
+- Photos sent via Telegram
+- Documents (PDFs, images, etc.)
+
 ## Session Management
 
 Sessions are never deleted automatically. You can have multiple sessions and switch between them.

package/dist/app.d.ts

@@ -1,6 +1,54 @@
+interface OpencodeClientLike {
+    session: {
+        list: (options?: any) => Promise<any>;
+        create: (options: any) => Promise<any>;
+        update: (options: any) => Promise<any>;
+        delete: (options: any) => Promise<any>;
+        get: (options: any) => Promise<any>;
+        messages: (options: any) => Promise<any>;
+        command: (options: any) => Promise<any>;
+        promptAsync: (options: any) => Promise<any>;
+    };
+    command: {
+        list: (options?: any) => Promise<any>;
+    };
+    provider: {
+        list: (options?: any) => Promise<any>;
+    };
+    path: {
+        get: (options?: any) => Promise<any>;
+    };
+    event: {
+        subscribe: (options?: any) => Promise<any>;
+    };
+}
 interface StartOptions {
     url: string;
     model?: string;
+    launch?: boolean;
+    client?: OpencodeClientLike;
+    botFactory?: (token: string) => TelegramBot;
+    sessionsFilePath?: string;
+}
+interface TelegramBot {
+    use: (fn: (ctx: any, next: () => Promise<void>) => Promise<void> | void) => void;
+    start: (fn: (ctx: any) => void | Promise<void>) => void;
+    help: (fn: (ctx: any) => void | Promise<void>) => void;
+    command: (command: string, fn: (ctx: any) => void | Promise<void>) => void;
+    on: (event: string, fn: (ctx: any) => void | Promise<void>) => void;
+    launch: () => Promise<void>;
+    stop: (reason?: string) => void;
+    telegram: {
+        sendMessage: (chatId: number, text: string, options?: Record<string, unknown>) => Promise<void>;
+        deleteMessage: (chatId: number, messageId: number) => Promise<void>;
+        sendDocument: (chatId: number, file: {
+            source: Buffer;
+            filename: string;
+        }) => Promise<void>;
+        getFileLink: (fileId: string) => Promise<{
+            toString(): string;
+        }>;
+    };
 }
-export declare function startTelegram(options: StartOptions): Promise<void>;
+export declare function startTelegram(options: StartOptions): Promise<TelegramBot>;
 export {};

package/dist/index.js

@@ -18584,8 +18584,9 @@ async function startTelegram(options) {
     else {
         console.log(`[Telegram] Bot is restricted to user ID: ${authorizedUserId}`);
     }
+    const sessionsFile = options.sessionsFilePath || SESSIONS_FILE;
     // Initialize OpenCode client
-    const client = client_createOpencodeClient({ baseUrl: url });
+    const client = options.client || client_createOpencodeClient({ baseUrl: url });
     // Verify connection to the OpenCode server and fetch available commands
     const opencodeCommands = new Set();
     let projectDirectory = "";
@@ -18615,7 +18616,7 @@ async function startTelegram(options) {
     }
     // Telegram-only commands that should not be forwarded to OpenCode
     const telegramCommands = new Set([
-        "start", "help", "new", "sessions", "switch", "title", "delete", "export", "verbose",
+        "start", "help", "new", "sessions", "switch", "title", "delete", "export", "verbose", "model", "usage",
     ]);
     // Map of chatId -> sessionId for the active session per chat
     const chatSessions = new Map();
@@ -18623,6 +18624,10 @@ async function startTelegram(options) {
     const knownSessionIds = new Set();
     // Set of chatIds with verbose mode enabled
     const chatVerboseMode = new Set();
+    // Map of chatId -> model override (provider/model)
+    const chatModelOverride = new Map();
+    // Map of chatId -> last search results (in-memory only)
+    const chatModelSearchResults = new Map();
     /**
      * Save the chat-to-session mapping and known session IDs to disk.
      */
@@ -18632,8 +18637,9 @@ async function startTelegram(options) {
                 active: Object.fromEntries(chatSessions),
                 known: [...knownSessionIds],
                 verbose: [...chatVerboseMode],
+                models: Object.fromEntries(chatModelOverride),
             };
-            (0,external_node_fs_.writeFileSync)(SESSIONS_FILE, JSON.stringify(data, null, 2));
+            (0,external_node_fs_.writeFileSync)(sessionsFile, JSON.stringify(data, null, 2));
         }
         catch (err) {
             console.error("[Telegram] Failed to save sessions file:", err);
@@ -18648,21 +18654,23 @@ async function startTelegram(options) {
         let storedActive = {};
         let storedKnown = [];
         let storedVerbose = [];
-        if ((0,external_node_fs_.existsSync)(SESSIONS_FILE)) {
+        let storedModels = {};
+        if ((0,external_node_fs_.existsSync)(sessionsFile)) {
             try {
-                const raw = (0,external_node_fs_.readFileSync)(SESSIONS_FILE, "utf-8");
+                const raw = (0,external_node_fs_.readFileSync)(sessionsFile, "utf-8");
                 const parsed = JSON.parse(raw);
                 if (parsed.active && typeof parsed.active === "object") {
                     // New format: { active: {...}, known: [...], verbose: [...] }
                     storedActive = parsed.active;
                     storedKnown = parsed.known || [];
                     storedVerbose = parsed.verbose || [];
+                    storedModels = parsed.models || {};
                 }
                 else {
                     // Old format: flat { chatId: sessionId }
                     storedActive = parsed;
                 }
-                console.log(`[Telegram] Loaded ${Object.keys(storedActive).length} active session(s) and ${storedKnown.length} known session(s) from ${SESSIONS_FILE}`);
+                console.log(`[Telegram] Loaded ${Object.keys(storedActive).length} active session(s) and ${storedKnown.length} known session(s) from ${sessionsFile}`);
             }
             catch (err) {
                 console.warn("[Telegram] Failed to parse sessions file:", err);
@@ -18675,6 +18683,12 @@ async function startTelegram(options) {
         if (storedVerbose.length > 0) {
             console.log(`[Telegram] Restored verbose mode for ${storedVerbose.length} chat(s)`);
         }
+        // Restore model overrides
+        for (const [chatId, modelId] of Object.entries(storedModels)) {
+            if (modelId) {
+                chatModelOverride.set(chatId, modelId);
+            }
+        }
         // Fetch all server sessions once for validation and fallback matching
         let serverSessions = [];
         try {
@@ -18777,6 +18791,45 @@ async function startTelegram(options) {
             console.warn("[Telegram] Failed to auto-title session:", err);
         }
     }
+    function buildPromptBody(chatId, parts) {
+        const promptBody = { parts };
+        const modelOverride = chatModelOverride.get(chatId) || model;
+        if (modelOverride) {
+            const [providerID, ...modelParts] = modelOverride.split("/");
+            const modelID = modelParts.join("/");
+            promptBody.model = { providerID, modelID };
+        }
+        return promptBody;
+    }
+    async function getTelegramFileUrl(fileId) {
+        const link = await bot.telegram.getFileLink(fileId);
+        return link.toString();
+    }
+    function isTextMime(mime) {
+        const normalized = mime.toLowerCase();
+        return (normalized.startsWith("text/") ||
+            normalized === "application/json" ||
+            normalized === "application/xml" ||
+            normalized === "application/yaml" ||
+            normalized === "application/x-yaml" ||
+            normalized === "application/markdown");
+    }
+    async function fetchTelegramFileText(fileId, maxBytes = 200_000) {
+        const url = await getTelegramFileUrl(fileId);
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch file: ${response.status}`);
+        }
+        const contentLength = response.headers.get("content-length");
+        if (contentLength && Number(contentLength) > maxBytes) {
+            throw new Error("File is too large to send as text.");
+        }
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > maxBytes) {
+            throw new Error("File is too large to send as text.");
+        }
+        return new TextDecoder("utf-8").decode(buffer);
+    }
     /**
      * Build a one-line summary for a tool call, picking the most meaningful input field.
      */
@@ -18986,6 +19039,40 @@ async function startTelegram(options) {
             await sendTelegramMessage(chatId, chunk);
         }
     }
+    async function handleFileMessage(ctx, fileId, mime, filename, caption) {
+        const chatId = ctx.chat.id.toString();
+        try {
+            const processingMsg = await ctx.reply("Processing your request...");
+            const sessionId = await getOrCreateSession(chatId);
+            const titleText = caption || filename || "File upload";
+            await autoTitleSession(sessionId, titleText);
+            const parts = [];
+            if (caption) {
+                parts.push({ type: "text", text: caption });
+            }
+            const normalizedMime = mime.toLowerCase();
+            if (isTextMime(normalizedMime)) {
+                const textContent = await fetchTelegramFileText(fileId);
+                const header = filename ? `File: ${filename}` : "File";
+                parts.push({
+                    type: "text",
+                    text: `${header}\n\n${textContent}`,
+                });
+            }
+            else {
+                const url = await getTelegramFileUrl(fileId);
+                parts.push({ type: "file", mime: normalizedMime, filename, url });
+            }
+            const promptBody = buildPromptBody(chatId, parts);
+            const verbose = chatVerboseMode.has(chatId);
+            await sendPromptStreaming(ctx.chat.id, sessionId, promptBody, processingMsg.message_id, verbose);
+        }
+        catch (err) {
+            console.error("[Telegram] Error processing file message:", err);
+            await handleSessionError(chatId);
+            await ctx.reply("Sorry, there was an error processing your request. Try again or use /new to start a fresh session.");
+        }
+    }
     /**
      * Handle session errors - clear invalid sessions.
      */
@@ -19010,7 +19097,9 @@ async function startTelegram(options) {
         }
     }
     // Initialize Telegram bot
-    const bot = new lib.Telegraf(token);
+    const bot = options.botFactory
+        ? options.botFactory(token)
+        : new lib.Telegraf(token);
     // Middleware to check if the user is authorized
     bot.use((ctx, next) => {
         if (!authorizedUserId) {
@@ -19039,6 +19128,8 @@ async function startTelegram(options) {
             "/export full - Export with all details (thinking, costs, steps)\n" +
             "/verbose - Toggle verbose mode (show thinking and tool calls)\n" +
             "/verbose on|off - Set verbose mode explicitly\n" +
+            "/model - Show or search available models\n" +
+            "/usage - Show token and cost usage for this session\n" +
             "/help - Show this help message\n";
         if (opencodeCommands.size > 0) {
             msg +=
@@ -19060,6 +19151,8 @@ async function startTelegram(options) {
             "/export full - Export with all details (thinking, costs, steps)\n" +
             "/verbose - Toggle verbose mode (show thinking and tool calls)\n" +
             "/verbose on|off - Set verbose mode explicitly\n" +
+            "/model - Show or search available models\n" +
+            "/usage - Show token and cost usage for this session\n" +
             "/help - Show this help message\n";
         if (opencodeCommands.size > 0) {
             msg +=
@@ -19081,9 +19174,10 @@ async function startTelegram(options) {
      */
     async function getKnownSessions() {
         const list = await client.session.list();
-        if (!list.data || list.data.length === 0)
+        const data = (list.data || []);
+        if (data.length === 0)
             return [];
-        return list.data
+        return data
             .filter((s) => knownSessionIds.has(s.id))
             .sort((a, b) => b.time.updated - a.time.updated);
     }
@@ -19245,6 +19339,161 @@ async function startTelegram(options) {
             ? "Verbose mode enabled. Responses will include thinking and tool calls."
             : "Verbose mode disabled. Responses will only show the assistant's text.");
     });
+    /**
+     * Fetch and search available models from connected providers.
+     */
+    async function searchModels(keyword) {
+        const list = await client.provider.list();
+        if (list.error || !list.data) {
+            throw new Error(`Failed to list providers: ${JSON.stringify(list.error)}`);
+        }
+        const connected = new Set(list.data.connected || []);
+        const results = [];
+        const query = keyword.toLowerCase();
+        for (const provider of list.data.all || []) {
+            if (!connected.has(provider.id))
+                continue;
+            const providerName = (provider.name || provider.id).toLowerCase();
+            const models = provider.models;
+            for (const [modelID, model] of Object.entries(models || {})) {
+                const modelName = ((model && model.name) || modelID).toLowerCase();
+                if (modelID.toLowerCase().includes(query) ||
+                    modelName.includes(query) ||
+                    providerName.includes(query)) {
+                    const displayName = `${(model && model.name) || modelID} (${provider.id})`;
+                    results.push({ providerID: provider.id, modelID, displayName });
+                }
+            }
+        }
+        return results;
+    }
+    // Handle /model command
+    // Usage: /model, /model <keyword>, /model <number>, /model default
+    bot.command("model", async (ctx) => {
+        const chatId = ctx.chat.id.toString();
+        const args = ctx.message.text.replace(/^\/model\s*/, "").trim();
+        if (!args) {
+            const current = chatModelOverride.get(chatId) || model || "server default";
+            await ctx.reply(`Current model: ${current}\n\n` +
+                "Use /model <keyword> to search available models.\n" +
+                "Use /model default to reset to the default model.");
+            return;
+        }
+        if (args.toLowerCase() === "default") {
+            chatModelOverride.delete(chatId);
+            saveSessions();
+            await ctx.reply("Model reset to the default model.");
+            return;
+        }
+        const asNumber = Number.parseInt(args, 10);
+        if (!Number.isNaN(asNumber) && String(asNumber) === args) {
+            const results = chatModelSearchResults.get(chatId) || [];
+            if (results.length === 0) {
+                await ctx.reply("No recent search results. Use /model <keyword> first.");
+                return;
+            }
+            if (asNumber < 1 || asNumber > results.length) {
+                await ctx.reply("Invalid selection. Use /model <number> from the latest search results.");
+                return;
+            }
+            const selection = results[asNumber - 1];
+            const value = `${selection.providerID}/${selection.modelID}`;
+            chatModelOverride.set(chatId, value);
+            saveSessions();
+            await ctx.reply(`Switched to ${selection.displayName}`);
+            return;
+        }
+        try {
+            const results = await searchModels(args);
+            if (results.length === 0) {
+                await ctx.reply(`No models found matching "${args}".`);
+                return;
+            }
+            const limited = results.slice(0, 10);
+            chatModelSearchResults.set(chatId, limited);
+            let msg = `Models matching "${args}":\n\n`;
+            for (const [index, item] of limited.entries()) {
+                msg += `${index + 1}. ${item.displayName}\n`;
+            }
+            if (results.length > limited.length) {
+                msg += `\nFound ${results.length} models. Refine your search to narrow the list.`;
+            }
+            msg += "\nUse /model <number> to select.";
+            await ctx.reply(msg);
+        }
+        catch (err) {
+            console.error("[Telegram] Error searching models:", err);
+            await ctx.reply("Failed to list models. Try again later.");
+        }
+    });
+    // Handle /usage command - show token and cost usage for current session
+    bot.command("usage", async (ctx) => {
+        const chatId = ctx.chat.id.toString();
+        const sessionId = chatSessions.get(chatId);
+        if (!sessionId) {
+            await ctx.reply("No active session. Send a message first to create one.");
+            return;
+        }
+        try {
+            const messagesResult = await client.session.messages({
+                path: { id: sessionId },
+            });
+            if (messagesResult.error || !messagesResult.data) {
+                throw new Error(`Failed to get messages: ${JSON.stringify(messagesResult.error)}`);
+            }
+            let assistantCount = 0;
+            let costTotal = 0;
+            let inputTokens = 0;
+            let outputTokens = 0;
+            let reasoningTokens = 0;
+            let cacheRead = 0;
+            let cacheWrite = 0;
+            for (const msg of messagesResult.data) {
+                const info = msg.info;
+                if (info.role !== "assistant")
+                    continue;
+                assistantCount += 1;
+                costTotal += info.cost || 0;
+                if (info.tokens) {
+                    inputTokens += info.tokens.input || 0;
+                    outputTokens += info.tokens.output || 0;
+                    reasoningTokens += info.tokens.reasoning || 0;
+                    cacheRead += info.tokens.cache?.read || 0;
+                    cacheWrite += info.tokens.cache?.write || 0;
+                }
+            }
+            const totalTokens = inputTokens + outputTokens + reasoningTokens;
+            const lines = [
+                `Session usage:`,
+                `- Assistant responses: ${assistantCount}`,
+                `- Tokens: ${totalTokens} total (input ${inputTokens}, output ${outputTokens}, reasoning ${reasoningTokens})`,
+                `- Cache: read ${cacheRead}, write ${cacheWrite}`,
+                `- Cost: $${costTotal.toFixed(4)}`,
+            ];
+            await ctx.reply(lines.join("\n"));
+        }
+        catch (err) {
+            console.error("[Telegram] Error getting usage:", err);
+            await ctx.reply("Failed to fetch usage. Try again later.");
+        }
+    });
+    // Handle photo messages (images)
+    bot.on("photo", async (ctx) => {
+        const photos = ctx.message.photo;
+        if (!photos || photos.length === 0)
+            return;
+        const largest = photos[photos.length - 1];
+        const caption = ctx.message.caption;
+        await handleFileMessage(ctx, largest.file_id, "image/jpeg", "photo.jpg", caption);
+    });
+    // Handle document messages (files)
+    bot.on("document", async (ctx) => {
+        const doc = ctx.message.document;
+        if (!doc)
+            return;
+        const caption = ctx.message.caption;
+        await handleFileMessage(ctx, doc.file_id, doc.mime_type || "application/octet-stream", doc.file_name, caption);
+    });
     /**
      * Render a message part to markdown.
      * In default mode: only text and tool calls (name + input/output).
@@ -19527,15 +19776,9 @@ async function startTelegram(options) {
             const sessionId = await getOrCreateSession(chatId);
             // Auto-title if this is the first message in a new session
             await autoTitleSession(sessionId, userText);
-            // Build the prompt body
-            const promptBody = {
-                parts: [{ type: "text", text: userText }],
-            };
-            if (model) {
-                const [providerID, ...modelParts] = model.split("/");
-                const modelID = modelParts.join("/");
-                promptBody.model = { providerID, modelID };
-            }
+            const promptBody = buildPromptBody(chatId, [
+                { type: "text", text: userText },
+            ]);
             const verbose = chatVerboseMode.has(chatId);
             await sendPromptStreaming(ctx.chat.id, sessionId, promptBody, processingMsg.message_id, verbose);
         }
@@ -19545,18 +19788,21 @@ async function startTelegram(options) {
             await ctx.reply("Sorry, there was an error processing your request. Try again or use /new to start a fresh session.");
         }
     });
-    try {
-        // Start the bot
-        await bot.launch();
-        console.log("[Telegram] Bot is running");
-        // Enable graceful stop
-        process.once("SIGINT", () => bot.stop("SIGINT"));
-        process.once("SIGTERM", () => bot.stop("SIGTERM"));
-    }
-    catch (error) {
-        console.error("Unable to start the Telegram bot:", error);
-        throw error;
+    if (options.launch !== false) {
+        try {
+            // Start the bot
+            await bot.launch();
+            console.log("[Telegram] Bot is running");
+            // Enable graceful stop
+            process.once("SIGINT", () => bot.stop("SIGINT"));
+            process.once("SIGTERM", () => bot.stop("SIGTERM"));
+        }
+        catch (error) {
+            console.error("Unable to start the Telegram bot:", error);
+            throw error;
+        }
     }
+    return bot;
 }
 /**
  * Format a Unix timestamp (seconds) into a human-readable relative time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-telegram-bot",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "Telegram bot that forwards messages to an OpenCode agent",
   "main": "./dist/index.js",
@@ -14,7 +14,10 @@
     "start": "tsx src/index.ts",
     "serve": "opencode serve",
     "build": "ncc build src/index.ts --out dist",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:integration": "vitest run tests/integration.test.ts"
   },
   "keywords": [
     "opencode",
@@ -35,6 +38,7 @@
   "devDependencies": {
     "@vercel/ncc": "^0.38.3",
     "tsx": "^4.0.0",
-    "@types/node": "^20.0.0"
+    "@types/node": "^20.0.0",
+    "vitest": "^2.1.5"
   }
 }