@llblab/pi-telegram 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.9.2: External Update Interceptors
+
+- `[External Update Interceptors]` Added a versioned `globalThis` registry that lets layered pi extensions observe and optionally consume Telegram updates before pi-telegram's default routing. Impact: approval gates and other same-process extensions can react synchronously to Telegram callbacks without owning a second bot poller.
+- `[External Update Interceptors]` Validated the full v1 registry shape (`version`, `add`, and `dispatch`) before reusing a pre-existing global registry and documented the zero-coupling bootstrap contract. Impact: install-order interop stays safe even when another extension initializes the registry first.
+- `[Queue Menu]` Non-empty queue lists now keep the `🌀 Refresh` row below queued items, matching the empty-queue surface. Impact: users can manually refresh the queue screen while waiting for changes without navigating away.
+- `[Security]` Refreshed the lockfile to resolve the transitive `basic-ftp` audit advisory. Impact: release validation returns to a clean npm audit state.
+- `[Package]` Bumped package metadata to `0.9.2` and kept the lockfile in sync.
+
+## 0.9.1: Model Detail Hotfix
+
+- `[Model Menu]` Detail-mode activation now preserves scoped `thinkingLevel` by resolving the selected scoped entry before falling back to the unscoped model list. Impact: scoped model shortcuts opened through the detail submenu keep their reasoning/thinking level.
+- `[Model Menu]` Activating an already active model from the detail submenu now still runs the refresh path that applies scoped thinking changes while returning to the model list. Impact: tapping Active can still correct the thinking level instead of becoming a no-op.
+- `[Proactive Push]` Removed the unused proactive reply-target store and always sends proactive local-result pushes without `reply_to_message_id`. Impact: the runtime no longer carries dead state for a target-capture behavior that does not exist yet.
+- `[Queue Reactions]` Added `🔥` as a priority reaction and `🗑` as a queue-removal reaction. Impact: the intuitive fire/removal gestures now work alongside the existing reaction controls.
+- `[Docs]` Updated the status-bar example to match the compact active/queued display.
+- `[Package]` Bumped package metadata to `0.9.1` and kept the lockfile in sync.
+
 ## 0.9.0: Hidden Settings And Proactive Push
 
 - `[Settings Menu]` Added hidden Telegram `/settings` with a proactive push checkbox detail submenu plus `/telegram-settings` in the terminal. Impact: operators can see green/black binary flag state, use green/black/yellow On/Off checkbox controls from Telegram, and toggle the same proactive push flag locally without adding a visible bot-command entry.

package/README.md

@@ -110,8 +110,8 @@ Run these inside π, not Telegram:
 
 - If you send more Telegram messages while π is busy, they enter the default prompt queue and are processed in order.
 - Very long text messages that Telegram appears to split automatically are coalesced through a short conservative debounce and forwarded to π as one prompt when the first chunk is near Telegram's text limit, currently using a 3600-character threshold. Commands, bot messages, media groups, and normal short follow-ups are not coalesced.
-- `👍`, `⚡️`, `❤️`, and `🕊` move a waiting prompt into the priority prompt queue, behind control actions but ahead of default prompts. Removing the last priority reaction sends it back to its normal queue position, and adding a priority reaction again gives it a fresh priority position.
-- `👎`, `👻`, `💔`, and `💩` remove a waiting turn from the queue. Telegram Bot API does not expose ordinary DM message-deletion events through the polling path used here, so queue removal is bound to removal reactions.
+- `👍`, `⚡️`, `❤️`, `🕊`, and `🔥` move a waiting prompt into the priority prompt queue, behind control actions but ahead of default prompts. Removing the last priority reaction sends it back to its normal queue position, and adding a priority reaction again gives it a fresh priority position.
+- `👎`, `👻`, `💔`, `💩`, and `🗑` remove a waiting turn from the queue. Telegram Bot API does not expose ordinary DM message-deletion events through the polling path used here, so queue removal is bound to removal reactions.
 - Reactions apply to any waiting Telegram turn, including text, voice, files, images, and media groups. For media groups, a reaction on any message in the group applies to the whole queued turn.
 - If you edit a Telegram message while it is still waiting in the queue, the queued turn is updated instead of creating a duplicate prompt. Edits after a turn has already started may not affect the active run.
 - Telegram replies to earlier text or caption messages are forwarded as `[reply]` context for normal prompts, while slash commands still parse from the new message text only.
