@llblab/pi-telegram 0.9.4 → 0.9.5

package/AGENTS.md

@@ -7,6 +7,7 @@
 - `Boundary Clarity`: Separate Telegram transport concerns, π integration concerns, rendering behavior, and release/documentation state
 - `Progressive Enhancement + Graceful Degradation`: Prefer behavior that upgrades automatically when richer runtime context exists, but always preserves a useful fallback path when it does not
 - `Runtime Safety`: Prefer queue and rendering behavior that fails predictably over clever behavior that can desynchronize the Telegram bridge from π session state
+- `Pi-Native Extensibility`: `pi-telegram` should inherit π's own extension philosophy. It is not only a Telegram adapter; it should become a small, convenient, composable Telegram shell for π extensions, where new capabilities plug into stable contracts instead of forking polling, transport, or menu ownership.
 
 ## 1. Concept
 

package/BACKLOG.md

@@ -2,4 +2,9 @@
 
 ## Open Work
 
-No open work.
+- Implement Telegram Extension Sections Platform for the 0.10.0 line.
+  - Exit: Runtime registry, main-menu integration, `section:` callback routing, safe section context ports, diagnostics, docs, and at least one small demo/fixture prove ordinary pi extensions can add Telegram menu sections without owning a second poller.
+- Explore always-available outbound Telegram tools for queued artifacts and controls.
+  - Priority: Low.
+  - Idea: Provide tools such as `telegram_attach_file` and `telegram_attach_button` that can be called outside an active Telegram turn, using the paired chat/session as the delivery target when safe.
+  - Exit: Design note defines active-turn versus ambient delivery semantics, safety constraints, failure modes, and whether the current `telegram_attach` contract should stay turn-scoped or gain an ambient companion.

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.9.5: Telegram Delivery Resilience Hotfix
+
+- `[Preview Delivery]` Preview flush failures from Telegram transport errors such as `fetch failed` / `ECONNRESET` are now caught and recorded as runtime diagnostics instead of escaping from the preview pipeline. Impact: transient Telegram connectivity failures no longer crash the extension during streamed preview edits.
+- `[Final Delivery]` Final Markdown preview replacement now catches Telegram transport failures and returns a normal fallback signal; the agent-end delivery path records final-text delivery failures and continues cleanup, attachment handling, and queue dispatch. Impact: a failed `editMessageText` at `agent_end` no longer breaks the bridge lifecycle or blocks the next queued Telegram turn.
+- `[Diagnostics]` Preview and final delivery failures now flow through the runtime event recorder with compact phase metadata. Impact: `/telegram-status` can show recent transport failures without dumping noisy stack traces into the extension runner.
+- `[Tests]` Added preview and queue regressions for non-fatal Telegram transport failures during preview flush and final delivery.
+- `[Extension Sections Draft]` Added a draft design note for pi-native Telegram extension sections, reserved the future `section:` callback prefix, linked the draft from docs, and recorded the project philosophy that `pi-telegram` should inherit π's extensibility model as a shared Telegram shell for loaded extensions. Impact: the future 0.10.0 extension platform direction is documented without exposing a stable API yet.
+- `[Docs Formatting]` Normalized project Markdown so prose paragraphs stay as single logical lines and Markdown tables remain narrow instead of using artificial hard wraps. Impact: editors and viewers can handle visual wrapping naturally while fixed-width structures stay readable.
+- `[Settings Copy]` Tightened the proactive-push settings text by removing redundant persistence/default wording.
+
 ## 0.9.4: Temp Dir And Command Template Hotfix
 
 - `[Telegram Temp Dir]` Default Telegram API temp files now respect `PI_CODING_AGENT_DIR`, falling back to `~/.pi/agent` when the env var is unset. Impact: sandboxed or relocated agent dirs no longer force Telegram downloads through the default home-directory path.

package/README.md

@@ -87,8 +87,8 @@ Use these inside the Telegram DM with your bot:
 - **`/compact`**: Start session compaction (only works when the session is idle).
 - **`/next`**: Dispatch the next queued turn (aborts π first if busy).
 - **`/continue`**: Enqueue a priority `continue` prompt. It waits like normal Telegram work when π is busy and can trigger prompt/skill handling that listens for `continue`.
-- **`/stop`**: Abort the active run and clear all waiting Telegram queue items.
 - **`/abort`**: Abort the active run without touching the queue.
+- **`/stop`**: Abort the active run and clear all waiting Telegram queue items.
 
 Prompt-template commands: π prompt templates are mapped to Telegram-safe aliases (`fix-tests.md` becomes `/fix_tests`) and shown as compact command-only rows between the built-in commands and status rows in `/start`. They are not registered in the Telegram bot command menu, keeping the bot menu focused on bridge controls. Sending `/template_name args` from Telegram expands the matching π prompt-template file and queues the expanded prompt like normal Telegram work.
 

package/docs/README.md

