@copilotkit/channels-telegram 0.0.3

package/dist/download-files.js

@@ -0,0 +1,157 @@
+/**
+ * Inbound file transport. Telegram messages can carry file attachments; this
+ * turns them into AG-UI multimodal message content the agent's model can
+ * read — images, audio, video, and documents as their respective binary parts —
+ * downloading each from the Telegram Bot API file endpoint.
+ *
+ * The bridge is transport-only: it delivers the bytes to the agent and lets
+ * the app decide what to do with them. Anything it can't represent is skipped
+ * with a short note so the agent knows a file was dropped and why.
+ */
+/** Redact all occurrences of `token` from `msg` so the bot secret never leaks into notes. */
+function redactToken(msg, token) {
+    if (!token)
+        return msg;
+    return msg.split(token).join("<redacted>");
+}
+const DEFAULTS = {
+    maxBytesPerFile: 8 * 1024 * 1024,
+    maxFiles: 5,
+};
+/**
+ * The AG-UI media part type that carries this MIME, or "document" as fallback.
+ * Images/audio/video go by their top-level type; everything else is document.
+ */
+function mediaPartType(mime) {
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime.startsWith("audio/"))
+        return "audio";
+    if (mime.startsWith("video/"))
+        return "video";
+    return "document";
+}
+/** Non-`text/*` MIME types that are still UTF-8 text the model should read. */
+const TEXT_APP_TYPES = new Set([
+    "application/json",
+    "application/ld+json",
+    "application/xml",
+    "application/csv",
+    "application/x-ndjson",
+    "application/yaml",
+    "application/x-yaml",
+    "application/javascript",
+    "application/sql",
+    "application/toml",
+]);
+/** Filename extensions that indicate text content when the MIME is unhelpful. */
+const TEXT_EXTENSIONS = /\.(csv|tsv|txt|md|markdown|json|ndjson|xml|ya?ml|log|html?|js|ts|css|sql|ini|toml|tex)$/i;
+/** Cap decoded text so a large upload can't blow the model's context window. */
+const MAX_TEXT_CHARS = 200_000;
+/**
+ * Whether a file is UTF-8 text the model should read inline (CSV/JSON/XML/plain
+ * text/…) rather than a binary attachment. Most models reject these as binary
+ * "file" parts (e.g. "media type text/csv not supported"), and the agent wants
+ * to read/parse the content anyway (e.g. parse a CSV → render_chart).
+ */
+function isTextLike(mime, fileName) {
+    if (mime.startsWith("text/"))
+        return true;
+    if (TEXT_APP_TYPES.has(mime))
+        return true;
+    if (fileName && TEXT_EXTENSIONS.test(fileName))
+        return true;
+    return false;
+}
+/**
+ * Download a message's files and turn them into AG-UI content parts. Returns
+ * the parts plus human-readable `notes` for anything skipped (appended to the
+ * message as a text part by the caller).
+ *
+ * @param files      List of Telegram file references to process.
+ * @param token      Telegram bot token used to build the download URL.
+ * @param getFilePath  Resolves a fileId to a Telegram file path (e.g. via getFile API).
+ * @param config     Optional delivery configuration.
+ */
+export async function buildFileContentParts(files, token, getFilePath, config = {}) {
+    const maxBytes = config.maxBytesPerFile ?? DEFAULTS.maxBytesPerFile;
+    const maxFiles = config.maxFiles ?? DEFAULTS.maxFiles;
+    const parts = [];
+    const notes = [];
+    const considered = files.slice(0, maxFiles);
+    if (files.length > maxFiles) {
+        notes.push(`(only the first ${maxFiles} of ${files.length} files processed)`);
+    }
+    for (const f of considered) {
+        const label = f.fileName ?? f.fileId;
+        const mime = (f.mimeType ?? "application/octet-stream").toLowerCase();
+        if (typeof f.size === "number" && f.size > maxBytes) {
+            notes.push(`skipped "${label}": ${f.size} bytes too large (cap is ${maxBytes} bytes)`);
+            continue;
+        }
+        let filePath;
+        try {
+            filePath = await getFilePath(f.fileId);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            notes.push(`skipped "${label}": could not resolve file path — ${redactToken(msg, token)}`);
+            continue;
+        }
+        const url = `https://api.telegram.org/file/bot${token}/${filePath}`;
+        let bytes;
+        try {
+            const res = await fetch(url);
+            if (!res.ok) {
+                notes.push(`skipped "${label}": download failed (HTTP ${res.status})`);
+                continue;
+            }
+            // Pre-check Content-Length to avoid buffering oversized responses entirely
+            // into memory (memory-DoS guard for cases where f.size is absent, e.g. photos).
+            const contentLength = res.headers.get("content-length");
+            if (contentLength !== null) {
+                const declared = parseInt(contentLength, 10);
+                if (!isNaN(declared) && declared > maxBytes) {
+                    notes.push(`skipped "${label}": Content-Length ${declared} bytes too large (cap is ${maxBytes} bytes)`);
+                    continue;
+                }
+            }
+            bytes = Buffer.from(await res.arrayBuffer());
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            notes.push(`skipped "${label}": ${redactToken(msg, token)}`);
+            continue;
+        }
+        // Backstop: reject if actual body exceeds cap (covers responses without Content-Length).
+        if (bytes.byteLength > maxBytes) {
+            notes.push(`skipped "${label}": ${bytes.byteLength} bytes too large (cap is ${maxBytes} bytes)`);
+            continue;
+        }
+        // Text-like files become a decoded TEXT part (the model can't take them as
+        // binary "file" parts, and the agent wants to read/parse the content).
+        if (isTextLike(mime, f.fileName)) {
+            let text = bytes.toString("utf8");
+            let truncated = "";
+            if (text.length > MAX_TEXT_CHARS) {
+                truncated = ` [truncated to ${MAX_TEXT_CHARS} of ${text.length} chars]`;
+                text = text.slice(0, MAX_TEXT_CHARS);
+            }
+            parts.push({
+                type: "text",
+                text: `Attached file "${label}" (${mime})${truncated}:\n\n${text}`,
+            });
+            continue;
+        }
+        const partType = mediaPartType(mime);
+        parts.push({
+            type: partType,
+            source: {
+                type: "data",
+                value: bytes.toString("base64"),
+                mimeType: mime,
+            },
+        });
+    }
+    return { parts, notes };
+}

