@copilotkit/channels-telegram 0.0.3

package/dist/interaction.js

@@ -0,0 +1,159 @@
+import { DM_SCOPE } from "./types.js";
+/**
+ * Stable string key shared by ingress (listener) and interaction decoding so
+ * the bot's awaitChoice waiters resolve. Both paths MUST derive the
+ * conversation key from this single helper — a mismatch silently strands
+ * the waiter.
+ */
+export function conversationKeyOf(key) {
+    return `tg:${key.chatId}:${key.scope}`;
+}
+/**
+ * Derive a ConversationKey from a Telegram message/chat object.
+ *
+ * - Private chat → DM_SCOPE
+ * - Forum supergroup with message_thread_id → "topic:<thread_id>"
+ * - Other group → "user:<senderUserId>"
+ *
+ * Non-forum groups are keyed by the SENDER's user id (not message ids) so that
+ * each user has one ongoing conversation per group: a fresh @mention (which has
+ * no reply, hence a unique message_id) continues the same conversation rather
+ * than spawning a new one, and a callback_query (whose `message` is the BOT's
+ * own message) still resolves to the clicking user's conversation. Pass an
+ * explicit `userId` to override `message.from?.id` (callbacks must pass the
+ * clicking user's id so the key matches ingress).
+ */
+export function deriveConversationKey(message, userId) {
+    const { chat } = message;
+    const chatId = String(chat.id);
+    if (chat.type === "private") {
+        return { chatId, scope: DM_SCOPE };
+    }
+    // Treat message_thread_id as a forum topic ONLY in forum supergroups. In a
+    // regular (non-forum) supergroup Telegram also sets message_thread_id on any
+    // REPLY message (it doubles as the reply-thread id), so keying off it there
+    // would defeat per-user keying (each reply would spawn a new conversation).
+    if (message.message_thread_id !== undefined && message.chat?.is_forum) {
+        return { chatId, scope: `topic:${message.message_thread_id}` };
+    }
+    return { chatId, scope: `user:${userId ?? message.from?.id ?? "unknown"}` };
+}
+/**
+ * Map a Telegram `from` user to a PlatformUser.
+ */
+export function toPlatformUser(from) {
+    if (!from)
+        return undefined;
+    const name = [from.first_name, from.last_name].filter(Boolean).join(" ") || undefined;
+    return {
+        id: String(from.id),
+        name,
+        handle: from.username,
+    };
+}
+const emojiSet = (list) => new Set((list ?? [])
+    .filter((r) => r.type === "emoji" && r.emoji)
+    .map((r) => r.emoji));
+/**
+ * Decode a Telegram `message_reaction` update into zero or more
+ * {@link IncomingReaction} events — one per emoji that was added or removed.
+ * Only `type === "emoji"` entries are considered; custom_emoji are ignored.
+ */
+export function decodeReaction(update) {
+    const mr = update
+        .message_reaction;
+    if (!mr?.chat?.id || mr.message_id === undefined)
+        return [];
+    const oldSet = emojiSet(mr.old_reaction);
+    const newSet = emojiSet(mr.new_reaction);
+    const chatId = mr.chat.id;
+    const message = {
+        chat: mr.chat,
+        message_id: mr.message_id,
+        message_thread_id: mr.message_thread_id,
+    };
+    const ck = deriveConversationKey(message, mr.user?.id);
+    const conversationKey = conversationKeyOf(ck);
+    const replyTarget = {
+        chatId,
+        messageThreadId: mr.chat.is_forum ? mr.message_thread_id : undefined,
+        conversationKey,
+    };
+    const user = mr.user
+        ? {
+            id: String(mr.user.id),
+            name: mr.user.first_name,
+            handle: mr.user.username,
+        }
+        : undefined;
+    const base = {
+        user,
+        conversationKey,
+        replyTarget,
+        messageId: String(mr.message_id),
+        // Update-capable ref (chatId + numeric messageId) so an onReaction handler
+        // can edit the reacted message in place via thread.update.
+        messageRef: { id: String(mr.message_id), chatId, messageId: mr.message_id },
+        raw: update,
+    };
+    const out = [];
+    for (const e of newSet)
+        if (!oldSet.has(e))
+            out.push({ ...base, rawEmoji: e, added: true });
+    for (const e of oldSet)
+        if (!newSet.has(e))
+            out.push({ ...base, rawEmoji: e, added: false });
+    return out;
+}
+/**
+ * Decode a Telegram callback_query update (grammY or raw Bot API) into a
+ * bot InteractionEvent.
+ *
+ * Accepts either:
+ *   - A grammY update: `{ callback_query: { ... } }`
+ *   - A bare callback query object: `{ id, data, from, message }`
+ */
+export function decodeInteraction(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const obj = raw;
+    // Unwrap grammY update wrapper if present.
+    const cq = (obj.callback_query ?? obj);
+    if (!cq || typeof cq !== "object")
+        return undefined;
+    // Must have callback data.
+    if (!cq.data || typeof cq.data !== "string")
+        return undefined;
+    const message = cq.message;
+    if (!message)
+        return undefined;
+    const from = cq.from;
+    // A callback_query's `message` is the BOT's message, so its `from` is the
+    // bot. Derive the key from the CLICKING user's id (cq.from) so non-forum
+    // group keys match the ingress key produced by the listener.
+    const ck = deriveConversationKey(message, from?.id);
+    const conversationKey = conversationKeyOf(ck);
+    const replyTarget = {
+        chatId: message.chat.id,
+        // Only attach a forum thread id in forum supergroups. In non-forum chats
+        // message_thread_id is the reply-thread id and Telegram rejects sends that
+        // attach it ("message thread not found").
+        messageThreadId: message.chat?.is_forum
+            ? message.message_thread_id
+            : undefined,
+        conversationKey,
+    };
+    const messageRef = {
+        id: `${message.chat.id}:${message.message_id}`,
+        chatId: message.chat.id,
+        messageId: message.message_id,
+    };
+    const user = from ? toPlatformUser(from) : undefined;
+    return {
+        id: cq.data,
+        conversationKey,
+        replyTarget,
+        messageRef,
+        user,
+    };
+}

