@llblab/pi-telegram 0.9.4 → 0.9.6

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/api.ts

@@ -12,6 +12,8 @@ import { join, resolve } from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
+export const TELEGRAM_API_BASE = "https://api.telegram.org";
+
 export const TELEGRAM_FILE_MAX_BYTES = 50 * 1024 * 1024;
 
 export function getTelegramInboundFileByteLimitFromEnv(
@@ -513,7 +515,7 @@ export async function callTelegram<TResponse>(
   return callTelegramWithRetry(
     method,
     async () =>
-      fetch(`https://api.telegram.org/bot${configuredBotToken}/${method}`, {
+      fetch(`${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify(body),
@@ -533,7 +535,7 @@ export async function fetchTelegramBotIdentity(
   fetchImpl: typeof fetch = fetch,
 ): Promise<TelegramBotIdentityResponse> {
   const response = await fetchImpl(
-    `https://api.telegram.org/bot${botToken}/getMe`,
+    `${TELEGRAM_API_BASE}/bot${botToken}/getMe`,
   );
   return response.json() as Promise<TelegramBotIdentityResponse>;
 }
@@ -558,7 +560,7 @@ export async function callTelegramMultipart<TResponse>(
       }
       form.set(fileField, fileBlob, fileName);
       return fetch(
-        `https://api.telegram.org/bot${configuredBotToken}/${method}`,
+        `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
         {
           method: "POST",
           body: form,
@@ -591,7 +593,7 @@ export async function downloadTelegramFile(
     `${randomUUID()}-${sanitizeFileName(suggestedName)}`,
   );
   const response = await fetch(
-    `https://api.telegram.org/file/bot${configuredBotToken}/${file.file_path}`,
+    `${TELEGRAM_API_BASE}/file/bot${configuredBotToken}/${file.file_path}`,
     { signal: options?.signal },
   );
   if (!response.ok) {

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;
 }