@llblab/pi-telegram 0.17.3 → 0.17.5

package/BACKLOG.md

@@ -5,6 +5,11 @@
   - Done when: each confirmed sequence has a conservative normalization or safe-degradation rule covered by tests.
   - Done when: unconfirmed speculative rewrites remain out of the delivery path.
 
+- [ ] Evaluate Rich Draft placeholder heartbeat for long unsafe preview gaps.
+  - Done when: live/client evidence confirms whether `RichBlockThinking` / `<tg-thinking>` prevents Telegram draft expiry while assistant output is still streaming but no safe Markdown prefix is available.
+  - Done when: the behavior is compared against the existing typing keepalive lifecycle so Telegram chat action and Rich Draft placeholder states do not fight each other.
+  - Done when: abort/clear behavior is tested so placeholder drafts do not create the transient confusing block observed after abort.
+
 - [ ] Track a public Pi session-replacement hook before adding Telegram `/new`.
   - [ ] Wait for a safe public Pi API.
     - Done when: Pi exposes an API that invokes the same session-replacement path as terminal `/new`.

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.17.5: Screenshot Refresh
+
+- `[Docs]` Refreshed the package screenshot.
+
+## 0.17.4: Native Rich Markdown Splitter Hotfix
+
+- `[Rich Markdown]` Rewrap oversized fenced code, display-math, and fully wrapped inline-formatting blocks when splitting native Rich Markdown at Telegram transport limits. Impact: very long structured Markdown blocks no longer produce invalid partial Rich Markdown chunks, so final assistant replies can stay native without losing long code/math/formatted output.
+- `[Tests]` Added regressions for oversized fenced code, display math, and inline formatting split behavior. Impact: future native splitter changes must preserve structurally valid chunks beyond Telegram's single-message size limit.
+
 ## 0.17.3: Native Draft Preview Hotfix
 
 - `[Rich Markdown]` Normalize multiline display-math blocks written as `$$` / content / `$$` into Telegram-supported `math` code fences before native Rich Markdown delivery, while preserving literal delimiters inside code fences. Impact: assistant replies following the Telegram prompt guidance for block formulas no longer risk making the whole Rich Markdown message render as raw Markdown.

package/docs/architecture.md

@@ -198,7 +198,7 @@ Assistant delivery guarantees:
 - Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML.
 - Before native Rich Markdown delivery, the bridge normalizes known Bot-API-fragile source forms without changing visible meaning, including space-after-marker blockquotes and dollar-prefixed ticker atoms that Telegram may otherwise treat as unterminated math.
 - Quoted rich replies use Telegram `rich_message` blocks as the prompt-context source when available, so `[reply]` context receives rendered plain text instead of raw `InputRichMessage.markdown` fallback text.
-- Long native Markdown replies are split only at Telegram Rich Message transport limits.
+- Long native Markdown replies are split only at Telegram Rich Message transport limits; oversized fenced code, display-math, and fully wrapped inline-formatting blocks are rewrapped per chunk so persisted Rich Markdown chunks remain structurally valid.
 - Streaming previews pass structurally closed assistant Markdown prefixes through to `sendRichMessageDraft` with ownership checks, voice suppression, and serialized flushes. Unclosed inline spans, links, fenced code, comments, and display-math blocks are held back until a safe boundary exists. Draft failures are recorded and the failing frame is skipped instead of degrading to raw plain-message previews, because partial Markdown can be invalid while the final message remains valid.
 - Preview flushes are serialized so older edits cannot race newer drafts; final delivery waits for active draft flushes and does not perform a post-final draft-clear call.
 

package/docs/public-api.md

@@ -99,7 +99,7 @@ Hidden/default semantics are represented by absence:
 - Voice Reply `hidden`: no `voice.replyMode` key is persisted.
 - Time Injection `hidden`: no `time.injectionMode` key is persisted; if `time` becomes empty, the whole `time` object may be omitted.
 
-Assistant Markdown delivery is native: final replies are sent as `InputRichMessage.markdown` via `sendRichMessage`, and draft previews use `sendRichMessageDraft` when a structurally closed preview frame is available. Draft-frame failures are recorded and skipped rather than converted into raw plain preview messages, because partial Markdown can be temporarily invalid while the final answer remains valid. Guest replies use `InputRichMessageContent` in `answerGuestQuery` results. Bridge-owned UI surfaces such as menus, status, queue controls, commands, and sections keep explicit Telegram HTML/plain rendering by default because those texts are authored by the bridge or companion extensions for Telegram UI. Companion extension sections may explicitly request `"markdown"`, `"html"`, or `"plain"` per view. There is no `telegram.json` rendering toggle for assistant delivery. The bridge sets `skip_entity_detection: true` for assistant and guest Markdown so technical text such as `/commands`, hashtags, URLs, phone numbers, and card-like numbers does not gain unintended automatic entities; explicit Markdown links still belong in the Markdown source.
+Assistant Markdown delivery is native: final replies are sent as `InputRichMessage.markdown` via `sendRichMessage`, and draft previews use `sendRichMessageDraft` when a structurally closed preview frame is available. Draft-frame failures are recorded and skipped rather than converted into raw plain preview messages, because partial Markdown can be temporarily invalid while the final answer remains valid. Long native replies are split at Telegram Rich Message transport limits, with oversized fenced code, display-math, and fully wrapped inline-formatting blocks rewrapped per chunk so persisted chunks remain structurally valid. Guest replies use `InputRichMessageContent` in `answerGuestQuery` results. Bridge-owned UI surfaces such as menus, status, queue controls, commands, and sections keep explicit Telegram HTML/plain rendering by default because those texts are authored by the bridge or companion extensions for Telegram UI. Companion extension sections may explicitly request `"markdown"`, `"html"`, or `"plain"` per view. There is no `telegram.json` rendering toggle for assistant delivery. The bridge sets `skip_entity_detection: true` for assistant and guest Markdown so technical text such as `/commands`, hashtags, URLs, phone numbers, and card-like numbers does not gain unintended automatic entities; explicit Markdown links still belong in the Markdown source.
 
 Environment variables are stable only where documented in the README: bot-token bootstrap, proxy behavior, agent root, and inbound/outbound file size limits.
 

