appback-remoteagent 0.13.16 → 0.13.17

package/.env.example

@@ -8,6 +8,13 @@ TELEGRAM_EMPTY_RESPONSE_RETRIES=1
 TELEGRAM_RETRYABLE_ERROR_RETRIES=2
 TELEGRAM_RETRYABLE_ERROR_DELAY_MS=5000
 TELEGRAM_UNTAGGED_INTENT_RETRIES=2
+TELEGRAM_SCHEDULER_TICK_MS=1000
+TELEGRAM_TIERED_POLLING_MIN_BOTS=4
+TELEGRAM_ACTIVE_POLL_INTERVAL_MS=3000
+TELEGRAM_IDLE_POLL_INTERVAL_MS=30000
+TELEGRAM_COLD_POLL_INTERVAL_MS=300000
+TELEGRAM_ACTIVE_IDLE_MS=1800000
+TELEGRAM_COLD_IDLE_MS=21600000
 ARTIFACT_CLEANUP_ENABLED=true
 ARTIFACT_RETENTION_DAYS=30
 ARTIFACT_CLEANUP_INTERVAL_MS=86400000

package/README.md

@@ -115,6 +115,8 @@ Current command surface implemented in `src/bot.ts`:
 | `/bot main <number\|@username\|id>` | Selects the main bot. If no valid main is configured, the oldest configured bot is used |
 | `/bot remove <username\|id>` | Removes a configured Telegram bot, restarts the runtime, and confirms the result after restart |
 | `/bot reload` | Restarts the runtime and confirms the result after restart |
+| `/sleep [bot]` | Puts a sub bot into deep sleep without removing its configuration |
+| `/wake <bot>` | Wakes a sleeping sub bot |
 | `/install codex\|claude` | Runs the configured provider install or update command for the bot owner |
 | `/login codex` | Starts the Codex device-auth login flow and returns a browser URL when available |
 | `/login claude [token]` | Starts or finishes the configured Claude Code login flow for the bot owner |
@@ -125,6 +127,8 @@ Current command surface implemented in `src/bot.ts`:
 | `/batch cancel` | Discards the current batch |
 | `/batch status` | Shows current batch state |
 
+Bot sleep keeps long-idle sub bots configured while stopping their polling load. See [docs/BOT_SLEEP.md](./docs/BOT_SLEEP.md).
+
 ### 2. Terminal control
 
 Remote shell control is available through:

package/dist/bot.js