@@ -224,7 +224,7 @@ List the main risks first.
 <!-- telegram_button: OK -->
 ```
 
-Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Unknown inline-button callbacks that do not belong to pi-telegram are forwarded to π as `[callback] <data>` so other extensions can namespace and handle their own Telegram buttons without polling the bot themselves; see the [Callback Namespace Standard](./docs/callback-namespaces.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
+Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Unknown inline-button callbacks that do not belong to pi-telegram are forwarded to π as `[callback] <data>` so other extensions can namespace and handle their own Telegram buttons without polling the bot themselves; see the [Callback Namespace Standard](./docs/callback-namespaces.md). Layered extensions that need to react to Telegram updates synchronously inside their own runtime (for example, to resolve a blocking-tool approval Promise the moment a callback arrives) can register a runtime interceptor on the shared update registry; see [External Update Handlers](./docs/external-update-handlers.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
 
 ## Streaming
 
@@ -237,7 +237,7 @@ Rich previews are sent through editable messages because Telegram drafts are tex
 The π status bar shows the current bridge state plus queued Telegram turns as compact previews. Busy labels distinguish states such as `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`. Telegram prompt guidance asks agents to keep tables, dense list items, and compact text blocks within about 37 visible cells when possible so mobile replies stay readable.
 
 ```text
-telegram queued +3: [⚡ write a shell script…, summarize this image…, 📎 2 attachments]
+telegram active +3
 ```
 
 ## Notes

package/docs/README.md

@@ -10,3 +10,4 @@ Living index of project documentation in `/docs`.
 - [outbound-handlers.md](./outbound-handlers.md) — Local `pi-telegram` outbound-handler config, text/voice/button behavior, artifact outputs, and callback routing
 - [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-update-handlers.md](./external-update-handlers.md) — Runtime interceptor registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection

package/docs/architecture.md

@@ -23,24 +23,24 @@ 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  |
+| 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                                 |
+| `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                                                                                                                   |
 
 Boundary invariants:
 
@@ -95,13 +95,13 @@ 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             |
+| 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                                           |
 
 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`.
 
@@ -181,7 +181,7 @@ Current operator controls include:
 - `/stop` for aborting the active Telegram-owned run and clearing waiting Telegram queue items
 - `/telegram-status` for π-side diagnostics as grouped line-by-line sections separated by blank lines: connection, polling, execution, queue, and the recent redacted runtime/API event ring. These sections include polling state, last update id, active turn source ids, pending dispatch, compaction state, active tool count, pending model-switch state, total queue depth, and queue-lane counts. The event ring records transport/API, polling/update, prompt-dispatch, control-action, typing, compaction, setup, session-lifecycle, and attachment queue/delivery failures; benign unchanged edit responses and unsupported empty draft-clear attempts are filtered out so expected preview transport noise does not obscure real failures
 - `/telegram-settings` for π-side bridge settings; it currently exposes proactive push as a local toggle backed by the same `telegram.json` flag as the hidden Telegram `/settings` menu
-- Queue reactions apply to waiting text, voice, file, image, and media-group turns by matching the turn's source Telegram message ids: `👍`, `⚡️`, `❤️`, and `🕊` promote waiting prompts, while `👎`, `👻`, `💔`, and `💩` remove waiting turns because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses
+- Queue reactions apply to waiting text, voice, file, image, and media-group turns by matching the turn's source Telegram message ids: `👍`, `⚡️`, `❤️`, `🕊`, and `🔥` promote waiting prompts, while `👎`, `👻`, `💔`, `💩`, and `🗑` remove waiting turns because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses
 
 ## In-Flight Model Switching
 

package/docs/external-update-handlers.md

@@ -0,0 +1,193 @@
+# External Update 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.
+
+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 update 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.
+
+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.
+
+## 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`.
+
+## 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.
+
+The first interceptor that returns `"consume"` wins; later interceptors are
+not called for that update.
+
+## Registering an interceptor
+
+Two equivalent paths.
+
+### Typed import (recommended when you can depend on `@llblab/pi-telegram`)
+
+```ts
+import { onTelegramUpdate } from "@llblab/pi-telegram/lib/external-update-handlers.ts";
+
+const off = onTelegramUpdate(async (update) => {
+  const cb = (update as { callback_query?: { id?: string; data?: string } })
+    .callback_query;
+  if (!cb?.data?.startsWith("myext:")) return "pass";
+  await resolveMyApproval(cb);
+  return "consume";
+});
+
+// Later, when your extension shuts down:
+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.__piTelegramExternalUpdateRegistry__`,
+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.
+
+```ts
+type PiTelegramVerdict =
+  | "consume"
+  | "pass"
+  | void
+  | Promise<"consume" | "pass" | void>;
+type PiTelegramInterceptor = (update: unknown) => PiTelegramVerdict;
+
+interface PiTelegramExternalUpdateRegistry {
+  readonly version: 1;
+  add: (handler: PiTelegramInterceptor) => () => void;
+  // Required: pi-telegram's polling loop calls this on every update.
+  dispatch: (update: unknown) => Promise<"consume" | "pass">;
+}
+
+const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
+
+function getOrCreateRegistry(): PiTelegramExternalUpdateRegistry {
+  const g = globalThis as Record<string, unknown>;
+  const existing = g[REGISTRY_KEY] as
+    | PiTelegramExternalUpdateRegistry
+    | undefined;
+  if (
+    existing &&
+    existing.version === 1 &&
+    typeof existing.add === "function" &&
+    typeof existing.dispatch === "function"
+  ) {
+    return existing;
+  }
+  const handlers = new Set<PiTelegramInterceptor>();
+  const registry: PiTelegramExternalUpdateRegistry = {
+    version: 1,
+    add(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    async dispatch(update) {
+      for (const handler of handlers) {
+        try {
+          const result = await handler(update);
+          if (result === "consume") return "consume";
+        } catch {
+          // Never break polling because of an interceptor error.
+        }
+      }
+      return "pass";
+    },
+  };
+  g[REGISTRY_KEY] = registry;
+  return registry;
+}
+
+const off = getOrCreateRegistry().add((update) => {
+  /* … */
+  return "pass";
+});
+```
+
+The registry object on `globalThis.__piTelegramExternalUpdateRegistry__` 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.
+
+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.
+
+## 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.
+
+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.

