pi-telegram-plus 0.0.2 → 0.0.3

package/lib/renderer.ts

@@ -1,8 +1,14 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { escapeHtml } from "./html.ts";
 import { markdownToTelegramHtml } from "./markdown.ts";
 import type { TelegramConfig, TelegramRenderLevel, TelegramTransport, TelegramTurn } from "./types.ts";
 import { RENDER_LEVELS } from "./types.ts";
+import { log } from "./logger.ts";
+
+const renderLog = log.child("renderer");
 
 type AnyMessage = {
   role?: string;
@@ -51,7 +57,9 @@ function contentToRenderParts(
         : `🔧 ${name}\n${stringifyShort(p.arguments ?? {}, 1200)}`);
     }
   }
-  return { body: body.filter(Boolean).join("\n"), inlineEvents };
+  // Multiple text parts (common when a turn interleaves text around tool calls)
+  // are separated by a blank line so paragraphs don't run together on mobile.
+  return { body: body.filter(Boolean).join("\n\n"), inlineEvents };
 }
 
 function contentImages(content: unknown): Array<{ data: string; mimeType?: string }> {
@@ -65,6 +73,33 @@ function contentImages(content: unknown): Array<{ data: string; mimeType?: strin
   });
 }
 
+/**
+ * Extract renderable text + image parts from a tool result. Tools return
+ * `{ content: (TextContent | ImageContent)[], details }`; we surface the
+ * actual output text (rendered as markdown) and any images, instead of the
+ * truncated JSON blob the previous `full` mode emitted.
+ *
+ * @internal Exported for tests; not part of the public module API.
+ */
+export function extractToolResultParts(result: unknown): {
+  body: string;
+  images: Array<{ data: string; mimeType?: string }>;
+} {
+  const content = (result as Record<string, any> | null | undefined)?.content;
+  const images = contentImages(content);
+  const body: string[] = [];
+  if (Array.isArray(content)) {
+    for (const part of content) {
+      if (part && typeof part === "object" && part.type === "text" && typeof part.text === "string") {
+        body.push(part.text);
+      }
+    }
+  } else if (typeof result === "string") {
+    body.push(result);
+  }
+  return { body: body.filter(Boolean).join("\n\n"), images };
+}
+
 function stringifyShort(value: unknown, max = 900): string {
   let text: string;
   if (typeof value === "string") text = value;
@@ -75,6 +110,63 @@ function stringifyShort(value: unknown, max = 900): string {
   return text.length <= max ? text : text.slice(0, max - 1) + "…";
 }
 
+// ── Oversized code block → file attachment (C1) ─────────────────────────────
+// A single fenced code block that won't fit in one Telegram message is sent
+// as a downloadable document instead of being split across many <pre> chunks
+// (which are painful to read on mobile). The fence is replaced in-body by a
+// short notice so the assistant's prose still reads coherently.
+
+const OVERSIZED_CODE_BYTES = 4000;
+
+const LANG_EXT: Record<string, string> = {
+  ts: ".ts", tsx: ".tsx", js: ".js", jsx: ".jsx", mjs: ".mjs", cjs: ".cjs",
+  py: ".py", python: ".py", rb: ".rb", ruby: ".rb", go: ".go", rs: ".rs", rust: ".rs", java: ".java", kt: ".kt", kotlin: ".kt",
+  c: ".c", h: ".h", cpp: ".cpp", cc: ".cc", hpp: ".hpp", cs: ".cs", php: ".php",
+  swift: ".swift", sh: ".sh", bash: ".sh", zsh: ".sh", fish: ".sh", ps1: ".ps1",
+  sql: ".sql", json: ".json", yml: ".yml", yaml: ".yaml", toml: ".toml",
+  xml: ".xml", html: ".html", htm: ".html", css: ".css", scss: ".scss",
+  md: ".md", markdown: ".md", txt: ".txt", text: ".txt", dockerfile: "Dockerfile",
+  makefile: "Makefile", graphql: ".graphql", lua: ".lua", r: ".r", dart: ".dart",
+  scala: ".scala", clj: ".clj", ex: ".ex", exs: ".exs", erl: ".erl", vim: ".vim",
+};
+
+function langToExt(lang: string): string {
+  const key = (lang || "").trim().toLowerCase();
+  return LANG_EXT[key] ?? ".txt";
+}
+
+/**
+ * Pull fenced code blocks > OVERSIZED_CODE_BYTES out of the markdown body,
+ * replacing each with a one-line notice. Returns the trimmed body and the
+ * extracted blocks (lang + raw content) for file attachment.
+ *
+ * @internal Exported for tests; not part of the public module API.
+ */
+export function extractOversizedCodeBlocks(body: string): {
+  body: string;
+  blocks: Array<{ lang: string; content: string; fileName: string }>;
+} {
+  const blocks: Array<{ lang: string; content: string; fileName: string }> = [];
+  const stripped = body.replace(/```([^\n]*)\n([\s\S]*?)\n```/g, (m, langRaw, content) => {
+    const lang = String(langRaw || "").trim();
+    const code = String(content);
+    if (Buffer.byteLength(code, "utf8") <= OVERSIZED_CODE_BYTES) return m;
+    const idx = blocks.length + 1;
+    const fileName = `code-${idx}${langToExt(lang)}`;
+    blocks.push({ lang, content: code, fileName });
+    const lines = code.split("\n").length;
+    return `\n\n📎 \`${lang || "code"} block (${lines} lines) — attached: ${fileName}\`\n\n`;
+  });
+  return { body: stripped, blocks };
+}
+
+async function writeTempCodeFile(fileName: string, content: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "pi-tg-code-"));
+  const filePath = join(dir, fileName);
+  await writeFile(filePath, content, "utf8");
+  return filePath;
+}
+
 function renderLevel(config: TelegramConfig, key: "tool" | "thinking"): TelegramRenderLevel {
   const value = config[key];
   return (RENDER_LEVELS as readonly string[]).includes(value ?? "") ? value! : "brief";
@@ -176,15 +268,16 @@ export function registerTelegramRenderer(
       return;
     }
     if (options.final && Buffer.byteLength(html, "utf8") > EDIT_LIMIT) {
-      await deps.transport.editText(turn.chatId, turn.replaceMessageId, "🤖 <b>Assistant</b>\n\nFinal answer follows in separate message(s).").catch(() => undefined);
+      await deps.transport.editText(turn.chatId, turn.replaceMessageId, "🤖 <b>Assistant</b>\n\nFinal answer follows in separate message(s).").catch(renderLog.swallow("warn", "editText final-answer pointer failed", { chatId: turn.chatId, messageId: turn.replaceMessageId }));
       turn.replaceMessageId = undefined;
       await deps.transport.sendText(turn.chatId, html);
       return;
     }
     try {
       await deps.transport.editText(turn.chatId, turn.replaceMessageId, html);
-    } catch {
+    } catch (err) {
       // Edit failed (message deleted / too many edits). Fall back to a new message.
+      renderLog.debug("editText failed; falling back to sendText", { chatId: turn.chatId, messageId: turn.replaceMessageId, err });
       turn.replaceMessageId = undefined;
       await deps.transport.sendText(turn.chatId, html);
     }
@@ -208,7 +301,7 @@ export function registerTelegramRenderer(
     const turn = deps.getActiveTurn();
     if (!turn) return;
     if (turn.replaceMessageId !== undefined) await deps.transport.editText(turn.chatId, turn.replaceMessageId, "🤖 <b>Working…</b>");
-    } catch { /* suppressed */ }
+    } catch (err) { renderLog.warn("render status-clear handler failed", { err }); }
   });
 
   pi.on("tool_execution_start", async (event) => {
@@ -221,7 +314,7 @@ export function registerTelegramRenderer(
       : `🔧 ${event.toolName} started
 ${stringifyShort(event.args, 1200)}`;
     await sendInlineEvent(inline);
-    } catch { /* suppressed */ }
+    } catch (err) { renderLog.warn("render tool_execution_start handler failed", { err }); }
   });
 
   pi.on("tool_execution_update", async (event) => {
@@ -236,7 +329,7 @@ ${stringifyShort(event.args, 1200)}`;
     if (!partial || partial === "{}") return;
     await sendInlineEvent(`🔄 ${event.toolName} update
 ${partial}`);
-    } catch { /* suppressed */ }
+    } catch (err) { renderLog.warn("render tool_execution_update handler failed", { err }); }
   });
 
   pi.on("tool_execution_end", async (event) => {
@@ -247,17 +340,33 @@ ${partial}`);
     toolArgs.delete(event.toolCallId);
     if (level === "hidden") return;
     const status = event.isError ? "❌ Tool failed" : "✅ Tool finished";
-    const result = stringifyShort(event.result, event.isError ? 1800 : 900);
     if (level === "brief") {
       if (!event.isError) return;
       await sendInlineEvent(formatToolFailureBrief(event.toolName, event.result, args));
+      return;
+    }
+    // full mode: render the tool's actual output (text + images) as a
+    // persistent new message, so users who opt into `full` see complete
+    // content instead of a truncated JSON blob. Tool results are excluded
+    // from the "never fold" rule, so long ones use an expandable blockquote.
+    const parts = extractToolResultParts(event.result);
+    const header = `${event.isError ? "❌" : "✅"} <b>${escapeHtml(event.toolName)}</b>`;
+    if (parts.body.trim()) {
+      const rendered = markdownToTelegramHtml(parts.body);
+      const expandable = rendered.length > 600 || rendered.split("\n").length > 8;
+      const tag = expandable ? "<blockquote expandable>" : "<blockquote>";
+      await send(`${tag}${header}\n${rendered}</blockquote>`);
     } else {
-      await sendInlineEvent(result && result !== "{}"
-        ? `${status}: ${event.toolName}
-${result}`
-        : `${status}: ${event.toolName}`);
+      await sendInlineEvent(`${status}: ${event.toolName}`);
+    }
+    for (const image of parts.images) {
+      const chatIds = currentChats();
+      for (const chatId of chatIds) {
+        await deps.transport.sendChatAction(chatId, "upload_photo");
+        await deps.transport.sendPhoto(chatId, image.data, "image").catch(renderLog.swallow("warn", "sendPhoto failed", { chatId }));
+      }
     }
-    } catch { /* suppressed */ }
+    } catch (err) { renderLog.warn("tool-result image upload failed", { err }); }
   });
 
   pi.on("message_end", async (event) => {
@@ -269,13 +378,31 @@ ${result}`
     const toolLevel = renderLevel(config, "tool");
     const rendered = contentToRenderParts(message.content, thinkingLevel, toolLevel);
     await sendInlineEvents(rendered.inlineEvents);
-    const body = rendered.body || message.errorMessage || "";
+    const rawBody = rendered.body || message.errorMessage || "";
+    // Pull oversized code blocks out of the body before rendering: they'd
+    // otherwise be split across many <pre> messages (painful on mobile). They
+    // are sent as downloadable files after the body.
+    const { body, blocks: codeFiles } = extractOversizedCodeBlocks(rawBody);
     const images = contentImages(message.content);
 
     const hasBody = body.trim().length > 0;
     if (hasBody) await sendToTurn(markdownToTelegramHtml(body), { final: true });
 
     const turn = deps.getActiveTurn();
+    if (codeFiles.length > 0) {
+      const chatIds = turn ? [turn.chatId] : currentChats();
+      for (const chatId of chatIds) {
+        for (const block of codeFiles) {
+          const filePath = await writeTempCodeFile(block.fileName, block.content).catch(renderLog.swallow("warn", "writeTempCodeFile failed", { fileName: block.fileName }));
+          if (!filePath) continue;
+          await deps.transport.sendChatAction(chatId, "upload_document");
+          const lines = block.content.split("\n").length;
+          const caption = `📎 ${block.lang || "code"} block (${lines} lines)`;
+          await deps.transport.sendDocument(chatId, filePath, caption).catch(renderLog.swallow("warn", "sendDocument code block failed", { chatId, fileName: block.fileName }));
+          await rm(filePath, { force: true }).catch(renderLog.swallow("debug", "rm temp code file failed", { filePath }));
+        }
+      }
+    }
     for (const image of images) {
       const chatIds = turn ? [turn.chatId] : currentChats();
       for (const chatId of chatIds) {
@@ -288,7 +415,7 @@ ${result}`
       await deps.transport.editText(turn.chatId, turn.replaceMessageId, `✅ <b>Output sent.</b>\n${noun}`);
       turn.replaceMessageId = undefined;
     }
-    } catch { /* suppressed */ }
+    } catch (err) { renderLog.warn("render assistant_message handler failed", { err }); }
   });
 
 }

