polygram 0.17.11 → 0.18.0

package/lib/session-key.js

@@ -107,26 +107,17 @@ function getTopicConfig(chatConfig, threadId) {
 }
 
 /**
- * Resolve the config object a per-chat/topic setting (model/effort) should be
- * WRITTEN to, given where the command/card was used. When in a topic, return
- * (creating if needed) that topic's override entry — so a /model in the Music
- * topic targets Music alone and matches what the per-topic card displays,
- * instead of leaking to the chat root and every other topic that inherits it
- * (the 2026-06-12 "/model in Music does nothing" bug). At the chat level
- * (no thread), the writable scope is the chat config itself.
+ * Resolve the config object a per-chat/topic setting should be written to.
+ * Process-level settings use topic scope only for isolated sessions. A live
+ * delivery setting can opt into topic scope even when sessions are shared.
  *
  * @returns {{ scope: object, threadId: (string|null) }}
  */
-function getConfigWriteScope(chatConfig, threadId) {
+function getConfigWriteScope(chatConfig, threadId, { allowNonIsolatedTopic = false } = {}) {
   const tid = (threadId == null || threadId === '') ? null : String(threadId);
-  // Mirror getSessionKey's isolation rule: a per-topic override only takes
-  // effect when isolateTopics === true (otherwise every topic shares the
-  // chatId-keyed session and topics[tid].model is silently ignored — the
-  // 2026-06-12 review found the topic-scope fix re-broke /model on the DEFAULT
-  // non-isolated chats and made the card lie). So write the topic scope ONLY
-  // when isolated; otherwise write the chat root (the session that actually
-  // runs), and report threadId:null so the audit row reflects chat-level reach.
-  if (tid && chatConfig?.isolateTopics === true) {
+  // Process-scoped settings follow session isolation. Live delivery settings
+  // may explicitly keep topic scope because they are resolved per message.
+  if (tid && (chatConfig?.isolateTopics === true || allowNonIsolatedTopic)) {
     chatConfig.topics = chatConfig.topics || {};
     // A topic can be stored in the legacy / hand-edited form where the entry
     // is the bare name string (topics["329"] = "Advertising") rather than the

package/lib/telegram/api.js

@@ -100,9 +100,14 @@ const METHODS_WITHOUT_MSG = new Set([
 // Derive the row's `text` column. sendSticker has no text/caption, so we
 // synthesize `[sticker:<name>]` (or file_id as fallback) — without this the
 // transcript shows an empty outbound that's impossible to interpret later.
+// Rich edits carry source Markdown in meta.richSourceText because the API
+// payload has `rich_message` instead of `text`. Edits are excluded from
+// transcript persistence by METHODS_WITHOUT_MSG, but deriving meaningful
+// text here keeps the helper correct for any tracked rich-message caller.
 function deriveOutboundText(method, params, meta) {
   if (params.text) return params.text;
   if (params.caption) return params.caption;
+  if (params.rich_message) return meta.richSourceText || '[rich message]';
   if (method === 'sendSticker') {
     const label = meta.stickerName || params.sticker || 'unknown';
     return `[sticker:${label}]`;
@@ -153,11 +158,17 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   // as a user-facing "Hit a snag" — confusing because the bot didn't
   // really fail. Throw a typed error before the API call so callers
   // can detect + skip silently if appropriate.
-  if (method === 'sendMessage' || method === 'editMessageText') {
+  // A rich edit carries `rich_message` instead of `text`, so validate
+  // its block collection rather than applying the plain-text guard.
+  if (method === 'sendMessage' || (method === 'editMessageText' && params.rich_message == null)) {
     const t = params.text;
     if (typeof t !== 'string' || t.length === 0) {
       throw new Error(`telegram ${method}: text is empty`);
     }
+  } else if (method === 'editMessageText' && params.rich_message != null) {
+    if (!Array.isArray(params.rich_message.blocks) || params.rich_message.blocks.length === 0) {
+      throw new Error(`telegram ${method}: rich_message.blocks is empty`);
+    }
   }
   if (method === 'sendPhoto' || method === 'sendVideo'
       || method === 'sendAudio' || method === 'sendDocument' || method === 'sendAnimation') {

package/lib/telegram/chunk.js

@@ -124,6 +124,20 @@ function resolveChunkEarlyReturn(text, limit) {
   return undefined;
 }
 
+// A hard cut at a fixed UTF-16 offset can land between the two code units
+// of a surrogate pair (astral chars: emoji, rare CJK, math symbols) — the
+// pair then renders as U+FFFD on both sides of the boundary. Back the cut
+// off one unit when it would split a pair. Never returns 0 (a degenerate
+// limit of 1 keeps the raw cut rather than looping forever on an empty
+// chunk).
+function surrogateSafeCut(text, idx) {
+  if (idx > 1 && idx < text.length) {
+    const c = text.charCodeAt(idx - 1);
+    if (c >= 0xD800 && c <= 0xDBFF) return idx - 1;
+  }
+  return idx;
+}
+
 // Generic break-resolver loop shared with markdown variant. The resolver
 // receives a `window` (text.slice(0, limit)) and returns where to break.
 // Negative / out-of-range break indices fall back to hard-cut at limit.
@@ -136,7 +150,7 @@ function chunkTextByBreakResolver(text, limit, resolveBreakIndex) {
     const candidateBreak = resolveBreakIndex(remaining.slice(0, limit));
     const breakIdx = Number.isFinite(candidateBreak) && candidateBreak > 0 && candidateBreak <= limit
       ? candidateBreak
-      : limit;
+      : surrogateSafeCut(remaining, limit);
     const chunk = remaining.slice(0, breakIdx).trimEnd();
     if (chunk.length > 0) chunks.push(chunk);
     // If we broke on a separator (whitespace), consume it — don't carry it
@@ -202,7 +216,7 @@ function chunkMarkdownText(text, limit) {
   while (remaining.length > limit) {
     const spans = parseFenceSpans(remaining);
     const softBreak = pickSafeBreakIndex(remaining.slice(0, limit), spans);
-    let breakIdx = softBreak > 0 ? softBreak : limit;
+    let breakIdx = softBreak > 0 ? softBreak : surrogateSafeCut(remaining, limit);
     const initialFence = isSafeFenceBreak(spans, breakIdx) ? undefined : findFenceSpanAt(spans, breakIdx);
     let fenceToSplit = initialFence;
     if (initialFence) {
@@ -215,7 +229,7 @@ function chunkMarkdownText(text, limit) {
         // Caller will see a malformed chunk, but that's a degenerate
         // input case (limit smaller than the close marker).
         fenceToSplit = undefined;
-        breakIdx = limit;
+        breakIdx = surrogateSafeCut(remaining, limit);
       } else {
         // Look for a newline inside the fence body that's late enough
         // to make progress (past the open line + at least one body line)
@@ -243,11 +257,11 @@ function chunkMarkdownText(text, limit) {
             // No safe in-fence newline found and no room to add one —
             // give up on splitting this fence; hard-cut at limit.
             fenceToSplit = undefined;
-            breakIdx = limit;
+            breakIdx = surrogateSafeCut(remaining, limit);
           } else {
             // Force the break; chunker will append a synthetic newline
             // before the close line.
-            breakIdx = Math.max(minProgressIdx, maxIdxIfNeedNewline);
+            breakIdx = surrogateSafeCut(remaining, Math.max(minProgressIdx, maxIdxIfNeedNewline));
           }
         }
       }
@@ -294,7 +308,7 @@ function chunkMarkdownText(text, limit) {
       // limit (cheap heuristic — much better than mid-word).
       const window = rest.slice(0, limit);
       const lastNl = window.lastIndexOf('\n', limit - 1);
-      const cutAt = lastNl > limit - 200 ? lastNl + 1 : limit;
+      const cutAt = lastNl > limit - 200 ? lastNl + 1 : surrogateSafeCut(rest, limit);
       safe.push(rest.slice(0, cutAt));
       rest = rest.slice(cutAt);
     }

package/lib/telegram/display-hint.js

@@ -27,11 +27,10 @@
 
 const TELEGRAM_TABLE_WIDTH_BUDGET = 40;
 
-const POLYGRAM_DISPLAY_HINT = [
-  '## Telegram display rules',
-  '',
-  'Your replies render in the Telegram client. Phone is the design target.',
-  '',
+// Plain-mode guidance avoids structures that Telegram's HTML rendering
+// cannot display well. The prompt and delivery capability must agree so
+// the agent is not encouraged to author unsupported structures.
+const TABLES_AND_HEADERS_SECTION_PLAIN = [
   '### Tables — HARD RULE',
   '',
   `Before emitting any markdown table, count the longest row in characters (including pipes \`|\`, padding, and separator dashes). If that row is longer than ${TELEGRAM_TABLE_WIDTH_BUDGET}, you MUST NOT emit a table. Use row blocks instead.`,
@@ -57,19 +56,54 @@ const POLYGRAM_DISPLAY_HINT = [
   '- Headers `#`, `##`, `###` render as plain text — use **bold** for emphasis.',
   '- Horizontal rules render as a thin divider line.',
   '- Long replies stream in chunks; prefer concise structure over walls of text.',
+].join('\n');
+
+// Rich-mode guidance is limited to the constructs detected by
+// needsRichRendering so ordinary prose stays on the compact plain path.
+const TABLES_AND_HEADERS_SECTION_RICH = [
+  '### Rich formatting is available in this chat',
+  '',
+  'This chat has rich-text rendering enabled. Real Telegram markdown tables, headings (`#`/`##`/etc.), task lists, and collapsible `<details>` blocks now render as an actual structured message, not flattened text — use them when they make an answer clearer or easier to scan (a comparison, a set of steps, a key/value summary, a checklist tracking progress). No character-width budget applies to tables here; write a normal markdown table.',
+  '',
+  '**Task lists for progress:** `- [ ] pending step` / `- [x] done step` renders as a real checkbox list — the natural way to show multi-step progress as it happens.',
   '',
-  '### NEVER emit shell-context canned strings — HARD RULE',
+  '**Collapsible detail:** wrap verbose logs/diffs/output you want available but not front-and-center in `<details><summary>Label</summary>...</details>`.',
   '',
-  'You are running as a Telegram chat bot, NOT as a script being piped into a shell. Certain phrases are CLI-context boilerplate from the underlying environment and MUST NEVER appear in a reply, because the user sees them as a literal message from you and they look like a system error:',
+  'Not every reply needs this — plain prose is still right for a normal conversational answer. Reach for structure when the CONTENT is structured, not by default.',
   '',
-  '- `No response requested.`',
-  '- `No response needed.`',
-  '- `Continuing...` as a standalone reply',
-  '- Any other shell-prompt-style filler that acknowledges silence',
+  '### Other Telegram quirks',
   '',
-  'If a user message is short, ambiguous, or feels like a no-op acknowledgement (e.g. `okay`, `ok`, `yes`, `got it`, `thanks`), reply with a brief substantive line — acknowledge what you understood and what (if anything) you will do next. If you genuinely have nothing useful to say, ask ONE specific clarifying question. NEVER emit a placeholder or a shell-style canned string — the chat surface has no silent-no-op state. Every reply must be intentional content.',
+  '- Horizontal rules render as a thin divider line.',
+  '- Long replies stream in chunks; prefer concise structure over walls of text.',
 ].join('\n');
 
+function buildPolygramDisplayHint(richText = false) {
+  const tablesSection = richText ? TABLES_AND_HEADERS_SECTION_RICH : TABLES_AND_HEADERS_SECTION_PLAIN;
+  return [
+    '## Telegram display rules',
+    '',
+    'Your replies render in the Telegram client. Phone is the design target.',
+    '',
+    tablesSection,
+    '',
+    '### NEVER emit shell-context canned strings — HARD RULE',
+    '',
+    'You are running as a Telegram chat bot, NOT as a script being piped into a shell. Certain phrases are CLI-context boilerplate from the underlying environment and MUST NEVER appear in a reply, because the user sees them as a literal message from you and they look like a system error:',
+    '',
+    '- `No response requested.`',
+    '- `No response needed.`',
+    '- `Continuing...` as a standalone reply',
+    '- Any other shell-prompt-style filler that acknowledges silence',
+    '',
+    'If a user message is short, ambiguous, or feels like a no-op acknowledgement (e.g. `okay`, `ok`, `yes`, `got it`, `thanks`), reply with a brief substantive line — acknowledge what you understood and what (if anything) you will do next. If you genuinely have nothing useful to say, ask ONE specific clarifying question. NEVER emit a placeholder or a shell-style canned string — the chat surface has no silent-no-op state. Every reply must be intentional content.',
+  ].join('\n');
+}
+
+// Pre-computed default (richText:false) — kept as a named export for
+// backward compatibility with any caller/test that imported the old
+// constant directly.
+const POLYGRAM_DISPLAY_HINT = buildPolygramDisplayHint(false);
+
 /**
  * Append the polygram display hint to an existing systemPrompt option,
  * preserving the original shape (string / preset object / undefined).
@@ -111,5 +145,6 @@ function appendDisplayHint(systemPromptOpt, hint = POLYGRAM_DISPLAY_HINT) {
 module.exports = {
   POLYGRAM_DISPLAY_HINT,
   TELEGRAM_TABLE_WIDTH_BUDGET,
+  buildPolygramDisplayHint,
   appendDisplayHint,
 };

package/lib/telegram/format.js

@@ -108,6 +108,12 @@ function buildRenderer() {
     image({ href, text }) {
       return `<a href="${escapeHtmlAttr(href)}">${escapeHtml(text || href)}</a>`;
     },
+    // Task-list items (marked type:'checkbox', gfm) render as a literal
+    // ☐/☑ glyph. Telegram's parse_mode=HTML has no support for <input> —
+    // marked's default checkbox() renderer emits one, which Telegram
+    // rejects outright (400: Unsupported start tag "input"), degrading
+    // the WHOLE message to raw markdown via api.js's HTML→plain fallback.
+    checkbox({ checked }) { return checked ? '☑ ' : '☐ '; },
     list({ items, ordered, start }) {
       const depth = listDepth;
       listDepth += 1;
@@ -115,7 +121,10 @@ function buildRenderer() {
       const bullet = bulletFor(depth);
       try {
         const lines = items.map((item, i) => {
-          const marker = ordered ? `${(start || 1) + i}. ` : `${bullet} `;
+          // Task items carry their own checkbox() glyph as the visual
+          // marker (rendered inline below) — an extra bullet in front
+          // would double up ("• ☐ x").
+          const marker = item.task ? '' : (ordered ? `${(start || 1) + i}. ` : `${bullet} `);
           const { inline, blocks } = splitItemTokens(item.tokens);
           const leader = this.parser.parseInline(inline).trim();
           let line = `${indent}${marker}${leader}`;

package/lib/telegram/process-agent-reply.js

@@ -51,7 +51,9 @@
  * @param {object} opts.bot                  — grammy bot instance
  * @param {Function} opts.tg                 — (bot, method, params, meta) → Promise<res>
  * @param {string|number} opts.chatId
- * @param {?number} opts.threadId            — Telegram message_thread_id (or null)
+ * @param {?(number|string)} opts.threadId   — Telegram message_thread_id (or null).
+ *   Treated as opaque, deliver.js-style: the cli backend passes a STRING, so an
+ *   integer-only guard would drop the id and send stickers to the General topic.
  * @param {?number} opts.replyToMessageId    — inbound msg_id this reply targets; null for unsolicited
  * @param {boolean} [opts.applyReactions]    — apply [react:EMOJI] tags to replyToMessageId. False for
  *                                              unsolicited (autonomous-wakeup) where there IS no target;
@@ -173,7 +175,7 @@ async function processAndDeliverAgentText({
       await tg(bot, 'sendSticker', {
         chat_id: chatId,
         sticker: parsed.sticker,
-        ...(Number.isInteger(threadId) && { message_thread_id: threadId }),
+        ...(threadId != null && { message_thread_id: threadId }),
       }, {
         ...meta,
         source: `${source}-sticker`,
@@ -192,7 +194,7 @@ async function processAndDeliverAgentText({
       await tg(bot, 'sendSticker', {
         chat_id: chatId,
         sticker: s.fileId,
-        ...(Number.isInteger(threadId) && { message_thread_id: threadId }),
+        ...(threadId != null && { message_thread_id: threadId }),
       }, {
         ...meta,
         source: `${source}-inline-sticker`,

package/lib/telegram/rich-edit.js

@@ -0,0 +1,94 @@
+/**
+ * Rich-message edit-with-fallback. Capability and content errors preserve
+ * the reply through a plain edit; transient errors remain visible to the
+ * streamer's retry/finalization logic.
+ */
+
+'use strict';
+
+/**
+ * @param {object} deps
+ * @param {(bot, method, params, meta) => Promise<*>} deps.tg
+ * @param {string} deps.botName
+ * @param {(kind: string, detail: object) => void} deps.logEvent
+ * @param {(s: string) => string} deps.redactBotToken
+ * @param {(err) => boolean} deps.isRichCapabilityError
+ * @param {(err) => boolean} deps.isRichContentError
+ * @param {() => boolean} deps.getRichKnownUnsupported
+ * @param {() => void} deps.setRichKnownUnsupported — marks the latch tripped
+ * @param {() => (string|null)} [deps.getApiRoot] — for the latch-trip log line only
+ * @param {(url: string) => string} [deps.stripUrlCreds] — strips basic-auth
+ *   userinfo from apiRoot before logging
+ * @returns {(args: {bot, chatId: string, threadId: (string|null), messageId: number, blocks: Array, sourceText: string}) => Promise<{result: *, wentRich: boolean}>}
+ */
+function createRichEditor({
+  tg,
+  botName,
+  logEvent,
+  redactBotToken,
+  isRichCapabilityError,
+  isRichContentError,
+  getRichKnownUnsupported = () => false,
+  setRichKnownUnsupported = () => {},
+  getApiRoot = () => null,
+  stripUrlCreds = (s) => s,
+} = {}) {
+  return async function richEditMessageText({ bot, chatId, threadId = null, messageId, blocks, sourceText }) {
+    if (getRichKnownUnsupported()) {
+      const res = await tg(bot, 'editMessageText', {
+        chat_id: chatId, message_id: messageId, text: sourceText,
+      }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
+      return { result: res, wentRich: false };
+    }
+
+    try {
+      const res = await tg(bot, 'editMessageText', {
+        chat_id: chatId,
+        message_id: messageId,
+        rich_message: { blocks },
+      }, { source: 'bot-reply-stream-edit-rich', botName, richSourceText: sourceText });
+      // Record successful rich deliveries without storing message content.
+      logEvent('rich-message-sent', {
+        chat_id: chatId, thread_id: threadId, bot: botName,
+        streaming: true, block_count: blocks.length,
+        char_count: sourceText?.length ?? null,
+      });
+      // The streamer commits rich state only when this marker is true.
+      return { result: res, wentRich: true };
+    } catch (err) {
+      if (isRichCapabilityError(err)) {
+        setRichKnownUnsupported();
+        logEvent('rich-capability-latched', {
+          chat_id: chatId, bot: botName,
+          api_root: stripUrlCreds(getApiRoot() || 'cloud'),
+          error: redactBotToken(err.message)?.slice(0, 200),
+        });
+      } else if (isRichContentError(err)) {
+        logEvent('rich-content-fallback', {
+          chat_id: chatId, bot: botName,
+          error: redactBotToken(err.message)?.slice(0, 200),
+        });
+      } else {
+        // Transient (5xx/timeout/etc) — not ours to reclassify as a
+        // fallback; rethrow so the caller's existing retry/error
+        // handling deals with it exactly as a plain-path edit failure
+        // would (streamer.js's flush()/finalize() catch + log + move on).
+        logEvent('telegram-edit-failed', {
+          chat_id: chatId, msg_id: messageId,
+          // Network errors can include the request URL and bot token.
+          api_error: redactBotToken(err.message)?.slice(0, 200),
+          bot: botName,
+        });
+        throw err;
+      }
+      // Preserve the same authored content and tell the streamer that the
+      // accepted payload is plain, so its delivery trackers stay accurate.
+      const fallbackRes = await tg(bot, 'editMessageText', {
+        chat_id: chatId, message_id: messageId, text: sourceText,
+      }, { source: 'bot-reply-stream-edit-rich-fallback', botName });
+      return { result: fallbackRes, wentRich: false };
+    }
+  };
+}
+
+module.exports = { createRichEditor };