@llblab/pi-telegram 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.10.2: Delete Message Port Hotfix
+
+- `[ctx.deleteMessage()]` Added `deleteMessage()` to `TelegramSectionContext` and `TelegramSectionCallbackContext`. Extensions can now delete the message that triggered a callback — useful for cleaning up confirmation dialogs after the user makes a choice.
+- `[API]` Added `deleteMessage` to `TelegramBridgeApiRuntime`, backed by Telegram's `deleteMessage` Bot API method with error recording.
+- `[Demo]` Confirmation dialog in `pi-telegram-extension-demo` now deletes itself on answer (`ctx.deleteMessage()`) and posts a follow-up result message (`ctx.open()`).
+- `[Docs]` Updated context port listings and interactive-messages section in `extension-sections.md` with `deleteMessage()`.
+
+## 0.10.1: Navigation Abstraction Hotfix
+
+- `[ctx.open()]` Removed automatic Back-row prepend from `ctx.open()`. `ctx.open()` sends a new message into the chat — a Back button makes no sense outside the menu. `ctx.edit()` still auto-prepends the correct navigation row for in-menu views.
+- `[Platform Docs]` Extended `docs/extension-sections.md` with a dedicated section on sending interactive messages into chat via `ctx.open()`: confirmation dialogs, approve/deny gates, and extension-driven button flows that live outside the menu hierarchy.
+
 ## 0.10.0: Extension Sections Platform
 
 - `[Extension Sections]` Implemented the Telegram Extension Sections platform: extensions can register structured UI sections that appear in the main Telegram application menu and Settings submenu without owning a second bot poller.

package/README.md

@@ -209,7 +209,7 @@ Unknown inline-button callbacks are forwarded to π as `[callback] <data>` when
 
 Ordinary pi extensions can register structured UI sections that appear in the main Telegram menu and Settings submenu without owning a second poller. Each section gets a narrow typed context with `edit`, `open`, `enqueuePrompt`, `answerCallback`, and `callbackData()` — enough to build interactive Telegram-native surfaces while `pi-telegram` owns transport, callback routing, navigation hierarchy, and diagnostics.
 
-Import from `@llblab/pi-telegram`, call `registerTelegramSection()`, and return a disposer on shutdown. See [`@llblab/pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) for a working reference and the [Extension Sections Standard](./docs/extension-sections.md) for the full contract.
+Import from `@llblab/pi-telegram`, call `registerTelegramSection()`, and return a disposer on shutdown. Sections can send interactive messages directly into the chat via `ctx.open()` — confirmation dialogs, approve/deny gates, and multi-step forms live outside the menu hierarchy while callbacks route through the same typed handler. See [`@llblab/pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) for a working reference and the [Extension Sections Standard](./docs/extension-sections.md) for the full contract.
 
 ### Proactive push
 

package/docs/extension-sections.md

@@ -260,6 +260,8 @@ interface TelegramSectionContext {
   enqueuePrompt(prompt: string): Promise<void>;
   /** Build a section-namespaced callback_data string */
   callbackData(action: string, payload?: string): string;
+  /** Delete the message that triggered this callback */
+  deleteMessage(): Promise<void>;
 }
 ```
 
@@ -279,6 +281,8 @@ interface TelegramSectionCallbackContext {
   open(view: TelegramSectionView): Promise<void>;
   enqueuePrompt(prompt: string): Promise<void>;
   callbackData(action: string, payload?: string): string;
+  /** Delete the message that triggered this callback */
+  deleteMessage(): Promise<void>;
 }
 ```
 
@@ -298,6 +302,46 @@ Context ports are intentionally narrow. Sections **cannot**:
 
 Add capability-specific ports only when the first real extension proves the need.
 
