appback-remoteagent 0.16.0 → 0.17.0

package/README.md

@@ -123,6 +123,9 @@ Current command surface implemented in `src/bot.ts`:
 | `/batch done` | Alias for `/batch send` |
 | `/batch cancel` | Discards the current batch |
 | `/batch status` | Shows current batch state |
+| `/queue` | Lists instructions waiting behind the active session work |
+| `/queue remove <id>` | Removes one waiting instruction by its `Q001`-style id |
+| `/queue del` | Removes the most recently queued instruction |
 
 Multi-bot polling is tiered by recent activity and active provider work. See [docs/BOT_POLLING_POLICY.md](./docs/BOT_POLLING_POLICY.md).
 

package/dist/bot.js

@@ -24,6 +24,7 @@ const HELP_TEXT = [
     "/attach codex <thread_id>",
     "/attach claude <session_id>",
     "/model [name]",
+    "/queue [remove <id>|del]",
     "/stop",
     "/sandbox codex <read-only|workspace-write|danger-full-access>",
     "/status",
@@ -80,6 +81,7 @@ const RECOGNIZED_COMMANDS = new Set([
     "batch",
     "attach",
     "model",
+    "queue",
     "stop",
     "sandbox",
     "status",
@@ -100,6 +102,8 @@ const TELEGRAM_STALE_UPDATE_GRACE_SECONDS = 10;
 const TELEGRAM_PROCESS_STARTED_AT_SECONDS = Math.floor(Date.now() / 1000);
 const workLoopTails = new Map();
 const workLoopGenerations = new Map();
+const queuedWorkLoops = new Map();
+let nextQueuedWorkSequence = 1;
 const REPORT_CONTINUE_PROMPT = [
     "Continue the same task now.",
     "Do more concrete work before replying again.",
@@ -453,17 +457,47 @@ ${bridge.formatStatus(mapping)}`);
         const mapping = await bridge.setModel(botId, chatId, model);
         await reply(ctx, `Set ${mapping.session.mode} model to ${model}.\n\n${bridge.formatStatus(mapping)}`);
     });
+    bot.command("queue", async (ctx) => {
+        const botId = getBotId();
+        const chatId = String(ctx.chat.id);
+        const mapping = await bridge.status(botId, chatId);
+        const activeKey = workLoopKey(botId, chatId, mapping?.session.sessionId);
+        const { args, rest } = parseCommand(ctx.message?.text, 2);
+        const action = args[0]?.toLowerCase();
+        const selector = args[1];
+        if (rest?.trim() || (action && action !== "list" && action !== "remove" && action !== "rm" && action !== "del")) {
+            await reply(ctx, "Usage: `/queue`, `/queue remove <id>`, or `/queue del`", { parse_mode: "Markdown" });
+            return;
+        }
+        if (!action || action === "list") {
+            await reply(ctx, formatQueuedWorkLoops(activeKey, mapping?.session.publicId));
+            return;
+        }
+        if ((action === "remove" || action === "rm") && !selector) {
+            await reply(ctx, "Usage: `/queue remove <id>`", { parse_mode: "Markdown" });
+            return;
+        }
+        const removed = removeQueuedWorkLoop(activeKey, selector);
+        if (!removed) {
+            const target = selector ? normalizeQueueId(selector) : "the latest queued instruction";
+            await reply(ctx, `Queued instruction was not found: ${target}`);
+            return;
+        }
+        await bridge.logSystem(botId, chatId, `Removed queued instruction ${removed.id} for ${activeKey}.`);
+        await reply(ctx, `Removed queued instruction ${removed.id} from ${removed.publicSessionId ?? "this session"}.\n`
+            + `Remaining queued instructions: ${listQueuedWorkLoops(activeKey).length}`);
+    });
     bot.command("stop", async (ctx) => {
         const botId = getBotId();
         const chatId = String(ctx.chat.id);
         const mapping = await bridge.status(botId, chatId);
         const sessionId = mapping?.session.sessionId;
         autoContinue.requestStop(botId, chatId, sessionId);
-        cancelQueuedWorkLoops(botId, chatId, sessionId);
+        const queuedWorkCount = cancelQueuedWorkLoops(botId, chatId, sessionId);
         const pendingBatch = messageBatcher.cancelPending(botId, chatId);
         const manualBatch = messageBatcher.cancelManual(botId, chatId);
         if (!autoContinue.beginStop(botId, chatId, sessionId)) {
-            const batchCount = pendingBatch.count + manualBatch.count;
+            const batchCount = queuedWorkCount + pendingBatch.count + manualBatch.count;
             if (batchCount > 0) {
                 await bridge.logSystem(botId, chatId, `Duplicate stop discarded ${batchCount} queued message(s).`);
             }
@@ -472,7 +506,7 @@ ${bridge.formatStatus(mapping)}`);
         try {
             const result = await bridge.stopActiveRun(botId, chatId);
             await bridge.logSystem(botId, chatId, "Stop requested for auto-continue.");
-            const batchCount = pendingBatch.count + manualBatch.count;
+            const batchCount = queuedWorkCount + pendingBatch.count + manualBatch.count;
             await reply(ctx, result.stopped
                 ? `Stop requested. Active work for ${result.sessionPublicId ?? "this session"} was interrupted, further automatic continuation will stop, and ${batchCount} queued message(s) were discarded.`
                 : `Stop requested. No active provider process was running, but further automatic continuation will stop, and ${batchCount} queued message(s) were discarded.`);
@@ -1228,12 +1262,36 @@ async function routeTelegramWorkLoop(bridge, botId, chatId, message, label, botM
         .catch(() => undefined)
         .then(() => gate);
     workLoopTails.set(activeKey, currentTail);
+    let queuedEntry;
     if (previousTail) {
-        await bridge.logSystem(botId, chatId, `Queued overlapping Telegram work loop for ${activeKey}.`);
-        await helpers.reportProgress([`Queued instruction for ${currentSession?.session.publicId ?? "this session"}. It will run after the active work finishes.`]);
-        await previousTail.catch(() => undefined);
-        if ((workLoopGenerations.get(activeKey) ?? 0) !== generation || autoContinue.isStopRequested(botId, chatId, sessionId)) {
-            await bridge.logSystem(botId, chatId, `Discarded queued Telegram work loop for ${activeKey}.`);
+        queuedEntry = registerQueuedWorkLoop({
+            activeKey,
+            botId,
+            chatId,
+            sessionId,
+            publicSessionId: currentSession?.session.publicId,
+            message,
+            release,
+        });
+        try {
+            await bridge.logSystem(botId, chatId, `Queued overlapping Telegram work loop ${queuedEntry.id} for ${activeKey}.`);
+            await helpers.reportProgress([
+                `Queued instruction ${queuedEntry.id} for ${currentSession?.session.publicId ?? "this session"}. It will run after the active work finishes.`,
+                `Remove it with \`/queue remove ${queuedEntry.id}\`, or remove the latest queued instruction with \`/queue del\`.`,
+            ]);
+            await previousTail.catch(() => undefined);
+        }
+        catch (error) {
+            queuedWorkLoops.delete(queuedEntry.id);
+            release();
+            if (workLoopTails.get(activeKey) === currentTail) {
+                workLoopTails.delete(activeKey);
+            }
+            throw error;
+        }
+        queuedWorkLoops.delete(queuedEntry.id);
+        if (queuedEntry.canceled || (workLoopGenerations.get(activeKey) ?? 0) !== generation || autoContinue.isStopRequested(botId, chatId, sessionId)) {
+            await bridge.logSystem(botId, chatId, `Discarded queued Telegram work loop ${queuedEntry.id} for ${activeKey}.`);
             release();
             if (workLoopTails.get(activeKey) === currentTail) {
                 workLoopTails.delete(activeKey);
@@ -1460,9 +1518,82 @@ function cancelQueuedWorkLoops(botId, chatId, sessionId) {
     if (sessionId) {
         keys.push(workLoopKey(botId, chatId));
     }
+    const keySet = new Set(keys);
+    let removed = 0;
+    for (const entry of queuedWorkLoops.values()) {
+        if (!keySet.has(entry.activeKey)) {
+            continue;
+        }
+        entry.canceled = true;
+        entry.release();
+        queuedWorkLoops.delete(entry.id);
+        removed += 1;
+    }
     for (const key of keys) {
         workLoopGenerations.set(key, (workLoopGenerations.get(key) ?? 0) + 1);
     }
+    return removed;
+}
+function registerQueuedWorkLoop(input) {
+    const sequence = nextQueuedWorkSequence;
+    nextQueuedWorkSequence += 1;
+    const entry = {
+        id: `Q${String(sequence).padStart(3, "0")}`,
+        sequence,
+        activeKey: input.activeKey,
+        botId: input.botId,
+        chatId: input.chatId,
+        sessionId: input.sessionId,
+        publicSessionId: input.publicSessionId,
+        messagePreview: summarizeQueuedInstruction(input.message),
+        createdAt: new Date().toISOString(),
+        canceled: false,
+        release: input.release,
+    };
+    queuedWorkLoops.set(entry.id, entry);
+    return entry;
+}
+function listQueuedWorkLoops(activeKey) {
+    return [...queuedWorkLoops.values()]
+        .filter((entry) => entry.activeKey === activeKey && !entry.canceled)
+        .sort((left, right) => left.sequence - right.sequence);
+}
+function removeQueuedWorkLoop(activeKey, selector) {
+    const entries = listQueuedWorkLoops(activeKey);
+    const target = selector
+        ? queuedWorkLoops.get(normalizeQueueId(selector))
+        : entries.at(-1);
+    if (!target || target.activeKey !== activeKey || target.canceled) {
+        return undefined;
+    }
+    target.canceled = true;
+    target.release();
+    queuedWorkLoops.delete(target.id);
+    return target;
+}
+function normalizeQueueId(value) {
+    const normalized = value.trim().toUpperCase();
+    if (/^\d+$/.test(normalized)) {
+        return `Q${normalized.padStart(3, "0")}`;
+    }
+    return normalized;
+}
+function summarizeQueuedInstruction(message) {
+    const normalized = message.replace(/\s+/g, " ").trim();
+    return normalized.length > 100 ? `${normalized.slice(0, 97)}...` : normalized;
+}
+function formatQueuedWorkLoops(activeKey, publicSessionId) {
+    const entries = listQueuedWorkLoops(activeKey);
+    if (entries.length === 0) {
+        return `No queued instructions for ${publicSessionId ?? "this chat"}.`;
+    }
+    return [
+        `Queued instructions for ${publicSessionId ?? "this chat"} (${entries.length})`,
+        ...entries.map((entry) => `${entry.id}: ${entry.messagePreview || "(empty instruction)"}`),
+        "",
+        `Remove one: /queue remove ${entries[0].id}`,
+        "Remove latest: /queue del",
+    ].join("\n");
 }
 class SilentTelegramAbort extends Error {
     constructor(message) {

package/dist/index.js

@@ -20,6 +20,7 @@ import { ProviderRecoveryService } from "./services/provider-recovery-service.js
 import { computePolicyPollIntervalMs, computeRecentMessageRanks } from "./services/polling-policy.js";
 import { terminateAllSpawnedExecutions } from "./adapters/windows-shell.js";
 import { setTelegramCommandMenu } from "./telegram-command-menu.js";
+import { buildBotInfoFromIdentity, buildFallbackBotInfo } from "./telegram-bot-identity.js";
 const execFileAsync = promisify(execFile);
 const TELEGRAM_GET_UPDATES_HTTP_TIMEOUT_SECONDS = 30;
 const TELEGRAM_GET_UPDATES_CURL_TIMEOUT_SECONDS = 60;
@@ -68,7 +69,7 @@ async function main() {
             console.error("Local UI failed to start:", error);
         });
     }
-    const botInfos = await Promise.all(config.telegramBotTokens.map((token, index) => resolveBotInfo(token, index)));
+    const botInfos = await Promise.all(config.telegramBotTokens.map((token, index) => resolveBotInfo(token, index, config.telegramBotUsernames[index])));
     const bots = config.telegramBotTokens.map((token, index) => createBot(token, bridge, botManagement, botInfos[index]));
     if (config.telegramCommandMenuEnabled) {
         for (const bot of bots) {
@@ -484,7 +485,7 @@ class AsyncSemaphore {
         }
     }
 }
-async function resolveBotInfo(token, index) {
+async function resolveBotInfo(token, index, configuredUsername) {
     try {
         const { stdout } = await execFileAsync("curl", [
             "-sS",
@@ -502,32 +503,7 @@ async function resolveBotInfo(token, index) {
     catch (error) {
         console.warn(`Telegram getMe failed for bot ${tokenIdLabel(token)}: ${summarizeTelegramIdentityError(error)}`);
     }
-    return buildFallbackBotInfo(token, index);
-}
-function buildBotInfoFromIdentity(id, username, firstName) {
-    return {
-        id,
-        is_bot: true,
-        first_name: firstName || username,
-        username,
-        can_join_groups: false,
-        can_read_all_group_messages: false,
-        supports_inline_queries: false,
-    };
-}
-function buildFallbackBotInfo(token, index) {
-    const id = Number.parseInt(token.split(":", 1)[0] ?? "", 10);
-    const fallbackUsername = knownBotUsername(id);
-    const username = fallbackUsername || `bot_${Number.isFinite(id) ? id : index + 1}`;
-    return {
-        id: Number.isFinite(id) ? id : index + 1,
-        is_bot: true,
-        first_name: username,
-        username,
-        can_join_groups: false,
-        can_read_all_group_messages: false,
-        supports_inline_queries: false,
-    };
+    return buildFallbackBotInfo(token, index, configuredUsername);
 }
 function tokenIdLabel(token) {
     return token.split(":", 1)[0] || "unknown";
@@ -543,15 +519,6 @@ function summarizeTelegramIdentityError(error) {
         .filter(Boolean)
         .join(" ");
 }
-function knownBotUsername(id) {
-    if (id === 8369496408) {
-        return "codex_remoteagent_bot";
-    }
-    if (id === 8429712341) {
-        return "sqream_bot";
-    }
-    return undefined;
-}
 function commandExists(command) {
     const trimmed = command.trim();
     if (!trimmed) {

package/dist/telegram-bot-identity.js

@@ -0,0 +1,36 @@
+export function buildBotInfoFromIdentity(id, username, firstName) {
+    return {
+        id,
+        is_bot: true,
+        first_name: firstName || username,
+        username,
+        can_join_groups: false,
+        can_read_all_group_messages: false,
+        supports_inline_queries: false,
+    };
+}
+export function buildFallbackBotInfo(token, index, configuredUsername) {
+    const id = Number.parseInt(token.split(":", 1)[0] ?? "", 10);
+    const persistedUsername = configuredUsername?.trim().replace(/^@/, "");
+    const username = persistedUsername
+        || knownBotUsername(id)
+        || `bot_${Number.isFinite(id) ? id : index + 1}`;
+    return {
+        id: Number.isFinite(id) ? id : index + 1,
+        is_bot: true,
+        first_name: username,
+        username,
+        can_join_groups: false,
+        can_read_all_group_messages: false,
+        supports_inline_queries: false,
+    };
+}
+function knownBotUsername(id) {
+    if (id === 8369496408) {
+        return "codex_remoteagent_bot";
+    }
+    if (id === 8429712341) {
+        return "sqream_bot";
+    }
+    return undefined;
+}

package/dist/telegram-command-menu.js

@@ -15,6 +15,7 @@ export const TELEGRAM_COMMAND_MENU = [
     { command: "docs", description: "Pin or find session documents" },
     { command: "macro", description: "Save or run reusable instructions" },
     { command: "model", description: "Show or change provider model" },
+    { command: "queue", description: "List or remove queued instructions" },
     { command: "stop", description: "Stop active work and clear queued messages" },
     { command: "sandbox", description: "Set Codex sandbox mode" },
     { command: "batch", description: "Collect and send a multi-message batch" },

package/docs/OPERATIONS.md

@@ -44,6 +44,10 @@ Current production bot ownership is intentionally split:
 Assign each Telegram bot token to one runtime at a time.
 Bot polling conflicts are treated as incidents, not harmless warnings.
 
+`TELEGRAM_BOT_TOKENS` and `TELEGRAM_BOT_USERNAMES` are parallel persisted lists.
+At startup, Telegram `getMe` is the preferred identity source, but a temporary DNS or Telegram failure must fall back to the persisted username at the same list position.
+Using a generated `bot_<numeric-id>` identity when a persisted username exists breaks the existing `<username>:<chat-id>` session binding.
+
 When a runtime has several configured Telegram bots, polling pressure can become operationally visible.
 RemoteAgent reduces that pressure with rank-based polling intervals instead of deep sleep or a special main bot.
 See [BOT_POLLING_POLICY.md](./BOT_POLLING_POLICY.md).

package/docs/RELEASING.md

@@ -174,3 +174,26 @@ Runtime targets:
 server 30: 0.15.5 active
 server 26: 0.15.5 running
 ```
+
+## Release 0.17.0
+
+Date: 2026-07-29
+
+Changes:
+
+- Queued instructions receive runtime-unique `Q001`-style ids.
+- `/queue` lists instructions waiting behind the current session work.
+- `/queue remove <id>` removes one selected waiting instruction.
+- `/queue del` removes the most recently queued instruction.
+- `/stop` reports and clears queued work-loop instructions as well as pending message batches.
+- Telegram startup preserves the configured bot username when `getMe` temporarily fails, preventing existing chat/session bindings from being bypassed by a generated numeric bot identity.
+
+Validated:
+
+```bash
+npm run check
+npm run build
+npm run selftest:telegram
+npm run release:publish
+npm run release:deploy -- 0.17.0 all
+```

package/package.json

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

package/scripts/selftest-telegram-update.mjs

@@ -69,6 +69,7 @@ const [
   { FileStore },
   { AgentMemoryService },
   { WorkspaceCleanupService },
+  { buildFallbackBotInfo },
 ] = await Promise.all([
   import(path.join(root, "dist", "bot.js")),
   import(path.join(root, "dist", "services", "bridge-service.js")),
@@ -76,12 +77,26 @@ const [
   import(path.join(root, "dist", "store", "file-store.js")),
   import(path.join(root, "dist", "services", "agent-memory-service.js")),
   import(path.join(root, "dist", "services", "workspace-cleanup-service.js")),
+  import(path.join(root, "dist", "telegram-bot-identity.js")),
 ]);
 
+const persistedBotIdentity = buildFallbackBotInfo(
+  "8966593034:test-token",
+  0,
+  "@appbackadmin_bot",
+);
+if (persistedBotIdentity.username !== "appbackadmin_bot") {
+  throw new Error(`Configured bot username was not preserved during getMe fallback: ${persistedBotIdentity.username}`);
+}
+
 const providerCalls = [];
 let providerMode = "success";
 let untaggedIntentCalls = 0;
 let missingEvidenceCalls = 0;
+let queueHoldStartedResolve;
+let queueHoldReleaseResolve;
+let queueHoldStartedPromise = Promise.resolve();
+let queueHoldReleasePromise = Promise.resolve();
 const provider = {
   async send(request) {
     providerCalls.push(request);
@@ -112,6 +127,17 @@ const provider = {
           : "REPORT:result\n수정 완료했습니다.\n\n근거:\n- 변경 파일: `src/example.ts`\n- 검증: `npm run check` 통과",
       };
     }
+    if (providerMode === "queue-hold") {
+      queueHoldStartedResolve?.();
+      await queueHoldReleasePromise;
+      return {
+        provider: "codex",
+        sessionId: request.sessionId || "mock-thread",
+        publicSessionId: request.publicSessionId,
+        cwd: request.cwd,
+        output: "REPORT:result\nactive queue test completed",
+      };
+    }
     return {
       provider: "codex",
       sessionId: request.sessionId || "mock-thread",
@@ -169,6 +195,34 @@ async function send(text) {
   await injectedBot.handleUpdates([update(text)]);
 }
 
+async function readTelegramCalls() {
+  return (await fs.readFile(telegramCalls, "utf8"))
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [method, chatId, textB64 = ""] = line.split("\t");
+      return {
+        method,
+        chat_id: chatId,
+        text: Buffer.from(textB64, "base64").toString("utf8"),
+      };
+    });
+}
+
+async function waitForTelegramCall(predicate, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const calls = await readTelegramCalls();
+    const match = [...calls].reverse().find(predicate);
+    if (match) {
+      return match;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  throw new Error("Timed out waiting for Telegram self-test call.");
+}
+
 await send("/start codex");
 await send("/option retry 6");
 await send("/option timeout 600");
@@ -407,6 +461,60 @@ if (evidenceCalls.some((call) => call.method === "sendMessage" && /^수정 완
   throw new Error(`Evidence-free completion leaked as final Telegram message. Calls: ${JSON.stringify(evidenceCalls, null, 2)}`);
 }
 
+const queueProviderCallsBefore = providerCalls.length;
+providerMode = "queue-hold";
+queueHoldStartedPromise = new Promise((resolve) => {
+  queueHoldStartedResolve = resolve;
+});
+queueHoldReleasePromise = new Promise((resolve) => {
+  queueHoldReleaseResolve = resolve;
+});
+
+await send("/batch start");
+await send("active queue regression test");
+const activeQueueSend = send("/batch send");
+await queueHoldStartedPromise;
+
+await send("/batch start");
+await send("first queued instruction");
+const firstQueuedSend = send("/batch send");
+const firstQueueNotice = await waitForTelegramCall((call) => /Queued instruction Q\d+/.test(call.text));
+const firstQueueId = firstQueueNotice.text.match(/Queued instruction (Q\d+)/)?.[1];
+if (!firstQueueId) {
+  throw new Error(`First queued instruction did not receive an id: ${firstQueueNotice.text}`);
+}
+
+await send("/batch start");
+await send("second queued instruction");
+const secondQueuedSend = send("/batch send");
+const secondQueueNotice = await waitForTelegramCall((call) => {
+  const queueId = call.text.match(/Queued instruction (Q\d+)/)?.[1];
+  return Boolean(queueId && queueId !== firstQueueId);
+});
+const secondQueueId = secondQueueNotice.text.match(/Queued instruction (Q\d+)/)?.[1];
+if (!secondQueueId) {
+  throw new Error(`Second queued instruction did not receive an id: ${secondQueueNotice.text}`);
+}
+
+await send("/queue");
+const queueListCall = await waitForTelegramCall((call) =>
+  call.text.includes(firstQueueId) && call.text.includes(secondQueueId)
+);
+if (!/Queued instructions for S001 \(2\)/.test(queueListCall.text)) {
+  throw new Error(`Queue list did not report both entries: ${queueListCall.text}`);
+}
+
+await send(`/queue remove ${firstQueueId}`);
+await waitForTelegramCall((call) => call.text.includes(`Removed queued instruction ${firstQueueId}`));
+await send("/queue del");
+await waitForTelegramCall((call) => call.text.includes(`Removed queued instruction ${secondQueueId}`));
+
+queueHoldReleaseResolve?.();
+await Promise.all([activeQueueSend, firstQueuedSend, secondQueuedSend]);
+if (providerCalls.length !== queueProviderCallsBefore + 1) {
+  throw new Error(`Removed queued instructions reached the provider: ${providerCalls.length - queueProviderCallsBefore} calls`);
+}
+
 console.log(JSON.stringify({
   ok: true,
   dataDir,
@@ -419,6 +527,8 @@ console.log(JSON.stringify({
   providerCalls: providerCalls.length,
   untaggedIntentCalls,
   missingEvidenceCalls,
+  queueRemoveById: firstQueueId,
+  queueRemoveLatest: secondQueueId,
   timeoutFinalMessage: true,
   telegramSendMessages: evidenceCalls.filter((call) => call.method === "sendMessage").length,
 }, null, 2));