@poncho-ai/messaging 0.2.9 → 0.4.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/messaging@0.2.9 build /Users/cesar/Dev/latitude/poncho-ai/packages/messaging
+> @poncho-ai/messaging@0.4.0 build /Users/cesar/Dev/latitude/poncho-ai/packages/messaging
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -7,8 +7,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 30.49 KB
-ESM ⚡️ Build success in 58ms
+ESM dist/index.js 44.99 KB
+ESM ⚡️ Build success in 69ms
 DTS Build start
-DTS ⚡️ Build success in 1611ms
-DTS dist/index.d.ts 8.98 KB
+DTS ⚡️ Build success in 1830ms
+DTS dist/index.d.ts 10.05 KB

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @poncho-ai/messaging
 
+## 0.4.0
+
+### Minor Changes
+
+- [`3216e80`](https://github.com/cesr/poncho-ai/commit/3216e8072027896dd1cc5f29b1a7b0eea9ee1ff5) Thanks [@cesr](https://github.com/cesr)! - Add `allowedUserIds` option to Telegram adapter for restricting bot access to specific users.
+
+## 0.3.0
+
+### Minor Changes
+
+- [`de28ef5`](https://github.com/cesr/poncho-ai/commit/de28ef5acceed921269d15816acd392f5208f03d) Thanks [@cesr](https://github.com/cesr)! - Add Telegram messaging adapter with private/group chat support, file attachments, /new command, and typing indicators.
+
+### Patch Changes
+
+- Updated dependencies [[`de28ef5`](https://github.com/cesr/poncho-ai/commit/de28ef5acceed921269d15816acd392f5208f03d)]:
+  - @poncho-ai/sdk@1.4.1
+
 ## 0.2.9
 
 ### Patch Changes

package/dist/index.d.ts

@@ -189,6 +189,38 @@ declare class ResendAdapter implements MessagingAdapter {
     private fetchAndDownloadAttachments;
 }
 
+interface TelegramAdapterOptions {
+    botTokenEnv?: string;
+    webhookSecretEnv?: string;
+    allowedUserIds?: number[];
+}
+declare class TelegramAdapter implements MessagingAdapter {
+    readonly platform: "telegram";
+    readonly autoReply = true;
+    readonly hasSentInCurrentRequest = false;
+    private botToken;
+    private webhookSecret;
+    private botUsername;
+    private botId;
+    private readonly botTokenEnv;
+    private readonly webhookSecretEnv;
+    private readonly allowedUserIds;
+    private handler;
+    private readonly sessionCounters;
+    private lastUpdateId;
+    constructor(options?: TelegramAdapterOptions);
+    initialize(): Promise<void>;
+    onMessage(handler: IncomingMessageHandler): void;
+    registerRoutes(router: RouteRegistrar): void;
+    sendReply(threadRef: ThreadRef, content: string, options?: {
+        files?: FileAttachment[];
+    }): Promise<void>;
+    indicateProcessing(threadRef: ThreadRef): Promise<() => Promise<void>>;
+    private handleRequest;
+    private sessionKey;
+    private extractFiles;
+}
+
 /** Extract the bare email address from a formatted string like `"Name <addr>"`. */
 declare function extractEmailAddress(formatted: string): string;
 /** Extract the display name from `"Name <addr>"`, or return `undefined`. */
@@ -241,4 +273,4 @@ declare function markdownToEmailHtml(text: string): string;
  */
 declare function matchesSenderPattern(sender: string, patterns: string[] | undefined): boolean;
 
-export { AgentBridge, type AgentBridgeOptions, type AgentRunner, type FileAttachment, type IncomingMessage, type IncomingMessageHandler, type MessagingAdapter, ResendAdapter, type ResendAdapterOptions, type RouteHandler, type RouteRegistrar, SlackAdapter, type SlackAdapterOptions, type ThreadRef, buildReplyHeaders, buildReplySubject, deriveRootMessageId, extractDisplayName, extractEmailAddress, markdownToEmailHtml, matchesSenderPattern, parseReferences, stripQuotedReply };
+export { AgentBridge, type AgentBridgeOptions, type AgentRunner, type FileAttachment, type IncomingMessage, type IncomingMessageHandler, type MessagingAdapter, ResendAdapter, type ResendAdapterOptions, type RouteHandler, type RouteRegistrar, SlackAdapter, type SlackAdapterOptions, TelegramAdapter, type TelegramAdapterOptions, type ThreadRef, buildReplyHeaders, buildReplySubject, deriveRootMessageId, extractDisplayName, extractEmailAddress, markdownToEmailHtml, matchesSenderPattern, parseReferences, stripQuotedReply };

package/dist/index.js

@@ -41,9 +41,11 @@ var AgentBridge = class {
         message.platform,
         message.threadRef
       );
-      const titleParts = [message.sender.id];
+      const platformTag = `[${message.platform.charAt(0).toUpperCase()}${message.platform.slice(1)}]`;
+      const senderLabel = message.sender.name || message.sender.id;
+      const titleParts = [platformTag, senderLabel];
       if (message.subject) titleParts.push(message.subject);
-      const title = titleParts.join(" \u2014 ") || `${message.platform} thread`;
+      const title = titleParts.join(" ") || `${message.platform} thread`;
       const conversation = await this.runner.getOrCreateConversation(
         conversationId,
         {
@@ -918,10 +920,454 @@ var ResendAdapter = class {
     return results;
   }
 };
+
+// src/adapters/telegram/verify.ts
+import { timingSafeEqual as timingSafeEqual2 } from "crypto";
+var verifyTelegramSecret = (expected, received) => {
+  if (!received) return false;
+  if (expected.length !== received.length) return false;
+  return timingSafeEqual2(Buffer.from(expected), Buffer.from(received));
+};
+
+// src/adapters/telegram/utils.ts
+var TELEGRAM_API = "https://api.telegram.org";
+var TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
+var telegramFetch = async (token, method, body) => {
+  const res = await fetch(`${TELEGRAM_API}/bot${token}/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return await res.json();
+};
+var telegramUpload = async (token, method, formData) => {
+  const res = await fetch(`${TELEGRAM_API}/bot${token}/${method}`, {
+    method: "POST",
+    body: formData
+  });
+  return await res.json();
+};
+var getMe = async (token) => {
+  const result = await telegramFetch(token, "getMe", {});
+  if (!result.ok) {
+    throw new Error(`Telegram getMe failed: ${result.description}`);
+  }
+  const user = result.result;
+  return { id: user.id, username: user.username ?? "" };
+};
+var getFile = async (token, fileId) => {
+  const result = await telegramFetch(token, "getFile", { file_id: fileId });
+  if (!result.ok) {
+    throw new Error(`Telegram getFile failed: ${result.description}`);
+  }
+  const file = result.result;
+  if (!file.file_path) {
+    throw new Error("Telegram getFile: no file_path returned");
+  }
+  return file.file_path;
+};
+var EXTENSION_MEDIA_TYPES = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  pdf: "application/pdf",
+  mp4: "video/mp4",
+  ogg: "audio/ogg",
+  mp3: "audio/mpeg"
+};
+var inferMediaType = (filePath, header) => {
+  if (header && header !== "application/octet-stream") return header;
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  if (ext && EXTENSION_MEDIA_TYPES[ext]) return EXTENSION_MEDIA_TYPES[ext];
+  return header ?? "application/octet-stream";
+};
+var downloadFile = async (token, filePath) => {
+  const url = `${TELEGRAM_API}/file/bot${token}/${filePath}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Telegram file download failed: ${res.status}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  const mediaType = inferMediaType(filePath, res.headers.get("content-type"));
+  return { data: buffer.toString("base64"), mediaType };
+};
+var sendMessage = async (token, chatId, text, opts) => {
+  const body = { chat_id: chatId, text };
+  if (opts?.reply_to_message_id) {
+    body.reply_parameters = {
+      message_id: opts.reply_to_message_id,
+      allow_sending_without_reply: true
+    };
+  }
+  if (opts?.message_thread_id) {
+    body.message_thread_id = opts.message_thread_id;
+  }
+  const result = await telegramFetch(token, "sendMessage", body);
+  if (!result.ok) {
+    throw new Error(`Telegram sendMessage failed: ${result.description}`);
+  }
+};
+var sendPhoto = async (token, chatId, photoData, opts) => {
+  const formData = new FormData();
+  formData.append("chat_id", String(chatId));
+  const blob = new Blob([Buffer.from(photoData, "base64")]);
+  formData.append("photo", blob, opts?.filename ?? "photo.jpg");
+  if (opts?.caption) formData.append("caption", opts.caption);
+  if (opts?.reply_to_message_id) {
+    formData.append(
+      "reply_parameters",
+      JSON.stringify({
+        message_id: opts.reply_to_message_id,
+        allow_sending_without_reply: true
+      })
+    );
+  }
+  if (opts?.message_thread_id) {
+    formData.append("message_thread_id", String(opts.message_thread_id));
+  }
+  const result = await telegramUpload(token, "sendPhoto", formData);
+  if (!result.ok) {
+    throw new Error(`Telegram sendPhoto failed: ${result.description}`);
+  }
+};
+var sendDocument = async (token, chatId, docData, opts) => {
+  const formData = new FormData();
+  formData.append("chat_id", String(chatId));
+  const blob = new Blob([Buffer.from(docData, "base64")], {
+    type: opts?.mediaType
+  });
+  formData.append("document", blob, opts?.filename ?? "file");
+  if (opts?.caption) formData.append("caption", opts.caption);
+  if (opts?.reply_to_message_id) {
+    formData.append(
+      "reply_parameters",
+      JSON.stringify({
+        message_id: opts.reply_to_message_id,
+        allow_sending_without_reply: true
+      })
+    );
+  }
+  if (opts?.message_thread_id) {
+    formData.append("message_thread_id", String(opts.message_thread_id));
+  }
+  const result = await telegramUpload(token, "sendDocument", formData);
+  if (!result.ok) {
+    throw new Error(`Telegram sendDocument failed: ${result.description}`);
+  }
+};
+var sendChatAction = async (token, chatId, action) => {
+  await telegramFetch(token, "sendChatAction", {
+    chat_id: chatId,
+    action
+  });
+};
+var splitMessage2 = (text) => {
+  if (text.length <= TELEGRAM_MAX_MESSAGE_LENGTH) return [text];
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= TELEGRAM_MAX_MESSAGE_LENGTH) {
+      chunks.push(remaining);
+      break;
+    }
+    let cutPoint = remaining.lastIndexOf(
+      "\n",
+      TELEGRAM_MAX_MESSAGE_LENGTH
+    );
+    if (cutPoint <= 0) {
+      cutPoint = TELEGRAM_MAX_MESSAGE_LENGTH;
+    }
+    chunks.push(remaining.slice(0, cutPoint));
+    remaining = remaining.slice(cutPoint).replace(/^\n/, "");
+  }
+  return chunks;
+};
+var isBotMentioned = (entities, botUsername, botId, text) => {
+  if (!entities || entities.length === 0) return false;
+  const lower = botUsername.toLowerCase();
+  for (const entity of entities) {
+    if (entity.type === "mention") {
+      const mentioned = text.slice(entity.offset, entity.offset + entity.length);
+      if (mentioned.toLowerCase() === `@${lower}`) return true;
+    }
+    if (entity.type === "text_mention" && entity.user?.id === botId) {
+      return true;
+    }
+  }
+  return false;
+};
+var stripMention2 = (text, entities, botUsername, botId) => {
+  if (!entities || entities.length === 0) return text.trim();
+  const lower = botUsername.toLowerCase();
+  for (const entity of entities) {
+    let match = false;
+    if (entity.type === "mention") {
+      const mentioned = text.slice(entity.offset, entity.offset + entity.length);
+      if (mentioned.toLowerCase() === `@${lower}`) match = true;
+    }
+    if (entity.type === "text_mention" && entity.user?.id === botId) {
+      match = true;
+    }
+    if (match) {
+      return (text.slice(0, entity.offset) + text.slice(entity.offset + entity.length)).trim();
+    }
+  }
+  return text.trim();
+};
+
+// src/adapters/telegram/index.ts
+var TYPING_INTERVAL_MS = 4e3;
+var NEW_COMMAND_RE = /^\/new(?:@(\S+))?$/i;
+var collectBody3 = (req) => new Promise((resolve, reject) => {
+  const chunks = [];
+  req.on("data", (chunk) => chunks.push(chunk));
+  req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+  req.on("error", reject);
+});
+var TelegramAdapter = class {
+  platform = "telegram";
+  autoReply = true;
+  hasSentInCurrentRequest = false;
+  botToken = "";
+  webhookSecret = "";
+  botUsername = "";
+  botId = 0;
+  botTokenEnv;
+  webhookSecretEnv;
+  allowedUserIds;
+  handler;
+  sessionCounters = /* @__PURE__ */ new Map();
+  lastUpdateId = 0;
+  constructor(options = {}) {
+    this.botTokenEnv = options.botTokenEnv ?? "TELEGRAM_BOT_TOKEN";
+    this.webhookSecretEnv = options.webhookSecretEnv ?? "TELEGRAM_WEBHOOK_SECRET";
+    this.allowedUserIds = options.allowedUserIds && options.allowedUserIds.length > 0 ? options.allowedUserIds : void 0;
+  }
+  // -----------------------------------------------------------------------
+  // MessagingAdapter implementation
+  // -----------------------------------------------------------------------
+  async initialize() {
+    this.botToken = process.env[this.botTokenEnv] ?? "";
+    this.webhookSecret = process.env[this.webhookSecretEnv] ?? "";
+    if (!this.botToken) {
+      throw new Error(
+        `Telegram messaging: ${this.botTokenEnv} environment variable is not set`
+      );
+    }
+    const me = await getMe(this.botToken);
+    this.botUsername = me.username;
+    this.botId = me.id;
+  }
+  onMessage(handler) {
+    this.handler = handler;
+  }
+  registerRoutes(router) {
+    router(
+      "POST",
+      "/api/messaging/telegram",
+      (req, res) => this.handleRequest(req, res)
+    );
+  }
+  async sendReply(threadRef, content, options) {
+    const chatId = threadRef.channelId;
+    const replyTo = threadRef.messageId ? Number(threadRef.messageId) : void 0;
+    if (content) {
+      const chunks = splitMessage2(content);
+      for (const chunk of chunks) {
+        await sendMessage(this.botToken, chatId, chunk, {
+          reply_to_message_id: replyTo
+        });
+      }
+    }
+    if (options?.files) {
+      for (const file of options.files) {
+        if (file.mediaType.startsWith("image/")) {
+          await sendPhoto(this.botToken, chatId, file.data, {
+            reply_to_message_id: replyTo,
+            filename: file.filename
+          });
+        } else {
+          await sendDocument(this.botToken, chatId, file.data, {
+            reply_to_message_id: replyTo,
+            filename: file.filename,
+            mediaType: file.mediaType
+          });
+        }
+      }
+    }
+  }
+  async indicateProcessing(threadRef) {
+    const chatId = threadRef.channelId;
+    await sendChatAction(this.botToken, chatId, "typing");
+    const interval = setInterval(() => {
+      void sendChatAction(this.botToken, chatId, "typing").catch(() => {
+      });
+    }, TYPING_INTERVAL_MS);
+    return async () => {
+      clearInterval(interval);
+    };
+  }
+  // -----------------------------------------------------------------------
+  // HTTP request handling
+  // -----------------------------------------------------------------------
+  async handleRequest(req, res) {
+    const rawBody = await collectBody3(req);
+    if (this.webhookSecret) {
+      const headerSecret = req.headers["x-telegram-bot-api-secret-token"];
+      if (!verifyTelegramSecret(this.webhookSecret, headerSecret)) {
+        res.writeHead(401);
+        res.end("Invalid secret");
+        return;
+      }
+    }
+    let payload;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      res.writeHead(400);
+      res.end("Invalid JSON");
+      return;
+    }
+    if (payload.update_id <= this.lastUpdateId) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    this.lastUpdateId = payload.update_id;
+    const message = payload.message;
+    if (!message) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    const text = message.text ?? message.caption ?? "";
+    const hasFiles = !!(message.photo || message.document);
+    if (!text && !hasFiles) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    if (this.allowedUserIds && message.from) {
+      if (!this.allowedUserIds.includes(message.from.id)) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+    }
+    const chatId = String(message.chat.id);
+    const chatType = message.chat.type;
+    const isGroup = chatType === "group" || chatType === "supergroup";
+    const entities = message.entities ?? message.caption_entities;
+    const newMatch = text.match(NEW_COMMAND_RE);
+    if (newMatch) {
+      const suffix = newMatch[1];
+      if (isGroup && suffix && suffix.toLowerCase() !== this.botUsername.toLowerCase()) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+      const key2 = this.sessionKey(message);
+      const current = this.sessionCounters.get(key2) ?? 0;
+      this.sessionCounters.set(key2, current + 1);
+      res.writeHead(200);
+      res.end();
+      await sendMessage(
+        this.botToken,
+        chatId,
+        "Conversation reset. Send a new message to start fresh.",
+        {
+          reply_to_message_id: message.message_id,
+          message_thread_id: message.message_thread_id
+        }
+      );
+      return;
+    }
+    if (isGroup) {
+      if (!isBotMentioned(entities, this.botUsername, this.botId, text)) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+    }
+    const cleanText = isGroup ? stripMention2(text, entities, this.botUsername, this.botId) : text;
+    if (!cleanText && !hasFiles) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    res.writeHead(200);
+    res.end();
+    if (!this.handler) return;
+    const files = await this.extractFiles(message);
+    const key = this.sessionKey(message);
+    const session = this.sessionCounters.get(key) ?? 0;
+    const topicId = message.message_thread_id;
+    const platformThreadId = topicId ? `${chatId}:${topicId}:${session}` : `${chatId}:${session}`;
+    const userId = String(message.from?.id ?? "unknown");
+    const userName = [message.from?.first_name, message.from?.last_name].filter(Boolean).join(" ") || void 0;
+    const ponchoMessage = {
+      text: cleanText,
+      files: files.length > 0 ? files : void 0,
+      threadRef: {
+        platformThreadId,
+        channelId: chatId,
+        messageId: String(message.message_id)
+      },
+      sender: { id: userId, name: userName },
+      platform: "telegram",
+      raw: message
+    };
+    void this.handler(ponchoMessage).catch((err) => {
+      console.error(
+        "[telegram-adapter] unhandled message handler error",
+        err
+      );
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Helpers
+  // -----------------------------------------------------------------------
+  sessionKey(message) {
+    const chatId = String(message.chat.id);
+    return message.message_thread_id ? `${chatId}:${message.message_thread_id}` : chatId;
+  }
+  async extractFiles(message) {
+    const files = [];
+    try {
+      if (message.photo && message.photo.length > 0) {
+        const largest = message.photo[message.photo.length - 1];
+        const filePath = await getFile(this.botToken, largest.file_id);
+        const { data } = await downloadFile(this.botToken, filePath);
+        files.push({ data, mediaType: "image/jpeg", filename: "photo.jpg" });
+      }
+      if (message.document) {
+        const filePath = await getFile(
+          this.botToken,
+          message.document.file_id
+        );
+        const downloaded = await downloadFile(this.botToken, filePath);
+        files.push({
+          data: downloaded.data,
+          mediaType: message.document.mime_type ?? downloaded.mediaType,
+          filename: message.document.file_name
+        });
+      }
+    } catch (err) {
+      console.warn(
+        "[telegram-adapter] failed to download file:",
+        err instanceof Error ? err.message : err
+      );
+    }
+    return files;
+  }
+};
 export {
   AgentBridge,
   ResendAdapter,
   SlackAdapter,
+  TelegramAdapter,
   buildReplyHeaders,
   buildReplySubject,
   deriveRootMessageId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/messaging",
-  "version": "0.2.9",
+  "version": "0.4.0",
   "description": "Messaging platform adapters for Poncho agents (Slack, Telegram, etc.)",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     }
   },
   "dependencies": {
-    "@poncho-ai/sdk": "1.4.0"
+    "@poncho-ai/sdk": "1.4.1"
   },
   "peerDependencies": {
     "resend": ">=4.0.0"
@@ -40,6 +40,7 @@
     "agent",
     "messaging",
     "slack",
+    "telegram",
     "email",
     "resend"
   ],

package/src/adapters/telegram/index.ts

@@ -0,0 +1,359 @@
+import type http from "node:http";
+import type {
+  FileAttachment,
+  IncomingMessage as PonchoIncomingMessage,
+  IncomingMessageHandler,
+  MessagingAdapter,
+  RouteRegistrar,
+  ThreadRef,
+} from "../../types.js";
+import { verifyTelegramSecret } from "./verify.js";
+import {
+  type TelegramMessage,
+  type TelegramUpdate,
+  downloadFile,
+  getFile,
+  getMe,
+  isBotMentioned,
+  sendChatAction,
+  sendDocument,
+  sendMessage,
+  sendPhoto,
+  splitMessage,
+  stripMention,
+} from "./utils.js";
+
+const TYPING_INTERVAL_MS = 4_000;
+const NEW_COMMAND_RE = /^\/new(?:@(\S+))?$/i;
+
+export interface TelegramAdapterOptions {
+  botTokenEnv?: string;
+  webhookSecretEnv?: string;
+  allowedUserIds?: number[];
+}
+
+const collectBody = (req: http.IncomingMessage): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+
+export class TelegramAdapter implements MessagingAdapter {
+  readonly platform = "telegram" as const;
+  readonly autoReply = true;
+  readonly hasSentInCurrentRequest = false;
+
+  private botToken = "";
+  private webhookSecret = "";
+  private botUsername = "";
+  private botId = 0;
+  private readonly botTokenEnv: string;
+  private readonly webhookSecretEnv: string;
+  private readonly allowedUserIds: number[] | undefined;
+  private handler: IncomingMessageHandler | undefined;
+  private readonly sessionCounters = new Map<string, number>();
+  private lastUpdateId = 0;
+
+  constructor(options: TelegramAdapterOptions = {}) {
+    this.botTokenEnv = options.botTokenEnv ?? "TELEGRAM_BOT_TOKEN";
+    this.webhookSecretEnv =
+      options.webhookSecretEnv ?? "TELEGRAM_WEBHOOK_SECRET";
+    this.allowedUserIds =
+      options.allowedUserIds && options.allowedUserIds.length > 0
+        ? options.allowedUserIds
+        : undefined;
+  }
+
+  // -----------------------------------------------------------------------
+  // MessagingAdapter implementation
+  // -----------------------------------------------------------------------
+
+  async initialize(): Promise<void> {
+    this.botToken = process.env[this.botTokenEnv] ?? "";
+    this.webhookSecret = process.env[this.webhookSecretEnv] ?? "";
+
+    if (!this.botToken) {
+      throw new Error(
+        `Telegram messaging: ${this.botTokenEnv} environment variable is not set`,
+      );
+    }
+
+    const me = await getMe(this.botToken);
+    this.botUsername = me.username;
+    this.botId = me.id;
+  }
+
+  onMessage(handler: IncomingMessageHandler): void {
+    this.handler = handler;
+  }
+
+  registerRoutes(router: RouteRegistrar): void {
+    router("POST", "/api/messaging/telegram", (req, res) =>
+      this.handleRequest(req, res),
+    );
+  }
+
+  async sendReply(
+    threadRef: ThreadRef,
+    content: string,
+    options?: { files?: FileAttachment[] },
+  ): Promise<void> {
+    const chatId = threadRef.channelId;
+    const replyTo = threadRef.messageId
+      ? Number(threadRef.messageId)
+      : undefined;
+
+    if (content) {
+      const chunks = splitMessage(content);
+      for (const chunk of chunks) {
+        await sendMessage(this.botToken, chatId, chunk, {
+          reply_to_message_id: replyTo,
+        });
+      }
+    }
+
+    if (options?.files) {
+      for (const file of options.files) {
+        if (file.mediaType.startsWith("image/")) {
+          await sendPhoto(this.botToken, chatId, file.data, {
+            reply_to_message_id: replyTo,
+            filename: file.filename,
+          });
+        } else {
+          await sendDocument(this.botToken, chatId, file.data, {
+            reply_to_message_id: replyTo,
+            filename: file.filename,
+            mediaType: file.mediaType,
+          });
+        }
+      }
+    }
+  }
+
+  async indicateProcessing(
+    threadRef: ThreadRef,
+  ): Promise<() => Promise<void>> {
+    const chatId = threadRef.channelId;
+
+    await sendChatAction(this.botToken, chatId, "typing");
+
+    const interval = setInterval(() => {
+      void sendChatAction(this.botToken, chatId, "typing").catch(() => {});
+    }, TYPING_INTERVAL_MS);
+
+    return async () => {
+      clearInterval(interval);
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // HTTP request handling
+  // -----------------------------------------------------------------------
+
+  private async handleRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ): Promise<void> {
+    const rawBody = await collectBody(req);
+
+    // -- Secret verification ----------------------------------------------
+    if (this.webhookSecret) {
+      const headerSecret = req.headers[
+        "x-telegram-bot-api-secret-token"
+      ] as string | undefined;
+      if (!verifyTelegramSecret(this.webhookSecret, headerSecret)) {
+        res.writeHead(401);
+        res.end("Invalid secret");
+        return;
+      }
+    }
+
+    let payload: TelegramUpdate;
+    try {
+      payload = JSON.parse(rawBody) as TelegramUpdate;
+    } catch {
+      res.writeHead(400);
+      res.end("Invalid JSON");
+      return;
+    }
+
+    // -- Update deduplication -----------------------------------------------
+    if (payload.update_id <= this.lastUpdateId) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    this.lastUpdateId = payload.update_id;
+
+    const message = payload.message;
+    if (!message) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    const text = message.text ?? message.caption ?? "";
+    const hasFiles = !!(message.photo || message.document);
+
+    if (!text && !hasFiles) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    // -- User allowlist -----------------------------------------------------
+    if (this.allowedUserIds && message.from) {
+      if (!this.allowedUserIds.includes(message.from.id)) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+    }
+
+    const chatId = String(message.chat.id);
+    const chatType = message.chat.type;
+    const isGroup = chatType === "group" || chatType === "supergroup";
+    const entities = message.entities ?? message.caption_entities;
+
+    // -- /new command -----------------------------------------------------
+    const newMatch = text.match(NEW_COMMAND_RE);
+    if (newMatch) {
+      const suffix = newMatch[1];
+      if (
+        isGroup &&
+        suffix &&
+        suffix.toLowerCase() !== this.botUsername.toLowerCase()
+      ) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+
+      const key = this.sessionKey(message);
+      const current = this.sessionCounters.get(key) ?? 0;
+      this.sessionCounters.set(key, current + 1);
+
+      res.writeHead(200);
+      res.end();
+
+      await sendMessage(
+        this.botToken,
+        chatId,
+        "Conversation reset. Send a new message to start fresh.",
+        {
+          reply_to_message_id: message.message_id,
+          message_thread_id: message.message_thread_id,
+        },
+      );
+      return;
+    }
+
+    // -- Group mention filter ---------------------------------------------
+    if (isGroup) {
+      if (!isBotMentioned(entities, this.botUsername, this.botId, text)) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+    }
+
+    const cleanText = isGroup
+      ? stripMention(text, entities, this.botUsername, this.botId)
+      : text;
+
+    if (!cleanText && !hasFiles) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    // Acknowledge immediately so Telegram doesn't retry.
+    res.writeHead(200);
+    res.end();
+
+    if (!this.handler) return;
+
+    // -- File extraction --------------------------------------------------
+    const files = await this.extractFiles(message);
+
+    // -- Build thread ref -------------------------------------------------
+    const key = this.sessionKey(message);
+    const session = this.sessionCounters.get(key) ?? 0;
+    const topicId = message.message_thread_id;
+    const platformThreadId = topicId
+      ? `${chatId}:${topicId}:${session}`
+      : `${chatId}:${session}`;
+
+    const userId = String(message.from?.id ?? "unknown");
+    const userName =
+      [message.from?.first_name, message.from?.last_name]
+        .filter(Boolean)
+        .join(" ") || undefined;
+
+    const ponchoMessage: PonchoIncomingMessage = {
+      text: cleanText,
+      files: files.length > 0 ? files : undefined,
+      threadRef: {
+        platformThreadId,
+        channelId: chatId,
+        messageId: String(message.message_id),
+      },
+      sender: { id: userId, name: userName },
+      platform: "telegram",
+      raw: message,
+    };
+
+    void this.handler(ponchoMessage).catch((err) => {
+      console.error(
+        "[telegram-adapter] unhandled message handler error",
+        err,
+      );
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Helpers
+  // -----------------------------------------------------------------------
+
+  private sessionKey(message: TelegramMessage): string {
+    const chatId = String(message.chat.id);
+    return message.message_thread_id
+      ? `${chatId}:${message.message_thread_id}`
+      : chatId;
+  }
+
+  private async extractFiles(
+    message: TelegramMessage,
+  ): Promise<FileAttachment[]> {
+    const files: FileAttachment[] = [];
+    try {
+      if (message.photo && message.photo.length > 0) {
+        const largest = message.photo[message.photo.length - 1]!;
+        const filePath = await getFile(this.botToken, largest.file_id);
+        const { data } = await downloadFile(this.botToken, filePath);
+        files.push({ data, mediaType: "image/jpeg", filename: "photo.jpg" });
+      }
+
+      if (message.document) {
+        const filePath = await getFile(
+          this.botToken,
+          message.document.file_id,
+        );
+        const downloaded = await downloadFile(this.botToken, filePath);
+        files.push({
+          data: downloaded.data,
+          mediaType: message.document.mime_type ?? downloaded.mediaType,
+          filename: message.document.file_name,
+        });
+      }
+    } catch (err) {
+      console.warn(
+        "[telegram-adapter] failed to download file:",
+        err instanceof Error ? err.message : err,
+      );
+    }
+    return files;
+  }
+}

package/src/adapters/telegram/utils.ts

@@ -0,0 +1,369 @@
+const TELEGRAM_API = "https://api.telegram.org";
+const TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
+
+// ---------------------------------------------------------------------------
+// Telegram Bot API object types (subset used by the adapter)
+// ---------------------------------------------------------------------------
+
+export interface TelegramEntity {
+  type: string;
+  offset: number;
+  length: number;
+  user?: { id: number; username?: string };
+}
+
+export interface TelegramUser {
+  id: number;
+  is_bot: boolean;
+  first_name: string;
+  last_name?: string;
+  username?: string;
+}
+
+export interface TelegramChat {
+  id: number;
+  type: "private" | "group" | "supergroup" | "channel";
+}
+
+export interface TelegramPhotoSize {
+  file_id: string;
+  file_unique_id: string;
+  width: number;
+  height: number;
+  file_size?: number;
+}
+
+export interface TelegramDocument {
+  file_id: string;
+  file_unique_id: string;
+  file_name?: string;
+  mime_type?: string;
+  file_size?: number;
+}
+
+export interface TelegramMessage {
+  message_id: number;
+  from?: TelegramUser;
+  chat: TelegramChat;
+  date: number;
+  text?: string;
+  caption?: string;
+  entities?: TelegramEntity[];
+  caption_entities?: TelegramEntity[];
+  photo?: TelegramPhotoSize[];
+  document?: TelegramDocument;
+  message_thread_id?: number;
+}
+
+export interface TelegramUpdate {
+  update_id: number;
+  message?: TelegramMessage;
+}
+
+// ---------------------------------------------------------------------------
+// Low-level fetch helpers
+// ---------------------------------------------------------------------------
+
+interface TelegramApiResult {
+  ok: boolean;
+  result?: unknown;
+  description?: string;
+}
+
+const telegramFetch = async (
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+): Promise<TelegramApiResult> => {
+  const res = await fetch(`${TELEGRAM_API}/bot${token}/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return (await res.json()) as TelegramApiResult;
+};
+
+const telegramUpload = async (
+  token: string,
+  method: string,
+  formData: FormData,
+): Promise<TelegramApiResult> => {
+  const res = await fetch(`${TELEGRAM_API}/bot${token}/${method}`, {
+    method: "POST",
+    body: formData,
+  });
+  return (await res.json()) as TelegramApiResult;
+};
+
+// ---------------------------------------------------------------------------
+// Bot info
+// ---------------------------------------------------------------------------
+
+export const getMe = async (
+  token: string,
+): Promise<{ id: number; username: string }> => {
+  const result = await telegramFetch(token, "getMe", {});
+  if (!result.ok) {
+    throw new Error(`Telegram getMe failed: ${result.description}`);
+  }
+  const user = result.result as TelegramUser;
+  return { id: user.id, username: user.username ?? "" };
+};
+
+// ---------------------------------------------------------------------------
+// File download
+// ---------------------------------------------------------------------------
+
+export const getFile = async (
+  token: string,
+  fileId: string,
+): Promise<string> => {
+  const result = await telegramFetch(token, "getFile", { file_id: fileId });
+  if (!result.ok) {
+    throw new Error(`Telegram getFile failed: ${result.description}`);
+  }
+  const file = result.result as { file_id: string; file_path?: string };
+  if (!file.file_path) {
+    throw new Error("Telegram getFile: no file_path returned");
+  }
+  return file.file_path;
+};
+
+const EXTENSION_MEDIA_TYPES: Record<string, string> = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  pdf: "application/pdf",
+  mp4: "video/mp4",
+  ogg: "audio/ogg",
+  mp3: "audio/mpeg",
+};
+
+const inferMediaType = (filePath: string, header: string | null): string => {
+  if (header && header !== "application/octet-stream") return header;
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  if (ext && EXTENSION_MEDIA_TYPES[ext]) return EXTENSION_MEDIA_TYPES[ext];
+  return header ?? "application/octet-stream";
+};
+
+export const downloadFile = async (
+  token: string,
+  filePath: string,
+): Promise<{ data: string; mediaType: string }> => {
+  const url = `${TELEGRAM_API}/file/bot${token}/${filePath}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Telegram file download failed: ${res.status}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  const mediaType = inferMediaType(filePath, res.headers.get("content-type"));
+  return { data: buffer.toString("base64"), mediaType };
+};
+
+// ---------------------------------------------------------------------------
+// Sending messages
+// ---------------------------------------------------------------------------
+
+export const sendMessage = async (
+  token: string,
+  chatId: number | string,
+  text: string,
+  opts?: { reply_to_message_id?: number; message_thread_id?: number },
+): Promise<void> => {
+  const body: Record<string, unknown> = { chat_id: chatId, text };
+  if (opts?.reply_to_message_id) {
+    body.reply_parameters = {
+      message_id: opts.reply_to_message_id,
+      allow_sending_without_reply: true,
+    };
+  }
+  if (opts?.message_thread_id) {
+    body.message_thread_id = opts.message_thread_id;
+  }
+  const result = await telegramFetch(token, "sendMessage", body);
+  if (!result.ok) {
+    throw new Error(`Telegram sendMessage failed: ${result.description}`);
+  }
+};
+
+export const sendPhoto = async (
+  token: string,
+  chatId: number | string,
+  photoData: string,
+  opts?: {
+    caption?: string;
+    reply_to_message_id?: number;
+    message_thread_id?: number;
+    filename?: string;
+  },
+): Promise<void> => {
+  const formData = new FormData();
+  formData.append("chat_id", String(chatId));
+  const blob = new Blob([Buffer.from(photoData, "base64")]);
+  formData.append("photo", blob, opts?.filename ?? "photo.jpg");
+  if (opts?.caption) formData.append("caption", opts.caption);
+  if (opts?.reply_to_message_id) {
+    formData.append(
+      "reply_parameters",
+      JSON.stringify({
+        message_id: opts.reply_to_message_id,
+        allow_sending_without_reply: true,
+      }),
+    );
+  }
+  if (opts?.message_thread_id) {
+    formData.append("message_thread_id", String(opts.message_thread_id));
+  }
+  const result = await telegramUpload(token, "sendPhoto", formData);
+  if (!result.ok) {
+    throw new Error(`Telegram sendPhoto failed: ${result.description}`);
+  }
+};
+
+export const sendDocument = async (
+  token: string,
+  chatId: number | string,
+  docData: string,
+  opts?: {
+    caption?: string;
+    reply_to_message_id?: number;
+    message_thread_id?: number;
+    filename?: string;
+    mediaType?: string;
+  },
+): Promise<void> => {
+  const formData = new FormData();
+  formData.append("chat_id", String(chatId));
+  const blob = new Blob([Buffer.from(docData, "base64")], {
+    type: opts?.mediaType,
+  });
+  formData.append("document", blob, opts?.filename ?? "file");
+  if (opts?.caption) formData.append("caption", opts.caption);
+  if (opts?.reply_to_message_id) {
+    formData.append(
+      "reply_parameters",
+      JSON.stringify({
+        message_id: opts.reply_to_message_id,
+        allow_sending_without_reply: true,
+      }),
+    );
+  }
+  if (opts?.message_thread_id) {
+    formData.append("message_thread_id", String(opts.message_thread_id));
+  }
+  const result = await telegramUpload(token, "sendDocument", formData);
+  if (!result.ok) {
+    throw new Error(`Telegram sendDocument failed: ${result.description}`);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Typing indicator
+// ---------------------------------------------------------------------------
+
+export const sendChatAction = async (
+  token: string,
+  chatId: number | string,
+  action: string,
+): Promise<void> => {
+  await telegramFetch(token, "sendChatAction", {
+    chat_id: chatId,
+    action,
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Message splitting (same pattern as Slack, adapted for 4096 limit)
+// ---------------------------------------------------------------------------
+
+export const splitMessage = (text: string): string[] => {
+  if (text.length <= TELEGRAM_MAX_MESSAGE_LENGTH) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= TELEGRAM_MAX_MESSAGE_LENGTH) {
+      chunks.push(remaining);
+      break;
+    }
+
+    let cutPoint = remaining.lastIndexOf(
+      "\n",
+      TELEGRAM_MAX_MESSAGE_LENGTH,
+    );
+    if (cutPoint <= 0) {
+      cutPoint = TELEGRAM_MAX_MESSAGE_LENGTH;
+    }
+
+    chunks.push(remaining.slice(0, cutPoint));
+    remaining = remaining.slice(cutPoint).replace(/^\n/, "");
+  }
+
+  return chunks;
+};
+
+// ---------------------------------------------------------------------------
+// Mention detection & stripping
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the bot is mentioned in a message's entities.
+ * Works with both `@username` mentions and `text_mention` entities.
+ */
+export const isBotMentioned = (
+  entities: TelegramEntity[] | undefined,
+  botUsername: string,
+  botId: number,
+  text: string,
+): boolean => {
+  if (!entities || entities.length === 0) return false;
+  const lower = botUsername.toLowerCase();
+
+  for (const entity of entities) {
+    if (entity.type === "mention") {
+      const mentioned = text.slice(entity.offset, entity.offset + entity.length);
+      if (mentioned.toLowerCase() === `@${lower}`) return true;
+    }
+    if (entity.type === "text_mention" && entity.user?.id === botId) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * Remove the first bot mention from the message text, using entity
+ * offsets for accuracy. Falls back to regex if no entity matches.
+ */
+export const stripMention = (
+  text: string,
+  entities: TelegramEntity[] | undefined,
+  botUsername: string,
+  botId: number,
+): string => {
+  if (!entities || entities.length === 0) return text.trim();
+  const lower = botUsername.toLowerCase();
+
+  for (const entity of entities) {
+    let match = false;
+    if (entity.type === "mention") {
+      const mentioned = text.slice(entity.offset, entity.offset + entity.length);
+      if (mentioned.toLowerCase() === `@${lower}`) match = true;
+    }
+    if (entity.type === "text_mention" && entity.user?.id === botId) {
+      match = true;
+    }
+    if (match) {
+      return (
+        text.slice(0, entity.offset) +
+        text.slice(entity.offset + entity.length)
+      ).trim();
+    }
+  }
+
+  return text.trim();
+};

package/src/adapters/telegram/verify.ts

@@ -0,0 +1,18 @@
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Verify the Telegram webhook secret token.
+ *
+ * When registering the webhook via `setWebhook`, a `secret_token` can be
+ * provided. Telegram then sends it in the `X-Telegram-Bot-Api-Secret-Token`
+ * header on every update. This function compares the expected and received
+ * values using timing-safe equality.
+ */
+export const verifyTelegramSecret = (
+  expected: string,
+  received: string | undefined,
+): boolean => {
+  if (!received) return false;
+  if (expected.length !== received.length) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
+};

package/src/bridge.ts

@@ -65,9 +65,11 @@ export class AgentBridge {
         message.threadRef,
       );
 
-      const titleParts = [message.sender.id];
+      const platformTag = `[${message.platform.charAt(0).toUpperCase()}${message.platform.slice(1)}]`;
+      const senderLabel = message.sender.name || message.sender.id;
+      const titleParts = [platformTag, senderLabel];
       if (message.subject) titleParts.push(message.subject);
-      const title = titleParts.join(" — ") || `${message.platform} thread`;
+      const title = titleParts.join(" ") || `${message.platform} thread`;
 
       const conversation = await this.runner.getOrCreateConversation(
         conversationId,

package/src/index.ts

@@ -15,6 +15,8 @@ export { SlackAdapter } from "./adapters/slack/index.js";
 export type { SlackAdapterOptions } from "./adapters/slack/index.js";
 export { ResendAdapter } from "./adapters/resend/index.js";
 export type { ResendAdapterOptions } from "./adapters/resend/index.js";
+export { TelegramAdapter } from "./adapters/telegram/index.js";
+export type { TelegramAdapterOptions } from "./adapters/telegram/index.js";
 
 export {
   buildReplyHeaders,