pi-telegram-plus 0.0.1

package/lib/session-capture.ts

@@ -0,0 +1,95 @@
+/**
+ * Session Capture & Handler Patching
+ *
+ * When p-tui starts, InteractiveMode calls session.bindExtensions() with
+ * command-context handlers (newSession, fork, navigateTree, switchSession, reload)
+ * that contain TUI rendering side effects.
+ *
+ * These handlers are needed for their CORE LOGIC (session lifecycle via runtimeHost).
+ * The TUI rendering is harmless (just refreshes the terminal).
+ *
+ * After bindExtensions, we patch two things:
+ *
+ * 1. The shutdown handler is replaced to prevent exiting the TUI event loop
+ *    from a Telegram command. Instead it just notifies.
+ *
+ * 2. Other handlers are left as-is. The TUI rendering they contain is harmless,
+ *    and Telegram notifications are handled by the command handlers themselves
+ *    using a captured ui reference (see below).
+ *
+ * IMPORTANT: rebindSession triggers a new bindExtensions() call, which re-runs
+ * our monkey-patch. Since originalBindExtensions sets FRESH handlers each time
+ * (from the new bindings), there is no accumulation of wrappers.
+ *
+ * IMPORTANT: /reload rebuilds the extension runtime without calling
+ * bindExtensions(). Therefore capture state must live on globalThis instead of
+ * module-local variables; otherwise the freshly loaded extension instance loses
+ * activeSession and Telegram appears disconnected after reload.
+ *
+ * IMPORTANT: After rebind, runner.uiContext is reset to the TUI UI context.
+ * This means ctx.ui (a getter reading runner.uiContext) would return the TUI UI
+ * instead of TelegramUi. Command handlers MUST capture ctx.ui at the start
+ * and use the captured reference for all Telegram notifications:
+ *
+ *   handler: async (args, ctx) => {
+ *     const ui = ctx.ui;  ← capture before any rebind can occur
+ *     ...
+ *     ui.notify("✅ Done", "info");  ← always goes to Telegram
+ *   };
+ */
+
+import { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { CapturedAgentSession } from "./types.ts";
+
+type SessionCaptureState = {
+  activeSession?: CapturedAgentSession;
+  installed: boolean;
+};
+
+const SESSION_CAPTURE_STATE = Symbol.for("pi-telegram-plus.session-capture-state");
+
+function getState(): SessionCaptureState {
+  const g = globalThis as typeof globalThis & Record<symbol, SessionCaptureState | undefined>;
+  g[SESSION_CAPTURE_STATE] ??= { installed: false };
+  return g[SESSION_CAPTURE_STATE];
+}
+
+export function installAgentSessionCapture(): void {
+  const state = getState();
+  if (state.installed) return;
+  state.installed = true;
+
+  const proto = AgentSession.prototype as CapturedAgentSession & {
+    bindExtensions: AgentSession["bindExtensions"];
+  };
+  const originalBindExtensions = proto.bindExtensions;
+
+  proto.bindExtensions = async function patchedBindExtensions(this: CapturedAgentSession, bindings) {
+    // Make the replacing session visible before originalBindExtensions emits
+    // session_start. Otherwise session_start handlers briefly see the previous
+    // session, which is especially visible for lifecycle-driven integrations
+    // such as Telegram reconnect/status handling after /new.
+    state.activeSession = this;
+
+    const result = await originalBindExtensions.call(this, bindings);
+
+    const runner = this.extensionRunner;
+
+    // ── Replace shutdown handler ───────────────────────────────────────
+    // Original exits the TUI event loop — dangerous from a Telegram command.
+    // Replace with a safe notification.
+    (runner as unknown as { shutdownHandler: () => void }).shutdownHandler = () => {
+      const ui = runner.getUIContext();
+      ui.notify(
+        "⚠️ Shutdown requested. Use Ctrl+C in terminal to stop pi.",
+        "info",
+      );
+    };
+
+    return result;
+  };
+}
+
+export function getActiveSession(): CapturedAgentSession | undefined {
+  return getState().activeSession;
+}

package/lib/status.ts

@@ -0,0 +1,46 @@
+export const TELEGRAM_STATUS_KEY = "telegram-plus";
+
+export type StatusLineTheme = {
+  fg(token: "accent" | "error" | "muted" | "warning" | "success", text: string): string;
+};
+
+export type StatusLineUi = {
+  theme: StatusLineTheme;
+  setStatus(key: string, text: string | undefined): void;
+};
+
+export function formatTelegramStatusLine(
+  theme: StatusLineTheme,
+  state: {
+    hasBotToken: boolean;
+    pollingActive: boolean;
+    paired: boolean;
+    processing?: boolean;
+    error?: string;
+    botUsername?: string;
+  },
+): string {
+  const label = theme.fg("accent", "telegram+");
+  if (state.error) {
+    return `${label} ${theme.fg("error", "error")} ${theme.fg("muted", state.error)}`;
+  }
+  if (!state.hasBotToken) {
+    return `${label} ${theme.fg("muted", "not configured")}`;
+  }
+  if (!state.pollingActive) {
+    return `${label} ${theme.fg("muted", "disconnected")}`;
+  }
+  if (!state.paired) {
+    return `${label} ${theme.fg("warning", "awaiting pairing")}`;
+  }
+  const bot = state.botUsername ? ` @${state.botUsername}` : "";
+  if (state.processing) {
+    return `${label} ${theme.fg("warning", "active")}${bot}`;
+  }
+  return `${label} ${theme.fg("success", "connected")}${bot}`;
+}
+
+export function clearTelegramStatus(ctx: { ui?: StatusLineUi }): void {
+  if (!ctx?.ui?.setStatus) return;
+  ctx.ui.setStatus(TELEGRAM_STATUS_KEY, undefined);
+}

package/lib/telegram-api.ts

@@ -0,0 +1,327 @@
+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";
+
+type TelegramFileInfo = {
+  file_id: string;
+  file_unique_id?: string;
+  file_size?: number;
+  file_path: string;
+};
+
+type TelegramApiError = {
+  ok: boolean;
+  result?: unknown;
+  description?: string;
+};
+
+const TELEGRAM_CALLBACK_LIMIT = 64;
+
+function inferMimeTypeFromPath(path: string): string | undefined {
+  const extension = extname(path).toLowerCase();
+  switch (extension) {
+    case ".png":
+      return "image/png";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".webp":
+      return "image/webp";
+    case ".gif":
+      return "image/gif";
+    case ".txt":
+      return "text/plain";
+    case ".json":
+      return "application/json";
+    case ".md":
+      return "text/markdown";
+    case ".html":
+    case ".htm":
+      return "text/html";
+    default:
+      return undefined;
+  }
+}
+
+export async function telegramApi<T>(
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+  signal?: AbortSignal,
+): Promise<T> {
+  const response = await fetch(`https://api.telegram.org/bot${token}/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+    signal,
+  });
+  const json = (await response.json()) as TelegramApiError & { result: T };
+  if (!json.ok) throw new Error(json.description ?? `${method} failed`);
+  return json.result;
+}
+
+export async function getTelegramFile(token: string, fileId: string, signal?: AbortSignal): Promise<TelegramFileInfo> {
+  return telegramApi<TelegramFileInfo>(
+    token,
+    "getFile",
+    { file_id: fileId },
+    signal,
+  );
+}
+
+export async function downloadTelegramFile(token: string, filePath: string, signal?: AbortSignal): Promise<Buffer> {
+  const encodedPath = filePath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  const response = await fetch(`https://api.telegram.org/file/bot${token}/${encodedPath}`, {
+    method: "GET",
+    signal,
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to download Telegram file: ${response.status}`);
+  }
+  const bytes = await response.arrayBuffer();
+  return Buffer.from(bytes);
+}
+
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export function createTelegramTransport(getConfig: () => TelegramConfig): TelegramTransport {
+  const cfg = () => getConfig();
+
+  /** Call a Telegram API method with retry on transient failures. */
+  const callApi = async <T>(method: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<T> => {
+    const token = requireToken();
+    const maxRetries = cfg().retryCount ?? 3;
+    let lastError: unknown;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await telegramApi<T>(token, method, body, signal);
+      } catch (error) {
+        lastError = error;
+        if (attempt >= maxRetries || signal?.aborted) throw error;
+        // Exponential backoff: 500ms, 1s, 2s
+        await sleep(250 * Math.pow(2, attempt));
+      }
+    }
+    throw lastError;
+  };
+
+  /** Non-retrying API call (for idempotent fire-and-forget or catch-suppressed helpers). */
+  const callApiOnce = async <T>(method: string, body: Record<string, unknown>) => {
+    return telegramApi<T>(requireToken(), method, body);
+  };
+  const buildInlineKeyboard = (rows: TelegramButton[][]) => ({
+    inline_keyboard: rows.map((row: TelegramButton[]) =>
+      row.map((button) => {
+        if (Buffer.byteLength(button.value, "utf8") > TELEGRAM_CALLBACK_LIMIT) {
+          throw new Error(`Telegram callback_data exceeds ${TELEGRAM_CALLBACK_LIMIT} bytes: ${button.text}`);
+        }
+        return {
+          text: button.text,
+          callback_data: button.value,
+        };
+      }),
+    ),
+  });
+
+  const requireToken = () => {
+    const token = getConfig().botToken;
+    if (!token) throw new Error("Telegram bot token is not configured");
+    return token;
+  };
+
+  return {
+    async sendText(chatId, text) {
+      const sent: TelegramSentMessage[] = [];
+      for (const chunk of splitTelegramText(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),
+          }));
+        sent.push(msg);
+      }
+      return sent;
+    },
+
+    async sendButtons(chatId, text, rows) {
+      // 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];
+      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,
+      }));
+    },
+
+    async editText(chatId, messageId, text) {
+      const first = splitTelegramText(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));
+    },
+
+    async editButtons(chatId, messageId, text, rows) {
+      const reply_markup = buildInlineKeyboard(rows);
+      const first = splitTelegramText(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));
+    },
+
+    async answerCallbackQuery(callbackQueryId, text) {
+      await callApi("answerCallbackQuery", {
+        callback_query_id: callbackQueryId,
+        ...(text ? { text } : {}),
+      });
+    },
+
+    async removeInlineKeyboard(chatId, messageId) {
+      await callApi("editMessageReplyMarkup", {
+        chat_id: chatId,
+        message_id: messageId,
+        reply_markup: { inline_keyboard: [] },
+      }).catch(() => undefined);
+    },
+
+    async deleteMessage(chatId, messageId) {
+      await callApi("deleteMessage", {
+        chat_id: chatId,
+        message_id: messageId,
+      }).catch(() => undefined);
+    },
+
+    async sendDocument(chatId, path, caption, signal) {
+      const token = requireToken();
+      const maxRetries = cfg().retryCount ?? 3;
+      const data = await readFile(path);
+      let lastError: unknown;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const form = new FormData();
+          form.set("chat_id", String(chatId));
+          if (caption) form.set("caption", caption);
+          const documentBlob = new Blob([data], {
+            type: inferMimeTypeFromPath(path) ?? "application/octet-stream",
+          });
+          form.set("document", documentBlob, basename(path));
+          const response = await fetch(`https://api.telegram.org/bot${token}/sendDocument`, {
+            method: "POST",
+            body: form,
+            signal,
+          });
+          const json = await response.json() as { ok: boolean; description?: string };
+          if (!json.ok) throw new Error(json.description ?? "sendDocument failed");
+          return;
+        } catch (error) {
+          lastError = error;
+          if (attempt >= maxRetries || signal?.aborted) throw error;
+          await sleep(250 * Math.pow(2, attempt));
+        }
+      }
+      throw lastError;
+    },
+
+    async sendPhoto(chatId, data, caption, isPath = false, signal) {
+      const token = requireToken();
+      const maxRetries = cfg().retryCount ?? 3;
+      let lastError: unknown;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const form = new FormData();
+          form.set("chat_id", String(chatId));
+          if (caption) form.set("caption", caption);
+          if (isPath) {
+            const bytes = await readFile(data);
+            form.set("photo", new Blob([bytes], {
+              type: inferMimeTypeFromPath(data) ?? "image/jpeg",
+            }), basename(data));
+          } else {
+            const match = data.match(/^data:([^;]+);base64,(.*)$/);
+            const base64 = match ? match[2] : data;
+            const mime = match?.[1] ?? "image/png";
+            const bytes = Buffer.from(base64, "base64");
+            form.set("photo", new Blob([bytes], { type: mime }), `image.${mime.split("/")[1] ?? "png"}`);
+          }
+          const response = await fetch(`https://api.telegram.org/bot${token}/sendPhoto`, {
+            method: "POST",
+            body: form,
+            signal,
+          });
+          const json = await response.json() as { ok: boolean; description?: string };
+          if (!json.ok) throw new Error(json.description ?? "sendPhoto failed");
+          return;
+        } catch (error) {
+          lastError = error;
+          if (attempt >= maxRetries || signal?.aborted) throw error;
+          await sleep(250 * Math.pow(2, attempt));
+        }
+      }
+      throw lastError;
+    },
+
+    async sendChatAction(chatId, action) {
+      await telegramApi(requireToken(), "sendChatAction", {
+        chat_id: chatId,
+        action,
+      }).catch(() => undefined);
+    },
+  };
+}
+
+export async function getTelegramBotUsername(token: string): Promise<string | undefined> {
+  const result = await telegramApi<{ username?: string }>(token, "getMe", {});
+  return result.username;
+}
+
+export async function setTelegramMyCommands(token: string, commands: Array<{ command: string; description: string }>): Promise<void> {
+  await telegramApi(token, "setMyCommands", {
+    commands,
+  });
+}
+
+export async function getTelegramUpdates(
+  config: TelegramConfig,
+  signal: AbortSignal,
+): Promise<TelegramUpdate[]> {
+  if (!config.botToken) return [];
+  return telegramApi<TelegramUpdate[]>(
+    config.botToken,
+    "getUpdates",
+    {
+      offset: config.lastUpdateId === undefined ? undefined : config.lastUpdateId + 1,
+      timeout: 30,
+      allowed_updates: ["message", "callback_query"],
+    },
+    signal,
+  );
+}