@@ -36,6 +36,8 @@ const HELP_TEXT = [
     "/bot main <number|@username|id>",
     "/bot remove <username|id>",
     "/bot reload",
+    "/sleep [bot]",
+    "/wake <bot>",
     "/install codex|claude",
     "/login codex",
     "/login claude [token]",
@@ -84,6 +86,8 @@ const RECOGNIZED_COMMANDS = new Set([
     "docs",
     "bots",
     "bot",
+    "sleep",
+    "wake",
     "install",
     "login",
     "reset",
@@ -734,6 +738,19 @@ ${bridge.formatStatus(mapping)}`);
         const result = await botManagement.reloadBots(sourceBotId, sourceBotToken, ctx.chat.id);
         await reply(ctx, result.message);
     });
+    bot.command("sleep", async (ctx) => {
+        await ensureOwnerControlAccess(ctx);
+        const sourceBotId = getBotId();
+        const { rest } = parseCommand(ctx.message?.text, 2);
+        const result = await botManagement.sleepBot(rest?.trim() ?? "", sourceBotId);
+        await reply(ctx, result.message);
+    });
+    bot.command("wake", async (ctx) => {
+        await ensureOwnerControlAccess(ctx);
+        const { rest } = parseCommand(ctx.message?.text, 2);
+        const result = await botManagement.wakeBot(rest?.trim() ?? "");
+        await reply(ctx, result.message);
+    });
     bot.command("install", async (ctx) => {
         await ensureOwnerControlAccess(ctx);
         const { args } = parseCommand(ctx.message?.text, 1);

package/dist/config.js

@@ -134,6 +134,13 @@ export const config = {
     telegramPollingBackoffMinMs: readTimeout("TELEGRAM_POLLING_BACKOFF_MIN_MS", 60_000),
     telegramPollingBackoffMaxMs: readTimeout("TELEGRAM_POLLING_BACKOFF_MAX_MS", 900_000),
     telegramPollingMaxConcurrency: readTimeout("TELEGRAM_POLLING_MAX_CONCURRENCY", 3),
+    telegramSchedulerTickMs: readTimeout("TELEGRAM_SCHEDULER_TICK_MS", 1000),
+    telegramTieredPollingMinBots: readTimeout("TELEGRAM_TIERED_POLLING_MIN_BOTS", 4),
+    telegramActivePollIntervalMs: readTimeout("TELEGRAM_ACTIVE_POLL_INTERVAL_MS", 3000),
+    telegramIdlePollIntervalMs: readTimeout("TELEGRAM_IDLE_POLL_INTERVAL_MS", 30_000),
+    telegramColdPollIntervalMs: readTimeout("TELEGRAM_COLD_POLL_INTERVAL_MS", 300_000),
+    telegramActiveIdleMs: readTimeout("TELEGRAM_ACTIVE_IDLE_MS", 1_800_000),
+    telegramColdIdleMs: readTimeout("TELEGRAM_COLD_IDLE_MS", 21_600_000),
     telegramOwnerId: readOptional("TELEGRAM_OWNER_ID"),
     telegramMessageBatchMs: readNonNegativeTimeout("TELEGRAM_MESSAGE_BATCH_MS", 1500),
     telegramTypingIntervalMs: readTimeout("TELEGRAM_TYPING_INTERVAL_MS", 10_000),

package/dist/index.js

@@ -14,6 +14,7 @@ import { BridgeService } from "./services/bridge-service.js";
 import { BotManagementService } from "./services/bot-management-service.js";
 import { LocalUiService } from "./services/local-ui-service.js";
 import { AgentMemoryService } from "./services/agent-memory-service.js";
+import { BotPollingStateService } from "./services/bot-polling-state-service.js";
 import { terminateAllSpawnedExecutions } from "./adapters/windows-shell.js";
 import { setTelegramCommandMenu } from "./telegram-command-menu.js";
 const execFileAsync = promisify(execFile);
@@ -23,10 +24,12 @@ let processLockPath;
 let telegramTransportStatusPath;
 const telegramTransportStatuses = {};
 let telegramPollingLimiter;
+let botPollingState;
 async function main() {
     processLockPath = await acquireProcessLock(config.dataDir);
     telegramTransportStatusPath = path.join(config.dataDir, "telegram-transport.json");
     telegramPollingLimiter = new AsyncSemaphore(config.telegramPollingMaxConcurrency);
+    botPollingState = new BotPollingStateService(config.dataDir);
     registerProcessLifecycle();
     const store = new FileStore(config.dataDir, config.defaultMode);
     await store.init();
@@ -49,7 +52,7 @@ async function main() {
     const availableProviders = ["codex", "claude"].filter((provider) => isProviderInstalled(provider));
     console.log(`Available providers: ${availableProviders.length > 0 ? availableProviders.join(", ") : "none"}`);
     const bridge = new BridgeService(store, adapters, config.defaultWorkspace, config.workspaceRoot, isProviderInstalled, config.defaultMode, config.codexSandboxMode);
-    const botManagement = new BotManagementService(config.dataDir, config.botRestartServiceName, config.botRestartHelperPath);
+    const botManagement = new BotManagementService(config.dataDir, config.botRestartServiceName, config.botRestartHelperPath, botPollingState);
     startArtifactCleanupSchedule(new AgentMemoryService(config.dataDir));
     if (config.localUiEnabled) {
         const localUi = new LocalUiService(bridge, config.localUiHost, config.localUiPort);
@@ -81,7 +84,7 @@ async function main() {
     await botManagement.reportPendingOperationResult().catch((error) => {
         console.error("Failed to report pending bot operation result:", error);
     });
-    await Promise.all(bots.map((bot, index) => startManualPolling(bot, index)));
+    await startManualPollingScheduler(bots);
 }
 function startArtifactCleanupSchedule(memoryService) {
     if (!config.artifactCleanupEnabled) {
@@ -132,36 +135,78 @@ main().catch((error) => {
     releaseProcessLockSync();
     process.exitCode = 1;
 });
-async function startManualPolling(bot, index) {
-    const pollingBot = bot;
-    let offset = 0;
-    let consecutiveFailures = 0;
-    let lastFailureLogAt = 0;
-    const activeHandlers = new Set();
-    const initialDelayMs = Math.min(30_000, index * 3_000 + stableJitterMs(pollingBot.botInfo.username));
-    if (initialDelayMs > 0) {
-        console.log(`Starting polling for @${pollingBot.botInfo.username} in ${formatDuration(initialDelayMs)}.`);
-        await sleep(initialDelayMs);
+async function startManualPollingScheduler(bots) {
+    const pollingBots = bots;
+    const runtimeStates = new Map();
+    const botIds = pollingBots.map((bot) => String(bot.botInfo.id));
+    await botPollingState.prune(botIds);
+    const explicitMainBotId = process.env.TELEGRAM_MAIN_BOT_ID?.trim();
+    const mainBotId = explicitMainBotId && botIds.includes(explicitMainBotId)
+        ? explicitMainBotId
+        : botIds[0];
+    for (const [index, bot] of pollingBots.entries()) {
+        const botId = String(bot.botInfo.id);
+        runtimeStates.set(botId, {
+            offset: 0,
+            inFlight: false,
+            consecutiveFailures: 0,
+            lastFailureLogAt: 0,
+        });
+        const initialDelayMs = Math.min(30_000, index * 3_000 + stableJitterMs(bot.botInfo.username));
+        await botPollingState.recordPoll(botId, {
+            username: bot.botInfo.username,
+            nextPollAt: new Date(Date.now() + initialDelayMs).toISOString(),
+        });
+        console.log(`Scheduled polling for @${bot.botInfo.username} in ${formatDuration(initialDelayMs)}.`);
     }
     while (true) {
-        try {
-            const payload = await telegramPollingLimiter.run(() => getUpdatesViaCurl(pollingBot.token, offset));
-            if (consecutiveFailures > 0) {
-                console.warn(`Telegram polling recovered for @${pollingBot.botInfo.username} after ${consecutiveFailures} failure(s).`);
-                await writeTelegramTransportStatus(pollingBot.botInfo.username, {
-                    status: "ok",
-                    consecutiveFailures: 0,
-                    lastRecoveredAt: new Date().toISOString(),
-                }).catch((error) => {
-                    console.error(`Failed to write Telegram transport recovery status for @${pollingBot.botInfo.username}:`, error);
-                });
-                consecutiveFailures = 0;
-                lastFailureLogAt = 0;
+        const now = Date.now();
+        for (const bot of pollingBots) {
+            const botId = String(bot.botInfo.id);
+            const runtime = runtimeStates.get(botId);
+            if (!runtime || runtime.inFlight) {
+                continue;
             }
-            if (payload.result.length === 0) {
+            const state = await botPollingState.get(botId, bot.botInfo.username);
+            const isMain = botId === mainBotId;
+            if (!isMain && state.sleepMode === "deep") {
                 continue;
             }
-            const orderedUpdates = orderUpdatesForDispatch(payload.result);
+            const nextPollAt = state.nextPollAt ? Date.parse(state.nextPollAt) : 0;
+            if (Number.isFinite(nextPollAt) && nextPollAt > now) {
+                continue;
+            }
+            runtime.inFlight = true;
+            void pollTelegramBot(bot, runtime, {
+                isMain,
+                totalBots: pollingBots.length,
+                lastMessageAt: state.lastMessageAt,
+            }).finally(() => {
+                runtime.inFlight = false;
+            });
+        }
+        await sleep(config.telegramSchedulerTickMs);
+    }
+}
+async function pollTelegramBot(pollingBot, runtime, options) {
+    const botId = String(pollingBot.botInfo.id);
+    try {
+        const payload = await telegramPollingLimiter.run(() => getUpdatesViaCurl(pollingBot.token, runtime.offset));
+        if (runtime.consecutiveFailures > 0) {
+            console.warn(`Telegram polling recovered for @${pollingBot.botInfo.username} after ${runtime.consecutiveFailures} failure(s).`);
+            await writeTelegramTransportStatus(pollingBot.botInfo.username, {
+                status: "ok",
+                consecutiveFailures: 0,
+                lastRecoveredAt: new Date().toISOString(),
+            }).catch((error) => {
+                console.error(`Failed to write Telegram transport recovery status for @${pollingBot.botInfo.username}:`, error);
+            });
+            runtime.consecutiveFailures = 0;
+            runtime.lastFailureLogAt = 0;
+        }
+        const now = Date.now();
+        const orderedUpdates = orderUpdatesForDispatch(payload.result);
+        if (orderedUpdates.length > 0) {
             const stopUpdates = orderedUpdates.filter((update) => isStopCommandUpdate(update));
             if (stopUpdates.length > 0) {
                 for (const update of stopUpdates) {
@@ -176,38 +221,69 @@ async function startManualPolling(bot, index) {
             }
             else {
                 for (const update of orderedUpdates) {
-                    const handler = pollingBot.handleUpdates([update]).catch((error) => {
+                    void pollingBot.handleUpdates([update]).catch((error) => {
                         console.error(`Telegram update ${update.update_id} handler failed for @${pollingBot.botInfo.username}:`, error);
-                    }).finally(() => {
-                        activeHandlers.delete(handler);
                     });
-                    activeHandlers.add(handler);
                 }
             }
-            offset = payload.result[payload.result.length - 1].update_id + 1;
+            runtime.offset = orderedUpdates[orderedUpdates.length - 1].update_id + 1;
         }
-        catch (error) {
-            consecutiveFailures += 1;
-            const issue = summarizeTelegramTransportError(error);
-            const delayMs = Math.max(nextPollingBackoffMs(consecutiveFailures, pollingBot.botInfo.username), getRetryAfterMs(error) ?? 0);
-            const now = Date.now();
-            if (consecutiveFailures === 1 || now - lastFailureLogAt >= 60_000) {
-                lastFailureLogAt = now;
-                console.error(`Polling failed for @${pollingBot.botInfo.username}: ${issue}. `
-                    + `consecutiveFailures=${consecutiveFailures}; nextRetryIn=${formatDuration(delayMs)}.`);
-            }
-            await writeTelegramTransportStatus(pollingBot.botInfo.username, {
-                status: "degraded",
-                consecutiveFailures,
-                lastIssue: issue,
-                lastFailureAt: new Date().toISOString(),
-                nextRetryAt: new Date(Date.now() + delayMs).toISOString(),
-            }).catch((statusError) => {
-                console.error(`Failed to write Telegram transport failure status for @${pollingBot.botInfo.username}:`, statusError);
-            });
-            await sleep(delayMs);
+        const lastMessageAt = orderedUpdates.some(hasMessagePayload) ? new Date(now).toISOString() : options.lastMessageAt;
+        const nextPollAt = now + computePolicyPollIntervalMs(options.isMain, options.totalBots, lastMessageAt, now);
+        await botPollingState.recordPoll(botId, {
+            username: pollingBot.botInfo.username,
+            lastPollAt: new Date(now).toISOString(),
+            lastUpdateAt: orderedUpdates.length > 0 ? new Date(now).toISOString() : undefined,
+            lastMessageAt,
+            nextPollAt: new Date(nextPollAt).toISOString(),
+            consecutiveFailures: 0,
+        });
+    }
+    catch (error) {
+        runtime.consecutiveFailures += 1;
+        const issue = summarizeTelegramTransportError(error);
+        const delayMs = Math.max(nextPollingBackoffMs(runtime.consecutiveFailures, pollingBot.botInfo.username), getRetryAfterMs(error) ?? 0);
+        const now = Date.now();
+        if (runtime.consecutiveFailures === 1 || now - runtime.lastFailureLogAt >= 60_000) {
+            runtime.lastFailureLogAt = now;
+            console.error(`Polling failed for @${pollingBot.botInfo.username}: ${issue}. `
+                + `consecutiveFailures=${runtime.consecutiveFailures}; nextRetryIn=${formatDuration(delayMs)}.`);
         }
+        await writeTelegramTransportStatus(pollingBot.botInfo.username, {
+            status: "degraded",
+            consecutiveFailures: runtime.consecutiveFailures,
+            lastIssue: issue,
+            lastFailureAt: new Date().toISOString(),
+            nextRetryAt: new Date(Date.now() + delayMs).toISOString(),
+        }).catch((statusError) => {
+            console.error(`Failed to write Telegram transport failure status for @${pollingBot.botInfo.username}:`, statusError);
+        });
+        await botPollingState.recordPoll(botId, {
+            username: pollingBot.botInfo.username,
+            consecutiveFailures: runtime.consecutiveFailures,
+            lastPollAt: new Date(now).toISOString(),
+            nextPollAt: new Date(now + delayMs).toISOString(),
+        });
+    }
+}
+function computePolicyPollIntervalMs(isMain, totalBots, lastMessageAt, now) {
+    if (isMain || totalBots < config.telegramTieredPollingMinBots) {
+        return config.telegramActivePollIntervalMs;
     }
+    const lastMessageTime = lastMessageAt ? Date.parse(lastMessageAt) : undefined;
+    const idleMs = lastMessageTime && Number.isFinite(lastMessageTime)
+        ? now - lastMessageTime
+        : Number.POSITIVE_INFINITY;
+    if (idleMs <= config.telegramActiveIdleMs) {
+        return config.telegramActivePollIntervalMs;
+    }
+    if (idleMs <= config.telegramColdIdleMs) {
+        return config.telegramIdlePollIntervalMs;
+    }
+    return config.telegramColdPollIntervalMs;
+}
+function hasMessagePayload(update) {
+    return Boolean(update.message || update.edited_message || update.channel_post);
 }
 function orderUpdatesForDispatch(updates) {
     return [...updates].sort((left, right) => {

package/dist/services/bot-management-service.js

@@ -4,18 +4,21 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
+import { BotPollingStateService } from "./bot-polling-state-service.js";
 const execFileAsync = promisify(execFile);
 export class BotManagementService {
     dataDir;
     serviceName;
     restartHelperPath;
+    pollingState;
     envPath;
     pendingPath;
     backupsDir;
-    constructor(dataDir, serviceName, restartHelperPath) {
+    constructor(dataDir, serviceName, restartHelperPath, pollingState = new BotPollingStateService(dataDir)) {
         this.dataDir = dataDir;
         this.serviceName = serviceName;
         this.restartHelperPath = restartHelperPath;
+        this.pollingState = pollingState;
         this.envPath = path.join(this.dataDir, ".env");
         this.pendingPath = path.join(this.dataDir, "pending-bot-operation.json");
         this.backupsDir = path.join(this.dataDir, "backups");
@@ -26,7 +29,7 @@ export class BotManagementService {
         if (bots.length === 0) {
             return "No Telegram bots are configured.";
         }
-        return this.formatBots(bots, env.mainBotId);
+        return this.formatBots(bots, env.mainBotId, await this.pollingState.list());
     }
     async formatCurrentBotSummary(currentBotId) {
         const env = await this.readEnvConfig();
@@ -36,13 +39,48 @@ export class BotManagementService {
         const currentLabel = current ? `@${current.username} (${current.id})` : currentBotId;
         const mainLabel = main ? `@${main.username} (${main.id})` : "not configured";
         const role = current && main && current.id === main.id ? "main" : "sub";
+        const states = await this.pollingState.list();
+        const currentState = current ? states[String(current.id)] : undefined;
         return [
             `bot: ${currentLabel}${current ? ` [${role}]` : ""}`,
             `mainBot: ${mainLabel}`,
             `botCount: ${bots.length}`,
-            "sleep: awake",
+            `sleep: ${this.pollingState.formatMode(String(current?.id ?? currentBotId), role === "main", currentState)}`,
         ].join("\n");
     }
+    async sleepBot(selector, currentBotId) {
+        const env = await this.readEnvConfig();
+        const bots = this.zipBots(env.tokens, env.usernames);
+        if (bots.length === 0) {
+            throw new Error("No Telegram bots are configured.");
+        }
+        const mainBotId = this.resolveMainBotId(bots, env.mainBotId);
+        const target = selector.trim()
+            ? this.resolveBotSelector(bots, selector)
+            : this.resolveBotSelector(bots, currentBotId);
+        if (!target) {
+            throw new Error("Usage: /sleep <bot>");
+        }
+        if (String(target.id) === mainBotId) {
+            throw new Error(`@${target.username} is the main bot and cannot enter deep sleep.`);
+        }
+        await this.pollingState.setSleepMode(String(target.id), "deep", target.username);
+        return {
+            message: `Set @${target.username} to deep sleep.\n\nIt remains configured. RemoteAgent will stop polling it until /wake is used from an awake bot.`,
+        };
+    }
+    async wakeBot(selector) {
+        const env = await this.readEnvConfig();
+        const bots = this.zipBots(env.tokens, env.usernames);
+        const target = this.resolveBotSelector(bots, selector);
+        if (!target) {
+            throw new Error("Usage: /wake <bot>");
+        }
+        await this.pollingState.setSleepMode(String(target.id), "awake", target.username);
+        return {
+            message: `Woke @${target.username}. It will be polled again.`,
+        };
+    }
     async getPendingOperationNotice() {
         const pending = await this.readPendingOperation();
         if (!pending) {
@@ -551,22 +589,51 @@ export class BotManagementService {
             || String(bot.id) === withoutAt
             || bot.token === normalized);
     }
-    formatBots(bots, mainBotId) {
+    formatBots(bots, mainBotId, states = {}) {
         if (bots.length === 0) {
             return "No Telegram bots are configured.";
         }
         return [
             `Configured bots (${bots.length})`,
-            ...this.formatBotListLines(bots, mainBotId),
+            ...this.formatBotListLines(bots, mainBotId, states),
         ].join("\n");
     }
-    formatBotListLines(bots, explicitMainBotId) {
+    formatBotListLines(bots, explicitMainBotId, states = {}) {
         const mainBotId = this.resolveMainBotId(bots, explicitMainBotId);
         return bots.map((bot, index) => {
-            const suffix = String(bot.id) === mainBotId ? " [main]" : "";
-            return `${index + 1}. @${bot.username} (${bot.id})${suffix}`;
+            const botId = String(bot.id);
+            const isMain = botId === mainBotId;
+            const state = states[botId];
+            const details = [
+                `[${isMain ? "main" : "sub"}]`,
+                this.pollingState.formatMode(botId, isMain, state),
+                state?.lastMessageAt ? `lastMessage=${this.formatAge(state.lastMessageAt)}` : undefined,
+                state?.lastPollAt ? `lastPoll=${this.formatAge(state.lastPollAt)}` : undefined,
+                state?.nextPollAt && state.sleepMode !== "deep" ? `nextPoll=${this.formatAge(state.nextPollAt)}` : undefined,
+                state?.consecutiveFailures ? `failures=${state.consecutiveFailures}` : undefined,
+            ].filter(Boolean).join(" ");
+            return `${index + 1}. @${bot.username} (${bot.id}) ${details}`;
         });
     }
+    formatAge(value) {
+        const timestamp = Date.parse(value);
+        if (!Number.isFinite(timestamp)) {
+            return value;
+        }
+        const diffMs = timestamp - Date.now();
+        const absMs = Math.abs(diffMs);
+        const suffix = diffMs > 0 ? "from now" : "ago";
+        if (absMs < 60_000) {
+            return `${Math.max(0, Math.round(absMs / 1000))}s ${suffix}`;
+        }
+        if (absMs < 3_600_000) {
+            return `${Math.round(absMs / 60_000)}m ${suffix}`;
+        }
+        if (absMs < 86_400_000) {
+            return `${Math.round(absMs / 3_600_000)}h ${suffix}`;
+        }
+        return `${Math.round(absMs / 86_400_000)}d ${suffix}`;
+    }
     resolveMainBot(bots, mainBotId) {
         if (bots.length === 0) {
             return undefined;

package/dist/services/bot-polling-state-service.js

@@ -0,0 +1,139 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_STATE = {
+    version: 1,
+    updatedAt: "",
+    bots: {},
+};
+export class BotPollingStateService {
+    filePath;
+    cache;
+    pendingWrite;
+    writeInFlight = Promise.resolve();
+    constructor(dataDir) {
+        this.filePath = path.join(dataDir, "bot-polling-state.json");
+    }
+    async get(botId, username) {
+        const state = await this.read();
+        const current = state.bots[botId] ?? {
+            botId,
+            username,
+            sleepMode: "awake",
+            consecutiveFailures: 0,
+        };
+        if (username && current.username !== username) {
+            current.username = username;
+            state.bots[botId] = current;
+            this.scheduleWrite();
+        }
+        return current;
+    }
+    async list() {
+        return { ...(await this.read()).bots };
+    }
+    async setSleepMode(botId, sleepMode, username) {
+        const state = await this.read();
+        const current = state.bots[botId] ?? {
+            botId,
+            username,
+            sleepMode,
+            consecutiveFailures: 0,
+        };
+        current.sleepMode = sleepMode;
+        if (username) {
+            current.username = username;
+        }
+        if (sleepMode === "awake") {
+            current.nextPollAt = new Date().toISOString();
+        }
+        state.bots[botId] = current;
+        await this.writeNow();
+        return current;
+    }
+    async recordPoll(botId, patch) {
+        const state = await this.read();
+        const current = state.bots[botId] ?? {
+            botId,
+            sleepMode: "awake",
+            consecutiveFailures: 0,
+        };
+        state.bots[botId] = {
+            ...current,
+            ...patch,
+            botId,
+        };
+        this.scheduleWrite();
+    }
+    async prune(validBotIds) {
+        const valid = new Set(validBotIds);
+        const state = await this.read();
+        let changed = false;
+        for (const botId of Object.keys(state.bots)) {
+            if (!valid.has(botId)) {
+                delete state.bots[botId];
+                changed = true;
+            }
+        }
+        if (changed) {
+            await this.writeNow();
+        }
+    }
+    formatMode(botId, isMain, state) {
+        if (isMain) {
+            return "awake";
+        }
+        return state?.sleepMode === "deep" ? "deep sleep" : "awake";
+    }
+    async flush() {
+        if (this.pendingWrite) {
+            clearTimeout(this.pendingWrite);
+            this.pendingWrite = undefined;
+        }
+        await this.writeNow();
+    }
+    async read() {
+        if (this.cache) {
+            return this.cache;
+        }
+        const raw = await fs.readFile(this.filePath, "utf8").catch(() => "");
+        if (!raw.trim()) {
+            this.cache = { ...DEFAULT_STATE, bots: {} };
+            return this.cache;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            this.cache = {
+                version: 1,
+                updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+                bots: parsed.bots && typeof parsed.bots === "object" ? parsed.bots : {},
+            };
+        }
+        catch {
+            this.cache = { ...DEFAULT_STATE, bots: {} };
+        }
+        return this.cache;
+    }
+    scheduleWrite() {
+        if (this.pendingWrite) {
+            return;
+        }
+        this.pendingWrite = setTimeout(() => {
+            this.pendingWrite = undefined;
+            void this.writeNow().catch((error) => {
+                console.error("Failed to write bot polling state:", error);
+            });
+        }, 1000);
+        this.pendingWrite.unref();
+    }
+    async writeNow() {
+        const state = await this.read();
+        state.updatedAt = new Date().toISOString();
+        const tmpPath = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+        this.writeInFlight = this.writeInFlight.then(async () => {
+            await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+            await fs.writeFile(tmpPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+            await fs.rename(tmpPath, this.filePath);
+        });
+        await this.writeInFlight;
+    }
+}

package/dist/telegram-command-menu.js

@@ -13,6 +13,8 @@ export const TELEGRAM_COMMAND_MENU = [
     { command: "batch", description: "Collect and send a multi-message batch" },
     { command: "bots", description: "List configured Telegram bots" },
     { command: "bot", description: "Manage Telegram bots" },
+    { command: "sleep", description: "Deep sleep a sub bot" },
+    { command: "wake", description: "Wake a sleeping sub bot" },
     { command: "install", description: "Install or update Codex or Claude" },
     { command: "login", description: "Run provider login flow" },
     { command: "reset", description: "Clear this chat binding" },

package/docs/BOT_SLEEP.md

@@ -0,0 +1,78 @@
+# Telegram Bot Sleep
+
+## Why this exists
+
+RemoteAgent can run multiple Telegram bots in one runtime.
+Each active bot needs Telegram polling.
+
+Operationally, up to three active polling bots has been stable enough.
+When more than three bots are active, polling pressure and Telegram transport errors become more likely.
+
+Sleep exists to reduce polling load without deleting bot configuration.
+
+## Definitions
+
+- main bot: the control bot that stays reachable
+- sub bot: any configured bot that is not the main bot
+- awake: the bot is polled normally
+- deep sleep: the bot is configured but not polled
+
+Sleep is not removal.
+Removing a bot deletes it from runtime configuration.
+Sleeping a bot keeps the bot registered and preserves its sessions.
+
+## Policy
+
+1. The main bot must not enter deep sleep.
+2. Sub bots may enter deep sleep.
+3. The main bot can wake a sleeping sub bot.
+4. Bot doctor and sleep are separate features.
+5. Bot doctor may remove permanently invalid Telegram bots.
+6. Sleep must never remove a bot token or session state.
+7. User-facing list output should show bot role and sleep state.
+
+## Polling Strategy
+
+The intended strategy is tiered:
+
+1. recently used bots poll normally
+2. idle bots poll less often
+3. manually sleeping bots do not poll
+
+This lets frequently used agents stay responsive while long-idle agents stop consuming polling capacity.
+
+## Commands
+
+Command surface:
+
+```text
+/sleep <bot>
+/wake <bot>
+/bot main <bot>
+/bots
+/list
+```
+
+Expected behavior:
+
+- `/sleep <bot>` puts a sub bot into deep sleep
+- `/sleep` without a target may sleep the current bot only when it is not the main bot
+- `/wake <bot>` wakes a sleeping sub bot
+- `/bots` shows main/sub and awake/sleeping state
+- `/list` shows session state and bot state where relevant
+
+## Non-goals
+
+- Do not infer sleep from natural-language provider replies.
+- Do not treat sleep as `/bot remove`.
+- Do not let Codex or Claude decide which bot should be removed.
+- Do not create a separate sleep-only bot registry that can drift from configured bots.
+
+## Implementation Notes
+
+Sleep state should be keyed by stable Telegram bot id, not by display index.
+
+Display indexes are only for user convenience.
+Internal actions must resolve to bot id.
+
+The runtime should still keep one always-awake control path through the main bot.

package/docs/OPERATIONS.md

@@ -35,6 +35,10 @@ Current production bot ownership is intentionally split:
 Do not run the same Telegram bot token from multiple runtimes at the same time.
 Bot polling conflicts are treated as incidents, not harmless warnings.
 
+When a runtime has more than three configured Telegram bots, polling pressure can become operationally visible.
+Bot sleep is the planned mitigation: keep one main bot reachable and let long-idle sub bots stop polling without removing their configuration.
+See [BOT_SLEEP.md](./BOT_SLEEP.md).
+
 ## Workspace policy
 
 Default fresh sessions should not use a broad parent folder like `/home/au2223/projects` as their direct working directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appback-remoteagent",
-  "version": "0.13.16",
+  "version": "0.13.17",
   "description": "Personal installable session server for continuing local AI work across PC and Telegram",
   "license": "MIT",
   "type": "module",