@@ -11,3 +11,4 @@ Living index of project documentation in `/docs`.
 - [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership
 - [callback-namespaces.md](./callback-namespaces.md) — Shared Telegram `callback_data` namespace standard for layered extensions
 - [external-handlers.md](./external-handlers.md) — Runtime interceptor registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection
+- [extension-sections.md](./extension-sections.md) — Draft Telegram Extension Sections Standard for external menu sections and structured Telegram UI extension points

package/docs/architecture.md

@@ -23,29 +23,28 @@ Naming rule: because the repository already scopes this codebase to Telegram, ex
 
 Current runtime areas use these ownership boundaries:
 
-| Domain                                                                                                          | Owns                                                                                                                                                                                                                                                |
-| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `index.ts`                                                                                                      | Single composition root for live π/Telegram ports, session state, API-bound transport adapters, and status updates                                                                                                                                  |
-| `api`                                                                                                           | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording                                                                                         |
-| `config` / `setup`                                                                                              | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence                                                                                                               |
-| `locks` / `polling`                                                                                             | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring                                                                                                       |
-| `updates` / `routing`                                                                                           | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition                                                                                                                          |
-| `media` / `text-groups` / `turns` / `inbound-handlers`                                                          | Text/media extraction, media-group debounce, long-text split coalescing, inbound downloads, inbound text/media handler execution, turn building/editing, image reads, legacy `attachmentHandlers` compatibility                                     |
-| `queue`                                                                                                         | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing                                                                                   |
-| `runtime`                                                                                                       | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding                                                                                    |
-| `model` / `menu-model` / `menu-thinking` / `menu-status` / `menu` / `menu-queue` / `menu-settings` / `commands` | Model identity/thinking levels, scoped model resolution, in-flight switching, model-menu UI, thinking-menu UI, status-menu UI, inline application callback composition, queue-menu UI, hidden settings UI, slash commands, bot command registration |
-| `keyboard`                                                                                                      | Shared Telegram inline-keyboard reply-markup structure; feature domains own callback semantics and button construction                                                                                                                              |
-| `preview` / `replies` / `rendering`                                                                             | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots                                                                                                       |
-| `outbound-handlers`                                                                                             | Outbound text transformation, assistant-authored outbound comments, generated reply artifacts, inline-keyboard callbacks, and post-`agent_end` outbound action delivery                                                                             |
-| `outbound-attachments`                                                                                          | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification                                                                                                                             |
-| `status`                                                                                                        | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped π diagnostics                                                                                                                                    |
-| `lifecycle` / `prompts` / `prompt-templates` / `pi`                                                             | π hook registration, Telegram-specific before-agent prompt injection, π prompt-template discovery/expansion, centralized direct pi SDK imports and context adapters                                                                                 |
-| `command-templates`                                                                                             | Portable shell-free command-template standard helpers, composition expansion, placeholder substitution, and executable resolution                                                                                                                   |
+- `index.ts`: single composition root for live π/Telegram ports, session state, API-bound transport adapters, and status updates.
+- `api`: Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, and runtime error recording.
+- `config` / `setup`: persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, and config persistence.
+- `locks` / `polling`: singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, and poll-loop runtime wiring.
+- `updates` / `routing`: update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition.
+- `media` / `text-groups` / `turns` / `inbound-handlers`: text/media extraction, media-group debounce, long-text split coalescing, inbound downloads, inbound text/media handler execution, turn building/editing, image reads, and legacy `attachmentHandlers` compatibility.
+- `queue`: queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, and session/agent/tool lifecycle sequencing.
+- `runtime`: session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, and agent-end reset binding.
+- `model` / `menu-model` / `menu-thinking` / `menu-status` / `menu` / `menu-queue` / `menu-settings` / `commands`: model identity/thinking levels, scoped model resolution, in-flight switching, model/thinking/status/queue/settings menu UI, inline application callback composition, slash commands, and bot command registration.
+- Future `extension-sections`: structured external Telegram menu sections registered by ordinary pi extensions; owns section registry, compact section callback tokens, section render/callback dispatch, safe section runtime ports, and diagnostics.
+- `keyboard`: shared Telegram inline-keyboard reply-markup structure; feature domains own callback semantics and button construction.
+- `preview` / `replies` / `rendering`: preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, and stable-preview snapshots.
+- `outbound-handlers`: outbound text transformation, assistant-authored outbound comments, generated reply artifacts, inline-keyboard callbacks, and post-`agent_end` outbound action delivery.
+- `outbound-attachments`: `telegram_attach` registration, outbound attachment queueing, stat/limit checks, and photo/document delivery classification.
+- `status`: status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, and grouped π diagnostics.
+- `lifecycle` / `prompts` / `prompt-templates` / `pi`: π hook registration, Telegram-specific before-agent prompt injection, π prompt-template discovery/expansion, and centralized direct pi SDK imports/context adapters.
+- `command-templates`: portable shell-free command-template standard helpers, composition expansion, placeholder substitution, and executable resolution.
 
 Boundary invariants:
 
 - Constants and state types live with their owning domains; do not reintroduce shared buckets such as `lib/constants.ts` or `lib/types.ts`
-- Shared Telegram inline-keyboard structure belongs to `keyboard`; application-control labels, callback data, and callback behavior stay in `menu`/`menu-model`/`menu-thinking`/`menu-status`/`menu-queue`; core queue mechanics stay in `queue`
+- Shared Telegram inline-keyboard structure belongs to `keyboard`; application-control labels, callback data, and callback behavior stay in `menu`/`menu-model`/`menu-thinking`/`menu-status`/`menu-queue`; future external section labels, callbacks, and dispatch stay in `extension-sections`; core queue mechanics stay in `queue`
 - Domain helpers use narrow structural projections when that avoids importing concrete wire DTOs or broader runtime objects unnecessarily
 - Preview appearance stays in `rendering`; preview transport/lifecycle stays in `preview`
 - Direct `node:*` file-operation imports stay in owning domains, not in `index.ts`
@@ -95,13 +94,11 @@ Queued items now use two explicit dimensions:
 
 Admission contract:
 
-| Admission             | Examples                                                     | Queue shape                                                                                                                                              | Dispatch rank                               |
-| --------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| Immediate execution   | `/compact`, `/queue`, `/stop`, `/help`, `/start`             | Does not enter the Telegram queue; `/help` opens the same menu as `/start`; `/stop` also clears queued items                                             | N/A                                         |
-| Queued prompt command | `/continue`, `/template_name args`                           | `/continue` enqueues a Telegram-owned `continue` prompt; prompt-template commands expand the matching π template before entering the normal prompt queue | priority for `/continue`, otherwise default |
-| Control queue         | Model-switch continuation turns and future deferred controls | `queueLane: control`; accepts control items and continuation prompts                                                                                     | 0                                           |
-| Priority prompt queue | A waiting prompt promoted by `👍`, `⚡️`, `❤️`, `🕊`, or `🔥` | `kind: prompt`, `queueLane: priority`                                                                                                                    | 1                                           |
-| Default prompt queue  | Normal Telegram text/media turns                             | `kind: prompt`, `queueLane: default`                                                                                                                     | 2                                           |
+- Immediate execution: `/compact`, `/queue`, `/stop`, `/help`, and `/start` do not enter the Telegram queue. `/help` opens the same menu as `/start`; `/stop` also clears queued items. Dispatch rank: N/A.
+- Queued prompt command: `/continue` enqueues a priority Telegram-owned `continue` prompt. Prompt-template commands such as `/template_name args` expand the matching π template before entering the normal prompt queue. Dispatch rank: priority for `/continue`, otherwise default.
+- Control queue: model-switch continuation turns and future deferred controls use `queueLane: control`, accept control items and continuation prompts, and dispatch at rank `0`.
+- Priority prompt queue: a waiting prompt promoted by `👍`, `⚡️`, `❤️`, `🕊`, or `🔥` uses `kind: prompt`, `queueLane: priority`, and dispatches at rank `1`.
+- Default prompt queue: normal Telegram text/media turns use `kind: prompt`, `queueLane: default`, and dispatch at rank `2`.
 
 The command action itself carries its execution mode, and the queue domain exposes lane contracts for admission mode, dispatch rank, and allowed item kinds. Queue append and planning paths validate lane admission so a malformed control/default or other invalid lane pairing fails predictably instead of silently changing priority. This lets synthetic control actions and Telegram prompts share one stable ordering model while still rendering distinctly in status output. In the π status bar, busy labels distinguish `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`; priority prompts and priority control items are marked with `⚡`. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, the status remains yellow `active` instead of degrading to green `connected`.
 
@@ -160,7 +157,7 @@ Telegram prompt responses use explicit delivery context to attach outbound text,
 
 Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, are staged atomically per tool call, are checked against a default 50 MiB limit configurable through `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 
-Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes body text, `text="..."`, or colon shorthand through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, the default command timeout applies automatically, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. Unknown callback data that does not match pi-telegram-owned prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) is forwarded to π as `[callback] <data>` after built-in handlers decline it, giving layered extensions a simple namespaced button channel without separate polling; layered callback payloads should follow the [Callback Namespace Standard](./callback-namespaces.md). When proactive push is enabled, successful local non-Telegram final replies are sent to the paired chat. Local prompt text is not sent because the bot does not own or mirror terminal user messages. This keeps terminal-originated results visible in Telegram without changing Telegram-originated turn delivery.
+Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes body text, `text="..."`, or colon shorthand through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, the default command timeout applies automatically, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. Unknown callback data that does not match pi-telegram-owned prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, future `section:`) is forwarded to π as `[callback] <data>` after built-in handlers decline it, giving layered extensions a simple namespaced button channel without separate polling; layered callback payloads should follow the [Callback Namespace Standard](./callback-namespaces.md). Future structured menu integrations should use the [Telegram Extension Sections Standard](./extension-sections.md) instead of hand-rolled fallback callbacks. When proactive push is enabled, successful local non-Telegram final replies are sent to the paired chat. Local prompt text is not sent because the bot does not own or mirror terminal user messages. This keeps terminal-originated results visible in Telegram without changing Telegram-originated turn delivery.
 
 This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools. Telegram prompt guidance targets about 37 visible cells for tables, dense list items, and compact text blocks because emoji and other wide glyphs make raw character counts misleading on mobile screens.
 

package/docs/callback-namespaces.md

@@ -20,7 +20,7 @@ myext:page:2
 
 - Use a stable extension-owned namespace, preferably the package or extension name without scope punctuation.
 - Keep the namespace lowercase ASCII: `a-z`, `0-9`, `_`, `-`.
-- Do not use `pi-telegram` owned prefixes: `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`. Current app navigation uses `menu:`; `status:` remains reserved for legacy/owned status callbacks but is not emitted by current UI.
+- Do not use `pi-telegram` owned prefixes: `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `section:`. Current app navigation uses `menu:`; `status:` remains reserved for legacy/owned status callbacks but is not emitted by current UI. `section:` is reserved for the structured extension-section router documented in [Extension Sections](./extension-sections.md).
 - Keep the full `callback_data` within Telegram's 64-byte limit.
 - Put only opaque ids or small enum values in payloads; do not store secrets, full prompts, or large state.
 - Treat callbacks as untrusted input. Validate namespace, action, and payload before executing side effects.
@@ -34,3 +34,15 @@ If `pi-telegram` receives callback data that is not owned by its built-in prefix
 ```
 
 Layered extensions may intercept that message and handle their own namespace. If no extension handles it, the assistant may see the fallback message and should tell the user the callback was not handled and the environment may be misconfigured.
+
+## Extension sections
+
+[Telegram Extension Sections](./extension-sections.md) are a higher-level UI contract over this namespace rule. A section owns a canonical extension identity such as `@llblab/pi-telegram-explorer`, but its Telegram `callback_data` should use the `pi-telegram` owned `section:` prefix plus a compact token, because Telegram limits callback payloads to 64 bytes.
+
+Conceptual form:
+
+```text
+section:<token>:<action>[:<payload>]
+```
+
+The token maps back to the full section identity inside the section registry. Section authors should not hand-roll `section:` callbacks outside the section context helpers, and ordinary layered extensions should continue using their own namespace plus external handlers or the `[callback]` fallback.

package/docs/extension-sections.md

@@ -0,0 +1,293 @@
+# Telegram Extension Sections Standard Draft
+
+**Status:** Draft. This document is a design note for the upcoming Extension Sections platform and is not an implemented or stable public API yet. Treat all names, shapes, and examples as provisional until the implementation lands.
+
+**Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
+
+---
+
+Telegram Extension Sections are a proposed registration contract that lets ordinary pi extensions add structured UI sections to the `pi-telegram` inline application menu.
+
+The guiding philosophy is pi-native extensibility: `pi-telegram` should inherit π's own model of small composable extensions. The bridge should act as a shared Telegram shell for loaded π extensions, not as a closed one-off bot or a place where every feature must fork Telegram polling and transport.
+
+They are not a new extension loader. pi still loads extensions through its normal TypeScript/package system. A loaded extension registers a Telegram section with `pi-telegram`; `pi-telegram` owns bot polling, menu rendering, callback routing, Telegram authorization, and message lifecycle.
+
+## Purpose
+
+Use sections when an extension needs a Telegram-native UI surface inside the existing bot shell:
+
+- File or project explorers
+- Prompt/session history viewers
+- Tool approval dashboards
+- Runtime status panels
+- Extension settings or diagnostics
+- Human-in-the-loop forms that should not become agent turns
+
+Do not use sections for plain agent prompts, one-shot buttons authored by the assistant, or command-template pipelines. Those stay in the normal queue, outbound action comments, inbound/outbound handlers, or command-template domains.
+
+## Identity key
+
+Each section has one stable identity key.
+
+Use the same identity rules as the Extension Locks Standard:
+
+1. `package.json/name` for npm-style pi packages
+2. Directory name when the extension entrypoint is `index.ts` but there is no package name
+3. File basename when the extension is a single file
+
+For npm-style package extensions, the canonical value is the `package.json` `name`.
+
+Examples:
+
+```text
+extensions/pi-telegram-explorer/package.json name=@llblab/pi-telegram-explorer -> @llblab/pi-telegram-explorer
+extensions/pi-telegram-explorer/index.ts without package.json              -> pi-telegram-explorer
+extensions/pi-telegram-explorer.ts                                         -> pi-telegram-explorer
+```
+
+The section `id` is also the owner identity. Do not add a separate `owner` field unless a later concrete need appears.
+
+The identity key is used for:
+
+- Registry ownership
+- Conflict detection
+- Diagnostics
+- Cleanup
+- Callback routing lookup
+- Future capability policy
+
+## Registration shape
+
+Minimum shape:
+
+```ts
+registerTelegramSection({
+  id: "@llblab/pi-telegram-explorer",
+  label: "🗂 Explorer",
+  render(ctx) {
+    return {
+      text: "<b>Explorer</b>",
+      parseMode: "html",
+      replyMarkup,
+    };
+  },
+  handleCallback(ctx) {
+    return "handled";
+  },
+});
+```
+
+Recommended TypeScript shape:
+
+```ts
+type TelegramSectionId = string;
+type TelegramSectionCallbackResult = "handled" | "pass";
+
+interface TelegramSectionRegistration {
+  id: TelegramSectionId;
+  label: string;
+  order?: number;
+  render: (
+    ctx: TelegramSectionRenderContext,
+  ) => TelegramSectionView | Promise<TelegramSectionView>;
+  handleCallback?: (
+    ctx: TelegramSectionCallbackContext,
+  ) => TelegramSectionCallbackResult | Promise<TelegramSectionCallbackResult>;
+}
+
+interface TelegramSectionView {
+  text: string;
+  parseMode?: "html" | "plain";
+  replyMarkup?: TelegramInlineKeyboardMarkup;
+}
+```
+
+Registration returns a disposer:
+
+```ts
+const unregister = registerTelegramSection(section);
+unregister();
+```
+
+## Loading model
+
+Sections are registered by normal pi extensions:
+
+```ts
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerTelegramSection } from "@llblab/pi-telegram/lib/extension-sections.ts";
+
+export default function (pi: ExtensionAPI) {
+  const unregister = registerTelegramSection({
+    id: "@llblab/pi-telegram-explorer",
+    label: "🗂 Explorer",
+    render: async (ctx) => ctx.html("<b>Explorer</b>"),
+  });
+  pi.on("shutdown", () => unregister());
+}
+```
+
+`pi-telegram` may expose a typed import and a zero-coupling `globalThis` registry. The typed import is the preferred authoring path. The global registry exists only to tolerate load order and package coupling constraints.
+
+## Menu integration
+
+`pi-telegram` owns the main Telegram application menu.
+
+Registered sections appear as top-level menu rows after built-in core sections unless an `order` value says otherwise.
+
+Rules:
+
+- `label` must be compact enough for mobile Telegram
+- Built-in sections keep priority over external sections
+- Duplicate `id` registration is rejected or replaces only the same live owner through an explicit disposer path
+- Section errors must not break the whole main menu
+- If a section fails to render, `pi-telegram` should show a compact error row or omit the section and record diagnostics
+
+## Callback routing
+
+`pi-telegram` owns section callback transport.
+
+A section callback must include a `pi-telegram` owned prefix plus a compact section token that maps back to the full identity key.
+
+Conceptual form:
+
+```text
+section:<token>:<action>:<payload>
+```
+
+The token is an implementation detail. The registry maps it to the canonical section `id`. `section:` is reserved in the [Callback Namespace Standard](./callback-namespaces.md); section authors should build callbacks through section context helpers rather than hand-crafting `section:` payloads.
+
+Routing order:
+
+1. Telegram update arrives through the single `pi-telegram` poller
+2. Existing low-level external handlers may observe or consume the update first
+3. Built-in menu callbacks are handled by built-in domains
+4. Section callbacks are resolved by token and sent to the registered section
+5. Unknown callbacks fall back to the existing callback namespace behavior when appropriate
+
+Section handlers return:
+
+- `"handled"` — callback was handled, do not continue routing
+- `"pass"` — section declines this callback, allow fallback routing
+
+Stale callbacks:
+
+- Missing section id or token should answer the callback with a short stale/expired notice
+- Missing target state should re-render the section root when possible
+- Section errors should be caught, surfaced as a short callback answer, and recorded in diagnostics
+
+## Runtime ports
+
+A section receives a narrow context, not raw `pi-telegram` internals.
+
+Initial safe ports:
+
+```ts
+interface TelegramSectionContext {
+  sectionId: string;
+  chatId: number;
+  messageId?: number;
+  answerCallback(text?: string): Promise<void>;
+  edit(view: TelegramSectionView): Promise<void>;
+  open(view: TelegramSectionView): Promise<void>;
+  enqueuePrompt(prompt: string): Promise<void>;
+  getQueueSnapshot(): TelegramQueueSnapshot;
+  getSessionSnapshot?(): TelegramSessionSnapshot;
+}
+```
+
+Filesystem or prompt-history mutation is not part of the baseline. Add capability-specific ports only when the first real extension needs them.
+
+## Security and authorization
+
+`pi-telegram` keeps Telegram authorization ownership.
+
+Baseline rules:
+
+- Section callbacks are accepted only from the paired/authorized Telegram user
+- Sections should not receive unauthorized updates
+- Sections must not start their own Telegram poller
+- Sections must not assume filesystem or session mutation rights
+- Sensitive capabilities should be exposed as explicit typed ports, not by passing raw process or bot clients
+
+For filesystem explorers, default to read-only browse and file-send behavior. Deleting, writing, shell execution, or rollback-like mutations require separate explicit capabilities and confirmation UI.
+
+## Diagnostics
+
+`pi-telegram` should be able to report registered sections.
+
+Minimum diagnostic fields:
+
+```text
+id
+label
+status: active | stale | error
+lastError
+```
+
+The identity key is sufficient as the owner label. Do not add a second owner field.
+
+Useful future fields:
+
+```text
+registeredAt
+lastRenderAt
+lastCallbackAt
+callbackCount
+errorCount
+capabilities
+```
+
+Diagnostics should be available through a status/debug surface without cluttering normal Telegram UI.
+
+## Relationship to callback namespaces and external handlers
+
+[Callback Namespaces](./callback-namespaces.md) define callback ownership names. [External Handlers](./external-handlers.md) define low-level raw update interception. Extension sections define the structured Telegram UI layer above both.
+
+Sections still use namespaced callback data, but `pi-telegram` owns the `section:` prefix and maps compact tokens to canonical section identities. That keeps Telegram's 64-byte callback limit compatible with full npm package names such as `@llblab/pi-telegram-explorer`.
+
+Use external handlers when an extension needs direct raw Telegram update access, a custom callback namespace, or out-of-band Promise resolution.
+
+Use extension sections when an extension needs a durable menu surface, callback routing, and Telegram UI lifecycle managed by `pi-telegram`.
+
+## Relationship to command templates
+
+Command templates execute local commands and pipelines through stdin/stdout.
+
+Extension sections do not execute command templates by default. A section may call an extension-owned command or tool internally, but the section standard is a UI registration and callback-routing contract, not a shell execution contract.
+
+## Non-goals
+
+- No second Telegram poller
+- No new pi extension loader
+- No generic webview system
+- No default filesystem mutation API
+- No prompt rollback semantics in the base standard
+- No separate owner field while identity key is sufficient
+
+## Evolution path
+
+0.10.0 minimum:
+
+- Section registry
+- Main menu integration
+- Section callback routing
+- Narrow runtime ports
+- Diagnostics for registered sections
+- Documentation for extension authors
+
+First demo extension candidate:
+
+```text
+@llblab/pi-telegram-explorer
+```
+
+Initial demo scope:
+
+- Browse current project tree read-only
+- View compact file previews
+- Send selected files as Telegram documents
+- Browse recent prompt/session snapshots read-only
+- Enqueue a prompt derived from a selected item
+
+Defer rollback, filesystem writes, deletes, and broad mutation until the read-only and enqueue-only model is proven.

package/docs/external-handlers.md

@@ -1,60 +1,38 @@
 # External Handlers
 
-`pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other
-pi extensions cannot open a competing poller against the same bot — the
-Telegram Bot API uses a per-bot `offset` cursor, and two pollers race each
-other and lose updates.
+`pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other pi extensions cannot open a competing poller against the same bot — the Telegram Bot API uses a per-bot `offset` cursor, and two pollers race each other and lose updates.
 
-This document describes the registry that lets layered pi extensions
-(running in the same pi process) hook into `pi-telegram`'s polling loop and
-react to inbound Telegram updates **before** `pi-telegram`'s default routing
-fires.
+This document describes the registry that lets layered pi extensions running in the same pi process hook into `pi-telegram`'s polling loop and react to inbound Telegram updates **before** `pi-telegram`'s default routing fires.
 
-It is the runtime counterpart to
-[Callback Namespaces](./callback-namespaces.md): callback namespaces define
-how to share `callback_data` cleanly; external handlers define how to
-observe and optionally short-circuit the dispatch of those updates.
+It is the runtime counterpart to [Callback Namespaces](./callback-namespaces.md): callback namespaces define how to share `callback_data` cleanly; external handlers define how to observe and optionally short-circuit the dispatch of those updates.
 
 ## When to use it
 
 Use it when a layered extension needs to:
 
-- Resolve out-of-band state (for example, a `tool_call` approval Promise)
-  the moment a Telegram callback arrives, rather than waiting for the next
-  agent turn.
-- Suppress `pi-telegram`'s default routing for callbacks owned by the
-  layered extension (so `pi-telegram` does not also forward them as
-  `[callback] <data>` text).
-- Observe arbitrary update types (messages, edits, channel posts, reactions)
-  without owning the polling connection.
+- Resolve out-of-band state, for example a `tool_call` approval Promise, the moment a Telegram callback arrives, rather than waiting for the next agent turn.
+- Suppress `pi-telegram`'s default routing for callbacks owned by the layered extension, so `pi-telegram` does not also forward them as `[callback] <data>` text.
+- Observe arbitrary update types such as messages, edits, channel posts, or reactions without owning the polling connection.
 
-If the layered extension only needs to read assistant-visible callbacks, the
-existing `[callback] <data>` fallback documented in
-[Callback Namespaces](./callback-namespaces.md) is enough.
+If the layered extension only needs to read assistant-visible callbacks, the existing `[callback] <data>` fallback documented in [Callback Namespaces](./callback-namespaces.md) is enough.
+
+If the extension needs a durable top-level Telegram menu section with managed rendering, callback routing, authorization, and diagnostics, use the higher-level [Telegram Extension Sections](./extension-sections.md) contract instead of a raw external handler.
 
 ## Constraints
 
-- One bot, one pi process, one `getUpdates` poller. This registry does **not**
-  enable running multiple pi instances against the same bot.
-- Interceptors run in the polling loop. They must return quickly; long
-  awaits delay subsequent updates.
-- Interceptor errors are caught and logged silently so polling never breaks.
-  If you need durable error reporting, do it inside your interceptor.
-- The registry lives on `globalThis`. Module instance identity is not
-  required, so layered extensions can reach it without importing
-  `@llblab/pi-telegram`.
+- One bot, one pi process, one `getUpdates` poller. This registry does **not** enable running multiple pi instances against the same bot.
+- Interceptors run in the polling loop. They must return quickly; long awaits delay subsequent updates.
+- Interceptor errors are caught and logged silently so polling never breaks. If you need durable error reporting, do it inside your interceptor.
+- The registry lives on `globalThis`. Module instance identity is not required, so layered extensions can reach it without importing `@llblab/pi-telegram`.
 
 ## Verdicts
 
 Each interceptor returns one of:
 
 - `"consume"` — `pi-telegram` skips its default routing for this update.
-- `"pass"` (or `void` / `undefined`) — `pi-telegram` routes the update
-  normally. Other interceptors registered after this one still run for the
-  same update.
+- `"pass"` or `void` / `undefined` — `pi-telegram` routes the update normally. Other interceptors registered after this one still run for the same update.
 
-The first interceptor that returns `"consume"` wins; later interceptors are
-not called for that update.
+The first interceptor that returns `"consume"` wins; later interceptors are not called for that update.
 
 ## Registering an interceptor
 
@@ -79,18 +57,9 @@ off();
 
 ### Zero-coupling globalThis lookup
 
-When the layered extension prefers no `import` from `@llblab/pi-telegram` (so
-load order between the two extensions does not matter, and either can be
-installed first), it must implement the **full v1 registry contract**, not
-just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on
-whatever object it finds at `globalThis.__piTelegramExternalHandlerRegistry__`,
-so a partial object would silently break the first update.
+When the layered extension prefers no `import` from `@llblab/pi-telegram`, so load order between the two extensions does not matter and either can be installed first, it must implement the **full v1 registry contract**, not just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on whatever object it finds at `globalThis.__piTelegramExternalHandlerRegistry__`, so a partial object would silently break the first update.
 
-pi-telegram defensively re-creates the registry if the object on `globalThis`
-is missing `add` or `dispatch` (validated as `version === 1`,
-`typeof add === "function"`, `typeof dispatch === "function"`). Handlers
-registered against a malformed object are dropped — make sure your bootstrap
-implements all three fields.
+pi-telegram defensively re-creates the registry if the object on `globalThis` is missing `add` or `dispatch`, validated as `version === 1`, `typeof add === "function"`, and `typeof dispatch === "function"`. Handlers registered against a malformed object are dropped — make sure your bootstrap implements all three fields.
 
 ```ts
 type PiTelegramVerdict =
