@llblab/pi-telegram 0.3.0 → 0.5.0

package/index.ts

@@ -7,20 +7,22 @@ import * as Api from "./lib/api.ts";
 import * as Attachments from "./lib/attachments.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
+import * as Handlers from "./lib/handlers.ts";
+import * as Lifecycle from "./lib/lifecycle.ts";
+import * as Locks from "./lib/locks.ts";
 import * as Media from "./lib/media.ts";
 import * as Menu from "./lib/menu.ts";
 import * as Model from "./lib/model.ts";
 import * as Pi from "./lib/pi.ts";
 import * as Polling from "./lib/polling.ts";
 import * as Preview from "./lib/preview.ts";
+import * as Prompts from "./lib/prompts.ts";
 import * as Queue from "./lib/queue.ts";
-import * as Registration from "./lib/registration.ts";
 import * as Replies from "./lib/replies.ts";
 import * as Runtime from "./lib/runtime.ts";
+import * as Routing from "./lib/routing.ts";
 import * as Setup from "./lib/setup.ts";
 import * as Status from "./lib/status.ts";
-import * as Turns from "./lib/turns.ts";
-import * as Updates from "./lib/updates.ts";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
 type RuntimeTelegramQueueItem = Queue.TelegramQueueItem<Pi.ExtensionContext>;
@@ -31,6 +33,7 @@ export default function (pi: Pi.ExtensionAPI) {
   const piRuntime = Pi.createExtensionApiRuntimePorts(pi);
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
   const configStore = Config.createTelegramConfigStore();
+  const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const activeTurnRuntime = Queue.createTelegramActiveTurnStore();
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
@@ -63,6 +66,7 @@ export default function (pi: Pi.ExtensionAPI) {
       getQueuedItems: telegramQueueStore.getQueuedItems,
       formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
       getRecentRuntimeEvents: runtimeEvents.getEvents,
+      getRuntimeLockState: lockRuntime.getStatusLabel,
     });
   const currentModelRuntime = Model.createCurrentModelRuntime<
     Pi.ExtensionContext,
@@ -80,6 +84,13 @@ export default function (pi: Pi.ExtensionAPI) {
         bridgeRuntime.queue.incrementNextPriorityReactionOrder,
       updateStatus,
     });
+  const attachmentHandlerRuntime =
+    Handlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>({
+      getHandlers: configStore.getAttachmentHandlers,
+      execCommand: piRuntime.exec,
+      getCwd: Pi.getExtensionContextCwd,
+      recordRuntimeEvent: runtimeEvents.record,
+    });
 
   // --- Telegram API ---
 
@@ -202,158 +213,52 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: Updates.createTelegramPairedUpdateRuntime<
+    handleUpdate: Routing.createTelegramInboundRouteRuntime<
+      Api.TelegramUpdate,
+      Api.TelegramMessage,
+      Api.TelegramCallbackQuery,
       Pi.ExtensionContext,
