@copilotkit/channels-telegram 0.0.3

package/dist/render/telegram.js

@@ -0,0 +1,429 @@
+import { telegramHtml, escapeHtml } from "../telegram-html.js";
+import { TELEGRAM_LIMITS, truncateText, clampArray, byteLen, } from "./budget.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 function renderTelegram(ir) {
+    // Each entry holds the pre-HTML (raw) text and the corresponding HTML for a
+    // line. Separating them lets us apply the character budget to SOURCE text
+    // before HTML conversion, so the emitted HTML is always well-formed.
+    const lineEntries = [];
+    const inlineKeyboard = [];
+    const photos = [];
+    for (const node of ir) {
+        renderNode(node, lineEntries, inlineKeyboard, photos);
+    }
+    // Build the HTML, enforcing the message-text budget on the joined RAW text
+    // (before HTML conversion) so the emitted HTML is always well-formed.
+    //
+    // Bug 2: the budget is measured in RAW chars, but the emitted payload is
+    // HTML — `<b>`, `<a href>`, and `&amp;`/`&lt;` entity expansion add length
+    // that the raw budget does not count. A near-4096 raw message with heavy
+    // markup can therefore exceed Telegram's 4096-char hard limit once converted
+    // ("message is too long", not caught by the format fallback). We bound the
+    // raw text first, then, if the resulting HTML still exceeds the limit,
+    // iteratively shrink the raw budget until the HTML fits — and apply a final
+    // hard guard that slices the HTML at a safe tag/entity boundary if needed.
+    const rawJoined = lineEntries.map((e) => e.raw).join("\n");
+    const LIMIT = TELEGRAM_LIMITS.messageText;
+    let rawBudget = LIMIT;
+    let text = buildBoundedHtml(lineEntries, rawJoined, rawBudget);
+    // Iteratively reduce the raw budget while the HTML overshoots the limit. Each
+    // pass cuts the budget proportionally to the observed overshoot (plus a small
+    // constant) so we converge quickly even under ~5x entity expansion.
+    let guard = 0;
+    while (text.length > LIMIT && rawBudget > 0 && guard < 32) {
+        const overshoot = text.length - LIMIT;
+        // Shrink by at least the overshoot (markup is at least 1:1) plus headroom.
+        rawBudget = Math.max(0, rawBudget - overshoot - 16);
+        text = buildBoundedHtml(lineEntries, rawJoined, rawBudget);
+        guard++;
+    }
+    // Final hard guard: if the HTML is still over (pathological markup density),
+    // slice it at a safe boundary that never splits a tag or an entity.
+    if (text.length > LIMIT) {
+        text = sliceHtmlSafely(text, LIMIT);
+    }
+    const result = { text, parseMode: "HTML" };
+    if (inlineKeyboard.length > 0)
+        result.inlineKeyboard = inlineKeyboard;
+    if (photos.length > 0)
+        result.photos = photos;
+    return result;
+}
+/**
+ * Build the joined HTML for `lineEntries`, enforcing a raw-character budget on
+ * the source text. Full lines reuse their pre-computed html; the last
+ * (possibly truncated) line is re-rendered from its raw slice. Returns
+ * well-formed HTML (no split tag/entity) whose underlying raw content is
+ * ≤ `rawBudget` chars.
+ */
+function buildBoundedHtml(lineEntries, rawJoined, rawBudget) {
+    const rawBounded = truncateText(rawJoined, rawBudget);
+    const wasTruncated = rawBounded.length !== rawJoined.length;
+    if (!wasTruncated) {
+        // Nothing was truncated — use the pre-computed HTML directly.
+        return lineEntries.map((e) => e.html).join("\n");
+    }
+    // Some lines were cut. `rawBounded` ends with a trailing "…" marker that
+    // truncateText appended (occupying one char of the budget but NOT present in
+    // the source entries). Strip it to recover the exact char budget of real
+    // content, walk the entries against that budget, then re-append "…" to the
+    // final emitted slice so the marker is preserved and the reconstructed raw
+    // length stays within budget.
+    const ELLIPSIS = "…";
+    const contentBudget = rawBounded.endsWith(ELLIPSIS)
+        ? rawBounded.length - 1
+        : rawBounded.length;
+    const htmlParts = [];
+    let remaining = contentBudget;
+    let markerEmitted = false;
+    for (const entry of lineEntries) {
+        if (remaining <= 0)
+            break;
+        if (entry.raw.length <= remaining) {
+            htmlParts.push(entry.html);
+            remaining -= entry.raw.length;
+            if (remaining > 0)
+                remaining -= 1; // account for the "\n" separator
+        }
+        else {
+            // This entry is partially truncated — re-render the bounded raw slice
+            // and append the ellipsis marker so dropped content is signalled.
+            const slicedRaw = entry.raw.slice(0, remaining);
+            htmlParts.push(reRenderRawLine(slicedRaw, entry) + ELLIPSIS);
+            markerEmitted = true;
+            break;
+        }
+    }
+    // If the cut fell exactly on a line boundary (no partial line was emitted),
+    // the marker would otherwise be lost. Append it to the last emitted line.
+    if (!markerEmitted && htmlParts.length > 0) {
+        htmlParts[htmlParts.length - 1] += ELLIPSIS;
+    }
+    return htmlParts.join("\n");
+}
+/**
+ * Re-render a truncated raw slice using the structural wrapper the original
+ * node recorded on the entry (Bug 3). Using the stored {@link WrapKind} —
+ * rather than reverse-engineering it from the html via regex — guarantees the
+ * truncated slice is re-wrapped balanced and correctly styled, even for lines
+ * whose html is NOT a single top-level wrapper (e.g. `<i>a</i> b <i>c</i>` or
+ * a `<b>Label</b> value` field).
+ */
+function reRenderRawLine(slicedRaw, entry) {
+    switch (entry.wrap) {
+        case "pre":
+            // Table/preformatted block: the slice is plain text — escape it and wrap
+            // in a balanced <pre>. (telegramHtml would re-interpret markdown that the
+            // original grid never had.)
+            return `<pre>${escapeHtml(slicedRaw)}</pre>`;
+        case "code":
+            return `<code>${escapeHtml(slicedRaw)}</code>`;
+        case "b":
+            // Header: original html was `<b>${escapeHtml(raw)}</b>`. Re-escape the
+            // slice (NOT telegramHtml — headers are plain text, not markdown).
+            return `<b>${escapeHtml(slicedRaw)}</b>`;
+        case "i":
+            // Context/input: original html was `<i>${telegramHtml(raw)}</i>`.
+            return `<i>${telegramHtml(slicedRaw)}</i>`;
+        case "none":
+        case undefined:
+        default:
+            // Inline telegramHtml output (section/markdown/text/fields/raw/divider) —
+            // the html is already balanced inline markup; re-run telegramHtml on the
+            // slice for the same well-formed result.
+            return telegramHtml(slicedRaw);
+    }
+}
+/**
+ * Hard guard for the pathological case where, even after shrinking the raw
+ * budget, the HTML still exceeds `limit` (extreme markup density). Slice the
+ * HTML to at most `limit` chars at a boundary that never splits an open tag or
+ * an `&entity;` — by trimming back to before the last unterminated `<` or `&`.
+ * Note: this is a last-resort safety net; balanced-tag invariants are upheld by
+ * the raw-budget path above, so in practice it is rarely hit.
+ */
+function sliceHtmlSafely(html, limit) {
+    if (html.length <= limit)
+        return html;
+    let cut = html.slice(0, limit);
+    // If we cut inside an unterminated tag (`…<b` / `…<`), trim back to before
+    // the `<`.
+    const lastLt = cut.lastIndexOf("<");
+    const lastGt = cut.lastIndexOf(">");
+    if (lastLt > lastGt)
+        cut = cut.slice(0, lastLt);
+    // If we cut inside an unterminated entity (`…&am` / `…&`), trim back to
+    // before the `&`.
+    const lastAmp = cut.lastIndexOf("&");
+    const lastSemi = cut.lastIndexOf(";");
+    if (lastAmp > lastSemi)
+        cut = cut.slice(0, lastAmp);
+    return cut;
+}
+/** Render a single IR node, appending to lineEntries/inlineKeyboard/photos. */
+function renderNode(node, lineEntries, inlineKeyboard, photos) {
+    if (typeof node.type !== "string")
+        return; // non-intrinsic — skip silently
+    const props = node.props ?? {};
+    /**
+     * Push a line, recording the structural wrapper (Bug 3) so a truncated last
+     * line can be re-wrapped deterministically. `wrap` defaults to "none" for
+     * lines whose html is inline telegramHtml output.
+     */
+    const pushLine = (raw, html, wrap = "none") => lineEntries.push({ raw, html, wrap });
+    /** Push an inline-html line (no structural wrapper). */
+    const pushRaw = (raw, html) => pushLine(raw, html, "none");
+    switch (node.type) {
+        case "message": {
+            // Container — flatten children.
+            for (const child of childNodes(node)) {
+                renderNode(child, lineEntries, inlineKeyboard, photos);
+            }
+            return;
+        }
+        case "header": {
+            const raw = truncateText(collectText(node), 256);
+            pushLine(raw, `<b>${escapeHtml(raw)}</b>`, "b");
+            return;
+        }
+        case "section":
+        case "markdown": {
+            const raw = collectText(node);
+            pushRaw(raw, telegramHtml(raw));
+            return;
+        }
+        case "text": {
+            // collectText on a text node returns props.value directly.
+            const raw = collectText(node);
+            pushRaw(raw, telegramHtml(raw));
+            return;
+        }
+        case "fields": {
+            const fieldChildren = childNodes(node).filter((c) => c.type === "field");
+            for (const f of fieldChildren) {
+                const fieldProps = f.props ?? {};
+                const label = fieldProps.label;
+                const children = childNodes(f);
+                if (label) {
+                    // Has a label: <b>label</b> value
+                    const valueText = collectText(f);
+                    const raw = `${label} ${valueText}`;
+                    pushRaw(raw, `<b>${escapeHtml(label)}</b> ${telegramHtml(valueText)}`);
+                }
+                else if (children.length === 1 &&
+                    children[0] &&
+                    children[0].type === "text") {
+                    // Single text child — bold it.
+                    const raw = collectText(f);
+                    pushRaw(raw, `<b>${telegramHtml(raw)}</b>`);
+                }
+                else {
+                    const raw = collectText(f);
+                    pushRaw(raw, telegramHtml(raw));
+                }
+            }
+            return;
+        }
+        case "field": {
+            const fieldProps = props;
+            const label = fieldProps.label;
+            const children = childNodes(node);
+            if (label) {
+                const valueText = collectText(node);
+                const raw = `${label} ${valueText}`;
+                pushRaw(raw, `<b>${escapeHtml(label)}</b> ${telegramHtml(valueText)}`);
+            }
+            else if (children.length === 1 &&
+                children[0] &&
+                children[0].type === "text") {
+                const raw = collectText(node);
+                pushRaw(raw, `<b>${telegramHtml(raw)}</b>`);
+            }
+            else {
+                const raw = collectText(node);
+                pushRaw(raw, telegramHtml(raw));
+            }
+            return;
+        }
+        case "context": {
+            const raw = collectText(node);
+            pushLine(raw, `<i>${telegramHtml(raw)}</i>`, "i");
+            return;
+        }
+        case "divider": {
+            pushRaw("──────", "──────");
+            return;
+        }
+        case "image": {
+            const url = (props.url ?? props.image_url);
+            const alt = (props.alt ?? props.altText ?? "");
+            if (url) {
+                // Bug 3 fix: cap caption to TELEGRAM_LIMITS.caption (1024 chars).
+                const caption = alt
+                    ? truncateText(alt, TELEGRAM_LIMITS.caption)
+                    : undefined;
+                const { items } = clampArray([...photos, { url, caption }], TELEGRAM_LIMITS.photosPerMessage);
+                photos.splice(0, photos.length, ...items);
+            }
+            return;
+        }
+        case "actions": {
+            const buttons = childNodes(node)
+                .map(renderActionButton)
+                .filter((b) => b !== null);
+            // Bug 4 fix: cap against the running total across the whole keyboard, not
+            // per-node, so multiple actions/select blocks can't exceed the limit.
+            appendButtons(inlineKeyboard, buttons);
+            return;
+        }
+        case "select": {
+            const options = props.options ?? [];
+            // Bug 2 fix: degrade (skip) options whose callback_data exceeds 64 bytes
+            // instead of throwing — keeps the rest of the message intact.
+            // Consistency: use JSON.stringify(value) (same as actionIdOf) when no id.
+            const buttons = options
+                .map((o) => {
+                const callbackData = o.id ? o.id : JSON.stringify(o.value);
+                if (byteLen(callbackData) > TELEGRAM_LIMITS.callbackData) {
+                    return null; // degrade: skip this option silently
+                }
+                return {
+                    text: truncateText(String(o.label ?? ""), TELEGRAM_LIMITS.buttonText),
+                    callbackData,
+                };
+            })
+                .filter((b) => b !== null);
+            // Bug 4 fix: cap against the running keyboard total (see "actions").
+            appendButtons(inlineKeyboard, buttons);
+            return;
+        }
+        case "input": {
+            const raw = "(open the chat to type your answer)";
+            pushLine(raw, `<i>${escapeHtml(raw)}</i>`, "i");
+            return;
+        }
+        case "table": {
+            // Render as monospace <pre> grid.
+            const columnsProp = props.columns;
+            const rowNodes = childNodes(node).filter((c) => c.type === "row");
+            const tableRows = [];
+            if (columnsProp && columnsProp.length > 0) {
+                tableRows.push(columnsProp.map((c) => c.header));
+            }
+            for (const rowNode of rowNodes) {
+                const cells = childNodes(rowNode).filter((c) => c.type === "cell");
+                tableRows.push(cells.map((cell) => collectText(cell)));
+            }
+            if (tableRows.length > 0) {
+                // Compute column widths.
+                const colCount = Math.max(...tableRows.map((r) => r.length));
+                const colWidths = Array(colCount).fill(0);
+                for (const row of tableRows) {
+                    for (let i = 0; i < row.length; i++) {
+                        colWidths[i] = Math.max(colWidths[i] ?? 0, (row[i] ?? "").length);
+                    }
+                }
+                const gridLines = tableRows.map((row) => row.map((cell, i) => cell.padEnd(colWidths[i] ?? 0)).join("  "));
+                const rawGrid = gridLines.join("\n");
+                pushLine(rawGrid, `<pre>${escapeHtml(rawGrid)}</pre>`, "pre");
+            }
+            return;
+        }
+        case "raw": {
+            const value = props.value;
+            if (value !== null &&
+                typeof value === "object" &&
+                "text" in value) {
+                const rawText = value.text;
+                if (typeof rawText === "string") {
+                    pushRaw(rawText, telegramHtml(rawText));
+                    return;
+                }
+            }
+            const rawStr = JSON.stringify(value);
+            pushRaw(rawStr, telegramHtml(rawStr));
+            return;
+        }
+        default:
+            // Unknown intrinsic — skip silently (total renderer).
+            return;
+    }
+}
+/**
+ * Append buttons to the inline keyboard, chunked into rows of buttonsPerRow,
+ * while enforcing {@link TELEGRAM_LIMITS.buttonsPerMessage} across the ENTIRE
+ * keyboard (Bug 4). Counts buttons already present from prior actions/select
+ * nodes and silently drops any overflow rather than throwing — Telegram would
+ * otherwise reject the whole message.
+ */
+function appendButtons(inlineKeyboard, buttons) {
+    const alreadyAdded = inlineKeyboard.reduce((sum, row) => sum + row.length, 0);
+    const capacity = TELEGRAM_LIMITS.buttonsPerMessage - alreadyAdded;
+    if (capacity <= 0)
+        return;
+    const accepted = buttons.slice(0, capacity);
+    for (let i = 0; i < accepted.length; i += TELEGRAM_LIMITS.buttonsPerRow) {
+        inlineKeyboard.push(accepted.slice(i, i + TELEGRAM_LIMITS.buttonsPerRow));
+    }
+}
+/** Render one button node for an inline keyboard. Returns null for non-renderable nodes. */
+function renderActionButton(node) {
+    if (typeof node.type !== "string")
+        return null;
+    if (node.type !== "button")
+        return null;
+    const props = node.props ?? {};
+    const buttonText = truncateText(collectText(node), TELEGRAM_LIMITS.buttonText);
+    if (props.url) {
+        return { text: buttonText, url: props.url };
+    }
+    const id = actionIdOf(props);
+    // Bug 2 fix: degrade (skip) buttons whose callback_data exceeds 64 bytes
+    // instead of throwing — keeps the rest of the message intact.
+    if (byteLen(id) > TELEGRAM_LIMITS.callbackData) {
+        return null;
+    }
+    return { text: buttonText, callbackData: id };
+}
+/** Derive callback data: prefer registry-stamped id, else value, else "action". */
+function actionIdOf(props) {
+    const onClick = props.onClick;
+    if (onClick != null && "id" in onClick) {
+        const id = onClick.id;
+        if (typeof id === "string")
+            return id;
+    }
+    if (props.value !== undefined) {
+        return JSON.stringify(props.value);
+    }
+    return "action";
+}
+/** The expanded `children` of an IR node as a `BotNode[]` (empty if none). */
+function childNodes(node) {
+    const children = node.props?.children;
+    if (Array.isArray(children))
+        return children;
+    if (children &&
+        typeof children === "object" &&
+        "type" in children) {
+        return [children];
+    }
+    return [];
+}
+/** Concatenate the `value` of all descendant `text` nodes (depth-first). */
+function collectText(node) {
+    if (typeof node.type === "string" && node.type === "text") {
+        return String(node.props?.value ?? "");
+    }
+    let acc = "";
+    for (const child of childNodes(node)) {
+        acc += collectText(child);
+    }
+    return acc;
+}

