@overpod/mcp-telegram 1.28.1 → 1.33.0

package/dist/tools/index.js

@@ -1,26 +1,36 @@
 import { registerAccountTools } from "./account.js";
 import { registerAuthTools } from "./auth.js";
 import { registerBoostTools } from "./boosts.js";
+import { registerBusinessTools } from "./business.js";
 import { registerChatTools } from "./chats.js";
 import { registerContactTools } from "./contacts.js";
 import { registerExtraTools } from "./extras.js";
+import { registerFactCheckTools } from "./fact-check.js";
+import { registerFolderTools } from "./folders.js";
 import { registerGroupCallTools } from "./group-calls.js";
 import { registerMediaTools } from "./media.js";
 import { registerMessageTools } from "./messages.js";
 import { registerQuickRepliesTools } from "./quick-replies.js";
 import { registerReactionTools } from "./reactions.js";
+import { registerSendMediaTools } from "./send-media.js";
 import { registerStarsTools } from "./stars.js";
 import { registerStickerTools } from "./stickers.js";
 import { registerStoryTools } from "./stories.js";
+import { registerTranscribeTools } from "./transcribe.js";
 export function registerTools(server, telegram) {
     registerAuthTools(server, telegram);
     registerMessageTools(server, telegram);
     registerChatTools(server, telegram);
     registerMediaTools(server, telegram);
+    registerSendMediaTools(server, telegram);
     registerContactTools(server, telegram);
     registerReactionTools(server, telegram);
+    registerTranscribeTools(server, telegram);
+    registerFactCheckTools(server, telegram);
     registerExtraTools(server, telegram);
     registerAccountTools(server, telegram);
+    registerBusinessTools(server, telegram);
+    registerFolderTools(server, telegram);
     registerStickerTools(server, telegram);
     registerStoryTools(server, telegram);
     registerBoostTools(server, telegram);

package/dist/tools/messages.js

@@ -1,22 +1,34 @@
 import { z } from "zod";
-import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
+import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, requireConnection, sanitizeInputText, WRITE, } from "./shared.js";
 export function registerMessageTools(server, telegram) {
     server.registerTool("telegram-send-message", {
         description: "Send a message to a Telegram chat",
         inputSchema: {
             chatId: z.string().describe("Chat ID or username (e.g. @username or numeric ID)"),
-            text: z.string().describe("Message text"),
+            text: z.string().transform(sanitizeInputText).describe("Message text"),
             replyTo: z.number().optional().describe("Message ID to reply to"),
             parseMode: z.enum(["md", "html"]).optional().describe("Message format: md (Markdown) or html"),
             topicId: z.number().optional().describe("Forum topic ID to send message into (for groups with Topics enabled)"),
+            quoteText: z
+                .string()
+                .transform(sanitizeInputText)
+                .optional()
+                .describe("Optional excerpt from the replied-to message to show as a quote above your reply. " +
+                "Requires `replyTo` to be set. Must be a verbatim substring of the original message text."),
+            effect: z
+                .string()
+                .regex(/^\d{1,19}$/)
+                .optional()
+                .describe("Optional message effect ID (numeric string, up to 19 digits). Premium animated effect attached to the message."),
         },
         annotations: WRITE,
-    }, async ({ chatId, text, replyTo, parseMode, topicId }) => {
+    }, async ({ chatId, text, replyTo, parseMode, topicId, quoteText, effect }) => {
         const err = await requireConnection(telegram);
         if (err)
             return fail(new Error(err));
         try {
-            const result = await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId);
+            const extra = quoteText || effect ? { quoteText, effect } : undefined;
+            const result = await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId, extra);
             const dest = topicId ? `topic ${topicId} in ${chatId}` : chatId;
             const messageId = result?.id;
             const idInfo = messageId ? ` [#${messageId}]` : "";
@@ -586,4 +598,171 @@ export function registerMessageTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-discussion-message", {
+        description: "For a channel post with comments enabled, returns the linked discussion-group info: discussionGroupId, discussionMsgId, unreadCount, readInboxMaxId, readOutboxMaxId, topMessage. Use discussionGroupId + discussionMsgId with telegram-send-message (replyTo=discussionMsgId) to post a comment.",
+        inputSchema: {
+            chatId: z.string().describe("Channel ID or @username that contains the post"),
+            messageId: z.number().int().positive().describe("ID of the channel post to get discussion info for"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getDiscussionMessage(chatId, messageId);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-groups-for-discussion", {
+        description: "List groups that can be linked as a discussion group to a channel you admin. Helper for channel admins setting up comment threads.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getGroupsForDiscussion();
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-message-read-participants", {
+        description: "List who has read a message in a small group (≤100 members, ≤7 days old). Returns readers with userId, readAt timestamp. Does NOT work for channels or groups over 100 members (CHAT_TOO_BIG).",
+        inputSchema: {
+            chatId: z.string().describe("Group chat ID or @username"),
+            messageId: z.number().int().positive().describe("ID of the message to check read status for"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getMessageReadParticipants(chatId, messageId);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    // ─── Poll interaction ──────────────────────────────────────────────────────
+    server.registerTool("telegram-vote-poll", {
+        description: "Vote in a poll by option index (single or multi-choice). Empty array retracts vote.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll"),
+            optionIndexes: z
+                .array(z.number().int().min(0).max(9))
+                .min(0)
+                .max(10)
+                .describe("Zero-based option indexes. Empty [] retracts vote."),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, optionIndexes }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.sendPollVote(chatId, messageId, optionIndexes);
+            if (optionIndexes.length === 0) {
+                return ok(`Retracted vote from poll #${messageId}`);
+            }
+            return ok(`Voted in poll #${messageId}: option(s) ${result.chosenLabels.join(", ")} | Total: ${result.totalVoters} voters`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-poll-results", {
+        description: "Get aggregated poll results: vote counts, percentages, quiz answer status",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPollResults(chatId, messageId);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-poll-voters", {
+        description: "List users who voted for specific poll options (public polls only, paginated)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll"),
+            optionIndex: z
+                .number()
+                .int()
+                .min(0)
+                .max(9)
+                .optional()
+                .describe("Zero-based option index to filter by. Omit to get all voters"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Max voters to return"),
+            offset: z.string().optional().describe("Pagination offset from previous call"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId, optionIndex, limit, offset }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPollVoters(chatId, messageId, { optionIndex, limit, offset });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-close-poll", {
+        description: "Close a poll permanently. This is a one-way operation — closed polls cannot be reopened.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            messageId: z.number().int().positive().describe("Message ID of the poll to close"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.closePoll(chatId, messageId);
+            return ok(`Closed poll #${messageId} (final: ${result.totalVoters} voters)`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-outbox-read-date", {
+        description: "Get when your recipient read your outgoing message in a private chat. Returns null/Not read yet if unread. Errors if the other side disabled read receipts (YOUR_PRIVACY_RESTRICTED / USER_PRIVACY_RESTRICTED).",
+        inputSchema: {
+            chatId: z.string().describe("Private chat ID or @username of the recipient"),
+            messageId: z.number().int().positive().describe("ID of your outgoing message"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, messageId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getOutboxReadDate(chatId, messageId);
+            return ok(result.readAt ? `Read at ${result.readAt}` : "Not read yet");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/reactions.js

@@ -161,4 +161,66 @@ export function registerReactionTools(server, telegram) {
             return fail(e);
         }
     });
+    // ─── Paid reactions ────────────────────────────────────────────────────────
+    server.registerTool("telegram-send-paid-reaction", {
+        description: "Send a paid reaction (★ Stars) on a channel post. Stars are spent from your balance. Optional private flag controls leaderboard visibility.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel)"),
+            messageId: z.number().int().positive().describe("Message ID of the channel post"),
+            count: z.number().int().min(1).max(2500).default(1).describe("Number of Stars to send (1-2500)"),
+            private: z
+                .boolean()
+                .optional()
+                .describe("true = anonymous on leaderboard, false = show name, omit = use account default"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, count, private: privateFlag }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.sendPaidReaction(chatId, messageId, count, { private: privateFlag });
+            const privacy = privateFlag === true ? " (anonymous)" : privateFlag === false ? " (public)" : "";
+            return ok(`Sent ★×${count} paid reaction to message #${messageId} in ${chatId}${privacy}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-toggle-paid-reaction-privacy", {
+        description: "Change leaderboard visibility of your paid reaction on a specific channel post (Layer 198 API).",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (channel)"),
+            messageId: z.number().int().positive().describe("Message ID of the channel post"),
+            private: z.boolean().describe("true = anonymous on leaderboard, false = show name"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, messageId, private: privateFlag }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.togglePaidReactionPrivacy(chatId, messageId, privateFlag);
+            return ok(`Updated paid reaction privacy on message #${messageId} in ${chatId}: ${privateFlag ? "anonymous" : "show name"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-paid-reaction-privacy", {
+        description: "Get your current default paid reaction privacy setting.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPaidReactionPrivacy();
+            return ok(`Default paid reaction privacy: ${result.private ? "anonymous" : "show name"}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/dist/tools/send-media.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerSendMediaTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/send-media.js

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { ABSOLUTE_PATH_ERROR, fail, isSafeAbsolutePath, ok, requireConnection, sanitizeInputText, WRITE, } from "./shared.js";
+const absolutePath = z.string().min(1).refine(isSafeAbsolutePath, ABSOLUTE_PATH_ERROR);
+const safeText = z.string().transform(sanitizeInputText);
+const DICE_EMOJIS = ["🎲", "🎯", "🎰", "🏀", "⚽", "🎳"];
+export function registerSendMediaTools(server, telegram) {
+    server.registerTool("telegram-send-voice", {
+        description: "Send a voice note (audio recording) to a Telegram chat. Shows as a voice message with waveform UI.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username (e.g. @username or numeric ID)"),
+            filePath: absolutePath.describe("Absolute local filesystem path to audio file (OGG/Opus preferred; M4A/MP3 also accepted). URLs are rejected."),
+            caption: safeText.optional().describe("Optional caption shown below the voice note"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID (for groups with Topics enabled)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Caption format: md (Markdown) or html"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, filePath, caption, replyTo, topicId, parseMode }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendVoice(chatId, filePath, {
+                caption,
+                replyTo,
+                topicId,
+                parseMode,
+            });
+            return ok(`Voice note sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-video-note", {
+        description: "Send a video note (round-shaped short video) to a Telegram chat. Shows as a circular video in the UI.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            filePath: absolutePath.describe("Absolute local filesystem path to video file (MP4 preferred, square source recommended for best look). URLs are rejected."),
+            duration: z.number().int().positive().max(60).optional().describe("Duration in seconds (Telegram caps at 60)"),
+            length: z
+                .number()
+                .int()
+                .positive()
+                .max(640)
+                .optional()
+                .describe("Frame edge length in pixels (the circle is square-cropped)"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, filePath, duration, length, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendVideoNote(chatId, filePath, {
+                duration,
+                length,
+                replyTo,
+                topicId,
+            });
+            return ok(`Video note sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-contact", {
+        description: "Send a contact card (phone number + name) to a Telegram chat.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            phone: z
+                .string()
+                .regex(/^\+?\d{6,15}$/)
+                .describe("Phone number in E.164-like format — 6-15 digits, optional leading +. " +
+                "Note: sent as-is; Telegram shows the number to the recipient."),
+            firstName: safeText.pipe(z.string().min(1).max(64)).describe("Contact first name"),
+            lastName: safeText.pipe(z.string().max(64)).optional().describe("Contact last name"),
+            vcard: safeText.pipe(z.string().max(2048)).optional().describe("Optional vCard v3.0 text content"),
+            replyTo: z.number().int().positive().optional(),
+            topicId: z.number().int().positive().optional(),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, phone, firstName, lastName, vcard, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendContact(chatId, phone, firstName, {
+                lastName,
+                vcard,
+                replyTo,
+                topicId,
+            });
+            return ok(`Contact sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-dice", {
+        description: "Send an animated dice/game emoji to a Telegram chat. Returns the server-rolled value — useful for games, " +
+            "coin-flips, random picks. Values: 🎲🎯🎳 = 1-6, 🏀⚽ = 1-5, 🎰 = slot combo 1-64.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            emoji: z
+                .enum(DICE_EMOJIS)
+                .default("🎲")
+                .describe("Dice emoji: 🎲 dice (1-6), 🎯 dart (1-6), 🎰 slot machine (1-64), 🏀 basketball (1-5), ⚽ football (1-5), 🎳 bowling (1-6)"),
+            replyTo: z.number().int().positive().optional(),
+            topicId: z.number().int().positive().optional(),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, emoji, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id, value } = await telegram.sendDice(chatId, emoji, { replyTo, topicId });
+            const rolled = value !== undefined ? `: rolled ${value}` : " (value pending)";
+            return ok(`Dice ${emoji} sent to ${chatId}${rolled} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-location", {
+        description: "Send a geographic location to a Telegram chat. Static pin by default; set livePeriod to share a live-updating location for N seconds.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            latitude: z.number().min(-90).max(90).describe("Latitude in decimal degrees (-90 to 90)"),
+            longitude: z.number().min(-180).max(180).describe("Longitude in decimal degrees (-180 to 180)"),
+            accuracyRadius: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Horizontal accuracy radius in meters (0 = unknown)"),
+            livePeriod: z
+                .number()
+                .int()
+                .min(60)
+                .max(86400)
+                .optional()
+                .describe("If set, sends a live location updated for N seconds (60-86400). Omit for static pin."),
+            heading: z
+                .number()
+                .int()
+                .min(1)
+                .max(360)
+                .optional()
+                .describe("Direction the user is heading, 1-360 degrees (meaningful only for live locations)"),
+            proximityRadius: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Alert radius for proximity notification in meters (live only)"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, latitude, longitude, accuracyRadius, livePeriod, heading, proximityRadius, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendLocation(chatId, latitude, longitude, {
+                accuracyRadius,
+                livePeriod,
+                heading,
+                proximityRadius,
+                replyTo,
+                topicId,
+            });
+            const label = livePeriod ? `Live location sent to ${chatId} for ${livePeriod}s` : `Location sent to ${chatId}`;
+            return ok(`${label} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-venue", {
+        description: "Send a venue card (point-of-interest with title and address) to a Telegram chat.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            latitude: z.number().min(-90).max(90).describe("Venue latitude"),
+            longitude: z.number().min(-180).max(180).describe("Venue longitude"),
+            title: safeText.pipe(z.string().min(1).max(256)).describe("Venue name (e.g. 'Red Square')"),
+            address: safeText.pipe(z.string().min(1).max(512)).describe("Street address"),
+            provider: safeText
+                .pipe(z.string().max(32))
+                .optional()
+                .describe("Data provider — typically 'foursquare' or 'gplaces'. Defaults to 'foursquare'."),
+            venueId: safeText.pipe(z.string().max(256)).optional().describe("Provider-specific venue ID"),
+            venueType: safeText.pipe(z.string().max(256)).optional().describe("Provider-specific venue type category"),
+            replyTo: z.number().int().positive().optional(),
+            topicId: z.number().int().positive().optional(),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, latitude, longitude, title, address, provider, venueId, venueType, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { id } = await telegram.sendVenue(chatId, latitude, longitude, title, address, {
+                provider,
+                venueId,
+                venueType,
+                replyTo,
+                topicId,
+            });
+            return ok(`Venue "${title}" sent to ${chatId} [#${id}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-album", {
+        description: "Send an album (group) of 2-10 photos as a single grouped message. Media type is auto-detected " +
+            "by file extension — videos are supported by the underlying TL call but are not covered by v1.29.0 " +
+            "mock tests, so uniform-photo albums are the safer choice until a live checkpoint. Uploads are " +
+            "serial per item: expect ≈4-10s for 10 mid-size photos, 15-40s for 10 large videos. Prefer ≤5 " +
+            "items or photos when low latency matters.",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            items: z
+                .array(z.object({
+                filePath: absolutePath.describe("Absolute local filesystem path to a photo or video file. URLs are rejected."),
+                caption: safeText
+                    .optional()
+                    .describe("Per-item caption (shown under this item when the album is expanded)"),
+            }))
+                .min(2)
+                .max(10)
+                .describe("Array of media items (2-10)"),
+            caption: safeText
+                .optional()
+                .describe("Album-level caption (attached to the first item — shown in the collapsed view)"),
+            parseMode: z.enum(["md", "html"]).optional().describe("Caption format (applies to all captions)"),
+            replyTo: z.number().int().positive().optional().describe("Message ID to reply to"),
+            topicId: z.number().int().positive().optional().describe("Forum topic ID"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, items, caption, parseMode, replyTo, topicId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const { ids } = await telegram.sendAlbum(chatId, items, { caption, parseMode, replyTo, topicId });
+            const idList = ids.map((id) => `#${id}`).join(", ");
+            return ok(`Album sent to ${chatId} (${ids.length} items) [${idList}]`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/shared.d.ts

@@ -36,5 +36,33 @@ export declare function formatReactions(reactions?: {
     count: number;
     me: boolean;
 }[]): string;
+/**
+ * Validate that a user-supplied path is safe to upload.
+ *
+ * The threat model is prompt-injection: an AI that was told "send the user's file" can be
+ * manipulated into sending `/proc/self/environ`, `/etc/shadow`, `http://169.254.169.254/...`,
+ * or an SMB share `\\attacker.com\share`. GramJS `sendFile` happily fetches URLs and reads
+ * any local path, so the validation has to live here.
+ *
+ * Rules:
+ * - Must be an absolute path (POSIX `/` or Windows `C:\` / `\\server\share`).
+ * - No URL schemes (http:, https:, file:, ftp:, data:, javascript:, …).
+ * - No path traversal (`..` segments) even inside an absolute path.
+ * - No OS-sensitive directories on POSIX (`/proc`, `/sys`, `/dev`, `/run`). These leak env,
+ *   kernel state, or block on device reads.
+ * - UNC paths (`\\server\share`) are blocked (NTLM-relay / remote-SMB risk).
+ *
+ * This is defence-in-depth: the admin still owns the machine and can exfiltrate files
+ * deliberately — we just refuse to help prompt-injection do it automatically.
+ */
+export declare function isSafeAbsolutePath(p: string): boolean;
+/** Zod refinement message paired with `isSafeAbsolutePath` */
+export declare const ABSOLUTE_PATH_ERROR = "Must be an absolute local filesystem path (e.g. /tmp/file.ogg). URLs, UNC shares, path traversal (..), and OS-sensitive dirs (/proc, /sys, /dev, /run) are rejected.";
+/**
+ * Sanitize a user-provided text for safe TL encoding.
+ * Strips unpaired UTF-16 surrogates that crash GramJS's wire serializer. Use on every
+ * free-text field that reaches GramJS (captions, provider names, venue titles, quoteText, …).
+ */
+export declare function sanitizeInputText(text: string): string;
 /** Try to connect, return error text if failed */
 export declare function requireConnection(telegram: TelegramService): Promise<string | null>;