package/dist/event-renderer.d.ts

@@ -0,0 +1,39 @@
+import type { RunRenderer } from "@copilotkit/channels";
+export interface CreateRunRendererArgs {
+    /** Posts a new Telegram message with placeholder text; resolves with its message id. */
+    postPlaceholder: (text: string) => Promise<number>;
+    /** Edits the Telegram message with the given id to contain `text`. */
+    editAt: (messageId: number, text: string) => Promise<void>;
+    /**
+     * Optional native typing indicator. When provided it is used in place of a
+     * posted `🔧 using <tool>…` status line on tool-call start.
+     */
+    setTyping?: () => Promise<void>;
+    /**
+     * Custom-event names that should be treated as interrupts — captured for
+     * later dispatch to an `InterruptHandler`. Defaults to `on_interrupt` (the
+     * name LangGraph's AG-UI adapter emits).
+     */
+    interruptEventNames?: ReadonlySet<string>;
+    /**
+     * Whether tool calls should surface a `🔧 using <tool>…` → done status line.
+     * Defaults to `true`. Tool calls are ALWAYS captured regardless of this flag.
+     */
+    showToolStatus?: boolean;
+}
+/**
+ * Construct a {@link RunRenderer} for a single agent run on Telegram.
+ *
+ * Mirrors the Slack renderer's lifecycle, swapping Slack's `chat.update`
+ * transport for {@link ChunkedEditStream} (numeric message ids + telegram
+ * HTML transform) and Slack's composer status for `setTyping()` / a posted
+ * status line.
+ *
+ * The `subscriber` is passed to `runAgent`. After the run resolves, the
+ * run-loop reads `getCapturedToolCalls()` and `getPendingInterrupt()`.
+ * `markInterrupted()` finalises EVERY in-flight stream (so no in-flight
+ * placeholder is abandoned), appending an `_(interrupted)_` marker to any
+ * stream that has real partial content.
+ */
+export declare function createRunRenderer(args: CreateRunRendererArgs): RunRenderer;
+//# sourceMappingURL=event-renderer.d.ts.map

package/dist/event-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-renderer.d.ts","sourceRoot":"","sources":["../src/event-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EAGZ,MAAM,sBAAsB,CAAC;AAM9B,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,sEAAsE;IACtE,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,WAAW,CAsT1E"}

package/dist/event-renderer.js

