@grinev/opencode-telegram-bot 0.15.0 → 0.16.1

package/.env.example

@@ -33,6 +33,11 @@ OPENCODE_MODEL_ID=big-pickle
 # Use "debug" to see detailed diagnostic logs including all bot events
 # LOG_LEVEL=info
 
+# Number of log files to keep (default: 10)
+# sources mode: keeps the latest N launch logs
+# installed mode: keeps the latest N daily logs
+# LOG_RETENTION=10
+
 # Bot Configuration (optional)
 # Maximum number of sessions shown in /sessions (default: 10)
 # SESSIONS_LIST_LIMIT=10
@@ -64,11 +69,22 @@ OPENCODE_MODEL_ID=big-pickle
 # Hide tool call service messages (default: false)
 # HIDE_TOOL_CALL_MESSAGES=false
 
+# Hide tool file edit documents sent as .txt attachments (default: false)
+# HIDE_TOOL_FILE_MESSAGES=false
+
 # Assistant message formatting mode (default: markdown)
 # markdown = convert assistant replies to Telegram MarkdownV2
 # raw = show assistant replies as plain text
 # MESSAGE_FORMAT_MODE=markdown
 
+# Directory Browser Roots (optional)
+# Comma-separated list of paths that /open is allowed to browse.
+# Supports ~ for home directory. Defaults to ~ when not set.
+# Examples:
+#   OPEN_BROWSER_ROOTS=~/projects
+#   OPEN_BROWSER_ROOTS=~/projects,~/work,/opt/repos
+# OPEN_BROWSER_ROOTS=
+
 # Code File Settings (optional)
 # Maximum file size in KB to send as document (default: 100)
 # CODE_FILE_MAX_SIZE_KB=100

package/README.md

