@llblab/pi-telegram 0.22.1 → 0.23.0

package/lib/text-groups.ts

@@ -4,6 +4,15 @@
  * Owns conservative delayed grouping for Telegram text messages that look like automatic long-message splits
  */
 
+import { setTimeout as waitForTimeout } from "node:timers/promises";
+
+import {
+  extractTelegramMessageText,
+  type TelegramMessageForwardOrigin,
+  type TelegramMessageUser,
+  type TelegramRichMessage,
+} from "./media.ts";
+
 const TELEGRAM_TEXT_GROUP_DEBOUNCE_MS = 1000;
 const TELEGRAM_TEXT_GROUP_MIN_SPLIT_LENGTH = 3600;
 const TELEGRAM_TEXT_GROUP_MAX_MESSAGE_ID_GAP = 12;
@@ -13,9 +22,13 @@ export interface TelegramTextGroupMessage {
   media_group_id?: string;
   chat: { id: number };
   message_thread_id?: number;
-  from?: { id: number; is_bot?: boolean };
+  from?: { id?: number; is_bot?: boolean };
   text?: string;
   caption?: string;
+  rich_message?: TelegramRichMessage;
+  forward_origin?: TelegramMessageForwardOrigin;
+  forward_from?: TelegramMessageUser;
+  forward_sender_name?: string;
 }
 
 export interface TelegramTextGroupState<TMessage, TContext = unknown> {
@@ -24,10 +37,24 @@ export interface TelegramTextGroupState<TMessage, TContext = unknown> {
   flushTimer?: ReturnType<typeof setTimeout>;
   dispatching?: boolean;
   suspended?: boolean;
-  reschedule?: () => void;
+  reschedule?: (delayMs?: number) => void;
+  dispatchLimit?: number;
+  forwardCommentCandidate?: boolean;
 }
 
+export type TelegramForwardCommentBatchPosition = "comment" | "forward";
+
 export interface TelegramTextGroupController<TMessage, TContext = unknown> {
+  prepareUpdateBatch: (
+    updates: readonly { message?: TMessage }[],
+  ) => void;
+  getPreparedForwardingPosition: (
+    message: TelegramTextGroupMessage,
+  ) => TelegramForwardCommentBatchPosition | undefined;
+  prepareForwardedMessage: (
+    message: TelegramTextGroupMessage,
+    position: TelegramForwardCommentBatchPosition,
+  ) => void;
   queueMessage: (options: {
     message: TMessage;
     context: TContext;
@@ -43,6 +70,7 @@ export interface TelegramTextGroupController<TMessage, TContext = unknown> {
 
 export interface TelegramTextGroupControllerOptions {
   debounceMs?: number;
+  forwardCommentWaitMs?: number | false;
   minSplitLength?: number;
   setTimer?: (
     callback: () => void,
@@ -66,19 +94,44 @@ export interface TelegramGroupedInputClearerDeps {
 function extractTelegramTextGroupText(
   message: TelegramTextGroupMessage,
 ): string {
-  return typeof message.text === "string" ? message.text : "";
+  return extractTelegramMessageText(message);
+}
+
+function isTelegramForwardedMessage(
+  message: TelegramTextGroupMessage,
+): boolean {
+  return (
+    message.forward_origin !== undefined ||
+    message.forward_from !== undefined ||
+    typeof message.forward_sender_name === "string"
+  );
 }
 
 function isTelegramTextGroupCommand(text: string): boolean {
   return text.trimStart().startsWith("/");
 }
 
+function isTelegramTextGroupClearingCommand(text: string): boolean {
+  const command = text.trimStart().split(/\s+/, 1)[0]?.split("@", 1)[0];
+  return command === "/stop";
+}
+
+function getTelegramTextGroupMessageIdentity(
+  message: TelegramTextGroupMessage,
+): string {
+  const threadKey =
+    typeof message.message_thread_id === "number"
+      ? `thread:${message.message_thread_id}`
+      : "private";
+  return `${message.chat.id}:${threadKey}:${message.message_id}`;
+}
+
 function getTelegramTextGroupKey(
   message: TelegramTextGroupMessage,
 ): string | undefined {
   if (message.media_group_id) return undefined;
   if (!message.from || message.from.is_bot) return undefined;
-  if (typeof message.text !== "string") return undefined;
+  if (!extractTelegramTextGroupText(message)) return undefined;
   const threadKey =
     typeof message.message_thread_id === "number"
       ? `thread:${message.message_thread_id}`
@@ -127,12 +180,20 @@ export function queueTelegramTextGroupMessage<
     messages: TMessage[],
     ctx: TContext,
   ) => unknown | Promise<unknown>;
+  forceStart?: boolean;
+  dispatchImmediately?: boolean;
+  forwardCommentCandidate?: boolean;
+  delayMs?: number;
 }): boolean {
   const key = getTelegramTextGroupKey(options.message);
   if (!key) return false;
   const existing = options.groups.get(key);
+  if (existing?.messages.some(
+    (message) => message.message_id === options.message.message_id,
+  )) return true;
   if (
     !existing &&
+    !options.forceStart &&
     !canStartTelegramTextGroup(options.message, options.minSplitLength)
   )
     return false;
@@ -141,9 +202,8 @@ export function queueTelegramTextGroupMessage<
   const state = existing ?? { messages: [] };
   state.messages.push(options.message);
   state.context = options.context;
-  const scheduleDispatch = (): void => {
-    if (state.suspended) return;
-    state.flushTimer = options.setTimer(() => {
+  state.forwardCommentCandidate = options.forwardCommentCandidate;
+  const dispatchQueued = (): void => {
       state.flushTimer = undefined;
       const queued = options.groups.get(key);
       if (!queued || queued.context === undefined) return;
@@ -151,7 +211,9 @@ export function queueTelegramTextGroupMessage<
         scheduleDispatch();
         return;
       }
-      const dispatchedMessages = [...queued.messages];
+      const dispatchCount = queued.dispatchLimit ?? queued.messages.length;
+      queued.dispatchLimit = undefined;
+      const dispatchedMessages = queued.messages.slice(0, dispatchCount);
       const dispatchedIds = new Set(
         dispatchedMessages.map((message) => message.message_id),
       );
@@ -174,12 +236,17 @@ export function queueTelegramTextGroupMessage<
           if (!queued.flushTimer) scheduleDispatch();
         },
       );
-    }, options.debounceMs);
+  };
+  const scheduleDispatch = (delayMs = options.debounceMs): void => {
+    if (state.suspended) return;
+    state.flushTimer = options.setTimer(dispatchQueued, delayMs);
     state.flushTimer.unref?.();
   };
   state.reschedule = scheduleDispatch;
   if (state.flushTimer) options.clearTimer(state.flushTimer);
-  scheduleDispatch();
+  scheduleDispatch(
+    options.dispatchImmediately ? 0 : (options.delayMs ?? options.debounceMs),
+  );
   options.groups.set(key, state);
   return true;
 }
@@ -191,17 +258,102 @@ export function createTelegramTextGroupController<
   options: TelegramTextGroupControllerOptions = {},
 ): TelegramTextGroupController<TMessage, TContext> {
   const groups = new Map<string, TelegramTextGroupState<TMessage, TContext>>();
+  const plannedForwardCommentStarts = new Set<string>();
+  const plannedForwardCommentEnds = new Set<string>();
   const debounceMs = options.debounceMs ?? TELEGRAM_TEXT_GROUP_DEBOUNCE_MS;
   const minSplitLength =
     options.minSplitLength ?? TELEGRAM_TEXT_GROUP_MIN_SPLIT_LENGTH;
+  const forwardCommentWaitMs =
+    options.forwardCommentWaitMs === undefined
+      ? debounceMs
+      : options.forwardCommentWaitMs;
   const setTimer =
     options.setTimer ??
-    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
-      setTimeout(callback, ms));
-  const clearTimer = options.clearTimer ?? clearTimeout;
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> => {
+      const controller = new AbortController();
+      void waitForTimeout(ms, undefined, {
+        signal: controller.signal,
+      }).then(callback, () => undefined);
+      return controller as unknown as ReturnType<typeof setTimeout>;
+    });
+  const clearTimer =
+    options.clearTimer ??
+    (options.setTimer
+      ? clearTimeout
+      : (timer: ReturnType<typeof setTimeout>): void => {
+          (timer as unknown as AbortController).abort();
+        });
   return {
-    queueMessage: ({ message, context, dispatchMessages }) =>
-      queueTelegramTextGroupMessage({
+    prepareUpdateBatch(updates) {
+      for (let index = 0; index + 1 < updates.length; index += 1) {
+        const comment = updates[index]?.message;
+        const forwarded = updates[index + 1]?.message;
+        if (!comment || !forwarded) continue;
+        const commentText = extractTelegramTextGroupText(comment);
+        const commentKey = getTelegramTextGroupKey(comment);
+        const forwardedKey = getTelegramTextGroupKey(forwarded);
+        if (
+          !commentKey ||
+          commentKey !== forwardedKey ||
+          !commentText ||
+          isTelegramTextGroupCommand(commentText) ||
+          isTelegramForwardedMessage(comment) ||
+          !isTelegramForwardedMessage(forwarded) ||
+          forwarded.message_id <= comment.message_id ||
+          forwarded.message_id >
+            comment.message_id + TELEGRAM_TEXT_GROUP_MAX_MESSAGE_ID_GAP
+        ) {
+          continue;
+        }
+        plannedForwardCommentStarts.add(
+          getTelegramTextGroupMessageIdentity(comment),
+        );
+        plannedForwardCommentEnds.add(
+          getTelegramTextGroupMessageIdentity(forwarded),
+        );
+      }
+    },
+    getPreparedForwardingPosition(message) {
+      const identity = getTelegramTextGroupMessageIdentity(message);
+      if (plannedForwardCommentStarts.has(identity)) return "comment";
+      if (plannedForwardCommentEnds.has(identity)) return "forward";
+      return undefined;
+    },
+    prepareForwardedMessage(message, position) {
+      const identity = getTelegramTextGroupMessageIdentity(message);
+      if (position === "comment") plannedForwardCommentStarts.add(identity);
+      else plannedForwardCommentEnds.add(identity);
+    },
+    queueMessage: ({ message, context, dispatchMessages }) => {
+      const identity = getTelegramTextGroupMessageIdentity(message);
+      const key = getTelegramTextGroupKey(message);
+      const plannedStart = plannedForwardCommentStarts.delete(identity);
+      const forwarded = isTelegramForwardedMessage(message);
+      const existing = key ? groups.get(key) : undefined;
+      const text = extractTelegramTextGroupText(message);
+      if (existing && isTelegramTextGroupClearingCommand(text)) {
+        if (existing.flushTimer) clearTimer(existing.flushTimer);
+        groups.delete(key!);
+      }
+      const separateFromCandidate =
+        !!existing?.forwardCommentCandidate &&
+        !forwarded &&
+        !isTelegramTextGroupCommand(text);
+      if (separateFromCandidate) {
+        existing.dispatchLimit = existing.messages.length;
+      }
+      const forceStart =
+        plannedStart ||
+        (forwardCommentWaitMs !== false &&
+          !forwarded &&
+          !!key &&
+          typeof message.text === "string" &&
+          !isTelegramTextGroupCommand(extractTelegramTextGroupText(message)));
+      const dispatchImmediately =
+        separateFromCandidate ||
+        plannedForwardCommentEnds.delete(identity) ||
+        (forwarded && !!key && groups.has(key));
+      return queueTelegramTextGroupMessage({
         message,
         context,
         groups,
@@ -210,7 +362,20 @@ export function createTelegramTextGroupController<
         setTimer,
         clearTimer,
         dispatchMessages,
-      }),
+        forceStart,
+        dispatchImmediately,
+        forwardCommentCandidate:
+          forceStart &&
+          !forwarded &&
+          !canStartTelegramTextGroup(message, minSplitLength),
+        delayMs:
+          forceStart && !canStartTelegramTextGroup(message, minSplitLength)
+            ? forwardCommentWaitMs === false
+              ? undefined
+              : forwardCommentWaitMs
+            : undefined,
+      });
+    },
     suspend: () => {
       for (const state of groups.values()) {
         state.suspended = true;
@@ -230,6 +395,8 @@ export function createTelegramTextGroupController<
         if (state.flushTimer) clearTimer(state.flushTimer);
       }
       groups.clear();
+      plannedForwardCommentStarts.clear();
+      plannedForwardCommentEnds.clear();
     },
   };
 }

package/lib/thread-reconciler.ts

@@ -10,7 +10,13 @@ import type { TelegramTarget } from "./target.ts";
 type ThreadTarget = TelegramTarget & { threadId: number };
 
 type ThreadRecordStatus =
-  "active" | "offline" | "stale" | "pending" | "starting" | "failed";
+  | "active"
+  | "offline"
+  | "stale"
+  | "pending"
+  | "starting"
+  | "probe-required"
+  | "failed";
 
 export interface ThreadReconciliationRecord {
   target: ThreadTarget;
@@ -182,6 +188,7 @@ export interface ThreadReconciliationPlan {
 
 export interface ThreadReconciliationApplyResult {
   changed: boolean;
+  incompleteActions?: ThreadReconciliationAction[];
 }
 
 export interface ThreadReconciliationApplyPorts {
@@ -376,7 +383,7 @@ function getActionLeaderEpoch(
   return "leaderEpoch" in action ? action.leaderEpoch : undefined;
 }
 
-function isTelegramTopicTargetGoneError(error: unknown): boolean {
+function isTelegramTopicTargetDeletedOrMissingError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
   const message = error.message.toLowerCase();
   return (
@@ -384,7 +391,15 @@ function isTelegramTopicTargetGoneError(error: unknown): boolean {
     message.includes("message thread not found") ||
     message.includes("thread not found") ||
     message.includes("topic not found") ||
-    message.includes("topic deleted") ||
+    message.includes("topic deleted")
+  );
+}
+
+function isTelegramTopicTargetGoneError(error: unknown): boolean {
+  if (isTelegramTopicTargetDeletedOrMissingError(error)) return true;
+  if (!(error instanceof Error)) return false;
+  const message = error.message.toLowerCase();
+  return (
     message.includes("topic closed") ||
     message.includes("thread closed") ||
     message.includes("forum topic closed") ||
@@ -503,6 +518,7 @@ export async function applyThreadReconciliationPlan(
 ): Promise<ThreadReconciliationApplyResult> {
   let shouldPersist = false;
   const persistFences: ThreadReconciliationAction[] = [];
+  const incompleteActions: ThreadReconciliationAction[] = [];
   for (const action of plan.actions) {
     if (action.kind === "remove-reservation") {
       shouldPersist =
@@ -521,7 +537,10 @@ export async function applyThreadReconciliationPlan(
       continue;
     }
     if (action.kind === "close-stale-replaced-topic") {
-      if (shouldSkipForStaleLeaderEpoch(action, ports)) continue;
+      if (shouldSkipForStaleLeaderEpoch(action, ports)) {
+        incompleteActions.push(action);
+        continue;
+      }
       if (!ports.callApi) {
         ports.recordRuntimeEvent?.(
           "telegram",
@@ -533,28 +552,35 @@ export async function applyThreadReconciliationPlan(
             threadId: action.target.threadId,
           },
         );
+        incompleteActions.push(action);
         continue;
       }
+      let closeConfirmed = false;
       try {
-        if (shouldSkipForStaleLeaderEpoch(action, ports)) continue;
         await ports.callApi("closeForumTopic", {
           chat_id: action.target.chatId,
           message_thread_id: action.target.threadId,
         });
-        if (!shouldSkipForStaleLeaderEpoch(action, ports)) {
-          const changed =
-            ports.markStaleByTarget?.(action.target, "closed") ?? false;
-          if (changed) persistFences.push(action);
-          shouldPersist = changed || shouldPersist;
-        }
+        closeConfirmed = true;
       } catch (error) {
-        ports.recordRuntimeEvent?.("telegram", error, {
-          phase: `thread-reconciler-${action.reason}-closeForumTopic`,
-          instanceId: action.instanceId,
-          chatId: action.target.chatId,
-          threadId: action.target.threadId,
-        });
+        closeConfirmed = isTelegramTopicTargetGoneError(error);
+        if (!closeConfirmed) {
+          ports.recordRuntimeEvent?.("telegram", error, {
+            phase: `thread-reconciler-${action.reason}-closeForumTopic`,
+            instanceId: action.instanceId,
+            chatId: action.target.chatId,
+            threadId: action.target.threadId,
+          });
+        }
       }
+      if (shouldSkipForStaleLeaderEpoch(action, ports) || !closeConfirmed) {
+        incompleteActions.push(action);
+        continue;
+      }
+      const changed =
+        ports.markStaleByTarget?.(action.target, "closed") ?? false;
+      if (changed) persistFences.push(action);
+      shouldPersist = changed || shouldPersist;
       continue;
     }
     if (
@@ -566,7 +592,10 @@ export async function applyThreadReconciliationPlan(
       action.kind === "close-delete-disconnected-instance-topic" ||
       action.kind === "close-delete-expired-pending-provision-topic"
     ) {
-      if (shouldSkipForStaleLeaderEpoch(action, ports)) continue;
+      if (shouldSkipForStaleLeaderEpoch(action, ports)) {
+        incompleteActions.push(action);
+        continue;
+      }
       if (!ports.callApi) {
         ports.recordRuntimeEvent?.(
           "telegram",
@@ -578,6 +607,7 @@ export async function applyThreadReconciliationPlan(
             threadId: action.target.threadId,
           },
         );
+        incompleteActions.push(action);
         continue;
       }
       let deleteConfirmed = false;
@@ -590,7 +620,11 @@ export async function applyThreadReconciliationPlan(
           });
           if (method === "deleteForumTopic") deleteConfirmed = true;
         } catch (error) {
-          if (isTelegramTopicTargetGoneError(error)) {
+          const confirmsMethodOutcome =
+            method === "deleteForumTopic"
+              ? isTelegramTopicTargetDeletedOrMissingError(error)
+              : isTelegramTopicTargetGoneError(error);
+          if (confirmsMethodOutcome) {
             if (method === "deleteForumTopic") deleteConfirmed = true;
           } else {
             ports.recordRuntimeEvent?.("telegram", error, {
@@ -601,7 +635,10 @@ export async function applyThreadReconciliationPlan(
           }
         }
       }
-      if (shouldSkipForStaleLeaderEpoch(action, ports)) continue;
+      if (shouldSkipForStaleLeaderEpoch(action, ports)) {
+        incompleteActions.push(action);
+        continue;
+      }
       if (!deleteConfirmed) {
         ports.recordRuntimeEvent?.(
           "telegram",
@@ -615,6 +652,7 @@ export async function applyThreadReconciliationPlan(
             ...("messageId" in action ? { messageId: action.messageId } : {}),
           },
         );
+        incompleteActions.push(action);
         continue;
       }
       if (shouldSkipForStaleLeaderEpoch(action, ports)) continue;
@@ -682,12 +720,18 @@ export async function applyThreadReconciliationPlan(
   if (shouldPersist) {
     for (const action of persistFences) {
       if (shouldSkipForStaleLeaderEpoch(action, ports)) {
-        return { changed: true };
+        return {
+          changed: true,
+          ...(incompleteActions.length > 0 ? { incompleteActions } : {}),
+        };
       }
     }
     await ports.persist?.();
   }
-  return { changed: shouldPersist };
+  return {
+    changed: shouldPersist,
+    ...(incompleteActions.length > 0 ? { incompleteActions } : {}),
+  };
 }
 
 export function planThreadReconciliation(