-      Api.TelegramUpdate
+      ActivePiModel
     >({
-      getAllowedUserId: configStore.getAllowedUserId,
-      setAllowedUserId: configStore.setAllowedUserId,
-      persistConfig: configStore.persist,
+      configStore,
+      bridgeRuntime,
+      activeTurnRuntime,
+      mediaGroupRuntime,
+      telegramQueueStore,
+      queueMutationRuntime,
+      modelMenuRuntime,
+      currentModelRuntime,
+      modelSwitchController,
+      menuActions,
+      attachmentHandlerRuntime,
       updateStatus,
-      removePendingMediaGroupMessages: mediaGroupRuntime.removeMessages,
-      removeQueuedTelegramTurnsByMessageIds:
-        queueMutationRuntime.removeByMessageIds,
-      clearQueuedTelegramTurnPriorityByMessageId:
-        queueMutationRuntime.clearPriorityByMessageId,
-      prioritizeQueuedTelegramTurnByMessageId:
-        queueMutationRuntime.prioritizeByMessageId,
+      dispatchNextQueuedTelegramTurn,
       answerCallbackQuery,
-      handleAuthorizedTelegramCallbackQuery:
-        Menu.createTelegramMenuCallbackHandlerForContext<
-          Api.TelegramCallbackQuery,
-          Pi.ExtensionContext,
-          ActivePiModel
-        >({
-          getStoredModelMenuState: modelMenuRuntime.getState,
-          getActiveModel: currentModelRuntime.get,
-          getThinkingLevel: piRuntime.getThinkingLevel,
-          setThinkingLevel: piRuntime.setThinkingLevel,
-          updateStatus,
-          updateModelMenuMessage: menuActions.updateModelMenuMessage,
-          updateThinkingMenuMessage: menuActions.updateThinkingMenuMessage,
-          updateStatusMessage: menuActions.updateStatusMessage,
-          answerCallbackQuery,
-          isIdle: Pi.isExtensionContextIdle,
-          hasActiveTelegramTurn: activeTurnRuntime.has,
-          hasAbortHandler: bridgeRuntime.abort.hasHandler,
-          getActiveToolExecutions:
-            bridgeRuntime.lifecycle.getActiveToolExecutions,
-          setModel: piRuntime.setModel,
-          setCurrentModel: currentModelRuntime.setCurrentModel,
-          stagePendingModelSwitch: modelSwitchController.stagePendingSwitch,
-          restartInterruptedTelegramTurn:
-            modelSwitchController.restartInterruptedTurn,
-        }),
       sendTextReply,
-      handleAuthorizedTelegramMessage:
-        Media.createTelegramMediaGroupDispatchRuntime<
-          Api.TelegramMessage,
-          Pi.ExtensionContext
-        >({
-          mediaGroups: mediaGroupRuntime,
-          dispatchMessages: Commands.createTelegramCommandOrPromptRuntime<
-            Api.TelegramMessage,
-            Pi.ExtensionContext
-          >({
-            extractRawText: Media.extractFirstTelegramMessageText,
-            handleCommand: Commands.createTelegramCommandHandlerTargetRuntime<
-              Api.TelegramMessage,
-              Pi.ExtensionContext
-            >({
-              hasAbortHandler: bridgeRuntime.abort.hasHandler,
-              clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
-              hasQueuedTelegramItems: telegramQueueStore.hasQueuedItems,
-              setPreserveQueuedTurnsAsHistory:
-                bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
-              abortCurrentTurn: bridgeRuntime.abort.abortTurn,
-              isIdle: Pi.isExtensionContextIdle,
-              hasPendingMessages: Pi.hasExtensionContextPendingMessages,
-              hasActiveTelegramTurn: activeTurnRuntime.has,
-              hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
-              isCompactionInProgress:
-                bridgeRuntime.lifecycle.isCompactionInProgress,
-              setCompactionInProgress:
-                bridgeRuntime.lifecycle.setCompactionInProgress,
-              updateStatus,
-              dispatchNextQueuedTelegramTurn,
-              compact: Pi.compactExtensionContext,
-              allocateItemOrder: bridgeRuntime.queue.allocateItemOrder,
-              allocateControlOrder: bridgeRuntime.queue.allocateControlOrder,
-              appendControlItem: queueMutationRuntime.append,
-              showStatus: menuActions.sendStatusMessage,
-              openModelMenu: menuActions.openModelMenu,
-              getAllowedUserId: configStore.getAllowedUserId,
-              setAllowedUserId: configStore.setAllowedUserId,
-              setMyCommands,
-              persistConfig: configStore.persist,
-              sendTextReply,
-              recordRuntimeEvent: runtimeEvents.record,
-            }),
-            enqueueTurn: Queue.createTelegramPromptEnqueueController<
-              Api.TelegramMessage,
-              Pi.ExtensionContext
-            >({
-              ...telegramQueueStore,
-              getPreserveQueuedTurnsAsHistory:
-                bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory,
-              setPreserveQueuedTurnsAsHistory:
-                bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
-              createTurn:
-                Turns.createTelegramPromptTurnRuntimeBuilder<Api.TelegramMessage>(
-                  {
-                    allocateQueueOrder: bridgeRuntime.queue.allocateItemOrder,
-                    downloadFile: downloadTelegramBridgeFile,
-                  },
-                ),
-              updateStatus,
-              dispatchNextQueuedTelegramTurn,
-            }).enqueue,
-          }).dispatchMessages,
-        }).handleMessage,
-      handleAuthorizedTelegramEditedMessage:
-        Turns.createTelegramQueuedPromptEditRuntime<
-          Api.TelegramMessage,
-          Pi.ExtensionContext
-        >({
-          ...telegramQueueStore,
-          updateStatus,
-        }).updateFromEditedMessage,
+      setMyCommands,
+      downloadFile: downloadTelegramBridgeFile,
+      getThinkingLevel: piRuntime.getThinkingLevel,
+      setThinkingLevel: piRuntime.setThinkingLevel,
+      setModel: piRuntime.setModel,
+      isIdle: Pi.isExtensionContextIdle,
+      hasPendingMessages: Pi.hasExtensionContextPendingMessages,
+      compact: Pi.compactExtensionContext,
+      recordRuntimeEvent: runtimeEvents.record,
     }).handleUpdate,
     stopTypingLoop: bridgeRuntime.typing.stop,
     updateStatus,
     recordRuntimeEvent: runtimeEvents.record,
   });
