bloby-bot 0.60.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "releaseNotes": [
     "1. Fix: image (and audio) attachments now render in chat again — /api/files is fetched with the auth token instead of a raw <img> src that 401'd after the endpoint hardening",
     "2. Affects chat thumbnails, the image lightbox, voice-note playback, and agent image cards",
@@ -52,11 +52,11 @@
     "sync:pi-models": "tsx scripts/sync-pi-models.ts"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.154",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.169",
     "@anthropic-ai/sdk": "^0.100.0",
     "@clack/prompts": "^1.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/codex": "^0.135.0",
+    "@openai/codex": "^0.138.0",
     "@streamdown/code": "^1.1.1",
     "@tailwindcss/vite": "^4.2.0",
     "@vitejs/plugin-react": "^6.0.1",
@@ -98,6 +98,7 @@
     "@types/qrcode": "^1.5.5",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@types/web-push": "^3.6.4",
     "@types/ws": "^8.18.1",
     "concurrently": "^9.2.1",
     "typescript": "^5.9.3"

package/shared/config.ts

@@ -25,6 +25,30 @@ export interface AlexaChannelConfig {
   sharedSecret?: string;
 }
 
+export interface TelegramChannelConfig {
+  enabled: boolean;
+  /** Same semantics as WhatsApp: 'channel' = just talk to me (owner DM only), 'business' = admin/customer,
+   *  'assistant' = personal assistant in conversations. */
+  mode: 'channel' | 'business' | 'assistant';
+  /** Telegram NUMERIC user IDs (not phone numbers) with admin access — business mode only. */
+  admins?: string[];
+  /** Active skill for customer-facing mode (folder name in workspace/skills/). */
+  skill?: string;
+  /** Opt-in: process messages in group chats (default false). Channel mode ignores this. */
+  allowGroups?: boolean;
+  /** Assistant mode only — see ChannelConfig.allowOthersToTrigger. DANGEROUS when true. */
+  allowOthersToTrigger?: boolean;
+  /** The bot's own access token (Bot API). Provisioned via the relay manager bot (Telegram
+   *  "Managed Bots") at pairing, or supplied directly (BYO @BotFather). Held locally — the Bloby
+   *  long-polls Telegram DIRECTLY with this token; the relay is NOT in the message path. */
+  botToken?: string;
+  /** The bot's @username (no @). For display + deep links. */
+  botUsername?: string;
+  /** Telegram user_id of the human who created/owns the bot. Treated as the admin/"self" identity:
+   *  in channel mode only this user's 1:1 DMs reach the agent. */
+  ownerUserId?: string;
+}
+
 export interface BotConfig {
   port: number;
   username: string;
@@ -52,6 +76,7 @@ export interface BotConfig {
   channels?: {
     whatsapp?: ChannelConfig;
     alexa?: AlexaChannelConfig;
+    telegram?: TelegramChannelConfig;
   };
   tunnelUrl?: string;
 }

package/supervisor/channels/manager.ts

@@ -20,12 +20,13 @@
 
 import fs from 'fs';
 import path from 'path';
-import { loadConfig } from '../../shared/config.js';
+import { loadConfig, saveConfig } from '../../shared/config.js';
 import { WORKSPACE_DIR } from '../../shared/paths.js';
 import { log } from '../../shared/logger.js';
 import { startBlobyAgentQuery, startConversation, pushMessage, hasConversation, type RecentMessage } from '../bloby-agent.js';
 import { WhatsAppChannel } from './whatsapp.js';
 import { AlexaChannel } from './alexa.js';
+import { TelegramChannel, type TelegramInbound } from './telegram.js';
 import type { ChannelConfig, ChannelProvider, ChannelStatus, ChannelType, InboundMessage, InboundMessageAttachment, RoutingTarget, SenderRole } from './types.js';
 import type { AgentAttachment } from '../bloby-agent.js';
 import { saveAttachment, type SavedFile } from '../file-saver.js';
@@ -157,6 +158,63 @@ export class ChannelManager {
       this.providers.set('alexa', alexa);
       await alexa.connect();
     }
+
+    // Telegram — only when a child bot token has been provisioned (via the relay
+    // manager bot) or supplied (BYO @BotFather). The provider long-polls Telegram
+    // directly; the relay is out of the message path from here on.
+    if (channelConfigs?.telegram?.enabled && channelConfigs.telegram.botToken && !this.providers.has('telegram')) {
+      log.info('[channels] Initializing Telegram channel...');
+      const telegram = new TelegramChannel(
+        (msg) => this.handleTelegramMessage(msg),
+        (status) => this.handleStatusChange(status),
+        (audioBase64) => this.transcribeAudio(audioBase64),
+      );
+      this.providers.set('telegram', telegram);
+      try {
+        await telegram.connect();
+      } catch (err: any) {
+        log.warn(`[channels] Telegram connect failed: ${err.message}`);
+      }
+    }
+  }
+
+  /** Map a Telegram inbound onto the shared channel pipeline.
+   *
+   *  Telegram has no "self-chat" like WhatsApp. Instead the bot OWNER (the human who created the
+   *  bot) is the "self" identity: fromMe=true and (in 1:1) isSelfChat=true. This makes channel mode
+   *  respond only to the owner's DMs and makes assistant-mode `@botname` triggers work — reusing the
+   *  exact mode/debounce/role gating in handleInboundMessage with no special-casing. */
+  private handleTelegramMessage(msg: TelegramInbound) {
+    let ownerUserId = loadConfig().channels?.telegram?.ownerUserId;
+    // Trust-on-first-use: if provisioning didn't capture the creator's id, adopt the first
+    // person to DM this freshly-minted private bot as the owner (its @username is random, so in
+    // practice only the owner knows it). Guarantees channel mode never silently ignores its owner.
+    if (!ownerUserId && !msg.isGroup && msg.fromUserId) {
+      ownerUserId = msg.fromUserId;
+      const cfg = loadConfig();
+      if (cfg.channels?.telegram) {
+        cfg.channels.telegram.ownerUserId = ownerUserId;
+        saveConfig(cfg);
+        log.info(`[channels] Telegram owner adopted (trust-on-first-use): userId=${ownerUserId}`);
+      }
+    }
+    const isOwner = !!ownerUserId && msg.fromUserId === String(ownerUserId);
+    const attachments = msg.images?.map((img) => ({ type: 'image' as const, mediaType: img.mediaType, data: img.data }));
+    // Sanitize the attacker-controlled display name so it can't fake a `[Telegram | … | admin]`
+    // context tag or inject newlines into the agent's context.
+    const safeName = msg.senderName ? msg.senderName.replace(/[\[\]|\r\n]/g, ' ').slice(0, 64).trim() || undefined : undefined;
+    this.handleInboundMessage(
+      'telegram',
+      msg.fromUserId,
+      safeName,
+      msg.text,
+      isOwner,                  // fromMe — the owner is treated as "me"
+      isOwner && !msg.isGroup,  // isSelfChat — owner's 1:1 DM is the personal channel
+      msg.chatId,               // chatJid (reply target)
+      msg.isGroup,
+      attachments,
+      undefined,                // inboundKey — Baileys-only (reactions not in Telegram v1)
+    );
   }
 
   /** Start WhatsApp connection (triggers QR flow if no credentials) */
@@ -222,8 +280,8 @@ export class ChannelManager {
       await provider.sendMessage(to, processed);
     }
 
-    // Send images natively via WhatsApp
-    if (images.length > 0 && provider instanceof WhatsAppChannel) {
+    // Send images natively via WhatsApp / Telegram (both expose sendImage)
+    if (images.length > 0 && (provider instanceof WhatsAppChannel || provider instanceof TelegramChannel)) {
       for (const img of images) {
         try {
           const resolved = this.resolveMediaFile(img.src);
@@ -233,7 +291,7 @@ export class ChannelManager {
             log.warn(`[channels] Image file not found in any location: ${img.src}`);
           }
         } catch (err: any) {
-          log.warn(`[channels] Failed to send image via WhatsApp: ${err.message}`);
+          log.warn(`[channels] Failed to send image via ${channel}: ${err.message}`);
         }
       }
     }
@@ -257,6 +315,16 @@ export class ChannelManager {
 
     const mimetype = media.mimetype || resolved.mimetype;
 
+    // Telegram supports images via the provider's sendImage (other media types not wired in v1).
+    if (provider instanceof TelegramChannel) {
+      if (media.type === 'image') {
+        await provider.sendImage(to, resolved.buffer, caption, mimetype);
+      } else {
+        throw new Error(`Telegram supports image media only (got ${media.type})`);
+      }
+      return;
+    }
+
     if (!(provider instanceof WhatsAppChannel)) {
       throw new Error(`Channel ${channel} does not support media`);
     }
@@ -361,6 +429,11 @@ export class ChannelManager {
     return `🤖 *${botName}:*\n\n${text}`;
   }
 
+  /** Human-facing channel label used in the `[Channel | ...]` context tag the agent sees. */
+  private channelLabel(channel: ChannelType): string {
+    return channel === 'telegram' ? 'Telegram' : channel === 'alexa' ? 'Alexa' : 'WhatsApp';
+  }
+
   /** Allocate per-conv state for WhatsApp text streaming. Both the orchestrator
    * (chat UI websocket) and the manager's own admin handler create one of these
    * and feed each agent stream event through `routeWaStreamEvent` below. */
@@ -566,6 +639,14 @@ export class ChannelManager {
   /** Deliver a streamed chunk to the WhatsApp side of a routing target.
    *  No-op when the target has no `waSendTo` (e.g., chat-UI turn with WA disconnected). */
   private sendStreamChunk(target: RoutingTarget | undefined, text: string, botName: string): void {
+    // Telegram: the bot is its own contact, so no "🤖 Bot:" prefix — send the agent's text as-is.
+    if (target?.surface === 'telegram') {
+      if (!target.telegramChatId) return;
+      this.sendMessage('telegram', target.telegramChatId, text).catch((err) =>
+        log.warn(`[channels] Telegram send failed (${target.telegramChatId}): ${err.message}`),
+      );
+      return;
+    }
     if (!target?.waSendTo) return;
     // Prefix only when the trigger came from WhatsApp AND it isn't the user's own self-chat —
     // the user doesn't need to see "🤖 Bot:" before their own bot's reply in their own chat.
@@ -585,7 +666,11 @@ export class ChannelManager {
   /** Get the channel config, re-reading from disk each time */
   private getChannelConfig(channel: ChannelType): ChannelConfig | undefined {
     const config = loadConfig();
-    return config.channels?.[channel];
+    // Only ever called for the ChannelConfig-shaped providers (whatsapp/telegram),
+    // both of which carry `mode`. Alexa's config has a different shape (no `mode`)
+    // and is handled via its own handleAlexaInbound path, so narrowing the stored
+    // channel union to ChannelConfig here is safe.
+    return config.channels?.[channel] as ChannelConfig | undefined;
   }
 
   /** Robust "is this the account owner's own self-chat?" check.
@@ -803,7 +888,7 @@ export class ChannelManager {
     }
 
     // Business mode — incoming message. Role is resolved against the actual sender JID (not the chat JID).
-    const role = this.resolveBusinessRole(channelConfig, sender);
+    const role = this.resolveBusinessRole(channelConfig, sender, channel);
 
     const message: InboundMessage = {
       channel,
@@ -827,8 +912,14 @@ export class ChannelManager {
   }
 
   /** Resolve role in business mode — check admins array */
-  private resolveBusinessRole(config: ChannelConfig, sender: string): SenderRole {
+  private resolveBusinessRole(config: ChannelConfig, sender: string, channel: ChannelType): SenderRole {
     if (config.admins?.length) {
+      // Telegram admins are EXACT numeric user ids — no suffix/country-code fuzz (that's
+      // phone-number tolerance and would wrongly grant admin on a numeric-id suffix collision).
+      if (channel === 'telegram') {
+        const senderId = sender.replace(/@.*/, '').trim();
+        return config.admins.some((a) => String(a).trim() === senderId) ? 'admin' : 'customer';
+      }
       const senderPhone = sender.replace(/@.*/, '').replace(/[^0-9]/g, '');
       for (const admin of config.admins) {
         const adminPhone = admin.replace(/[^0-9]/g, '');
@@ -853,7 +944,7 @@ export class ChannelManager {
       if (ctx.conversationId) {
         convId = ctx.conversationId;
       } else {
-        const conv = await workerApi('/api/conversations', 'POST', { title: 'WhatsApp', model });
+        const conv = await workerApi('/api/conversations', 'POST', { title: this.channelLabel(msg.channel), model });
         convId = conv.id;
         await workerApi('/api/context/set', 'POST', { conversationId: convId });
       }
@@ -861,13 +952,20 @@ export class ChannelManager {
       log.warn(`[channels] Failed to get/create conversation: ${err.message}`);
       return;
     }
+    // Mirrors handleAlexaInbound's guard: never proceed with an undefined convId
+    // (e.g. the conversation API returned no id) — that would push the turn into a
+    // broken conversation key and silently drop the reply.
+    if (!convId) {
+      log.warn('[channels] No conversation id resolved — dropping inbound message');
+      return;
+    }
 
     // Use display text for DB/chat (hides enriched agent context from the UI).
     // Prepend the channel tag so the UI can detect the source for icons.
     const rawDisplay = msg.displayText || msg.text;
     const earlyRoleTag = msg.senderName && msg.role === 'assistant'
       ? `${msg.role} | ${msg.senderName}` : msg.role;
-    const channelTag = `[WhatsApp | ${msg.sender} | ${earlyRoleTag}]\n`;
+    const channelTag = `[${this.channelLabel(msg.channel)} | ${msg.sender} | ${earlyRoleTag}]\n`;
     const displayContent = channelTag + rawDisplay;
 
     // Save user message to DB
@@ -992,9 +1090,11 @@ export class ChannelManager {
     // The agent's reply for THIS specific input will go to msg.rawSender — no other
     // surface can hijack it via the FIFO ordering of the shared conversation.
     const channelContent = channelContext + msg.text;
+    const isTelegram = msg.channel === 'telegram';
     const target: RoutingTarget = {
-      surface: 'whatsapp',
-      waSendTo: msg.rawSender,
+      surface: isTelegram ? 'telegram' : 'whatsapp',
+      waSendTo: isTelegram ? undefined : msg.rawSender,
+      telegramChatId: isTelegram ? msg.rawSender : undefined,
       isGroup: msg.isGroup,
       // Self-chat in 1:1: don't prefix "🤖 Bot:" — it's the user's own chat with themselves.
       isSelfChat: msg.role === 'admin' && !msg.isGroup,
@@ -1210,7 +1310,7 @@ export class ChannelManager {
       }
     } catch {}
 
-    const channelContext = `[WhatsApp | ${msg.sender} | customer${msg.senderName ? ` | ${msg.senderName}` : ''}]\n`;
+    const channelContext = `[${this.channelLabel(msg.channel)} | ${msg.sender} | customer${msg.senderName ? ` | ${msg.senderName}` : ''}]\n`;
 
     // Convert inbound attachments to agent format
     const agentAttachments: AgentAttachment[] | undefined = msg.attachments?.map((att) => ({

package/supervisor/channels/telegram.ts

@@ -0,0 +1,361 @@
+/**
+ * Telegram channel provider — DIRECT Bot API, no relay in the message path.
+ *
+ * Unlike Alexa (relay-mediated, degenerate provider), this provider holds the
+ * user's OWN bot token and long-polls `getUpdates` straight against
+ * api.telegram.org. After the relay provisions the token at pairing time (via
+ * Telegram "Managed Bots"), the relay is gone — every inbound/outbound message
+ * (including media) flows Bloby ↔ Telegram directly. Outbound HTTPS only: works
+ * behind NAT, no public URL, no relay egress.
+ *
+ * It is lighter than the WhatsApp/Baileys provider (no reverse-engineered
+ * protocol, no QR, no auth-state files) — just a token string and a poll loop.
+ */
+
+import { loadConfig } from '../../shared/config.js';
+import { log } from '../../shared/logger.js';
+import type { ChannelProvider, ChannelStatus, ChannelType } from './types.js';
+
+const TG_API = 'https://api.telegram.org';
+const POLL_TIMEOUT_S = 25;          // long-poll hold time
+const MAX_MESSAGE_CHARS = 4096;     // Telegram hard limit per sendMessage
+const TYPING_REFRESH_MS = 5_000;    // Telegram "typing" expires ~5s
+
+/** Image extracted from an inbound Telegram message. */
+export interface TelegramImageAttachment {
+  mediaType: string;
+  data: string; // base64
+}
+
+/** Normalized inbound message handed to the ChannelManager. */
+export interface TelegramInbound {
+  /** Chat id (string form of the numeric Telegram chat.id). Reply target. */
+  chatId: string;
+  /** Sender's numeric Telegram user id (string). */
+  fromUserId: string;
+  /** Display name (first name / @username) if available. */
+  senderName?: string;
+  text: string;
+  isGroup: boolean;
+  messageId?: number;
+  images?: TelegramImageAttachment[];
+}
+
+export type OnTelegramMessage = (msg: TelegramInbound) => void;
+export type TranscribeFn = (audioBase64: string) => Promise<string | null>;
+
+export class TelegramChannel implements ChannelProvider {
+  readonly type: ChannelType = 'telegram';
+
+  private token: string | null = null;
+  private botUsername: string | null = null;
+  private connected = false;
+  private offset = 0;
+  private intentionalDisconnect = false;
+  private pollAbort: AbortController | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private typingIntervals = new Map<string, ReturnType<typeof setInterval>>();
+
+  private onMessage: OnTelegramMessage;
+  private onStatusChange: (status: ChannelStatus) => void;
+  private transcribe: TranscribeFn | null;
+
+  constructor(
+    onMessage: OnTelegramMessage,
+    onStatusChange: (status: ChannelStatus) => void,
+    transcribe?: TranscribeFn,
+  ) {
+    this.onMessage = onMessage;
+    this.onStatusChange = onStatusChange;
+    this.transcribe = transcribe || null;
+  }
+
+  private api(method: string): string {
+    return `${TG_API}/bot${this.token}/${method}`;
+  }
+
+  hasCredentials(): boolean {
+    return !!loadConfig().channels?.telegram?.botToken;
+  }
+
+  getQrCode(): string | null {
+    return null;
+  }
+
+  getStatus(): ChannelStatus {
+    return {
+      channel: 'telegram',
+      connected: this.connected,
+      info: {
+        botUsername: this.botUsername || loadConfig().channels?.telegram?.botUsername || null,
+        linked: this.hasCredentials(),
+        hasCredentials: this.hasCredentials(),
+      },
+    };
+  }
+
+  async connect(): Promise<void> {
+    this.intentionalDisconnect = false;
+    const cfg = loadConfig().channels?.telegram;
+    if (!cfg?.botToken) {
+      log.warn('[telegram] No bot token configured — not connecting');
+      return;
+    }
+    this.token = cfg.botToken;
+    this.botUsername = cfg.botUsername || null;
+
+    // getMe confirms the token and learns the @username.
+    try {
+      const me = await this.call('getMe', {});
+      if (me?.username) this.botUsername = me.username;
+      log.ok(`[telegram] Connected as @${this.botUsername || 'unknown'} (id=${me?.id || '?'})`);
+    } catch (err: any) {
+      log.warn(`[telegram] getMe failed: ${err.message} — will retry in poll loop`);
+    }
+
+    this.connected = true;
+    this.emitStatus();
+    this.pollLoop(); // fire and forget
+  }
+
+  async disconnect(): Promise<void> {
+    this.intentionalDisconnect = true;
+    if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null; }
+    if (this.pollAbort) { try { this.pollAbort.abort(); } catch {} this.pollAbort = null; }
+    for (const interval of this.typingIntervals.values()) clearInterval(interval);
+    this.typingIntervals.clear();
+    this.connected = false;
+    this.emitStatus();
+  }
+
+  // ── Outbound ──────────────────────────────────────────────────────────────
+
+  async sendMessage(to: string, text: string): Promise<void> {
+    if (!this.token) { log.warn('[telegram] Cannot send — no token'); return; }
+    this.stopTyping(to);
+    // Telegram caps messages at 4096 chars — split on the limit.
+    for (const chunk of splitMessage(text, MAX_MESSAGE_CHARS)) {
+      try {
+        await this.call('sendMessage', { chat_id: to, text: chunk, link_preview_options: { is_disabled: true } });
+      } catch (err: any) {
+        log.warn(`[telegram] sendMessage to ${to} failed: ${err.message}`);
+        return;
+      }
+    }
+    log.info(`[telegram] Sent message to ${to} (${text.length} chars)`);
+  }
+
+  /** Send an image natively (used by ChannelManager for <BlobyImage> tags). */
+  async sendImage(to: string, image: Buffer, caption?: string, mimetype?: string): Promise<void> {
+    if (!this.token) { log.warn('[telegram] Cannot send image — no token'); return; }
+    this.stopTyping(to);
+    try {
+      const form = new FormData();
+      form.append('chat_id', to);
+      if (caption) form.append('caption', caption.slice(0, 1024));
+      const ext = (mimetype?.split('/')[1] || 'png').replace('jpeg', 'jpg');
+      form.append('photo', new Blob([new Uint8Array(image)], { type: mimetype || 'image/png' }), `image.${ext}`);
+      const r = await fetch(this.api('sendPhoto'), { method: 'POST', body: form });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      log.info(`[telegram] Sent image to ${to}`);
+    } catch (err: any) {
+      log.warn(`[telegram] sendImage to ${to} failed: ${err.message}`);
+    }
+  }
+
+  /** Show "typing…" — refreshes every 5s since Telegram's indicator expires. */
+  startTyping(to: string): void {
+    if (!this.token || !this.connected) return;
+    this.stopTyping(to);
+    let ticks = 0;
+    const send = () => {
+      // Cap the refresh (~2 min) so a turn that ends without a reply can't leave a stuck indicator.
+      if (++ticks > 24) { this.stopTyping(to); return; }
+      this.call('sendChatAction', { chat_id: to, action: 'typing' }).catch(() => {});
+    };
+    send();
+    this.typingIntervals.set(to, setInterval(send, TYPING_REFRESH_MS));
+  }
+
+  stopTyping(to: string): void {
+    const interval = this.typingIntervals.get(to);
+    if (interval) { clearInterval(interval); this.typingIntervals.delete(to); }
+  }
+
+  // ── Inbound poll loop ─────────────────────────────────────────────────────
+
+  private async pollLoop(): Promise<void> {
+    while (!this.intentionalDisconnect) {
+      this.pollAbort = new AbortController();
+      try {
+        const updates = await this.call('getUpdates', {
+          offset: this.offset,
+          timeout: POLL_TIMEOUT_S,
+          allowed_updates: ['message'],
+        }, this.pollAbort.signal, (POLL_TIMEOUT_S + 10) * 1000);
+
+        if (Array.isArray(updates)) {
+          for (const update of updates) {
+            this.offset = Math.max(this.offset, (update.update_id || 0) + 1);
+            try { await this.handleUpdate(update); }
+            catch (err: any) { log.warn(`[telegram] handleUpdate error: ${err.message}`); }
+          }
+        }
+      } catch (err: any) {
+        if (this.intentionalDisconnect) break;
+        // Watchdog timeout (the long-poll exceeded its deadline without a response —
+        // e.g. a silently dropped connection). A disconnect-driven abort is caught by
+        // the intentionalDisconnect check above, so any AbortError here is the timeout:
+        // re-open a fresh long-poll immediately rather than treating it as fatal.
+        if (err?.name === 'AbortError') continue;
+        // 409 = another getUpdates/webhook is consuming this bot — do not hot-loop.
+        if (String(err.message).includes('409')) {
+          log.warn('[telegram] getUpdates conflict (409) — another consumer holds this bot. Stopping poll.');
+          this.connected = false;
+          this.emitStatus();
+          return;
+        }
+        log.warn(`[telegram] getUpdates error: ${err.message} — retrying in 5s`);
+        await sleep(5000);
+      }
+    }
+  }
+
+  private async handleUpdate(update: any): Promise<void> {
+    const message = update.message;
+    if (!message) return;
+
+    const from = message.from || {};
+    if (from.is_bot) return; // ignore other bots (our own sends never come back here anyway)
+
+    const chat = message.chat || {};
+    const chatId = String(chat.id);
+    const fromUserId = String(from.id ?? '');
+    const isGroup = chat.type === 'group' || chat.type === 'supergroup';
+    const senderName = from.first_name
+      ? (from.last_name ? `${from.first_name} ${from.last_name}` : from.first_name)
+      : (from.username || undefined);
+
+    let rawText: string = message.text || message.caption || '';
+    const images: TelegramImageAttachment[] = [];
+
+    // Photo: download the largest available size.
+    if (Array.isArray(message.photo) && message.photo.length > 0) {
+      const largest = message.photo[message.photo.length - 1];
+      const img = await this.downloadFile(largest.file_id).catch(() => null);
+      if (img) images.push({ mediaType: 'image/jpeg', data: img.toString('base64') });
+    }
+
+    // Voice note / audio: download + transcribe.
+    const voice = message.voice || message.audio;
+    if (!rawText && voice?.file_id) {
+      if (!this.transcribe) {
+        await this.sendMessage(chatId, 'Voice transcription is off — add an OpenAI API key in your Bloby chat settings (the three-dots menu) to enable it.');
+        return;
+      }
+      const buf = await this.downloadFile(voice.file_id).catch(() => null);
+      if (buf) {
+        const transcript = await this.transcribe(buf.toString('base64')).catch(() => null);
+        if (transcript) {
+          rawText = transcript;
+          log.info(`[telegram] Transcribed voice: "${rawText.slice(0, 80)}"`);
+        } else {
+          await this.sendMessage(chatId, "I couldn't transcribe that voice message — if this keeps happening, add an OpenAI API key in your Bloby chat settings (the three-dots menu) to enable voice transcription.");
+          return;
+        }
+      }
+    }
+
+    if (!rawText && images.length === 0) return;
+    if (!rawText && images.length > 0) rawText = '(image)';
+
+    const text = escapeMessageText(rawText);
+
+    log.info(`[telegram] Message from ${fromUserId} (chat=${chatId}, group=${isGroup}, images=${images.length}): ${text.slice(0, 80)}`);
+
+    this.onMessage({
+      chatId,
+      fromUserId,
+      senderName,
+      text,
+      isGroup,
+      messageId: message.message_id,
+      images: images.length > 0 ? images : undefined,
+    });
+  }
+
+  /** Resolve a Telegram file_id to its bytes (getFile → download from the file CDN). */
+  private async downloadFile(fileId: string): Promise<Buffer | null> {
+    const file = await this.call('getFile', { file_id: fileId });
+    const filePath = file?.file_path;
+    if (!filePath) return null;
+    const r = await fetch(`${TG_API}/file/bot${this.token}/${filePath}`);
+    if (!r.ok) throw new Error(`file download HTTP ${r.status}`);
+    const buf = Buffer.from(await r.arrayBuffer());
+    log.info(`[telegram] Downloaded file (${Math.round(buf.length / 1024)}KB)`);
+    return buf;
+  }
+
+  /** Call a Bot API method, returning `result` or throwing on `ok:false`. */
+  private async call(method: string, params: Record<string, any>, signal?: AbortSignal, timeoutMs = 30_000): Promise<any> {
+    // Always apply the watchdog timeout, AND honor the caller's abort signal (disconnect)
+    // when present — abort whichever fires first. The previous version dropped the timeout
+    // whenever a signal was passed, leaving the long-poll with no deadline.
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    const onExternalAbort = () => ctrl.abort();
+    if (signal) {
+      if (signal.aborted) ctrl.abort();
+      else signal.addEventListener('abort', onExternalAbort, { once: true });
+    }
+    try {
+      const r = await fetch(this.api(method), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(params),
+        signal: ctrl.signal,
+      });
+      const data = await r.json().catch(() => ({}));
+      if (!r.ok || !data.ok) {
+        throw new Error(`${method} → ${r.status} ${data.description || ''}`.trim());
+      }
+      return data.result;
+    } finally {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onExternalAbort);
+    }
+  }
+
+  private emitStatus() {
+    this.onStatusChange(this.getStatus());
+  }
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Split a long message into <=limit-char chunks, preferring newline boundaries. */
+function splitMessage(text: string, limit: number): string[] {
+  if (text.length <= limit) return [text];
+  const chunks: string[] = [];
+  let rest = text;
+  while (rest.length > limit) {
+    let cut = rest.lastIndexOf('\n', limit);
+    if (cut < limit * 0.5) cut = limit; // no good newline — hard cut
+    chunks.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^\n/, '');
+  }
+  if (rest) chunks.push(rest);
+  return chunks;
+}
+
+/** Mirror WhatsApp's anti-injection escaping so message content can't fake channel/role tags. */
+function escapeMessageText(text: string): string {
+  return text
+    .replace(/\[Telegram\s*\|/gi, '(Telegram|')
+    .replace(/\[WhatsApp\s*\|/gi, '(WhatsApp|')
+    .replace(/\[\s*(admin|customer)\s*\]/gi, '($1)');
+}

package/supervisor/channels/types.ts

@@ -78,13 +78,17 @@ export interface RoutingTarget {
   /** Which surface triggered this turn. Drives whether the WA reply carries a "🤖 Bot:" prefix.
    *  'workspace' is a dashboard surface like 'chat' (broadcast-driven, optional WA self-chat mirror)
    *  but isolated for telemetry / future per-surface routing. */
-  surface: 'chat' | 'whatsapp' | 'alexa' | 'workspace';
+  surface: 'chat' | 'whatsapp' | 'alexa' | 'telegram' | 'workspace';
   /** WhatsApp JID to deliver the reply to.
    *  - 'whatsapp' surface → the originating chat JID (group or peer).
    *  - 'chat' surface     → optionally the user's own number (self-chat mirror), or undefined.
    *  When undefined, no WhatsApp send happens — the reply only reaches the dashboard via broadcast.
    */
   waSendTo?: string;
+  /** Telegram chat id to deliver the reply to ('telegram' surface). */
+  telegramChatId?: string;
+  /** Telegram message id of the inbound that triggered this turn (for reply-to / reactions). */
+  telegramMessageId?: number;
   isGroup?: boolean;
   isSelfChat?: boolean;
   /** When set, the assistant's reply is appended to this customer buffer (assistant-mode context). */