package/lib/replies.ts

@@ -456,6 +456,12 @@ function countTelegramNativeMarkdownBlocks(block: string): number {
 }
 
 function splitTelegramNativeMarkdownLongBlock(block: string): string[] {
+  return splitTelegramNativeMarkdownLongFenceBlock(block) ??
+    splitTelegramNativeMarkdownLongWrappedInlineBlock(block) ??
+    splitTelegramNativeMarkdownLongPlainBlock(block);
+}
+
+function splitTelegramNativeMarkdownLongPlainBlock(block: string): string[] {
   const chunks: string[] = [];
   let remaining = block;
   while (remaining.length > TELEGRAM_RICH_MESSAGE_MAX_CHARS) {
@@ -468,8 +474,70 @@ function splitTelegramNativeMarkdownLongBlock(block: string): string[] {
   return chunks;
 }
 
-function findTelegramNativeMarkdownSplitIndex(text: string): number {
-  const hardLimit = TELEGRAM_RICH_MESSAGE_MAX_CHARS;
+function splitTelegramNativeMarkdownLongFenceBlock(block: string): string[] | undefined {
+  const lines = block.split("\n");
+  const opening = lines[0] ?? "";
+  const closing = lines[lines.length - 1] ?? "";
+  const openingMatch = opening?.match(/^ {0,3}(`{3,}|~{3,})/);
+  if (!openingMatch || !closing || lines.length < 2) return undefined;
+  const markerText = openingMatch[1] ?? "```";
+  const marker = markerText[0] as "`" | "~";
+  if (!new RegExp(`^ {0,3}${marker}{${markerText.length},}\\s*$`).test(closing)) {
+    return undefined;
+  }
+  const maxContentLength = TELEGRAM_RICH_MESSAGE_MAX_CHARS -
+    opening.length -
+    closing.length -
+    2;
+  if (maxContentLength <= 0) return undefined;
+  const content = lines.slice(1, -1).join("\n");
+  return splitTelegramNativeMarkdownWrappedContent(
+    content,
+    maxContentLength,
+    (chunk) => `${opening}\n${chunk}${chunk.endsWith("\n") ? "" : "\n"}${closing}`,
+  );
+}
+
+function splitTelegramNativeMarkdownLongWrappedInlineBlock(
+  block: string,
+): string[] | undefined {
+  const delimiter = ["**", "__", "~~", "`", "*", "_"]
+    .find((candidate) =>
+      block.startsWith(candidate) &&
+      block.endsWith(candidate) &&
+      block.length > candidate.length * 2
+    );
+  if (!delimiter) return undefined;
+  const maxContentLength = TELEGRAM_RICH_MESSAGE_MAX_CHARS - delimiter.length * 2;
+  if (maxContentLength <= 0) return undefined;
+  return splitTelegramNativeMarkdownWrappedContent(
+    block.slice(delimiter.length, -delimiter.length),
+    maxContentLength,
+    (chunk) => `${delimiter}${chunk}${delimiter}`,
+  );
+}
+
+function splitTelegramNativeMarkdownWrappedContent(
+  content: string,
+  maxContentLength: number,
+  wrap: (chunk: string) => string,
+): string[] {
+  const chunks: string[] = [];
+  let remaining = content;
+  while (remaining.length > maxContentLength) {
+    const window = remaining.slice(0, maxContentLength + 1);
+    const splitIndex = findTelegramNativeMarkdownSplitIndex(window, maxContentLength);
+    chunks.push(wrap(remaining.slice(0, splitIndex)));
+    remaining = remaining.slice(splitIndex);
+  }
+  if (remaining.length > 0) chunks.push(wrap(remaining));
+  return chunks;
+}
+
+function findTelegramNativeMarkdownSplitIndex(
+  text: string,
+  hardLimit = TELEGRAM_RICH_MESSAGE_MAX_CHARS,
+): number {
   const paragraphIndex = text.lastIndexOf("\n\n", hardLimit);
   if (paragraphIndex > 0) return paragraphIndex + 2;
   const lineIndex = text.lastIndexOf("\n", hardLimit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "private": false,
   "publishConfig": {
     "access": "public"