@llblab/pi-telegram 0.19.1 → 0.19.3

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Changelog
 
+## 0.19.3: Extension Catalogue Image Hotfix
+
+- `[Package]` Updated the Pi extension catalogue image URL from the missing `screenshot.png` to the packaged `banner.png`. Impact: Pi extension catalogue listings can render the working banner image for `pi-telegram`.
+
+## 0.19.2: Draft And Rendering Isolation Hotfix
+
+- `[Config]` Grouped assistant answer output under `assistant: { rendering, draftPreviews }`, while still reading and cleaning up legacy `assistantRendering`, `draftPreviews`, and `richDraftPreviews`. Impact: config vocabulary now matches the feature boundary; draft visibility and final rendering live together without implying that previews are inherently Rich Markdown.
+- `[Preview]` Hard-gated preview state creation behind the Draft previews setting. Impact: when Draft previews are off, `message_start` / `message_update` cannot create or flush draft frames; Telegram should show only native active status until the final answer.
+- `[Preview]` Aligned enabled draft previews with the selected final renderer: `assistant.rendering: "rich"` uses `sendRichMessageDraft`, while `assistant.rendering: "html"` uses legacy `sendMessageDraft` with HTML. Impact: the visible draft no longer morphs from Native Rich Markdown into legacy HTML at finalization.
+- `[Rendering]` Removed the thread-reply special case that forced anchored thread assistant replies through legacy Markdown-to-HTML. Impact: `assistant.rendering: "rich"` now uses native Rich Markdown for final assistant replies in Threaded Mode too, while `assistant.rendering: "html"` remains the only path that selects legacy HTML rendering.
+- `[Tests]` Updated reply regressions to assert native Rich Markdown delivery for anchored thread replies.
+
 ## 0.19.1: Settings Layer Hotfix
 
 - `[Settings]` Split the overloaded Rich Draft setting into two independent controls: `Draft previews` for live `sendRichMessageDraft` streaming and `Assistant rendering` for final-answer delivery mode. Impact: operators can hide/show in-progress drafts without changing how final Markdown is rendered.
 - `[Rendering]` Added persisted `assistantRendering: "rich" | "html"`, defaulting to Native Rich Markdown and allowing legacy Markdown-to-HTML final assistant replies when selected. Impact: renderer compatibility is explicit instead of being conflated with preview visibility.
-- `[Preview]` Kept `richDraftPreviews` as the stored draft-preview flag for compatibility, but renamed the Settings UI to `Draft previews`. Impact: existing configs keep working while the product vocabulary matches the Bot API layer.
+- `[Preview]` Kept `richDraftPreviews` as the stored draft-preview flag for compatibility, but renamed the Settings UI to `Draft previews`. Impact: existing configs keep working while the product vocabulary moves toward the preview feature boundary.
 - `[Validation]` Updated menu/settings/reply regressions for the two-axis configuration model.
 
 ## 0.19.0: Telegram Companion Hub

package/README.md

@@ -202,7 +202,7 @@ Most controls live in Pi commands or the Telegram menu. Environment variables re
 | Inbound file limit | `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES`, `TELEGRAM_MAX_FILE_SIZE_BYTES` |
 | Outbound attachment limit | `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES`, `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES` |
 
-Defaults are chosen for ordinary private-bot use: saved config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, `assistantRendering: "rich"` for final replies, `richDraftPreviews: false` for no live draft text by default, and native Telegram active status for long-running turns.
+Defaults are chosen for ordinary private-bot use: saved config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, `assistant: { rendering: "rich", draftPreviews: false }` for assistant answer output, and native Telegram active status for long-running turns.
 
 ## Extension Platform
 

package/docs/architecture.md

@@ -223,11 +223,11 @@ During active Telegram-owned turns, assistant message start/update hooks re-arm
 
 ### Rendering And Delivery
 
