beecork 1.4.11 → 1.6.0

package/dist/channels/telegram.js

@@ -1,41 +1,50 @@
 import TelegramBot from 'node-telegram-bot-api';
 import fs from 'node:fs';
 import path from 'node:path';
-import { chunkText, timeAgo, parseTabMessage } from '../util/text.js';
+import { chunkText, parseTabMessage, formatTabbedResponse } from '../util/text.js';
 import { logger } from '../util/logger.js';
 import { retryWithBackoff } from '../util/retry.js';
-import { getAdminUserId } from '../config.js';
+import { sendChunkedResponse } from './send-helpers.js';
 import { getLogsDir } from '../util/paths.js';
 import { saveMedia, isOversized } from '../media/store.js';
 import { inboundLimiter, groupLimiter } from '../util/rate-limiter.js';
 import { processInboundMessage } from './pipeline.js';
-import { initVoiceProviders } from '../voice/index.js';
-const DEFAULT_GROUP_CONFIG = { activationMode: 'mention', maxResponsesPerMinute: 3, tabPerGroup: true };
-/** Format tab status for Telegram display */
-export function formatTabStatus(tabs) {
-    if (tabs.length === 0)
-        return 'No tabs.';
-    return tabs.map(t => {
-        const ago = timeAgo(t.lastActivityAt);
-        return `• ${t.name} [${t.status}] — ${ago}`;
-    }).join('\n');
+import { isChannelAdmin } from './admin.js';
+import { VoiceState } from './voice-state.js';
+const DEFAULT_GROUP_CONFIG = {
+    activationMode: 'mention',
+    maxResponsesPerMinute: 3,
+    tabPerGroup: true,
+};
+/**
+ * Strip Telegram bot tokens out of strings before logging. Telegram embeds
+ * the token in the URL path (e.g. https://api.telegram.org/bot1234:abc.../method),
+ * so on fetch errors the message/cause can leak the token to disk.
+ */
+function sanitizeBotToken(text) {
+    return text.replace(/bot\d+:[A-Za-z0-9_-]+/g, 'bot<REDACTED>');
 }
 export class TelegramChannel {
     id = 'telegram';
     name = 'Telegram';
     maxMessageLength = 4096;
-    supportsStreaming = true;
-    supportsMedia = true;
     bot;
     ctx;
     activeChatIds = new Set();
-    sttProvider = null;
-    ttsProvider = null;
+    // Set form of config.telegram.allowedUserIds for O(1) per-message membership
+    // checks. Built lazily in start() so config edits via reload (if added later)
+    // can call rebuildAllowedSet().
+    allowedUserIdSet = new Set();
+    voice = new VoiceState('telegram');
     botUserId = null;
     botUsername = null;
     mutedGroups = new Set();
     welcomeSent = new Set();
-    sttWarmedUp = false;
+    // Polling-error tracking: warn the user once when the bot is silently broken
+    // (network drop, telegram 5xx, token revoked, etc.). Without this, the daemon
+    // looks fine but Telegram has stopped delivering inbound messages.
+    pollingErrorTimes = [];
+    pollingDegradedNotified = false;
     constructor(ctx) {
         this.ctx = ctx;
         this.bot = new TelegramBot(ctx.config.telegram.token, {
@@ -50,18 +59,33 @@ export class TelegramChannel {
         this.bot.sendMessage = this.bot.sendMessage.bind(this.bot);
     }
     async start() {
-        // Clear pending updates from old sessions, then start polling
+        // Clear pending updates from old sessions, then start polling.
+        // node-telegram-bot-api's TS types don't include deleteWebHook, so we go
+        // through a typed shim rather than `as any`.
         try {
             await this.bot.deleteWebHook({ drop_pending_updates: true });
         }
         catch (err) {
             logger.error('Failed to clear pending updates, starting anyway:', err);
         }
-        // Initialize voice providers
-        const { stt, tts } = initVoiceProviders(this.ctx.config.voice);
-        this.sttProvider = stt;
-        this.ttsProvider = tts;
+        // Initialize voice providers (STT + TTS)
+        this.voice.init(this.ctx.config);
+        // Subscribe to library-level error events BEFORE startPolling so transient
+        // failures don't disappear into the void. node-telegram-bot-api emits
+        // 'polling_error' on network/auth/5xx issues — without a listener these
+        // were previously silently dropped, leaving the channel dead with no signal.
+        this.bot.on('polling_error', (err) => {
+            logger.error('Telegram polling error:', sanitizeBotToken(err?.message || String(err)));
+            this.recordPollingError();
+        });
+        this.bot.on('error', (err) => {
+            logger.error('Telegram client error:', sanitizeBotToken(err?.message || String(err)));
+        });
         this.bot.startPolling();
+        this.allowedUserIdSet = new Set(this.ctx.config.telegram.allowedUserIds);
+        if (this.allowedUserIdSet.size === 0) {
+            logger.warn('Telegram allowedUserIds is empty — bot will reject all inbound messages until you add at least one user ID.');
+        }
         // Cache bot identity for group mention detection
         try {
             const me = await this.bot.getMe();
@@ -74,11 +98,32 @@ export class TelegramChannel {
         this.setupHandlers();
         logger.info('Telegram bot started (polling mode, cleared pending updates)');
     }
+    /**
+     * Track polling errors over a 60s rolling window. If we see 5+ errors in 60s
+     * we surface "polling degraded" exactly once via the notify callback so the
+     * user knows Telegram is broken instead of silently failing.
+     */
+    recordPollingError() {
+        const now = Date.now();
+        this.pollingErrorTimes.push(now);
+        this.pollingErrorTimes = this.pollingErrorTimes.filter((t) => now - t < 60_000);
+        if (this.pollingErrorTimes.length >= 5 && !this.pollingDegradedNotified) {
+            this.pollingDegradedNotified = true;
+            this.ctx
+                .notifyCallback?.('⚠️ Telegram polling degraded (5+ errors in 60s). Check daemon.log.')
+                .catch((err) => logger.warn('Failed to send polling-degraded notice:', err));
+            // Reset notification flag after 5 minutes so a sustained outage that
+            // recovers and reoccurs can re-notify.
+            setTimeout(() => {
+                this.pollingDegradedNotified = false;
+            }, 5 * 60_000).unref();
+        }
+    }
     stop() {
         this.bot.stopPolling();
         logger.info('Telegram bot stopped');
     }
-    async sendMessage(peerId, text, options) {
+    async sendMessage(peerId, text, _options) {
         const chatId = Number(peerId);
         const chunks = chunkText(text);
         for (const chunk of chunks) {
@@ -101,7 +146,57 @@ export class TelegramChannel {
                 await this.bot.sendMessage(userId, message);
                 this.activeChatIds.add(userId);
             }
-            catch { /* User hasn't started conversation yet */ }
+            catch (err) {
+                // Differentiate: 400 "chat not found" means the user has not started a
+                // conversation with the bot yet — silently skip. Anything else (rate
+                // limit, bot blocked, network) is a real delivery failure worth logging.
+                const errAny = err;
+                const status = errAny?.response?.statusCode;
+                const isChatNotFound = status === 400 || /chat not found/i.test(errAny?.message || '');
+                if (!isChatNotFound) {
+                    logger.warn(`Telegram notify to ${userId} failed (status=${status ?? '?'}):`, sanitizeBotToken(errAny?.message || String(err)));
+                }
+            }
+        }
+    }
+    /**
+     * Send a media file to every recipient the bot would notify. Used by the
+     * pending-message dispatcher to deliver media queued by MCP tools.
+     * Routes by attachment type to the right Telegram primitive (sendVoice for
+     * voice messages, sendPhoto for images, sendVideo for video, sendDocument
+     * for everything else).
+     */
+    async broadcastMedia(media) {
+        const recipients = new Set(this.activeChatIds);
+        for (const userId of this.ctx.config.telegram.allowedUserIds)
+            recipients.add(userId);
+        if (recipients.size === 0)
+            return;
+        const caption = media.caption ? { caption: media.caption.slice(0, 1024) } : undefined;
+        for (const chatId of recipients) {
+            try {
+                switch (media.type) {
+                    case 'voice':
+                        await this.bot.sendVoice(chatId, media.filePath, caption);
+                        break;
+                    case 'audio':
+                        await this.bot.sendAudio(chatId, media.filePath, caption);
+                        break;
+                    case 'image':
+                        await this.bot.sendPhoto(chatId, media.filePath, caption);
+                        break;
+                    case 'video':
+                        await this.bot.sendVideo(chatId, media.filePath, caption);
+                        break;
+                    case 'document':
+                    default:
+                        await this.bot.sendDocument(chatId, media.filePath, caption);
+                        break;
+                }
+            }
+            catch (err) {
+                logger.warn(`Telegram broadcastMedia to ${chatId} failed:`, sanitizeBotToken(err instanceof Error ? err.message : String(err)));
+            }
         }
     }
     async setTyping(peerId, active) {
@@ -111,9 +206,6 @@ export class TelegramChannel {
             });
         }
     }
-    onMessage(_handler) {
-        // Messages are handled directly in setupHandlers()
-    }
     // ─── Private ───
     setupHandlers() {
         this.bot.on('message', async (msg) => {
@@ -135,14 +227,14 @@ export class TelegramChannel {
                     const welcomeText = msg.text?.trim() || '';
                     await this.bot.sendMessage(chatId, [
                         '\uD83D\uDC4B Welcome to Beecork!\n',
-                        'Send any message and I\'ll pass it to Claude Code.',
+                        "Send any message and I'll pass it to Claude Code.",
                         '',
                         'Quick tips:',
-                        '\u2022 `/tab name message` \u2014 organize work into tabs',
-                        '\u2022 `/tabs` \u2014 see what\'s running',
-                        '\u2022 `/stop name` \u2014 stop a tab',
+                        '\u2022 /tab name message \u2014 organize work into tabs',
+                        "\u2022 /tabs \u2014 see what's running",
+                        '\u2022 /stop name \u2014 stop a tab',
                         '',
-                        'Let\'s get started! Send me something.',
+                        "Let's get started! Send me something.",
                     ].join('\n'));
                     // Don't return - let the actual message be processed too (unless it was just /start)
                     if (welcomeText === '/start')
@@ -175,7 +267,9 @@ export class TelegramChannel {
                         shouldActivate = !!isReplyToBot;
                         break;
                     case 'keyword':
-                        shouldActivate = groupConfig.keywords?.some(kw => text.toLowerCase().includes(kw.toLowerCase())) ?? false;
+                        shouldActivate =
+                            groupConfig.keywords?.some((kw) => text.toLowerCase().includes(kw.toLowerCase())) ??
+                                false;
                         break;
                     case 'always':
                         shouldActivate = true;
@@ -201,39 +295,63 @@ export class TelegramChannel {
             if (msg.photo) {
                 const photo = msg.photo[msg.photo.length - 1];
                 downloadTasks.push(this.downloadTelegramFile(photo.file_id, 'jpg')
-                    .then(fp => fp ? { type: 'image', mimeType: 'image/jpeg', filePath: fp, fileName: `photo-${photo.file_id}.jpg` } : null)
+                    .then((fp) => fp
+                    ? {
+                        type: 'image',
+                        mimeType: 'image/jpeg',
+                        filePath: fp,
+                        fileName: `photo-${photo.file_id}.jpg`,
+                    }
+                    : null)
                     .catch(() => null));
             }
             if (msg.voice) {
                 downloadTasks.push(this.downloadTelegramFile(msg.voice.file_id, 'ogg')
-                    .then(fp => fp ? { type: 'voice', mimeType: 'audio/ogg', filePath: fp, duration: msg.voice.duration } : null)
+                    .then((fp) => fp ? { type: 'voice', mimeType: 'audio/ogg', filePath: fp } : null)
                     .catch(() => null));
             }
             if (msg.audio) {
                 downloadTasks.push(this.downloadTelegramFile(msg.audio.file_id, 'mp3')
-                    .then(fp => fp ? { type: 'audio', mimeType: msg.audio.mime_type || 'audio/mpeg', filePath: fp, fileName: msg.audio.title, duration: msg.audio.duration } : null)
+                    .then((fp) => fp
+                    ? {
+                        type: 'audio',
+                        mimeType: msg.audio.mime_type || 'audio/mpeg',
+                        filePath: fp,
+                        fileName: msg.audio.title,
+                    }
+                    : null)
                     .catch(() => null));
             }
             if (msg.document) {
                 const ext = msg.document.file_name?.split('.').pop() || 'bin';
                 downloadTasks.push(this.downloadTelegramFile(msg.document.file_id, ext)
-                    .then(fp => fp ? { type: 'document', mimeType: msg.document.mime_type || 'application/octet-stream', filePath: fp, fileName: msg.document.file_name } : null)
+                    .then((fp) => fp
+                    ? {
+                        type: 'document',
+                        mimeType: msg.document.mime_type || 'application/octet-stream',
+                        filePath: fp,
+                        fileName: msg.document.file_name,
+                    }
+                    : null)
                     .catch(() => null));
             }
             if (msg.video) {
                 downloadTasks.push(this.downloadTelegramFile(msg.video.file_id, 'mp4')
-                    .then(fp => fp ? { type: 'video', mimeType: msg.video.mime_type || 'video/mp4', filePath: fp, duration: msg.video.duration } : null)
+                    .then((fp) => fp
+                    ? {
+                        type: 'video',
+                        mimeType: msg.video.mime_type || 'video/mp4',
+                        filePath: fp,
+                    }
+                    : null)
                     .catch(() => null));
             }
             const downloadResults = await Promise.allSettled(downloadTasks);
             const media = downloadResults
                 .filter((r) => r.status === 'fulfilled' && r.value !== null)
-                .map(r => r.value);
+                .map((r) => r.value);
             // Transcribe voice messages if STT is configured
-            if (this.sttProvider) {
-                const { transcribeVoiceMessages } = await import('../voice/index.js');
-                this.sttWarmedUp = await transcribeVoiceMessages(media, this.sttProvider, 'telegram', this.sttWarmedUp);
-            }
+            await this.voice.transcribe(media);
             // Skip if no text AND no media
             if (!text && media.length === 0)
                 return;
@@ -255,7 +373,11 @@ export class TelegramChannel {
             }
             catch (err) {
                 logger.error('Telegram: error handling message:', err);
-                await this.bot.sendMessage(chatId, 'Something went wrong processing your message. Check daemon logs for details.');
+                // Wrap the fallback send so a Telegram outage doesn't escalate to an
+                // unhandledRejection on the message-event handler.
+                this.bot
+                    .sendMessage(chatId, 'Something went wrong processing your message. Check daemon logs for details.')
+                    .catch((sendErr) => logger.error('Telegram: failed to send fallback error message:', sendErr));
             }
         });
     }
@@ -271,35 +393,8 @@ export class TelegramChannel {
             await this.bot.sendMessage(chatId, 'Beecork unmuted in this group.');
             return;
         }
-        if (text === '/history' || text.startsWith('/history ')) {
-            const dateArg = text.slice(9).trim();
-            const { getTimeline, formatTimeline } = await import('../timeline/index.js');
-            let date;
-            if (dateArg === 'yesterday') {
-                date = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
-            }
-            else if (dateArg) {
-                date = dateArg;
-            }
-            else {
-                date = new Date().toISOString().slice(0, 10);
-            }
-            const events = getTimeline({ date, limit: 30 });
-            await this.sendResponse(chatId, formatTimeline(events));
-            return;
-        }
-        if (text === '/knowledge') {
-            const { getAllKnowledge, formatKnowledgeForContext } = await import('../knowledge/index.js');
-            const entries = getAllKnowledge();
-            if (entries.length === 0) {
-                await this.bot.sendMessage(chatId, 'No knowledge stored yet. Beecork learns from your conversations.');
-                return;
-            }
-            const formatted = formatKnowledgeForContext(entries);
-            await this.sendResponse(chatId, formatted.slice(0, 4000));
-            return;
-        }
-        // Shared command handler (covers /tabs, /stop, /tab, /projects, /project, /newproject, /close, /fresh, /register, /link, /users, /cost, /activity, /handoff)
+        // /history and /knowledge now handled by the shared command handler.
+        // Shared command handler (covers /tabs, /stop, /tab, /projects, /project, /newproject, /close, /fresh, /cost, /activity, /handoff, /history, /knowledge)
         const { handleSharedCommand } = await import('./command-handler.js');
         const result = await handleSharedCommand({
             userId: String(userId || 'default'),
@@ -345,9 +440,6 @@ export class TelegramChannel {
             this.bot.sendMessage(chatId, `Still working on your request...`).catch(() => { });
         }, 120000);
         try {
-            let responseText;
-            let responseError;
-            let responseTab;
             // Telegram-specific: streaming message edits
             let streamMsgId = null;
             let streamBuffer = '';
@@ -362,8 +454,8 @@ export class TelegramChannel {
                     return;
                 lastEditTime = now;
                 try {
-                    const prefix = effectiveTabForStream !== 'default' ? `[${effectiveTabForStream}] ` : '';
-                    const preview = prefix + streamBuffer.slice(0, 4000) + (streamBuffer.length > 4000 ? '...' : '');
+                    const truncated = streamBuffer.slice(0, 4000) + (streamBuffer.length > 4000 ? '...' : '');
+                    const preview = formatTabbedResponse(truncated, effectiveTabForStream);
                     if (!streamMsgId) {
                         const sent = await this.bot.sendMessage(chatId, preview);
                         streamMsgId = sent.message_id;
@@ -372,7 +464,9 @@ export class TelegramChannel {
                         await this.bot.editMessageText(preview, { chat_id: chatId, message_id: streamMsgId });
                     }
                 }
-                catch { /* edit failures are non-critical */ }
+                catch {
+                    /* edit failures are non-critical */
+                }
             };
             // Shared pipeline handles: routing, media prompt, progress, sendMessage, TTS
             const pipelineResult = await processInboundMessage({
@@ -381,7 +475,7 @@ export class TelegramChannel {
                 channelId: 'telegram',
                 tabManager: this.ctx.tabManager,
                 voiceReplyMode: this.ctx.config.voice?.replyMode,
-                ttsProvider: this.ttsProvider,
+                ttsProvider: this.voice.tts,
                 userId: String(chatId),
                 sendProgress: (msg) => {
                     this.bot.sendMessage(chatId, msg).catch(() => { });
@@ -397,9 +491,9 @@ export class TelegramChannel {
             }
             // Update the effective tab for stream prefix (now known)
             effectiveTabForStream = pipelineResult.tabName;
-            responseText = pipelineResult.responseText;
-            responseError = pipelineResult.isError;
-            responseTab = pipelineResult.tabName;
+            const responseText = pipelineResult.responseText;
+            const responseError = pipelineResult.isError;
+            const responseTab = pipelineResult.tabName;
             // Telegram-specific: if streaming was active and no error, edit the final message
             if (streamMsgId && !responseError) {
                 clearInterval(typingInterval);
@@ -412,8 +506,7 @@ export class TelegramChannel {
                         return;
                 }
                 try {
-                    const prefix = responseTab !== 'default' ? `[${responseTab}] ` : '';
-                    const finalText = prefix + responseText;
+                    const finalText = formatTabbedResponse(responseText, responseTab);
                     if (finalText.length <= 4096) {
                         await this.bot.editMessageText(finalText, { chat_id: chatId, message_id: streamMsgId });
                     }
@@ -457,41 +550,55 @@ export class TelegramChannel {
         }
     }
     async sendResponse(chatId, text, tabName) {
-        const prefix = tabName && tabName !== 'default' ? `[${tabName}] ` : '';
-        const fullText = prefix + text;
+        const fullText = formatTabbedResponse(text, tabName);
         const chunks = chunkText(fullText);
+        // Telegram-specific quirk: if the response would be >10 chunks, send a
+        // preview + the rest as a file. This runs BEFORE sendChunkedResponse so the
+        // helper is only invoked for normal-sized responses.
         if (chunks.length > 10) {
             for (let i = 0; i < 3; i++) {
                 await this.sendWithRetry(chatId, chunks[i]);
             }
             const tmpPath = path.join(getLogsDir(), `response-${Date.now()}.txt`);
             fs.writeFileSync(tmpPath, fullText);
-            await this.bot.sendDocument(chatId, tmpPath, { caption: `Full response (${chunks.length} chunks)` });
+            await this.bot.sendDocument(chatId, tmpPath, {
+                caption: `Full response (${chunks.length} chunks)`,
+            });
             fs.unlinkSync(tmpPath);
             return;
         }
-        for (const chunk of chunks) {
-            await this.sendWithRetry(chatId, chunk);
-        }
+        // Use the shared chunked-send helper so prefix/chunk/retry logic stays
+        // identical across Telegram/Discord/WhatsApp. Quirky per-chunk error
+        // logging (delivery-failures.log) stays in sendWithRetry.
+        await sendChunkedResponse({
+            text,
+            tabName,
+            maxLength: this.maxMessageLength,
+            retryLabel: 'telegram-send',
+            sendChunk: (chunk) => this.sendWithRetryRaw(chatId, chunk),
+        });
     }
     async sendWithRetry(chatId, text) {
+        // Wrapped call used by the >10-chunk fallback path. retryWithBackoff +
+        // delivery-failures.log on permanent failure.
         try {
-            await retryWithBackoff(async () => {
-                try {
-                    await this.bot.sendMessage(chatId, text, { parse_mode: 'Markdown' });
-                }
-                catch {
-                    await this.bot.sendMessage(chatId, text);
-                }
-            }, [1000, 5000, 15000], 'telegram-send');
+            await this.sendWithRetryRaw(chatId, text);
         }
         catch (err) {
             const failLog = path.join(getLogsDir(), 'delivery-failures.log');
-            const entry = `[${new Date().toISOString()}] chatId=${chatId} error=${err instanceof Error ? err.message : err} text=${text.slice(0, 200)}\n`;
+            const sanitizedErr = sanitizeBotToken(err instanceof Error ? err.message : String(err));
+            const entry = `[${new Date().toISOString()}] chatId=${chatId} error=${sanitizedErr} text=${text.slice(0, 200)}\n`;
             fs.appendFileSync(failLog, entry);
             logger.error(`Delivery failed after retries for chat ${chatId}`);
         }
     }
+    async sendWithRetryRaw(chatId, text) {
+        await retryWithBackoff(
+        // Send as plain text — Telegram's legacy "Markdown" parser silently mangles
+        // underscores/asterisks in Claude's responses (code identifiers, names),
+        // and Beecork has no escaping pass for it.
+        () => this.bot.sendMessage(chatId, text), [1000, 5000, 15000], 'telegram-send');
+    }
     async downloadTelegramFile(fileId, extension) {
         const fileInfo = await this.bot.getFile(fileId);
         if (!fileInfo.file_path)
@@ -511,12 +618,15 @@ export class TelegramChannel {
     isAllowed(userId) {
         if (!userId)
             return false;
-        return this.ctx.config.telegram.allowedUserIds.includes(userId);
+        // Set-based O(1) membership check; explicit empty-set check keeps the
+        // fail-closed contract documented in code.
+        if (this.allowedUserIdSet.size === 0)
+            return false;
+        return this.allowedUserIdSet.has(userId);
     }
     isAdmin(userId) {
-        if (!userId)
-            return false;
-        return userId === getAdminUserId();
+        const cfg = this.ctx.config.telegram;
+        return isChannelAdmin(cfg.allowedUserIds, userId, cfg.adminUserId);
     }
     async setReaction(chatId, messageId, emoji) {
         try {

package/dist/channels/types.d.ts

@@ -1,35 +1,12 @@
 import type { TabManager } from '../session/manager.js';
-import type { BeecorkConfig } from '../types.js';
-/** A media file attached to a message */
-export interface MediaAttachment {
-    type: 'image' | 'audio' | 'video' | 'document' | 'voice';
-    mimeType: string;
-    filePath: string;
-    fileName?: string;
-    duration?: number;
-    caption?: string;
-}
-/** An inbound message from any channel */
-export interface InboundMessage {
-    channelId: string;
-    peerId: string;
-    text?: string;
-    media?: MediaAttachment[];
-    replyTo?: string;
-    isGroup: boolean;
-    groupId?: string;
-    isMentioned?: boolean;
-    isReply?: boolean;
-    messageId: string;
-    raw: unknown;
-}
-/** Options for sending a message */
-export interface SendOptions {
-    parseMode?: 'markdown' | 'plain';
-    replyToMessageId?: string;
-}
-/** Handler for inbound messages */
-export type InboundMessageHandler = (message: InboundMessage) => Promise<void>;
+import type { BeecorkConfig, MediaAttachment } from '../types.js';
+export type { MediaAttachment };
+/**
+ * Options for sending a message. Currently empty — channels do not honor
+ * markdown/reply-threading hints. Kept as a placeholder so future per-channel
+ * options can be added without touching every call site.
+ */
+export type SendOptions = Record<string, never>;
 /** The Channel interface — all channels must implement this */
 export interface Channel {
     /** Unique channel identifier (e.g., 'telegram', 'whatsapp', 'discord') */
@@ -38,24 +15,22 @@ export interface Channel {
     readonly name: string;
     /** Maximum message length in characters */
     readonly maxMessageLength: number;
-    /** Whether this channel supports live streaming of responses */
-    readonly supportsStreaming: boolean;
-    /** Whether this channel supports media attachments */
-    readonly supportsMedia: boolean;
     /** Start the channel (connect, start polling, etc.) */
     start(): Promise<void>;
     /** Stop the channel gracefully */
     stop(): void;
     /** Send a text message to a specific peer */
     sendMessage(peerId: string, text: string, options?: SendOptions): Promise<void>;
-    /** Send a media attachment to a peer (optional — check supportsMedia) */
+    /** Send a media attachment to a peer (optional — channels implement when supported) */
     sendMedia?(peerId: string, media: MediaAttachment): Promise<void>;
     /** Send a notification to all configured recipients */
     sendNotification(message: string, urgent?: boolean): Promise<void>;
     /** Set typing indicator for a peer */
     setTyping(peerId: string, active: boolean): Promise<void>;
-    /** Register the inbound message handler — called by the registry */
-    onMessage(handler: InboundMessageHandler): void;
+    /** Broadcast a media file to every configured recipient — used by the
+     * pending-message dispatcher to deliver MCP-queued media. Optional; channels
+     * that don't implement it fall back to sendNotification with a text summary. */
+    broadcastMedia?(media: MediaAttachment): Promise<void>;
 }
 /** Context passed to channels during construction */
 export interface ChannelContext {

package/dist/channels/voice-state.d.ts

@@ -0,0 +1,29 @@
+import type { STTProvider } from '../voice/stt.js';
+import type { TTSProvider } from '../voice/tts.js';
+import type { VoiceConfig, BeecorkConfig } from '../types.js';
+import type { MediaAttachment } from '../types.js';
+/**
+ * Per-channel STT/TTS state. Used to be duplicated across Telegram, WhatsApp,
+ * and Discord; consolidated here so init + warmup + transcription happen the
+ * same way across all 3.
+ *
+ * Discord historically only called warmup() and did NOT transcribe — preserve
+ * that behavior unless the caller explicitly asks for transcription.
+ */
+export declare class VoiceState {
+    private readonly channelId;
+    stt: STTProvider | null;
+    tts: TTSProvider | null;
+    private warmedUp;
+    constructor(channelId: string);
+    init(config: BeecorkConfig | {
+        voice?: VoiceConfig;
+    }): void;
+    /** One-shot warmup (no media). Used by Discord today. */
+    warmup(): Promise<void>;
+    /**
+     * Transcribe voice attachments in-place (mutates the caption fields).
+     * Returns the updated warmed-up flag. No-op if STT isn't configured.
+     */
+    transcribe(media: MediaAttachment[]): Promise<void>;
+}