@grinev/opencode-telegram-bot 0.16.0 → 0.16.1

package/.env.example

@@ -69,6 +69,9 @@ 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

package/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,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
@@ -170,6 +184,7 @@ When installed via npm, the configuration wizard handles the initial setup. The
 | `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`                    |

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 { 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);
@@ -40,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/index.js

@@ -36,7 +36,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";
@@ -68,6 +68,7 @@ import { prepareAssistantFinalStreamingPayload, prepareAssistantStreamingPayload
 let botInstance = null;
 let chatIdInstance = null;
 let commandsInitialized = false;
+let heartbeatTimer = null;
 const TELEGRAM_DOCUMENT_CAPTION_MAX_LENGTH = 1024;
 const RESPONSE_STREAM_THROTTLE_MS = config.bot.responseStreamThrottleMs;
 const RESPONSE_STREAM_TEXT_LIMIT = 3800;
@@ -442,6 +443,9 @@ async function ensureEventSubscription(directory) {
         if (!currentSession || currentSession.id !== fileInfo.sessionId) {
             return;
         }
+        if (config.bot.hideToolFileMessages) {
+            return;
+        }
         try {
             await toolCallStreamer.breakSession(fileInfo.sessionId, "tool_file_boundary");
             const toolMessage = formatToolInfo(fileInfo);
@@ -718,6 +722,10 @@ export function createBot() {
     clearAllInteractionState("bot_startup");
     sessionCompletionTasks.clear();
     assistantRunState.clearAll("bot_startup");
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+    }
     const botOptions = {};
     if (config.telegram.proxyUrl) {
         const proxyUrl = config.telegram.proxyUrl;
@@ -740,7 +748,7 @@ export function createBot() {
     const bot = new Bot(config.telegram.token, botOptions);
     // 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)
@@ -1053,3 +1061,18 @@ export function createBot() {
     });
     return bot;
 }
+export function cleanupBotRuntime(reason) {
+    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;
+}

package/dist/cli/args.js

@@ -1,4 +1,11 @@
-import { t } from "../i18n/index.js";
+const CLI_MESSAGES = {
+    unknownCommand: (value) => `Unknown command: ${value}`,
+    modeRequiresValue: "Option --mode requires a value: sources|installed",
+    invalidMode: (value) => `Invalid mode value: ${value}. Expected sources|installed`,
+    unknownOption: (value) => `Unknown option: ${value}`,
+    modeOnlyStart: "Option --mode is supported only for the start command",
+    daemonOnlyStart: "Option --daemon is supported only for the start command",
+};
 const SUPPORTED_COMMANDS = ["start", "status", "stop", "config"];
 function isCliCommand(value) {
     return SUPPORTED_COMMANDS.includes(value);
@@ -16,6 +23,7 @@ export function parseCliArgs(argv) {
     const args = [...argv];
     let command = "start";
     let mode;
+    let daemon = false;
     let showHelp = false;
     let currentIndex = 0;
     const firstArg = args[0];
@@ -23,8 +31,9 @@ export function parseCliArgs(argv) {
         if (!isCliCommand(firstArg)) {
             return {
                 command,
+                daemon,
                 showHelp: true,
-                error: t("cli.args.unknown_command", { value: firstArg }),
+                error: CLI_MESSAGES.unknownCommand(firstArg),
             };
         }
         command = firstArg;
@@ -37,23 +46,30 @@ export function parseCliArgs(argv) {
             currentIndex += 1;
             continue;
         }
+        if (token === "--daemon") {
+            daemon = true;
+            currentIndex += 1;
+            continue;
+        }
         if (token === "--mode") {
             const modeValue = args[currentIndex + 1];
             if (!modeValue || modeValue.startsWith("-")) {
                 return {
                     command,
+                    daemon,
                     mode,
                     showHelp: true,
-                    error: t("cli.args.mode_requires_value"),
+                    error: CLI_MESSAGES.modeRequiresValue,
                 };
             }
             const parsedMode = normalizeMode(modeValue);
             if (!parsedMode) {
                 return {
                     command,
+                    daemon,
                     mode,
                     showHelp: true,
-                    error: t("cli.args.invalid_mode", { value: modeValue }),
+                    error: CLI_MESSAGES.invalidMode(modeValue),
                 };
             }
             mode = parsedMode;
@@ -66,9 +82,10 @@ export function parseCliArgs(argv) {
             if (!parsedMode) {
                 return {
                     command,
+                    daemon,
                     mode,
                     showHelp: true,
-                    error: t("cli.args.invalid_mode", { value: modeValue }),
+                    error: CLI_MESSAGES.invalidMode(modeValue),
                 };
             }
             mode = parsedMode;
@@ -77,21 +94,33 @@ export function parseCliArgs(argv) {
         }
         return {
             command,
+            daemon,
             mode,
             showHelp: true,
-            error: t("cli.args.unknown_option", { value: token }),
+            error: CLI_MESSAGES.unknownOption(token),
         };
     }
     if (command !== "start" && mode) {
         return {
             command,
+            daemon,
+            mode,
+            showHelp: true,
+            error: CLI_MESSAGES.modeOnlyStart,
+        };
+    }
+    if (command !== "start" && daemon) {
+        return {
+            command,
+            daemon,
             mode,
             showHelp: true,
-            error: t("cli.args.mode_only_start"),
+            error: CLI_MESSAGES.daemonOnlyStart,
         };
     }
     return {
         command,
+        daemon,
         mode,
         showHelp,
     };

package/dist/cli.js

@@ -1,10 +1,38 @@
 #!/usr/bin/env node
 import { parseCliArgs } from "./cli/args.js";
 import { resolveRuntimeMode, setRuntimeMode } from "./runtime/mode.js";
-import { t } from "./i18n/index.js";
+import { getRuntimePaths } from "./runtime/paths.js";
 const EXIT_SUCCESS = 0;
 const EXIT_RUNTIME_ERROR = 1;
 const EXIT_INVALID_ARGS = 2;
+const CLI_USAGE = `Usage:
+  opencode-telegram [start] [--daemon] [--mode installed]
+  opencode-telegram status
+  opencode-telegram stop
+  opencode-telegram config
+
+Notes:
+  - No command defaults to start
+  - start runs in foreground by default
+  - --daemon is supported for the installed runtime only`;
+const CLI_MESSAGES = {
+    daemonRequiresInstalled: "Daemon mode is supported only for the installed runtime. Use `opencode-telegram start` for foreground source runs.",
+    unknownServiceError: "Unknown service error.",
+    cleanupStale: "Removed stale daemon state file.",
+    cleanupInvalid: "Removed invalid daemon state file.",
+    startSuccess: "OpenCode Telegram Bot daemon started.",
+    startAlreadyRunning: "OpenCode Telegram Bot daemon is already running.",
+    statusRunning: "Service status: running",
+    statusStopped: "Service status: stopped",
+    stopSuccess: "OpenCode Telegram Bot daemon stopped.",
+    stopAlreadyStopped: "OpenCode Telegram Bot daemon is not running.",
+    linePid: (pid) => `PID: ${pid}`,
+    lineStartedAt: (startedAt) => `Started at: ${startedAt}`,
+    lineUptimeSec: (seconds) => `Uptime: ${seconds} sec`,
+    lineLogFile: (filePath) => `Log file: ${filePath}`,
+    lineAppHome: (appHome) => `App home: ${appHome}`,
+    errorPrefix: (message) => `CLI error: ${message}`,
+};
 function writeStdout(message) {
     process.stdout.write(`${message}\n`);
 }
@@ -12,18 +40,33 @@ function writeStderr(message) {
     process.stderr.write(`${message}\n`);
 }
 function printUsage() {
-    writeStdout(t("cli.usage"));
+    writeStdout(CLI_USAGE);
 }
-function getPlaceholderMessage(command) {
-    if (command === "status") {
-        return t("cli.placeholder.status");
+function formatServiceCleanupMessage(cleanupReason) {
+    if (cleanupReason === "stale") {
+        return CLI_MESSAGES.cleanupStale;
     }
-    if (command === "stop") {
-        return t("cli.placeholder.stop");
+    if (cleanupReason === "invalid") {
+        return CLI_MESSAGES.cleanupInvalid;
     }
-    return t("cli.placeholder.unavailable");
+    return null;
 }
-async function runStartCommand(mode) {
+function formatServiceDetails(details) {
+    const uptimeSec = Math.max(0, Math.floor((Date.now() - Date.parse(details.startedAt)) / 1000));
+    return [
+        CLI_MESSAGES.linePid(details.pid),
+        CLI_MESSAGES.lineStartedAt(details.startedAt),
+        CLI_MESSAGES.lineUptimeSec(uptimeSec),
+        CLI_MESSAGES.lineLogFile(details.logFilePath),
+        CLI_MESSAGES.lineAppHome(details.appHome),
+    ].join("\n");
+}
+function writeOptionalLine(message) {
+    if (message) {
+        writeStdout(message);
+    }
+}
+async function runStartCommand(mode, daemon) {
     const modeResult = resolveRuntimeMode({
         defaultMode: "installed",
         explicitMode: mode,
@@ -32,10 +75,46 @@ async function runStartCommand(mode) {
         throw new Error(modeResult.error);
     }
     setRuntimeMode(modeResult.mode);
-    const { initializeLogger } = await import("./utils/logger.js");
-    await initializeLogger();
+    if (daemon && modeResult.mode !== "installed") {
+        throw new Error(CLI_MESSAGES.daemonRequiresInstalled);
+    }
     const { ensureRuntimeConfigForStart } = await import("./runtime/bootstrap.js");
     await ensureRuntimeConfigForStart();
+    if (daemon) {
+        const { startBotDaemon } = await import("./service/manager.js");
+        const result = await startBotDaemon(modeResult.mode);
+        const cleanupMessage = formatServiceCleanupMessage(result.cleanupReason);
+        const runtimePaths = getRuntimePaths();
+        writeOptionalLine(cleanupMessage);
+        if (!result.success) {
+            if (result.alreadyRunning && result.service) {
+                writeStdout(CLI_MESSAGES.startAlreadyRunning);
+                writeStdout("");
+                writeStdout(formatServiceDetails({
+                    pid: result.service.pid,
+                    startedAt: result.service.startedAt,
+                    logFilePath: result.service.logFilePath,
+                    appHome: runtimePaths.appHome,
+                }));
+                return EXIT_SUCCESS;
+            }
+            throw new Error(result.error || CLI_MESSAGES.unknownServiceError);
+        }
+        if (!result.service) {
+            throw new Error(CLI_MESSAGES.unknownServiceError);
+        }
+        writeStdout(CLI_MESSAGES.startSuccess);
+        writeStdout("");
+        writeStdout(formatServiceDetails({
+            pid: result.service.pid,
+            startedAt: result.service.startedAt,
+            logFilePath: result.service.logFilePath,
+            appHome: runtimePaths.appHome,
+        }));
+        return EXIT_SUCCESS;
+    }
+    const { initializeLogger } = await import("./utils/logger.js");
+    await initializeLogger();
     const { startBotApp } = await import("./app/start-bot-app.js");
     await startBotApp();
     return EXIT_SUCCESS;
@@ -48,8 +127,40 @@ async function runConfigCommand() {
     await runConfigWizardCommand();
     return EXIT_SUCCESS;
 }
-async function runPlaceholderCommand(command) {
-    writeStdout(getPlaceholderMessage(command));
+async function runStatusCommand() {
+    setRuntimeMode("installed");
+    const { getBotServiceStatus } = await import("./service/manager.js");
+    const runtimePaths = getRuntimePaths();
+    const status = await getBotServiceStatus();
+    writeOptionalLine(formatServiceCleanupMessage(status.cleanupReason));
+    if (status.status !== "running" || !status.service) {
+        writeStdout(CLI_MESSAGES.statusStopped);
+        writeStdout(CLI_MESSAGES.lineAppHome(runtimePaths.appHome));
+        return EXIT_SUCCESS;
+    }
+    writeStdout(CLI_MESSAGES.statusRunning);
+    writeStdout("");
+    writeStdout(formatServiceDetails({
+        pid: status.service.pid,
+        startedAt: status.service.startedAt,
+        logFilePath: status.service.logFilePath,
+        appHome: runtimePaths.appHome,
+    }));
+    return EXIT_SUCCESS;
+}
+async function runStopCommand() {
+    setRuntimeMode("installed");
+    const { stopBotDaemon } = await import("./service/manager.js");
+    const result = await stopBotDaemon();
+    writeOptionalLine(formatServiceCleanupMessage(result.cleanupReason));
+    if (!result.success) {
+        throw new Error(result.error || CLI_MESSAGES.unknownServiceError);
+    }
+    if (result.alreadyStopped) {
+        writeStdout(CLI_MESSAGES.stopAlreadyStopped);
+        return EXIT_SUCCESS;
+    }
+    writeStdout(CLI_MESSAGES.stopSuccess);
     return EXIT_SUCCESS;
 }
 async function runCli(argv) {
@@ -62,12 +173,15 @@ async function runCli(argv) {
         return parsedArgs.error ? EXIT_INVALID_ARGS : EXIT_SUCCESS;
     }
     if (parsedArgs.command === "start") {
-        return runStartCommand(parsedArgs.mode);
+        return runStartCommand(parsedArgs.mode, parsedArgs.daemon);
     }
     if (parsedArgs.command === "config") {
         return runConfigCommand();
     }
-    return runPlaceholderCommand(parsedArgs.command);
+    if (parsedArgs.command === "status") {
+        return runStatusCommand();
+    }
+    return runStopCommand();
 }
 void runCli(process.argv.slice(2))
     .then((exitCode) => {
@@ -75,10 +189,10 @@ void runCli(process.argv.slice(2))
 })
     .catch((error) => {
     if (error instanceof Error) {
-        writeStderr(t("cli.error.prefix", { message: error.message }));
+        writeStderr(CLI_MESSAGES.errorPrefix(error.message));
     }
     else {
-        writeStderr(t("cli.error.prefix", { message: String(error) }));
+        writeStderr(CLI_MESSAGES.errorPrefix(String(error)));
     }
     process.exitCode = EXIT_RUNTIME_ERROR;
 });

package/dist/config.js

@@ -78,6 +78,7 @@ export const config = {
         locale: getOptionalLocaleEnvVar("BOT_LOCALE", "en"),
         hideThinkingMessages: getOptionalBooleanEnvVar("HIDE_THINKING_MESSAGES", false),
         hideToolCallMessages: getOptionalBooleanEnvVar("HIDE_TOOL_CALL_MESSAGES", false),
+        hideToolFileMessages: getOptionalBooleanEnvVar("HIDE_TOOL_FILE_MESSAGES", false),
         messageFormatMode: getOptionalMessageFormatModeEnvVar("MESSAGE_FORMAT_MODE", "markdown"),
     },
     files: {

package/dist/i18n/de.js

@@ -324,16 +324,6 @@ export const de = {
     "commands.page_empty_callback": "Keine Befehle auf dieser Seite",
     "commands.page_load_error_callback": "Diese Seite konnte nicht geladen werden. Bitte versuche es erneut.",
     "cmd.description.rename": "Aktuelle Sitzung umbenennen",
-    "cli.usage": "Verwendung:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nHinweise:\n  - Ohne Befehl wird standardmäßig `start` verwendet\n  - `--mode` wird derzeit nur für `start` unterstützt",
-    "cli.placeholder.status": "Befehl `status` ist derzeit ein Platzhalter. Echte Statusprüfungen werden in der Service-Schicht hinzugefügt (Phase 5).",
-    "cli.placeholder.stop": "Befehl `stop` ist derzeit ein Platzhalter. Ein echter Stop des Hintergrundprozesses wird in der Service-Schicht hinzugefügt (Phase 5).",
-    "cli.placeholder.unavailable": "Befehl ist nicht verfügbar.",
-    "cli.error.prefix": "CLI-Fehler: {message}",
-    "cli.args.unknown_command": "Unbekannter Befehl: {value}",
-    "cli.args.mode_requires_value": "Option --mode erfordert einen Wert: sources|installed",
-    "cli.args.invalid_mode": "Ungültiger Wert für --mode: {value}. Erwartet sources|installed",
-    "cli.args.unknown_option": "Unbekannte Option: {value}",
-    "cli.args.mode_only_start": "Option --mode wird nur für den start-Befehl unterstützt",
     "legacy.models.fetch_error": "🔴 Modellliste konnte nicht geladen werden. Prüfe den Serverstatus mit /status.",
     "legacy.models.empty": "📋 Keine verfügbaren Modelle. Konfiguriere Provider in OpenCode.",
     "legacy.models.header": "📋 Verfügbare Modelle:\n\n",

package/dist/i18n/en.js

@@ -324,16 +324,6 @@ export const en = {
     "commands.page_empty_callback": "No commands on this page",
     "commands.page_load_error_callback": "Cannot load this page. Please try again.",
     "cmd.description.rename": "Rename current session",
-    "cli.usage": "Usage:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nNotes:\n  - No command defaults to `start`\n  - `--mode` is currently supported for `start` only",
-    "cli.placeholder.status": "Command `status` is currently a placeholder. Real status checks will be added in service layer (Phase 5).",
-    "cli.placeholder.stop": "Command `stop` is currently a placeholder. Real background process stop will be added in service layer (Phase 5).",
-    "cli.placeholder.unavailable": "Command is unavailable.",
-    "cli.error.prefix": "CLI error: {message}",
-    "cli.args.unknown_command": "Unknown command: {value}",
-    "cli.args.mode_requires_value": "Option --mode requires a value: sources|installed",
-    "cli.args.invalid_mode": "Invalid mode value: {value}. Expected sources|installed",
-    "cli.args.unknown_option": "Unknown option: {value}",
-    "cli.args.mode_only_start": "Option --mode is supported only for the start command",
     "legacy.models.fetch_error": "🔴 Failed to get models list. Check server status with /status.",
     "legacy.models.empty": "📋 No available models. Configure providers in OpenCode.",
     "legacy.models.header": "📋 Available models:\n\n",

package/dist/i18n/es.js

@@ -324,16 +324,6 @@ export const es = {
     "commands.page_empty_callback": "No hay comandos en esta página",
     "commands.page_load_error_callback": "No se pudo cargar esta página. Por favor, inténtalo de nuevo.",
     "cmd.description.rename": "Renombrar la sesión actual",
-    "cli.usage": "Uso:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nNotas:\n  - Sin comando, el valor por defecto es `start`\n  - `--mode` actualmente solo se admite para `start`",
-    "cli.placeholder.status": "El comando `status` es actualmente un marcador de posición. Las comprobaciones reales de estado se agregarán en la capa de servicio (Fase 5).",
-    "cli.placeholder.stop": "El comando `stop` es actualmente un marcador de posición. La detención real del proceso en segundo plano se agregará en la capa de servicio (Fase 5).",
-    "cli.placeholder.unavailable": "El comando no esta disponible.",
-    "cli.error.prefix": "Error de CLI: {message}",
-    "cli.args.unknown_command": "Comando desconocido: {value}",
-    "cli.args.mode_requires_value": "La opción --mode requiere un valor: sources|installed",
-    "cli.args.invalid_mode": "Valor de --mode inválido: {value}. Se espera sources|installed",
-    "cli.args.unknown_option": "Opción desconocida: {value}",
-    "cli.args.mode_only_start": "La opción --mode solo se admite para el comando start",
     "legacy.models.fetch_error": "🔴 No se pudo obtener la lista de modelos. Revisa el estado del servidor con /status.",
     "legacy.models.empty": "📋 No hay modelos disponibles. Configura los proveedores en OpenCode.",
     "legacy.models.header": "📋 Modelos disponibles:\n\n",

package/dist/i18n/fr.js

@@ -324,16 +324,6 @@ export const fr = {
     "commands.page_empty_callback": "Aucune commande sur cette page",
     "commands.page_load_error_callback": "Impossible de charger cette page. Veuillez réessayer.",
     "cmd.description.rename": "Renommer la session actuelle",
-    "cli.usage": "Utilisation :\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nNotes :\n  - Sans commande, `start` est utilisé par défaut\n  - `--mode` n'est actuellement pris en charge que pour `start`",
-    "cli.placeholder.status": "La commande `status` est actuellement un placeholder. Les vraies vérifications d'état seront ajoutées dans la couche service (Phase 5).",
-    "cli.placeholder.stop": "La commande `stop` est actuellement un placeholder. Le véritable arrêt du processus en arrière-plan sera ajouté dans la couche service (Phase 5).",
-    "cli.placeholder.unavailable": "Commande indisponible.",
-    "cli.error.prefix": "Erreur CLI : {message}",
-    "cli.args.unknown_command": "Commande inconnue : {value}",
-    "cli.args.mode_requires_value": "L'option --mode nécessite une valeur : sources|installed",
-    "cli.args.invalid_mode": "Valeur de mode invalide : {value}. Attendu : sources|installed",
-    "cli.args.unknown_option": "Option inconnue : {value}",
-    "cli.args.mode_only_start": "L'option --mode est prise en charge uniquement pour la commande start",
     "legacy.models.fetch_error": "🔴 Impossible de récupérer la liste des modèles. Vérifiez l'état du serveur avec /status.",
     "legacy.models.empty": "📋 Aucun modèle disponible. Configurez les fournisseurs dans OpenCode.",
     "legacy.models.header": "📋 Modèles disponibles :\n\n",

package/dist/i18n/ru.js

@@ -324,16 +324,6 @@ export const ru = {
     "commands.page_empty_callback": "На этой странице нет команд",
     "commands.page_load_error_callback": "Не удалось загрузить эту страницу. Пожалуйста, попробуйте снова.",
     "cmd.description.rename": "Переименовать текущую сессию",
-    "cli.usage": "Использование:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\nЗаметки:\n  - Без команды по умолчанию используется `start`\n  - `--mode` сейчас поддерживается только для `start`",
-    "cli.placeholder.status": "Команда `status` пока работает как заглушка. Реальная проверка статуса появится на этапе service-слоя (Этап 5).",
-    "cli.placeholder.stop": "Команда `stop` пока работает как заглушка. Реальная остановка фонового процесса появится на этапе service-слоя (Этап 5).",
-    "cli.placeholder.unavailable": "Команда недоступна.",
-    "cli.error.prefix": "CLI error: {message}",
-    "cli.args.unknown_command": "Неизвестная команда: {value}",
-    "cli.args.mode_requires_value": "Опция --mode требует значение: sources|installed",
-    "cli.args.invalid_mode": "Некорректное значение --mode: {value}. Ожидается sources|installed",
-    "cli.args.unknown_option": "Неизвестная опция: {value}",
-    "cli.args.mode_only_start": "Опция --mode поддерживается только для команды start",
     "legacy.models.fetch_error": "🔴 Не удалось получить список моделей. Проверьте статус сервера /status.",
     "legacy.models.empty": "📋 Нет доступных моделей. Настройте провайдеры через OpenCode.",
     "legacy.models.header": "📋 Доступные модели:\n\n",

package/dist/i18n/zh.js

@@ -324,16 +324,6 @@ export const zh = {
     "commands.page_empty_callback": "这一页没有命令",
     "commands.page_load_error_callback": "无法加载此页面。请重试。",
     "cmd.description.rename": "重命名当前会话",
-    "cli.usage": "用法:\n  opencode-telegram [start] [--mode sources|installed]\n  opencode-telegram status\n  opencode-telegram stop\n  opencode-telegram config\n\n注意:\n  - 无命令时默认为 `start`\n  - `--mode` 当前仅支持 `start`",
-    "cli.placeholder.status": "`status` 命令当前为占位符。实际状态检查将在服务层中添加（第5阶段）。",
-    "cli.placeholder.stop": "`stop` 命令当前为占位符。实际后台进程停止功能将在服务层中添加（第5阶段）。",
-    "cli.placeholder.unavailable": "命令不可用。",
-    "cli.error.prefix": "CLI 错误：{message}",
-    "cli.args.unknown_command": "未知命令：{value}",
-    "cli.args.mode_requires_value": "选项 --mode 需要一个值：sources|installed",
-    "cli.args.invalid_mode": "无效的 --mode 值：{value}。期望 sources|installed",
-    "cli.args.unknown_option": "未知选项：{value}",
-    "cli.args.mode_only_start": "选项 --mode 仅支持 start 命令",
     "legacy.models.fetch_error": "🔴 获取模型列表失败。请使用 /status 检查服务器状态。",
     "legacy.models.empty": "📋 没有可用模型。请在 OpenCode 中配置 providers。",
     "legacy.models.header": "📋 可用模型：\n\n",

package/dist/scheduled-task/runtime.js

@@ -122,6 +122,14 @@ export class ScheduledTaskRuntime {
             this.flushInProgress = false;
         }
     }
+    shutdown() {
+        for (const timer of this.timersByTaskId.values()) {
+            clearTimeout(timer);
+        }
+        this.timersByTaskId.clear();
+        this.runningTaskIds.clear();
+        this.initialized = false;
+    }
     __resetForTests() {
         for (const timer of this.timersByTaskId.values()) {
             clearTimeout(timer);

package/dist/service/manager.js

@@ -0,0 +1,244 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import { exec, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { getRuntimePaths } from "../runtime/paths.js";
+import { buildServiceChildEnv } from "./runtime.js";
+const execAsync = promisify(exec);
+const SERVICE_STATE_FILE_NAME = "bot-service.json";
+const PROCESS_EXIT_POLL_MS = 100;
+const DEFAULT_STOP_TIMEOUT_MS = 5000;
+function sanitizeTimestampForFile(timestamp) {
+    return timestamp.replace(/:/g, "-").replace("T", "_");
+}
+function createServiceLogFilePath(logsDirPath) {
+    const timestamp = sanitizeTimestampForFile(new Date().toISOString().slice(0, 19));
+    return path.join(logsDirPath, `bot-service-${timestamp}.log`);
+}
+function isValidServiceState(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.pid === "number" &&
+        Number.isInteger(candidate.pid) &&
+        candidate.pid > 0 &&
+        typeof candidate.startedAt === "string" &&
+        candidate.startedAt.length > 0 &&
+        typeof candidate.logFilePath === "string" &&
+        candidate.logFilePath.length > 0 &&
+        candidate.mode === "daemon");
+}
+async function writeFileAtomically(filePath, content) {
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    const tempFilePath = `${filePath}.${process.pid}.tmp`;
+    await fsPromises.writeFile(tempFilePath, content, "utf-8");
+    await fsPromises.rename(tempFilePath, filePath);
+}
+async function readServiceStateFile(filePath) {
+    try {
+        const content = await fsPromises.readFile(filePath, "utf-8");
+        const parsed = JSON.parse(content);
+        if (!isValidServiceState(parsed)) {
+            await clearServiceStateFile(filePath);
+            return { service: null, cleanupReason: "invalid" };
+        }
+        return { service: parsed, cleanupReason: null };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { service: null, cleanupReason: null };
+        }
+        if (error instanceof SyntaxError) {
+            await clearServiceStateFile(filePath);
+            return { service: null, cleanupReason: "invalid" };
+        }
+        throw error;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        if (!isProcessAlive(pid)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, PROCESS_EXIT_POLL_MS));
+    }
+    return !isProcessAlive(pid);
+}
+function getServiceEntryScriptPath() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath || scriptPath.trim().length === 0) {
+        throw new Error("Failed to resolve CLI entry script path.");
+    }
+    return path.resolve(scriptPath);
+}
+async function stopWindowsProcess(pid, timeoutMs) {
+    try {
+        await execAsync(`taskkill /PID ${pid} /T`);
+    }
+    catch {
+        // Continue with forced stop if the process is still alive.
+    }
+    if (await waitForProcessExit(pid, timeoutMs)) {
+        return;
+    }
+    await execAsync(`taskkill /F /PID ${pid} /T`);
+    await waitForProcessExit(pid, timeoutMs);
+}
+async function stopUnixProcess(pid, timeoutMs) {
+    process.kill(pid, "SIGTERM");
+    if (await waitForProcessExit(pid, timeoutMs)) {
+        return;
+    }
+    process.kill(pid, "SIGKILL");
+    await waitForProcessExit(pid, timeoutMs);
+}
+export function getServiceStateFilePath() {
+    return path.join(getRuntimePaths().runDirPath, SERVICE_STATE_FILE_NAME);
+}
+export async function clearServiceStateFile(filePath = getServiceStateFilePath()) {
+    try {
+        await fsPromises.unlink(filePath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+export async function getBotServiceStatus() {
+    const stateFilePath = getServiceStateFilePath();
+    const { service, cleanupReason } = await readServiceStateFile(stateFilePath);
+    if (!service) {
+        return {
+            status: "stopped",
+            service: null,
+            cleanupReason,
+        };
+    }
+    if (!isProcessAlive(service.pid)) {
+        await clearServiceStateFile(stateFilePath);
+        return {
+            status: "stopped",
+            service: null,
+            cleanupReason: "stale",
+        };
+    }
+    return {
+        status: "running",
+        service,
+        cleanupReason,
+    };
+}
+export async function startBotDaemon(mode) {
+    const currentStatus = await getBotServiceStatus();
+    if (currentStatus.status === "running" && currentStatus.service) {
+        return {
+            success: false,
+            service: currentStatus.service,
+            cleanupReason: currentStatus.cleanupReason,
+            alreadyRunning: true,
+        };
+    }
+    const runtimePaths = getRuntimePaths();
+    await Promise.all([
+        fsPromises.mkdir(runtimePaths.runDirPath, { recursive: true }),
+        fsPromises.mkdir(runtimePaths.logsDirPath, { recursive: true }),
+    ]);
+    const stateFilePath = getServiceStateFilePath();
+    const logFilePath = createServiceLogFilePath(runtimePaths.logsDirPath);
+    const logFileDescriptor = fs.openSync(logFilePath, "a");
+    try {
+        const childArgs = [getServiceEntryScriptPath(), "start"];
+        if (mode) {
+            childArgs.push("--mode", mode);
+        }
+        const childProcess = spawn(process.execPath, childArgs, {
+            detached: true,
+            stdio: ["ignore", logFileDescriptor, logFileDescriptor],
+            windowsHide: true,
+            env: buildServiceChildEnv(process.env, stateFilePath),
+        });
+        if (!childProcess.pid) {
+            throw new Error("Failed to start background bot process.");
+        }
+        childProcess.unref();
+        const serviceState = {
+            pid: childProcess.pid,
+            startedAt: new Date().toISOString(),
+            logFilePath,
+            mode: "daemon",
+        };
+        await writeFileAtomically(stateFilePath, `${JSON.stringify(serviceState, null, 2)}\n`);
+        return {
+            success: true,
+            service: serviceState,
+            cleanupReason: currentStatus.cleanupReason,
+        };
+    }
+    catch (error) {
+        await clearServiceStateFile(stateFilePath);
+        return {
+            success: false,
+            service: null,
+            cleanupReason: currentStatus.cleanupReason,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        fs.closeSync(logFileDescriptor);
+    }
+}
+export async function stopBotDaemon(timeoutMs = DEFAULT_STOP_TIMEOUT_MS) {
+    const currentStatus = await getBotServiceStatus();
+    if (currentStatus.status !== "running" || !currentStatus.service) {
+        return {
+            success: true,
+            service: null,
+            cleanupReason: currentStatus.cleanupReason,
+            alreadyStopped: true,
+        };
+    }
+    const { pid } = currentStatus.service;
+    try {
+        if (process.platform === "win32") {
+            await stopWindowsProcess(pid, timeoutMs);
+        }
+        else {
+            await stopUnixProcess(pid, timeoutMs);
+        }
+        if (isProcessAlive(pid)) {
+            return {
+                success: false,
+                service: currentStatus.service,
+                cleanupReason: currentStatus.cleanupReason,
+                error: `Failed to stop background bot process PID=${pid}.`,
+            };
+        }
+        await clearServiceStateFile();
+        return {
+            success: true,
+            service: currentStatus.service,
+            cleanupReason: currentStatus.cleanupReason,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            service: currentStatus.service,
+            cleanupReason: currentStatus.cleanupReason,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/service/runtime.js

@@ -0,0 +1,19 @@
+const SERVICE_CHILD_ENV_KEY = "OPENCODE_TELEGRAM_SERVICE_CHILD";
+const SERVICE_STATE_PATH_ENV_KEY = "OPENCODE_TELEGRAM_SERVICE_STATE_PATH";
+export function buildServiceChildEnv(baseEnv, stateFilePath) {
+    return {
+        ...baseEnv,
+        [SERVICE_CHILD_ENV_KEY]: "1",
+        [SERVICE_STATE_PATH_ENV_KEY]: stateFilePath,
+    };
+}
+export function isServiceChildProcess() {
+    return process.env[SERVICE_CHILD_ENV_KEY] === "1";
+}
+export function getServiceStateFilePathFromEnv() {
+    const value = process.env[SERVICE_STATE_PATH_ENV_KEY];
+    if (!value || value.trim().length === 0) {
+        return null;
+    }
+    return value;
+}

package/dist/service/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grinev/opencode-telegram-bot",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Telegram bot client for OpenCode to run and monitor coding tasks from chat.",
   "type": "module",
   "main": "./dist/index.js",