telegram-agent-kit 0.3.0 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/npm/l/telegram-agent-kit.svg)](./LICENSE)
 [![types](https://img.shields.io/npm/types/telegram-agent-kit.svg)](https://www.typescriptlang.org/)
 
-ESM-only. Runs on **Node 18+, Bun, Deno, and the browser** (the formatting core).
+ESM-only. Runs on **Node 20+, Bun, Deno, and the browser** (the formatting core).
 
 ---
 
@@ -111,6 +111,12 @@ async function call(method: string, body: unknown, signal?: AbortSignal) {
 > transport. If your bot has no rich endpoint, point them at plain `sendMessage`
 > and set `rich: false` — the kit then renders via HTML only.
 
+> **Note:** `rich: true` means *rich when it buys something*, not *rich always*.
+> Drafts and final messages go out rich only for text that needs the rich
+> renderer — today, a GFM table (`needsRich`); everything else is classic HTML, so
+> ordinary replies keep the client's normal message font. `rich: false` is still
+> the kill-switch: HTML only, always.
+
 ## How it works
 
 The kit is three layers plus one optional adapter. The dependency direction is
@@ -151,8 +157,9 @@ You implement these; the kit drives them.
 | `Checkpointer` | `{ snapshot(threadId), rollback(threadId, id) }`                       | Per-thread snapshot/rollback for clean recovery on a failed turn. |
 | `ThreadStore`  | `{ resolve(chatKey, now), touch(chatKey, now) }`                      | Maps `{ chatId, agentId }` to a thread id (so two bots over one chat id don't collide). |
 
-A `RenderEvent` is one of `token`, `tool_start`, `tool_end`, or `error`. The kit
-appends `token` text to the live draft and treats an `error` event as a rollback.
+A `RenderEvent` is either `token` or `error`: `token` text is appended to the live draft,
+an `error` rolls the turn back, logs the message, and — if you pass `errorNotice` — tells
+the user in the chat instead of going silent.
 
 ## API reference
 
@@ -165,6 +172,8 @@ appends `token` text to the live draft and treats an `error` event as a rollback
 - `chunkText(text)` / `safeSlice(text, max)` / `chunkRich(md)` — surrogate-safe splitting
   (classic limit 4096, rich limit 32768).
 - `repairRichTables(md)` · `neutralizeRichMedia(md)` · `extractTrailingCover(reply)` — rich helpers.
+- `needsRich(md)` — does this text need the rich renderer (today: does it contain a GFM
+  table, outside code)? The gate behind `rich: true`; everything else goes classic.
 
 **Draft engine**
 
@@ -177,6 +186,8 @@ appends `token` text to the live draft and treats an `error` event as a rollback
 - `runTelegramTurn(opts)` — orchestrate one turn. Never throws out; every failure is caught and logged.
   Accepts an optional `configurable` bag forwarded to your `AgentStream` as `context.configurable`,
   for passing per-turn data (e.g. `pendingImages`) to the agent without widening the core input type.
+  Pass `errorNotice` (plain text, your language) to have a failed turn say so in the chat —
+  omit it and the user just sees the draft stop, which reads as being ignored.
 - `sendReply(client, chatId, reply, opts, signal?)` / `sendText(...)` — the send path on its own.
 - Types: `BotClient`, `AgentStream`, `Checkpointer`, `ThreadStore`, `RenderEvent`, `ChatKey`, `Logger`.
 

package/dist/index.d.ts

@@ -5,7 +5,17 @@ type SendOpts = {
     rich: boolean;
     log: Logger;
 };
-/** Active reply path — rich when opts.rich, else classic. */
+/** Active reply path — rich when `opts.rich`, but `sendRich` sends each chunk
+ *  rich only if it actually needs the rich renderer (`needsRich`), else classic.
+ *  `rich: true` means "rich when it buys something", not "rich always": the rich
+ *  renderer sizes body text its own way with no Bot API field to override it, so
+ *  pushing ordinary prose through it just makes every reply look unlike a normal
+ *  message for nothing.
+ *
+ *  Media is neutralized HERE, before the split, so it happens on BOTH paths:
+ *  classic has no image renderer either (`mdToTelegramHtml` leaves `![a](u)`
+ *  verbatim), so prose that routes to classic would otherwise show raw image
+ *  markdown. Idempotent, so `sendReply`'s photo-fallback re-entry is harmless. */
 declare function sendText(client: BotClient, chatId: number, text: string, opts: SendOpts, signal?: AbortSignal): Promise<void>;
 /** Final reply send for a completed turn (client.ts sendReply). */
 declare function sendReply(client: BotClient, chatId: number, reply: string, opts: SendOpts, signal?: AbortSignal): Promise<void>;
@@ -78,6 +88,10 @@ type RunTelegramTurnOpts = {
     };
     draftConstants?: Partial<DraftConstants>;
     configurable?: Record<string, unknown>;
+    /** Plain-text line sent to the chat when the stream errors out (model chain
+     *  exhausted, graph threw). Without it the turn returns silently and the user
+     *  sees only a draft that stops moving — indistinguishable from being ignored. */
+    errorNotice?: string;
 };
 declare function runTelegramTurn(opts: RunTelegramTurnOpts): Promise<void>;
 
@@ -137,6 +151,27 @@ declare function mdToTelegramHtml(md: string, opts?: MdToHtmlOpts): string;
  *  non-table prose (mid-body or trailing) is not eligible either (else the orphan
  *  glues onto non-table content). Pure and total. */
 declare function repairRichTables(md: string): string;
+/** Does `md` carry structure only the rich renderer can draw? Today that means
+ *  one thing: a GFM table. Everything else a reply contains — bold, italic,
+ *  code, links, quotes, lists — classic HTML renders fine, and classic keeps the
+ *  client's normal message font, while the rich renderer sizes body text its own
+ *  way with no Bot API knob to override it (the only size field in the whole
+ *  rich schema is `RichBlockSectionHeading.size`). So routing prose to classic is
+ *  the only way to keep ordinary replies looking like ordinary messages.
+ *
+ *  Scanned per LINE, not per blank-line block: a table needs no blank line above
+ *  it, and models routinely put one directly under a lead-in line, a heading, a
+ *  list, or a closing fence. A block-first-line check misses every one of those
+ *  (and every table after `\n\n\n` or in CRLF output, where the block split
+ *  lands wrong) — and a missed table is the one case where classic is WORSE:
+ *  it has no table renderer, so the reply goes out as literal pipes.
+ *
+ *  Code regions are skipped, using the SAME `advanceCodeRegion` walk as
+ *  `repairRichTables`: a table inside a fence or an HTML `<pre>`/`<code>` region
+ *  is a literal example, and classic renders it as code perfectly well — it is
+ *  not a reason to go rich. Only a header+delimiter pair counts; stray pipe rows
+ *  print as literal pipes either way. Pure and total. */
+declare function needsRich(md: string): boolean;
 /** Extract a standalone cover image that is the LAST non-empty line of `md`:
  *  the whole line is a single `![alt](http(s)://…)` token. Returns the URL plus
  *  the body (the reply with that line removed, trailing whitespace trimmed).
@@ -164,4 +199,4 @@ declare function extractTrailingCover(md: string): {
  *  total. */
 declare function neutralizeRichMedia(md: string): string;
 
-export { AgentStream, BotClient, ChatKey, Checkpointer, DEFAULT_DRAFT_CONSTANTS, type DraftConstants, type DraftStreamer, type DraftStreamerDeps, Logger, type MdToHtmlOpts, type RunTelegramTurnOpts, TelegramApiError, ThreadStore, type TurnContext, chunkRich, chunkText, createDraftStreamer, extractTrailingCover, isBadRequest, mdToTelegramHtml, neutralizeRichMedia, repairRichTables, runTelegramTurn, safeSlice, sendReply, sendText };
+export { AgentStream, BotClient, ChatKey, Checkpointer, DEFAULT_DRAFT_CONSTANTS, type DraftConstants, type DraftStreamer, type DraftStreamerDeps, Logger, type MdToHtmlOpts, type RunTelegramTurnOpts, TelegramApiError, ThreadStore, type TurnContext, chunkRich, chunkText, createDraftStreamer, extractTrailingCover, isBadRequest, mdToTelegramHtml, needsRich, neutralizeRichMedia, repairRichTables, runTelegramTurn, safeSlice, sendReply, sendText };

package/dist/index.js

@@ -365,6 +365,16 @@ ${block}`;
   }
   return out.join("\n\n");
 }
+function needsRich(md) {
+  if (!md.includes("|")) return false;
+  const lines = md.split("\n");
+  let region = null;
+  for (let i = 0; i + 1 < lines.length; i++) {
+    if (region === null && isTableBlock(lines.slice(i, i + 2))) return true;
+    region = advanceCodeRegion(region, [lines[i] ?? ""]);
+  }
+  return false;
+}
 var TRAILING_COVER_RE = /^!\[[^\]]*\]\(\s*(https?:\/\/[^\s)]+)[^)]*\)$/;
 function insideCodeRegion(lines, idx) {
   return advanceCodeRegion(null, lines.slice(0, idx)) !== null;
@@ -461,9 +471,11 @@ async function sendClassic(client, chatId, text, signal) {
   }
 }
 async function sendRich(client, chatId, markdown, log, signal) {
-  for (const piece of chunkRich(
-    neutralizeRichMedia(repairRichTables(markdown))
-  )) {
+  for (const piece of chunkRich(repairRichTables(markdown))) {
+    if (!needsRich(piece)) {
+      await sendClassic(client, chatId, piece, signal);
+      continue;
+    }
     try {
       await client.sendRichMessage({ chatId, markdown: piece }, signal);
     } catch (err) {
@@ -479,8 +491,9 @@ async function sendRich(client, chatId, markdown, log, signal) {
   }
 }
 async function sendText(client, chatId, text, opts, signal) {
-  if (opts.rich) await sendRich(client, chatId, text, opts.log, signal);
-  else await sendClassic(client, chatId, text, signal);
+  const md = neutralizeRichMedia(text);
+  if (opts.rich) await sendRich(client, chatId, md, opts.log, signal);
+  else await sendClassic(client, chatId, md, signal);
 }
 async function sendCover(client, chatId, url, caption, signal) {
   if (caption === void 0 || caption === "") {
@@ -519,7 +532,7 @@ async function sendReply(client, chatId, reply, opts, signal) {
     else await sendCover(client, chatId, cover.url, cover.body, signal);
   } catch (err) {
     if (!isBadRequest(err)) throw err;
-    await sendText(client, chatId, neutralizeRichMedia(reply), opts, signal);
+    await sendText(client, chatId, reply, opts, signal);
     return;
   }
   if (longBody) await sendText(client, chatId, cover.body, opts, signal);
@@ -574,7 +587,7 @@ function createDraftStreamer(deps) {
     const controller = new AbortController();
     inFlightController = controller;
     lastAttemptAt = t;
-    const usingRich = richMode;
+    const usingRich = richMode && needsRich(text);
     const op = usingRich ? client.sendRichMessageDraft(
       { chatId, draftId, markdown: text },
       controller.signal
@@ -724,7 +737,7 @@ async function runTelegramTurn(opts) {
     });
     draft.start();
     let reply = "";
-    let errored = false;
+    let errorMessage;
     for await (const ev of opts.agentStream(
       { messages: [{ role: "user", content: opts.userText }] },
       { threadId, signal: opts.signal, configurable: opts.configurable }
@@ -732,15 +745,27 @@ async function runTelegramTurn(opts) {
       if (ev.type === "token") {
         reply += ev.text;
         draft.push(reply);
-      } else if (ev.type === "error") errored = true;
+      } else if (ev.type === "error") errorMessage = ev.message;
     }
-    if (errored) {
+    if (errorMessage !== void 0) {
+      log.error("telegram turn errored", {
+        chatId: opts.chatKey.chatId,
+        err: errorMessage
+      });
       draftTornDown = true;
       await draft.abort().catch(() => {
       });
       await opts.checkpointer.rollback(rollback.threadId, rollback.checkpointId).catch(
         (e) => log.error("telegram rollback failed", { err: String(e) })
       );
+      if (opts.errorNotice && !opts.signal?.aborted) {
+        await opts.client.sendMessage(
+          { chatId: opts.chatKey.chatId, text: opts.errorNotice },
+          opts.signal
+        ).catch(
+          (e) => log.error("telegram error notice failed", { err: String(e) })
+        );
+      }
       return;
     }
     draftTornDown = true;
@@ -790,6 +815,7 @@ export {
   extractTrailingCover,
   isBadRequest,
   mdToTelegramHtml,
+  needsRich,
   neutralizeRichMedia,
   repairRichTables,
   runTelegramTurn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-agent-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Render markdown to Telegram, stream agent replies into live drafts, and drive a snapshot/rollback turn-loop — runtime-agnostic.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "esm"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "files": [
     "dist"
@@ -65,10 +65,10 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.0",
     "@langchain/core": "^1.2.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.13.3",
     "deepagents": "^1.10.5",
     "tsup": "^8.3.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   }
 }