package/dist/telegram-html.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Translate the agent's standard Markdown into Telegram HTML parse mode.
+ *
+ * Telegram HTML supports only: <b> <i> <u> <s> <a href> <code> <pre> <tg-spoiler>
+ * All & < > in text must be entity-escaped.
+ *
+ *   Markdown         →  Telegram HTML
+ *   **bold**         →  <b>bold</b>
+ *   __bold__         →  <b>bold</b>
+ *   *italic*         →  <i>italic</i>
+ *   _italic_         →  <i>italic</i>
+ *   ~~strike~~       →  <s>strike</s>
+ *   # heading        →  <b>heading</b>
+ *   [text](url)      →  <a href="url">text</a>
+ *   - bullet         →  •  bullet
+ *   `code`           →  <code>code</code>
+ *   ```…```          →  <pre>…</pre>
+ */
+/** Escape & < > " for use inside Telegram HTML text nodes and attributes. */
+export declare function escapeHtml(s: string): string;
+export declare function telegramHtml(input: string): string;
+//# sourceMappingURL=telegram-html.d.ts.map

package/dist/telegram-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-html.d.ts","sourceRoot":"","sources":["../src/telegram-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5C;AAcD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmFlD"}

package/dist/telegram-html.js

@@ -0,0 +1,98 @@
+/**
+ * Translate the agent's standard Markdown into Telegram HTML parse mode.
+ *
+ * Telegram HTML supports only: <b> <i> <u> <s> <a href> <code> <pre> <tg-spoiler>
+ * All & < > in text must be entity-escaped.
+ *
+ *   Markdown         →  Telegram HTML
+ *   **bold**         →  <b>bold</b>
+ *   __bold__         →  <b>bold</b>
+ *   *italic*         →  <i>italic</i>
+ *   _italic_         →  <i>italic</i>
+ *   ~~strike~~       →  <s>strike</s>
+ *   # heading        →  <b>heading</b>
+ *   [text](url)      →  <a href="url">text</a>
+ *   - bullet         →  •  bullet
+ *   `code`           →  <code>code</code>
+ *   ```…```          →  <pre>…</pre>
+ */
+/** Escape & < > " for use inside Telegram HTML text nodes and attributes. */
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+// Unique placeholder that won't appear in normal text.
+// Uses a non-regex-control-char delimiter so ESLint is happy.
+const CODE_PLACEHOLDER_RE = /\u{FFFE}CODE(\d+)\u{FFFE}/gu;
+function codePlaceholder(i) {
+    return `￾CODE${i}￾`;
+}
+const LINK_PLACEHOLDER_RE = /\u{FFFE}LINK(\d+)\u{FFFE}/gu;
+function linkPlaceholder(i) {
+    return `￾LINK${i}￾`;
+}
+export function telegramHtml(input) {
+    if (!input)
+        return input;
+    // ── 1. Pull code regions out so we don't touch them. ──
+    const codeRegions = [];
+    // Fenced code blocks first (```…```)
+    let body = input.replace(/```([\s\S]*?)```/g, (_match, inner) => {
+        const escaped = escapeHtml(inner.replace(/^\n/, "").replace(/\n$/, ""));
+        codeRegions.push(`<pre>${escaped}</pre>`);
+        return codePlaceholder(codeRegions.length - 1);
+    });
+    // Inline code `…`
+    body = body.replace(/`([^`\n]*)`/g, (_match, inner) => {
+        const escaped = escapeHtml(inner);
+        codeRegions.push(`<code>${escaped}</code>`);
+        return codePlaceholder(codeRegions.length - 1);
+    });
+    // ── 1b. Pull markdown links out before bold/italic transforms mangle URLs. ──
+    // The link text and URL will be HTML-escaped in step 2 below via the
+    // global escapeHtml pass on the placeholder-free body; the final <a> tag
+    // is assembled after escaping so the URL keeps its escaped form (single-escape,
+    // consistent with the existing `&`-in-URL behaviour).
+    const linkRegions = [];
+    body = body.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/g, (_m, text, url) => {
+        linkRegions.push({ text, url });
+        return linkPlaceholder(linkRegions.length - 1);
+    });
+    // ── 2. Escape HTML-special chars in the remaining (non-code) text. ──
+    body = escapeHtml(body);
+    // ── 3. Bold first, into a sentinel; then italic won't eat its output. ──
+    const BOLD_OPEN = "\x01B\x01";
+    const BOLD_CLOSE = "\x02B\x02";
+    body = body.replace(/\*\*([^\n*]+?)\*\*/g, `${BOLD_OPEN}$1${BOLD_CLOSE}`);
+    body = body.replace(/__([^\n_]+?)__/g, `${BOLD_OPEN}$1${BOLD_CLOSE}`);
+    // Headings (#…) → bold
+    body = body.replace(/^\s{0,3}#{1,6}\s+(.*)$/gm, (_m, text) => `${BOLD_OPEN}${text.trim()}${BOLD_CLOSE}`);
+    // Strikethrough ~~text~~ → <s>text</s>
+    body = body.replace(/~~([^\n~]+?)~~/g, "<s>$1</s>");
+    // Italic *text* or _text_ → <i>text</i> (skip bold sentinels)
+    body = body.replace(/(^|[^*\w])\*(\S(?:[^*\n]*\S)?)\*(?!\w)/g, "$1<i>$2</i>");
+    body = body.replace(/(^|[^_\w])_(\S(?:[^_\n]*\S)?)_(?!\w)/g, "$1<i>$2</i>");
+    // Bullet list markers: `- ` / `* ` / `+ ` at the start of a line → "•  "
+    body = body.replace(/^(\s*)[-*+]\s+/gm, "$1•  ");
+    // ── 4. Restore sentinels and code regions. ──
+    body = body.replace(new RegExp(BOLD_OPEN, "g"), "<b>");
+    body = body.replace(new RegExp(BOLD_CLOSE, "g"), "</b>");
+    body = body.replace(CODE_PLACEHOLDER_RE, (_m, idx) => codeRegions[Number(idx)] ?? "");
+    // ── 5. Restore link placeholders LAST so URLs are never touched by markup passes. ──
+    // text and url were captured from the raw input before escapeHtml; escapeHtml
+    // was applied globally to the body (which at that point contained only the
+    // placeholder token), so here we escape text/url ourselves to produce the
+    // same single-escaped output the old inline regex produced.
+    body = body.replace(LINK_PLACEHOLDER_RE, (_m, idx) => {
+        const link = linkRegions[Number(idx)];
+        if (!link)
+            return "";
+        const escapedUrl = escapeHtml(link.url);
+        const escapedText = escapeHtml(link.text);
+        return `<a href="${escapedUrl}">${escapedText}</a>`;
+    });
+    return body;
+}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+import type { MessageRef } from "@copilotkit/channels-ui";
+/** Sentinel scope used for DMs (DMs are flat — no thread). */
+export declare const DM_SCOPE = "dm";
+/**
+ * Stable key identifying one ongoing conversation with the bot.
+ *
+ * - For a group/forum thread: `{ chatId, scope: <threadId> }`
+ * - For a DM:                 `{ chatId, scope: "dm" }`
+ *
+ * The store uses the pair as a string key; conversations from different
+ * chats never collide.
+ */
+export interface ConversationKey {
+    chatId: string;
+    scope: string;
+}
+/**
+ * Where to post a reply in Telegram. Used by the renderer; constructed by
+ * the listener once per turn.
+ */
+export interface ReplyTarget {
+    chatId: number | string;
+    /** Forum thread id to post into. Omit for flat replies (DMs). */
+    messageThreadId?: number;
+    /** Message id to reply to. */
+    replyToMessageId?: number;
+    /** Whether the chat is a forum supergroup. */
+    isForum?: boolean;
+    /**
+     * The exact conversation key for this turn, stamped at ingress so egress
+     * (post/getMessages) keys history identically to the listener — avoids
+     * re-deriving (which can't reproduce the group `user:` scope).
+     */
+    conversationKey?: string;
+}
+/** A stable reference to one Telegram message. */
+export interface TelegramMessageRef extends MessageRef {
+    id: string;
+    chatId: number | string;
+    messageId: number;
+}
+/** A single button in an inline keyboard. */
+export interface TelegramInlineButton {
+    text: string;
+    callbackData?: string;
+    url?: string;
+}
+/** The wire payload sent to the Telegram Bot API. */
+export interface TelegramPayload {
+    text: string;
+    parseMode: "HTML";
+    inlineKeyboard?: TelegramInlineButton[][];
+    photos?: {
+        url: string;
+        caption?: string;
+    }[];
+}
+/** Options accepted by the Telegram adapter constructor. */
+export interface TelegramAdapterOptions {
+    /** Bot token from @BotFather. */
+    token: string;
+    /** How to receive updates. Defaults to "polling" (long-polling); "webhook" and "auto" are opt-in. */
+    mode?: "polling" | "webhook" | "auto";
+    /** Webhook configuration (required when mode is "webhook" or "auto" with a domain). */
+    webhook?: {
+        domain: string;
+        path?: string;
+        port?: number;
+        secretToken?: string;
+    };
+    /** AG-UI event names that should interrupt the running agent. */
+    interruptEventNames?: ReadonlySet<string>;
+    /** Surface "using <tool>…" status messages while the agent runs. */
+    showToolStatus?: boolean;
+    /** Posted when a user starts a conversation. */
+    greeting?: string;
+    /** Prompt chips shown at conversation start. */
+    suggestedPrompts?: {
+        title: string;
+        message: string;
+    }[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,8DAA8D;AAC9D,eAAO,MAAM,QAAQ,OAAO,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8BAA8B;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,oBAAoB,EAAE,EAAE,CAAC;IAC1C,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9C;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,qGAAqG;IACrG,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IACtC,uFAAuF;IACvF,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,oEAAoE;IACpE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACzD"}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Sentinel scope used for DMs (DMs are flat — no thread). */
+export const DM_SCOPE = "dm";