-Rich Markdown is the default model-answer membrane. Complete assistant replies send final Markdown directly as `InputRichMessage.markdown` through `sendRichMessage` when `assistantRendering` is `rich`, and through the legacy Markdown-to-HTML renderer when `assistantRendering` is `html`; guest replies use native Rich Markdown through `InputRichMessageContent` in `answerGuestQuery` results. Tool-call rows, reasoning/thinking blocks, menus, status rows, queue controls, settings, diagnostics, and other harness-owned surfaces stay on explicit Telegram HTML/plain rendering. Streaming previews may use `sendRichMessageDraft` only when Draft previews are enabled and draft delivery succeeds. The bridge still strips top-level assistant action comments before delivery and may split output only for Telegram transport limits.
+Rich Markdown is the default model-answer membrane. Complete assistant replies send final Markdown directly as `InputRichMessage.markdown` through `sendRichMessage` when `assistant.rendering` is `rich`, and through the legacy Markdown-to-HTML renderer when `assistant.rendering` is `html`; guest replies use native Rich Markdown through `InputRichMessageContent` in `answerGuestQuery` results. Tool-call rows, reasoning/thinking blocks, menus, status rows, queue controls, settings, diagnostics, and other harness-owned surfaces stay on explicit Telegram HTML/plain rendering. Streaming previews may use `sendRichMessageDraft` only when `assistant.draftPreviews` is enabled and draft delivery succeeds. The bridge still strips top-level assistant action comments before delivery and may split output only for Telegram transport limits.
 
 Assistant delivery guarantees:
 
-- Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML unless the operator selects `assistantRendering: "html"` for compatibility.
+- Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML unless the operator selects `assistant.rendering: "html"` for compatibility.
 - 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; oversized fenced code, display-math, and fully wrapped inline-formatting blocks are rewrapped per chunk so persisted Rich Markdown chunks remain structurally valid.

package/index.ts

@@ -478,7 +478,9 @@ export default function (pi: Pi.ExtensionAPI) {
       recordRuntimeEvent,
     });
   const nativeMarkdownDraftSender =