@@ -4,6 +4,7 @@
 [![CI](https://github.com/grinev/opencode-telegram-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/grinev/opencode-telegram-bot/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![Follow updates](https://img.shields.io/badge/-Follow%20updates-333333?logo=x)](https://x.com/grin_rus)
 
 OpenCode Telegram Bot is a secure Telegram client for [OpenCode](https://opencode.ai) CLI that runs on your local machine.
 
@@ -72,7 +73,7 @@ opencode serve
 The fastest way — run directly with `npx`:
 
 ```bash
-npx @grinev/opencode-telegram-bot
+npx @grinev/opencode-telegram-bot@latest
 ```
 
 > Quick start is for npm usage. You do not need to clone this repository. If you run this command from the source directory (repository root), it may fail with `opencode-telegram: not found`. To run from sources, use the [Development](#development) section.
@@ -86,6 +87,20 @@ npm install -g @grinev/opencode-telegram-bot
 opencode-telegram start
 ```
 
+`start` runs in the foreground by default. This is the recommended mode for `systemd`, Docker, local debugging, and other external process managers.
+
+To run the bot in the built-in background mode instead:
+
+```bash
+opencode-telegram start --daemon
+opencode-telegram status
+opencode-telegram stop
+```
+
+> Built-in daemon mode is intended for standalone npm installs without an external supervisor. For `systemd`, `pm2`, or Docker, keep using `opencode-telegram start` without `--daemon`.
+
+For Linux `systemd` setup, see [`docs/LINUX_SYSTEMD_SETUP.md`](./docs/LINUX_SYSTEMD_SETUP.md).
+
 To reconfigure at any time:
 
 ```bash
@@ -109,6 +124,7 @@ opencode-telegram config
 | `/abort`          | Abort the current task                                  |
 | `/sessions`       | Browse and switch between recent sessions               |
 | `/projects`       | Switch between OpenCode projects                        |
+| `/open`           | Add a project by browsing directories                   |
 | `/tts`            | Toggle audio replies                                    |
 | `/rename`         | Rename the current session                              |
 | `/commands`       | Browse and run custom commands                          |
@@ -161,12 +177,14 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `BOT_LOCALE`                    | Bot UI language (supported locale code, e.g. `en`, `de`, `es`, `fr`, `ru`, `zh`)                             |    No    | `en`                     |
 | `SESSIONS_LIST_LIMIT`           | Sessions per page in `/sessions`                                                                             |    No    | `10`                     |
 | `PROJECTS_LIST_LIMIT`           | Projects per page in `/projects`                                                                             |    No    | `10`                     |
+| `OPEN_BROWSER_ROOTS`            | Comma-separated paths `/open` is allowed to browse (supports `~`)                                            |    No    | `~` (home directory)     |
 | `COMMANDS_LIST_LIMIT`           | Commands per page in `/commands`                                                                             |    No    | `10`                     |
 | `TASK_LIMIT`                    | Maximum number of scheduled tasks that can exist at once                                                     |    No    | `10`                     |
 | `BASH_TOOL_DISPLAY_MAX_LENGTH`  | Maximum displayed length for `bash` tool commands in Telegram summaries; longer commands are truncated       |    No    | `128`                    |
 | `SERVICE_MESSAGES_INTERVAL_SEC` | Service messages interval (thinking + tool calls); keep `>=2` to avoid Telegram rate limits, `0` = immediate |    No    | `5`                      |
 | `HIDE_THINKING_MESSAGES`        | Hide `💭 Thinking...` service messages                                                                       |    No    | `false`                  |
 | `HIDE_TOOL_CALL_MESSAGES`       | Hide tool-call service messages (`💻 bash ...`, `📖 read ...`, etc.)                                         |    No    | `false`                  |
+| `HIDE_TOOL_FILE_MESSAGES`       | Hide file edit documents sent as `.txt` attachments (`edit_*.txt`, `write_*.txt`)                            |    No    | `false`                  |
 | `RESPONSE_STREAMING`            | Stream assistant replies while they are generated across one or more Telegram messages                       |    No    | `true`                   |
 | `MESSAGE_FORMAT_MODE`           | Assistant reply formatting mode: `markdown` (Telegram MarkdownV2) or `raw`                                   |    No    | `markdown`               |
 | `CODE_FILE_MAX_SIZE_KB`         | Max file size (KB) to send as document                                                                       |    No    | `100`                    |
@@ -179,9 +197,12 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `TTS_MODEL`                     | TTS model name passed to `/audio/speech`                                                                     |    No    | `gpt-4o-mini-tts`        |
 | `TTS_VOICE`                     | OpenAI-compatible TTS voice name                                                                             |    No    | `alloy`                  |
 | `LOG_LEVEL`                     | Log level (`debug`, `info`, `warn`, `error`)                                                                 |    No    | `info`                   |
+| `LOG_RETENTION`                 | Number of log files to keep: launch files in `sources`, daily files in `installed`                           |    No    | `10`                     |
 
 > **Keep your `.env` file private.** It contains your bot token. Never commit it to version control.
 
+Logs are written to `./logs` when running from sources and to the runtime config directory `logs/` folder in `installed` mode. Log rotation depends on runtime mode: `sources` creates one file per bot launch, while `installed` appends to one file per day. Old log files are removed according to `LOG_RETENTION`.
+
 ### Voice and Audio Transcription (Optional)
 
 If `STT_API_URL` and `STT_API_KEY` are set, the bot will:

package/dist/app/start-bot-app.js

@@ -1,5 +1,6 @@
+import fs from "node:fs/promises";
 import { readFile } from "node:fs/promises";
-import { createBot } from "../bot/index.js";
+import { cleanupBotRuntime, createBot } from "../bot/index.js";
 import { config } from "../config.js";
 import { loadSettings } from "../settings/manager.js";
 import { processManager } from "../process/manager.js";
@@ -8,7 +9,10 @@ import { warmupSessionDirectoryCache } from "../session/cache-manager.js";
 import { reconcileStoredModelSelection } from "../model/manager.js";
 import { getRuntimeMode } from "../runtime/mode.js";
 import { getRuntimePaths } from "../runtime/paths.js";
-import { logger } from "../utils/logger.js";
+import { clearServiceStateFile } from "../service/manager.js";
+import { getServiceStateFilePathFromEnv, isServiceChildProcess } from "../service/runtime.js";
+import { getLogFilePath, initializeLogger, logger } from "../utils/logger.js";
+const SHUTDOWN_TIMEOUT_MS = 5000;
 async function getBotVersion() {
     try {
         const packageJsonPath = new URL("../../package.json", import.meta.url);
@@ -22,11 +26,16 @@ async function getBotVersion() {
     }
 }
 export async function startBotApp() {
+    await initializeLogger();
     const mode = getRuntimeMode();
     const runtimePaths = getRuntimePaths();
     const version = await getBotVersion();
+    const logFilePath = getLogFilePath();
     logger.info(`Starting OpenCode Telegram Bot v${version}...`);
     logger.info(`Config loaded from ${runtimePaths.envFilePath}`);
+    if (logFilePath) {
+        logger.info(`Logs are written to ${logFilePath}`);
+    }
     logger.info(`Allowed User ID: ${config.telegram.allowedUserId}`);
     logger.debug(`[Runtime] Application start mode: ${mode}`);
     await loadSettings();
@@ -35,15 +44,81 @@ export async function startBotApp() {
     await warmupSessionDirectoryCache();
     const bot = createBot();
     await scheduledTaskRuntime.initialize(bot);
+    let shutdownStarted = false;
+    let serviceStateCleared = false;
+    let shutdownTimeout = null;
+    const clearManagedServiceState = async () => {
+        if (!isServiceChildProcess() || serviceStateCleared) {
+            return;
+        }
+        const stateFilePath = getServiceStateFilePathFromEnv();
+        if (!stateFilePath) {
+            return;
+        }
+        try {
+            await fs.access(stateFilePath);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                serviceStateCleared = true;
+                return;
+            }
+            throw error;
+        }
+        await clearServiceStateFile(stateFilePath);
+        serviceStateCleared = true;
+    };
+    const shutdown = (signal) => {
+        if (shutdownStarted) {
+            return;
+        }
+        shutdownStarted = true;
+        logger.info(`[App] Received ${signal}, shutting down...`);
+        cleanupBotRuntime(`app_shutdown_${signal.toLowerCase()}`);
+        scheduledTaskRuntime.shutdown();
+        shutdownTimeout = setTimeout(() => {
+            logger.warn(`[App] Shutdown did not finish in ${SHUTDOWN_TIMEOUT_MS}ms, forcing exit.`);
+            process.exit(0);
+        }, SHUTDOWN_TIMEOUT_MS);
+        shutdownTimeout.unref?.();
+        try {
+            bot.stop();
+        }
+        catch (error) {
+            logger.warn("[App] Failed to stop Telegram bot cleanly", error);
+        }
+        void clearManagedServiceState().catch((error) => {
+            logger.warn("[App] Failed to clear managed service state", error);
+        });
+    };
+    const handleSigint = () => shutdown("SIGINT");
+    const handleSigterm = () => shutdown("SIGTERM");
+    process.on("SIGINT", handleSigint);
+    process.on("SIGTERM", handleSigterm);
     const webhookInfo = await bot.api.getWebhookInfo();
     if (webhookInfo.url) {
         logger.info(`[Bot] Webhook detected: ${webhookInfo.url}, removing...`);
         await bot.api.deleteWebhook();
         logger.info("[Bot] Webhook removed, switching to long polling");
     }
-    await bot.start({
-        onStart: (botInfo) => {
-            logger.info(`Bot @${botInfo.username} started!`);
-        },
-    });
+    try {
+        await bot.start({
+            onStart: (botInfo) => {
+                logger.info(`Bot @${botInfo.username} started!`);
+            },
+        });
+    }
+    finally {
+        process.off("SIGINT", handleSigint);
+        process.off("SIGTERM", handleSigterm);
+        if (shutdownTimeout) {
+            clearTimeout(shutdownTimeout);
+            shutdownTimeout = null;
+        }
+        cleanupBotRuntime("app_shutdown_complete");
+        scheduledTaskRuntime.shutdown();
+        await clearManagedServiceState().catch((error) => {
+            logger.warn("[App] Failed to clear managed service state", error);
+        });
+    }
 }

package/dist/bot/assistant-run-state.js

@@ -0,0 +1,60 @@
+import { logger } from "../utils/logger.js";
+class AssistantRunState {
+    runs = new Map();
+    startRun(sessionId, info) {
+        if (!sessionId) {
+            return;
+        }
+        this.runs.set(sessionId, {
+            sessionId,
+            startedAt: info.startedAt,
+            configuredAgent: info.configuredAgent,
+            configuredProviderID: info.configuredProviderID,
+            configuredModelID: info.configuredModelID,
+            hasCompletedResponse: false,
+        });
+        logger.debug(`[AssistantRunState] Started run: session=${sessionId}, agent=${info.configuredAgent || "unknown"}, model=${info.configuredProviderID || "unknown"}/${info.configuredModelID || "unknown"}`);
+    }
+    markResponseCompleted(sessionId, info) {
+        const run = this.runs.get(sessionId);
+        if (!run) {
+            return;
+        }
+        run.hasCompletedResponse = true;
+        if (info?.agent) {
+            run.actualAgent = info.agent;
+        }
+        if (info?.providerID) {
+            run.actualProviderID = info.providerID;
+        }
+        if (info?.modelID) {
+            run.actualModelID = info.modelID;
+        }
+    }
+    finishRun(sessionId, reason) {
+        const run = this.runs.get(sessionId) ?? null;
+        if (!run) {
+            return null;
+        }
+        this.runs.delete(sessionId);
+        logger.debug(`[AssistantRunState] Finished run: session=${sessionId}, reason=${reason}`);
+        return { ...run };
+    }
+    clearRun(sessionId, reason) {
+        if (!this.runs.delete(sessionId)) {
+            return;
+        }
+        logger.debug(`[AssistantRunState] Cleared run: session=${sessionId}, reason=${reason}`);
+    }
+    clearAll(reason) {
+        if (this.runs.size === 0) {
+            return;
+        }
+        logger.debug(`[AssistantRunState] Cleared all runs: count=${this.runs.size}, reason=${reason}`);
+        this.runs.clear();
+    }
+    __resetForTests() {
+        this.runs.clear();
+    }
+}
+export const assistantRunState = new AssistantRunState();

package/dist/bot/commands/abort.js

@@ -6,6 +6,7 @@ import { summaryAggregator } from "../../summary/aggregator.js";
 import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 import { foregroundSessionState } from "../../scheduled-task/foreground-state.js";
+import { assistantRunState } from "../assistant-run-state.js";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function abortLocalStreaming() {
     stopEventListening();
@@ -86,6 +87,7 @@ export async function abortCurrentOperation(ctx, options = {}) {
             const finalStatus = await pollSessionStatus(currentSession.id, currentSession.directory, 5000);
             if (finalStatus === "idle" || finalStatus === "not-found") {
                 foregroundSessionState.markIdle(currentSession.id);
+                assistantRunState.clearRun(currentSession.id, "abort_confirmed");
                 if (notifyUser && chatId !== null && waitingMessageId !== null) {
                     await ctx.api.editMessageText(chatId, waitingMessageId, t("stop.success"));
                 }

package/dist/bot/commands/commands.js

@@ -12,6 +12,7 @@ import { logger } from "../../utils/logger.js";
 import { t } from "../../i18n/index.js";
 import { foregroundSessionState } from "../../scheduled-task/foreground-state.js";
 import { config } from "../../config.js";
+import { assistantRunState } from "../assistant-run-state.js";
 const COMMANDS_CALLBACK_PREFIX = "commands:";
 const COMMANDS_CALLBACK_SELECT_PREFIX = `${COMMANDS_CALLBACK_PREFIX}select:`;
 const COMMANDS_CALLBACK_PAGE_PREFIX = `${COMMANDS_CALLBACK_PREFIX}page:`;
@@ -236,6 +237,7 @@ async function ensureSessionForProject(ctx, projectDirectory) {
         clearSession();
         summaryAggregator.clear();
         foregroundSessionState.clearAll("session_mismatch_reset");
+        assistantRunState.clearAll("session_mismatch_reset");
         await ctx.reply(t("bot.session_reset_project_mismatch"));
         currentSession = null;
     }
@@ -285,6 +287,12 @@ async function executeCommand(ctx, deps, params) {
         ? `${storedModel.providerID}/${storedModel.modelID}`
         : undefined;
     foregroundSessionState.markBusy(session.id);
+    assistantRunState.startRun(session.id, {
+        startedAt: Date.now(),
+        configuredAgent: currentAgent,
+        configuredProviderID: storedModel.providerID,
+        configuredModelID: storedModel.modelID,
+    });
     safeBackgroundTask({
         taskName: "session.command",
         task: () => opencodeClient.session.command({
@@ -299,6 +307,7 @@ async function executeCommand(ctx, deps, params) {
         onSuccess: ({ error }) => {
             if (error) {
                 foregroundSessionState.markIdle(session.id);
+                assistantRunState.clearRun(session.id, "session_command_api_error");
                 logger.error("[Commands] OpenCode API returned an error for session.command", {
                     sessionId: session.id,
                     command: params.commandName,
@@ -312,6 +321,7 @@ async function executeCommand(ctx, deps, params) {
         },
         onError: (error) => {
             foregroundSessionState.markIdle(session.id);
+            assistantRunState.clearRun(session.id, "session_command_background_error");
             logger.error("[Commands] session.command background task failed", {
                 sessionId: session.id,
                 command: params.commandName,

package/dist/bot/commands/definitions.js

@@ -16,6 +16,7 @@ const COMMAND_DEFINITIONS = [
     { command: "commands", descriptionKey: "cmd.description.commands" },
     { command: "opencode_start", descriptionKey: "cmd.description.opencode_start" },
     { command: "opencode_stop", descriptionKey: "cmd.description.opencode_stop" },
+    { command: "open", descriptionKey: "cmd.description.open" },
     { command: "help", descriptionKey: "cmd.description.help" },
 ];
 export function getLocalizedBotCommands() {

package/dist/bot/commands/open.js

@@ -0,0 +1,314 @@
+import { InlineKeyboard } from "grammy";
+import path from "node:path";
+import { appendInlineMenuCancelButton, ensureActiveInlineMenu } from "../handlers/inline-menu.js";
+import { interactionManager } from "../../interaction/manager.js";
+import { isForegroundBusy, replyBusyBlocked } from "../utils/busy-guard.js";
+import { pathToDisplayPath, scanDirectory, buildEntryLabel, buildTreeHeader, isScanError, MAX_ENTRIES_PER_PAGE, } from "../utils/file-tree.js";
+import { getBrowserRoots, isWithinAllowedRoot, isAllowedRoot } from "../utils/browser-roots.js";
+import { upsertSessionDirectory } from "../../session/cache-manager.js";
+import { getProjectByWorktree } from "../../project/manager.js";
+import { switchToProject } from "../utils/switch-project.js";
+import { logger } from "../../utils/logger.js";
+import { t } from "../../i18n/index.js";
+const CALLBACK_PREFIX = "open:";
+const CALLBACK_NAV_PREFIX = "open:nav:";
+const CALLBACK_SELECT_PREFIX = "open:sel:";
+const CALLBACK_PAGE_PREFIX = "open:pg:";
+const CALLBACK_ROOTS = "open:roots";
+const MAX_BUTTON_LABEL_LENGTH = 64;
+/**
+ * Separator used inside pagination callback data between the encoded path
+ * reference and the page number. We avoid `:` because it appears in Windows
+ * drive letters (e.g. `C:\`) and is already used as a prefix delimiter.
+ */
+const PAGE_SEPARATOR = "|";
+function truncateLabel(label, maxLen = MAX_BUTTON_LABEL_LENGTH) {
+    if (label.length <= maxLen) {
+        return label;
+    }
+    return label.slice(0, Math.max(0, maxLen - 3)) + "...";
+}
+/**
+ * Encode a path into callback data. Telegram limits callback_data to 64 bytes.
+ * Long absolute paths can exceed this, so we encode them as a compact index
+ * when necessary. The index is stored in a module-level map that lives for the
+ * duration of the current inline menu interaction.
+ */
+const pathIndex = new Map();
+let pathCounter = 0;
+/** Clear the path index. Exported so it can be called on menu cancel/cleanup. */
+export function clearOpenPathIndex() {
+    pathIndex.clear();
+    pathCounter = 0;
+}
+/**
+ * @param prefix   Callback-data prefix that precedes the path.
+ * @param fullPath Absolute path to encode.
+ * @param reserveBytes Extra bytes to reserve for a suffix that will be
+ *   appended *after* the returned value (e.g. the page separator + digits in
+ *   pagination callbacks). The total callback_data must stay ≤ 64 bytes.
+ */
+function encodePathForCallback(prefix, fullPath, reserveBytes = 0) {
+    const naive = `${prefix}${fullPath}`;
+    if (Buffer.byteLength(naive, "utf-8") + reserveBytes <= 64) {
+        return naive;
+    }
+    // Use a short numeric key instead
+    const key = `#${pathCounter++}`;
+    pathIndex.set(key, fullPath);
+    return `${prefix}${key}`;
+}
+function decodePathFromCallback(prefix, data) {
+    if (!data.startsWith(prefix)) {
+        return null;
+    }
+    const raw = data.slice(prefix.length);
+    if (raw.startsWith("#")) {
+        return pathIndex.get(raw) ?? null;
+    }
+    return raw;
+}
+/**
+ * Encode a pagination callback. The path part goes through the same 64-byte
+ * safe encoding used by nav/select callbacks, followed by a separator and
+ * the page number.
+ *
+ * We reserve bytes for the page suffix so the 64-byte check inside
+ * `encodePathForCallback` accounts for the complete final callback length.
+ */
+function encodePaginationCallback(currentPath, page) {
+    const pageSuffix = `${PAGE_SEPARATOR}${page}`;
+    const reserveBytes = Buffer.byteLength(pageSuffix, "utf-8");
+    const pathRef = encodePathForCallback(CALLBACK_PAGE_PREFIX, currentPath, reserveBytes);
+    return `${pathRef}${pageSuffix}`;
+}
+/**
+ * Decode a pagination callback into { path, page } or null on failure.
+ */
+function decodePaginationCallback(data) {
+    if (!data.startsWith(CALLBACK_PAGE_PREFIX)) {
+        return null;
+    }
+    const payload = data.slice(CALLBACK_PAGE_PREFIX.length);
+    const sepIndex = payload.lastIndexOf(PAGE_SEPARATOR);
+    if (sepIndex < 0) {
+        return null;
+    }
+    const pathRef = payload.slice(0, sepIndex);
+    const pageNum = Number.parseInt(payload.slice(sepIndex + 1), 10);
+    if (Number.isNaN(pageNum)) {
+        return null;
+    }
+    // Resolve indexed path references
+    const resolvedPath = pathRef.startsWith("#") ? (pathIndex.get(pathRef) ?? null) : pathRef;
+    if (resolvedPath === null) {
+        return null;
+    }
+    return { path: resolvedPath, page: pageNum };
+}
+function buildBrowseKeyboard(entries, currentPath, hasParent, page, totalCount) {
+    const keyboard = new InlineKeyboard();
+    const totalPages = Math.max(1, Math.ceil(totalCount / MAX_ENTRIES_PER_PAGE));
+    // Directory entries
+    for (const entry of entries) {
+        const label = truncateLabel(buildEntryLabel(entry));
+        keyboard.text(label, encodePathForCallback(CALLBACK_NAV_PREFIX, entry.fullPath)).row();
+    }
+    // Navigation: Up + Back to roots
+    // Suppress "Up" when at an allowed root (don't let user navigate above it)
+    const atRoot = isAllowedRoot(currentPath);
+    const showUp = hasParent && !atRoot;
+    const roots = getBrowserRoots();
+    const showRoots = roots.length > 1;
+    if (showUp || showRoots) {
+        if (showUp) {
+            const parentPath = path.dirname(currentPath);
+            keyboard.text(t("open.back"), encodePathForCallback(CALLBACK_NAV_PREFIX, parentPath));
+        }
+        if (showRoots) {
+            keyboard.text(t("open.roots"), CALLBACK_ROOTS);
+        }
+        keyboard.row();
+    }
+    // Pagination
+    if (totalPages > 1) {
+        if (page > 0) {
+            keyboard.text(t("open.prev_page"), encodePaginationCallback(currentPath, page - 1));
+        }
+        if (page < totalPages - 1) {
+            keyboard.text(t("open.next_page"), encodePaginationCallback(currentPath, page + 1));
+        }
+        keyboard.row();
+    }
+    // Select current folder
+    keyboard
+        .text(t("open.select_current"), encodePathForCallback(CALLBACK_SELECT_PREFIX, currentPath))
+        .row();
+    // Cancel
+    appendInlineMenuCancelButton(keyboard, "open");
+    return keyboard;
+}
+async function renderBrowseView(dirPath, page = 0) {
+    const result = await scanDirectory(dirPath, page);
+    if (isScanError(result)) {
+        return { error: result.error };
+    }
+    const { entries, totalCount, page: clampedPage, currentPath, displayPath, hasParent } = result;
+    const totalPages = Math.max(1, Math.ceil(totalCount / MAX_ENTRIES_PER_PAGE));
+    const header = buildTreeHeader(displayPath, totalCount, clampedPage, totalPages);
+    const keyboard = buildBrowseKeyboard(entries, currentPath, hasParent, clampedPage, totalCount);
+    return { text: header, keyboard };
+}
+function buildRootsKeyboard() {
+    const keyboard = new InlineKeyboard();
+    const roots = getBrowserRoots();
+    for (const root of roots) {
+        const label = truncateLabel(`📂 ${pathToDisplayPath(root)}`);
+        keyboard.text(label, encodePathForCallback(CALLBACK_NAV_PREFIX, root)).row();
+    }
+    appendInlineMenuCancelButton(keyboard, "open");
+    return keyboard;
+}
+export async function openCommand(ctx) {
+    try {
+        if (isForegroundBusy()) {
+            await replyBusyBlocked(ctx);
+            return;
+        }
+        // Reset path index for new interaction
+        clearOpenPathIndex();
+        const roots = getBrowserRoots();
+        let text;
+        let keyboard;
+        if (roots.length === 1) {
+            // Single root — navigate directly into it
+            const view = await renderBrowseView(roots[0]);
+            if ("error" in view) {
+                await ctx.reply(t("open.scan_error", { error: view.error }));
+                return;
+            }
+            text = view.text;
+            keyboard = view.keyboard;
+        }
+        else {
+            // Multiple roots — show root selection
+            text = t("open.select_root");
+            keyboard = buildRootsKeyboard();
+        }
+        const message = await ctx.reply(text, { reply_markup: keyboard });
+        interactionManager.start({
+            kind: "inline",
+            expectedInput: "callback",
+            metadata: {
+                menuKind: "open",
+                messageId: message.message_id,
+            },
+        });
+    }
+    catch (error) {
+        logger.error("[Bot] Error opening directory browser:", error);
+        await ctx.reply(t("open.open_error"));
+    }
+}
+export async function handleOpenCallback(ctx) {
+    const data = ctx.callbackQuery?.data;
+    if (!data || !data.startsWith(CALLBACK_PREFIX)) {
+        return false;
+    }
+    if (isForegroundBusy()) {
+        await replyBusyBlocked(ctx);
+        return true;
+    }
+    const isActiveMenu = await ensureActiveInlineMenu(ctx, "open");
+    if (!isActiveMenu) {
+        return true;
+    }
+    try {
+        // Back to root selection (multi-root mode)
+        if (data === CALLBACK_ROOTS) {
+            await showRoots(ctx);
+            return true;
+        }
+        // Navigate into a directory (including "up")
+        const navPath = decodePathFromCallback(CALLBACK_NAV_PREFIX, data);
+        if (navPath !== null) {
+            if (!isWithinAllowedRoot(navPath)) {
+                await ctx.answerCallbackQuery({ text: t("open.access_denied") });
+                return true;
+            }
+            await navigateTo(ctx, navPath);
+            return true;
+        }
+        // Pagination
+        const pageInfo = decodePaginationCallback(data);
+        if (pageInfo !== null) {
+            if (!isWithinAllowedRoot(pageInfo.path)) {
+                await ctx.answerCallbackQuery({ text: t("open.access_denied") });
+                return true;
+            }
+            await navigateTo(ctx, pageInfo.path, pageInfo.page);
+            return true;
+        }
+        // Select directory as project
+        const selectPath = decodePathFromCallback(CALLBACK_SELECT_PREFIX, data);
+        if (selectPath !== null) {
+            if (!isWithinAllowedRoot(selectPath)) {
+                await ctx.answerCallbackQuery({ text: t("open.access_denied") });
+                return true;
+            }
+            await selectDirectory(ctx, selectPath);
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        logger.error("[Bot] Error handling open callback:", error);
+        await ctx.answerCallbackQuery({ text: t("callback.processing_error") });
+        return true;
+    }
+}
+async function showRoots(ctx) {
+    const text = t("open.select_root");
+    const keyboard = buildRootsKeyboard();
+    await ctx.answerCallbackQuery();
+    await ctx.editMessageText(text, { reply_markup: keyboard });
+}
+async function navigateTo(ctx, dirPath, page = 0) {
+    const view = await renderBrowseView(dirPath, page);
+    if ("error" in view) {
+        await ctx.answerCallbackQuery({ text: view.error });
+        return;
+    }
+    await ctx.answerCallbackQuery();
+    await ctx.editMessageText(view.text, {
+        reply_markup: view.keyboard,
+    });
+}
+async function selectDirectory(ctx, directory) {
+    const displayPath = pathToDisplayPath(directory);
+    try {
+        logger.info(`[Bot] Adding project directory: ${directory}`);
+        // Register directory in the session cache first — getProjectByWorktree
+        // needs the entry to exist so it can resolve the project. If the
+        // subsequent switch fails, the entry stays in the cache, which is
+        // acceptable: it's a real directory the user explicitly selected and
+        // will simply appear in /projects for retry.
+        await upsertSessionDirectory(directory, Date.now());
+        const projectInfo = await getProjectByWorktree(directory);
+        const replyKeyboard = await switchToProject(ctx, { ...projectInfo, name: displayPath }, "open_project_selected");
+        await ctx.answerCallbackQuery();
+        await ctx.reply(t("open.selected", { project: displayPath }), {
+            reply_markup: replyKeyboard,
+        });
+        // Clean up the inline menu message
+        await ctx.deleteMessage();
+        // Clear path index after selection
+        clearOpenPathIndex();
+        logger.info(`[Bot] Project added and selected: ${displayPath}`);
+    }
+    catch (error) {
+        logger.error("[Bot] Error selecting directory:", error);
+        await ctx.answerCallbackQuery({ text: t("callback.processing_error") });
+        await ctx.reply(t("open.select_error"));
+    }
+}