package/lib/telegram-ui.ts

@@ -0,0 +1,208 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { encodeUiCallback } from "./callback-protocol.ts";
+import { escapeHtml } from "./html.ts";
+import type { CapturedAgentSession, PendingInputResolver, TelegramTransport } from "./types.ts";
+
+const MAX_BUTTON_TEXT = 60;
+const PAGE_SIZE = 10;
+const INPUT_TIMEOUT_MS = 10 * 60 * 1000;
+
+type Pending = { flowId: string; resolve: PendingInputResolver; timer: NodeJS.Timeout; sensitive: boolean; acceptsText: boolean; promptMessageId?: number };
+
+function truncateLabel(text: string): string { return text.length <= MAX_BUTTON_TEXT ? text : text.slice(0, MAX_BUTTON_TEXT - 1) + "…"; }
+
+export type TelegramUiRuntime = {
+  create(chatId: number): ExtensionUIContext & { chatId: number; inputSecret?: (title: string, placeholder?: string) => Promise<string | undefined> };
+  resolveInput(chatId: number, value: string | boolean | undefined, replyToMessageId?: number, fromCallback?: boolean): { handled: boolean; promptMessageId?: number };
+  isSensitiveInput(chatId: number, replyToMessageId?: number): boolean;
+  hasPendingInput(chatId: number): boolean;
+  dispose(): void;
+};
+
+export function createTelegramUiRuntime(deps: {
+  getSession: () => CapturedAgentSession | undefined;
+  transport: TelegramTransport;
+  onPendingInputChange?: (chatId: number) => void;
+}): TelegramUiRuntime {
+  const pendingByChat = new Map<number, Map<string, Pending>>();
+  // Per-flow replace targets prevent rapid callbacks from overwriting each other.
+  const replaceNextMessageByFlow = new Map<string, number>();
+  const latestTextFlow = new Map<number, string>();
+  const latestFlow = new Map<number, string>();
+  let nextFlowId = 1;
+
+  const flows = (chatId: number) => {
+    let map = pendingByChat.get(chatId);
+    if (!map) { map = new Map(); pendingByChat.set(chatId, map); }
+    return map;
+  };
+  const clearFlow = (chatId: number, flowId: string) => {
+    const map = pendingByChat.get(chatId); const pending = map?.get(flowId);
+    if (pending) clearTimeout(pending.timer);
+    map?.delete(flowId);
+    if (latestTextFlow.get(chatId) === flowId) latestTextFlow.delete(chatId);
+    if (latestFlow.get(chatId) === flowId) latestFlow.delete(chatId);
+    if (map && map.size === 0) pendingByChat.delete(chatId);
+    if (pending) deps.onPendingInputChange?.(chatId);
+  };
+  const beginFlow = () => String(nextFlowId++);
+  const waitInput = (chatId: number, flowId: string, sensitive = false, acceptsText = true, promptMessageId?: number) =>
+    new Promise<string | boolean | undefined>((resolve) => {
+      const timer = setTimeout(() => { if (flows(chatId).has(flowId)) { clearFlow(chatId, flowId); resolve(undefined); } }, INPUT_TIMEOUT_MS);
+      flows(chatId).set(flowId, { flowId, resolve, timer, sensitive, acceptsText, promptMessageId });
+      latestFlow.set(chatId, flowId);
+      if (acceptsText) latestTextFlow.set(chatId, flowId);
+      deps.onPendingInputChange?.(chatId);
+    });
+  const cb = (flowId: string, value: string) => encodeUiCallback(`f:${flowId}:${value}`);
+  const getReplaceIdForFlow = (chatId: number, flowId: string | undefined): number | undefined => {
+    if (!flowId) return undefined;
+    const id = replaceNextMessageByFlow.get(flowId);
+    if (id !== undefined) replaceNextMessageByFlow.delete(flowId);
+    return id;
+  };
+  const sendOrReplaceText = async (chatId: number, text: string, flowId?: string) => {
+    const replaceId = getReplaceIdForFlow(chatId, flowId);
+    if (replaceId !== undefined) {
+      await deps.transport.editText(chatId, replaceId, text);
+      return { message_id: replaceId };
+    }
+    const [sent] = await deps.transport.sendText(chatId, text);
+    return sent;
+  };
+  const sendOrReplaceButtons = async (chatId: number, text: string, rows: { text: string; value: string }[][], flowId?: string) => {
+    const replaceId = getReplaceIdForFlow(chatId, flowId);
+    if (replaceId !== undefined) {
+      await deps.transport.editButtons(chatId, replaceId, text, rows);
+      return { message_id: replaceId };
+    }
+    return deps.transport.sendButtons(chatId, text, rows);
+  };
+
+  /** Track the currently active flow for each chat (for sendOrReplace lookups). */
+  const activeFlowByChat = new Map<number, string>();
+
+  return {
+    create(chatId) {
+      const base = deps.getSession()?.extensionRunner.getUIContext?.();
+      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);
+        },
+        confirm: async (title, message) => {
+          const flowId = beginFlow();
+          activeFlowByChat.set(chatId, flowId);
+          const sent = await sendOrReplaceButtons(chatId, `<b>${escapeHtml(title)}</b>\n${escapeHtml(message)}`, [[
+            { text: "Yes", value: cb(flowId, "yes") }, { text: "No", value: cb(flowId, "no") }, { text: "Cancel", value: cb(flowId, "cancel") },
+          ]], flowId);
+          const value = await waitInput(chatId, flowId, false, false, sent.message_id);
+          activeFlowByChat.delete(chatId);
+          return value === true || value === "yes";
+        },
+        input: async (title, placeholder) => {
+          const flowId = beginFlow();
+          activeFlowByChat.set(chatId, flowId);
+          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);
+          return typeof value === "string" ? value : undefined;
+        },
+        inputSecret: async (title: string, placeholder?: string) => {
+          const flowId = beginFlow();
+          activeFlowByChat.set(chatId, flowId);
+          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);
+          return typeof value === "string" ? value : undefined;
+        },
+        editor: async (title, prefill) => {
+          const flowId = beginFlow();
+          activeFlowByChat.set(chatId, flowId);
+          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);
+          return typeof value === "string" ? value : undefined;
+        },
+        select: async (title, options) => {
+          if (options.length === 0) return undefined;
+          let page = 0; const pageCount = Math.ceil(options.length / PAGE_SIZE); const flowId = beginFlow();
+          activeFlowByChat.set(chatId, flowId);
+          while (true) {
+            const start = page * PAGE_SIZE; const pageOptions = options.slice(start, start + PAGE_SIZE);
+            const rows = pageOptions.map((label, i) => [{ text: truncateLabel(label), value: cb(flowId, `s:${start + i}`) }]);
+            const nav = [];
+            if (page > 0) nav.push({ text: "◀ Prev", value: cb(flowId, `p:${page - 1}`) });
+            if (page < pageCount - 1) nav.push({ text: "Next ▶", value: cb(flowId, `p:${page + 1}`) });
+            nav.push({ text: "Cancel", value: cb(flowId, "cancel") }); rows.push(nav);
+            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 (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; }
+            activeFlowByChat.delete(chatId);
+            return undefined;
+          }
+        },
+      };
+    },
+    resolveInput(chatId, raw, replyToMessageId, fromCallback = false) {
+      let flowId: string | undefined; let value = raw;
+      if (fromCallback && typeof raw === "string" && raw.startsWith("f:")) {
+        const [, id, ...rest] = raw.split(":"); flowId = id; const inner = rest.join(":");
+        value = inner === "yes" ? true : inner === "no" ? false : inner === "cancel" ? undefined : inner;
+      } else {
+        const map = pendingByChat.get(chatId);
+        const isCancel = raw === undefined;
+        if (replyToMessageId) {
+          flowId = map ? [...map.values()].find((p) =>
+            p.promptMessageId === replyToMessageId && (isCancel || p.acceptsText)
+          )?.flowId : undefined;
+          if (!flowId) return { handled: false };
+        } else {
+          flowId = isCancel ? latestFlow.get(chatId) : latestTextFlow.get(chatId);
+        }
+      }
+      if (!flowId) return { handled: false };
+      const pending = pendingByChat.get(chatId)?.get(flowId); if (!pending) return { handled: false };
+      if (fromCallback) {
+        if (replyToMessageId !== pending.promptMessageId) return { handled: false };
+      } else if (raw !== undefined && !pending.acceptsText) return { handled: false };
+      clearFlow(chatId, flowId);
+      // Store the per-flow replace target after clearing, so subsequent sendOrReplace* calls
+      // (e.g. pagination, notify) can edit the message instead of sending a new one.
+      if (fromCallback && replyToMessageId !== undefined) replaceNextMessageByFlow.set(flowId, replyToMessageId);
+      pending.resolve(value); return { handled: true, promptMessageId: pending.promptMessageId };
+    },
+    isSensitiveInput(chatId, replyToMessageId) {
+      const map = pendingByChat.get(chatId); if (!map) return false;
+      if (replyToMessageId) {
+        const exact = [...map.values()].find((p) => p.acceptsText && p.promptMessageId === replyToMessageId);
+        return exact?.sensitive === true;
+      }
+      const latest = latestTextFlow.get(chatId);
+      return latest ? map.get(latest)?.sensitive === true : false;
+    },
+    hasPendingInput(chatId) {
+      return (pendingByChat.get(chatId)?.size ?? 0) > 0;
+    },
+    dispose() {
+      for (const map of pendingByChat.values()) {
+        for (const pending of map.values()) {
+          clearTimeout(pending.timer);
+          pending.resolve(undefined);
+        }
+      }
+      pendingByChat.clear();
+      replaceNextMessageByFlow.clear();
+      latestTextFlow.clear();
+      latestFlow.clear();
+      activeFlowByChat.clear();
+    },
+  };
+}