@@ -151,43 +120,32 @@ const off = getOrCreateRegistry().add((update) => {
 });
 ```
 
-The registry object on `globalThis.__piTelegramExternalHandlerRegistry__` is
-versioned (`version: 1`) and stable across pi-telegram releases; future
-breaking changes will use a new schema version and a new key.
+The registry object on `globalThis.__piTelegramExternalHandlerRegistry__` is versioned (`version: 1`) and stable across pi-telegram releases; future breaking changes will use a new schema version and a new key.
 
 ## Interaction with built-in routing
 
-`pi-telegram` invokes registered interceptors first, then routes the update
-through its own handlers (commands, app menu, queue menu, model menu,
-default prompt routing, callback namespace fallback). If any interceptor
-returns `"consume"`, `pi-telegram` skips the rest of routing for that update.
+`pi-telegram` invokes registered interceptors first, then routes the update through its own handlers: commands, app menu, queue menu, model menu, default prompt routing, and callback namespace fallback. If any interceptor returns `"consume"`, `pi-telegram` skips the rest of routing for that update.
 
 This means:
 
-- Extensions can claim callback namespaces that `pi-telegram` would
-  otherwise forward as `[callback] <data>` text.
-- Extensions can observe (but not consume) updates by always returning
-  `"pass"`.
-- Extensions must not consume updates that belong to `pi-telegram`'s own
-  prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`)
-  unless they are deliberately replacing that behavior.
+- Extensions can claim callback namespaces that `pi-telegram` would otherwise forward as `[callback] <data>` text.
+- Extensions can observe updates by always returning `"pass"`.
+- Extensions must not consume updates that belong to `pi-telegram`'s own prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) unless they are deliberately replacing that behavior.
 
 ## Ownership semantics
 