+### Interactive messages in chat (`ctx.open`)
+
+`ctx.open()` sends a new message directly into the Telegram chat — outside the menu hierarchy. No Back row is prepended. Use it for extension-driven interactions that live in the conversation:
+
+- Confirmation dialogs ("Delete file.txt?")
+- Approve/deny gates ("Allow tool execution?")
+- Multi-step forms that should not be menu-bound
+- Status reports with action buttons
+
+```ts
+handleCallback: async (ctx) => {
+  if (ctx.action === "delete-file") {
+    await ctx.open({
+      text: `<b>Delete ${ctx.payload}?</b>\n\nThis cannot be undone.`,
+      parseMode: "html",
+      replyMarkup: {
+        inline_keyboard: [[
+          { text: "✅ Yes, delete",
+            callback_data: ctx.callbackData("confirm-delete", ctx.payload) },
+          { text: "❌ Cancel",
+            callback_data: ctx.callbackData("cancel") },
+        ]],
+      },
+    });
+    return "handled";
+  }
+  if (ctx.action === "confirm-delete") {
+    await ctx.deleteMessage();
+    await ctx.answerCallback(`Deleted: ${ctx.payload}`);
+    return "handled";
+  }
+  if (ctx.action === "cancel") {
+    await ctx.deleteMessage();
+    return "handled";
+  }
+}
+```
+
+`ctx.deleteMessage()` removes the dialog from chat after the user makes a choice. Callbacks from chat buttons route through the same `handleCallback` — the same `ctx.callbackData()` works regardless of where the button lives. The extension owns its callback namespace; the bridge owns transport.
+
 ## 10. Telegram Bot API Integration
 
 ### `callback_data` contract

package/index.ts

@@ -157,6 +157,7 @@ export default function (pi: Pi.ExtensionAPI) {
     editMessageText: editTelegramMessageText,
     answerCallbackQuery,
     answerGuestQuery,
+    deleteMessage: deleteTelegramMessage,
     prepareTempDir,
   } = Api.createDefaultTelegramBridgeApiRuntime({
     getBotToken: configStore.getBotToken,
@@ -354,6 +355,7 @@ export default function (pi: Pi.ExtensionAPI) {
     answerCallbackQuery,
     editInteractiveMessage,
     sendInteractiveMessage,
+    deleteMessage: deleteTelegramMessage,
     answerGuestQuery,
     sendTextReply,
     setMyCommands,

package/lib/api.ts

@@ -323,6 +323,7 @@ export interface TelegramBridgeApiRuntime {
     text?: string,
     options?: { parseMode?: string },
   ) => Promise<void>;
+  deleteMessage: (chatId: number, messageId: number) => Promise<void>;
   prepareTempDir: () => Promise<number>;
 }
 
@@ -668,6 +669,21 @@ export async function answerTelegramCallbackQuery(
   }
 }
 
+export async function deleteTelegramMessage(
+  botToken: string | undefined,
+  chatId: number,
+  messageId: number,
+): Promise<void> {
+  try {
+    await callTelegram<boolean>(botToken, "deleteMessage", {
+      chat_id: chatId,
+      message_id: messageId,
+    });
+  } catch {
+    // ignore
+  }
+}
+
 export function createTelegramChatActionSender<TAction extends string>(
   sendChatAction: (chatId: number, action: TAction) => Promise<unknown>,
   action: TAction,
@@ -817,6 +833,11 @@ export function createTelegramBridgeApiRuntime(
     },
     prepareTempDir: () =>
       prepareTelegramTempDir(deps.tempDir, deps.tempFileMaxAgeMs),
+    deleteMessage: (chatId, messageId) =>
+      callRecorded<boolean>("deleteMessage", {
+        chat_id: chatId,
+        message_id: messageId,
+      }).then(() => {}),
   };
 }
 

package/lib/extension-sections.ts