@@ -0,0 +1,295 @@
+import { ChunkedEditStream } from "./chunked-edit-stream.js";
+import { telegramHtml } from "./telegram-html.js";
+const INTERRUPTED_SUFFIX = "\n_(interrupted)_";
+/**
+ * Construct a {@link RunRenderer} for a single agent run on Telegram.
+ *
+ * Mirrors the Slack renderer's lifecycle, swapping Slack's `chat.update`
+ * transport for {@link ChunkedEditStream} (numeric message ids + telegram
+ * HTML transform) and Slack's composer status for `setTyping()` / a posted
+ * status line.
+ *
+ * The `subscriber` is passed to `runAgent`. After the run resolves, the
+ * run-loop reads `getCapturedToolCalls()` and `getPendingInterrupt()`.
+ * `markInterrupted()` finalises EVERY in-flight stream (so no in-flight
+ * placeholder is abandoned), appending an `_(interrupted)_` marker to any
+ * stream that has real partial content.
+ */
+export function createRunRenderer(args) {
+    const interruptEventNames = args.interruptEventNames ?? new Set(["on_interrupt"]);
+    const showToolStatus = args.showToolStatus ?? true;
+    /** Per-AG-UI-message accumulated text (we accumulate deltas locally). */
+    const buffers = new Map();
+    /** Per-AG-UI-message text stream. Lazily created on first content. */
+    const streams = new Map();
+    /** Per-tool-call status message id so we can edit it on END. */
+    const toolStatusIds = new Map();
+    /**
+     * Once a stream has been finalised (via TEXT_MESSAGE_END or markInterrupted)
+     * we drop it. Late-arriving events for the same messageId are ignored.
+     */
+    const finalised = new Set();
+    /**
+     * Set when the caller intentionally aborted the run (a new turn arrived for
+     * the same conversation). Suppresses the RUN_ERROR notice and stops
+     * accepting further AG-UI events — the `_(interrupted)_` marker conveys the
+     * state visually.
+     */
+    let aborted = false;
+    /** Tool calls observed in this run, in event order. */
+    const capturedToolCalls = [];
+    /** Interrupt observed via a matching `onCustomEvent`; read after runAgent. */
+    let pendingInterrupt;
+    const ensureStream = (messageId) => {
+        if (finalised.has(messageId))
+            return undefined;
+        let s = streams.get(messageId);
+        if (!s) {
+            s = new ChunkedEditStream({
+                postPlaceholder: args.postPlaceholder,
+                editAt: args.editAt,
+                transform: telegramHtml,
+            });
+            streams.set(messageId, s);
+        }
+        return s;
+    };
+    /**
+     * BEST-EFFORT cleanup of tool-status placeholders that were posted on START
+     * but never resolved by an END (the run ended/errored/was interrupted while
+     * the tool call was still in flight). Edits each remaining placeholder to a
+     * terminal marker so the stale `🔧 using <tool>…` line doesn't linger. This
+     * is not a hard guarantee: each `editAt` can fail (message too old, deleted,
+     * not-modified, flood-wait) and on failure it is caught + logged, NOT
+     * retried — so a placeholder can still end up stranded if Telegram rejects
+     * the edit. `terminal` is the marker each placeholder is edited to (e.g.
+     * `✅` on finish, `⚠️ … (cancelled)` on error/interrupt).
+     */
+    const drainToolStatuses = async (terminal) => {
+        if (toolStatusIds.size === 0)
+            return;
+        const tasks = [];
+        for (const [toolCallId, messageId] of Array.from(toolStatusIds.entries())) {
+            const captured = capturedToolCalls.find((c) => c.toolCallId === toolCallId);
+            const toolName = captured?.toolCallName ?? "tool";
+            tasks.push(args
+                .editAt(messageId, telegramHtml(terminal(toolName)))
+                .catch((err) => console.error("[telegram-renderer] tool-status drain failed:", err)));
+        }
+        toolStatusIds.clear();
+        await Promise.all(tasks);
+    };
+    const captureToolCall = (toolCallId, toolCallName, toolCallArgs) => {
+        const existing = capturedToolCalls.find((c) => c.toolCallId === toolCallId);
+        if (existing) {
+            existing.toolCallName = toolCallName;
+            existing.toolCallArgs = toolCallArgs;
+        }
+        else {
+            capturedToolCalls.push({ toolCallId, toolCallName, toolCallArgs });
+        }
+    };
+    const subscriber = {
+        // ── 1. Text streaming ──────────────────────────────────────────────
+        async onTextMessageStartEvent({ event }) {
+            if (aborted)
+                return;
+            // A reused messageId (legal START→END→START across steps in some AG-UI
+            // adapters) must start fresh. The first message's stream may have eagerly
+            // posted a "…" placeholder and queued its content; FINISH it (flushing
+            // the first message into its placeholder) before resetting. Deleting it
+            // without finishing would silently lose the first message's content AND
+            // leave its placeholder orphaned in the chat forever.
+            const existing = streams.get(event.messageId);
+            if (existing) {
+                await existing
+                    .finish()
+                    .catch((e) => console.error("[bot-telegram] stream finalize failed:", e));
+                streams.delete(event.messageId);
+            }
+            // Clear the finalised guard and reset the buffer so ensureStream
+            // recreates a fresh stream for the second message's content.
+            finalised.delete(event.messageId);
+            buffers.set(event.messageId, "");
+        },
+        onTextMessageContentEvent({ event }) {
+            if (aborted)
+                return;
+            const next = (buffers.get(event.messageId) ?? "") + (event.delta ?? "");
+            buffers.set(event.messageId, next);
+            ensureStream(event.messageId)?.append(next);
+        },
+        onTextMessageEndEvent({ event }) {
+            if (aborted)
+                return;
+            // Keep the stream alive; the final flush happens in onRunFinishedEvent.
+            // Marking finalised here would reopen-guard a stream that may still
+            // receive its flush, so we only stop accepting NEW deltas.
+            finalised.add(event.messageId);
+        },
+        // ── 2. Tool-call surfacing + capture ──────────────────────────────
+        async onToolCallStartEvent({ event }) {
+            if (aborted)
+                return;
+            // Always capture — the run-loop filters by which tools are registered.
+            captureToolCall(event.toolCallId, event.toolCallName, {});
+            if (!showToolStatus)
+                return;
+            if (args.setTyping) {
+                await args.setTyping();
+                return;
+            }
+            // Dedup by toolCallId so a re-emitted START can't post a second line.
+            if (toolStatusIds.has(event.toolCallId))
+                return;
+            try {
+                const id = await args.postPlaceholder(telegramHtml(`🔧 using ${event.toolCallName}…`));
+                toolStatusIds.set(event.toolCallId, id);
+            }
+            catch (err) {
+                console.error("[telegram-renderer] tool-start post failed:", err);
+            }
+        },
+        onToolCallArgsEvent({ event, toolCallName, partialToolCallArgs }) {
+            if (aborted)
+                return;
+            captureToolCall(event.toolCallId, toolCallName, (partialToolCallArgs ?? {}));
+        },
+        async onToolCallEndEvent({ event, toolCallName, toolCallArgs }) {
+            if (aborted)
+                return;
+            captureToolCall(event.toolCallId, toolCallName, (toolCallArgs ?? {}));
+            if (!showToolStatus)
+                return;
+            const id = toolStatusIds.get(event.toolCallId);
+            if (id === undefined)
+                return;
+            try {
+                await args.editAt(id, telegramHtml(`✅ ${toolCallName}`));
+            }
+            catch (err) {
+                console.error("[telegram-renderer] tool-end edit failed:", err);
+            }
+            toolStatusIds.delete(event.toolCallId);
+        },
+        // ── 3. Interrupts (LangGraph `interrupt()` → AG-UI custom event) ─
+        onCustomEvent({ event }) {
+            if (aborted)
+                return;
+            const e = event;
+            if (!e.name || !interruptEventNames.has(e.name))
+                return;
+            // LangGraph's AG-UI adapter ships the interrupt value as a JSON string
+            // in some shapes (and as an object in others). Normalize here so
+            // downstream schema validation always sees the parsed shape.
+            let value = e.value;
+            if (typeof value === "string") {
+                try {
+                    value = JSON.parse(value);
+                }
+                catch {
+                    // Leave it as a string — the handler's schema will reject it
+                    // explicitly with a clearer error.
+                }
+            }
+            pendingInterrupt = { eventName: e.name, value };
+        },
+        // ── 4. Run lifecycle: finalise streams ─────────────────────────────
+        async onRunFinishedEvent() {
+            if (aborted)
+                return;
+            const tasks = [];
+            for (const [id, stream] of Array.from(streams.entries())) {
+                // Best-effort: a terminal-edit rejection (message too old, deleted,
+                // not-modified, flood-wait) must not bubble into the AG-UI run loop.
+                tasks.push(stream
+                    .finish()
+                    .catch((e) => console.error("[bot-telegram] stream finalize failed:", e)));
+                streams.delete(id);
+                finalised.add(id);
+            }
+            buffers.clear();
+            await Promise.all(tasks);
+            // Drain any tool-status placeholders left over from a tool call whose
+            // END never arrived before the run finished — flip them to done so they
+            // aren't orphaned as a perpetual "🔧 using <tool>…".
+            await drainToolStatuses((tool) => `✅ ${tool}`);
+        },
+        // ── 5. Errors ─────────────────────────────────────────────────────
+        async onRunErrorEvent({ event }) {
+            // Don't post a notice if we're the ones aborting; the `_(interrupted)_`
+            // marker on the partial reply is the user-visible signal in that case.
+            if (aborted)
+                return;
+            // Drain any in-flight text streams so partial replies are finalized
+            // rather than left dangling (a _thinking…_ or partial message that
+            // never resolves). Mirror the flush from onRunFinishedEvent.
+            const tasks = [];
+            for (const [id, stream] of Array.from(streams.entries())) {
+                tasks.push(stream
+                    .finish()
+                    .catch((e) => console.error("[bot-telegram] stream finalize failed:", e)));
+                streams.delete(id);
+                finalised.add(id);
+            }
+            buffers.clear();
+            await Promise.all(tasks);
+            // Clean up any tool-status placeholders whose END never arrived before
+            // the error — mark them cancelled rather than leaving "🔧 using <tool>…"
+            // orphaned in the chat.
+            await drainToolStatuses((tool) => `⚠️ ${tool} (cancelled)`);
+            try {
+                await args.postPlaceholder(telegramHtml(`⚠️ Agent error: ${event.message ?? "unknown error"}`));
+            }
+            catch (err) {
+                console.error("[telegram-renderer] error notice failed:", err);
+            }
+        },
+    };
+    return {
+        subscriber,
+        getCapturedToolCalls: () => capturedToolCalls,
+        getPendingInterrupt: () => pendingInterrupt,
+        clearPendingInterrupt: () => {
+            pendingInterrupt = undefined;
+        },
+        async markInterrupted() {
+            // Idempotent. Mark BEFORE any await so subsequent subscriber callbacks
+            // (including the RUN_ERROR that AG-UI fires when we abort) bail.
+            if (aborted)
+                return;
+            aborted = true;
+            // Settle EVERY in-flight text stream. `ChunkedEditStream.append`
+            // schedules its placeholder post asynchronously (on setupPromise), so a
+            // stream that just received content may still report chunkCount === 0
+            // until that post resolves. If we deleted such a stream without
+            // finishing it, its in-flight postPlaceholder would still resolve and
+            // leave a stray "…" message orphaned forever. `finish()` awaits
+            // setupPromise, so it deterministically creates-and-flushes any pending
+            // placeholder rather than abandoning it.
+            const tasks = [];
+            for (const [id, stream] of Array.from(streams.entries())) {
+                const buf = buffers.get(id) ?? "";
+                if (buf.trim().length > 0) {
+                    // Real content: surface the interrupted marker on the partial reply
+                    // before finishing.
+                    stream.append(buf + INTERRUPTED_SUFFIX);
+                }
+                // Empty/whitespace buffer: just finish(). If nothing was ever posted
+                // it's a no-op; if a placeholder post is in flight it gets flushed/
+                // edited rather than left as a stray "…".
+                tasks.push(stream
+                    .finish()
+                    .catch((e) => console.error("[bot-telegram] stream finalize failed:", e)));
+                streams.delete(id);
+                finalised.add(id);
+            }
+            buffers.clear();
+            await Promise.all(tasks);
+            // Clean up any tool-status placeholders whose END never arrived before
+            // the interrupt — mark them cancelled rather than leaving the stale
+            // "🔧 using <tool>…" line orphaned in the chat.
+            await drainToolStatuses((tool) => `⚠️ ${tool} (cancelled)`);
+        },
+    };
+}

