chore(cli): support bot daemon mode and graceful stop

Author: grinev

README.md

@@ -73,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.
@@ -87,6 +87,18 @@ 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`.
+
 To reconfigure at any time:
 
 ```bash

src/app/start-bot-app.ts

@@ -1,6 +1,7 @@
+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";
@@ -9,8 +10,12 @@ 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 { 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(): Promise<string> {
   try {
     const packageJsonPath = new URL("../../package.json", import.meta.url);
@@ -48,16 +53,91 @@ export async function startBotApp(): Promise<void> {
   const bot = createBot();
   await scheduledTaskRuntime.initialize(bot);
 
+  let shutdownStarted = false;
+  let serviceStateCleared = false;
+  let shutdownTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  const clearManagedServiceState = async (): Promise<void> => {
+    if (!isServiceChildProcess() || serviceStateCleared) {
+      return;
+    }
+
+    const stateFilePath = getServiceStateFilePathFromEnv();
+    if (!stateFilePath) {
+      return;
+    }
+
+    try {
+      await fs.access(stateFilePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        serviceStateCleared = true;
+        return;
+      }
+
+      throw error;
+    }
+
+    await clearServiceStateFile(stateFilePath);
+    serviceStateCleared = true;
+  };
+
+  const shutdown = (signal: NodeJS.Signals): void => {
+    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 = (): void => shutdown("SIGINT");
+  const handleSigterm = (): void => 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);
+    });
+  }
 }

src/bot/index.ts

@@ -48,7 +48,7 @@ import { questionManager } from "../question/manager.js";
 import { interactionManager } from "../interaction/manager.js";
 import { clearAllInteractionState } from "../interaction/cleanup.js";
 import { keyboardManager } from "../keyboard/manager.js";
-import { subscribeToEvents } from "../opencode/events.js";
+import { stopEventListening, subscribeToEvents } from "../opencode/events.js";
 import { summaryAggregator } from "../summary/aggregator.js";
 import { formatToolInfo } from "../summary/formatter.js";
 import { renderSubagentCards } from "../summary/subagent-formatter.js";
@@ -92,6 +92,7 @@ import {
 let botInstance: Bot<Context> | null = null;
 let chatIdInstance: number | null = null;
 let commandsInitialized = false;
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 
 const TELEGRAM_DOCUMENT_CAPTION_MAX_LENGTH = 1024;
 const RESPONSE_STREAM_THROTTLE_MS = config.bot.responseStreamThrottleMs;
@@ -882,6 +883,11 @@ export function createBot(): Bot<Context> {
   sessionCompletionTasks.clear();
   assistantRunState.clearAll("bot_startup");
 
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+
   const botOptions: ConstructorParameters<typeof Bot<Context>>[1] = {};
 
   if (config.telegram.proxyUrl) {
@@ -908,7 +914,7 @@ export function createBot(): Bot<Context> {
 
   // Heartbeat for diagnostics: verify the event loop is not blocked
   let heartbeatCounter = 0;
-  setInterval(() => {
+  heartbeatTimer = setInterval(() => {
     heartbeatCounter++;
     if (heartbeatCounter % 6 === 0) {
       // Log every 30 seconds (5 sec * 6)
@@ -1289,3 +1295,21 @@ export function createBot(): Bot<Context> {
 
   return bot;
 }
+
+export function cleanupBotRuntime(reason: string): void {
+  stopEventListening();
+  summaryAggregator.clear();
+  responseStreamer.clearAll(reason);
+  toolCallStreamer.clearAll(reason);
+  toolMessageBatcher.clearAll(reason);
+  sessionCompletionTasks.clear();
+  assistantRunState.clearAll(reason);
+
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+
+  botInstance = null;
+  chatIdInstance = null;
+}