beecork 1.5.0 → 1.6.0

package/dist/capabilities/index.d.ts

@@ -1,3 +1,3 @@
 export type { CapabilityPack, EnabledCapability } from './types.js';
 export { CAPABILITY_PACKS } from './packs.js';
-export { getAvailablePacks, getEnabledCapabilities, isEnabled, enablePack, disablePack, updateMcpConfig } from './manager.js';
+export { getAvailablePacks, getEnabledCapabilities, isEnabled, enablePack, disablePack, updateMcpConfig, } from './manager.js';

package/dist/capabilities/index.js

@@ -1,2 +1,2 @@
 export { CAPABILITY_PACKS } from './packs.js';
-export { getAvailablePacks, getEnabledCapabilities, isEnabled, enablePack, disablePack, updateMcpConfig } from './manager.js';
+export { getAvailablePacks, getEnabledCapabilities, isEnabled, enablePack, disablePack, updateMcpConfig, } from './manager.js';

package/dist/capabilities/manager.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { getConfig, saveConfig } from '../config.js';
+const SAFE_NPM_PACKAGE = /^[@a-zA-Z0-9_/.-]+$/;
 import { getMcpConfigPath } from '../util/paths.js';
 import { logger } from '../util/logger.js';
 import { CAPABILITY_PACKS } from './packs.js';
