verybot 0.1.8

package/dist/channels/slack/channel.js

@@ -0,0 +1,227 @@
+import { App } from "@slack/bolt";
+import { logger } from "../../logger.js";
+import { markdownToSlackMrkdwnChunks, escapeSlackMrkdwn, SLACK_TEXT_LIMIT } from "./markdown.js";
+import { CommandRouter } from "../commands.js";
+/** Emoji added while the bot is processing a message. */
+const TYPING_EMOJI = "eyes";
+/** Send chunked Slack mrkdwn to a channel. Optionally in-thread via threadTs. */
+async function sendMrkdwnChunks(app, channelId, text, resolveTableMode, threadTs) {
+    const tableMode = resolveTableMode();
+    const chunks = markdownToSlackMrkdwnChunks(text, SLACK_TEXT_LIMIT, { tableMode });
+    if (chunks.length === 0 && text) {
+        await app.client.chat.postMessage({ channel: channelId, text, thread_ts: threadTs });
+        return;
+    }
+    for (const chunk of chunks) {
+        await app.client.chat.postMessage({ channel: channelId, text: chunk, thread_ts: threadTs });
+    }
+}
+/** Strip the bot mention prefix (e.g. `<@U12345>`) from message text. */
+function stripBotMention(text, botUserId) {
+    const prefix = `<@${botUserId}>`;
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith(prefix)) {
+        return trimmed.slice(prefix.length).trim();
+    }
+    return text.trim();
+}
+export function createSlackChannel(opts) {
+    const { botToken, appToken, onMessage, onClear, onLearn, onRemember, listTeams, defaultTeamId, schedulerOpts, resolveTableMode = () => "code", } = opts;
+    const app = new App({
+        token: botToken,
+        appToken,
+        socketMode: true,
+    });
+    const commands = new CommandRouter({ onClear, onLearn, onRemember, listTeams, defaultTeamId });
+    /** Map<channelId, { teamId, connectionKey }> for active scheduler connections. */
+    const schedulerConnections = new Map();
+    /** Track active typing-proxy reaction timestamps per channel to avoid duplicate removals. */
+    const typingReactionTs = new Map();
+    /**
+     * Track thread context per channelId so replies stay in-thread.
+     * Note: in channels with concurrent @mentions, the latest message wins.
+     * DMs are safe since each DM conversation has a unique channelId.
+     */
+    const threadMap = new Map();
+    /** Format a CommandResult using Slack mrkdwn syntax. */
+    function formatSlackResult(result) {
+        return result.parts
+            .map((p) => {
+            if (typeof p === "string")
+                return escapeSlackMrkdwn(p);
+            if ("bold" in p)
+                return `*${escapeSlackMrkdwn(p.bold)}*`;
+            return `\`${p.code}\``;
+        })
+            .join("");
+    }
+    /**
+     * Handle text-based commands (e.g. "/clear", "/team foo").
+     * Returns true if the message was consumed as a command.
+     */
+    async function handleTextCommand(text, channelId) {
+        const result = await commands.handle("slack", channelId, text);
+        if (!result)
+            return false;
+        await app.client.chat.postMessage({ channel: channelId, text: formatSlackResult(result) });
+        return true;
+    }
+    /** Add a reaction as typing proxy; silently ignore failures. */
+    async function addTypingReaction(channelId, ts) {
+        let activeTs = typingReactionTs.get(channelId);
+        if (!activeTs) {
+            activeTs = new Set();
+            typingReactionTs.set(channelId, activeTs);
+        }
+        activeTs.add(ts);
+        try {
+            await app.client.reactions.add({ channel: channelId, timestamp: ts, name: TYPING_EMOJI });
+        }
+        catch {
+            // Reaction may already exist or bot lacks permission — safe to ignore
+        }
+    }
+    /** Remove typing reaction; silently ignore failures. */
+    async function removeTypingReaction(channelId, ts) {
+        const activeTs = typingReactionTs.get(channelId);
+        if (!activeTs?.has(ts))
+            return;
+        activeTs.delete(ts);
+        if (activeTs.size === 0)
+            typingReactionTs.delete(channelId);
+        try {
+            await app.client.reactions.remove({ channel: channelId, timestamp: ts, name: TYPING_EMOJI });
+        }
+        catch {
+            // Safe to ignore
+        }
+    }
+    const channel = {
+        name: "slack",
+        start: async () => {
+            // --- @mention events (channels/groups) ---
+            app.event("app_mention", async ({ event, context }) => {
+                const channelId = event.channel;
+                const userId = event.user ?? "unknown";
+                const botUserId = context.botUserId ?? "";
+                const rawText = event.text ?? "";
+                const text = stripBotMention(rawText, botUserId);
+                const ts = event.ts;
+                const threadTs = event.thread_ts ?? ts;
+                if (!text)
+                    return;
+                if (await handleTextCommand(text, channelId))
+                    return;
+                logger.info(`[slack] mention from ${userId} in ${channelId}`);
+                threadMap.set(channelId, { threadTs, messageTs: ts });
+                await addTypingReaction(channelId, ts);
+                try {
+                    await onMessage({
+                        channelType: "slack",
+                        channelId,
+                        userId,
+                        text,
+                        teamId: commands.resolveTeamId(channelId),
+                    }, channel);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logger.error(`[slack] error handling mention in ${channelId}: ${msg}`);
+                }
+                finally {
+                    await removeTypingReaction(channelId, ts);
+                }
+            });
+            // --- DM events ---
+            app.event("message", async ({ event, context }) => {
+                // Only handle direct messages (im channel type)
+                // Skip bot messages, changed messages, etc.
+                if (!("channel_type" in event) || event.channel_type !== "im")
+                    return;
+                if ("subtype" in event && event.subtype)
+                    return;
+                if (!("user" in event) || !event.user)
+                    return;
+                if (!("text" in event) || !event.text)
+                    return;
+                // Ignore messages from the bot itself
+                if (event.user === context.botUserId)
+                    return;
+                const channelId = event.channel;
+                const userId = event.user;
+                const botUserId = context.botUserId ?? "";
+                // Strip bot mention so "@bot /clear" is matched as "/clear"
+                const text = stripBotMention(event.text, botUserId);
+                const ts = event.ts;
+                const threadTs = ("thread_ts" in event ? event.thread_ts : undefined) ?? ts;
+                if (!text)
+                    return;
+                if (await handleTextCommand(text, channelId))
+                    return;
+                logger.info(`[slack] DM from ${userId}`);
+                threadMap.set(channelId, { threadTs, messageTs: ts });
+                await addTypingReaction(channelId, ts);
+                try {
+                    await onMessage({
+                        channelType: "slack",
+                        channelId,
+                        userId,
+                        text,
+                        teamId: commands.resolveTeamId(channelId),
+                    }, channel);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logger.error(`[slack] error handling DM from ${userId}: ${msg}`);
+                }
+                finally {
+                    await removeTypingReaction(channelId, ts);
+                }
+            });
+            await app.start();
+            logger.info("[slack] connected via Socket Mode");
+        },
+        stop: async () => {
+            for (const [, conn] of schedulerConnections) {
+                schedulerOpts?.disconnectScheduler(conn.teamId, conn.connectionKey);
+            }
+            schedulerConnections.clear();
+            await app.stop();
+            logger.info("[slack] disconnected");
+        },
+        send: async (channelId, text) => {
+            const entry = threadMap.get(channelId);
+            await sendMrkdwnChunks(app, channelId, text, resolveTableMode, entry?.threadTs);
+            if (entry) {
+                await removeTypingReaction(channelId, entry.messageTs);
+            }
+        },
+        readHistory: async (channelId, limit = 20, threadTs) => {
+            logger.info(`[slack] readHistory channel=${channelId} limit=${limit} threadTs=${threadTs ?? "none"}`);
+            let raw;
+            if (threadTs) {
+                const result = await app.client.conversations.replies({
+                    channel: channelId,
+                    ts: threadTs,
+                    limit,
+                });
+                raw = result.messages ?? [];
+            }
+            else {
+                const result = await app.client.conversations.history({
+                    channel: channelId,
+                    limit,
+                });
+                // conversations.history returns newest-first, reverse for chronological
+                raw = (result.messages ?? []).reverse();
+            }
+            logger.info(`[slack] readHistory returned ${raw.length} messages for ${channelId}`);
+            return raw.map((msg) => ({
+                user: msg.user ?? "bot",
+                text: msg.text ?? "",
+                ts: msg.ts ?? "",
+            }));
+        },
+    };
+    return channel;
+}