@@ -52,6 +52,8 @@ export interface TelegramSectionContext {
   open(view: TelegramSectionView): Promise<void>;
   enqueuePrompt(prompt: string): Promise<void>;
   callbackData(action: string, payload?: string): string;
+  /** Delete the message that triggered this callback (dialog cleanup) */
+  deleteMessage(): Promise<void>;
 }
 
 export interface TelegramSectionCallbackContext {
@@ -65,6 +67,8 @@ export interface TelegramSectionCallbackContext {
   open(view: TelegramSectionView): Promise<void>;
   enqueuePrompt(prompt: string): Promise<void>;
   callbackData(action: string, payload?: string): string;
+  /** Delete the message that triggered this callback (dialog cleanup) */
+  deleteMessage(): Promise<void>;
 }
 
 export interface RegisteredTelegramSection {
@@ -121,6 +125,7 @@ export interface TelegramSectionRuntimeDeps {
     replyMarkup: TelegramInlineKeyboardMarkup,
   ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;
+  deleteMessage: (chatId: number, messageId: number) => Promise<void>;
 }
 
 function buildTelegramSectionContext(
@@ -157,7 +162,7 @@ function buildTelegramSectionContext(
           chatId,
           view.text,
           view.parseMode ?? "html",
-          prependBackRow(view.replyMarkup, backCallback, backLabel),
+          view.replyMarkup ?? { inline_keyboard: [] },
         )
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
@@ -165,6 +170,10 @@ function buildTelegramSectionContext(
       payload
         ? `section:${token}:${action}:${payload}`
         : `section:${token}:${action}`,
+    deleteMessage: () =>
+      messageId !== undefined
+        ? deps.deleteMessage(chatId, messageId)
+        : Promise.resolve(),
   };
 }
 
@@ -203,7 +212,7 @@ function buildTelegramSectionCallbackContext(
           chatId,
           view.text,
           view.parseMode ?? "html",
-          prependBackRow(view.replyMarkup, backCallback, backLabel),
+          view.replyMarkup ?? { inline_keyboard: [] },
         )
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
@@ -211,6 +220,10 @@ function buildTelegramSectionCallbackContext(
       payload
         ? `section:${token}:${action}:${payload}`
         : `section:${token}:${action}`,
+    deleteMessage: () =>
+      messageId !== undefined
+        ? deps.deleteMessage(chatId, messageId)
+        : Promise.resolve(),
   };
 }
 
@@ -402,6 +415,7 @@ export interface TelegramSectionCallbackHandlerDeps {
     replyMarkup: TelegramInlineKeyboardMarkup,
   ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;
+  deleteMessage: (chatId: number, messageId: number) => Promise<void>;
 }
 
 export async function handleTelegramSectionOpen(

package/lib/menu.ts

@@ -238,6 +238,7 @@ export interface TelegramMenuCallbackRuntimeDeps<
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<number | undefined>;
   enqueueSectionPrompt?: (prompt: string, ctx: TContext) => Promise<void>;
+  deleteMessage?: (chatId: number, messageId: number) => Promise<void>;
 }
 
 export interface TelegramMenuActionRuntimeDeps<
@@ -471,6 +472,7 @@ export interface TelegramMenuCallbackRuntimeAdapterDeps<
     replyMarkup: TelegramReplyMarkup,
   ) => Promise<number | undefined>;
   enqueueSectionPrompt?: (prompt: string, ctx: TContext) => Promise<void>;
+  deleteMessage?: (chatId: number, messageId: number) => Promise<void>;
 }
 
 export function createTelegramMenuCallbackHandler<
@@ -514,6 +516,7 @@ export function createTelegramMenuCallbackHandlerForContext<
     editInteractiveMessage: deps.editInteractiveMessage,
     sendInteractiveMessage: deps.sendInteractiveMessage,
     enqueueSectionPrompt: deps.enqueueSectionPrompt,
+    deleteMessage: deps.deleteMessage,
   });
 }
 
@@ -570,6 +573,7 @@ export async function handleTelegramMenuCallbackRuntime<
               enqueuePrompt: deps.enqueueSectionPrompt
                 ? (prompt: string) => deps.enqueueSectionPrompt!(prompt, ctx)
                 : async () => {},
+              deleteMessage: deps.deleteMessage ?? (async () => {}),
             },
           );
           if (handled) return;
@@ -590,6 +594,7 @@ export async function handleTelegramMenuCallbackRuntime<
                 enqueuePrompt: deps.enqueueSectionPrompt
                   ? (prompt: string) => deps.enqueueSectionPrompt!(prompt, ctx)
                   : async () => {},
+                deleteMessage: deps.deleteMessage ?? (async () => {}),
               },
             );
             if (handled) return;
@@ -612,6 +617,7 @@ export async function handleTelegramMenuCallbackRuntime<
               enqueuePrompt: deps.enqueueSectionPrompt
                 ? (prompt: string) => deps.enqueueSectionPrompt!(prompt, ctx)
                 : async () => {},
+              deleteMessage: deps.deleteMessage ?? (async () => {}),
             },
           );
           if (handled) return;

package/lib/routing.ts

@@ -96,6 +96,7 @@ export interface TelegramInboundRouteRuntimeDeps<
     mode: "html" | "plain",
     replyMarkup: Menu.TelegramReplyMarkup,
   ) => Promise<number | undefined>;
+  deleteMessage?: (chatId: number, messageId: number) => Promise<void>;
   answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
   sendTextReply: (
     chatId: number,
@@ -193,6 +194,7 @@ export function createTelegramInboundRouteRuntime<
     sectionRegistry: deps.sectionRegistry,
     editInteractiveMessage: deps.editInteractiveMessage,
     sendInteractiveMessage: deps.sendInteractiveMessage,
+    deleteMessage: deps.deleteMessage,
     enqueueSectionPrompt: async (prompt: string, ctx: TContext) => {
       const chatId = deps.configStore.getAllowedUserId();
       if (typeof chatId !== "number") return;

package/package.json

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