-
-  // --- Extension Registration ---
-
-  Registration.registerTelegramAttachmentTool(pi, {
-    getActiveTurn: activeTurnRuntime.get,
-    recordRuntimeEvent: runtimeEvents.record,
-  });
-
-  Registration.registerTelegramCommands(pi, {
-    promptForConfig: Setup.createTelegramSetupPromptRuntime({
-      getConfig: configStore.get,
-      setConfig: configStore.set,
-      setupGuard: bridgeRuntime.setup,
-      getMe: Api.fetchTelegramBotIdentity,
-      persistConfig: configStore.persist,
-      startPolling: pollingRuntime.start,
-      updateStatus,
-      recordRuntimeEvent: runtimeEvents.record,
-    }),
-    getStatusLines,
-    reloadConfig: configStore.load,
+  const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
+    lock: lockRuntime,
     hasBotToken: configStore.hasBotToken,
     startPolling: pollingRuntime.start,
     stopPolling: pollingRuntime.stop,
     updateStatus,
+    recordRuntimeEvent: runtimeEvents.record,
   });
-
-  // --- Lifecycle Hooks ---
-
-  Registration.registerTelegramLifecycleHooks(pi, {
-    ...Queue.createTelegramSessionLifecycleRuntime<
+  const sessionLifecycleRuntime = Lifecycle.appendTelegramLifecycleHooks(
+    Queue.createTelegramSessionLifecycleRuntime<
       Pi.ExtensionContext,
       RuntimeTelegramQueueItem,
       ActivePiModel
@@ -373,10 +278,43 @@ export default function (pi: Pi.ExtensionAPI) {
       clearPreview: previewRuntime.clear,
       clearActiveTurn: activeTurnRuntime.clear,
       clearAbort: bridgeRuntime.abort.clearHandler,
-      stopPolling: pollingRuntime.stop,
+      stopPolling: lockedPollingRuntime.suspend,
+      recordRuntimeEvent: runtimeEvents.record,
+    }),
+    { onSessionStart: lockedPollingRuntime.onSessionStart },
+  );
+
+  // --- Extension API Bindings ---
+
+  Attachments.registerTelegramAttachmentTool(pi, {
+    getActiveTurn: activeTurnRuntime.get,
+    recordRuntimeEvent: runtimeEvents.record,
+  });
+
+  Commands.registerTelegramBridgeCommands(pi, {
+    promptForConfig: Setup.createTelegramSetupPromptRuntime({
+      getConfig: configStore.get,
+      setConfig: configStore.set,
+      setupGuard: bridgeRuntime.setup,
+      getMe: Api.fetchTelegramBotIdentity,
+      persistConfig: configStore.persist,
+      startPolling: lockedPollingRuntime.start,
+      updateStatus,
       recordRuntimeEvent: runtimeEvents.record,
     }),
-    onBeforeAgentStart: Registration.createTelegramBeforeAgentStartHook(),
+    getStatusLines,
+    reloadConfig: configStore.load,
+    hasBotToken: configStore.hasBotToken,
+    startPolling: lockedPollingRuntime.start,
+    stopPolling: lockedPollingRuntime.stop,
+    updateStatus,
+  });
+
+  // --- Lifecycle Hooks ---
+
+  Lifecycle.registerTelegramLifecycleHooks(pi, {
+    ...sessionLifecycleRuntime,
+    onBeforeAgentStart: Prompts.createTelegramBeforeAgentStartHook(),
     onModelSelect: currentModelRuntime.onModelSelect,
     ...Queue.createTelegramAgentLifecycleHooks<
       Queue.PendingTelegramTurn,

package/lib/attachments.ts

@@ -1,13 +1,18 @@
 /**
  * Telegram attachment domain helpers
- * Owns attachment queueing and attachment delivery so Telegram file output stays in one domain module
+ * Owns telegram_attach registration, attachment queueing, and attachment delivery so Telegram file output stays in one domain module
  */
 
 import { stat } from "node:fs/promises";
 import { basename } from "node:path";
 
+import { Type } from "@sinclair/typebox";
+
+import type { ExtensionAPI } from "./pi.ts";
 import { buildTelegramMultipartReplyParameters } from "./replies.ts";
 
+const MAX_ATTACHMENTS_PER_TURN = 10;
+
 export const TELEGRAM_OUTBOUND_ATTACHMENT_DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
 
 export function getTelegramAttachmentByteLimitFromEnv(
@@ -35,6 +40,21 @@ export interface TelegramAttachmentToolResult {
   details: { paths: string[] };
 }
 
+export interface TelegramAttachmentRuntimeEventRecorderPort {
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
+export interface TelegramAttachmentToolRegistrationDeps extends TelegramAttachmentRuntimeEventRecorderPort {
+  maxAttachmentsPerTurn?: number;
+  maxAttachmentSizeBytes?: number;
+  getActiveTurn: () => TelegramAttachmentQueueTargetView | undefined;
+  statPath?: (path: string) => Promise<{ isFile(): boolean; size?: number }>;
+}
+
 export interface TelegramQueuedAttachmentView {
   path: string;
   fileName: string;
@@ -69,6 +89,54 @@ function formatTelegramAttachmentSizeLimitError(
   return path ? `${message}: ${path}` : message;
 }
 
+function formatTelegramAttachmentToolResultText(count: number): string {
+  // Pi's compact tool rows need an empty first line to visually separate header and result
+  return ["", `Queued ${count} Telegram attachment(s).`].join("\n");
+}
+
+export function registerTelegramAttachmentTool(
+  pi: ExtensionAPI,
+  deps: TelegramAttachmentToolRegistrationDeps,
+): void {
+  const maxAttachmentsPerTurn =
+    deps.maxAttachmentsPerTurn ?? MAX_ATTACHMENTS_PER_TURN;
+  const maxAttachmentSizeBytes =
+    deps.maxAttachmentSizeBytes ?? TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES;
+  pi.registerTool({
+    name: "telegram_attach",
+    label: "Telegram Attach",
+    description:
+      "Queue one or more local files to be sent with the next Telegram reply.",
+    promptSnippet: "Queue local files to be sent with the next Telegram reply.",
+    promptGuidelines: [
+      "When handling a [telegram] message and the user asked for a file or generated artifact, call telegram_attach with the local path instead of only mentioning the path in text.",
+    ],
+    parameters: Type.Object({
+      paths: Type.Array(
+        Type.String({ description: "Local file path to attach" }),
+        { minItems: 1, maxItems: maxAttachmentsPerTurn },
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      try {
+        return await queueTelegramAttachments({
+          activeTurn: deps.getActiveTurn(),
+          paths: params.paths,
+          maxAttachmentsPerTurn,
+          maxAttachmentSizeBytes,
+          statPath: deps.statPath,
+        });
+      } catch (error) {
+        deps.recordRuntimeEvent?.("attachment", error, {
+          phase: "queue",
+          count: params.paths.length,
+        });
+        throw error;
+      }
+    },
+  });
+}
+
 export interface TelegramQueuedAttachmentDeliveryDeps {
   sendMultipart: (
     method: string,
@@ -141,7 +209,7 @@ export async function queueTelegramAttachments(options: {
     content: [
       {
         type: "text",
-        text: `Queued ${added.length} Telegram attachment(s).`,
+        text: formatTelegramAttachmentToolResultText(added.length),
       },
     ],
     details: { paths: added },

package/lib/commands.ts

@@ -1,9 +1,10 @@
 /**
  * Telegram command routing helpers
- * Owns slash-command normalization and command side-effect branching behind runtime ports
+ * Owns Telegram slash-command normalization, bot command metadata, and pi-side command registration behind runtime ports
  */
 
 import { pairTelegramUserIfNeeded } from "./config.ts";
+import type { ExtensionAPI, ExtensionCommandContext } from "./pi.ts";
 import {
   createTelegramControlItemBuilder,
   createTelegramControlQueueController,
@@ -52,22 +53,115 @@ export function createTelegramBotCommandRegistrar(
   return () => registerTelegramBotCommands(deps);
 }
 
+export interface TelegramBridgeCommandStartPollingOptions {
+  force?: boolean;
+}
+
+export interface TelegramBridgeCommandStartPollingResult {
+  ok: boolean;
+  message?: string;
+  canTakeover?: boolean;
+  owner?: string;
+}
+
+export interface TelegramBridgeCommandRegistrationDeps {
+  promptForConfig: (ctx: ExtensionCommandContext) => Promise<void>;
+  getStatusLines: () => string[];
+  reloadConfig: () => Promise<void>;
+  hasBotToken: () => boolean;
+  startPolling: (
+    ctx: ExtensionCommandContext,
+    options?: TelegramBridgeCommandStartPollingOptions,
+  ) =>
+    | void
+    | Promise<void | TelegramBridgeCommandStartPollingResult>
+    | TelegramBridgeCommandStartPollingResult;
+  stopPolling: () => Promise<void | string>;
+  updateStatus: (ctx: ExtensionCommandContext) => void;
+}
+
+function formatTelegramTakeoverTitle(ctx: ExtensionCommandContext): string {
+  return ctx.ui.theme.fg("accent", "pi-telegram");
+}
+
+function formatTelegramTakeoverPrompt(
+  ctx: ExtensionCommandContext,
+  owner?: string,
+): string {
+  const theme = ctx.ui.theme;
+  const action = theme.fg("warning", "move singleton lock here?");
+  const from = theme.fg("muted", "from:");
+  const to = theme.fg("muted", "to:");
+  const source = owner ?? "another pi instance";
+  return `${action}\n\n${from} ${source}\n${to} ${ctx.cwd}`;
+}
+
+export function registerTelegramBridgeCommands(
+  pi: ExtensionAPI,
+  deps: TelegramBridgeCommandRegistrationDeps,
+): void {
+  pi.registerCommand("telegram-setup", {
+    description: "Configure Telegram bot token",
+    handler: async (_args, ctx) => {
+      await deps.promptForConfig(ctx);
+    },
+  });
+  pi.registerCommand("telegram-status", {
+    description: "Show Telegram bridge status",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(deps.getStatusLines().join("\n"), "info");
+    },
+  });
+  pi.registerCommand("telegram-connect", {
+    description: "Start the Telegram bridge in this pi session",
+    handler: async (_args, ctx) => {
+      await deps.reloadConfig();
+      if (!deps.hasBotToken()) {
+        await deps.promptForConfig(ctx);
+        return;
+      }
+      let result = await deps.startPolling(ctx);
+      if (result && !result.ok && result.canTakeover) {
+        const confirmed = await ctx.ui.confirm(
+          formatTelegramTakeoverTitle(ctx),
+          formatTelegramTakeoverPrompt(ctx, result.owner),
+        );
+        if (!confirmed) {
+          ctx.ui.notify("Telegram bridge takeover cancelled.", "info");
+          deps.updateStatus(ctx);
+          return;
+        }
+        result = await deps.startPolling(ctx, { force: true });
+      }
+      if (result?.message) {
+        ctx.ui.notify(result.message, result.ok ? "info" : "warning");
+      }
+      deps.updateStatus(ctx);
+    },
+  });
+  pi.registerCommand("telegram-disconnect", {
+    description: "Stop the Telegram bridge in this pi session",
+    handler: async (_args, ctx) => {
+      const message = await deps.stopPolling();
+      if (message) ctx.ui.notify(message, "info");
+      deps.updateStatus(ctx);
+    },
+  });
+}
+
 export type TelegramCommandAction =
   | { kind: "ignore"; executionMode: "ignored" }
   | { kind: "stop"; executionMode: "immediate" }
   | { kind: "compact"; executionMode: "immediate" }
-  | { kind: "status"; executionMode: "control-queue" }
-  | { kind: "model"; executionMode: "control-queue" }
+  | { kind: "status"; executionMode: "immediate" }
+  | { kind: "model"; executionMode: "immediate" }
   | {
       kind: "help";
       commandName: "help" | "start";
       executionMode: "immediate";
     };
 
-export type TelegramCommandExecutionMode =
-  | "ignored"
-  | "immediate"
-  | "control-queue";
+export type TelegramCommandExecutionMode = "ignored" | "immediate";
 
 export interface TelegramCommandActionDeps<TMessage, TContext> {
   handleStop: (message: TMessage, ctx: TContext) => Promise<void>;
@@ -99,8 +193,7 @@ export interface TelegramRuntimeEventRecorderPort {
   ) => void;
 }
 
-export interface TelegramCompactCommandDeps
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramCompactCommandDeps extends TelegramRuntimeEventRecorderPort {
   isIdle: () => boolean;
   hasPendingMessages: () => boolean;
   hasActiveTelegramTurn: () => boolean;
@@ -130,14 +223,6 @@ export interface TelegramHelpCommandDeps {
 export type TelegramControlCommandType =
   PendingTelegramControlItem<unknown>["controlType"];
 
-export interface TelegramQueuedControlCommandDeps<TContext> {
-  enqueueControlItem: (
-    controlType: TelegramControlCommandType,
-    statusSummary: string,
-    execute: (ctx: TContext) => Promise<void>,
-  ) => void;
-}
-
 export interface TelegramCommandRuntimeMessage {
   chat: { id: number };
   message_id: number;
@@ -380,9 +465,9 @@ export function buildTelegramCommandAction(
     case "compact":
       return { kind: "compact", executionMode: "immediate" };
     case "status":
-      return { kind: "status", executionMode: "control-queue" };
+      return { kind: "status", executionMode: "immediate" };
     case "model":
-      return { kind: "model", executionMode: "control-queue" };
+      return { kind: "model", executionMode: "immediate" };
     case "help":
     case "start":
       return { kind: "help", commandName, executionMode: "immediate" };
@@ -483,20 +568,18 @@ export async function handleTelegramHelpCommand(
   });
 }
 
-export async function handleTelegramStatusCommand<TContext>(
-  deps: TelegramQueuedControlCommandDeps<TContext> & {
-    showStatus: (ctx: TContext) => Promise<void>;
-  },
-): Promise<void> {
-  deps.enqueueControlItem("status", "⚡ status", deps.showStatus);
+export async function handleTelegramStatusCommand<TContext>(deps: {
+  ctx: TContext;
+  showStatus: (ctx: TContext) => Promise<void>;
+}): Promise<void> {
+  await deps.showStatus(deps.ctx);
 }
 
-export async function handleTelegramModelCommand<TContext>(
-  deps: TelegramQueuedControlCommandDeps<TContext> & {
-    openModelMenu: (ctx: TContext) => Promise<void>;
-  },
-): Promise<void> {
-  deps.enqueueControlItem("model", "⚡ model", deps.openModelMenu);
+export async function handleTelegramModelCommand<TContext>(deps: {
+  ctx: TContext;
+  openModelMenu: (ctx: TContext) => Promise<void>;
+}): Promise<void> {
+  await deps.openModelMenu(deps.ctx);
 }
 
 export async function executeTelegramCommandAction<TMessage, TContext>(
@@ -644,21 +727,6 @@ async function handleTelegramCommandRuntime<
     deps.sendTextReply(nextMessage, text);
   const updateStatusFor = (commandCtx: TContext) => () =>
     deps.updateStatus(commandCtx);
-  const enqueueControlFor =
-    (nextMessage: TMessage, commandCtx: TContext) =>
-    (
-      controlType: TelegramControlCommandType,
-      statusSummary: string,
-      execute: (ctx: TContext) => Promise<void>,
-    ) => {
-      deps.enqueueControlItem(
-        nextMessage,
-        commandCtx,
-        controlType,
-        statusSummary,
-        execute,
-      );
-    };
   return executeTelegramCommandAction(
     buildTelegramCommandAction(commandName),
     message,
@@ -694,13 +762,13 @@ async function handleTelegramCommandRuntime<
       },
       handleStatus: async (nextMessage, commandCtx) => {
         await handleTelegramStatusCommand<TContext>({
-          enqueueControlItem: enqueueControlFor(nextMessage, commandCtx),
+          ctx: commandCtx,
           showStatus: (controlCtx) => deps.showStatus(nextMessage, controlCtx),
         });
       },
       handleModel: async (nextMessage, commandCtx) => {
         await handleTelegramModelCommand<TContext>({
-          enqueueControlItem: enqueueControlFor(nextMessage, commandCtx),
+          ctx: commandCtx,
           openModelMenu: (controlCtx) =>
             deps.openModelMenu(nextMessage, controlCtx),
         });

package/lib/config.ts

@@ -5,10 +5,19 @@
 
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
-const AGENT_DIR = join(homedir(), ".pi", "agent");
-const CONFIG_PATH = join(AGENT_DIR, "telegram.json");
+import type { TelegramAttachmentHandlerConfig } from "./handlers.ts";
+
+function getAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR
+    ? resolve(process.env.PI_CODING_AGENT_DIR)
+    : join(homedir(), ".pi", "agent");
+}
+
+function getConfigPath(): string {
+  return join(getAgentDir(), "telegram.json");
+}
 
 export interface TelegramConfig {
   botToken?: string;
@@ -16,6 +25,7 @@ export interface TelegramConfig {
   botId?: number;
   allowedUserId?: number;
   lastUpdateId?: number;
+  attachmentHandlers?: TelegramAttachmentHandlerConfig[];
 }
 
 export interface TelegramConfigStore {
@@ -25,6 +35,7 @@ export interface TelegramConfigStore {
   getBotToken: () => string | undefined;
   hasBotToken: () => boolean;
   getAllowedUserId: () => number | undefined;
+  getAttachmentHandlers: () => TelegramAttachmentHandlerConfig[] | undefined;
   setAllowedUserId: (userId: number) => void;
   load: () => Promise<void>;
   persist: (config?: TelegramConfig) => Promise<void>;
@@ -64,8 +75,8 @@ export function createTelegramConfigStore(
   options: TelegramConfigStoreOptions = {},
 ): TelegramConfigStore {
   let config: TelegramConfig = options.initialConfig ?? {};
-  const agentDir = options.agentDir ?? AGENT_DIR;
-  const configPath = options.configPath ?? CONFIG_PATH;
+  const agentDir = options.agentDir ?? getAgentDir();
+  const configPath = options.configPath ?? getConfigPath();
   return {
     get: () => config,
     set: (nextConfig) => {
@@ -77,6 +88,7 @@ export function createTelegramConfigStore(
     getBotToken: () => config.botToken,
     hasBotToken: () => !!config.botToken,
     getAllowedUserId: () => config.allowedUserId,
+    getAttachmentHandlers: () => config.attachmentHandlers,
     setAllowedUserId: (userId) => {
       config.allowedUserId = userId;
     },