telegram-agent-kit 0.3.1 → 0.4.1

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
@@ -166,6 +172,8 @@ the user in the chat instead of going silent.
 - `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**
 
@@ -181,6 +189,7 @@ the user in the chat instead of going silent.
   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.
+  `opts` is `{ rich: boolean, log: Logger }`, with the same `rich` semantics as above.
 - Types: `BotClient`, `AgentStream`, `Checkpointer`, `ThreadStore`, `RenderEvent`, `ChatKey`, `Logger`.
 
 **Errors**
@@ -196,6 +205,10 @@ the user in the chat instead of going silent.
   `__pregel_*` LangGraph internal-execution key — are stripped so the kit retains full control over
   checkpoint routing and execution.
 - `streamAgent(agent, input, config, signal?)` — lower-level event stream if you need direct control.
+  Yields tokens from the **root** agent only: a delegated agent (a `subagents` entry, or the built-in
+  `task` tool) runs its own model node and LangChain replays its events into the parent stream, so
+  without this its monologue would interleave with the reply. Naming the root agent does not change
+  what streams.
 
 > `@langchain/core` and `deepagents` are **type-only, optional** peers. The built
 > `/deepagents` bundle contains no runtime import of either, so the core stays

package/dist/deepagents/index.js

@@ -18,6 +18,7 @@ async function* streamAgent(agent, input, config, signal) {
     for await (const ev of iter) {
       if (ev.event === "on_chat_model_stream") {
         if (ev.metadata?.langgraph_node !== "model_request") continue;
+        if (ev.metadata?.checkpoint_ns?.includes("|")) continue;
         const text = extractText(ev.data?.chunk?.content);
         if (text) yield { type: "token", text };
       }

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>;
@@ -141,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).
@@ -168,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
@@ -802,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.1",
+  "version": "0.4.1",
   "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"
   }
 }