package/lib/telegram-api.ts

@@ -1,7 +1,10 @@
 import { readFile } from "node:fs/promises";
 import { basename, extname } from "node:path";
 import type { TelegramButton, TelegramConfig, TelegramSentMessage, TelegramTransport, TelegramUpdate } from "./types.ts";
-import { stripHtml, splitTelegramText } from "./text-split.ts";
+import { stripHtml, splitTelegramHtml } from "./text-split.ts";
+import { log } from "./logger.ts";
+
+const apiLog = log.child("telegram-api");
 
 type TelegramFileInfo = {
   file_id: string;
@@ -141,20 +144,60 @@ export function createTelegramTransport(getConfig: () => TelegramConfig): Telegr
     return token;
   };
 
+  /** True when an error represents a network-level failure (fetch rejected,
+   *  DNS, connection refused/timeout, …). When the bot is unreachable the
+   *  plain-text fallback retry will fail identically, so callers should skip
+   *  it and let existing `.catch(swallow(...))` / status-line reporting
+   *  surface the outage instead of pointlessly retrying (and logging). */
+  const isNetworkError = (err: unknown): boolean => {
+    const msg = err instanceof Error ? err.message : String(err);
+    // telegramApi wraps raw fetch failures as "Telegram API request failed: <cause>".
+    if (msg.startsWith("Telegram API request failed")) return true;
+    // sendDocument/sendPhoto wrap as "Telegram sendX failed: <cause>"; direct
+    // Node fetch errors also surface with these signatures.
+    return /\bfetch failed\b|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|UND_ERR|socket hang up|network(?:\s|_)?error/i.test(msg);
+  };
+
+  /** Log why an HTML-format send failed before falling back to plain text.
+   *  Without this the renderer's failures were completely silent — a single
+   *  unsupported tag nuked the whole message's formatting and nobody noticed.
+   *
+   *  Network-level failures are intentionally NOT logged here: the polling
+   *  loop already reports them via the status line / ui.notify, and logging
+   *  every failed send when the bot is simply offline would only noise up the
+   *  log file. */
+  const warnHtmlFallback = (label: string, err: unknown, preview: string) => {
+    if (isNetworkError(err)) return;
+    const reason = err instanceof Error ? err.message : String(err);
+    const snippet = preview.replace(/\s+/g, " ").slice(0, 120);
+    apiLog.warn(`HTML ${label} rejected; falling back to plain text`, { reason, snippet });
+  };
+
   return {
     async sendText(chatId, text) {
       const sent: TelegramSentMessage[] = [];
-      for (const chunk of splitTelegramText(text)) {
+      // Use the semantic HTML splitter so multi-message sends cut at block
+      // boundaries (every chunk is independently valid Telegram HTML) instead
+      // of the legacy byte splitter that could split mid-<pre>/<blockquote>
+      // and force a plain-text fallback.
+      for (const chunk of splitTelegramHtml(text)) {
         const body = {
           chat_id: chatId,
           text: chunk,
           parse_mode: "HTML",
         };
         const msg = await callApi<TelegramSentMessage>("sendMessage", body)
-          .catch(() => callApi<TelegramSentMessage>("sendMessage", {
-            chat_id: chatId,
-            text: stripHtml(chunk),
-          }));
+          .catch((err) => {
+            // Network failure: the plain-text retry will fail identically.
+            // Propagate so the caller's `.catch` (or renderer suppression)
+            // handles it; the polling status line already reports outages.
+            if (isNetworkError(err)) throw err;
+            warnHtmlFallback("sendMessage", err, chunk);
+            return callApi<TelegramSentMessage>("sendMessage", {
+              chat_id: chatId,
+              text: stripHtml(chunk),
+            });
+          });
         sent.push(msg);
       }
       return sent;
@@ -164,48 +207,60 @@ export function createTelegramTransport(getConfig: () => TelegramConfig): Telegr
       // Button messages cannot be split without duplicating keyboards, so keep
       // title text short. The UI layer already truncates button labels.
       const reply_markup = buildInlineKeyboard(rows);
-      const first = splitTelegramText(text)[0];
+      const first = splitTelegramHtml(text)[0];
       return await callApi<TelegramSentMessage>("sendMessage", {
         chat_id: chatId,
         text: first,
         parse_mode: "HTML",
         reply_markup,
-      }).catch(() => callApi<TelegramSentMessage>("sendMessage", {
-        chat_id: chatId,
-        text: stripHtml(first),
-        reply_markup,
-      }));
+      }).catch((err) => {
+        if (isNetworkError(err)) throw err;
+        warnHtmlFallback("sendButtons", err, first);
+        return callApi<TelegramSentMessage>("sendMessage", {
+          chat_id: chatId,
+          text: stripHtml(first),
+          reply_markup,
+        });
+      });
     },
 
     async editText(chatId, messageId, text) {
-      const first = splitTelegramText(text)[0];
+      const first = splitTelegramHtml(text)[0];
       await callApi("editMessageText", {
         chat_id: chatId,
         message_id: messageId,
         text: first,
         parse_mode: "HTML",
-      }).catch(() => callApi("editMessageText", {
-        chat_id: chatId,
-        message_id: messageId,
-        text: stripHtml(first),
-      }).catch(() => undefined));
+      }).catch((err) => {
+        if (isNetworkError(err)) return; // swallow; nothing useful to retry
+        warnHtmlFallback("editMessageText", err, first);
+        return callApi("editMessageText", {
+          chat_id: chatId,
+          message_id: messageId,
+          text: stripHtml(first),
+        }).catch(apiLog.swallow("debug", "editMessageText plain-text fallback failed", { chatId, messageId }));
+      });
     },
 
     async editButtons(chatId, messageId, text, rows) {
       const reply_markup = buildInlineKeyboard(rows);
-      const first = splitTelegramText(text)[0];
+      const first = splitTelegramHtml(text)[0];
       await callApi("editMessageText", {
         chat_id: chatId,
         message_id: messageId,
         text: first,
         parse_mode: "HTML",
         reply_markup,
-      }).catch(() => callApi("editMessageText", {
-        chat_id: chatId,
-        message_id: messageId,
-        text: stripHtml(first),
-        reply_markup,
-      }).catch(() => undefined));
+      }).catch((err) => {
+        if (isNetworkError(err)) return; // swallow; nothing useful to retry
+        warnHtmlFallback("editButtons", err, first);
+        return callApi("editMessageText", {
+          chat_id: chatId,
+          message_id: messageId,
+          text: stripHtml(first),
+          reply_markup,
+        }).catch(apiLog.swallow("debug", "editButtons plain-text fallback failed", { chatId, messageId }));
+      });
     },
 
     async answerCallbackQuery(callbackQueryId, text) {
@@ -220,14 +275,14 @@ export function createTelegramTransport(getConfig: () => TelegramConfig): Telegr
         chat_id: chatId,
         message_id: messageId,
         reply_markup: { inline_keyboard: [] },
-      }).catch(() => undefined);
+      }).catch(apiLog.swallow("debug", "removeInlineKeyboard failed", { chatId, messageId }));
     },
 
     async deleteMessage(chatId, messageId) {
       await callApi("deleteMessage", {
         chat_id: chatId,
         message_id: messageId,
-      }).catch(() => undefined);
+      }).catch(apiLog.swallow("warn", "deleteMessage failed", { chatId, messageId }));
     },
 
     async sendDocument(chatId, path, caption, signal) {
@@ -313,7 +368,7 @@ export function createTelegramTransport(getConfig: () => TelegramConfig): Telegr
       await telegramApi(requireToken(), "sendChatAction", {
         chat_id: chatId,
         action,
-      }).catch(() => undefined);
+      }).catch(apiLog.swallow("debug", "sendChatAction failed", { chatId, action }));
     },
   };
 }

