@elizaos/plugin-telegram 1.0.0-beta.3 → 1.0.0-beta.32

package/dist/index.js

@@ -54,6 +54,7 @@ import {
 } from "@elizaos/core";
 
 // src/utils.ts
+import { Markup } from "telegraf";
 function escapeMarkdown(text) {
   if (text.startsWith("```") && text.endsWith("```")) {
     return text;
@@ -66,8 +67,20 @@ function escapeMarkdown(text) {
     return part.replace(/`.*?`/g, (match) => match).replace(/([*_`\\])/g, "\\$1");
   }).join("");
 }
+function convertToTelegramButtons(buttons) {
+  if (!buttons) return [];
+  return buttons.map((button) => {
+    switch (button.kind) {
+      case "login":
+        return Markup.button.login(button.text, button.url);
+      case "url":
+        return Markup.button.url(button.text, button.url);
+    }
+  });
+}
 
 // src/messageManager.ts
+import { Markup as Markup2 } from "telegraf";
 import fs from "node:fs";
 var MAX_MESSAGE_LENGTH = 4096;
 var getChannelType = (chat) => {
@@ -127,7 +140,7 @@ ${description}]` };
    * Sends a message in chunks, handling attachments and splitting the message if necessary
    *
    * @param {Context} ctx - The context object representing the current state of the bot
-   * @param {Content} content - The content of the message to be sent
+   * @param {TelegramContent} content - The content of the message to be sent
    * @param {number} [replyToMessageId] - The ID of the message to reply to, if any
    * @returns {Promise<Message.TextMessage[]>} - An array of TextMessage objects representing the messages sent
    */
@@ -158,11 +171,13 @@ ${description}]` };
     } else {
       const chunks = this.splitMessage(content.text);
       const sentMessages = [];
+      const telegramButtons = convertToTelegramButtons(content.buttons ?? []);
       for (let i = 0; i < chunks.length; i++) {
         const chunk = escapeMarkdown(chunks[i]);
         const sentMessage = await ctx.telegram.sendMessage(ctx.chat.id, chunk, {
           reply_parameters: i === 0 && replyToMessageId ? { message_id: replyToMessageId } : void 0,
-          parse_mode: "Markdown"
+          parse_mode: "Markdown",
+          ...Markup2.inlineKeyboard(telegramButtons)
         });
         sentMessages.push(sentMessage);
       }
@@ -249,8 +264,11 @@ ${description}]` };
     const message = ctx.message;
     try {
       const entityId = createUniqueUuid(this.runtime, ctx.from.id.toString());
-      const userName = ctx.from.username || ctx.from.first_name || "Unknown User";
-      const roomId = createUniqueUuid(this.runtime, (_a = ctx.chat) == null ? void 0 : _a.id.toString());
+      const threadId = "is_topic_message" in message && message.is_topic_message ? (_a = message.message_thread_id) == null ? void 0 : _a.toString() : void 0;
+      const roomId = createUniqueUuid(
+        this.runtime,
+        threadId ? `${ctx.chat.id}-${threadId}` : ctx.chat.id.toString()
+      );
       const messageId = createUniqueUuid(this.runtime, (_b = message == null ? void 0 : message.message_id) == null ? void 0 : _b.toString());
       const imageInfo = await this.processImage(message);
       let messageText = "";
@@ -263,34 +281,6 @@ ${description}]` };
       if (!fullText) return;
       const chat = message.chat;
       const channelType = getChannelType(chat);
-      const worldId = createUniqueUuid(
-        this.runtime,
-        chat.type === "private" ? `private_${chat.id}` : chat.id.toString()
-      );
-      const worldName = chat.type === "supergroup" ? chat.title : chat.type === "channel" ? chat.title : chat.type === "private" ? `Chat with ${chat.first_name || "Unknown"}` : "Telegram";
-      const roomName = chat.type === "private" ? chat.first_name : chat.type === "supergroup" ? chat.title : chat.type === "channel" ? chat.title : chat.type === "group" ? chat.title : "Unknown Group";
-      await this.runtime.ensureConnection({
-        entityId,
-        roomId,
-        userName,
-        name: userName,
-        source: "telegram",
-        channelId: ctx.chat.id.toString(),
-        serverId: chat.type === "private" ? void 0 : chat.id.toString(),
-        // Only set serverId for non-private chats
-        type: channelType,
-        worldId
-      });
-      const room = {
-        id: roomId,
-        name: roomName,
-        source: "telegram",
-        type: channelType,
-        channelId: ctx.chat.id.toString(),
-        serverId: chat.type === "private" ? void 0 : chat.id.toString(),
-        worldId
-      };
-      await this.runtime.ensureRoomExists(room);
       const memory = {
         id: messageId,
         entityId,
@@ -306,6 +296,7 @@ ${description}]` };
       };
       const callback = async (content, _files) => {
         try {
+          if (!content.text) return [];
           const sentMessages = await this.sendMessageInChunks(ctx, content, message.message_id);
           if (!sentMessages) return [];
           const memories = [];
@@ -360,7 +351,7 @@ ${description}]` };
   }
   /**
    * Handles the reaction event triggered by a user reacting to a message.
-   * * @param {NarrowedContext<Context<Update>, Update.MessageReactionUpdate>} ctx The context of the message reaction update
+   * @param {NarrowedContext<Context<Update>, Update.MessageReactionUpdate>} ctx The context of the message reaction update
    * @returns {Promise<void>} A Promise that resolves when the reaction handling is complete
    */
   async handleReaction(ctx) {
@@ -371,7 +362,6 @@ ${description}]` };
     try {
       const entityId = createUniqueUuid(this.runtime, ctx.from.id.toString());
       const roomId = createUniqueUuid(this.runtime, ctx.chat.id.toString());
-      const worldId = createUniqueUuid(this.runtime, ctx.chat.id.toString());
       const reactionId = createUniqueUuid(
         this.runtime,
         `${reaction.message_id}-${ctx.from.id}-${Date.now()}`
@@ -472,7 +462,9 @@ ${description}]` };
       }
       this.runtime.emitEvent(EventType.MESSAGE_SENT, {
         runtime: this.runtime,
-        messages: memories,
+        message: {
+          content
+        },
         roomId,
         source: "telegram"
       });
@@ -496,6 +488,7 @@ var TelegramService = class _TelegramService extends Service {
   messageManager;
   options;
   knownChats = /* @__PURE__ */ new Map();
+  syncedEntityIds = /* @__PURE__ */ new Set();
   /**
    * Constructor for TelegramService class.
    * @param {IAgentRuntime} runtime - The runtime object for the agent.
@@ -532,6 +525,7 @@ var TelegramService = class _TelegramService extends Service {
         );
         logger2.log("\u{1F680} Starting Telegram bot...");
         await service.initializeBot();
+        service.setupMiddlewares();
         service.setupMessageHandlers();
         await service.bot.telegram.getMe();
         return service;
@@ -584,6 +578,106 @@ var TelegramService = class _TelegramService extends Service {
     process.once("SIGINT", () => this.bot.stop("SIGINT"));
     process.once("SIGTERM", () => this.bot.stop("SIGTERM"));
   }
+  /**
+   * Sets up the middleware chain for preprocessing messages before they reach handlers.
+   * This critical method establishes a sequential processing pipeline that:
+   *
+   * 1. Authorization - Verifies if a chat is allowed to interact with the bot based on configured settings
+   * 2. Chat Discovery - Ensures chat entities and worlds exist in the runtime, creating them if needed
+   * 3. Forum Topics - Handles Telegram forum topics as separate rooms for better conversation management
+   * 4. Entity Synchronization - Ensures message senders are properly synchronized as entities
+   *
+   * The middleware chain runs in sequence for each message, with each step potentially
+   * enriching the context or stopping processing if conditions aren't met.
+   * This preprocessing is essential for maintaining consistent state before message handlers execute.
+   *
+   * @private
+   */
+  setupMiddlewares() {
+    this.bot.use(this.authorizationMiddleware.bind(this));
+    this.bot.use(this.chatAndEntityMiddleware.bind(this));
+  }
+  /**
+   * Authorization middleware - checks if chat is allowed to interact with the bot
+   * based on the TELEGRAM_ALLOWED_CHATS configuration.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {Function} next - The function to call to proceed to the next middleware
+   * @returns {Promise<void>}
+   * @private
+   */
+  async authorizationMiddleware(ctx, next) {
+    if (!await this.isGroupAuthorized(ctx)) {
+      logger2.debug("Chat not authorized, skipping message processing");
+      return;
+    }
+    await next();
+  }
+  /**
+   * Chat and entity management middleware - handles new chats, forum topics, and entity synchronization.
+   * This middleware implements decision logic to determine which operations are needed based on
+   * the chat type and whether we've seen this chat before.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {Function} next - The function to call to proceed to the next middleware
+   * @returns {Promise<void>}
+   * @private
+   */
+  async chatAndEntityMiddleware(ctx, next) {
+    if (!ctx.chat) return next();
+    const chatId = ctx.chat.id.toString();
+    if (!this.knownChats.has(chatId)) {
+      await this.handleNewChat(ctx);
+      return next();
+    }
+    await this.processExistingChat(ctx);
+    await next();
+  }
+  /**
+   * Process an existing chat based on chat type and message properties.
+   * Different chat types require different processing steps.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async processExistingChat(ctx) {
+    var _a;
+    if (!ctx.chat) return;
+    const chat = ctx.chat;
+    if (chat.type === "supergroup" && chat.is_forum && ((_a = ctx.message) == null ? void 0 : _a.message_thread_id)) {
+      try {
+        await this.handleForumTopic(ctx);
+      } catch (error) {
+        logger2.error(`Error handling forum topic: ${error}`);
+      }
+    }
+    if (ctx.from && ctx.chat.type !== "private") {
+      await this.syncEntity(ctx);
+    }
+  }
+  /**
+   * Sets up message and reaction handlers for the bot.
+   * Configures event handlers to process incoming messages and reactions.
+   *
+   * @private
+   */
+  setupMessageHandlers() {
+    this.bot.on("message", async (ctx) => {
+      try {
+        await this.messageManager.handleMessage(ctx);
+      } catch (error) {
+        logger2.error("Error handling message:", error);
+      }
+    });
+    this.bot.on("message_reaction", async (ctx) => {
+      try {
+        await this.messageManager.handleReaction(ctx);
+      } catch (error) {
+        logger2.error("Error handling reaction:", error);
+      }
+    });
+  }
   /**
    * Checks if a group is authorized, based on the TELEGRAM_ALLOWED_CHATS setting.
    * @param {Context} ctx - The context of the incoming update.
@@ -593,9 +687,6 @@ var TelegramService = class _TelegramService extends Service {
     var _a;
     const chatId = (_a = ctx.chat) == null ? void 0 : _a.id.toString();
     if (!chatId) return false;
-    if (!this.knownChats.has(chatId)) {
-      await this.handleNewChat(ctx);
-    }
     const allowedChats = this.runtime.getSetting("TELEGRAM_ALLOWED_CHATS");
     if (!allowedChats) {
       return true;
@@ -609,39 +700,196 @@ var TelegramService = class _TelegramService extends Service {
     }
   }
   /**
-   * Handles new chat discovery and emits WORLD_JOINED event
+   * Synchronizes an entity from a message context with the runtime system.
+   * This method handles three cases:
+   * 1. Message sender - most common case
+   * 2. New chat member - when a user joins the chat
+   * 3. Left chat member - when a user leaves the chat
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncEntity(ctx) {
+    var _a;
+    if (!ctx.chat) return;
+    const chat = ctx.chat;
+    const chatId = chat.id.toString();
+    const worldId = createUniqueUuid2(this.runtime, chatId);
+    const roomId = createUniqueUuid2(
+      this.runtime,
+      ((_a = ctx.message) == null ? void 0 : _a.message_thread_id) ? `${ctx.chat.id}-${ctx.message.message_thread_id}` : ctx.chat.id.toString()
+    );
+    await this.syncMessageSender(ctx, worldId, roomId, chatId);
+    await this.syncNewChatMember(ctx, worldId, roomId, chatId);
+    await this.syncLeftChatMember(ctx);
+  }
+  /**
+   * Synchronizes the message sender entity with the runtime system.
+   * This is the most common entity sync case.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {UUID} worldId - The ID of the world
+   * @param {UUID} roomId - The ID of the room
+   * @param {string} chatId - The ID of the chat
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncMessageSender(ctx, worldId, roomId, chatId) {
+    if (ctx.from && !this.syncedEntityIds.has(ctx.from.id.toString())) {
+      const telegramId = ctx.from.id.toString();
+      const entityId = createUniqueUuid2(this.runtime, telegramId);
+      await this.runtime.ensureConnection({
+        entityId,
+        roomId,
+        userName: ctx.from.username,
+        userId: telegramId,
+        name: ctx.from.first_name || ctx.from.username || "Unknown User",
+        source: "telegram",
+        channelId: chatId,
+        serverId: chatId,
+        type: ChannelType2.GROUP,
+        worldId
+      });
+      this.syncedEntityIds.add(entityId);
+    }
+  }
+  /**
+   * Synchronizes a new chat member entity with the runtime system.
+   * Triggered when a user joins the chat.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {UUID} worldId - The ID of the world
+   * @param {UUID} roomId - The ID of the room
+   * @param {string} chatId - The ID of the chat
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncNewChatMember(ctx, worldId, roomId, chatId) {
+    if (ctx.message && "new_chat_member" in ctx.message) {
+      const newMember = ctx.message.new_chat_member;
+      const telegramId = newMember.id.toString();
+      const entityId = createUniqueUuid2(this.runtime, telegramId);
+      if (this.syncedEntityIds.has(telegramId)) return;
+      await this.runtime.ensureConnection({
+        entityId,
+        roomId,
+        userName: newMember.username,
+        userId: telegramId,
+        name: newMember.first_name || newMember.username || "Unknown User",
+        source: "telegram",
+        channelId: chatId,
+        serverId: chatId,
+        type: ChannelType2.GROUP,
+        worldId
+      });
+      this.syncedEntityIds.add(entityId);
+      this.runtime.emitEvent(["TELEGRAM_ENTITY_JOINED" /* ENTITY_JOINED */], {
+        runtime: this.runtime,
+        entityId,
+        worldId,
+        newMember,
+        ctx
+      });
+    }
+  }
+  /**
+   * Updates entity status when a user leaves the chat.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async syncLeftChatMember(ctx) {
+    if (ctx.message && "left_chat_member" in ctx.message) {
+      const leftMember = ctx.message.left_chat_member;
+      const telegramId = leftMember.id.toString();
+      const entityId = createUniqueUuid2(this.runtime, telegramId);
+      const existingEntity = await this.runtime.getEntityById(entityId);
+      if (existingEntity) {
+        existingEntity.metadata = {
+          ...existingEntity.metadata,
+          status: "INACTIVE",
+          leftAt: Date.now()
+        };
+        await this.runtime.updateEntity(existingEntity);
+      }
+    }
+  }
+  /**
+   * Handles forum topics by creating appropriate rooms in the runtime system.
+   * This enables proper conversation management for Telegram's forum feature.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
+   */
+  async handleForumTopic(ctx) {
+    var _a;
+    if (!ctx.chat || !((_a = ctx.message) == null ? void 0 : _a.message_thread_id)) return;
+    const chat = ctx.chat;
+    const chatId = chat.id.toString();
+    const worldId = createUniqueUuid2(this.runtime, chatId);
+    const room = await this.buildForumTopicRoom(ctx, worldId);
+    if (!room) return;
+    await this.runtime.ensureRoomExists(room);
+  }
+  /**
+   * Builds entity for message sender
+   */
+  buildMsgSenderEntity(from) {
+    if (!from) return null;
+    const userId = createUniqueUuid2(this.runtime, from.id.toString());
+    const telegramId = from.id.toString();
+    return {
+      id: userId,
+      agentId: this.runtime.agentId,
+      names: [from.first_name || from.username || "Unknown User"],
+      metadata: {
+        telegram: {
+          id: telegramId,
+          username: from.username,
+          name: from.first_name || from.username || "Unknown User"
+        }
+      }
+    };
+  }
+  /**
+   * Handles new chat discovery and emits WORLD_JOINED event.
+   * This is a critical function that ensures new chats are properly
+   * registered in the runtime system and appropriate events are emitted.
+   *
    * @param {Context} ctx - The context of the incoming update
+   * @returns {Promise<void>}
+   * @private
    */
   async handleNewChat(ctx) {
+    var _a;
     if (!ctx.chat) return;
     const chat = ctx.chat;
     const chatId = chat.id.toString();
     this.knownChats.set(chatId, chat);
-    let chatTitle;
-    let channelType;
-    switch (chat.type) {
-      case "private":
-        chatTitle = `Chat with ${chat.first_name || "Unknown User"}`;
-        channelType = ChannelType2.DM;
-        break;
-      case "group":
-        chatTitle = chat.title || "Unknown Group";
-        channelType = ChannelType2.GROUP;
-        break;
-      case "supergroup":
-        chatTitle = chat.title || "Unknown Supergroup";
-        channelType = ChannelType2.GROUP;
-        break;
-      case "channel":
-        chatTitle = chat.title || "Unknown Channel";
-        channelType = ChannelType2.FEED;
-        break;
-      default:
-        chatTitle = "Unknown Chat";
-        channelType = ChannelType2.GROUP;
-    }
+    const { chatTitle, channelType } = this.getChatTypeInfo(chat);
     const worldId = createUniqueUuid2(this.runtime, chatId);
-    const roomId = createUniqueUuid2(this.runtime, chatId);
+    const existingWorld = await this.runtime.getWorld(worldId);
+    if (existingWorld) {
+      return;
+    }
+    const userId = ctx.from ? createUniqueUuid2(this.runtime, ctx.from.id.toString()) : null;
+    let admins = [];
+    let owner = null;
+    if (chat.type === "group" || chat.type === "supergroup" || chat.type === "channel") {
+      try {
+        admins = await ctx.getChatAdministrators();
+        owner = admins.find((admin) => admin.status === "creator");
+      } catch (error) {
+        logger2.warn(`Could not get chat administrators: ${error.message}`);
+      }
+    }
+    let ownerId = userId;
+    if (owner) {
+      ownerId = createUniqueUuid2(this.runtime, String(owner.user.id));
+    }
     const world = {
       id: worldId,
       name: chatTitle,
@@ -649,14 +897,17 @@ var TelegramService = class _TelegramService extends Service {
       serverId: chatId,
       metadata: {
         source: "telegram",
-        ownership: { ownerId: chatId },
-        roles: {
-          [chatId]: Role.OWNER
-        }
+        ownership: { ownerId },
+        roles: ownerId ? {
+          [ownerId]: Role.OWNER
+        } : {},
+        chatType: chat.type,
+        isForumEnabled: chat.type === "supergroup" && chat.is_forum
       }
     };
-    const room = {
-      id: roomId,
+    await this.runtime.ensureWorldExists(world);
+    const generalRoom = {
+      id: createUniqueUuid2(this.runtime, chatId),
       name: chatTitle,
       source: "telegram",
       type: channelType,
@@ -664,204 +915,242 @@ var TelegramService = class _TelegramService extends Service {
       serverId: chatId,
       worldId
     };
-    const users = [];
-    if (chat.type === "private" && chat.id) {
-      const userId = createUniqueUuid2(this.runtime, chat.id.toString());
-      users.push({
-        id: userId,
-        names: [chat.first_name || "Unknown User"],
-        agentId: this.runtime.agentId,
-        metadata: {
-          telegram: {
-            id: chat.id.toString(),
-            username: chat.username || "unknown",
-            name: chat.first_name || "Unknown User"
-          },
-          source: "telegram"
-        }
-      });
-    } else if (chat.type === "group" || chat.type === "supergroup") {
-      try {
-        const admins = await this.bot.telegram.getChatAdministrators(chat.id);
-        if (admins && admins.length > 0) {
-          for (const admin of admins) {
-            const userId = createUniqueUuid2(this.runtime, admin.user.id.toString());
-            users.push({
-              id: userId,
-              names: [admin.user.first_name || admin.user.username || "Unknown Admin"],
-              agentId: this.runtime.agentId,
-              metadata: {
-                telegram: {
-                  id: admin.user.id.toString(),
-                  username: admin.user.username || "unknown",
-                  name: admin.user.first_name || "Unknown Admin",
-                  isAdmin: true,
-                  adminTitle: admin.custom_title || (admin.status === "creator" ? "Owner" : "Admin")
-                },
-                source: "telegram",
-                roles: [admin.status === "creator" ? Role.OWNER : Role.ADMIN]
-              }
-            });
-          }
-        }
-        try {
-          const chatInfo = await this.bot.telegram.getChat(chat.id);
-          if (chatInfo && "member_count" in chatInfo) {
-            world.metadata.memberCount = chatInfo.member_count;
-          }
-        } catch (countError) {
-          logger2.warn(`Could not get member count for chat ${chatId}: ${countError}`);
-        }
-      } catch (error) {
-        logger2.warn(`Could not fetch administrators for chat ${chatId}: ${error}`);
+    await this.runtime.ensureRoomExists(generalRoom);
+    const rooms = [generalRoom];
+    if (chat.type === "supergroup" && chat.is_forum && ((_a = ctx.message) == null ? void 0 : _a.message_thread_id)) {
+      const topicRoom = await this.buildForumTopicRoom(ctx, worldId);
+      if (topicRoom) {
+        rooms.push(topicRoom);
+      }
+      await this.runtime.ensureRoomExists(topicRoom);
+    }
+    const entities = await this.buildStandardizedEntities(chat);
+    if (ctx.from) {
+      const senderEntity = this.buildMsgSenderEntity(ctx.from);
+      if (senderEntity && !entities.some((e) => e.id === senderEntity.id)) {
+        entities.push(senderEntity);
+        this.syncedEntityIds.add(senderEntity.id);
       }
     }
-    const worldPayload = {
+    await this.batchProcessEntities(
+      entities,
+      generalRoom.id,
+      generalRoom.channelId,
+      generalRoom.serverId,
+      generalRoom.type,
+      worldId
+    );
+    const telegramWorldPayload = {
       runtime: this.runtime,
       world,
-      rooms: [room],
-      entities: users,
-      source: "telegram"
-    };
-    const telegramWorldPayload = {
-      ...worldPayload,
-      chat
+      rooms,
+      entities,
+      source: "telegram",
+      chat,
+      botUsername: this.bot.botInfo.username
     };
-    this.runtime.emitEvent(EventType2.WORLD_JOINED, worldPayload);
-    this.runtime.emitEvent("TELEGRAM_WORLD_JOINED" /* WORLD_JOINED */, telegramWorldPayload);
-    if (chat.type === "group" || chat.type === "supergroup") {
-      this.setupEntityTracking(chat.id);
+    if (chat.type !== "private") {
+      await this.runtime.emitEvent("TELEGRAM_WORLD_JOINED" /* WORLD_JOINED */, telegramWorldPayload);
     }
+    await this.runtime.emitEvent(EventType2.WORLD_JOINED, {
+      runtime: this.runtime,
+      world,
+      rooms,
+      entities,
+      source: "telegram"
+    });
   }
   /**
-   * Sets up message and reaction handlers for the bot.
+   * Processes entities in batches to prevent overwhelming the system.
    *
+   * @param {Entity[]} entities - The entities to process
+   * @param {UUID} roomId - The ID of the room to connect entities to
+   * @param {string} channelId - The channel ID
+   * @param {string} serverId - The server ID
+   * @param {ChannelType} roomType - The type of the room
+   * @param {UUID} worldId - The ID of the world
+   * @returns {Promise<void>}
    * @private
-   * @returns {void}
    */
-  setupMessageHandlers() {
-    this.bot.on("message", async (ctx) => {
-      try {
-        if (!await this.isGroupAuthorized(ctx)) return;
-        await this.messageManager.handleMessage(ctx);
-      } catch (error) {
-        logger2.error("Error handling message:", error);
-      }
-    });
-    this.bot.on("message_reaction", async (ctx) => {
-      try {
-        if (!await this.isGroupAuthorized(ctx)) return;
-        await this.messageManager.handleReaction(ctx);
-      } catch (error) {
-        logger2.error("Error handling reaction:", error);
+  async batchProcessEntities(entities, roomId, channelId, serverId, roomType, worldId) {
+    const batchSize = 50;
+    for (let i = 0; i < entities.length; i += batchSize) {
+      const entityBatch = entities.slice(i, i + batchSize);
+      await Promise.all(
+        entityBatch.map(async (entity) => {
+          var _a, _b, _c, _d, _e, _f, _g, _h;
+          try {
+            await this.runtime.ensureConnection({
+              entityId: entity.id,
+              roomId,
+              userName: (_b = (_a = entity.metadata) == null ? void 0 : _a.telegram) == null ? void 0 : _b.username,
+              name: (_d = (_c = entity.metadata) == null ? void 0 : _c.telegram) == null ? void 0 : _d.name,
+              userId: (_f = (_e = entity.metadata) == null ? void 0 : _e.telegram) == null ? void 0 : _f.id,
+              source: "telegram",
+              channelId,
+              serverId,
+              type: roomType,
+              worldId
+            });
+          } catch (err) {
+            logger2.warn(`Failed to sync user ${(_h = (_g = entity.metadata) == null ? void 0 : _g.telegram) == null ? void 0 : _h.username}: ${err}`);
+          }
+        })
+      );
+      if (i + batchSize < entities.length) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
       }
-    });
+    }
   }
   /**
-   * Sets up tracking for new entities in a group chat to sync them as entities
-   * @param {number} chatId - The Telegram chat ID to track entities for
+   * Gets chat title and channel type based on Telegram chat type.
+   * Maps Telegram-specific chat types to standardized system types.
+   *
+   * @param {any} chat - The Telegram chat object
+   * @returns {Object} Object containing chatTitle and channelType
+   * @private
    */
-  setupEntityTracking(chatId) {
-    const syncedEntityIds = /* @__PURE__ */ new Set();
-    this.bot.on("message", async (ctx) => {
-      if (!ctx.chat || ctx.chat.id !== chatId || !ctx.from) return;
-      const entityId = ctx.from.id.toString();
-      if (syncedEntityIds.has(entityId)) return;
-      syncedEntityIds.add(entityId);
-      const entityUuid = createUniqueUuid2(this.runtime, entityId);
-      const worldId = createUniqueUuid2(this.runtime, chatId.toString());
-      const chatIdStr = chatId.toString();
-      try {
-        await this.runtime.ensureConnection({
-          entityId: entityUuid,
-          roomId: createUniqueUuid2(this.runtime, chatIdStr),
-          userName: ctx.from.username || ctx.from.first_name || "Unknown Entity",
-          name: ctx.from.first_name || ctx.from.username || "Unknown Entity",
-          source: "telegram",
-          channelId: chatIdStr,
-          serverId: chatIdStr,
-          type: ChannelType2.GROUP,
-          worldId
-        });
-        const entityJoinedPayload = {
-          runtime: this.runtime,
-          entityId: entityUuid,
-          entity: {
-            id: entityId,
-            username: ctx.from.username || ctx.from.first_name || "Unknown Entity",
-            displayName: ctx.from.first_name || ctx.from.username || "Unknown Entity"
-          },
-          worldId,
-          source: "telegram",
+  getChatTypeInfo(chat) {
+    let chatTitle;
+    let channelType;
+    switch (chat.type) {
+      case "private":
+        chatTitle = `Chat with ${chat.first_name || "Unknown User"}`;
+        channelType = ChannelType2.DM;
+        break;
+      case "group":
+        chatTitle = chat.title || "Unknown Group";
+        channelType = ChannelType2.GROUP;
+        break;
+      case "supergroup":
+        chatTitle = chat.title || "Unknown Supergroup";
+        channelType = ChannelType2.GROUP;
+        break;
+      case "channel":
+        chatTitle = chat.title || "Unknown Channel";
+        channelType = ChannelType2.FEED;
+        break;
+      default:
+        chatTitle = "Unknown Chat";
+        channelType = ChannelType2.GROUP;
+    }
+    return { chatTitle, channelType };
+  }
+  /**
+   * Builds standardized entity representations from Telegram chat data.
+   * Transforms Telegram-specific user data into system-standard Entity objects.
+   *
+   * @param {any} chat - The Telegram chat object
+   * @returns {Promise<Entity[]>} Array of standardized Entity objects
+   * @private
+   */
+  async buildStandardizedEntities(chat) {
+    const entities = [];
+    try {
+      if (chat.type === "private" && chat.id) {
+        const userId = createUniqueUuid2(this.runtime, chat.id.toString());
+        entities.push({
+          id: userId,
+          names: [chat.first_name || "Unknown User"],
+          agentId: this.runtime.agentId,
           metadata: {
-            joinedAt: Date.now()
+            telegram: {
+              id: chat.id.toString(),
+              username: chat.username || "unknown",
+              name: chat.first_name || "Unknown User"
+            },
+            source: "telegram"
           }
-        };
-        const telegramEntityJoinedPayload = {
-          ...entityJoinedPayload,
-          telegramUser: {
-            id: ctx.from.id,
-            username: ctx.from.username,
-            first_name: ctx.from.first_name
+        });
+        this.syncedEntityIds.add(userId);
+      } else if (chat.type === "group" || chat.type === "supergroup") {
+        try {
+          const admins = await this.bot.telegram.getChatAdministrators(chat.id);
+          if (admins && admins.length > 0) {
+            for (const admin of admins) {
+              const userId = createUniqueUuid2(this.runtime, admin.user.id.toString());
+              entities.push({
+                id: userId,
+                names: [admin.user.first_name || admin.user.username || "Unknown Admin"],
+                agentId: this.runtime.agentId,
+                metadata: {
+                  telegram: {
+                    id: admin.user.id.toString(),
+                    username: admin.user.username || "unknown",
+                    name: admin.user.first_name || "Unknown Admin",
+                    isAdmin: true,
+                    adminTitle: admin.custom_title || (admin.status === "creator" ? "Owner" : "Admin")
+                  },
+                  source: "telegram",
+                  roles: [admin.status === "creator" ? Role.OWNER : Role.ADMIN]
+                }
+              });
+              this.syncedEntityIds.add(userId);
+            }
           }
-        };
-        this.runtime.emitEvent(EventType2.ENTITY_JOINED, entityJoinedPayload);
-        this.runtime.emitEvent("TELEGRAM_ENTITY_JOINED" /* ENTITY_JOINED */, telegramEntityJoinedPayload);
-        logger2.info(
-          `Tracked new Telegram entity: ${ctx.from.username || ctx.from.first_name || entityId}`
-        );
-      } catch (error) {
-        logger2.error(`Error syncing new Telegram entity ${entityId} from chat ${chatId}:`, error);
+        } catch (error) {
+          logger2.warn(`Could not fetch administrators for chat ${chat.id}: ${error}`);
+        }
       }
-    });
-    this.bot.on("left_chat_member", async (ctx) => {
-      var _a, _b;
-      if (!((_a = ctx.message) == null ? void 0 : _a.left_chat_member) || ((_b = ctx.chat) == null ? void 0 : _b.id) !== chatId) return;
-      const leftUser = ctx.message.left_chat_member;
-      const entityId = createUniqueUuid2(this.runtime, leftUser.id.toString());
-      const chatIdStr = chatId.toString();
-      const worldId = createUniqueUuid2(this.runtime, chatIdStr);
-      try {
-        const entity = await this.runtime.getEntityById(entityId);
-        if (entity) {
-          entity.metadata = {
-            ...entity.metadata,
-            status: "INACTIVE",
-            leftAt: Date.now()
-          };
-          await this.runtime.updateEntity(entity);
-          const entityLeftPayload = {
-            runtime: this.runtime,
-            entityId,
-            entity: {
-              id: leftUser.id.toString(),
-              username: leftUser.username || leftUser.first_name || "Unknown Entity",
-              displayName: leftUser.first_name || leftUser.username || "Unknown Entity"
-            },
-            worldId,
-            source: "telegram",
-            metadata: {
-              leftAt: Date.now()
-            }
-          };
-          const telegramEntityLeftPayload = {
-            ...entityLeftPayload,
-            telegramUser: {
-              id: leftUser.id,
-              username: leftUser.username,
-              first_name: leftUser.first_name
-            }
-          };
-          this.runtime.emitEvent(EventType2.ENTITY_LEFT, entityLeftPayload);
-          this.runtime.emitEvent("TELEGRAM_ENTITY_LEFT" /* ENTITY_LEFT */, telegramEntityLeftPayload);
-          logger2.info(
-            `Entity ${leftUser.username || leftUser.first_name || leftUser.id} left chat ${chatId}`
-          );
+    } catch (error) {
+      logger2.error(
+        `Error building standardized entities: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    return entities;
+  }
+  /**
+   * Extracts and builds the room object for a forum topic from a message context.
+   * This refactored method can be used both in middleware and when handling new chats.
+   *
+   * @param {Context} ctx - The context of the incoming update
+   * @param {UUID} worldId - The ID of the world the topic belongs to
+   * @returns {Promise<Room | null>} A Promise that resolves with the room or null if not a topic
+   * @private
+   */
+  async buildForumTopicRoom(ctx, worldId) {
+    var _a;
+    if (!ctx.chat || !((_a = ctx.message) == null ? void 0 : _a.message_thread_id)) return null;
+    if (ctx.chat.type !== "supergroup" || !ctx.chat.is_forum) return null;
+    const chat = ctx.chat;
+    const chatId = chat.id.toString();
+    const threadId = ctx.message.message_thread_id.toString();
+    const roomId = createUniqueUuid2(this.runtime, `${chatId}-${threadId}`);
+    try {
+      const replyMessage = JSON.parse(JSON.stringify(ctx.message));
+      let topicName = `Topic #${threadId}`;
+      if (replyMessage && typeof replyMessage === "object" && "forum_topic_created" in replyMessage && replyMessage.forum_topic_created) {
+        const topicCreated = replyMessage.forum_topic_created;
+        if (topicCreated && typeof topicCreated === "object" && "name" in topicCreated) {
+          topicName = topicCreated.name;
+        }
+      } else if (replyMessage && typeof replyMessage === "object" && "reply_to_message" in replyMessage && replyMessage.reply_to_message && typeof replyMessage.reply_to_message === "object" && "forum_topic_created" in replyMessage.reply_to_message && replyMessage.reply_to_message.forum_topic_created) {
+        const topicCreated = replyMessage.reply_to_message.forum_topic_created;
+        if (topicCreated && typeof topicCreated === "object" && "name" in topicCreated) {
+          topicName = topicCreated.name;
         }
-      } catch (error) {
-        logger2.error(`Error handling Telegram entity leaving chat ${chatId}:`, error);
       }
-    });
+      const room = {
+        id: roomId,
+        name: topicName,
+        source: "telegram",
+        type: ChannelType2.GROUP,
+        channelId: `${chatId}-${threadId}`,
+        serverId: chatId,
+        worldId,
+        metadata: {
+          threadId,
+          isForumTopic: true,
+          parentChatId: chatId
+        }
+      };
+      return room;
+    } catch (error) {
+      logger2.error(
+        `Error building forum topic room: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return null;
+    }
   }
 };