@llblab/pi-telegram 0.9.9 → 0.10.1

package/lib/menu-settings.ts

@@ -4,6 +4,10 @@
  * Owns hidden settings-menu rendering, settings callbacks, and persisted toggle wiring
  */
 
+import {
+  getTelegramExtensionSettingsRows,
+  type TelegramSectionRegistry,
+} from "./extension-sections.ts";
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 import type { TelegramModelMenuState } from "./menu-model.ts";
 import type { MenuModel } from "./model.ts";
@@ -39,6 +43,7 @@ export interface TelegramSettingsMenuCallbackDeps extends TelegramSettingsMutati
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
+  sectionRegistry?: TelegramSectionRegistry;
 }
 
 export interface TelegramSettingsMenuRuntime<TContext> {
@@ -116,28 +121,41 @@ export function buildProactivePushSettingsText(): string {
 
 export function buildTelegramSettingsMenuReplyMarkup(
   proactivePushEnabled: boolean,
+  sectionRegistry?: TelegramSectionRegistry,
 ): TelegramSettingsMenuReplyMarkup {
-  return {
-    inline_keyboard: [
-      [{ text: "⬆️ Main menu", callback_data: "menu:back" }],
-      [
-        {
-          text: `${proactivePushEnabled ? "🟢" : "⚫️"} Proactive push`,
-          callback_data: "settings:open:proactive",
-        },
-      ],
-    ],
-  };
+  const rows: Array<Array<{ text: string; callback_data: string }>> = [
+    [{ text: "⬆️ Main menu", callback_data: "menu:back" }],
+  ];
+  // Extension settings rows before built-in controls
+  if (sectionRegistry) {
+    const settingsRows = getTelegramExtensionSettingsRows(sectionRegistry);
+    for (const row of settingsRows) {
+      rows.push([{ text: row.label, callback_data: row.callback_data }]);
+    }
+  }
+  rows.push([
+    {
+      text: `${proactivePushEnabled ? "🟢" : "⚫️"} Proactive push`,
+      callback_data: "settings:open:proactive",
+    },
+  ]);
+  return { inline_keyboard: rows };
 }
 
 export async function openTelegramSettingsMenu<
   TModel extends MenuModel = MenuModel,
->(deps: TelegramSettingsMenuOpenDeps<TModel>): Promise<void> {
+>(
+  deps: TelegramSettingsMenuOpenDeps<TModel>,
+  sectionRegistry?: TelegramSectionRegistry,
+): Promise<void> {
   const state = await deps.getModelMenuState();
   const messageId = await deps.sendSettingsMenu(
     state,
     buildTelegramSettingsMenuText(),
-    buildTelegramSettingsMenuReplyMarkup(deps.isProactivePushEnabled()),
+    buildTelegramSettingsMenuReplyMarkup(
+      deps.isProactivePushEnabled(),
+      sectionRegistry,
+    ),
   );
   if (messageId === undefined) return;
   state.messageId = messageId;
@@ -167,10 +185,14 @@ export function buildProactivePushSettingsReplyMarkup(
 
 export async function updateTelegramSettingsMenuMessage(
   deps: TelegramSettingsMenuMessageUpdateDeps,
+  sectionRegistry?: TelegramSectionRegistry,
 ): Promise<void> {
   await deps.updateSettingsMessage(
     buildTelegramSettingsMenuText(),
-    buildTelegramSettingsMenuReplyMarkup(deps.isProactivePushEnabled()),
+    buildTelegramSettingsMenuReplyMarkup(
+      deps.isProactivePushEnabled(),
+      sectionRegistry,
+    ),
   );
 }
 
@@ -190,7 +212,7 @@ export async function handleTelegramSettingsMenuCallbackAction(
 ): Promise<boolean> {
   if (!data?.startsWith("settings:")) return false;
   if (data === "settings:list") {
-    await updateTelegramSettingsMenuMessage(deps);
+    await updateTelegramSettingsMenuMessage(deps, deps.sectionRegistry);
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
@@ -221,28 +243,40 @@ export function createTelegramSettingsMenuRuntime<
   TModel extends MenuModel = MenuModel,
 >(
   deps: TelegramSettingsMenuRuntimeDeps<TContext, TModel>,
+  sectionRegistry?: TelegramSectionRegistry,
 ): TelegramSettingsMenuRuntime<TContext> {
   return {
     openSettingsMenu: (chatId, _replyToMessageId, ctx) =>
-      openTelegramSettingsMenu({
-        getModelMenuState: () => deps.getModelMenuState(chatId, ctx),
-        isProactivePushEnabled: deps.isProactivePushEnabled,
-        sendSettingsMenu: (state, text, replyMarkup) =>
-          deps.sendInteractiveMessage(state.chatId, text, "html", replyMarkup),
-        storeModelMenuState: deps.storeModelMenuState,
-      }),
+      openTelegramSettingsMenu(
+        {
+          getModelMenuState: () => deps.getModelMenuState(chatId, ctx),
+          isProactivePushEnabled: deps.isProactivePushEnabled,
+          sendSettingsMenu: (state, text, replyMarkup) =>
+            deps.sendInteractiveMessage(
+              state.chatId,
+              text,
+              "html",
+              replyMarkup,
+            ),
+          storeModelMenuState: deps.storeModelMenuState,
+        },
+        sectionRegistry,
+      ),
     updateSettingsMenuMessage: (state) =>
-      updateTelegramSettingsMenuMessage({
-        isProactivePushEnabled: deps.isProactivePushEnabled,
-        updateSettingsMessage: (text, replyMarkup) =>
-          deps.editInteractiveMessage(
-            state.chatId,
-            state.messageId,
-            text,
-            "html",
-            replyMarkup,
-          ),
-      }),
+      updateTelegramSettingsMenuMessage(
+        {
+          isProactivePushEnabled: deps.isProactivePushEnabled,
+          updateSettingsMessage: (text, replyMarkup) =>
+            deps.editInteractiveMessage(
+              state.chatId,
+              state.messageId,
+              text,
+              "html",
+              replyMarkup,
+            ),
+        },
+        sectionRegistry,
+      ),
     handleCallbackQuery: async (query) => {
       if (!query.data?.startsWith("settings:")) return false;
       const state = deps.getStoredModelMenuState(query.message?.message_id);
@@ -265,6 +299,7 @@ export function createTelegramSettingsMenuRuntime<
             replyMarkup,
           ),
         answerCallbackQuery: deps.answerCallbackQuery,
+        sectionRegistry,
       });
     },
   };

package/lib/menu-status.ts

@@ -5,6 +5,10 @@
  */
 
 import { formatTelegramCommandEmojiPrefix } from "./commands.ts";
+import {
+  getTelegramSectionMainMenuRows,
+  type TelegramSectionRegistry,
+} from "./extension-sections.ts";
 import {
   formatStatusButtonLabel,
   type TelegramMenuMessageRuntimeDeps,
@@ -143,6 +147,7 @@ export function buildStatusReplyMarkup(
   activeModel: MenuModel | undefined,
   currentThinkingLevel: ThinkingLevel,
   queueItemCount = 0,
+  sectionRegistry?: TelegramSectionRegistry,
 ): TelegramReplyMarkup {
   const rows: Array<Array<{ text: string; callback_data: string }>> = [];
   rows.push([
@@ -171,6 +176,13 @@ export function buildStatusReplyMarkup(
       callback_data: "menu:queue",
     },
   ]);
+  // Extension section rows before Settings
+  if (sectionRegistry) {
+    const sectionRows = getTelegramSectionMainMenuRows(sectionRegistry);
+    for (const row of sectionRows) {
+      rows.push([{ text: row.text, callback_data: row.callback_data }]);
+    }
+  }
   rows.push([
     {
       text: "⚙️ Settings",
@@ -185,6 +197,7 @@ export function buildTelegramStatusMenuRenderPayload(
   activeModel: MenuModel | undefined,
   currentThinkingLevel: ThinkingLevel,
   queueItemCount = 0,
+  sectionRegistry?: TelegramSectionRegistry,
 ): TelegramMenuRenderPayload {
   return {
     nextMode: "status",
@@ -194,6 +207,7 @@ export function buildTelegramStatusMenuRenderPayload(
       activeModel,
       currentThinkingLevel,
       queueItemCount,
+      sectionRegistry,
     ),
   };
 }
@@ -205,6 +219,7 @@ export async function updateTelegramStatusMessage(
   currentThinkingLevel: ThinkingLevel,
   deps: TelegramMenuMessageRuntimeDeps,
   queueItemCount = 0,
+  sectionRegistry?: TelegramSectionRegistry,
 ): Promise<void> {
   await editTelegramMenuMessage(
     state,
@@ -213,6 +228,7 @@ export async function updateTelegramStatusMessage(
       activeModel,
       currentThinkingLevel,
       queueItemCount,
+      sectionRegistry,
     ),
     deps,
   );
@@ -225,6 +241,7 @@ export function sendTelegramStatusMessage(
   currentThinkingLevel: ThinkingLevel,
   deps: TelegramMenuMessageRuntimeDeps,
   queueItemCount = 0,
+  sectionRegistry?: TelegramSectionRegistry,
 ): Promise<number | undefined> {
   return sendTelegramMenuMessage(
     state,
@@ -233,6 +250,7 @@ export function sendTelegramStatusMessage(
       activeModel,
       currentThinkingLevel,
       queueItemCount,
+      sectionRegistry,
     ),
     deps,
   );

package/lib/menu.ts

@@ -4,6 +4,13 @@
  * Owns app-menu/status state, inline UI text, and callback composition while model/thinking/queue menu details live in dedicated domains
  */
 
+import {
+  handleTelegramSectionCallback,
+  handleTelegramSectionOpen,
+  handleTelegramSectionSettingsOpen,
+  parseTelegramSectionCallback,
+  type TelegramSectionRegistry,
+} from "./extension-sections.ts";
 import {
   createTelegramModelMenuStateBuilder,
   handleTelegramModelMenuCallbackAction,
@@ -14,6 +21,7 @@ import {
   type TelegramModelMenuState,
   type TelegramModelMenuStateBuilderContext,
   type TelegramModelMenuStateBuilderDeps,
+  type TelegramReplyMarkup,
 } from "./menu-model.ts";
 import {
   handleTelegramStatusMenuCallbackAction,
@@ -39,9 +47,9 @@ export {
   buildModelPageMenuReplyMarkup,
   buildTelegramModelCallbackPlan,
   buildTelegramModelMenuRenderPayload,
-  buildTelegramModelPageMenuRenderPayload,
   buildTelegramModelMenuState,
   buildTelegramModelMenuStateRuntime,
+  buildTelegramModelPageMenuRenderPayload,
   createTelegramModelMenuRuntime,
   createTelegramModelMenuStateBuilder,
   formatScopedModelButtonText,
@@ -215,6 +223,21 @@ export interface TelegramMenuCallbackRuntimeDeps<
     selection: ScopedTelegramModel<TModel>,
     ctx: TContext,
   ) => Promise<boolean> | boolean;
+  sectionRegistry?: TelegramSectionRegistry;
+  editInteractiveMessage?: (
+    chatId: number,
+    messageId: number,
+    text: string,
+    mode: "html" | "plain",
+    replyMarkup: TelegramReplyMarkup,
+  ) => Promise<void>;
+  sendInteractiveMessage?: (
+    chatId: number,
+    text: string,
+    mode: "html" | "plain",
+    replyMarkup: TelegramReplyMarkup,
+  ) => Promise<number | undefined>;
+  enqueueSectionPrompt?: (prompt: string, ctx: TContext) => Promise<void>;
 }
 
 export interface TelegramMenuActionRuntimeDeps<
@@ -237,6 +260,7 @@ export interface TelegramMenuActionRuntimeDeps<
     replyToMessageId: number,
     text: string,
   ) => Promise<unknown>;
+  sectionRegistry?: TelegramSectionRegistry;
 }
 
 export interface TelegramMenuActionRuntime<
@@ -432,6 +456,21 @@ export interface TelegramMenuCallbackRuntimeAdapterDeps<
     selection: ScopedTelegramModel<TModel>,
     ctx: TContext,
   ) => Promise<boolean> | boolean;
+  sectionRegistry?: TelegramSectionRegistry;
+  editInteractiveMessage?: (
+    chatId: number,
+    messageId: number,
+    text: string,
+    mode: "html" | "plain",
+    replyMarkup: TelegramReplyMarkup,
+  ) => Promise<void>;
+  sendInteractiveMessage?: (
+    chatId: number,
+    text: string,
+    mode: "html" | "plain",
+    replyMarkup: TelegramReplyMarkup,
+  ) => Promise<number | undefined>;
+  enqueueSectionPrompt?: (prompt: string, ctx: TContext) => Promise<void>;
 }
 
 export function createTelegramMenuCallbackHandler<
@@ -471,6 +510,10 @@ export function createTelegramMenuCallbackHandlerForContext<
     setCurrentModel: deps.setCurrentModel,
     stagePendingModelSwitch: deps.stagePendingModelSwitch,
     restartInterruptedTelegramTurn: deps.restartInterruptedTelegramTurn,
+    sectionRegistry: deps.sectionRegistry,
+    editInteractiveMessage: deps.editInteractiveMessage,
+    sendInteractiveMessage: deps.sendInteractiveMessage,
+    enqueueSectionPrompt: deps.enqueueSectionPrompt,
   });
 }
 
@@ -493,6 +536,89 @@ export async function handleTelegramMenuCallbackRuntime<
     await deps.answerCallbackQuery(query.id);
     return;
   }
+  // Section callbacks: dispatch before built-in menu handling
+  if (deps.sectionRegistry && query.data?.startsWith("section:")) {
+    const parsed = parseTelegramSectionCallback(query.data);
+    if (parsed) {
+      const chatId = (query as { message?: { chat?: { id?: number } } }).message
+        ?.chat?.id;
+      const messageId = (query as { message?: { message_id?: number } }).message
+        ?.message_id;
+      if (typeof chatId === "number" && typeof messageId === "number") {
+        const { token, action, payload } = parsed;
+        if (action === "open") {
+          const state = deps.getStoredModelMenuState(messageId);
+          if (!state) {
+            await deps.answerCallbackQuery(
+              query.id,
+              "Interactive message expired.",
+            );
+            return;
+          }
+          const handled = await handleTelegramSectionOpen(
+            deps.sectionRegistry,
+            token,
+            chatId,
+            messageId,
+            query.id,
+            {
+              answerCallbackQuery: deps.answerCallbackQuery,
+              editInteractiveMessage:
+                deps.editInteractiveMessage ?? (async () => {}),
+              sendInteractiveMessage:
+                deps.sendInteractiveMessage ?? (async () => undefined),
+              enqueuePrompt: deps.enqueueSectionPrompt
+                ? (prompt: string) => deps.enqueueSectionPrompt!(prompt, ctx)
+                : async () => {},
+            },
+          );
+          if (handled) return;
+        } else if (action === "settings") {
+          if (typeof chatId === "number" && typeof messageId === "number") {
+            const handled = await handleTelegramSectionSettingsOpen(
+              deps.sectionRegistry,
+              token,
+              chatId,
+              messageId,
+              query.id,
+              {
+                answerCallbackQuery: deps.answerCallbackQuery,
+                editInteractiveMessage:
+                  deps.editInteractiveMessage ?? (async () => {}),
+                sendInteractiveMessage:
+                  deps.sendInteractiveMessage ?? (async () => undefined),
+                enqueuePrompt: deps.enqueueSectionPrompt
+                  ? (prompt: string) => deps.enqueueSectionPrompt!(prompt, ctx)
+                  : async () => {},
+              },
+            );
+            if (handled) return;
+          }
+        } else {
+          const handled = await handleTelegramSectionCallback(
+            deps.sectionRegistry,
+            token,
+            action,
+            payload,
+            chatId,
+            messageId,
+            query.id,
+            {
+              answerCallbackQuery: deps.answerCallbackQuery,
+              editInteractiveMessage:
+                deps.editInteractiveMessage ?? (async () => {}),
+              sendInteractiveMessage:
+                deps.sendInteractiveMessage ?? (async () => undefined),
+              enqueuePrompt: deps.enqueueSectionPrompt
+                ? (prompt: string) => deps.enqueueSectionPrompt!(prompt, ctx)
+                : async () => {},
+            },
+          );
+          if (handled) return;
+        }
+      }
+    }
+  }
   await handleStoredTelegramMenuCallback(query, {
     getStoredModelMenuState: deps.getStoredModelMenuState,
     handleStatusAction: async (state) =>
@@ -601,6 +727,7 @@ export function createTelegramMenuActionRuntimeWithStateBuilder<
     sendTextReply: deps.sendTextReply,
     editInteractiveMessage: deps.editInteractiveMessage,
     sendInteractiveMessage: deps.sendInteractiveMessage,
+    sectionRegistry: deps.sectionRegistry,
   });
 }
 
@@ -628,6 +755,7 @@ export function createTelegramMenuActionRuntime<
         deps.getThinkingLevel(),
         deps,
         deps.getQueueItemCount?.() ?? 0,
+        deps.sectionRegistry,
       ),
     sendStatusMessage: (chatId, replyToMessageId, ctx) =>
       openTelegramStatusMenu({
@@ -658,6 +786,7 @@ export function createTelegramMenuActionRuntime<
             thinkingLevel,
             deps,
             queueItemCount,
+            deps.sectionRegistry,
           ),
         storeModelMenuState: deps.storeModelMenuState,
       }),

package/lib/replies.ts

@@ -430,8 +430,7 @@ export function dedupSendMarkdownReply<TReplyMarkup = unknown>(
 /**
  * Guest reply sender: renders Markdown → HTML, sends via answerGuestQuery.
  * Keeps guest rendering inside the replies domain so the orchestration layer
- * (index.ts) does not import from rendering.ts directly.
- */
+ * (index.ts) does not import from rendering.ts directly. */
 export function createGuestMarkdownReplySender(deps: {
   renderTelegramMessage: (
     text: string,

package/lib/routing.ts

@@ -4,21 +4,22 @@
  * Wires authorized updates into menus, commands, media grouping, and prompt queueing
  */
 
-import * as OutboundHandlers from "./outbound-handlers.ts";
-import * as Commands from "./commands.ts";
 import { readFile } from "node:fs/promises";
+import * as Commands from "./commands.ts";
 import type { TelegramConfigStore } from "./config.ts";
+import type { TelegramSectionRegistry } from "./extension-sections.ts";
 import type { TelegramInboundHandlerRuntime } from "./inbound-handlers.ts";
 import * as Media from "./media.ts";
 import * as Menu from "./menu.ts";
 import * as Model from "./model.ts";
-import * as Queue from "./queue.ts";
+import * as OutboundHandlers from "./outbound-handlers.ts";
 import * as PromptTemplates from "./prompt-templates.ts";
+import * as Queue from "./queue.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
 import * as TextGroups from "./text-groups.ts";
 import * as Turns from "./turns.ts";
-import * as Updates from "./updates.ts";
 import type { TelegramUser } from "./updates.ts";
+import * as Updates from "./updates.ts";
 
 export type TelegramRoutedMessage = Updates.TelegramUpdateMessage &
   Media.TelegramMediaMessage &
@@ -82,6 +83,19 @@ export interface TelegramInboundRouteRuntimeDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
+  editInteractiveMessage?: (
+    chatId: number,
+    messageId: number,
+    text: string,
+    mode: "html" | "plain",
+    replyMarkup: Menu.TelegramReplyMarkup,
+  ) => Promise<void>;
+  sendInteractiveMessage?: (
+    chatId: number,
+    text: string,
+    mode: "html" | "plain",
+    replyMarkup: Menu.TelegramReplyMarkup,
+  ) => Promise<number | undefined>;
   answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
   sendTextReply: (
     chatId: number,
@@ -112,12 +126,14 @@ export interface TelegramInboundRouteRuntimeDeps<
     error: unknown,
     details?: Record<string, unknown>,
   ) => void;
+  sectionRegistry?: TelegramSectionRegistry;
 }
 
 const TELEGRAM_OWNED_CALLBACK_PREFIXES = [
   "menu:",
   "model:",
   "queue:",
+  "section:",
   "settings:",
   "status:",
   "tgbtn:",
@@ -174,6 +190,35 @@ export function createTelegramInboundRouteRuntime<
     stagePendingModelSwitch: deps.modelSwitchController.stagePendingSwitch,
     restartInterruptedTelegramTurn:
       deps.modelSwitchController.restartInterruptedTurn,
+    sectionRegistry: deps.sectionRegistry,
+    editInteractiveMessage: deps.editInteractiveMessage,
+    sendInteractiveMessage: deps.sendInteractiveMessage,
+    enqueueSectionPrompt: async (prompt: string, ctx: TContext) => {
+      const chatId = deps.configStore.getAllowedUserId();
+      if (typeof chatId !== "number") return;
+      const order = deps.bridgeRuntime.queue.allocateItemOrder();
+      const turn: Queue.PendingTelegramTurn = {
+        kind: "prompt",
+        chatId,
+        replyToMessageId: 0,
+        sourceMessageIds: [],
+        queueOrder: order,
+        queueLane: "default",
+        laneOrder: order,
+        queuedAttachments: [],
+        content: [
+          {
+            type: "text",
+            text: `[telegram] ${prompt}`,
+          },
+        ],
+        historyText: Turns.truncateTelegramQueueSummary(prompt),
+        statusSummary: Turns.truncateTelegramQueueSummary(prompt),
+      };
+      deps.queueMutationRuntime.append(turn, ctx);
+      deps.updateStatus(ctx);
+      deps.dispatchNextQueuedTelegramTurn(ctx);
+    },
   });
   const callbackHandler = async (
     query: TCallbackQuery,
@@ -376,9 +421,7 @@ export function createTelegramInboundRouteRuntime<
     // Build telegram prefix with guest context
     const fromRaw = gm.from as Record<string, unknown> | undefined;
     const fromName =
-      (fromRaw?.username as string) ||
-      (fromRaw?.first_name as string) ||
-      "";
+      (fromRaw?.username as string) || (fromRaw?.first_name as string) || "";
     const chatRaw = gm.chat as Record<string, unknown>;
     const chatTitle = chatRaw?.title as string | undefined;
     const chatType = chatRaw?.type as string;
@@ -390,20 +433,24 @@ export function createTelegramInboundRouteRuntime<
     const telegramPrefix = `[${prefixParts.join("|")}]`;
     // Extract reply context
     const replyMsg = gm.reply_to_message as Record<string, unknown> | undefined;
-    const replyText =
-      replyMsg
-        ? ((replyMsg.text as string) || (replyMsg.caption as string) || "").trim()
-        : "";
-    const replyFrom =
-      replyMsg
-        ? (replyMsg.from as Record<string, unknown> | undefined)?.username as string | undefined
-        : undefined;
+    const replyText = replyMsg
+      ? ((replyMsg.text as string) || (replyMsg.caption as string) || "").trim()
+      : "";
+    const replyFrom = replyMsg
+      ? ((replyMsg.from as Record<string, unknown> | undefined)?.username as
+          | string
+          | undefined)
+      : undefined;
     // Download files, run inbound handlers
     const guestMsg = guestMessage as unknown as Media.TelegramMediaMessage;
     const files = await Media.downloadTelegramMessageFiles([guestMsg], {
       downloadFile: deps.downloadFile,
     });
-    const processed = await deps.inboundHandlerRuntime.process(files, text, ctx);
+    const processed = await deps.inboundHandlerRuntime.process(
+      files,
+      text,
+      ctx,
+    );
     let rawText = processed.rawText || text;
     // Append reply context after handler processing
     if (replyText) {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.9.9",
+  "version": "0.10.1",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
-  "description": "Telegram Runtime Adapter for π",
+  "description": "Telegram runtime adapter for π",
   "type": "module",
   "keywords": [
     "pi-package",