package/lib/telegram-ui.ts

@@ -1,5 +1,6 @@
 import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import { encodeUiCallback } from "./callback-protocol.ts";
+import { bridgeCustomDialog } from "./custom-dialogs.ts";
 import { escapeHtml } from "./html.ts";
 import type { CapturedAgentSession, PendingInputResolver, TelegramTransport } from "./types.ts";
 
@@ -84,14 +85,29 @@ export function createTelegramUiRuntime(deps: {
 
   return {
     create(chatId) {
-      const base = deps.getSession()?.extensionRunner.getUIContext?.();
+      // base is the real TUI UI context (create() is called BEFORE runWithTelegramUi
+      // swaps the UI context, so this is the genuine TUI context). We forward persistent
+      // /stateful methods to base so the TUI stays accurate even when the trigger came
+      // from Telegram. Interactive modals stay Telegram-only; editor ops are no-ops.
+      const base = deps.getSession()?.extensionRunner.getUIContext?.() as ExtensionUIContext | undefined;
+
+      const notifyFn = (message: string, level: "info" | "warning" | "error" = "info") => {
+        const fid = activeFlowByChat.get(chatId);
+        void sendOrReplaceText(chatId, `<b>${escapeHtml(String(level))}</b>\n${escapeHtml(message)}`, fid);
+      };
+
       return {
-        ...(base as ExtensionUIContext),
         chatId,
-        notify: (message, level = "info") => {
-          const flowId = activeFlowByChat.get(chatId);
-          void sendOrReplaceText(chatId, `<b>${escapeHtml(String(level))}</b>\n${escapeHtml(message)}`, flowId);
-        },
+
+        // ---- Interactive modals: Telegram-only (do NOT forward to base) ----
+        // Plan Layer A: "谁触发的 turn 就给谁". A Telegram-triggered turn must NOT
+        // also pop the modal in the local TUI, because ExtensionUIContext.custom and
+        // the other modals expose no external cancel handle — once the Telegram side
+        // resolves, any TUI-side component we mounted could never be dismissed, so
+        // the local TUI would stay "stuck at the selection". Local TUI turns never
+        // enter runWithTelegramUi, so they keep using the real TUI UIContext and are
+        // completely unaffected by this Telegram-only path.
+        notify: notifyFn,
         confirm: async (title, message) => {
           const flowId = beginFlow();
           activeFlowByChat.set(chatId, flowId);
@@ -100,6 +116,7 @@ export function createTelegramUiRuntime(deps: {
           ]], flowId);
           const value = await waitInput(chatId, flowId, false, false, sent.message_id);
           activeFlowByChat.delete(chatId);
+          void deps.transport.removeInlineKeyboard(chatId, sent.message_id);
           return value === true || value === "yes";
         },
         input: async (title, placeholder) => {
@@ -108,6 +125,7 @@ export function createTelegramUiRuntime(deps: {
           const sent = await sendOrReplaceButtons(chatId, `<b>${escapeHtml(title)}</b>${placeholder ? `\n${escapeHtml(placeholder)}` : ""}`, [[{ text: "Cancel", value: cb(flowId, "cancel") }]], flowId);
           const value = await waitInput(chatId, flowId, false, true, sent.message_id);
           activeFlowByChat.delete(chatId);
+          void deps.transport.removeInlineKeyboard(chatId, sent.message_id);
           return typeof value === "string" ? value : undefined;
         },
         inputSecret: async (title: string, placeholder?: string) => {
@@ -116,6 +134,7 @@ export function createTelegramUiRuntime(deps: {
           const sent = await sendOrReplaceButtons(chatId, `<b>${escapeHtml(title)}</b>${placeholder ? `\n${escapeHtml(placeholder)}` : ""}`, [[{ text: "Cancel", value: cb(flowId, "cancel") }]], flowId);
           const value = await waitInput(chatId, flowId, true, true, sent.message_id);
           activeFlowByChat.delete(chatId);
+          void deps.transport.removeInlineKeyboard(chatId, sent.message_id);
           return typeof value === "string" ? value : undefined;
         },
         editor: async (title, prefill) => {
@@ -124,6 +143,7 @@ export function createTelegramUiRuntime(deps: {
           const sent = await sendOrReplaceButtons(chatId, `<b>${escapeHtml(title)}</b>${prefill ? `\n${escapeHtml(prefill)}` : ""}`, [[{ text: "Cancel", value: cb(flowId, "cancel") }]], flowId);
           const value = await waitInput(chatId, flowId, false, true, sent.message_id);
           activeFlowByChat.delete(chatId);
+          void deps.transport.removeInlineKeyboard(chatId, sent.message_id);
           return typeof value === "string" ? value : undefined;
         },
         select: async (title, options) => {
@@ -140,15 +160,74 @@ export function createTelegramUiRuntime(deps: {
             const suffix = pageCount > 1 ? ` (${page + 1}/${pageCount})` : "";
             const sent = await sendOrReplaceButtons(chatId, `<b>${escapeHtml(title + suffix)}</b>`, rows, flowId);
             const value = await waitInput(chatId, flowId, false, false, sent.message_id);
-            if (typeof value !== "string") { activeFlowByChat.delete(chatId); return undefined; }
-            if (value === "cancel") { activeFlowByChat.delete(chatId); return undefined; }
+            if (typeof value !== "string") { activeFlowByChat.delete(chatId); void deps.transport.removeInlineKeyboard(chatId, sent.message_id); return undefined; }
+            if (value === "cancel") { activeFlowByChat.delete(chatId); void deps.transport.removeInlineKeyboard(chatId, sent.message_id); return undefined; }
             if (value.startsWith("p:")) { const next = parseInt(value.slice(2), 10); if (next >= 0 && next < pageCount) page = next; continue; }
-            if (value.startsWith("s:")) { const idx = parseInt(value.slice(2), 10); activeFlowByChat.delete(chatId); return idx >= 0 && idx < options.length ? options[idx] : undefined; }
-            if (options.includes(value)) { activeFlowByChat.delete(chatId); return value; }
+            if (value.startsWith("s:")) { const idx = parseInt(value.slice(2), 10); activeFlowByChat.delete(chatId); void deps.transport.removeInlineKeyboard(chatId, sent.message_id); return idx >= 0 && idx < options.length ? options[idx] : undefined; }
+            if (options.includes(value)) { activeFlowByChat.delete(chatId); void deps.transport.removeInlineKeyboard(chatId, sent.message_id); return value; }
             activeFlowByChat.delete(chatId);
+            void deps.transport.removeInlineKeyboard(chatId, sent.message_id);
             return undefined;
           }
         },
+        // custom: bridge pi-goal dialogs to Telegram buttons (Layer B). Does NOT
+        // forward to base — see the modals comment above for why racing the TUI is
+        // structurally un-dismissible and would leave the local TUI stuck.
+        custom: async <T>(factory: (tui: any, theme: any, keybindings: any, done: (result: T) => void) => any | Promise<any>, _options?: any): Promise<T> => {
+          const flowId = beginFlow();
+          activeFlowByChat.set(chatId, flowId);
+          let promptMessageId: number | undefined;
+          const result = await bridgeCustomDialog<T>({
+            factory,
+            theme: base?.theme,
+            width: 80,
+            sendButtons: async (text, rows) => {
+              const encodedRows = rows.map((row) => row.map((btn) => ({ text: btn.text, value: cb(flowId, btn.value) })));
+              const sent = await sendOrReplaceButtons(chatId, text, encodedRows, flowId);
+              promptMessageId = sent.message_id;
+              return sent;
+            },
+            waitInput: (acceptsText = false, sensitive = false) =>
+              waitInput(chatId, flowId, sensitive, acceptsText, promptMessageId),
+            notify: notifyFn,
+            removeKeyboard: async () => { if (promptMessageId) await deps.transport.removeInlineKeyboard(chatId, promptMessageId); },
+          });
+          activeFlowByChat.delete(chatId);
+          // pi-goal accesses result.cancelled/answers without an undefined-guard, so
+          // never resolve undefined: fall back to a structured cancelled result.
+          return (result ?? ({ questions: [], answers: [], cancelled: true } as unknown as T)) as T;
+        },
+
+        // ---- Persistent/stateful UI: forward to TUI base (keeps TUI accurate) ----
+        setStatus: (key: string, text: string | undefined) => { base?.setStatus?.(key, text); },
+        setWorkingMessage: (message?: string) => { base?.setWorkingMessage?.(message); },
+        setWorkingVisible: (visible: boolean) => { base?.setWorkingVisible?.(visible); },
+        setWorkingIndicator: (options?: { frames?: string[]; intervalMs?: number }) => { base?.setWorkingIndicator?.(options); },
+        setHiddenThinkingLabel: (label?: string) => { base?.setHiddenThinkingLabel?.(label); },
+        setWidget: ((key: string, content: unknown, options?: unknown) => { base?.setWidget?.(key as string, content as any, options as any); }) as ExtensionUIContext["setWidget"],
+        setFooter: (factory: unknown) => { base?.setFooter?.(factory as any); },
+        setHeader: (factory: unknown) => { base?.setHeader?.(factory as any); },
+        setTitle: (title: string) => { base?.setTitle?.(title); },
+        setToolsExpanded: (expanded: boolean) => { base?.setToolsExpanded?.(expanded); },
+        getToolsExpanded: () => base?.getToolsExpanded?.() ?? false,
+        setTheme: (theme: string | unknown) => base?.setTheme?.(theme as any) ?? { success: false, error: "UI not available" },
+        getTheme: (name: string) => base?.getTheme?.(name),
+        getAllThemes: () => base?.getAllThemes?.() ?? [],
+
+        // ---- Editor/terminal: no-ops (remote turns must not touch local editor) ----
+        onTerminalInput: () => () => {},
+        pasteToEditor: () => {},
+        setEditorText: () => {},
+        getEditorText: () => "",
+        setEditorComponent: () => {},
+        getEditorComponent: () => undefined,
+        addAutocompleteProvider: () => {},
+
+        // ---- Theme getter: delegate to base (factory needs theme.fg/bg) ----
+        // base is always defined when create() runs (create() is called before the
+        // runWithTelegramUi UI swap, per plan §2.1). The non-null assertion makes
+        // this precondition explicit instead of hiding it behind a cast.
+        get theme() { return base!.theme; },
       };
     },
     resolveInput(chatId, raw, replyToMessageId, fromCallback = false) {