package/dist/channels/slack/markdown.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Markdown → Slack mrkdwn conversion.
+ * Slack uses a custom markdown-like format called "mrkdwn".
+ */
+import { type MarkdownTableMode } from "../../markdown/ir.js";
+/** Slack mrkdwn uses &, <, > as control chars — escape them in plain text. */
+export declare function escapeSlackMrkdwn(text: string): string;
+export declare function markdownToSlackMrkdwn(markdown: string, options?: {
+    tableMode?: MarkdownTableMode;
+}): string;
+/** Slack message limit (text blocks). */
+export declare const SLACK_TEXT_LIMIT = 4000;
+/**
+ * Convert markdown to chunked Slack mrkdwn strings.
+ * Each chunk is ≤ `limit` characters of plain-text IR.
+ */
+export declare function markdownToSlackMrkdwnChunks(markdown: string, limit?: number, options?: {
+    tableMode?: MarkdownTableMode;
+}): string[];

package/dist/channels/slack/markdown.js

@@ -0,0 +1,62 @@
+/**
+ * Markdown → Slack mrkdwn conversion.
+ * Slack uses a custom markdown-like format called "mrkdwn".
+ */
+import { chunkMarkdownIR, markdownToIR, } from "../../markdown/ir.js";
+import { renderMarkdownWithMarkers } from "../../markdown/render.js";
+const SAFE_LINK_PROTOCOL = /^https?:\/\/|^mailto:|^tel:/i;
+/** Slack mrkdwn uses &, <, > as control chars — escape them in plain text. */
+export function escapeSlackMrkdwn(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function buildSlackLink(link, _text) {
+    const href = link.href.trim();
+    if (!href || link.start === link.end)
+        return null;
+    if (!SAFE_LINK_PROTOCOL.test(href))
+        return null;
+    return {
+        start: link.start,
+        end: link.end,
+        open: `<${escapeSlackMrkdwn(href)}|`,
+        close: ">",
+    };
+}
+function renderSlackMrkdwn(ir) {
+    return renderMarkdownWithMarkers(ir, {
+        styleMarkers: {
+            bold: { open: "*", close: "*" },
+            italic: { open: "_", close: "_" },
+            strikethrough: { open: "~", close: "~" },
+            code: { open: "`", close: "`" },
+            code_block: { open: "```\n", close: "\n```" },
+        },
+        escapeText: escapeSlackMrkdwn,
+        buildLink: buildSlackLink,
+    });
+}
+export function markdownToSlackMrkdwn(markdown, options = {}) {
+    const ir = markdownToIR(markdown ?? "", {
+        linkify: true,
+        headingStyle: "none",
+        blockquotePrefix: "> ",
+        tableMode: options.tableMode,
+    });
+    return renderSlackMrkdwn(ir);
+}
+/** Slack message limit (text blocks). */
+export const SLACK_TEXT_LIMIT = 4000;
+/**
+ * Convert markdown to chunked Slack mrkdwn strings.
+ * Each chunk is ≤ `limit` characters of plain-text IR.
+ */
+export function markdownToSlackMrkdwnChunks(markdown, limit = SLACK_TEXT_LIMIT, options = {}) {
+    const ir = markdownToIR(markdown ?? "", {
+        linkify: true,
+        headingStyle: "none",
+        blockquotePrefix: "> ",
+        tableMode: options.tableMode,
+    });
+    const chunks = chunkMarkdownIR(ir, limit);
+    return chunks.map((chunk) => renderSlackMrkdwn(chunk));
+}

package/dist/channels/specs.d.ts

@@ -0,0 +1,32 @@
+import type { MessageHandler } from "./types.js";
+import type { ChannelSpec } from "./manager.js";
+import type { MarkdownTableMode } from "../markdown/ir.js";
+import type { ConnectedChannelRegistry } from "../scheduler/connected-channels.js";
+import type { Config } from "../config.js";
+export interface ChannelCallbacks {
+    onMessage: MessageHandler;
+    onClear: (channelType: string, channelId: string, teamId?: string) => Promise<void>;
+    onLearn: (channelType: string, channelId: string, topic?: string, teamId?: string) => Promise<{
+        topic?: string;
+        extracted: number;
+        saved: number;
+        skipped: number;
+        savedFacts: string[];
+    }>;
+    onRemember: (channelType: string, channelId: string, fact: string, teamId?: string) => Promise<{
+        saved: boolean;
+        fact: string;
+    }>;
+    listTeams: () => {
+        id: string;
+        name: string;
+    }[];
+    connectedChannels: ConnectedChannelRegistry | null;
+    /** Return the raw per-channel table config value (resolved lazily at send time). */
+    getChannelTableConfig: (channel: string) => MarkdownTableMode | string | null | undefined;
+}
+/**
+ * Build channel specs from config. Pure function — all side effects are
+ * deferred via callbacks so agent.ts stays thin.
+ */
+export declare function buildChannelSpecs(config: Config, cb: ChannelCallbacks): ChannelSpec[];

package/dist/channels/specs.js

@@ -0,0 +1,99 @@
+import { channelFingerprint } from "./manager.js";
+import { createTelegramChannel } from "./telegram/channel.js";
+import { createDiscordChannel } from "./discord/channel.js";
+import { createSlackChannel } from "./slack/channel.js";
+import { createWhatsAppChannel } from "./whatsapp/channel.js";
+import { resolveMarkdownTableMode } from "../markdown/tables.js";
+/** Build scheduler opts shared across channels. */
+function buildSchedulerOpts(channelType, connectedChannels) {
+    return {
+        connectScheduler: (teamId, channelId, sendFn) => connectedChannels.connect(teamId, {
+            channelType,
+            channelId,
+            send: sendFn,
+        }),
+        disconnectScheduler: (teamId, key) => connectedChannels.disconnect(teamId, key),
+    };
+}
+/**
+ * Build channel specs from config. Pure function — all side effects are
+ * deferred via callbacks so agent.ts stays thin.
+ */
+export function buildChannelSpecs(config, cb) {
+    const specs = [];
+    if (config.channels.telegram) {
+        const token = config.channels.telegram.token;
+        const resolveTableMode = () => resolveMarkdownTableMode({ channel: "telegram", channelTableMode: cb.getChannelTableConfig("telegram") });
+        specs.push({
+            name: "telegram",
+            fingerprint: channelFingerprint(token),
+            create: () => createTelegramChannel({
+                token,
+                listTeams: cb.listTeams,
+                onMessage: cb.onMessage,
+                onClear: cb.onClear,
+                onLearn: cb.onLearn,
+                onRemember: cb.onRemember,
+                resolveTableMode,
+            }),
+        });
+    }
+    if (config.channels.discord) {
+        const token = config.channels.discord.token;
+        const resolveTableMode = () => resolveMarkdownTableMode({ channel: "discord", channelTableMode: cb.getChannelTableConfig("discord") });
+        specs.push({
+            name: "discord",
+            fingerprint: channelFingerprint(token),
+            create: () => createDiscordChannel({
+                token,
+                listTeams: cb.listTeams,
+                onMessage: cb.onMessage,
+                onClear: cb.onClear,
+                onLearn: cb.onLearn,
+                onRemember: cb.onRemember,
+                resolveTableMode,
+            }),
+        });
+    }
+    if (config.channels.slack) {
+        const { botToken, appToken } = config.channels.slack;
+        const resolveTableMode = () => resolveMarkdownTableMode({ channel: "slack", channelTableMode: cb.getChannelTableConfig("slack") });
+        const schedulerOpts = cb.connectedChannels
+            ? buildSchedulerOpts("slack", cb.connectedChannels)
+            : undefined;
+        specs.push({
+            name: "slack",
+            fingerprint: channelFingerprint(botToken + appToken),
+            create: () => createSlackChannel({
+                botToken,
+                appToken,
+                listTeams: cb.listTeams,
+                onMessage: cb.onMessage,
+                onClear: cb.onClear,
+                onLearn: cb.onLearn,
+                onRemember: cb.onRemember,
+                schedulerOpts,
+                resolveTableMode,
+            }),
+        });
+    }
+    if (config.channels.whatsapp) {
+        const { phoneId } = config.channels.whatsapp;
+        const resolveTableMode = () => resolveMarkdownTableMode({ channel: "whatsapp", channelTableMode: cb.getChannelTableConfig("whatsapp") });
+        specs.push({
+            name: "whatsapp",
+            fingerprint: channelFingerprint(phoneId),
+            create: () => createWhatsAppChannel({
+                phoneId,
+                selfOnly: config.channels.whatsapp?.selfOnly,
+                listTeams: cb.listTeams,
+                onMessage: cb.onMessage,
+                onClear: cb.onClear,
+                onLearn: cb.onLearn,
+                onRemember: cb.onRemember,
+                resolveTableMode,
+            }),
+        });
+    }
+    return specs;
+}

package/dist/channels/telegram/channel.d.ts

@@ -0,0 +1,29 @@
+import type { Channel, MessageHandler } from "../types.js";
+import type { MarkdownTableMode } from "../../markdown/ir.js";
+/** Callback that resolves the current table mode from config at send time. */
+export type ResolveTableMode = () => MarkdownTableMode;
+export interface CreateTelegramChannelOpts {
+    token: string;
+    onMessage: MessageHandler;
+    onClear?: (channelType: string, channelId: string, teamId?: string) => Promise<void>;
+    onLearn?: (channelType: string, channelId: string, topic?: string, teamId?: string) => Promise<{
+        topic?: string;
+        extracted: number;
+        saved: number;
+        skipped: number;
+        savedFacts: string[];
+    }>;
+    onRemember?: (channelType: string, channelId: string, fact: string, teamId?: string) => Promise<{
+        saved: boolean;
+        fact: string;
+    }>;
+    /** List available teams for the /team command. */
+    listTeams?: () => {
+        id: string;
+        name: string;
+    }[];
+    /** Fallback team when no active team is set for a chat. */
+    defaultTeamId?: string;
+    resolveTableMode?: ResolveTableMode;
+}
+export declare function createTelegramChannel(opts: CreateTelegramChannelOpts): Channel;

package/dist/channels/telegram/channel.js

@@ -0,0 +1,182 @@
+import { Bot, InputFile } from "grammy";
+import { transcribe } from "../../tts/transcribe.js";
+import { logger } from "../../logger.js";
+import { markdownToTelegramHtmlChunks, escapeHtml } from "./markdown.js";
+import { CommandRouter } from "../commands.js";
+const TELEGRAM_TEXT_LIMIT = 4000;
+/** Send chunked HTML to a Telegram chat. Handles markdown→HTML conversion + splitting. */
+async function sendHtmlChunks(bot, chatId, text, resolveTableMode) {
+    const tableMode = resolveTableMode();
+    const chunks = markdownToTelegramHtmlChunks(text, TELEGRAM_TEXT_LIMIT, { tableMode });
+    if (chunks.length === 0 && text) {
+        // Fallback: if conversion produced nothing, send raw text
+        await bot.api.sendMessage(chatId, text);
+        return;
+    }
+    for (const chunk of chunks) {
+        await bot.api.sendMessage(chatId, chunk, { parse_mode: "HTML" });
+    }
+}
+export function createTelegramChannel(opts) {
+    const { token, onMessage, onClear, onLearn, onRemember, listTeams, defaultTeamId, resolveTableMode = () => "code", } = opts;
+    const bot = new Bot(token);
+    const typingIntervals = new Map();
+    const commands = new CommandRouter({ onClear, onLearn, onRemember, listTeams, defaultTeamId });
+    /** Format a CommandResult using Telegram HTML syntax. */
+    function formatTelegramResult(result) {
+        return result.parts
+            .map((p) => {
+            if (typeof p === "string")
+                return escapeHtml(p);
+            if ("bold" in p)
+                return `<b>${escapeHtml(p.bold)}</b>`;
+            return `<code>${escapeHtml(p.code)}</code>`;
+        })
+            .join("");
+    }
+    function startTyping(chatId) {
+        stopTyping(chatId);
+        const numId = Number(chatId);
+        // Send immediately, then every 4s (Telegram typing expires after ~5s)
+        bot.api.sendChatAction(numId, "typing").catch((err) => logger.error(`typing error: ${err}`));
+        logger.info(`typing started for ${chatId}`);
+        const interval = setInterval(() => {
+            bot.api.sendChatAction(numId, "typing").catch((err) => logger.error(`typing interval error: ${err}`));
+        }, 4000);
+        typingIntervals.set(chatId, interval);
+    }
+    function stopTyping(chatId) {
+        const interval = typingIntervals.get(chatId);
+        if (interval) {
+            clearInterval(interval);
+            typingIntervals.delete(chatId);
+        }
+    }
+    const channel = {
+        name: "telegram",
+        start: async () => {
+            for (const cmd of ["clear", "reset"]) {
+                bot.command(cmd, async (ctx) => {
+                    const chatId = String(ctx.chat.id);
+                    const result = await commands.handleClear("telegram", chatId);
+                    await ctx.reply(formatTelegramResult(result), { parse_mode: "HTML" });
+                });
+            }
+            // --- /team command for multi-team switching ---
+            if (listTeams) {
+                bot.command("team", async (ctx) => {
+                    try {
+                        const chatId = String(ctx.chat.id);
+                        const arg = ctx.match?.trim() ?? "";
+                        const result = await commands.handleTeam("telegram", chatId, arg);
+                        await ctx.reply(formatTelegramResult(result), { parse_mode: "HTML" });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        logger.error(`[telegram] /team command failed: ${msg}`);
+                        await ctx.reply("Failed to process team command. Please try again.");
+                    }
+                });
+            }
+            for (const cmd of ["learn", "remember"]) {
+                bot.command(cmd, async (ctx) => {
+                    try {
+                        const chatId = String(ctx.chat.id);
+                        const arg = ctx.match?.trim() ?? "";
+                        const text = arg ? `/${cmd} ${arg}` : `/${cmd}`;
+                        const result = await commands.handle("telegram", chatId, text);
+                        if (!result)
+                            return;
+                        await ctx.reply(formatTelegramResult(result), { parse_mode: "HTML" });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        logger.error(`[telegram] /${cmd} command failed: ${msg}`);
+                        await ctx.reply("Failed to process memory command. Please try again.");
+                    }
+                });
+            }
+            bot.on("message:voice", async (ctx) => {
+                const chatId = String(ctx.chat.id);
+                logger.info(`[telegram] voice message received from ${chatId}`);
+                startTyping(chatId);
+                try {
+                    const file = await ctx.getFile();
+                    const url = `https://api.telegram.org/file/bot${token}/${file.file_path}`;
+                    const res = await fetch(url);
+                    if (!res.ok)
+                        throw new Error(`Download failed: ${res.status}`);
+                    const buffer = Buffer.from(await res.arrayBuffer());
+                    const text = await transcribe(buffer, file.file_path ?? "voice.ogg");
+                    logger.info(`[telegram] transcribed voice: "${text.slice(0, 100)}"`);
+                    await onMessage({
+                        channelType: "telegram",
+                        channelId: chatId,
+                        userId: String(ctx.from.id),
+                        text,
+                        isVoice: true,
+                        teamId: commands.resolveTeamId(chatId),
+                    }, channel);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logger.error(`[telegram] voice transcription failed: ${msg}`);
+                    await ctx.reply("Sorry, I couldn't process your voice message.");
+                }
+                finally {
+                    stopTyping(chatId);
+                }
+            });
+            bot.on("message:text", async (ctx) => {
+                // Skip bot commands — registered ones are handled by bot.command(),
+                // unregistered ones (e.g. /help) should not be forwarded as text
+                const entities = ctx.message.entities ?? [];
+                if (entities.some((e) => e.type === "bot_command" && e.offset === 0))
+                    return;
+                const chatId = String(ctx.chat.id);
+                logger.info(`[telegram] message received from ${chatId}`);
+                startTyping(chatId);
+                try {
+                    await onMessage({
+                        channelType: "telegram",
+                        channelId: chatId,
+                        userId: String(ctx.from.id),
+                        text: ctx.message.text,
+                        teamId: commands.resolveTeamId(chatId),
+                    }, channel);
+                }
+                finally {
+                    stopTyping(chatId);
+                }
+            });
+            // Register commands with Telegram so they appear in the "/" menu
+            const menuCommands = [
+                { command: "clear", description: "Clear the current session." },
+                { command: "reset", description: "Clear the current session." },
+                { command: "learn", description: "Teach me a fact to remember." },
+            ];
+            if (listTeams) {
+                menuCommands.push({ command: "team", description: "List or switch teams." });
+            }
+            bot.start();
+            // setMyCommands after start() so Grammy has initialized the bot
+            bot.api.setMyCommands(menuCommands).then(() => logger.info(`[telegram] registered ${menuCommands.length} commands`), (err) => logger.error(`[telegram] setMyCommands failed: ${err}`));
+        },
+        stop: async () => {
+            for (const chatId of typingIntervals.keys())
+                stopTyping(chatId);
+            await bot.stop();
+        },
+        send: async (channelId, text) => {
+            stopTyping(channelId);
+            await sendHtmlChunks(bot, Number(channelId), text, resolveTableMode);
+        },
+        sendVoice: async (channelId, audioPath) => {
+            stopTyping(channelId);
+            const chatId = Number(channelId);
+            await bot.api.sendVoice(chatId, new InputFile(audioPath));
+            logger.info(`[telegram] voice message sent to ${channelId}`);
+        },
+    };
+    return channel;
+}

package/dist/channels/telegram/markdown.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Markdown → Telegram HTML conversion.
+ * Markdown to Telegram HTML conversion.
+ */
+import { type MarkdownTableMode } from "../../markdown/ir.js";
+export declare function escapeHtml(text: string): string;
+export declare function markdownToTelegramHtml(markdown: string, options?: {
+    tableMode?: MarkdownTableMode;
+}): string;
+/**
+ * Convert markdown to chunked Telegram HTML strings.
+ * Each chunk is ≤ `limit` characters of the plain-text IR (the HTML tags
+ * add overhead but Telegram counts the visible text).
+ */
+export declare function markdownToTelegramHtmlChunks(markdown: string, limit: number, options?: {
+    tableMode?: MarkdownTableMode;
+}): string[];