package/dist/listener.d.ts

@@ -0,0 +1,16 @@
+import type { Bot } from "grammy";
+import type { IngressSink } from "@copilotkit/channels";
+import type { TelegramConversationStore } from "./conversation-store.js";
+export interface ListenerConfig {
+    bot: Bot;
+    store: TelegramConversationStore;
+    botUsername: string;
+    botUserId: number;
+    sink: IngressSink;
+    /** Telegram bot token, used to download inbound files. */
+    botToken: string;
+    /** Resolve a Telegram fileId to its file path (e.g. via the getFile API). */
+    getFilePath: (fileId: string) => Promise<string>;
+}
+export declare function attachTelegramListener(config: ListenerConfig): void;
+//# sourceMappingURL=listener.d.ts.map

package/dist/listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAgBzE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,yBAAyB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD;AA2ED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CA6cnE"}

package/dist/listener.js

@@ -0,0 +1,419 @@
+import { conversationKeyOf, deriveConversationKey, toPlatformUser, decodeInteraction, decodeReaction, } from "./interaction.js";
+import { buildFileContentParts } from "./download-files.js";
+/** Escape special regex characters in a string so it can be used in a RegExp. */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Extract downloadable file refs from any media-bearing message (used for the
+ * message a user *replied to*). Mirrors the per-type extraction in the
+ * `message:*` handlers — photo (largest size), document, video, audio, voice.
+ */
+function fileRefsFromMessage(m) {
+    if (m.photo?.length) {
+        const largest = m.photo[m.photo.length - 1];
+        // Telegram re-encodes most photos to JPEG (see the message:photo handler).
+        if (largest)
+            return [{ fileId: largest.file_id, mimeType: "image/jpeg" }];
+    }
+    if (m.document) {
+        return [
+            {
+                fileId: m.document.file_id,
+                fileName: m.document.file_name,
+                mimeType: m.document.mime_type,
+                size: m.document.file_size,
+            },
+        ];
+    }
+    for (const media of [m.video, m.audio, m.voice]) {
+        if (media) {
+            return [
+                {
+                    fileId: media.file_id,
+                    mimeType: media.mime_type,
+                    size: media.file_size,
+                },
+            ];
+        }
+    }
+    return [];
+}
+export function attachTelegramListener(config) {
+    const { bot, botUsername, botUserId, sink, store, botToken, getFilePath } = config;
+    /**
+     * When the inbound message is a Telegram *reply*, fold the referenced
+     * message's content into the turn so the agent knows what the user is
+     * pointing at — e.g. replying to an earlier image with "what's in it". Its
+     * media is downloaded (reusing the inbound-file pipeline) and its text is
+     * quoted. Returns [] when the replied-to message carries nothing usable.
+     */
+    async function buildReplyContextParts(reply) {
+        const refs = fileRefsFromMessage(reply);
+        const quotedRaw = (reply.text ?? reply.caption ?? "").trim();
+        const quoted = quotedRaw.length > 500 ? `${quotedRaw.slice(0, 500)}…` : quotedRaw;
+        if (refs.length === 0 && !quoted)
+            return [];
+        const desc = [
+            quoted ? `text: "${quoted}"` : null,
+            refs.length ? "an attached file" : null,
+        ]
+            .filter(Boolean)
+            .join(" and ");
+        const parts = [
+            { type: "text", text: `[In reply to an earlier message — ${desc}:]` },
+        ];
+        if (refs.length) {
+            const { parts: fileParts, notes } = await buildFileContentParts(refs, botToken, getFilePath);
+            parts.push(...fileParts);
+            if (notes.length) {
+                parts.push({
+                    type: "text",
+                    text: `[attachment notes: ${notes.join("; ")}]`,
+                });
+            }
+        }
+        return parts;
+    }
+    /**
+     * Apply loop-guard + group gating and (when answered) enqueue the user's
+     * message onto the store and emit `onTurn`. Returns without effect when the
+     * turn should be ignored (own message, or un-addressed group message).
+     *
+     * @param ctx          grammY context (provides `chat`).
+     * @param msg          the inbound message.
+     * @param userText     the addressing text used for gating + handler context
+     *                     (text body or media caption; "" when absent).
+     * @param buildContent produces the agent message content for an answered
+     *                     turn — the mention-stripped string for text, or an
+     *                     array of content parts for media.
+     */
+    async function handleTurn(ctx, msg, userText, buildContent) {
+        const from = msg.from;
+        // LOOP GUARD: ignore our own messages.
+        if (from?.id === botUserId)
+            return;
+        // Bug 4 fix: guard against an empty botUsername. `@${escapeRegExp("")}\b`
+        // would be `/@\b/`, which matches a bare "@". When botUsername is empty
+        // there is no mention to match, so use a regex that never matches.
+        const mentionRegex = botUsername
+            ? new RegExp(`@${escapeRegExp(botUsername)}\\b`, "i")
+            : undefined;
+        // Decide whether to answer.
+        const chatType = ctx.chat.type;
+        let shouldAnswer = false;
+        if (chatType === "private") {
+            shouldAnswer = true;
+        }
+        else {
+            // group / supergroup: answer if @mentioned (case-insensitive, word-boundary)
+            // or reply to bot's message.
+            const mentionedBot = mentionRegex?.test(userText) ?? false;
+            const replyToBot = msg.reply_to_message?.from?.id === botUserId;
+            shouldAnswer = mentionedBot || replyToBot;
+        }
+        if (!shouldAnswer)
+            return;
+        // Bug 1 & 2 fix: strip the @mention wherever it appears (first occurrence),
+        // case-insensitively, collapsing surrounding whitespace so the agent gets
+        // clean text. With no botUsername there is nothing to strip.
+        let strippedText = (mentionRegex ? userText.replace(mentionRegex, "") : userText)
+            .replace(/\s{2,}/g, " ")
+            .trim();
+        const turnConversationKey = conversationKeyOf(deriveConversationKey(msg));
+        // Build the agent content, then fold in any replied-to message so the
+        // agent can resolve a Telegram reply ("what's in this image" pointing at an
+        // earlier photo). Reply context is appended after the user's own content.
+        let content = buildContent(strippedText);
+        if (msg.reply_to_message) {
+            const replyParts = await buildReplyContextParts(msg.reply_to_message);
+            if (replyParts.length) {
+                const baseParts = typeof content === "string"
+                    ? content
+                        ? [{ type: "text", text: content }]
+                        : []
+                    : content;
+                content = [...baseParts, ...replyParts];
+            }
+        }
+        // Enqueue the user's message so getOrCreate delivers it to the agent. The
+        // listener runs before the bot handler that calls runAgent → getOrCreate,
+        // so the drain happens at exactly the right time.
+        store.enqueueUserMessage(turnConversationKey, content);
+        // Bug 3 fix: record the inbound user turn so getMessages() includes it.
+        // Record the STRIPPED text (the same clean text handed to the agent, not
+        // the raw text including the @mention) and stamp `ts` so history ordering
+        // matches the outbound records.
+        config.store.recordMessage(turnConversationKey, {
+            text: strippedText,
+            ts: String(msg.message_id),
+            isBot: false,
+            user: from ? toPlatformUser(from) : undefined,
+        });
+        // CRITICAL: run the turn WITHOUT blocking grammY's poll loop. grammY's
+        // built-in long polling processes updates SEQUENTIALLY — it awaits one
+        // update's handler before fetching the next. If we awaited the full turn
+        // here, a blocking human-in-the-loop step (confirm_write → awaitChoice)
+        // would pause polling indefinitely: the callback_query that resolves the
+        // choice can only arrive via the next getUpdates, which never happens while
+        // this handler is blocked. With no in-flight poll request (and only a
+        // pending promise, which does not ref the event loop) the process would
+        // then drain and exit(0) silently — a deadlock, not a crash. Firing the
+        // turn async lets polling continue and deliver that callback. Errors are
+        // logged here since nothing awaits the promise.
+        void Promise.resolve(sink.onTurn({
+            conversationKey: turnConversationKey,
+            replyTarget: {
+                chatId: ctx.chat.id,
+                // Only attach a forum thread id in forum supergroups. In non-forum
+                // chats Telegram sets message_thread_id on reply messages, but
+                // attaching it to a send is rejected ("message thread not found").
+                messageThreadId: ctx.chat.is_forum
+                    ? msg.message_thread_id
+                    : undefined,
+                replyToMessageId: msg.message_id,
+                conversationKey: turnConversationKey,
+            },
+            userText: strippedText,
+            user: from ? toPlatformUser(from) : undefined,
+            platform: "telegram",
+        })).catch((e) => {
+            console.error(`[bot-telegram] turn failed for conversationKey=${turnConversationKey}:`, e);
+        });
+    }
+    /** Build media content parts from file refs + caption, then route the turn. */
+    async function handleMedia(ctx, fileRefs) {
+        const msg = ctx.message;
+        if (!msg)
+            return;
+        // LOOP GUARD up-front to avoid downloading files for our own messages.
+        if (msg.from?.id === botUserId)
+            return;
+        const caption = msg.caption ?? "";
+        // Gating is applied inside handleTurn against the caption; only build the
+        // (potentially expensive) file parts once we know the turn is answered.
+        // Bug 1 fix: use case-insensitive, word-boundary regex for mention check.
+        // Bug 4 fix: guard against an empty botUsername (see handleTurn).
+        const mediaMentionRegex = botUsername
+            ? new RegExp(`@${escapeRegExp(botUsername)}\\b`, "i")
+            : undefined;
+        const chatType = ctx.chat.type;
+        let shouldAnswer = chatType === "private";
+        if (!shouldAnswer) {
+            const mentionedBot = mediaMentionRegex?.test(caption) ?? false;
+            const replyToBot = msg.reply_to_message?.from?.id === botUserId;
+            shouldAnswer = mentionedBot || replyToBot;
+        }
+        if (!shouldAnswer)
+            return;
+        const { parts, notes } = await buildFileContentParts(fileRefs, botToken, getFilePath);
+        await handleTurn(ctx, msg, caption, (strippedCaption) => [
+            ...(strippedCaption
+                ? [{ type: "text", text: strippedCaption }]
+                : []),
+            ...parts,
+            ...(notes.length
+                ? [
+                    {
+                        type: "text",
+                        text: `[attachment notes: ${notes.join("; ")}]`,
+                    },
+                ]
+                : []),
+        ]);
+    }
+    // ── Text messages ──────────────────────────────────────────────────
+    bot.on("message:text", async (ctx) => {
+        const msg = ctx.message;
+        const from = msg.from;
+        // LOOP GUARD: ignore our own messages.
+        if (from?.id === botUserId)
+            return;
+        const text = msg.text ?? "";
+        const entities = msg
+            .entities ?? [];
+        const cmdEntity = entities.find((e) => e.type === "bot_command" && e.offset === 0);
+        if (cmdEntity) {
+            // Extract the command token (e.g. "/triage" or "/triage@cpk_bot")
+            const cmdToken = text.slice(cmdEntity.offset, cmdEntity.offset + cmdEntity.length);
+            // Parse: /cmd[@bot]
+            const withoutSlash = cmdToken.slice(1); // strip leading "/"
+            const atIdx = withoutSlash.indexOf("@");
+            let cmd;
+            let targetBot;
+            if (atIdx !== -1) {
+                cmd = withoutSlash.slice(0, atIdx);
+                targetBot = withoutSlash.slice(atIdx + 1);
+            }
+            else {
+                cmd = withoutSlash;
+                targetBot = undefined;
+            }
+            // If targeted at another bot, ignore. Guard against an undefined/empty
+            // botUsername (consistent with the mention-path guard): when we have no
+            // username we cannot prove the command targets us, so skip the compare
+            // and let it through rather than throwing on `botUsername.toLowerCase()`.
+            if (targetBot !== undefined &&
+                botUsername &&
+                targetBot.toLowerCase() !== botUsername.toLowerCase()) {
+                return;
+            }
+            // Bug 2 fix: `/start` is handled exclusively by the dedicated
+            // bot.command("start") handler (which emits onThreadStarted). Returning
+            // early here prevents a double-dispatch where both onCommand("start") and
+            // onThreadStarted fire for the same /start message.
+            if (cmd.toLowerCase() === "start") {
+                return;
+            }
+            // Rest of the text after the command token
+            const rest = text.slice(cmdEntity.offset + cmdEntity.length).trim();
+            const commandConversationKey = conversationKeyOf(deriveConversationKey(msg));
+            // Commands do NOT enqueue: their args are injected by the command handler
+            // via runAgent({ prompt }), so enqueuing here would double-deliver.
+            // Fire async (not awaited) for the same reason as onTurn above — a command
+            // whose agent hits confirm_write must not block grammY's poll loop.
+            void Promise.resolve(sink.onCommand({
+                command: cmd.toLowerCase(),
+                text: rest,
+                conversationKey: commandConversationKey,
+                replyTarget: {
+                    chatId: ctx.chat.id,
+                    // Forum thread id only in forum supergroups (see onTurn above).
+                    messageThreadId: ctx.chat.is_forum
+                        ? msg.message_thread_id
+                        : undefined,
+                    conversationKey: commandConversationKey,
+                },
+                user: from ? toPlatformUser(from) : undefined,
+                platform: "telegram",
+            })).catch((e) => console.error("[bot-telegram] command failed:", e));
+            return;
+        }
+        // Non-command text: gate, enqueue the (mention-stripped) text, emit onTurn.
+        await handleTurn(ctx, msg, text, (strippedText) => strippedText);
+    });
+    // ── Media messages ─────────────────────────────────────────────────
+    bot.on("message:photo", async (ctx) => {
+        const photos = ctx.message.photo ?? [];
+        const largest = photos[photos.length - 1];
+        if (!largest)
+            return;
+        // Bug 5: at this point we only have the file_id, not the bytes, so we
+        // cannot sniff the real MIME type here. Telegram re-encodes most photos to
+        // JPEG, so "image/jpeg" is a reasonable default. Telegram photos can in
+        // principle be PNG/WebP; refining the MIME from the download response's
+        // Content-Type belongs in the download layer (out of scope for this file).
+        await handleMedia(ctx, [
+            { fileId: largest.file_id, mimeType: "image/jpeg" },
+        ]);
+    });
+    bot.on("message:document", async (ctx) => {
+        const doc = ctx.message.document;
+        if (!doc)
+            return;
+        await handleMedia(ctx, [
+            {
+                fileId: doc.file_id,
+                fileName: doc.file_name,
+                mimeType: doc.mime_type,
+                size: doc.file_size,
+            },
+        ]);
+    });
+    bot.on("message:video", async (ctx) => {
+        const video = ctx.message.video;
+        if (!video)
+            return;
+        await handleMedia(ctx, [
+            {
+                fileId: video.file_id,
+                mimeType: video.mime_type,
+                size: video.file_size,
+            },
+        ]);
+    });
+    bot.on("message:audio", async (ctx) => {
+        const audio = ctx.message.audio;
+        if (!audio)
+            return;
+        await handleMedia(ctx, [
+            {
+                fileId: audio.file_id,
+                mimeType: audio.mime_type,
+                size: audio.file_size,
+            },
+        ]);
+    });
+    bot.on("message:voice", async (ctx) => {
+        const voice = ctx.message.voice;
+        if (!voice)
+            return;
+        await handleMedia(ctx, [
+            {
+                fileId: voice.file_id,
+                mimeType: voice.mime_type,
+                size: voice.file_size,
+            },
+        ]);
+    });
+    // ── Callback queries (inline keyboard interactions) ─────────────────
+    bot.on("callback_query:data", async (ctx) => {
+        // Ack FIRST to clear the client spinner. The ack itself may throw (e.g. a
+        // stale button → "query is too old"); that must NOT block decode/dispatch,
+        // otherwise the awaitChoice waiter is stranded. Wrap it in its own
+        // try/catch, log on failure, then ALWAYS decode + dispatch.
+        try {
+            await ctx.answerCallbackQuery();
+        }
+        catch (err) {
+            console.error("[bot-telegram] callback ack failed:", err);
+        }
+        // Guard the dispatch: a throw here (decode, action handler, or the resumed
+        // agent turn) must NOT escape into grammy's poll loop and crash the bot.
+        try {
+            const evt = decodeInteraction(ctx.update);
+            if (evt) {
+                await sink.onInteraction(evt);
+            }
+        }
+        catch (err) {
+            console.error("[bot-telegram] onInteraction failed:", err);
+        }
+    });
+    // ── Emoji reactions ────────────────────────────────────────────────
+    bot.on("message_reaction", async (ctx) => {
+        // LOOP GUARD: ignore the bot's OWN reactions. If our setMessageReaction
+        // egress is ever echoed back as a message_reaction update, dispatching it
+        // to sink.onReaction would treat it as a user reaction (loop risk for a
+        // catch-all handler). Mirrors the from?.id === botUserId guard the message
+        // handlers use, and Discord's user?.bot skip.
+        const reactor = ctx.update.message_reaction?.user;
+        if (reactor?.id === botUserId)
+            return;
+        try {
+            for (const evt of decodeReaction(ctx.update))
+                await sink.onReaction(evt);
+        }
+        catch (err) {
+            console.error("[bot-telegram] onReaction failed:", err);
+        }
+    });
+    // ── /start command (private chats only) ────────────────────────────
+    bot.command("start", async (ctx) => {
+        if (ctx.chat.type !== "private")
+            return;
+        const msg = ctx.message;
+        if (!msg)
+            return;
+        const startConversationKey = conversationKeyOf(deriveConversationKey(msg));
+        await sink.onThreadStarted({
+            conversationKey: startConversationKey,
+            replyTarget: {
+                chatId: ctx.chat.id,
+                conversationKey: startConversationKey,
+            },
+            user: msg.from ? toPlatformUser(msg.from) : undefined,
+            platform: "telegram",
+        });
+    });
+}

