@songsid/agend 2.3.5-alpha.3 → 2.3.5-alpha.5

package/dist/channel/adapters/telegram.js

@@ -4,8 +4,9 @@ import { randomBytes } from "node:crypto";
 import { inboxTempName } from "../inbox-temp-name.js";
 import { Agent as HttpAgent } from "node:http";
 import { Agent as HttpsAgent } from "node:https";
-import { createReadStream, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { createReadStream, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { join, extname, basename } from "node:path";
+import { atomicWriteFileSync } from "../../atomic-write.js";
 import { Bot, GrammyError, HttpError, InputFile } from "grammy";
 import { InlineKeyboard } from "grammy";
 import { stripPlaceRefs } from "../../topic-link.js";
@@ -52,9 +53,34 @@ export const TELEGRAM_ALLOWED_UPDATES = [
     "callback_query",
     "message_reaction",
 ];
+/**
+ * Pending Telegram updates older than this are filed as a Needs-you item
+ * ("missed while AgEnD was offline") and never auto-injected into an agent.
+ * Telegram itself keeps the getUpdates queue for about 24 hours.
+ */
+export const TELEGRAM_PENDING_LIVE_MAX_MS = 2 * 60 * 60 * 1000;
+/**
+ * Telegram may pick a new random `update_id` after about a week with no
+ * updates (Bot API). A floor older than this is ignored so inbound is not
+ * dropped forever.
+ */
+export const TELEGRAM_UPDATE_ID_FLOOR_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Telegram's default getUpdates page size; a shorter page means the queue drained. */
+export const TELEGRAM_GETUPDATES_LIMIT = 100;
+/** Crash-safe last processed `update_id` for this adapter (inside inboxDir; prune skips it). */
+export function telegramLastUpdateIdPath(inboxDir, adapterId) {
+    const safe = adapterId.replace(/[^A-Za-z0-9._-]+/g, "_") || "adapter";
+    return join(inboxDir, `telegram-${safe}-last-update-id`);
+}
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function telegramUpdateAgeMs(update, now) {
+    const date = update.message?.date ?? update.callback_query?.message?.date;
+    if (typeof date !== "number" || !Number.isFinite(date))
+        return null;
+    return now - date * 1000;
+}
 /** Remove Bot API credentials from nested node-fetch errors before logging. */
 export function redactTelegramSecrets(value, botToken = "") {
     let redacted = value.replace(/\/bot[^/\s]+(?=\/)/gi, "/bot[REDACTED]");
@@ -247,6 +273,14 @@ export class TelegramAdapter extends EventEmitter {
     /** Topics the probe itself is addressing right now — their failures are results, not hints. */
     probingThreads = new Set();
     topicGoneHintAt = new Map();
+    /** Last processed `update_id`; 0 means no floor. Telegram ids are usually monotonic. */
+    lastUpdateId = 0;
+    floorBotId;
+    floorRecordedAt = 0;
+    /** False until a getUpdates page shorter than TELEGRAM_GETUPDATES_LIMIT (the queue drained). */
+    backlogDrained = false;
+    backlogUpdateIds = new Set();
+    persistFloorTimer;
     constructor(opts) {
         super();
         this.id = opts.id;
@@ -297,6 +331,7 @@ export class TelegramAdapter extends EventEmitter {
                 }
             },
         });
+        this.loadFloor();
         this._registerHandlers();
     }
     /**
@@ -314,11 +349,21 @@ export class TelegramAdapter extends EventEmitter {
         if (!this.bot.api.config?.use)
             return;
         this.bot.api.config.use(async (prev, method, payload, signal) => {
+            // grammY.stop sends a final offset ACK, and an already-fetched batch can finish later.
+            // Once fenced, neither path may confirm or admit updates for the stopping fleet.
+            if (method === "getUpdates" && this.stopped)
+                return { ok: true, result: [] };
             const requestGeneration = this.httpAgentGeneration;
             try {
-                return await prev(method, payload, signal);
+                const result = await prev(method, payload, signal);
+                if (method === "getUpdates" && this.stopped)
+                    return { ok: true, result: [] };
+                this.noteGetUpdatesBacklog(method, result);
+                return result;
             }
             catch (err) {
+                if (method === "getUpdates" && this.stopped)
+                    return { ok: true, result: [] };
                 if (!(err instanceof HttpError))
                     throw err;
                 const firstDetail = telegramNetworkErrorDetails(err, this.botToken);
@@ -326,6 +371,8 @@ export class TelegramAdapter extends EventEmitter {
                 console.warn(`[telegram] ${method} transport failed; HTTP pool ${reset ? "reset" : "reset suppressed by cooldown"}: ${firstDetail}`);
                 if (isDefinitelyPreDeliveryNetworkError(err) && !signal?.aborted) {
                     await new Promise(resolve => setTimeout(resolve, TELEGRAM_NETWORK_RETRY_MS));
+                    if (method === "getUpdates" && this.stopped)
+                        return { ok: true, result: [] };
                     const retryGeneration = this.httpAgentGeneration;
                     try {
                         return await prev(method, payload, signal);
@@ -370,14 +417,42 @@ export class TelegramAdapter extends EventEmitter {
         return true;
     }
     _registerHandlers() {
-        // Own messages must never become inbound work even when transport replays
-        // them. Fleet-wide echo provenance is checked in the common ingress path.
-        // Put this ahead of rich-message middleware as well as ordinary messages.
+        // Dedup, own-message skip, and the downtime age cap run before any handler.
+        // Record the update_id before acting so a crash mid-batch cannot inject twice.
         this.bot.use(async (ctx, next) => {
-            const message = ctx.update?.message;
+            if (this.stopped)
+                return; // Before the durable floor as well as handler dispatch.
+            const update = ctx.update;
+            const updateId = update.update_id;
+            this.discardFloorIfStale(Date.now());
+            if (typeof updateId === "number") {
+                if (this.lastUpdateId > 0 && updateId <= this.lastUpdateId)
+                    return;
+                this.lastUpdateId = updateId;
+                this.floorRecordedAt = Date.now();
+                if (this.bot.botInfo?.id != null)
+                    this.floorBotId = this.bot.botInfo.id;
+                this.schedulePersistFloor();
+            }
+            const message = update.message;
             const sender = message?.from?.id;
             if (sender != null && sender === this.bot.botInfo?.id)
                 return;
+            // Age cap / stale callbacks apply to the downtime queue (pages until a short getUpdates).
+            const isBacklog = typeof updateId === "number" && this.backlogUpdateIds.has(updateId);
+            if (isBacklog) {
+                if (update.callback_query) {
+                    // The card's date is not the click's; queued callbacks are stale by being in the backlog.
+                    ctx.answerCallbackQuery().catch(() => { });
+                    return;
+                }
+                const ageMs = telegramUpdateAgeMs(update, Date.now());
+                if (ageMs != null && ageMs > TELEGRAM_PENDING_LIVE_MAX_MS
+                    && message && !this._isServiceMessage(message)) {
+                    this.emitMissedOffline(updateId ?? 0, message);
+                    return;
+                }
+            }
             return next();
         });
         // Middleware: catch Rich Message updates that grammy doesn't route to bot.on("message")
@@ -640,6 +715,8 @@ export class TelegramAdapter extends EventEmitter {
     authRejected = false;
     /** #1537 review: stop() was called (and no start() since). */
     stopped = false;
+    pollingGeneration = 0;
+    receiveStop = null;
     connectionEvidence() {
         return { ready: this.pollingReady, authRejected: this.authRejected, stopped: this.stopped };
     }
@@ -647,6 +724,10 @@ export class TelegramAdapter extends EventEmitter {
         // #1537 review: a new start borrows nothing from the last one — not ready until its own onStart, and not stopped.
         this.pollingReady = false;
         this.stopped = false;
+        this.receiveStop = null;
+        const generation = ++this.pollingGeneration, current = () => !this.stopped && this.pollingGeneration === generation;
+        this.backlogDrained = false;
+        this.backlogUpdateIds.clear();
         this.queue.start();
         this._pruneInbox();
         this.cleanupTimer = setInterval(() => this._pruneInbox(), 60 * 60 * 1000);
@@ -663,15 +744,18 @@ export class TelegramAdapter extends EventEmitter {
         const MAX_RECONNECT_RETRIES = 10; // auto-reconnect on non-409 errors
         void (async () => {
             let reconnects = 0;
-            while (true) {
-                for (let attempt = 1; attempt <= MAX_409_RETRIES; attempt++) {
+            while (current()) {
+                for (let attempt = 1; current() && attempt <= MAX_409_RETRIES; attempt++) {
                     try {
                         await this.bot.start({
                             // Keep the server-side long poll comfortably below both 30s
                             // client deadlines. Equal 30s deadlines race the normal empty
                             // getUpdates response and would churn the HTTP pool while idle.
                             timeout: TELEGRAM_LONG_POLL_TIMEOUT_SECONDS,
-                            drop_pending_updates: attempt === 1 && reconnects === 0,
+                            // Telegram queues ~24h of updates. Dropping them on a cold start
+                            // discards messages sent while AgEnD was stopped. Keep them; the
+                            // adapter delivers recent ones and files older ones as Needs-you.
+                            drop_pending_updates: false,
                             // Telegram's DEFAULT allowed_updates excludes message_reaction, so
                             // reactions cannot arrive unless the set is listed explicitly. Passing
                             // this list also FREEZES the set: any update type omitted here stops
@@ -681,15 +765,20 @@ export class TelegramAdapter extends EventEmitter {
                             // added here too, or it will never fire.
                             allowed_updates: TELEGRAM_ALLOWED_UPDATES,
                             onStart: (info) => {
+                                if (!current())
+                                    return;
                                 reconnects = 0; // reset on successful start
                                 this.pollingReady = true;
                                 this.authRejected = false;
+                                this.discardFloorIfStale(Date.now(), info.id);
                                 this.emit("started", info.username, String(info.id));
                             },
                         });
                         return; // bot.stop() was called — clean exit
                     }
                     catch (err) {
+                        if (!current())
+                            return;
                         // #1519 P6: what the connection's status reports — not polling now, and whether Telegram refused the token.
                         this.pollingReady = false;
                         if (err instanceof GrammyError && err.error_code === 401)
@@ -720,10 +809,19 @@ export class TelegramAdapter extends EventEmitter {
             }
         })();
     }
-    async stop() {
-        // #1537 review: the connection is not polling from the moment it is told to stop (before any await).
+    stopReceiving() {
+        if (this.receiveStop)
+            return this.receiveStop;
+        // Set before bot.stop (and its final getUpdates ACK); do not close the outbound queue yet.
         this.pollingReady = false;
         this.stopped = true;
+        this.pollingGeneration++;
+        this.flushPersistFloor();
+        this.receiveStop = this.bot.stop();
+        return this.receiveStop;
+    }
+    async stop() {
+        const receivingStopped = this.stopReceiving();
         // Invalidate queued status work before any await. Re-created adapters must
         // not inherit proof from this object's pending requests.
         this.reactionGeneration = (this.reactionGeneration ?? 0) + 1;
@@ -733,9 +831,126 @@ export class TelegramAdapter extends EventEmitter {
         if (this.cleanupTimer)
             clearInterval(this.cleanupTimer);
         this.queue.stop();
-        await this.bot.stop();
-        this.httpAgent.destroy();
-        this.httpsAgent.destroy();
+        try {
+            await receivingStopped;
+        }
+        finally {
+            this.httpAgent.destroy();
+            this.httpsAgent.destroy();
+        }
+    }
+    lastUpdateIdFile() {
+        return telegramLastUpdateIdPath(this.inboxDir, this.id);
+    }
+    loadFloor() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.lastUpdateIdFile(), "utf8"));
+            if (!parsed || typeof parsed !== "object")
+                return;
+            const rec = parsed;
+            const id = rec.update_id;
+            if (typeof id !== "number" || !Number.isSafeInteger(id) || id < 0)
+                return;
+            this.lastUpdateId = id;
+            this.floorBotId = typeof rec.bot_id === "number" && Number.isSafeInteger(rec.bot_id) ? rec.bot_id : undefined;
+            this.floorRecordedAt = typeof rec.recorded_at === "number" && Number.isFinite(rec.recorded_at) ? rec.recorded_at : 0;
+            this.discardFloorIfStale(Date.now());
+        }
+        catch { /* no floor yet */ }
+    }
+    clearFloor() {
+        this.lastUpdateId = 0;
+        this.floorBotId = undefined;
+        this.floorRecordedAt = 0;
+    }
+    /** Drop a floor that belongs to another bot, or that is older than a week of silence. */
+    discardFloorIfStale(now, botId) {
+        if (this.lastUpdateId <= 0)
+            return;
+        if (this.floorRecordedAt > 0 && now - this.floorRecordedAt > TELEGRAM_UPDATE_ID_FLOOR_MAX_AGE_MS) {
+            this.clearFloor();
+            return;
+        }
+        const id = botId ?? (this.bot.isInited() ? this.bot.botInfo.id : undefined);
+        if (this.floorBotId != null && id != null && this.floorBotId !== id)
+            this.clearFloor();
+    }
+    schedulePersistFloor() {
+        if (this.persistFloorTimer)
+            return;
+        this.persistFloorTimer = setImmediate(() => {
+            this.persistFloorTimer = undefined;
+            this.writeFloor();
+        });
+    }
+    flushPersistFloor() {
+        if (this.persistFloorTimer) {
+            clearImmediate(this.persistFloorTimer);
+            this.persistFloorTimer = undefined;
+        }
+        this.writeFloor();
+    }
+    writeFloor() {
+        try {
+            const rec = { update_id: this.lastUpdateId };
+            if (this.floorBotId != null)
+                rec.bot_id = this.floorBotId;
+            if (this.floorRecordedAt > 0)
+                rec.recorded_at = this.floorRecordedAt;
+            atomicWriteFileSync(this.lastUpdateIdFile(), `${JSON.stringify(rec)}\n`, { mode: 0o600 });
+        }
+        catch (err) {
+            console.warn(`[telegram:${this.id}] could not persist last update_id (${errorMessage(err)})`);
+        }
+    }
+    noteGetUpdatesBacklog(method, result) {
+        if (method !== "getUpdates" || this.backlogDrained)
+            return;
+        if (result && typeof result === "object" && "ok" in result && result.ok !== true)
+            return;
+        // Transformers see the raw Bot API envelope `{ ok, result }`; callApi unwraps after.
+        const updates = result && typeof result === "object" && "result" in result
+            ? result.result
+            : result;
+        if (!Array.isArray(updates))
+            return;
+        const ids = [];
+        for (const item of updates) {
+            if (item && typeof item === "object" && typeof item.update_id === "number") {
+                ids.push(item.update_id);
+            }
+        }
+        // A new random sequence after a week of silence can land entirely below the stored floor.
+        if (ids.length > 0 && this.lastUpdateId > 0 && Math.max(...ids) < this.lastUpdateId) {
+            this.clearFloor();
+            this.schedulePersistFloor();
+        }
+        for (const id of ids)
+            this.backlogUpdateIds.add(id);
+        if (updates.length < TELEGRAM_GETUPDATES_LIMIT)
+            this.backlogDrained = true;
+    }
+    emitMissedOffline(updateId, msg) {
+        const userId = msg.from?.id;
+        if (userId == null || msg.chat?.id == null)
+            return;
+        const text = String(msg.text ?? msg.caption ?? "").replace(/\s+/g, " ").trim();
+        const preview = text.length > 160 ? `${text.slice(0, 159)}…` : text;
+        const threadId = msg.message_thread_id != null ? String(msg.message_thread_id) : undefined;
+        const payload = {
+            source: "telegram",
+            adapterId: this.id,
+            updateId,
+            chatId: String(msg.chat.id),
+            ...(threadId !== undefined ? { threadId } : {}),
+            messageId: String(msg.message_id ?? ""),
+            userId: String(userId),
+            username: msg.from?.username ?? msg.from?.first_name ?? String(userId),
+            preview,
+            timestamp: new Date((msg.date ?? 0) * 1000),
+            ...(msg.chat.title ? { chatTitle: String(msg.chat.title) } : {}),
+        };
+        this.emit("missed_offline", payload);
     }
     /** Delete inbox files older than 1 hour */
     _pruneInbox() {
@@ -743,6 +958,8 @@ export class TelegramAdapter extends EventEmitter {
         const now = Date.now();
         try {
             for (const name of readdirSync(this.inboxDir)) {
+                if (/^telegram-.+-last-update-id$/.test(name))
+                    continue;
                 const filePath = join(this.inboxDir, name);
                 try {
                     const mtime = statSync(filePath).mtimeMs;
@@ -1498,12 +1715,13 @@ export class TelegramAdapter extends EventEmitter {
         return res.message_thread_id;
     }
     async deleteTopic(topicId) {
-        // Telegram's General topic is the forum root, not a deletable topic.
+        // Telegram's General topic is the forum root, not a deletable topic. Refused, never "done": a caller reports what
+        // happened (delete_instance's topic_deleted), and silence would read as a deletion.
         if (String(topicId) === "1")
-            return;
+            throw new Error("the General topic is never deleted");
         const chatId = this.getChatId();
         if (!chatId)
-            return;
+            throw new Error("the Telegram bot is not connected to its group");
         await this.bot.api.raw.deleteForumTopic({ chat_id: Number(chatId), message_thread_id: Number(topicId) });
     }
     async probeTopicPresence(topicId) {