-The interceptor registry is ownership-agnostic and does not interact with
-the `locks.json` singleton lock documented in [Locks](./locks.md). When the
-locked polling runtime stops `pi-telegram`'s poller (for example, after
-ownership is moved to another pi process), interceptors stop receiving
-updates because no updates are being fetched. They are not unregistered.
+The interceptor registry is ownership-agnostic and does not interact with the `locks.json` singleton lock documented in [Locks](./locks.md). When the locked polling runtime stops `pi-telegram`'s poller, for example after ownership is moved to another pi process, interceptors stop receiving updates because no updates are being fetched. They are not unregistered.
 
-If a layered extension needs to react to ownership changes, it should
-observe `pi-telegram` lifecycle events through the standard pi extension
-hooks rather than through the interceptor registry.
+If a layered extension needs to react to ownership changes, it should observe `pi-telegram` lifecycle events through the standard pi extension hooks rather than through the interceptor registry.
 
 ## Not a multiplexer
 
-This registry does not multiplex one bot across multiple pi processes, and
-it does not bypass Telegram's single-poller-per-bot constraint. To run
-multiple pi instances on Telegram, give each instance its own bot and its
-own `~/.pi/agent` directory; the registry is for layered extensions inside
-**one** pi process.
+This registry does not multiplex one bot across multiple pi processes, and it does not bypass Telegram's single-poller-per-bot constraint. To run multiple pi instances on Telegram, give each instance its own bot and its own `~/.pi/agent` directory; the registry is for layered extensions inside **one** pi process.
+
+## Relationship to extension sections
+
+External handlers are the raw update primitive. Extension sections are the structured Telegram UI layer above that primitive.
+
+Use external handlers for immediate update interception, custom callback namespaces, out-of-band Promise resolution, and update types that should not become a Telegram menu surface.
+
+Use extension sections when the desired behavior is a menu-integrated UI: `render(ctx)`, managed callback dispatch, safe runtime ports, stale-callback handling, and diagnostics owned by `pi-telegram`.