package/index.ts

@@ -8,6 +8,7 @@ import * as Api from "./lib/api.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
+import { createTelegramInterceptedHandleUpdate } from "./lib/external-update-handlers.ts";
 import * as InboundHandlers from "./lib/inbound-handlers.ts";
 import * as Keyboard from "./lib/keyboard.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
@@ -53,8 +54,6 @@ export default function (pi: Pi.ExtensionAPI) {
     Config.createTelegramProactivePushChecker(configStore);
   const setProactivePushEnabled =
     Config.createTelegramProactivePushSetter(configStore);
-  const proactivePromptTargetStore =
-    Config.createTelegramProactivePromptTargetStore();
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const lockOwnershipGuard =
     Locks.createTelegramLockOwnershipGuard(lockRuntime);
@@ -360,7 +359,9 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: inboundRouteRuntime.handleUpdate,
+    handleUpdate: createTelegramInterceptedHandleUpdate({
+      defaultHandle: inboundRouteRuntime.handleUpdate,
+    }),
     stopTypingLoop: typing.stop,
     updateStatus,
     recordRuntimeEvent,
@@ -496,7 +497,6 @@ export default function (pi: Pi.ExtensionAPI) {
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
     isCurrentOwner: lockOwnershipGuard.ownsContext,
     getDefaultChatId: proactivePushChatIdGetter,
-    consumeProactiveReplyToMessageId: proactivePromptTargetStore.consumeForChat,
     isProactivePushEnabled,
     recordRuntimeEvent,
     getActiveToolExecutions: lifecycle.getActiveToolExecutions,

package/lib/config.ts

@@ -148,31 +148,6 @@ export function createTelegramProactivePushChatIdGetter(deps: {
   return () => deps.getActiveTurnChatId() ?? deps.getAllowedUserId();
 }
 
-export interface TelegramProactivePromptTarget {
-  chatId: number;
-  messageId: number;
-}
-
-export interface TelegramProactivePromptTargetStore {
-  set: (target: TelegramProactivePromptTarget) => void;
-  consumeForChat: (chatId: number) => number | undefined;
-}
-
-export function createTelegramProactivePromptTargetStore(): TelegramProactivePromptTargetStore {
-  let target: TelegramProactivePromptTarget | undefined;
-  return {
-    set: (nextTarget) => {
-      target = nextTarget;
-    },
-    consumeForChat: (chatId) => {
-      if (!target || target.chatId !== chatId) return undefined;
-      const messageId = target.messageId;
-      target = undefined;
-      return messageId;
-    },
-  };
-}
-
 export type TelegramAuthorizationState =
   | { kind: "pair"; userId: number }
   | { kind: "allow" }

package/lib/external-update-handlers.ts

@@ -0,0 +1,165 @@
+/**
+ * External Telegram update interceptor registry
+ * Zones: telegram transport, layered extension interop
+ * Lets other pi extensions hook into the polling loop without owning their own getUpdates connection
+ */
+
+/**
+ * Verdict returned by an interceptor.
+ *
+ * - `"consume"` — the interceptor handled this update; pi-telegram skips default routing.
+ * - `"pass"` (or `void`/`undefined`) — pi-telegram routes the update normally.
+ */
+export type TelegramExternalUpdateVerdict = "consume" | "pass";
+
+export type TelegramExternalUpdateInterceptor = (
+  update: unknown,
+) =>
+  | TelegramExternalUpdateVerdict
+  | void
+  | Promise<TelegramExternalUpdateVerdict | void>;
+
+export interface TelegramExternalUpdateRegistry {
+  /** Schema version of this registry shape. */
+  readonly version: 1;
+  /**
+   * Register an interceptor. Returns a disposer that removes it.
+   *
+   * Interceptors are invoked in registration order on every Telegram update,
+   * before pi-telegram's own routing. The first interceptor that returns
+   * `"consume"` wins and stops the chain for that update.
+   */
+  add: (handler: TelegramExternalUpdateInterceptor) => () => void;
+  /**
+   * Run all registered interceptors against an update.
+   *
+   * Used by pi-telegram's polling runtime; layered extensions should call
+   * {@link onTelegramUpdate} or `add` instead of dispatching directly.
+   */
+  dispatch: (update: unknown) => Promise<TelegramExternalUpdateVerdict>;
+}
+
+const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
+
+/**
+ * Validate that a value on `globalThis` matches the full v1 registry contract.
+ *
+ * pi-telegram's polling runtime invokes `dispatch`, so a partial object that
+ * only carries `version` and `add` (which an early draft of the zero-coupling
+ * docs showed) would silently break the first update. We treat any object
+ * tagged `version === 1` but missing required methods as malformed and
+ * replace it with a fresh, fully-formed registry. Layered extensions that
+ * follow the full documented shape are unaffected; ones that don't lose any
+ * handlers they registered against the malformed object, which is the
+ * desired fail-loud-during-development behavior.
+ */
+function isValidV1Registry(
+  candidate: unknown,
+): candidate is TelegramExternalUpdateRegistry {
+  if (!candidate || typeof candidate !== "object") return false;
+  const r = candidate as Partial<TelegramExternalUpdateRegistry>;
+  return (
+    r.version === 1 &&
+    typeof r.add === "function" &&
+    typeof r.dispatch === "function"
+  );
+}
+
+function getOrCreateRegistry(): TelegramExternalUpdateRegistry {
+  const g = globalThis as Record<string, unknown>;
+  const existing = g[REGISTRY_KEY];
+  if (isValidV1Registry(existing)) return existing;
+  const handlers = new Set<TelegramExternalUpdateInterceptor>();
+  const registry: TelegramExternalUpdateRegistry = {
+    version: 1,
+    add(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    async dispatch(update) {
+      for (const handler of handlers) {
+        try {
+          const result = await handler(update);
+          if (result === "consume") return "consume";
+        } catch {
+          // External handler errors must not break polling.
+        }
+      }
+      return "pass";
+    },
+  };
+  g[REGISTRY_KEY] = registry;
+  return registry;
+}
+
+/**
+ * Called by pi-telegram's own runtime to obtain the registry it dispatches
+ * through. Layered extensions should not call this; use
+ * {@link onTelegramUpdate} instead.
+ */
+export function getTelegramExternalUpdateRegistry(): TelegramExternalUpdateRegistry {
+  return getOrCreateRegistry();
+}
+
+export interface TelegramExternalInterceptorWrapDeps<TUpdate, TContext> {
+  defaultHandle: (update: TUpdate, ctx: TContext) => Promise<void>;
+  registry?: TelegramExternalUpdateRegistry;
+}
+
+/**
+ * Wrap a default polling `handleUpdate` with the external interceptor registry.
+ *
+ * Returned function dispatches `update` through registered interceptors first;
+ * if any returns `"consume"`, default routing is skipped for that update.
+ *
+ * Composition-root callers (pi-telegram's `index.ts`) should use this builder
+ * instead of writing the lifting logic inline.
+ */
+export function createTelegramInterceptedHandleUpdate<TUpdate, TContext>(
+  deps: TelegramExternalInterceptorWrapDeps<TUpdate, TContext>,
+): (update: TUpdate, ctx: TContext) => Promise<void> {
+  const registry = deps.registry ?? getOrCreateRegistry();
+  const { defaultHandle } = deps;
+  return async function handleInterceptedUpdate(update, ctx) {
+    const verdict = await registry.dispatch(update);
+    if (verdict === "consume") return;
+    await defaultHandle(update, ctx);
+  };
+}
+
+/**
+ * Register an interceptor that runs before pi-telegram routes a Telegram
+ * update through its built-in handlers (commands, app menu, queue menu,
+ * model menu, default prompt routing).
+ *
+ * This is the recommended public surface for layered extensions that share
+ * the same bot and pi process with pi-telegram (single bot ↔ single
+ * `getUpdates` poller).
+ *
+ * Returns a disposer that removes the interceptor.
+ *
+ * @example
+ * ```ts
+ * import { onTelegramUpdate } from "@llblab/pi-telegram/lib/external-update-handlers.ts";
+ *
+ * const off = onTelegramUpdate(async (update) => {
+ *   const cb = (update as { callback_query?: { data?: string } }).callback_query;
+ *   if (!cb?.data?.startsWith("myext:")) return "pass";
+ *   await handleMyCallback(cb);
+ *   return "consume"; // skip pi-telegram's default routing for this update
+ * });
+ *
+ * // later, e.g. on session shutdown:
+ * off();
+ * ```
+ *
+ * Extensions that prefer zero coupling can also reach the registry directly
+ * via `globalThis.__piTelegramExternalUpdateRegistry__` (versioned object,
+ * see {@link TelegramExternalUpdateRegistry}). This avoids importing
+ * `@llblab/pi-telegram` and tolerates either install order.
+ */
+export function onTelegramUpdate(
+  handler: TelegramExternalUpdateInterceptor,
+): () => void {
+  return getOrCreateRegistry().add(handler);
+}

package/lib/menu-model.ts

@@ -620,6 +620,19 @@ export function applyTelegramModelDetailSelection(
 export function getTelegramSelectedDetailModel<
   TModel extends MenuModel = MenuModel,
 >(state: TelegramModelMenuState<TModel>): TelegramMenuSelectionResult<TModel> {
+  const indexedSelection = getTelegramModelSelection(
+    state,
+    state.selectedModelIndex?.toString(),
+  );
+  if (indexedSelection.kind === "selected") {
+    if (!state.selectedModelKey) return indexedSelection;
+    const indexedKey = getCanonicalModelId(
+      indexedSelection.selection.model,
+    ).toLowerCase();
+    if (indexedKey === state.selectedModelKey.toLowerCase()) {
+      return indexedSelection;
+    }
+  }
   if (state.selectedModelKey) {
     const lowerKey = state.selectedModelKey.toLowerCase();
     const selection = state.allModels.find(
@@ -627,7 +640,7 @@ export function getTelegramSelectedDetailModel<
     );
     if (selection) return { kind: "selected", selection };
   }
-  return getTelegramModelSelection(state, state.selectedModelIndex?.toString());
+  return indexedSelection;
 }
 
 export function isTelegramModelScoped(
@@ -817,7 +830,6 @@ export function buildTelegramModelCallbackPlan<
   if (modelsMatch(selection.model, params.activeModel)) {
     if (action.action === "pick-selected") {
       focusTelegramModelListPage(params.state, selection.model);
-      return { kind: "update-menu", text: `Model: ${selection.model.id}` };
     }
     return {
       kind: "refresh-status",

package/lib/menu-queue.ts

@@ -57,10 +57,8 @@ function buildTelegramQueueMenuReplyMarkup(
   items: readonly TelegramQueueMenuItem[],
 ): TelegramQueueMenuReplyMarkup {
   const backRow = [{ text: "⬆️ Main menu", callback_data: "menu:back" }];
-  if (items.length === 0) {
-    const refreshRow = [{ text: "🌀 Refresh", callback_data: "queue:refresh" }];
-    return { inline_keyboard: [backRow, refreshRow] };
-  }
+  const refreshRow = [{ text: "🌀 Refresh", callback_data: "queue:refresh" }];
+  if (items.length === 0) return { inline_keyboard: [backRow, refreshRow] };
   const rows = items.map(function buildTelegramQueueMenuRow(item, index) {
     const prefix = item.isPriority
       ? `${item.priorityEmoji ?? "⚡"} `
@@ -75,7 +73,7 @@ function buildTelegramQueueMenuReplyMarkup(
       },
     ];
   });
-  return { inline_keyboard: [backRow, ...rows] };
+  return { inline_keyboard: [backRow, ...rows, refreshRow] };
 }
 function findTelegramQueueItem<Context>(
   items: readonly Queue.TelegramQueueItem<Context>[],

package/lib/queue.ts

@@ -794,7 +794,6 @@ export interface TelegramAgentEndRuntimeDeps<
     options?: { replyToPrompt?: boolean },
   ) => Promise<void>;
   getDefaultChatId?: () => number | undefined;
-  consumeProactiveReplyToMessageId?: (chatId: number) => number | undefined;
   isProactivePushEnabled?: () => boolean;
   recordRuntimeEvent?: (
     category: string,
@@ -839,7 +838,6 @@ export interface TelegramAgentEndHookRuntimeDeps<
   >["planOutboundReply"];
   sendOutboundReplyArtifacts?: TelegramAgentEndRuntimeDeps<TTurn>["sendOutboundReplyArtifacts"];
   getDefaultChatId?: TelegramAgentEndRuntimeDeps<TTurn>["getDefaultChatId"];
-  consumeProactiveReplyToMessageId?: TelegramAgentEndRuntimeDeps<TTurn>["consumeProactiveReplyToMessageId"];
   isProactivePushEnabled?: TelegramAgentEndRuntimeDeps<TTurn>["isProactivePushEnabled"];
   recordRuntimeEvent?: TelegramAgentEndRuntimeDeps<TTurn>["recordRuntimeEvent"];
 }
@@ -957,7 +955,6 @@ export function createTelegramAgentEndHook<
       planOutboundReply: deps.planOutboundReply,
       sendOutboundReplyArtifacts: deps.sendOutboundReplyArtifacts,
       getDefaultChatId: deps.getDefaultChatId,
-      consumeProactiveReplyToMessageId: deps.consumeProactiveReplyToMessageId,
       isProactivePushEnabled: deps.isProactivePushEnabled,
       recordRuntimeEvent: deps.recordRuntimeEvent,
     });
@@ -998,14 +995,8 @@ export async function handleTelegramAgentEndRuntime<
     ) {
       const defaultChatId = deps.getDefaultChatId?.();
       if (defaultChatId !== undefined) {
-        const replyToMessageId =
-          deps.consumeProactiveReplyToMessageId?.(defaultChatId);
         try {
-          await deps.sendMarkdownReply(
-            defaultChatId,
-            replyToMessageId,
-            finalText,
-          );
+          await deps.sendMarkdownReply(defaultChatId, undefined, finalText);
         } catch (error) {
           deps.recordRuntimeEvent?.("proactive-push", error, {
             chatId: defaultChatId,

package/lib/updates.ts

@@ -31,12 +31,14 @@ export const TELEGRAM_PRIORITY_REACTIONS = [
   { id: 11, name: "lightning", emoji: "⚡" },
   { id: 12, name: "heart", emoji: "❤" },
   { id: 13, name: "dove", emoji: "🕊" },
+  { id: 14, name: "fire", emoji: "🔥" },
 ] as const;
 export const TELEGRAM_REMOVAL_REACTIONS = [
   { id: 20, name: "dislike", emoji: "👎" },
   { id: 21, name: "ghost", emoji: "👻" },
   { id: 22, name: "broken-heart", emoji: "💔" },
   { id: 23, name: "poop", emoji: "💩" },
+  { id: 24, name: "wastebasket", emoji: "🗑" },
 ] as const;
 export const TELEGRAM_PRIORITY_REACTION_EMOJIS =
   TELEGRAM_PRIORITY_REACTIONS.map((reaction) => reaction.emoji);

package/package.json

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