@capybara-hq/plugin-telegram 0.1.0-rc.5 → 0.1.0-rc.7

package/.capybara-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "name": "telegram",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.7",
   "publisher": "Capybara",
   "description": {
     "en": "Telegram (channel@1 bot over the Bot API: long polling or webhook, inline keyboard cards)",
@@ -17,7 +17,7 @@
     "entry": "./dist/index.mjs",
     "manifest": {
       "name": "telegram",
-      "version": "0.1.0-rc.5",
+      "version": "0.1.0-rc.7",
       "sdk": "^0.1.0-rc.4",
       "provides": [
         "channel@1"

package/README.md

@@ -14,18 +14,21 @@ global (one person has the same id for every bot), so one person is one identity
 
 The Telegram docs cited here are the [Bot API reference](https://core.telegram.org/bots/api) (Bot API 10.3), consulted on 2026-11-08.
 
-Verified live on 2026-11-08 against a real bot: verify, send, edit, a 5000-character split send and a card with an inline callback keyboard, in a private chat and in a basic group. Not covered live: a person clicking a card button, webhook mode and forum supergroups.
+Verified live on 2026-11-08 against a real bot: verify, send, edit, a 5000-character split send and a card with an inline callback keyboard, in a private chat and in a basic group. Verified live on 2026-11-10: a reply with a table sent as a rich message, and a plain draft edited into one and edited again, in a private chat (live test `rich table`; in Node, a slow IPv4 connect can lose to an unreachable IPv6 address: run it with `NODE_OPTIONS=--network-family-autoselection-attempt-timeout=3000` if every call fails with a network error). Not covered live: a person clicking a card button, webhook mode and forum supergroups.
 
 ## Create the bot
 
 1. In Telegram, open [@BotFather](https://t.me/BotFather) and send `/newbot`. Pick a display name and a username
    (it must end in `bot`). BotFather replies with the bot token, such as `123456:ABC-DEF…`
    ([Bot API: authorizing your bot](https://core.telegram.org/bots/api#authorizing-your-bot)). Treat it like a password.
-2. **Privacy mode** (`/setprivacy`): leave it **enabled** (the default). With it on, a bot in a group receives only
-   commands, mentions of the bot and replies to the bot's own messages, which is exactly what this plugin forwards
-   ([Bot API: `getMe`, `can_read_all_group_messages`](https://core.telegram.org/bots/api#getme)).
-   If you turn it off the bot receives every group message; the plugin still forwards only mentions and replies to
-   the bot, and `verify` logs a warning. Telegram applies a privacy change to a group only after the bot is removed from the group and added again.
+2. **Privacy mode** (`/setprivacy`): for groups, turn it **off** (`Disable`), or make the bot an admin of
+   each group it joins. With privacy mode on (the default), Telegram delivers group commands addressed to the
+   bot (`/cmd@botname`) and replies to the bot's messages, but **not** a plain `@botname` mention, although
+   BotFather's description says otherwise (verified live 2026-11-10;
+   [Bot API: privacy mode](https://core.telegram.org/bots/features#privacy-mode)). With it off the bot receives
+   every group message; the plugin still forwards only mentions of the bot and replies to it, everything else
+   is dropped. Telegram applies a privacy change to a group only after the bot is removed from the group and
+   added again. `verify` logs a warning while privacy mode is on. Private chats work either way.
 3. **Groups** (`/setjoingroups`): enable it if people should add the bot to groups, disable it for a private-only bot.
 4. **Topics in private chats**: leave the bot's topic mode off. It is not supported (see [Behavior](#behavior)); `verify` warns when it is on.
 5. In the Capybara org settings, enable the `telegram` plugin, then **create a new channel connection** under Channels:
@@ -85,13 +88,22 @@ The deployment-level config lives under the kernel config `extensionConfig.teleg
 - **Format**: the model reply's Markdown is converted to Telegram HTML (`parse_mode: "HTML"`); everything else is escaped.
   Link previews are off. Links are limited to http(s): `tg://` and other schemes stay plain text, so model text cannot produce `tg://user?id=…` mentions.
   A raw `@username` in model text would notify people, so the converter puts a U+2060 WORD JOINER after the `@` outside code and links, and Telegram no longer parses it as a mention.
-- **Limit and splitting**: one message holds at most 4096 characters after entity parsing
+- **Tables**: a reply with a Markdown (GFM) table is sent as a [rich message](https://core.telegram.org/bots/api/rich-messages)
+  (Bot API 10.1: [`sendRichMessage`](https://core.telegram.org/bots/api#sendrichmessage), and `editMessageText` with `rich_message` while it streams),
+  so the table renders natively (bordered, striped, column alignment from the delimiter row). The rest of the reply goes through the same converter
+  as plain replies (escaping, http(s)-only links, the mention guard), as rich HTML with `<br>` line breaks (rich HTML collapses bare newlines).
+  A rich message holds up to 32768 characters, so such a reply is never split. A table wider than 20 columns becomes the list described below;
+  a reply over 500 blocks (table rows count) or 32768 characters, or one with cards, is sent as plain HTML.
+  When Telegram refuses the rich message for its content (any 400, or 404 from a Bot API server without the method), the same reply is sent or edited
+  as plain HTML, where each table is a list (one item per row, led by its first cell); flood waits, 5xx and a blocked bot are not retried as plain HTML.
+  Telegram turns a text message into a rich one and back on edit, so streaming keeps the send-then-edit flow (no delete and resend, no extra notification).
+- **Limit and splitting**: one plain message holds at most 4096 characters after entity parsing
   ([`sendMessage`, `text`](https://core.telegram.org/bots/api#sendmessage)); longer text is split into several messages and the last id is returned.
   An edit that would need several messages reports `too_large` and the kernel sends a new message instead.
 - **Streaming edits**: replies are sent and then edited ([`editMessageText`](https://core.telegram.org/bots/api#editmessagetext)); `minEditIntervalMs = 3000`.
   Telegram's limit for a group is about 20 messages per minute ([Broadcasting to users, FAQ](https://core.telegram.org/bots/faq))
   and edits count; a 429 is honored through `retry_after`. "message is not modified" on an edit counts as success.
-  [`sendMessageDraft`](https://core.telegram.org/bots/api#sendmessagedraft) is not used: it exists only in private chats, is a 30-second preview that must be followed by a real
+  [`sendMessageDraft`](https://core.telegram.org/bots/api#sendmessagedraft) and `sendRichMessageDraft` are not used: it exists only in private chats, is a 30-second preview that must be followed by a real
   `sendMessage`, and does not fit the kernel's send-then-edit model.
 - **Idempotency**: the Bot API has no idempotent send, so `idempotencyKey` is ignored. A send whose response is lost and is retried can show the message twice; the alternative (never retrying) would lose messages.
 - **Permission manifest**: `network: ["api.telegram.org"]`, shown only and not enforced.

package/dist/index.mjs

@@ -291,9 +291,14 @@ function splitRow(line) {
 }
 var candidate = (line) => !/^\s{4,}/.test(line) && !/^\s*>/.test(line);
 function delimiterRow(line, width) {
-  if (line === void 0 || !candidate(line)) return false;
+  if (line === void 0 || !candidate(line)) return void 0;
   const cells = splitRow(line);
-  return cells !== void 0 && cells.length === width && cells.every((c) => DELIM_CELL.test(c));
+  if (cells === void 0 || cells.length !== width || !cells.every((c) => DELIM_CELL.test(c))) {
+    return void 0;
+  }
+  return cells.map(
+    (c) => c.startsWith(":") ? c.endsWith(":") ? "center" : "left" : c.endsWith(":") ? "right" : void 0
+  );
 }
 var fit = (cells, width) => Array.from({ length: width }, (_, i) => cells[i] ?? "");
 function segmentTables(md) {
@@ -313,7 +318,8 @@ function segmentTables(md) {
       continue;
     }
     const header = !inFence && candidate(line) ? splitRow(line) : void 0;
-    if (!header || !delimiterRow(lines[i + 1], header.length)) {
+    const align = header && delimiterRow(lines[i + 1], header.length);
+    if (!header || !align) {
       text.push(line);
       continue;
     }
@@ -327,7 +333,7 @@ function segmentTables(md) {
       rows.push(fit(cells, header.length));
     }
     flushText();
-    out.push({ kind: "table", table: { header, rows } });
+    out.push({ kind: "table", table: { header, rows, align } });
     i = j - 1;
   }
   flushText();
@@ -337,7 +343,7 @@ var BR = /<br\s*\/?>/gi;
 var CJK_END = /[⺀-鿿가-힯豈-﫿＀-￯]$/u;
 var INDENT = "   ";
 var pair = (h, v) => h === "" ? v : `${h}${CJK_END.test(h) ? "：" : ": "}${v}`;
-var lead = (cell) => /`|\*\*|__/.test(cell) ? cell : `**${cell}**`;
+var lead = (cell2) => /`|\*\*|__/.test(cell2) ? cell2 : `**${cell2}**`;
 function tableToListMarkdown(t) {
   const clean = (s) => s.replace(BR, " / ").trim();
   const header = t.header.map(clean);
@@ -442,8 +448,8 @@ function codeBlock(lang, lines) {
   const l = lang.replace(/[^A-Za-z0-9_+#.-]/g, "");
   return l === "" ? `<pre>${body}</pre>` : `<pre><code class="language-${l}">${body}</code></pre>`;
 }
-function markdownToTelegramHtml(md) {
-  const lines = tablesToLists(md.replace(/\r\n?/g, "\n").replaceAll("\0", "")).split("\n");
+var normaliseMarkdown = (md) => md.replace(/\r\n?/g, "\n").replaceAll("\0", "");
+function convertLines(lines) {
   const out = [];
   let fence;
   let quote;
@@ -476,7 +482,10 @@ function markdownToTelegramHtml(md) {
   }
   if (fence) out.push(codeBlock(fence.lang, fence.lines));
   closeQuote();
-  return neutraliseHtmlMentions(out.join("\n"));
+  return out.join("\n");
+}
+function markdownToTelegramHtml(md) {
+  return neutraliseHtmlMentions(convertLines(tablesToLists(normaliseMarkdown(md)).split("\n")));
 }
 function tokenise(html) {
   const tokens = [];
@@ -599,10 +608,12 @@ var urlButton = (text, url) => isHttp(url) ? [{ text, url }] : [];
 function cardText(card, locale) {
   const url = card.kind === "connect" || card.kind === "bind" ? card.url : card.webUrl;
   const lines = renderCardAsText(card, locale).split("\n");
-  const last = lines[lines.length - 1];
-  if (lines.length > 1 && last?.endsWith(url)) {
-    lines.pop();
-    const label = markdownToTelegramHtml(last.slice(0, last.length - url.length));
+  let at = lines.length - 1;
+  if (card.kind === "question" && card.state === "pending" && card.textReply !== void 0) at--;
+  const line = lines[at];
+  if (at > 0 && line?.endsWith(url)) {
+    lines.splice(at, 1);
+    const label = markdownToTelegramHtml(line.slice(0, line.length - url.length));
     return { body: markdownToTelegramHtml(lines.join("\n")), linkLine: `${label}${htmlLink(url)}` };
   }
   return { body: markdownToTelegramHtml(lines.join("\n")) };
@@ -649,7 +660,9 @@ async function keyboard(card, locale, tokens) {
     case "question": {
       const f = card.form.fields[0];
       const rows = [];
-      if (card.state === "pending" && f && !f.multiSelect && questionRenderableInline(card.form) && "enum" in f.schema) {
+      if (card.state === "pending" && f && !f.multiSelect && // With textReply the Other path is a plain reply: a field with allowOther still gets its
+      // option buttons, never an Other button.
+      questionRenderableInline(card.form, { textReply: card.textReply !== void 0 }) && "enum" in f.schema) {
         for (const option of f.schema.enum) {
           rows.push(
             await callbackButton(tokens, option, {
@@ -1043,6 +1056,50 @@ async function writeOffset(kv, key, offset, log) {
   }
 }
 
+// src/rich.ts
+var RICH_LIMITS = { text: 32768, blocks: 500, columns: 20 };
+function cell(tag, text, align) {
+  const body = text.split(BR).map((part) => inline(part.trim())).join("<br>");
+  return `<${tag}${align ? ` align="${align}"` : ""}>${body}</${tag}>`;
+}
+function tableToRichHtml(t) {
+  const row = (tag, cells) => `<tr>${cells.map((c, i) => cell(tag, c, t.align[i])).join("")}</tr>`;
+  return `<table bordered striped>${row("th", t.header)}${t.rows.map((r) => row("td", r)).join("")}</table>`;
+}
+function textToRichHtml(html) {
+  return html.split(/(<pre[^>]*>[\s\S]*?<\/pre>)/).map(
+    (part, i) => i % 2 === 1 ? part : part.replace(/\n*(<\/?blockquote>)\n*/g, "$1").replace(/^\n+|\n+$/g, "").replace(/\n/g, "<br>")
+  ).join("");
+}
+function markdownToRichHtml(md) {
+  const segments = segmentTables(normaliseMarkdown(md));
+  const native = (t) => t.header.length <= RICH_LIMITS.columns;
+  if (!segments.some((s) => s.kind === "table" && native(s.table))) return void 0;
+  const parts = [];
+  let lines = [];
+  let blocks = 0;
+  const flush = () => {
+    const html2 = textToRichHtml(convertLines(lines));
+    lines = [];
+    if (html2 === "") return;
+    parts.push(html2);
+    blocks += 1 + (html2.match(/<pre|<blockquote/g)?.length ?? 0);
+  };
+  for (const s of segments) {
+    if (s.kind === "text") lines.push(...s.lines);
+    else if (!native(s.table)) lines.push(...tableToListMarkdown(s.table));
+    else {
+      flush();
+      parts.push(tableToRichHtml(s.table));
+      blocks += 1 + s.table.rows.length + 1;
+    }
+  }
+  flush();
+  const html = neutraliseHtmlMentions(parts.join(""));
+  if (blocks > RICH_LIMITS.blocks || visibleLength(html) > RICH_LIMITS.text) return void 0;
+  return html;
+}
+
 // src/webhook.ts
 import { timingSafeEqual } from "node:crypto";
 var SECRET_HEADER = "x-telegram-bot-api-secret-token";
@@ -1123,6 +1180,13 @@ var tooLarge = () => new ChannelSendError2("message too long for a single Telegr
   reason: "too_large"
 });
 var urlButtonRejected = (e) => e instanceof TelegramApiError && (e.errorCode ?? e.status) === 400 && /button URL|Wrong HTTP URL|BUTTON_URL_INVALID/i.test(e.description ?? "");
+var richRefused = (e) => {
+  if (!(e instanceof TelegramApiError)) return false;
+  const mapped = toChannelSendError(e);
+  return !mapped.retryable && (mapped.reason === "rejected" || mapped.reason === "too_large");
+};
+var notModified = (e) => e instanceof TelegramApiError && /message is not modified/i.test(e.description ?? "");
+var richOf = (message) => (message.cards ?? []).length === 0 && message.text.trim() !== "" ? markdownToRichHtml(message.text) : void 0;
 function createTelegramChannel(o) {
   const apiFor = (config, signal) => {
     const c = TelegramConnection.parse(config);
@@ -1163,6 +1227,33 @@ function createTelegramChannel(o) {
       return attempt(post.withoutUrlButtons);
     }
   }
+  const warnRichFallback = (e, method) => o.log.warn("telegram: Telegram refused a rich message; the reply is sent as plain HTML", {
+    method,
+    ...e instanceof TelegramApiError && { error: e.description ?? e.message }
+  });
+  async function sendRich(api, target, html, extra) {
+    let r;
+    try {
+      r = await api.call("sendRichMessage", {
+        chat_id: target.chatId,
+        rich_message: { html },
+        ...extra
+      });
+    } catch (e) {
+      if (richRefused(e)) {
+        warnRichFallback(e, "sendRichMessage");
+        return void 0;
+      }
+      throw toChannelSendError(e);
+    }
+    if (typeof r?.message_id !== "number") {
+      throw new ChannelSendError2("Telegram returned no message id", {
+        retryable: false,
+        reason: "rejected"
+      });
+    }
+    return r.message_id;
+  }
   async function sendOne(api, target, post, extra) {
     let r;
     try {
@@ -1197,9 +1288,9 @@ function createTelegramChannel(o) {
       if (typeof me?.id !== "number" || !me.username) {
         throw new Error("Telegram getMe returned no bot user");
       }
-      if (me.can_read_all_group_messages) {
+      if (!me.can_read_all_group_messages) {
         o.log.warn(
-          "telegram: the bot can read all group messages (privacy mode is off); only mentions and replies to the bot are forwarded",
+          "telegram: privacy mode is on, so in groups the bot gets only commands and replies to its messages, not plain @mentions; turn privacy mode off in BotFather (then remove and re-add the bot to each group) or make the bot a group admin",
           { botId: me.id }
         );
       }
@@ -1281,8 +1372,11 @@ function createTelegramChannel(o) {
     },
     async send({ config, target, message, locale, signal }) {
       const { call, botId } = apiFor(config, signal);
-      const posts = await render(message, locale, botId);
-      if (posts.length === 0) throw new ChannelSendError2("nothing to send", { retryable: false });
+      const rich = richOf(message);
+      const posts = rich === void 0 ? await render(message, locale, botId) : [];
+      if (rich === void 0 && posts.length === 0) {
+        throw new ChannelSendError2("nothing to send", { retryable: false });
+      }
       const store = threadStore(o.kv, botId);
       const inThread = target.chatType === "group" && target.threadId !== void 0;
       const extra = {};
@@ -1294,25 +1388,50 @@ function createTelegramChannel(o) {
         const topic = await store.topicOf(target.threadId);
         if (topic !== void 0) extra.message_thread_id = topic;
       }
+      const record = async (sent) => {
+        if (!inThread || target.threadId === void 0) return;
+        try {
+          await store.recordSent(target.chatId, sent, target.threadId);
+        } catch {
+          o.log.warn("telegram: could not record a sent message's thread", {
+            chatId: target.chatId,
+            messageId: sent
+          });
+        }
+      };
+      if (rich !== void 0) {
+        const sent = await sendRich({ call }, target, rich, extra);
+        if (sent !== void 0) {
+          await record(sent);
+          return { messageId: `${target.chatId}:${sent}` };
+        }
+        posts.push(...await render(message, locale, botId));
+      }
       let last = 0;
       for (const post of posts) {
         last = await sendOne({ call }, target, post, extra);
-        if (inThread && target.threadId !== void 0) {
-          try {
-            await store.recordSent(target.chatId, last, target.threadId);
-          } catch {
-            o.log.warn("telegram: could not record a sent message's thread", {
-              chatId: target.chatId,
-              messageId: last
-            });
-          }
-        }
+        await record(last);
       }
       return { messageId: `${target.chatId}:${last}` };
     },
     async update({ config, messageId, message, locale, signal }) {
       const { call, botId } = apiFor(config, signal);
       const { chatId, messageId: id } = parseMessageId(messageId);
+      const rich = richOf(message);
+      if (rich !== void 0) {
+        try {
+          await call("editMessageText", {
+            chat_id: chatId,
+            message_id: id,
+            rich_message: { html: rich }
+          });
+          return;
+        } catch (e) {
+          if (notModified(e)) return;
+          if (!richRefused(e)) throw toChannelSendError(e);
+          warnRichFallback(e, "editMessageText");
+        }
+      }
       const posts = await render(message, locale, botId);
       if (posts.length > 1) throw tooLarge();
       const post = posts[0];
@@ -1330,9 +1449,7 @@ function createTelegramChannel(o) {
           })
         );
       } catch (e) {
-        if (e instanceof TelegramApiError && /message is not modified/i.test(e.description ?? "")) {
-          return;
-        }
+        if (notModified(e)) return;
         throw toChannelSendError(e);
       }
     }
@@ -1342,7 +1459,7 @@ function createTelegramChannel(o) {
 // src/index.ts
 var index_default = defineExtension({
   name: "telegram",
-  version: "0.1.0-rc.5",
+  version: "0.1.0-rc.7",
   sdk: "^0.1.0-rc.4",
   provides: [CHANNEL_EXTENSION_POINT],
   permissions: { network: ["api.telegram.org"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-telegram",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.7",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Telegram (channel@1 bot over the Bot API: long polling or webhook, inline keyboard cards)",