-    TelegramApi.createTelegramNativeMarkdownDraftSender({
+    TelegramApi.createTelegramAssistantDraftSender({
+      getAssistantRenderingMode: configControls.getAssistantRenderingMode,
+      renderMarkdownToHtmlDraft: Replies.renderTelegramMarkdownToHtmlDraft,
       sendMessageDraft,
       sendRichMessageDraft,
     });
@@ -488,7 +490,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getMessageText: Replies.getAgentMessageText,
     getDefaultReplyToMessageId: activeTurnRuntime.getReplyToMessageId,
     sendDraft: nativeMarkdownDraftSender,
-    canSend: configControls.areRichDraftPreviewsEnabled,
+    canSend: configControls.areDraftPreviewsEnabled,
     sendMarkdownReply,
     recordRuntimeEvent,
     ...replyTransport,

package/lib/config.ts

@@ -59,7 +59,15 @@ export interface TelegramConfig {
   attachmentHandlers?: TelegramInboundHandlerConfig[];
   outboundHandlers?: TelegramOutboundHandlerConfig[];
   proactivePush?: boolean;
+  assistant?: {
+    draftPreviews?: boolean;
+    rendering?: TelegramAssistantRenderingMode;
+  };
+  /** @deprecated use assistant.draftPreviews */
+  draftPreviews?: boolean;
+  /** @deprecated use assistant.draftPreviews */
   richDraftPreviews?: boolean;
+  /** @deprecated use assistant.rendering */
   assistantRendering?: TelegramAssistantRenderingMode;
   voice?: {
     replyMode?: "manual" | "mirror" | "always";
@@ -263,18 +271,34 @@ export function createTelegramProactivePushSetter(
   };
 }
 
-export function createTelegramRichDraftPreviewsChecker(
+export function createTelegramDraftPreviewsChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
-  return () => configStore.get().richDraftPreviews ?? false;
+  return () => {
+    const config = configStore.get();
+    return (
+      config.assistant?.draftPreviews ??
+      config.draftPreviews ??
+      config.richDraftPreviews ??
+      false
+    );
+  };
 }
 
-export function createTelegramRichDraftPreviewsSetter(
+export function createTelegramDraftPreviewsSetter(
   configStore: TelegramMutableConfigStore,
 ): (enabled: boolean) => Promise<void> {
   return async (enabled) => {
     await loadLatestTelegramConfig(configStore);
-    const config = { ...configStore.get(), richDraftPreviews: enabled };
+    const {
+      draftPreviews: _legacyDraftPreviews,
+      richDraftPreviews: _legacyRichDraftPreviews,
+      ...current
+    } = configStore.get();
+    const config = {
+      ...current,
+      assistant: { ...current.assistant, draftPreviews: enabled },
+    };
     configStore.set(config);
     await configStore.persist(config);
   };
@@ -284,7 +308,8 @@ export function createTelegramAssistantRenderingModeGetter(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => TelegramAssistantRenderingMode {
   return () => {
-    const mode = configStore.get().assistantRendering;
+    const config = configStore.get();
+    const mode = config.assistant?.rendering ?? config.assistantRendering;
     return mode === "html" ? "html" : "rich";
   };
 }
@@ -294,7 +319,12 @@ export function createTelegramAssistantRenderingModeSetter(
 ): (mode: TelegramAssistantRenderingMode) => Promise<void> {
   return async (mode) => {
     await loadLatestTelegramConfig(configStore);
-    const config = { ...configStore.get(), assistantRendering: mode };
+    const { assistantRendering: _legacyAssistantRendering, ...current } =
+      configStore.get();
+    const config = {
+      ...current,
+      assistant: { ...current.assistant, rendering: mode },
+    };
     configStore.set(config);
     await configStore.persist(config);
   };
@@ -435,10 +465,8 @@ export function createTelegramConfigControls(
   return {
     isProactivePushEnabled: createTelegramProactivePushChecker(configStore),
     setProactivePushEnabled: createTelegramProactivePushSetter(configStore),
-    areRichDraftPreviewsEnabled:
-      createTelegramRichDraftPreviewsChecker(configStore),
-    setRichDraftPreviewsEnabled:
-      createTelegramRichDraftPreviewsSetter(configStore),
+    areDraftPreviewsEnabled: createTelegramDraftPreviewsChecker(configStore),
+    setDraftPreviewsEnabled: createTelegramDraftPreviewsSetter(configStore),
     getAssistantRenderingMode:
       createTelegramAssistantRenderingModeGetter(configStore),
     setAssistantRenderingMode:

package/lib/menu-settings.ts

@@ -21,7 +21,7 @@ export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 
 export interface TelegramSettingsStateDeps {
   isProactivePushEnabled: () => boolean;
-  areRichDraftPreviewsEnabled: () => boolean;
+  areDraftPreviewsEnabled: () => boolean;
   getAssistantRenderingMode: () => TelegramAssistantRenderingMode;
   getTimeInjectionMode: () => TelegramTimeMode;
   getVoiceReplyMode: () => TelegramVoiceReplyMode;
@@ -30,7 +30,7 @@ export interface TelegramSettingsStateDeps {
 
 export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps {
   setProactivePushEnabled: (enabled: boolean) => Promise<void>;
-  setRichDraftPreviewsEnabled: (enabled: boolean) => Promise<void>;
+  setDraftPreviewsEnabled: (enabled: boolean) => Promise<void>;
   setAssistantRenderingMode: (
     mode: TelegramAssistantRenderingMode,
   ) => Promise<void>;
@@ -311,7 +311,7 @@ export async function openTelegramSettingsMenu<
     buildTelegramSettingsMenuText(),
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
-      deps.areRichDraftPreviewsEnabled(),
+      deps.areDraftPreviewsEnabled(),
       deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
       deps.getTimeInjectionMode(),
@@ -431,7 +431,7 @@ export async function updateTelegramSettingsMenuMessage(
     buildTelegramSettingsMenuText(),
     buildTelegramSettingsMenuReplyMarkup(
       deps.isProactivePushEnabled(),
-      deps.areRichDraftPreviewsEnabled(),
+      deps.areDraftPreviewsEnabled(),
       deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
       deps.getTimeInjectionMode(),
@@ -454,7 +454,7 @@ export async function updateProactivePushSettingsMessage(
 export async function updateDraftPreviewsSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
-  const enabled = deps.areRichDraftPreviewsEnabled();
+  const enabled = deps.areDraftPreviewsEnabled();
   await deps.updateSettingsMessage(
     buildDraftPreviewsSettingsText(enabled),
     buildDraftPreviewsSettingsReplyMarkup(enabled),
@@ -577,7 +577,7 @@ export async function handleTelegramSettingsMenuCallbackAction(
     data === "settings:set:rich-drafts:off"
   ) {
     const enabled = data.endsWith(":on");
-    await deps.setRichDraftPreviewsEnabled(enabled);
+    await deps.setDraftPreviewsEnabled(enabled);
     await updateDraftPreviewsSettingsMessage(deps);
     await deps.answerCallbackQuery(
       callbackQueryId,
@@ -624,7 +624,7 @@ export function createTelegramSettingsMenuRuntime<
         {
           getModelMenuState: () => deps.getModelMenuState(chatId, ctx),
           isProactivePushEnabled: deps.isProactivePushEnabled,
-          areRichDraftPreviewsEnabled: deps.areRichDraftPreviewsEnabled,
+          areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
           getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
@@ -644,7 +644,7 @@ export function createTelegramSettingsMenuRuntime<
       updateTelegramSettingsMenuMessage(
         {
           isProactivePushEnabled: deps.isProactivePushEnabled,
-          areRichDraftPreviewsEnabled: deps.areRichDraftPreviewsEnabled,
+          areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
           getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
@@ -691,7 +691,7 @@ export function createTelegramSettingsMenuRuntime<
           query.data === "settings:set:rich-drafts:off"
         ) {
           const enabled = query.data.endsWith(":on");
-          await deps.setRichDraftPreviewsEnabled(enabled);
+          await deps.setDraftPreviewsEnabled(enabled);
           await deps.answerCallbackQuery(
             query.id,
             `Draft previews ${enabled ? "enabled" : "disabled"}`,
@@ -736,13 +736,13 @@ export function createTelegramSettingsMenuRuntime<
       }
       return handleTelegramSettingsMenuCallbackAction(query.id, query.data, {
         isProactivePushEnabled: deps.isProactivePushEnabled,
-        areRichDraftPreviewsEnabled: deps.areRichDraftPreviewsEnabled,
+        areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
         getAssistantRenderingMode: deps.getAssistantRenderingMode,
         getVoiceReplyMode: deps.getVoiceReplyMode,
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
         getTimeInjectionMode: deps.getTimeInjectionMode,
         setProactivePushEnabled: deps.setProactivePushEnabled,
-        setRichDraftPreviewsEnabled: deps.setRichDraftPreviewsEnabled,
+        setDraftPreviewsEnabled: deps.setDraftPreviewsEnabled,
         setAssistantRenderingMode: deps.setAssistantRenderingMode,
         setVoiceReplyMode: deps.setVoiceReplyMode,
         setTimeInjectionMode: deps.setTimeInjectionMode,

package/lib/preview.ts

@@ -73,6 +73,7 @@ export interface TelegramAssistantMessagePreviewStartDeps<
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   createPreviewState: () => TelegramPreviewRuntimeState;
+  canSend?: () => boolean;
   finalizePreview: (chatId: number) => Promise<boolean>;
   finalizeMarkdownPreview: (
     chatId: number,
@@ -88,6 +89,7 @@ export interface TelegramAssistantMessagePreviewUpdateDeps<TMessage> {
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   createPreviewState: () => TelegramPreviewRuntimeState;
+  canSend?: () => boolean;
   getMessageText: (message: TMessage) => string;
   schedulePreviewFlush: (
     chatId: number,
@@ -260,6 +262,7 @@ export function createTelegramAssistantPreviewRuntime<
       getState: controller.getState,
       setState: controller.setState,
       createPreviewState: controller.createState,
+      canSend: deps.canSend,
       finalizePreview: controller.finalize,
       finalizeMarkdownPreview,
       getMessageText: deps.getMessageText,
@@ -349,6 +352,10 @@ export async function handleTelegramAssistantMessagePreviewStart<
 ): Promise<void> {
   const turn = deps.getActiveTurn();
   if (!turn || !deps.isAssistantMessage(message)) return;
+  if (deps.canSend && !deps.canSend()) {
+    deps.setState(undefined);
+    return;
+  }
   if (shouldSuppressPreviewForVoice(turn)) {
     deps.setState(undefined);
     return;
@@ -382,6 +389,10 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
 ): Promise<void> {
   const turn = deps.getActiveTurn();
   if (!turn || !deps.isAssistantMessage(message)) return;
+  if (deps.canSend && !deps.canSend()) {
+    deps.setState(undefined);
+    return;
+  }
   if (shouldSuppressPreviewForVoice(turn)) return;
   let state = deps.getState();
   if (!state) {

package/lib/replies.ts

@@ -27,6 +27,12 @@ export {
   type TelegramRenderMode,
 };
 
+export function renderTelegramMarkdownToHtmlDraft(markdown: string): string {
+  return renderTelegramMessage(markdown, { mode: "markdown" })
+    .map((chunk) => chunk.text)
+    .join("\n");
+}
+
 export const TELEGRAM_RICH_MESSAGE_MAX_CHARS = 32768;
 export const TELEGRAM_RICH_MESSAGE_MAX_BLOCKS = 500;
 
@@ -783,12 +789,7 @@ export function createTelegramRenderedMessageRuntime<TReplyMarkup>(
     },
     sendMarkdownReply: async (chatId, replyToMessageId, markdown, options) => {
       const renderingMode = deps.getAssistantRenderingMode?.() ?? "rich";
-      if (
-        renderingMode === "html" ||
-        (typeof options?.target?.threadId === "number" &&
-          replyToMessageId !== undefined &&
-          replyToMessageId > 0)
-      ) {
+      if (renderingMode === "html") {
         return deps.replyTransport.sendRenderedChunks(
           chatId,
           deps.renderTelegramMessage(markdown, { mode: "markdown" }),

package/lib/telegram-api.ts

@@ -1112,6 +1112,24 @@ export function createTelegramNativeMarkdownDraftSender(deps: {
   };
 }
 
+export function createTelegramAssistantDraftSender(deps: {
+  getAssistantRenderingMode: () => "rich" | "html";
+  renderMarkdownToHtmlDraft: (markdown: string) => string;
+  sendMessageDraft: TelegramBridgeApiRuntime["sendMessageDraft"];
+  sendRichMessageDraft: TelegramBridgeApiRuntime["sendRichMessageDraft"];
+}): TelegramBridgeApiRuntime["sendMessageDraft"] {
+  const sendNativeDraft = createTelegramNativeMarkdownDraftSender(deps);
+  return (chatId, draftId, text, options) => {
+    if (text === undefined || deps.getAssistantRenderingMode() === "rich") {
+      return sendNativeDraft(chatId, draftId, text, options);
+    }
+    return deps.sendMessageDraft(chatId, draftId, deps.renderMarkdownToHtmlDraft(text), {
+      ...options,
+      parse_mode: "HTML",
+    });
+  };
+}
+
 export function createDefaultTelegramBridgeApiRuntime(deps: {
   getBotToken: () => string | undefined;
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -59,7 +59,7 @@
     "extensions": [
       "./index.ts"
     ],
-    "image": "https://github.com/llblab/pi-telegram/raw/main/screenshot.png"
+    "image": "https://github.com/llblab/pi-telegram/raw/main/banner.png"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",