@@ -15,28 +16,31 @@ export function getEnabledCapabilities() {
 }
 /** Check if a pack is enabled */
 export function isEnabled(packId) {
-    return getEnabledCapabilities().some(c => c.packId === packId);
+    return getEnabledCapabilities().some((c) => c.packId === packId);
 }
 /** Enable a capability pack */
 export function enablePack(packId, apiKey) {
-    const pack = CAPABILITY_PACKS.find(p => p.id === packId);
+    const pack = CAPABILITY_PACKS.find((p) => p.id === packId);
     if (!pack)
         throw new Error(`Unknown capability: ${packId}. Use 'beecork capabilities' to list.`);
     if (pack.requiresApiKey && !apiKey) {
         throw new Error(`${pack.name} requires an API key. Hint: ${pack.apiKeyHint}`);
     }
     // Install the MCP server package
+    if (!SAFE_NPM_PACKAGE.test(pack.mcpServer.package)) {
+        throw new Error(`Invalid package name in capability pack: ${pack.mcpServer.package}`);
+    }
     try {
         console.log(`Installing ${pack.mcpServer.package}...`);
-        execSync(`npm install -g ${pack.mcpServer.package}`, { stdio: 'pipe' });
+        execFileSync('npm', ['install', '-g', pack.mcpServer.package], { stdio: 'pipe' });
     }
-    catch (err) {
+    catch {
         logger.warn(`Package install skipped (may already be available via npx): ${pack.mcpServer.package}`);
     }
     // Update config
     const config = getConfig();
     const capabilities = config.capabilities || [];
-    const existing = capabilities.findIndex(c => c.packId === packId);
+    const existing = capabilities.findIndex((c) => c.packId === packId);
     const entry = { packId, apiKey, enabledAt: new Date().toISOString() };
     if (existing >= 0) {
         capabilities[existing] = entry;
@@ -54,7 +58,7 @@ export function enablePack(packId, apiKey) {
 export function disablePack(packId) {
     const config = getConfig();
     const capabilities = config.capabilities || [];
-    config.capabilities = capabilities.filter(c => c.packId !== packId);
+    config.capabilities = capabilities.filter((c) => c.packId !== packId);
     saveConfig(config);
     updateMcpConfig();
     logger.info(`Capability disabled: ${packId}`);
@@ -78,7 +82,7 @@ export function updateMcpConfig() {
     // Add enabled capability servers
     const capabilities = getEnabledCapabilities();
     for (const cap of capabilities) {
-        const pack = CAPABILITY_PACKS.find(p => p.id === cap.packId);
+        const pack = CAPABILITY_PACKS.find((p) => p.id === cap.packId);
         if (!pack)
             continue;
         // Resolve env vars
@@ -96,7 +100,7 @@ export function updateMcpConfig() {
             env[pack.apiKeyEnvVar] = cap.apiKey;
         }
         // Resolve args templates
-        const args = (pack.mcpServer.args || []).map(arg => arg.replace(/\$\{(\w+)\}/g, (_, varName) => {
+        const args = (pack.mcpServer.args || []).map((arg) => arg.replace(/\$\{(\w+)\}/g, (_, varName) => {
             if (varName === pack.apiKeyEnvVar)
                 return cap.apiKey || '';
             return process.env[varName] || '';

package/dist/capabilities/packs.js

@@ -9,7 +9,9 @@ export const CAPABILITY_PACKS = [
             package: '@notionhq/notion-mcp-server',
             command: 'npx',
             args: ['-y', '@notionhq/notion-mcp-server'],
-            env: { OPENAPI_MCP_HEADERS: '{"Authorization":"Bearer ${NOTION_API_KEY}","Notion-Version":"2022-06-28"}' },
+            env: {
+                OPENAPI_MCP_HEADERS: '{"Authorization":"Bearer ${NOTION_API_KEY}","Notion-Version":"2022-06-28"}',
+            },
         },
         requiresApiKey: true,
         apiKeyHint: 'Notion integration token (from notion.so/my-integrations)',

package/dist/channels/command-handler.js

@@ -4,6 +4,8 @@
  */
 import { timeAgo } from '../util/text.js';
 import { validateTabName } from '../config.js';
+import { exportTab, formatHandoffInfo } from '../session/handoff.js';
+import { logActivity } from '../timeline/index.js';
 /**
  * Handle shared commands that work identically across all channels.
  * Returns { handled: true, response } if a command was matched.
@@ -16,7 +18,9 @@ export async function handleSharedCommand(ctx, tabManager) {
         const tabs = tabManager.listTabs();
         if (tabs.length === 0)
             return { handled: true, response: 'No tabs.' };
-        const list = tabs.map(t => `• ${t.name} [${t.status}] — ${timeAgo(t.lastActivityAt)}`).join('\n');
+        const list = tabs
+            .map((t) => `• ${t.name} [${t.status}] — ${timeAgo(t.lastActivityAt)}`)
+            .join('\n');
         return { handled: true, response: list };
     }
     // /stop <name>
@@ -71,10 +75,12 @@ export async function handleSharedCommand(ctx, tabManager) {
         const watchers = db.prepare('SELECT * FROM watchers ORDER BY created_at').all();
         if (watchers.length === 0)
             return { handled: true, response: 'No watchers configured.' };
-        const watchList = watchers.map((w) => {
+        const watchList = watchers
+            .map((w) => {
             const status = w.enabled ? 'active' : 'disabled';
             return `[${status}] ${w.name} -- ${w.schedule} (triggers: ${w.trigger_count})`;
-        }).join('\n');
+        })
+            .join('\n');
         return { handled: true, response: `Watchers:\n${watchList}` };
     }
     // /tasks
@@ -84,10 +90,12 @@ export async function handleSharedCommand(ctx, tabManager) {
         const tasks = db.prepare('SELECT * FROM tasks ORDER BY created_at').all();
         if (tasks.length === 0)
             return { handled: true, response: 'No tasks scheduled.' };
-        const taskList = tasks.map((t) => {
+        const taskList = tasks
+            .map((t) => {
             const status = t.enabled ? 'enabled' : 'disabled';
             return `[${status}] ${t.name} (${t.schedule_type}: ${t.schedule}) -> tab:${t.tab_name}`;
-        }).join('\n');
+        })
+            .join('\n');
         return { handled: true, response: `Tasks:\n${taskList}` };
     }
     // /cost
@@ -104,14 +112,17 @@ export async function handleSharedCommand(ctx, tabManager) {
     // /handoff [tab]
     if (text.startsWith('/handoff')) {
         const tabName = text.slice(9).trim() || 'default';
-        const { exportTab, formatHandoffInfo } = await import('../cli/handoff.js');
         const info = exportTab(tabName);
         if (!info)
             return { handled: true, response: `Tab "${tabName}" not found.` };
+        logActivity('user_command', '/handoff', { tabName });
         return { handled: true, response: formatHandoffInfo(info) };
     }
     // /folders (also accept legacy /projects)
-    if (text === '/folders' || text === '/projects' || text.startsWith('/folders@') || text.startsWith('/projects@')) {
+    if (text === '/folders' ||
+        text === '/projects' ||
+        text.startsWith('/folders@') ||
+        text.startsWith('/projects@')) {
         const { listProjects } = await import('../projects/index.js');
         const projects = listProjects();
         if (projects.length === 0)
@@ -128,15 +139,22 @@ export async function handleSharedCommand(ctx, tabManager) {
         return { handled: true, response: msg };
     }
     // /folder <name> (also accept legacy /project <name>)
-    if ((text.startsWith('/folder ') && !text.startsWith('/folders')) || (text.startsWith('/project ') && !text.startsWith('/projects'))) {
+    if ((text.startsWith('/folder ') && !text.startsWith('/folders')) ||
+        (text.startsWith('/project ') && !text.startsWith('/projects'))) {
         const prefix = text.startsWith('/folder ') ? '/folder ' : '/project ';
         const name = text.slice(prefix.length).trim();
         const { getProject, setUserContext } = await import('../projects/index.js');
         const project = getProject(name);
         if (!project)
-            return { handled: true, response: `Folder "${name}" not found. Use /folders to list or /newfolder to create.` };
+            return {
+                handled: true,
+                response: `Folder "${name}" not found. Use /folders to list or /newfolder to create.`,
+            };
         setUserContext(userId, project.name, project.name);
-        return { handled: true, response: `Switched to folder: ${project.name}\nPath: ${project.path}\n\nNext messages will work in this folder.` };
+        return {
+            handled: true,
+            response: `Switched to folder: ${project.name}\nPath: ${project.path}\n\nNext messages will work in this folder.`,
+        };
     }
     // /newfolder <name> [path] (also accept legacy /newproject)
     if (text.startsWith('/newfolder ') || text.startsWith('/newproject ')) {
@@ -149,7 +167,10 @@ export async function handleSharedCommand(ctx, tabManager) {
         const { createProject, setUserContext } = await import('../projects/index.js');
         const project = createProject(name, customPath);
         setUserContext(userId, project.name, project.name);
-        return { handled: true, response: `✓ Folder "${name}" created at ${project.path}\nSwitched to this folder.` };
+        return {
+            handled: true,
+            response: `✓ Folder "${name}" created at ${project.path}\nSwitched to this folder.`,
+        };
     }
     // /close <tab>
     if (text.startsWith('/close ')) {
@@ -157,7 +178,12 @@ export async function handleSharedCommand(ctx, tabManager) {
         if (!tabNameToClose)
             return { handled: true, response: 'Usage: /close <tabname>' };
         const closed = tabManager.closeTab(tabNameToClose);
-        return { handled: true, response: closed ? `Tab "${tabNameToClose}" permanently closed. History deleted.` : `Tab "${tabNameToClose}" not found.` };
+        return {
+            handled: true,
+            response: closed
+                ? `Tab "${tabNameToClose}" permanently closed. History deleted.`
+                : `Tab "${tabNameToClose}" not found.`,
+        };
     }
     // /fresh <folder>
     if (text.startsWith('/fresh ')) {
@@ -168,7 +194,10 @@ export async function handleSharedCommand(ctx, tabManager) {
             return { handled: true, response: `Folder "${folderName}" not found.` };
         const freshTabName = `${folderName}-${Date.now().toString(36).slice(-4)}`;
         setUserContext(userId, project.name, freshTabName);
-        return { handled: true, response: `Fresh start in "${folderName}" (tab: ${freshTabName})\nSend your message now.` };
+        return {
+            handled: true,
+            response: `Fresh start in "${folderName}" (tab: ${freshTabName})\nSend your message now.`,
+        };
     }
     // /history [date|yesterday]
     if (text === '/history' || text.startsWith('/history ')) {
@@ -192,7 +221,10 @@ export async function handleSharedCommand(ctx, tabManager) {
         const { getAllKnowledge, formatKnowledgeForContext } = await import('../knowledge/index.js');
         const entries = getAllKnowledge();
         if (entries.length === 0) {
-            return { handled: true, response: 'No knowledge stored yet. Beecork learns from your conversations.' };
+            return {
+                handled: true,
+                response: 'No knowledge stored yet. Beecork learns from your conversations.',
+            };
         }
         return { handled: true, response: formatKnowledgeForContext(entries).slice(0, 4000) };
     }

package/dist/channels/discord.d.ts

@@ -1,10 +1,8 @@
-import type { Channel, ChannelContext, InboundMessageHandler, SendOptions } from './types.js';
+import type { Channel, ChannelContext, SendOptions } from './types.js';
 export declare class DiscordChannel implements Channel {
     readonly id = "discord";
     readonly name = "Discord";
     readonly maxMessageLength = 2000;
-    readonly supportsStreaming = false;
-    readonly supportsMedia = true;
     private client;
     private ctx;
     private allowedUserIds;
@@ -12,9 +10,8 @@ export declare class DiscordChannel implements Channel {
     constructor(ctx: ChannelContext);
     start(): Promise<void>;
     stop(): void;
-    onMessage(_handler: InboundMessageHandler): void;
-    sendMessage(peerId: string, text: string, options?: SendOptions): Promise<void>;
-    sendNotification(message: string, urgent?: boolean): Promise<void>;
+    sendMessage(peerId: string, text: string, _options?: SendOptions): Promise<void>;
+    sendNotification(message: string, _urgent?: boolean): Promise<void>;
     setTyping(peerId: string, active: boolean): Promise<void>;
     private sendResponse;
 }

package/dist/channels/discord.js

@@ -1,6 +1,17 @@
+/*
+ * Discord integration via discord.js (peer-optional, dynamic-imported).
+ *
+ * discord.js's strict union types (PartialGroupDMChannel, TextChannel, etc.)
+ * require narrowing at every send/sendTyping callsite. The runtime channel
+ * objects we receive in handlers all support these methods, but expressing
+ * that to TypeScript via the published types is a significant refactor with
+ * no runtime benefit. We accept `any` at this library boundary — same pattern
+ * as the WhatsApp/baileys integration.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import { logger } from '../util/logger.js';
-import { chunkText, formatTabbedResponse, parseTabMessage } from '../util/text.js';
-import { retryWithBackoff } from '../util/retry.js';
+import { parseTabMessage } from '../util/text.js';
+import { sendChunkedResponse } from './send-helpers.js';
 import { inboundLimiter } from '../util/rate-limiter.js';
 import { saveMedia, isOversized } from '../media/store.js';
 import { VoiceState } from './voice-state.js';
@@ -10,8 +21,6 @@ export class DiscordChannel {
     id = 'discord';
     name = 'Discord';
     maxMessageLength = 2000;
-    supportsStreaming = false; // Discord message editing is rate-limited
-    supportsMedia = true;
     client = null; // Discord.js Client
     ctx;
     allowedUserIds;
@@ -56,7 +65,9 @@ export class DiscordChannel {
             }
             // Rate limit
             if (!inboundLimiter.check(this.id)) {
-                await message.reply("I'm receiving too many messages right now. Please wait a moment.").catch(() => { });
+                await message
+                    .reply("I'm receiving too many messages right now. Please wait a moment.")
+                    .catch(() => { });
                 return;
             }
             const text = message.content
@@ -188,26 +199,25 @@ export class DiscordChannel {
         }
         logger.info('Discord bot stopped');
     }
-    onMessage(_handler) {
-        // Messages are handled directly in start()
-    }
-    async sendMessage(peerId, text, options) {
+    async sendMessage(peerId, text, _options) {
         if (!this.client)
             return;
         try {
             const channel = await this.client.channels.fetch(peerId);
             if (!channel?.isTextBased())
                 return;
-            const chunks = chunkText(text, this.maxMessageLength);
-            for (const chunk of chunks) {
-                await retryWithBackoff(() => channel.send(chunk), [1000, 5000, 15000], 'discord-send');
-            }
+            await sendChunkedResponse({
+                text,
+                maxLength: this.maxMessageLength,
+                retryLabel: 'discord-send',
+                sendChunk: (chunk) => channel.send(chunk),
+            });
         }
         catch (err) {
             logger.error(`Discord send failed for ${peerId}:`, err);
         }
     }
-    async sendNotification(message, urgent) {
+    async sendNotification(message, _urgent) {
         if (!this.client)
             return;
         // Send to all allowed users via DM
@@ -236,14 +246,21 @@ export class DiscordChannel {
     }
     async sendResponse(message, text, tabName) {
         // Discord quirk: first chunk uses message.reply so it threads under the
-        // original user message; follow-ups use channel.send. The shared helper
-        // takes a sendChunk callback so each channel keeps its platform-specific
-        // dispatch while sharing chunk + prefix + retry logic.
-        const full = formatTabbedResponse(text, tabName);
-        const chunks = chunkText(full, this.maxMessageLength);
-        for (let i = 0; i < chunks.length; i++) {
-            const isFirst = i === 0;
-            await retryWithBackoff(() => isFirst ? message.reply(chunks[i]) : message.channel.send(chunks[i]), [1000, 5000], isFirst ? 'discord-reply' : 'discord-send');
-        }
+        // original user message; follow-ups use channel.send. sendChunkedResponse
+        // handles prefix + chunking + retry envelope; the closure-tracked chunkIdx
+        // keeps the "first chunk replies, rest send" behavior.
+        let chunkIdx = 0;
+        await sendChunkedResponse({
+            text,
+            tabName,
+            maxLength: this.maxMessageLength,
+            retryDelays: [1000, 5000],
+            retryLabel: 'discord-send',
+            sendChunk: (chunk) => {
+                const isFirst = chunkIdx === 0;
+                chunkIdx++;
+                return isFirst ? message.reply(chunk) : message.channel.send(chunk);
+            },
+        });
     }
 }

package/dist/channels/index.d.ts

@@ -4,4 +4,4 @@ export { WhatsAppChannel } from './whatsapp.js';
 export { WebhookChannel } from './webhook.js';
 export { DiscordChannel } from './discord.js';
 export { loadCommunityChannels } from './loader.js';
-export type { Channel, ChannelContext, InboundMessage, InboundMessageHandler, MediaAttachment, SendOptions } from './types.js';
+export type { Channel, ChannelContext, MediaAttachment, SendOptions } from './types.js';

package/dist/channels/loader.js

@@ -47,8 +47,15 @@ export async function loadCommunityChannels(ctx) {
                         logger.warn(`Community channel ${dir}: entry point not found at ${entryPath}`);
                         continue;
                     }
-                    // Dynamic import — community channels run with full daemon access
-                    logger.warn(`Loading community channel from ${dir} — ensure you trust this package`);
+                    // Dynamic import — community channels run with full daemon access:
+                    // they can read every config token (Telegram, Discord, WhatsApp,
+                    // notification provider keys) AND every environment variable the
+                    // daemon inherits (including SSH-agent sockets, GitHub tokens,
+                    // anything sourced from your shell profile). A compromised
+                    // community-channel package is effectively a root credential drop.
+                    // Pin versions in package.json, audit before opting in, and treat
+                    // every entry in `communityChannels` as a trust anchor.
+                    logger.warn(`Loading community channel "${dir}" — this package will have FULL access to your channel tokens (Telegram/Discord/WhatsApp) and every environment variable inherited by the daemon (including SSH keys). Only enable if you trust the package author and have audited the version.`);
                     const module = await import(entryPath);
                     const ChannelClass = module.default || module[Object.keys(module)[0]];
                     if (!ChannelClass || typeof ChannelClass !== 'function') {
@@ -57,7 +64,10 @@ export async function loadCommunityChannels(ctx) {
                     }
                     const instance = new ChannelClass(ctx);
                     // Validate it implements Channel interface (duck typing)
-                    if (!instance.id || !instance.name || typeof instance.start !== 'function' || typeof instance.stop !== 'function') {
+                    if (!instance.id ||
+                        !instance.name ||
+                        typeof instance.start !== 'function' ||
+                        typeof instance.stop !== 'function') {
                         logger.warn(`Community channel ${dir}: does not implement Channel interface`);
                         continue;
                     }

package/dist/channels/pipeline.js

@@ -22,9 +22,20 @@ import { logger } from '../util/logger.js';
 export async function processInboundMessage(opts) {
     const { text, media, channelId, tabManager, voiceReplyMode, ttsProvider, userId, sendProgress, overrideTabName, onTextChunk, } = opts;
     // 1. Parse tab name and prompt from the message text
-    let { tabName, prompt: rawPrompt } = parseTabMessage(text);
-    // Allow channel to override tab name (group tabs, thread tabs, etc.)
+    const parsed = parseTabMessage(text);
+    const rawPrompt = parsed.prompt;
+    let tabName = parsed.tabName;
+    // Allow channel to override tab name (group tabs, thread tabs, etc.).
+    // Validate centrally so each channel doesn't need its own check — keeps the
+    // CLAUDE.md "validation is centralized" rule honest. `default` is allowed.
     if (overrideTabName) {
+        if (overrideTabName !== 'default') {
+            const { validateTabName } = await import('../config.js');
+            const overrideErr = validateTabName(overrideTabName);
+            if (overrideErr) {
+                return { responseText: `Invalid tab name: ${overrideErr}`, tabName, isError: true };
+            }
+        }
         tabName = overrideTabName;
     }
     if (!rawPrompt && media.length === 0) {
@@ -56,9 +67,7 @@ export async function processInboundMessage(opts) {
     progressTracker.stop();
     // 6. Build response text
     const isError = result.error;
-    const responseText = isError
-        ? `Error: ${result.text}`
-        : result.text || '(empty response)';
+    const responseText = isError ? `Error: ${result.text}` : result.text || '(empty response)';
     // 7. TTS voice reply (shared logic)
     let audioPath;
     let voiceOnly = false;

package/dist/channels/registry.d.ts

@@ -1,4 +1,5 @@
 import type { Channel } from './types.js';
+import type { MediaAttachment } from '../types.js';
 /**
  * ChannelRegistry manages the lifecycle of all channels.
  * Channels register themselves, and the registry handles start/stop/broadcast.
@@ -7,7 +8,12 @@ export declare class ChannelRegistry {
     private channels;
     /** Register a channel */
     register(channel: Channel): void;
-    /** Start all registered channels */
+    /**
+     * Start all registered channels in parallel. Each channel's start() is an
+     * independent network handshake (Telegram getMe, Discord login, WhatsApp
+     * Baileys boot) — running them sequentially adds 2-5s to cold start with no
+     * coordination benefit.
+     */
     start(): Promise<void>;
     /** Stop all channels */
     stop(): void;
@@ -17,4 +23,14 @@ export declare class ChannelRegistry {
     getAll(): Channel[];
     /** Broadcast a notification to all channels */
     broadcastNotify(text: string, urgent?: boolean): Promise<void>;
+    /**
+     * Broadcast a media attachment to every channel that supports it. Used by
+     * the pending-message dispatcher to deliver media queued by
+     * `beecork_send_media` and the `beecork_generate_*` tools — without this,
+     * those tools queue a row whose JSON envelope is never rendered.
+     *
+     * Channels that don't implement broadcastMedia get a sendNotification
+     * fallback so the user at least learns a file was generated.
+     */
+    broadcastMedia(media: MediaAttachment): Promise<void>;
 }

package/dist/channels/registry.js

@@ -13,9 +13,14 @@ export class ChannelRegistry {
         this.channels.set(channel.id, channel);
         logger.info(`Channel registered: ${channel.name} (${channel.id})`);
     }
-    /** Start all registered channels */
+    /**
+     * Start all registered channels in parallel. Each channel's start() is an
+     * independent network handshake (Telegram getMe, Discord login, WhatsApp
+     * Baileys boot) — running them sequentially adds 2-5s to cold start with no
+     * coordination benefit.
+     */
     async start() {
-        for (const [id, channel] of this.channels) {
+        await Promise.all(Array.from(this.channels.entries()).map(async ([id, channel]) => {
             try {
                 await channel.start();
                 logger.info(`Channel started: ${channel.name}`);
@@ -23,7 +28,7 @@ export class ChannelRegistry {
             catch (err) {
                 logger.error(`Failed to start channel ${id}:`, err);
             }
-        }
+        }));
     }
     /** Stop all channels */
     stop() {
@@ -46,6 +51,30 @@ export class ChannelRegistry {
     }
     /** Broadcast a notification to all channels */
     async broadcastNotify(text, urgent) {
-        await Promise.all(Array.from(this.channels.values()).map(channel => channel.sendNotification(text, urgent).catch(err => logger.warn(`${channel.name} notify failed:`, err))));
+        await Promise.all(Array.from(this.channels.values()).map((channel) => channel
+            .sendNotification(text, urgent)
+            .catch((err) => logger.warn(`${channel.name} notify failed:`, err))));
+    }
+    /**
+     * Broadcast a media attachment to every channel that supports it. Used by
+     * the pending-message dispatcher to deliver media queued by
+     * `beecork_send_media` and the `beecork_generate_*` tools — without this,
+     * those tools queue a row whose JSON envelope is never rendered.
+     *
+     * Channels that don't implement broadcastMedia get a sendNotification
+     * fallback so the user at least learns a file was generated.
+     */
+    async broadcastMedia(media) {
+        await Promise.all(Array.from(this.channels.values()).map((channel) => {
+            if (channel.broadcastMedia) {
+                return channel
+                    .broadcastMedia(media)
+                    .catch((err) => logger.warn(`${channel.name} broadcastMedia failed:`, err));
+            }
+            const fallback = `📎 Media generated: ${media.filePath}${media.caption ? `\n${media.caption}` : ''}`;
+            return channel
+                .sendNotification(fallback)
+                .catch((err) => logger.warn(`${channel.name} media-fallback notify failed:`, err));
+        }));
     }
 }

package/dist/channels/telegram.d.ts

@@ -1,30 +1,45 @@
-import type { Channel, ChannelContext, InboundMessageHandler, SendOptions } from './types.js';
+import type { Channel, ChannelContext, MediaAttachment, SendOptions } from './types.js';
 export declare class TelegramChannel implements Channel {
     readonly id = "telegram";
     readonly name = "Telegram";
     readonly maxMessageLength = 4096;
-    readonly supportsStreaming = true;
-    readonly supportsMedia = true;
     private bot;
     private ctx;
     private activeChatIds;
+    private allowedUserIdSet;
     private voice;
     private botUserId;
     private botUsername;
     private mutedGroups;
     private welcomeSent;
+    private pollingErrorTimes;
+    private pollingDegradedNotified;
     constructor(ctx: ChannelContext);
     start(): Promise<void>;
+    /**
+     * 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.
+     */
+    private recordPollingError;
     stop(): void;
-    sendMessage(peerId: string, text: string, options?: SendOptions): Promise<void>;
+    sendMessage(peerId: string, text: string, _options?: SendOptions): Promise<void>;
     sendNotification(message: string, _urgent?: boolean): Promise<void>;
+    /**
+     * 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).
+     */
+    broadcastMedia(media: MediaAttachment): Promise<void>;
     setTyping(peerId: string, active: boolean): Promise<void>;
-    onMessage(_handler: InboundMessageHandler): void;
     private setupHandlers;
     private handleCommand;
     private handleMessage;
     private sendResponse;
     private sendWithRetry;
+    private sendWithRetryRaw;
     private downloadTelegramFile;
     private isAllowed;
     private isAdmin;