package/dist/render/budget.d.ts

@@ -0,0 +1,18 @@
+export declare const TELEGRAM_LIMITS: {
+    readonly messageText: 4096;
+    readonly caption: 1024;
+    readonly callbackData: 64;
+    readonly buttonsPerRow: 8;
+    readonly buttonsPerMessage: 100;
+    readonly buttonText: 64;
+    readonly photosPerMessage: 10;
+};
+export declare const byteLen: (s: string) => number;
+/** Truncate to max chars, appending an ellipsis marker if the input was longer. Never returns >max. */
+export declare function truncateText(text: string, max: number): string;
+/** Clamp an array to max items; return the kept items plus how many overflowed (for an overflow signal). */
+export declare function clampArray<T>(items: readonly T[], max: number): {
+    items: T[];
+    overflow: number;
+};
+//# sourceMappingURL=budget.d.ts.map

package/dist/render/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/render/budget.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;;;CAQlB,CAAC;AAEX,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,WAAiC,CAAC;AAEnE,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGlC"}

package/dist/render/budget.js

@@ -0,0 +1,24 @@
+export const TELEGRAM_LIMITS = {
+    messageText: 4096,
+    caption: 1024,
+    callbackData: 64,
+    buttonsPerRow: 8,
+    buttonsPerMessage: 100,
+    buttonText: 64,
+    photosPerMessage: 10,
+};
+export const byteLen = (s) => Buffer.byteLength(s, "utf8");
+/** Truncate to max chars, appending an ellipsis marker if the input was longer. Never returns >max. */
+export function truncateText(text, max) {
+    if (text.length <= max)
+        return text;
+    if (max <= 1)
+        return text.slice(0, max);
+    return text.slice(0, max - 1) + "…"; // …
+}
+/** Clamp an array to max items; return the kept items plus how many overflowed (for an overflow signal). */
+export function clampArray(items, max) {
+    if (items.length <= max)
+        return { items: [...items], overflow: 0 };
+    return { items: items.slice(0, max), overflow: items.length - max };
+}

package/dist/render/telegram.d.ts

@@ -0,0 +1,11 @@
+import type { BotNode } from "@copilotkit/channels-ui";
+import type { TelegramPayload } from "../types.js";
+/**
+ * Render a cross-platform component IR tree into a Telegram Bot API payload.
+ *
+ * The renderer is total: unknown intrinsic types are skipped rather than
+ * throwing. Telegram limits are enforced via {@link truncateText},
+ * {@link clampArray}, and {@link byteLen}.
+ */
+export declare function renderTelegram(ir: BotNode[]): TelegramPayload;
+//# sourceMappingURL=telegram.d.ts.map

package/dist/render/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/render/telegram.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAwB,eAAe,EAAE,MAAM,aAAa,CAAC;AA6BzE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,eAAe,CAoD7D"}