@grinev/opencode-telegram-bot 0.19.2 → 0.20.0

package/.env.example

@@ -83,6 +83,11 @@ OPENCODE_MODEL_ID=big-pickle
 # Hide tool file edit documents sent as .txt attachments (default: false)
 # HIDE_TOOL_FILE_MESSAGES=false
 
+# Track background sessions in the currently selected project/worktree (default: true)
+# Sends short notifications when detached or non-current sessions in the current directory reply,
+# ask questions, or request permissions. Other projects/worktrees are not tracked.
+# TRACK_BACKGROUND_SESSIONS=true
+
 # Assistant message formatting mode (default: markdown)
 # markdown = convert assistant replies to Telegram MarkdownV2
 # raw = show assistant replies as plain text

package/README.md

@@ -28,6 +28,7 @@ Languages: English (`en`), Deutsch (`de`), Español (`es`), Français (`fr`), Р
 - **Remote coding** — send prompts to OpenCode from anywhere, receive complete results with code sent as files
 - **Session management** — create new sessions or continue existing ones, just like in the TUI
 - **Track live session** — follow a live OpenCode CLI session; see [Track Existing Session](#track-existing-session)
+- **Background session notifications** — get short notifications when detached or non-current sessions in the current project/worktree reply, ask questions, or request permissions
 - **Live status** — pinned message with current project/worktree, model, context usage, and changed files list, updated in real time
 - **Model switching** — pick models from OpenCode favorites and recent history directly in the chat (favorites are shown first)
 - **Agent modes** — switch between Plan and Build modes on the fly
@@ -43,6 +44,7 @@ Languages: English (`en`), Deutsch (`de`), Español (`es`), Français (`fr`), Р
 - **Git worktree switching** — browse and switch between existing git worktrees for the current repository with `/worktree`
 - **Security** — strict user ID whitelist; no one else can access your bot, even if they find it
 - **Localization** — UI localization is supported for multiple languages (`BOT_LOCALE`)
+- **Interactive file browser** — use `/ls` to browse files and directories inside the current project, open subdirectories, go back, and download files by tapping them
 
 Planned features currently in development are listed in [Current Task List](PRODUCT.md#current-task-list).
 
@@ -130,10 +132,12 @@ opencode-telegram config
 | `/status`         | Server health, current project, session, and model info |
 | `/new`            | Create a new session                                    |
 | `/abort`          | Abort the current task                                  |
+| `/detach`         | Detach from the current session without stopping it     |
 | `/sessions`       | Browse and switch between recent sessions               |
 | `/projects`       | Switch between OpenCode projects                        |
 | `/worktree`       | Switch between existing git worktrees                   |
 | `/open`           | Add a project by browsing directories                   |
+| `/ls`             | List directory contents, then tap to open or download   |
 | `/tts`            | Toggle audio replies                                    |
 | `/rename`         | Rename the current session                              |
 | `/commands`       | Browse and run custom commands                          |
@@ -213,6 +217,7 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `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`                  |
+| `TRACK_BACKGROUND_SESSIONS`                | Track detached/non-current sessions in the current selected project/worktree and send short notifications             |    No    | `true`                   |
 | `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`                    |

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

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { cleanupBotRuntime, createBot } from "../bot/index.js";
 import { config } from "../config.js";
 import { opencodeAutoRestartService } from "../opencode/auto-restart.js";
-import { refreshSessionCacheIfOpencodeReady } from "../opencode/ready-refresh.js";
+import { notifyOpencodeReadyIfHealthy, registerOpenCodeReadyRefreshHandler, } from "../opencode/ready-refresh.js";
 import { loadSettings } from "../settings/manager.js";
 import { scheduledTaskRuntime } from "../scheduled-task/runtime.js";
 import { reconcileStoredModelSelection } from "../model/manager.js";
@@ -40,12 +40,11 @@ export async function startBotApp() {
     logger.debug(`[Runtime] Application start mode: ${mode}`);
     await loadSettings();
     await reconcileStoredModelSelection();
-    const autoRestartHandledStartup = await opencodeAutoRestartService.start();
-    if (!autoRestartHandledStartup) {
-        await refreshSessionCacheIfOpencodeReady("startup");
-    }
+    registerOpenCodeReadyRefreshHandler();
     const bot = createBot();
     await scheduledTaskRuntime.initialize(bot);
+    await opencodeAutoRestartService.start();
+    await notifyOpencodeReadyIfHealthy("startup");
     let shutdownStarted = false;
     let serviceStateCleared = false;
     let shutdownTimeout = null;

package/dist/attach/service.js

@@ -1,5 +1,5 @@
 import { opencodeClient } from "../opencode/client.js";
-import { stopEventListening } from "../opencode/events.js";
+import { isOpencodeServerHealthy } from "../opencode/ready-refresh.js";
 import { summaryAggregator } from "../summary/aggregator.js";
 import { pinnedMessageManager } from "../pinned/manager.js";
 import { keyboardManager } from "../keyboard/manager.js";
@@ -11,6 +11,7 @@ import { getCurrentSession } from "../session/manager.js";
 import { getCurrentProject } from "../settings/manager.js";
 import { attachManager } from "./manager.js";
 import { logger } from "../utils/logger.js";
+import { isExpectedOpencodeUnavailableError } from "../utils/opencode-error.js";
 function getAttachBusyStatus(sessionId, statuses) {
     if (!statuses || typeof statuses !== "object") {
         return false;
@@ -18,13 +19,16 @@ function getAttachBusyStatus(sessionId, statuses) {
     const sessionStatus = statuses[sessionId];
     return sessionStatus?.type === "busy";
 }
-async function ensureAttachPinnedSession({ api, chatId, session, }) {
+async function ensureAttachPinnedSession({ api, chatId, session, forceFullRestore = false, }) {
     if (!pinnedMessageManager.isInitialized()) {
         pinnedMessageManager.initialize(api, chatId);
     }
     keyboardManager.initialize(api, chatId);
     const pinnedState = pinnedMessageManager.getState();
     if (pinnedState.sessionId === session.id && pinnedState.messageId) {
+        if (forceFullRestore) {
+            await pinnedMessageManager.loadContextFromHistory(session.id, session.directory);
+        }
         return;
     }
     if (pinnedState.messageId && pinnedState.sessionId === null) {
@@ -51,7 +55,12 @@ async function restorePendingQuestion(bot, chatId, sessionId, directory) {
         directory,
     });
     if (error || !data) {
-        logger.warn("[Attach] Failed to load pending questions during attach:", error);
+        if (isExpectedOpencodeUnavailableError(error)) {
+            logger.warn("[Attach] OpenCode server unavailable; skipping pending question restore");
+        }
+        else {
+            logger.warn("[Attach] Failed to load pending questions during attach:", error);
+        }
         return false;
     }
     const pendingQuestion = data.find((request) => request.sessionID === sessionId);
@@ -67,7 +76,12 @@ async function restorePendingPermissions(bot, chatId, sessionId, directory) {
         directory,
     });
     if (error || !data) {
-        logger.warn("[Attach] Failed to load pending permissions during attach:", error);
+        if (isExpectedOpencodeUnavailableError(error)) {
+            logger.warn("[Attach] OpenCode server unavailable; skipping pending permission restore");
+        }
+        else {
+            logger.warn("[Attach] Failed to load pending permissions during attach:", error);
+        }
         return 0;
     }
     const pendingPermissions = data.filter((request) => request.sessionID === sessionId);
@@ -77,12 +91,13 @@ async function restorePendingPermissions(bot, chatId, sessionId, directory) {
     return pendingPermissions.length;
 }
 export async function attachToSession(deps) {
-    const { bot, chatId, session, ensureEventSubscription } = deps;
+    const { bot, chatId, session, ensureEventSubscription, forceFullRestore = false } = deps;
     const alreadyAttached = attachManager.isAttachedSession(session.id, session.directory);
     await ensureAttachPinnedSession({
         api: bot.api,
         chatId,
         session,
+        forceFullRestore,
     });
     if (!alreadyAttached) {
         await ensureEventSubscription(session.directory);
@@ -98,7 +113,12 @@ export async function attachToSession(deps) {
         directory: session.directory,
     });
     if (statusesError) {
-        logger.warn("[Attach] Failed to load session status during attach:", statusesError);
+        if (isExpectedOpencodeUnavailableError(statusesError)) {
+            logger.warn("[Attach] OpenCode server unavailable; skipping session status restore");
+        }
+        else {
+            logger.warn("[Attach] Failed to load session status during attach:", statusesError);
+        }
     }
     const busy = getAttachBusyStatus(session.id, statuses);
     if (busy) {
@@ -110,7 +130,9 @@ export async function attachToSession(deps) {
     await syncPinnedAttachState();
     let restoredQuestion = false;
     let restoredPermissions = 0;
-    if (!alreadyAttached && !questionManager.isActive() && !permissionManager.isActive()) {
+    if ((!alreadyAttached || forceFullRestore) &&
+        !questionManager.isActive() &&
+        !permissionManager.isActive()) {
         restoredQuestion = await restorePendingQuestion(bot, chatId, session.id, session.directory);
         if (!restoredQuestion) {
             restoredPermissions = await restorePendingPermissions(bot, chatId, session.id, session.directory);
@@ -134,11 +156,16 @@ export async function restoreAttachedCurrentSession(deps) {
         return false;
     }
     try {
+        if (!(await isOpencodeServerHealthy())) {
+            logger.warn(`[Attach] OpenCode server is unavailable; skipping followed session restore: session=${currentSession.id}, directory=${currentSession.directory}`);
+            return false;
+        }
         await attachToSession({
             bot: deps.bot,
             chatId: deps.chatId,
             session: currentSession,
             ensureEventSubscription: deps.ensureEventSubscription,
+            forceFullRestore: deps.forceFullRestore,
         });
         logger.info(`[Attach] Restored followed session on startup: session=${currentSession.id}, directory=${currentSession.directory}`);
         return true;
@@ -152,7 +179,6 @@ export function detachAttachedSession(reason) {
     if (!attachManager.isAttached()) {
         return;
     }
-    stopEventListening();
     summaryAggregator.clear();
     attachManager.clear(reason);
     void syncPinnedAttachState();

package/dist/background-session/tracker.js

@@ -0,0 +1,137 @@
+import { isScheduledTaskSessionIgnored } from "../scheduled-task/session-ignore.js";
+import { logger } from "../utils/logger.js";
+class BackgroundSessionTracker {
+    directory = null;
+    onNotification = null;
+    sessionTitles = new Map();
+    childSessionIds = new Set();
+    completedAssistantMessageIds = new Set();
+    pendingAssistantResponsesBySessionId = new Map();
+    questionRequestIds = new Set();
+    permissionRequestIds = new Set();
+    setDirectory(directory) {
+        if (this.directory === directory) {
+            return;
+        }
+        this.clear();
+        this.directory = directory;
+    }
+    setOnNotification(callback) {
+        this.onNotification = callback;
+    }
+    clear() {
+        this.directory = null;
+        this.sessionTitles.clear();
+        this.childSessionIds.clear();
+        this.completedAssistantMessageIds.clear();
+        this.pendingAssistantResponsesBySessionId.clear();
+        this.questionRequestIds.clear();
+        this.permissionRequestIds.clear();
+    }
+    processEvent(event, currentSessionId) {
+        switch (event.type) {
+            case "session.created":
+            case "session.updated":
+                this.handleSessionInfo(event.properties);
+                break;
+            case "message.updated":
+                this.handleMessageUpdated(event.properties, currentSessionId);
+                break;
+            case "session.idle":
+                this.handleSessionIdle(event.properties, currentSessionId);
+                break;
+            case "question.asked":
+                this.handleRequestEvent("question_asked", event.properties, currentSessionId);
+                break;
+            case "permission.asked":
+                this.handleRequestEvent("permission_asked", event.properties, currentSessionId);
+                break;
+            default:
+                break;
+        }
+    }
+    handleSessionInfo(properties) {
+        const info = properties.info;
+        if (!info?.id) {
+            return;
+        }
+        const title = info.title?.trim();
+        if (title) {
+            this.sessionTitles.set(info.id, title);
+        }
+        if (info.parentID) {
+            this.childSessionIds.add(info.id);
+        }
+    }
+    handleMessageUpdated(properties, currentSessionId) {
+        const info = properties.info;
+        const sessionId = info?.sessionID;
+        const messageId = info?.id;
+        if (!sessionId || !messageId || info?.role !== "assistant" || !info.time?.completed) {
+            return;
+        }
+        if (this.shouldIgnoreSession(sessionId, currentSessionId)) {
+            return;
+        }
+        if (this.completedAssistantMessageIds.has(messageId)) {
+            return;
+        }
+        this.completedAssistantMessageIds.add(messageId);
+        this.pendingAssistantResponsesBySessionId.set(sessionId, { messageId });
+    }
+    handleSessionIdle(properties, currentSessionId) {
+        const sessionId = properties.sessionID;
+        if (!sessionId || this.shouldIgnoreSession(sessionId, currentSessionId)) {
+            return;
+        }
+        const pendingResponse = this.pendingAssistantResponsesBySessionId.get(sessionId);
+        if (!pendingResponse) {
+            return;
+        }
+        this.pendingAssistantResponsesBySessionId.delete(sessionId);
+        this.emitNotification({
+            kind: "assistant_response",
+            sessionId,
+            sessionTitle: this.sessionTitles.get(sessionId),
+            messageId: pendingResponse.messageId,
+        });
+    }
+    handleRequestEvent(kind, properties, currentSessionId) {
+        const { id, sessionID: sessionId } = properties;
+        if (!id || !sessionId) {
+            return;
+        }
+        if (this.shouldIgnoreSession(sessionId, currentSessionId)) {
+            return;
+        }
+        const deliveredRequestIds = kind === "question_asked" ? this.questionRequestIds : this.permissionRequestIds;
+        if (deliveredRequestIds.has(id)) {
+            return;
+        }
+        deliveredRequestIds.add(id);
+        this.emitNotification({
+            kind,
+            sessionId,
+            sessionTitle: this.sessionTitles.get(sessionId),
+            requestId: id,
+        });
+    }
+    shouldIgnoreSession(sessionId, currentSessionId) {
+        return (sessionId === currentSessionId ||
+            this.childSessionIds.has(sessionId) ||
+            isScheduledTaskSessionIgnored(sessionId));
+    }
+    emitNotification(notification) {
+        if (!this.onNotification) {
+            return;
+        }
+        const callback = this.onNotification;
+        setImmediate(() => {
+            Promise.resolve(callback(notification)).catch((error) => {
+                logger.error("[BackgroundSessionTracker] Failed to deliver notification:", error);
+            });
+        });
+    }
+}
+export { BackgroundSessionTracker };
+export const backgroundSessionTracker = new BackgroundSessionTracker();

package/dist/bot/commands/definitions.js

@@ -7,6 +7,7 @@ const COMMAND_DEFINITIONS = [
     { command: "status", descriptionKey: "cmd.description.status" },
     { command: "new", descriptionKey: "cmd.description.new" },
     { command: "abort", descriptionKey: "cmd.description.stop" },
+    { command: "detach", descriptionKey: "cmd.description.detach" },
     { command: "sessions", descriptionKey: "cmd.description.sessions" },
     { command: "tts", descriptionKey: "cmd.description.tts" },
     { command: "projects", descriptionKey: "cmd.description.projects" },
@@ -20,6 +21,7 @@ const COMMAND_DEFINITIONS = [
     { command: "opencode_start", descriptionKey: "cmd.description.opencode_start" },
     { command: "opencode_stop", descriptionKey: "cmd.description.opencode_stop" },
     { command: "open", descriptionKey: "cmd.description.open" },
+    { command: "ls", descriptionKey: "cmd.description.ls" },
     { command: "help", descriptionKey: "cmd.description.help" },
 ];
 export function getLocalizedBotCommands() {

package/dist/bot/commands/detach.js

@@ -0,0 +1,54 @@
+import { getCurrentProject } from "../../settings/manager.js";
+import { clearSession, getCurrentSession } from "../../session/manager.js";
+import { detachAttachedSession } from "../../attach/service.js";
+import { clearAllInteractionState } from "../../interaction/cleanup.js";
+import { pinnedMessageManager } from "../../pinned/manager.js";
+import { keyboardManager } from "../../keyboard/manager.js";
+import { foregroundSessionState } from "../../scheduled-task/foreground-state.js";
+import { assistantRunState } from "../assistant-run-state.js";
+import { clearPromptResponseMode } from "../handlers/prompt.js";
+import { logger } from "../../utils/logger.js";
+import { t } from "../../i18n/index.js";
+export async function detachCommand(ctx) {
+    try {
+        const currentProject = getCurrentProject();
+        if (!currentProject) {
+            await ctx.reply(t("detach.project_not_selected"));
+            return;
+        }
+        const currentSession = getCurrentSession();
+        if (!currentSession) {
+            await ctx.reply(t("detach.no_active_session"));
+            return;
+        }
+        detachAttachedSession("detach_command");
+        clearPromptResponseMode(currentSession.id);
+        foregroundSessionState.markIdle(currentSession.id);
+        assistantRunState.clearRun(currentSession.id, "detach_command");
+        clearAllInteractionState("detach_command");
+        clearSession();
+        if (pinnedMessageManager.isInitialized()) {
+            try {
+                await pinnedMessageManager.clear();
+            }
+            catch (error) {
+                logger.error("[Detach] Failed to clear pinned message:", error);
+            }
+        }
+        if (ctx.chat) {
+            keyboardManager.initialize(ctx.api, ctx.chat.id);
+        }
+        await pinnedMessageManager.refreshContextLimit();
+        const contextLimit = pinnedMessageManager.getContextLimit();
+        keyboardManager.updateContext(0, contextLimit);
+        const keyboard = keyboardManager.getKeyboard();
+        logger.info(`[Detach] Detached from session: id=${currentSession.id}, title="${currentSession.title}", project=${currentProject.worktree}`);
+        await ctx.reply(t("detach.success", { title: currentSession.title }), {
+            ...(keyboard ? { reply_markup: keyboard } : {}),
+        });
+    }
+    catch (error) {
+        logger.error("[Detach] Failed to detach from current session:", error);
+        await ctx.reply(t("detach.error"));
+    }
+}