@asermax/tachikoma 2.0.0

package/dist/extensions/telegram/chunking.js

@@ -0,0 +1,67 @@
+// Telegram's hard limit, in UTF-16 code units — exactly what JS string length measures.
+export const TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
+/**
+ * Split text into chunks within Telegram's message length limit, preferring
+ * paragraph boundaries, then line boundaries, then a hard split that never
+ * cuts a surrogate pair in half.
+ */
+export const splitMessage = (text, limit = TELEGRAM_MAX_MESSAGE_LENGTH) => {
+    if (text.length <= limit)
+        return [text];
+    const chunks = [];
+    let current = "";
+    for (const paragraph of text.split("\n\n")) {
+        for (const piece of splitParagraph(paragraph, limit)) {
+            const joined = current.length > 0 ? `${current}\n\n${piece}` : piece;
+            if (joined.length <= limit) {
+                current = joined;
+            }
+            else {
+                if (current.length > 0)
+                    chunks.push(current);
+                current = piece;
+            }
+        }
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+};
+const splitParagraph = (paragraph, limit) => {
+    if (paragraph.length <= limit)
+        return [paragraph];
+    const pieces = [];
+    let current = "";
+    for (const line of paragraph.split("\n")) {
+        for (const fragment of hardSplit(line, limit)) {
+            const joined = current.length > 0 ? `${current}\n${fragment}` : fragment;
+            if (joined.length <= limit) {
+                current = joined;
+            }
+            else {
+                if (current.length > 0)
+                    pieces.push(current);
+                current = fragment;
+            }
+        }
+    }
+    if (current.length > 0)
+        pieces.push(current);
+    return pieces;
+};
+const hardSplit = (line, limit) => {
+    if (line.length <= limit)
+        return [line];
+    const fragments = [];
+    let start = 0;
+    while (start < line.length) {
+        let end = Math.min(start + limit, line.length);
+        if (end < line.length && isLowSurrogate(line.charCodeAt(end)))
+            end -= 1;
+        fragments.push(line.slice(start, end));
+        start = end;
+    }
+    return fragments;
+};
+const isLowSurrogate = (code) => code >= 0xdc00 && code <= 0xdfff;
+//# sourceMappingURL=chunking.js.map

package/dist/extensions/telegram/chunking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.js","sourceRoot":"","sources":["../../../src/extensions/telegram/chunking.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,KAAK,GAAG,2BAA2B,EAAY,EAAE;IAC1F,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,OAAO,GAAG,EAAE,CAAC;IAEjB,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3C,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC;YACrD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;YAErE,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;gBAC3B,OAAO,GAAG,MAAM,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;oBAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC7C,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE7C,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,SAAiB,EAAE,KAAa,EAAY,EAAE;IACpE,IAAI,SAAS,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAElD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,OAAO,GAAG,EAAE,CAAC;IAEjB,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;YAEzE,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;gBAC3B,OAAO,GAAG,MAAM,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;oBAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC7C,OAAO,GAAG,QAAQ,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE7C,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,KAAa,EAAY,EAAE;IAC1D,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3B,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAE/C,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YAAE,GAAG,IAAI,CAAC,CAAC;QAExE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QACvC,KAAK,GAAG,GAAG,CAAC;IACd,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC"}

package/dist/extensions/telegram/inbound.d.ts

@@ -0,0 +1,7 @@
+import type { Message } from "grammy/types";
+import type { InboundMessage, MediaAttachment } from "../../domain/message.ts";
+export declare const CHANNEL_NAME = "telegram";
+export declare const mapTextMessage: (message: Pick<Message, "text" | "message_id">) => InboundMessage | null;
+export declare const mapMediaMessage: (message: Pick<Message, "caption" | "message_id">, attachment: MediaAttachment) => InboundMessage;
+/** Frame a button tap so the agent can distinguish it from typed input. */
+export declare const mapButtonTap: (value: string, messageId: number | null) => InboundMessage;

package/dist/extensions/telegram/inbound.js

@@ -0,0 +1,29 @@
+export const CHANNEL_NAME = "telegram";
+export const mapTextMessage = (message) => {
+    const text = message.text?.trim() ?? "";
+    if (text.length === 0)
+        return null;
+    return {
+        text,
+        channel: CHANNEL_NAME,
+        receivedAt: new Date(),
+        media: [],
+        metadata: { messageId: message.message_id },
+    };
+};
+export const mapMediaMessage = (message, attachment) => ({
+    text: message.caption?.trim() ?? "",
+    channel: CHANNEL_NAME,
+    receivedAt: new Date(),
+    media: [attachment],
+    metadata: { messageId: message.message_id },
+});
+/** Frame a button tap so the agent can distinguish it from typed input. */
+export const mapButtonTap = (value, messageId) => ({
+    text: `The user tapped the option \`${value}\` out of the options you displayed.`,
+    channel: CHANNEL_NAME,
+    receivedAt: new Date(),
+    media: [],
+    metadata: { buttonValue: value, ...(messageId != null ? { messageId } : {}) },
+});
+//# sourceMappingURL=inbound.js.map

package/dist/extensions/telegram/inbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.js","sourceRoot":"","sources":["../../../src/extensions/telegram/inbound.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEvC,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,OAA6C,EACtB,EAAE;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAExC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,YAAY;QACrB,UAAU,EAAE,IAAI,IAAI,EAAE;QACtB,KAAK,EAAE,EAAE;QACT,QAAQ,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE;KAC5C,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAAgD,EAChD,UAA2B,EACX,EAAE,CAAC,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;IACnC,OAAO,EAAE,YAAY;IACrB,UAAU,EAAE,IAAI,IAAI,EAAE;IACtB,KAAK,EAAE,CAAC,UAAU,CAAC;IACnB,QAAQ,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE;CAC5C,CAAC,CAAC;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAa,EAAE,SAAwB,EAAkB,EAAE,CAAC,CAAC;IACxF,IAAI,EAAE,gCAAgC,KAAK,sCAAsC;IACjF,OAAO,EAAE,YAAY;IACrB,UAAU,EAAE,IAAI,IAAI,EAAE;IACtB,KAAK,EAAE,EAAE;IACT,QAAQ,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;CAC9E,CAAC,CAAC"}

package/dist/extensions/telegram/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Telegram channel: grammY long-polling bot restricted to a single chat, media
+ * download into the workspace data dir, and agent tools for sending files,
+ * reactions, pins, and inline-button prompts through the shared bot instance.
+ */
+declare const _default: import("../api.ts").TachikomaExtension<{
+    chatId: number;
+    botToken: string;
+    allowMedia: boolean;
+    pushNotifications: boolean;
+    extraFileRoots: string[];
+}>;
+export default _default;

package/dist/extensions/telegram/index.js

@@ -0,0 +1,67 @@
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { Bot } from "grammy";
+import { Type } from "typebox";
+import { expandHome } from "../../workspace.js";
+import { defineExtension } from "../api.js";
+import { TelegramChannel } from "./channel.js";
+import { ensureMediaDir } from "./media.js";
+import { registerTelegramTools } from "./tools.js";
+const TelegramConfigSchema = Type.Object({
+    botToken: Type.String({ default: "", description: "Telegram bot token from @BotFather" }),
+    chatId: Type.Number({ default: 0, description: "Authorized Telegram chat ID" }),
+    allowMedia: Type.Boolean({ default: true, description: "Accept inbound media attachments" }),
+    pushNotifications: Type.Boolean({
+        default: true,
+        description: "Fire push notifications for background deliveries via copy+delete",
+    }),
+    extraFileRoots: Type.Array(Type.String(), {
+        default: [],
+        description: "Extra absolute roots send_telegram_file may read from",
+    }),
+});
+/**
+ * Telegram channel: grammY long-polling bot restricted to a single chat, media
+ * download into the workspace data dir, and agent tools for sending files,
+ * reactions, pins, and inline-button prompts through the shared bot instance.
+ */
+export default defineExtension({
+    name: "telegram",
+    configSchema: TelegramConfigSchema,
+    setup(app) {
+        const { botToken, chatId, allowMedia, pushNotifications, extraFileRoots } = app.extensionConfig;
+        if (botToken === "" || chatId === 0) {
+            app.log.info("telegram channel disabled — set botToken and chatId under [extensions.telegram]");
+            return;
+        }
+        const bot = new Bot(botToken);
+        const mediaDir = join(app.workspace.dataDir, "media");
+        const channel = new TelegramChannel(bot, {
+            chatId,
+            allowMedia,
+            pushNotifications,
+            mediaDir,
+            stop: () => app.sessions.abortExchange(),
+        });
+        app.bootstrap("media-dir", () => ensureMediaDir(mediaDir, app.log));
+        app.channels.register(channel);
+        const allowedRoots = [
+            ...new Set([
+                app.workspace.root,
+                tmpdir(),
+                ...extraFileRoots.map((root) => resolve(expandHome(root))),
+            ]),
+        ];
+        app.agent.use((pi) => {
+            registerTelegramTools(pi, {
+                api: bot.api,
+                chatId,
+                workspaceRoot: app.workspace.root,
+                allowedRoots,
+                getLastInboundMessageId: () => channel.lastInboundMessageId,
+                getLastOutboundMessageId: () => channel.lastOutboundMessageId,
+            });
+        });
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/extensions/telegram/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/extensions/telegram/index.ts"],"names":[],"mappings":"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"}

package/dist/extensions/telegram/media.d.ts

@@ -0,0 +1,39 @@
+import type { Message } from "grammy/types";
+import type { MediaAttachment, MediaKind } from "../../domain/message.ts";
+import type { Logger } from "../../log.ts";
+export declare const TELEGRAM_MAX_DOWNLOAD_BYTES: number;
+export type MediaMessage = Pick<Message, "animation" | "sticker" | "video_note" | "photo" | "voice" | "video" | "audio" | "document">;
+export interface ResolvedMedia {
+    kind: MediaKind;
+    label: string;
+    fileId: string;
+    fileSize: number | null;
+    fileName: string | null;
+    extension: string;
+    mimeType: string | null;
+    metadata: Record<string, unknown>;
+    /** Human-readable facts for the attachment description, e.g. "800 × 600". */
+    summary: string[];
+}
+export declare class MediaTooLargeError extends Error {
+    readonly fileSize: number;
+    constructor(fileSize: number);
+}
+/**
+ * Resolve the first matching media payload on a message, in priority order:
+ * animation before document (animations set both fields), video_note before
+ * video (defensive), document last (most generic).
+ */
+export declare const resolveMedia: (message: MediaMessage) => ResolvedMedia | null;
+/** Unique filename: original names are preserved behind a random prefix. */
+export declare const generateMediaFilename: (media: Pick<ResolvedMedia, "fileName" | "extension">) => string;
+export declare const buildAttachment: (media: ResolvedMedia, path: string) => MediaAttachment;
+export interface FileApi {
+    getFile(fileId: string): Promise<{
+        file_path?: string;
+    }>;
+}
+/** Download a Telegram file to disk, pre-checking the bot download size limit. */
+export declare const downloadMedia: (api: FileApi, token: string, media: Pick<ResolvedMedia, "fileId" | "fileSize">, destPath: string) => Promise<void>;
+/** Bootstrap: ensure the media directory exists and prune stale downloads. */
+export declare const ensureMediaDir: (mediaDir: string, log: Logger) => Promise<void>;

package/dist/extensions/telegram/media.js

@@ -0,0 +1,223 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
+// Telegram bots can only download files up to 20 MB.
+export const TELEGRAM_MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
+const MEDIA_RETENTION_DAYS = 30;
+export class MediaTooLargeError extends Error {
+    fileSize;
+    constructor(fileSize) {
+        super(`File too large to download (${(fileSize / (1024 * 1024)).toFixed(1)} MB). ` +
+            "Telegram bots can only download files up to 20 MB.");
+        this.fileSize = fileSize;
+    }
+}
+/**
+ * Resolve the first matching media payload on a message, in priority order:
+ * animation before document (animations set both fields), video_note before
+ * video (defensive), document last (most generic).
+ */
+export const resolveMedia = (message) => {
+    if (message.animation != null) {
+        const media = message.animation;
+        return {
+            kind: "animation",
+            label: "Animation",
+            fileId: media.file_id,
+            fileSize: media.file_size ?? null,
+            fileName: media.file_name ?? null,
+            extension: ".mp4",
+            mimeType: media.mime_type ?? "video/mp4",
+            metadata: { width: media.width, height: media.height, duration: media.duration },
+            summary: [`${media.duration} seconds`, `${media.width} × ${media.height}`],
+        };
+    }
+    if (message.sticker != null) {
+        const media = message.sticker;
+        const format = media.is_animated
+            ? { extension: ".tgs", mimeType: "application/x-tgsticker", description: "animated (.tgs)" }
+            : media.is_video
+                ? { extension: ".webm", mimeType: "video/webm", description: "video (.webm)" }
+                : { extension: ".webp", mimeType: "image/webp", description: "regular (.webp)" };
+        return {
+            kind: "sticker",
+            label: "Sticker",
+            fileId: media.file_id,
+            fileSize: media.file_size ?? null,
+            fileName: null,
+            extension: format.extension,
+            mimeType: format.mimeType,
+            metadata: {
+                ...(media.emoji != null ? { emoji: media.emoji } : {}),
+                format: format.description,
+            },
+            summary: [
+                ...(media.emoji != null ? [`Emoji: ${media.emoji}`] : []),
+                `Format: ${format.description}`,
+            ],
+        };
+    }
+    if (message.video_note != null) {
+        const media = message.video_note;
+        // The domain has no dedicated video-note kind — closest is video.
+        return {
+            kind: "video",
+            label: "Video note",
+            fileId: media.file_id,
+            fileSize: media.file_size ?? null,
+            fileName: null,
+            extension: ".mp4",
+            mimeType: "video/mp4",
+            metadata: { duration: media.duration, diameter: media.length },
+            summary: [`${media.duration} seconds`, `Diameter: ${media.length}px`],
+        };
+    }
+    const photo = message.photo?.at(-1);
+    if (photo != null) {
+        return {
+            kind: "photo",
+            label: "Photo",
+            fileId: photo.file_id,
+            fileSize: photo.file_size ?? null,
+            fileName: null,
+            extension: ".jpg",
+            mimeType: "image/jpeg",
+            metadata: { width: photo.width, height: photo.height },
+            summary: [`${photo.width} × ${photo.height}`, formatFileSize(photo.file_size ?? null)],
+        };
+    }
+    if (message.voice != null) {
+        const media = message.voice;
+        return {
+            kind: "voice",
+            label: "Voice message",
+            fileId: media.file_id,
+            fileSize: media.file_size ?? null,
+            fileName: null,
+            extension: ".ogg",
+            mimeType: media.mime_type ?? "audio/ogg",
+            metadata: { duration: media.duration },
+            summary: [`${media.duration} seconds`, ...(media.mime_type != null ? [media.mime_type] : [])],
+        };
+    }
+    if (message.video != null) {
+        const media = message.video;
+        return {
+            kind: "video",
+            label: "Video",
+            fileId: media.file_id,
+            fileSize: media.file_size ?? null,
+            fileName: media.file_name ?? null,
+            extension: extensionFromName(media.file_name, ".mp4"),
+            mimeType: media.mime_type ?? null,
+            metadata: { width: media.width, height: media.height, duration: media.duration },
+            summary: [`${media.duration} seconds`, `${media.width} × ${media.height}`],
+        };
+    }
+    if (message.audio != null) {
+        const media = message.audio;
+        return {
+            kind: "audio",
+            label: "Audio file",
+            fileId: media.file_id,
+            fileSize: media.file_size ?? null,
+            fileName: media.file_name ?? null,
+            extension: extensionFromName(media.file_name, ".mp3"),
+            mimeType: media.mime_type ?? null,
+            metadata: {
+                duration: media.duration,
+                ...(media.title != null ? { title: media.title } : {}),
+                ...(media.performer != null ? { performer: media.performer } : {}),
+            },
+            summary: [
+                ...(media.title != null ? [media.title] : []),
+                ...(media.performer != null ? [media.performer] : []),
+                `${media.duration} seconds`,
+            ],
+        };
+    }
+    if (message.document != null) {
+        const media = message.document;
+        return {
+            kind: "document",
+            label: "Document",
+            fileId: media.file_id,
+            fileSize: media.file_size ?? null,
+            fileName: media.file_name ?? null,
+            extension: extensionFromName(media.file_name, ""),
+            mimeType: media.mime_type ?? null,
+            metadata: { ...(media.file_name != null ? { fileName: media.file_name } : {}) },
+            summary: [
+                ...(media.file_name != null ? [media.file_name] : []),
+                ...(media.mime_type != null ? [media.mime_type] : []),
+                ...(media.file_size != null ? [formatFileSize(media.file_size)] : []),
+            ],
+        };
+    }
+    return null;
+};
+/** Unique filename: original names are preserved behind a random prefix. */
+export const generateMediaFilename = (media) => {
+    const unique = randomBytes(6).toString("hex");
+    return media.fileName != null ? `${unique}-${media.fileName}` : `${unique}${media.extension}`;
+};
+export const buildAttachment = (media, path) => ({
+    kind: media.kind,
+    path,
+    ...(media.mimeType != null ? { mimeType: media.mimeType } : {}),
+    description: `${media.label} (${media.summary.join(", ")})`,
+    metadata: { ...media.metadata, ...(media.fileSize != null ? { fileSize: media.fileSize } : {}) },
+});
+/** Download a Telegram file to disk, pre-checking the bot download size limit. */
+export const downloadMedia = async (api, token, media, destPath) => {
+    if (media.fileSize != null && media.fileSize > TELEGRAM_MAX_DOWNLOAD_BYTES) {
+        throw new MediaTooLargeError(media.fileSize);
+    }
+    const file = await api.getFile(media.fileId);
+    if (file.file_path == null)
+        throw new Error("Telegram returned no file path for download");
+    const response = await fetch(`https://api.telegram.org/file/bot${token}/${file.file_path}`);
+    if (!response.ok)
+        throw new Error(`File download failed with status ${response.status}`);
+    await mkdir(dirname(destPath), { recursive: true });
+    await writeFile(destPath, Buffer.from(await response.arrayBuffer()));
+};
+/** Bootstrap: ensure the media directory exists and prune stale downloads. */
+export const ensureMediaDir = async (mediaDir, log) => {
+    await mkdir(mediaDir, { recursive: true });
+    const cutoff = Date.now() - MEDIA_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    let cleaned = 0;
+    for (const entry of await readdir(mediaDir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        const path = join(mediaDir, entry.name);
+        try {
+            if ((await stat(path)).mtimeMs < cutoff) {
+                await unlink(path);
+                cleaned += 1;
+            }
+        }
+        catch (error) {
+            log.warn({ err: error, path }, "failed to clean old media file");
+        }
+    }
+    log.debug({ mediaDir, cleaned }, "media directory ready");
+};
+const extensionFromName = (fileName, fallback) => {
+    if (fileName != null) {
+        const extension = extname(fileName);
+        if (extension !== "")
+            return extension;
+    }
+    return fallback;
+};
+const formatFileSize = (size) => {
+    if (size == null)
+        return "size unknown";
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${Math.round(size / 1024)} KB`;
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+};
+//# sourceMappingURL=media.js.map

package/dist/extensions/telegram/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../../../src/extensions/telegram/media.ts"],"names":[],"mappings":"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"}

package/dist/extensions/telegram/mutex.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Promise-chain mutex serializing channel deliveries: callers queue FIFO
+ * behind the in-flight task, so two send sequences never interleave their
+ * Telegram API calls.
+ */
+export declare class Mutex {
+    private tail;
+    run<T>(task: () => Promise<T>): Promise<T>;
+}

package/dist/extensions/telegram/mutex.js

@@ -0,0 +1,14 @@
+/**
+ * Promise-chain mutex serializing channel deliveries: callers queue FIFO
+ * behind the in-flight task, so two send sequences never interleave their
+ * Telegram API calls.
+ */
+export class Mutex {
+    tail = Promise.resolve();
+    run(task) {
+        const result = this.tail.then(() => task());
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+//# sourceMappingURL=mutex.js.map

package/dist/extensions/telegram/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../../src/extensions/telegram/mutex.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,KAAK;IACR,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEhD,GAAG,CAAI,IAAsB;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAE5C,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CACrB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/extensions/telegram/sending.d.ts

@@ -0,0 +1,48 @@
+import type { Logger } from "../../log.ts";
+export interface SendMessageOptions {
+    parse_mode?: "Markdown";
+    disable_notification?: boolean;
+}
+export interface EditMessageOptions {
+    parse_mode?: "Markdown";
+}
+/** Narrow grammY API surface the channel sends through — fakeable in tests. */
+export interface SendApi {
+    sendMessage(chatId: number, text: string, other?: SendMessageOptions): Promise<{
+        message_id: number;
+    }>;
+    sendChatAction(chatId: number, action: "typing"): Promise<unknown>;
+    copyMessage(chatId: number, fromChatId: number, messageId: number): Promise<{
+        message_id: number;
+    }>;
+    deleteMessage(chatId: number, messageId: number): Promise<unknown>;
+    editMessageText(chatId: number, messageId: number, text: string, other?: EditMessageOptions): Promise<unknown>;
+}
+export declare const isMarkdownParseError: (error: unknown) => boolean;
+/** Telegram rejects edits whose content matches the current message — benign. */
+export declare const isMessageNotModifiedError: (error: unknown) => boolean;
+/** Try Markdown first; on a Telegram entity-parse rejection resend as plain text. */
+export declare const sendWithMarkdownFallback: (api: Pick<SendApi, "sendMessage">, chatId: number, text: string, options?: {
+    silent?: boolean;
+}) => Promise<number>;
+/**
+ * Edit a message trying Markdown first, falling back to plain text on a parse
+ * rejection. "Message is not modified" rejections are swallowed — the visible
+ * content already matches.
+ */
+export declare const editWithMarkdownFallback: (api: Pick<SendApi, "editMessageText">, chatId: number, messageId: number, text: string) => Promise<void>;
+/** Send text as one or more messages, split at Telegram's length limit. */
+export declare const sendChunked: (api: Pick<SendApi, "sendMessage">, chatId: number, text: string, options?: {
+    silent?: boolean;
+}) => Promise<number[]>;
+/**
+ * Copy+delete a silently-sent message so the copy fires a push notification.
+ * Copy-first ordering keeps the
+ * text safe: on copy failure the original is preserved and no delete runs; on
+ * delete failure the duplicate is accepted after retries.
+ */
+export declare const notifyViaCopyDelete: (api: Pick<SendApi, "copyMessage" | "deleteMessage">, chatId: number, messageId: number, log: Logger, retryDelayMs?: number) => Promise<number | null>;
+/** Full background-delivery flow: silent chunked send, then copy+delete to fire the push. */
+export declare const deliverText: (api: SendApi, chatId: number, text: string, pushNotifications: boolean, log: Logger, retryDelayMs?: number) => Promise<number | null>;
+/** Show a typing indicator until the returned stop function is called. */
+export declare const startTyping: (api: Pick<SendApi, "sendChatAction">, chatId: number, log: Logger) => (() => void);