@llblab/pi-telegram 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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

@@ -298,6 +298,42 @@ 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") {
+    // actual deletion logic
+    await ctx.answerCallback(`Deleted: ${ctx.payload}`);
+    return "handled";
+  }
+}
+```
+
+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/lib/extension-sections.ts

@@ -157,7 +157,7 @@ function buildTelegramSectionContext(
           chatId,
           view.text,
           view.parseMode ?? "html",
-          prependBackRow(view.replyMarkup, backCallback, backLabel),
+          view.replyMarkup ?? { inline_keyboard: [] },
         )
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
@@ -203,7 +203,7 @@ function buildTelegramSectionCallbackContext(
           chatId,
           view.text,
           view.parseMode ?? "html",
-          prependBackRow(view.replyMarkup, backCallback, backLabel),
+          view.replyMarkup ?? { inline_keyboard: [] },
         )
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,

package/package.json

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