@llblab/pi-telegram 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.9.3: External Handlers Rename
+
+- `[External Handlers]` Renamed the external update handlers domain to `external-handlers` across source, tests, and docs. Impact: the interop domain now has a cleaner name aligned with inbound/outbound handler naming.
+- `[Breaking]` Removed the old `external-update-handlers` module/doc path and old exported update/interceptor aliases. Impact: layered extensions should import from `@llblab/pi-telegram/lib/external-handlers.ts` and use the `TelegramExternalHandler*` names.
+- `[Package]` Bumped package metadata to `0.9.3` and kept the lockfile in sync.
+
+## 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.

package/README.md

@@ -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 Handlers](./docs/external-handlers.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
 
 ## Streaming
 

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-handlers.md](./external-handlers.md) — Runtime interceptor registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection

package/docs/external-handlers.md

@@ -0,0 +1,193 @@
+# 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.
+
+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.
+
+## 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 { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
+
+const off = onTelegramExternalUpdate(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.__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.
+
+```ts
+type PiTelegramVerdict =
+  | "consume"
+  | "pass"
+  | void
+  | Promise<"consume" | "pass" | void>;
+type PiTelegramInterceptor = (update: unknown) => PiTelegramVerdict;
+
+interface PiTelegramExternalHandlerRegistry {
+  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 = "__piTelegramExternalHandlerRegistry__";
+
+function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
+  const g = globalThis as Record<string, unknown>;
+  const existing = g[REGISTRY_KEY] as
+    | PiTelegramExternalHandlerRegistry
+    | undefined;
+  if (
+    existing &&
+    existing.version === 1 &&
+    typeof existing.add === "function" &&
+    typeof existing.dispatch === "function"
+  ) {
+    return existing;
+  }
+  const handlers = new Set<PiTelegramInterceptor>();
+  const registry: PiTelegramExternalHandlerRegistry = {
+    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.__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.
+
+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 { createTelegramExternalHandleUpdate } from "./lib/external-handlers.ts";
 import * as InboundHandlers from "./lib/inbound-handlers.ts";
 import * as Keyboard from "./lib/keyboard.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
@@ -358,7 +359,9 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: inboundRouteRuntime.handleUpdate,
+    handleUpdate: createTelegramExternalHandleUpdate({
+      defaultHandle: inboundRouteRuntime.handleUpdate,
+    }),
     stopTypingLoop: typing.stop,
     updateStatus,
     recordRuntimeEvent,

package/lib/external-handlers.ts

@@ -0,0 +1,167 @@
+/**
+ * External Telegram handler 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 TelegramExternalHandlerVerdict = "consume" | "pass";
+
+export type TelegramExternalHandler = (
+  update: unknown,
+) =>
+  | TelegramExternalHandlerVerdict
+  | void
+  | Promise<TelegramExternalHandlerVerdict | void>;
+
+export interface TelegramExternalHandlerRegistry {
+  /** 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: TelegramExternalHandler) => () => void;
+  /**
+   * Run all registered interceptors against an update.
+   *
+   * Used by pi-telegram's polling runtime; layered extensions should call
+   * {@link onTelegramExternalUpdate} or `add` instead of dispatching directly.
+   */
+  dispatch: (update: unknown) => Promise<TelegramExternalHandlerVerdict>;
+}
+
+const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
+
+/**
+ * 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 TelegramExternalHandlerRegistry {
+  if (!candidate || typeof candidate !== "object") return false;
+  const r = candidate as Partial<TelegramExternalHandlerRegistry>;
+  return (
+    r.version === 1 &&
+    typeof r.add === "function" &&
+    typeof r.dispatch === "function"
+  );
+}
+
+function getOrCreateRegistry(): TelegramExternalHandlerRegistry {
+  const g = globalThis as Record<string, unknown>;
+  const existing = g[REGISTRY_KEY];
+  if (isValidV1Registry(existing)) return existing;
+  const handlers = new Set<TelegramExternalHandler>();
+  const registry: TelegramExternalHandlerRegistry = {
+    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 onTelegramExternalUpdate} instead.
+ */
+export function getTelegramExternalHandlerRegistry(): TelegramExternalHandlerRegistry {
+  return getOrCreateRegistry();
+}
+
+export interface TelegramExternalHandlerWrapDeps<TUpdate, TContext> {
+  defaultHandle: (update: TUpdate, ctx: TContext) => Promise<void>;
+  registry?: TelegramExternalHandlerRegistry;
+}
+export type TelegramExternalInterceptorWrapDeps<TUpdate, TContext> =
+  TelegramExternalHandlerWrapDeps<TUpdate, TContext>;
+
+/**
+ * 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 createTelegramExternalHandleUpdate<TUpdate, TContext>(
+  deps: TelegramExternalHandlerWrapDeps<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 { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
+ *
+ * const off = onTelegramExternalUpdate(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.__piTelegramExternalHandlerRegistry__` (versioned object,
+ * see {@link TelegramExternalHandlerRegistry}). This avoids importing
+ * `@llblab/pi-telegram` and tolerates either install order.
+ */
+export function onTelegramExternalUpdate(
+  handler: TelegramExternalHandler,
+): () => void {
+  return getOrCreateRegistry().add(handler);
+}

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/package.json

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