package/dist/format-fallback.d.ts

@@ -0,0 +1,6 @@
+export declare function stripHtml(s: string): string;
+export declare function withTelegramFormatFallback<T>(send: (opts: {
+    parseMode?: "HTML";
+    text: string;
+}) => Promise<T>, text: string): Promise<T>;
+//# sourceMappingURL=format-fallback.d.ts.map

package/dist/format-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-fallback.d.ts","sourceRoot":"","sources":["../src/format-fallback.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3C;AAED,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,IAAI,EAAE,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAChE,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,CAAC,CAcZ"}

package/dist/format-fallback.js

@@ -0,0 +1,21 @@
+export function stripHtml(s) {
+    return s
+        .replace(/<[^>]*>/g, "")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+export async function withTelegramFormatFallback(send, text) {
+    try {
+        return await send({ parseMode: "HTML", text });
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            /can't parse (?:caption )?entities|unsupported start tag|can't find end tag|tag .* is not (?:allowed|closed)/i.test(err.message)) {
+            return send({ text: stripHtml(text) });
+        }
+        throw err;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { telegram, TelegramAdapter } from "./adapter.js";
+export { createRunRenderer } from "./event-renderer.js";
+export type { CreateRunRendererArgs } from "./event-renderer.js";
+export { decodeInteraction, conversationKeyOf, deriveConversationKey, toPlatformUser, } from "./interaction.js";
+export { renderTelegram } from "./render/telegram.js";
+export { TELEGRAM_LIMITS, truncateText, clampArray, byteLen, } from "./render/budget.js";
+export { defaultTelegramTools, lookupTelegramUserTool, } from "./built-in-tools.js";
+export { defaultTelegramContext, telegramTaggingContext, telegramFormattingContext, telegramConversationModelContext, } from "./built-in-context.js";
+export { telegramHtml, escapeHtml } from "./telegram-html.js";
+export { withTelegramFormatFallback, stripHtml } from "./format-fallback.js";
+export { TelegramConversationStore } from "./conversation-store.js";
+export { ChunkedEditStream } from "./chunked-edit-stream.js";
+export type { ChunkedEditStreamConfig } from "./chunked-edit-stream.js";
+export { attachTelegramListener } from "./listener.js";
+export type { ListenerConfig } from "./listener.js";
+export { buildFileContentParts } from "./download-files.js";
+export type { TelegramFileRef, AgentContentPart, FileDeliveryConfig, } from "./download-files.js";
+export type { ConversationKey, ReplyTarget, TelegramMessageRef, TelegramInlineButton, TelegramPayload, TelegramAdapterOptions, } from "./types.js";
+export { DM_SCOPE } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,UAAU,EACV,OAAO,GACR,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,GACjC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,0BAA0B,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export { telegram, TelegramAdapter } from "./adapter.js";
+export { createRunRenderer } from "./event-renderer.js";
+export { decodeInteraction, conversationKeyOf, deriveConversationKey, toPlatformUser, } from "./interaction.js";
+export { renderTelegram } from "./render/telegram.js";
+export { TELEGRAM_LIMITS, truncateText, clampArray, byteLen, } from "./render/budget.js";
+export { defaultTelegramTools, lookupTelegramUserTool, } from "./built-in-tools.js";
+export { defaultTelegramContext, telegramTaggingContext, telegramFormattingContext, telegramConversationModelContext, } from "./built-in-context.js";
+export { telegramHtml, escapeHtml } from "./telegram-html.js";
+export { withTelegramFormatFallback, stripHtml } from "./format-fallback.js";
+export { TelegramConversationStore } from "./conversation-store.js";
+export { ChunkedEditStream } from "./chunked-edit-stream.js";
+export { attachTelegramListener } from "./listener.js";
+export { buildFileContentParts } from "./download-files.js";
+export { DM_SCOPE } from "./types.js";

package/dist/interaction.d.ts

@@ -0,0 +1,65 @@
+import type { InteractionEvent, IncomingReaction } from "@copilotkit/channels";
+import type { PlatformUser } from "@copilotkit/channels-ui";
+import type { ConversationKey } 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 declare function conversationKeyOf(key: ConversationKey): string;
+/**
+ * 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 declare function deriveConversationKey(message: {
+    message_id: number;
+    message_thread_id?: number;
+    chat: {
+        id: number | string;
+        type: string;
+        is_forum?: boolean;
+    };
+    reply_to_message?: {
+        message_id: number;
+    };
+    from?: {
+        id: number;
+    };
+}, userId?: number): ConversationKey;
+/**
+ * Map a Telegram `from` user to a PlatformUser.
+ */
+export declare function toPlatformUser(from: {
+    id: number;
+    first_name?: string;
+    last_name?: string;
+    username?: string;
+}): PlatformUser | undefined;
+/**
+ * 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 declare function decodeReaction(update: unknown): IncomingReaction[];
+/**
+ * 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 declare function decodeInteraction(raw: unknown): InteractionEvent | undefined;
+//# sourceMappingURL=interaction.d.ts.map

package/dist/interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.d.ts","sourceRoot":"","sources":["../src/interaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAChE,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACvB,EACD,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,CAiBjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,YAAY,GAAG,SAAS,CAS3B;AAsBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,EAAE,CA0ClE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CA2D5E"}