package/docs/inbound-handlers.md

@@ -71,12 +71,12 @@ Media/file handlers keep the legacy attachment-handler behavior: downloaded file
 
 Built-in placeholders for media/file handlers:
 
-| Placeholder | Value                                                            |
-| ----------- | ---------------------------------------------------------------- |
-| `{file}`    | Full local path to the downloaded file                           |
-| `{mime}`    | MIME type if known                                               |
-| `{type}`    | Attachment kind such as `voice`, `audio`, `document`, or `photo` |
-| `{text}`    | Empty string                                                     |
+| Placeholder | Value                                          |
+| ----------- | ---------------------------------------------- |
+| `{file}`    | Downloaded file path                           |
+| `{mime}`    | MIME type if known                             |
+| `{type}`    | Kind: `voice`, `audio`, `document`, or `photo` |
+| `{text}`    | Empty string                                   |
 
 If a top-level one-step media handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg as a one-step handler convenience. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
 

package/docs/outbound-handlers.md

@@ -10,11 +10,11 @@ This document is the local outbound adaptation of the portable [Command Template
 
 An outbound handler is selected by `type`. Text replies and assistant markup map to handler types:
 
-| Source            | Handler type | Telegram action                                    |
-| ----------------- | ------------ | -------------------------------------------------- |
-| Final text reply  | `text`       | Transform text/Markdown before Telegram rendering  |
-| `telegram_voice`  | `voice`      | Generate OGG/Opus and call `sendVoice`             |
-| `telegram_button` | Built-in     | Attach an inline keyboard button to the final text |
+| Source | Type | Action |
+| --- | --- | --- |
+| Final text | `text` | Transform before render |
+| `telegram_voice` | `voice` | Generate OGG/Opus |
+| `telegram_button` | Built-in | Attach inline button |
 
 Configured command-template handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. `output` selects the primary artifact path when the handler produces a file instead of stdout text. Legacy configs may still use `pipe`, but `template: [...]` is the preferred standard shape.
 
@@ -96,13 +96,13 @@ The bridge strips the comment from Telegram text. On `agent_end`, it maps each `
 
 Voice outbound handlers receive these runtime placeholders:
 
-| Placeholder | Value                                                    |
-| ----------- | -------------------------------------------------------- |
-| `{text}`    | Voice text from body, `text="..."`, or colon shorthand |
-| `{lang}`    | Optional markup override such as `lang=ru`               |
-| `{rate}`    | Optional markup override such as `rate=+30%`             |
-| `{mp3}`     | Flat temp artifact path under `~/.pi/agent/tmp/telegram` |
-| `{ogg}`     | Flat temp artifact path under `~/.pi/agent/tmp/telegram` |
+| Placeholder | Value |
+| --- | --- |
+| `{text}` | Voice text from body, attr, or colon form |
+| `{lang}` | Optional override, e.g. `lang=ru` |
+| `{rate}` | Optional override, e.g. `rate=+30%` |
+| `{mp3}` | Temp MP3 path under agent temp |
+| `{ogg}` | Temp OGG path under agent temp |
 
 Temp artifacts use unique flat names such as `<uuid>-voice.mp3` and `<uuid>-voice.ogg`. The bridge does not create per-handler directory trees.
 

package/index.ts

@@ -212,6 +212,7 @@ export default function (pi: Pi.ExtensionAPI) {
     sendMessage,
     editMessageText: editTelegramMessageText,
     canSend: lockOwnershipGuard.ownsCurrentProcess,
+    recordRuntimeEvent,
     ...replyTransport,
   });
   const { finalizeMarkdownPreview } =

package/lib/menu-settings.ts

@@ -111,7 +111,6 @@ export function buildProactivePushSettingsText(): string {
     PROACTIVE_PUSH_SETTINGS_TITLE,
     "",
     "Send successful local π task results to Telegram when the bridge is connected.",
-    "Default: off. Persists until disabled or removed from config.",
   ].join("\n");
 }
 

package/lib/preview.ts

@@ -90,6 +90,11 @@ export interface TelegramPreviewRuntimeDeps<
     options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
   canSend?: () => boolean;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
 }
 
 export interface TelegramPreviewActiveTurn {
@@ -191,6 +196,11 @@ export interface TelegramPreviewControllerDeps<
     ms: number,
   ) => ReturnType<typeof setTimeout>;
   clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
 }
 
 export interface TelegramPreviewController<
@@ -421,6 +431,7 @@ export function createTelegramPreviewController<
       ),
     editRenderedMessage: deps.editRenderedMessage,
     canSend: deps.canSend,
+    recordRuntimeEvent: deps.recordRuntimeEvent,
   });
   return {
     getState: () => state,
@@ -645,7 +656,16 @@ export async function flushTelegramPreview<
   state.flushPromise = (async () => {
     do {
       state.flushRequested = false;
-      await performTelegramPreviewFlush(chatId, state, deps);
+      try {
+        await performTelegramPreviewFlush(chatId, state, deps);
+      } catch (error) {
+        deps.recordRuntimeEvent?.("preview", error, {
+          phase: "flush",
+          chatId,
+          messageId: state.messageId,
+        });
+        break;
+      }
     } while (deps.getState() === state && state.flushRequested);
   })();
   try {
@@ -704,13 +724,22 @@ export async function finalizeTelegramMarkdownPreview<
     await clearTelegramPreview(chatId, deps);
     return false;
   }
-  if (state.mode === "draft") {
-    await deps.sendRenderedChunks(chatId, chunks, options);
-    await clearTelegramPreview(chatId, deps);
+  try {
+    if (state.mode === "draft") {
+      await deps.sendRenderedChunks(chatId, chunks, options);
+      await clearTelegramPreview(chatId, deps);
+      return true;
+    }
+    if (state.messageId === undefined) return false;
+    await deps.editRenderedMessage(chatId, state.messageId, chunks, options);
+    deps.setState(undefined);
     return true;
+  } catch (error) {
+    deps.recordRuntimeEvent?.("preview", error, {
+      phase: "finalize-markdown",
+      chatId,
+      messageId: state.messageId,
+    });
+    return false;
   }
-  if (state.messageId === undefined) return false;
-  await deps.editRenderedMessage(chatId, state.messageId, chunks, options);
-  deps.setState(undefined);
-  return true;
 }

package/lib/queue.ts

@@ -1023,20 +1023,28 @@ export async function handleTelegramAgentEndRuntime<
   if (finalText) deps.setPreviewPendingText(finalText);
   if (!finalText && hasOutboundArtifacts) await deps.clearPreview(turn.chatId);
   if (endPlan.kind === "text" && finalText) {
-    const finalized = await deps.finalizeMarkdownPreview(
-      turn.chatId,
-      finalText,
-      turn.replyToMessageId,
-      { replyMarkup },
-    );
-    if (!finalized) {
-      await deps.clearPreview(turn.chatId);
-      await deps.sendMarkdownReply(
+    try {
+      const finalized = await deps.finalizeMarkdownPreview(
         turn.chatId,
-        turn.replyToMessageId,
         finalText,
+        turn.replyToMessageId,
         { replyMarkup },
       );
+      if (!finalized) {
+        await deps.clearPreview(turn.chatId);
+        await deps.sendMarkdownReply(
+          turn.chatId,
+          turn.replyToMessageId,
+          finalText,
+          { replyMarkup },
+        );
+      }
+    } catch (error) {
+      deps.recordRuntimeEvent?.("delivery", error, {
+        phase: "final-text",
+        chatId: turn.chatId,
+        replyToMessageId: turn.replyToMessageId,
+      });
     }
   }
   if (outboundReply && deps.sendOutboundReplyArtifacts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "private": false,
   "description": "Better Telegram DM bridge extension for π",
   "type": "module",