@llblab/pi-telegram 0.6.2 → 0.7.0

package/index.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram bridge extension entrypoint and orchestration layer
+ * Zones: telegram, pi agent, orchestration
  * Keeps the runtime wiring in one place while delegating reusable domain logic to /lib modules
  */
 
@@ -9,14 +10,17 @@ import * as Attachments from "./lib/attachments.ts";
 import * as Commands from "./lib/commands.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Config from "./lib/config.ts";
+import * as Keyboard from "./lib/keyboard.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 MenuQueue from "./lib/menu-queue.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 PromptTemplates from "./lib/prompt-templates.ts";
 import * as Prompts from "./lib/prompts.ts";
 import * as Queue from "./lib/queue.ts";
 import * as Replies from "./lib/replies.ts";
@@ -33,7 +37,15 @@ type RuntimeTelegramQueueItem = Queue.TelegramQueueItem<Pi.ExtensionContext>;
 
 export default function (pi: Pi.ExtensionAPI) {
   const piRuntime = Pi.createExtensionApiRuntimePorts(pi);
+  const {
+    getCommands,
+    getThinkingLevel,
+    sendUserMessage,
+    setModel,
+    setThinkingLevel,
+  } = piRuntime;
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
+  const { abort, lifecycle, queue, setup, typing } = bridgeRuntime;
   const configStore = Config.createTelegramConfigStore();
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const activeTurnRuntime = Queue.createTelegramActiveTurnStore();
@@ -46,6 +58,11 @@ export default function (pi: Pi.ExtensionAPI) {
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
+  const recordRuntimeEvent = runtimeEvents.record;
+  const getContextModel = Pi.getExtensionContextModel;
+  const isIdle = Pi.isExtensionContextIdle;
+  const hasPendingMessages = Pi.hasExtensionContextPendingMessages;
+  const compact = Pi.compactExtensionContext;
   const mediaGroupRuntime = Media.createTelegramMediaGroupController<
     Api.TelegramMessage,
     Pi.ExtensionContext
@@ -54,7 +71,7 @@ export default function (pi: Pi.ExtensionAPI) {
     Queue.createTelegramQueueStore<Pi.ExtensionContext>();
   const deferredQueueDispatchRuntime =
     Queue.createTelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>({
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
     });
   const pollingControllerState = Polling.createTelegramPollingControllerState();
   const { getStatusLines, updateStatus } =
@@ -68,9 +85,9 @@ export default function (pi: Pi.ExtensionAPI) {
       ),
       getActiveSourceMessageIds: activeTurnRuntime.getSourceMessageIds,
       hasActiveTurn: activeTurnRuntime.has,
-      hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
-      isCompactionInProgress: bridgeRuntime.lifecycle.isCompactionInProgress,
-      getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
+      hasDispatchPending: lifecycle.hasDispatchPending,
+      isCompactionInProgress: lifecycle.isCompactionInProgress,
+      getActiveToolExecutions: lifecycle.getActiveToolExecutions,
       hasPendingModelSwitch: pendingModelSwitchStore.has,
       getQueuedItems: telegramQueueStore.getQueuedItems,
       formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
@@ -81,16 +98,15 @@ export default function (pi: Pi.ExtensionAPI) {
     Pi.ExtensionContext,
     ActivePiModel
   >({
-    getContextModel: Pi.getExtensionContextModel,
+    getContextModel,
     updateStatus,
   });
   const queueMutationRuntime =
     Queue.createTelegramQueueMutationController<Pi.ExtensionContext>({
       ...telegramQueueStore,
-      getNextPriorityReactionOrder:
-        bridgeRuntime.queue.getNextPriorityReactionOrder,
+      getNextPriorityReactionOrder: queue.getNextPriorityReactionOrder,
       incrementNextPriorityReactionOrder:
-        bridgeRuntime.queue.incrementNextPriorityReactionOrder,
+        queue.incrementNextPriorityReactionOrder,
       updateStatus,
     });
   const attachmentHandlerRuntime =
@@ -99,7 +115,7 @@ export default function (pi: Pi.ExtensionAPI) {
         getHandlers: configStore.getAttachmentHandlers,
         execCommand: CommandTemplates.execCommandTemplate,
         getCwd: Pi.getExtensionContextCwd,
-        recordRuntimeEvent: runtimeEvents.record,
+        recordRuntimeEvent,
       },
     );
 
@@ -119,19 +135,19 @@ export default function (pi: Pi.ExtensionAPI) {
     prepareTempDir,
   } = Api.createDefaultTelegramBridgeApiRuntime({
     getBotToken: configStore.getBotToken,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
   });
 
   // --- Message Delivery & Preview ---
 
   const promptDispatchRuntime =
     Runtime.createTelegramPromptDispatchRuntime<Pi.ExtensionContext>({
-      lifecycle: bridgeRuntime.lifecycle,
-      typing: bridgeRuntime.typing,
+      lifecycle,
+      typing,
       getDefaultChatId: activeTurnRuntime.getChatId,
       sendTypingAction,
       updateStatus,
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
     });
 
   // --- Reply Runtime Wiring ---
@@ -143,7 +159,7 @@ export default function (pi: Pi.ExtensionAPI) {
     editInteractiveMessage,
     sendInteractiveMessage,
   } =
-    Replies.createTelegramRenderedMessageDeliveryRuntime<Menu.TelegramReplyMarkup>(
+    Replies.createTelegramRenderedMessageDeliveryRuntime<Keyboard.TelegramInlineKeyboardMarkup>(
       {
         sendMessage,
         editMessage: editTelegramMessageText,
@@ -152,19 +168,22 @@ export default function (pi: Pi.ExtensionAPI) {
   const dispatchNextQueuedTelegramTurn =
     Queue.createTelegramQueueDispatchRuntime<Pi.ExtensionContext>({
       ...telegramQueueStore,
-      isCompactionInProgress: bridgeRuntime.lifecycle.isCompactionInProgress,
+      isCompactionInProgress: lifecycle.isCompactionInProgress,
       hasActiveTurn: activeTurnRuntime.has,
-      hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
-      isIdle: Pi.isExtensionContextIdle,
-      hasPendingMessages: Pi.hasExtensionContextPendingMessages,
+      hasDispatchPending: lifecycle.hasDispatchPending,
+      isIdle,
+      hasPendingMessages,
       hasDispatchContext: deferredQueueDispatchRuntime.isBound,
       updateStatus,
       sendTextReply,
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
       ...promptDispatchRuntime,
-      sendUserMessage: piRuntime.sendUserMessage,
+      sendUserMessage,
     }).dispatchNext;
-  const previewRuntime = Preview.createTelegramAssistantPreviewRuntime({
+  const previewRuntime = Preview.createTelegramAssistantPreviewRuntime<
+    unknown,
+    Keyboard.TelegramInlineKeyboardMarkup
+  >({
     getActiveTurn: activeTurnRuntime.get,
     isAssistantMessage: Replies.isAssistantAgentMessage,
     getMessageText: Replies.getAgentMessageText,
@@ -182,18 +201,26 @@ export default function (pi: Pi.ExtensionAPI) {
       Pi.ExtensionContext,
       Model.ScopedTelegramModel<ActivePiModel>
     >({
-      isIdle: Pi.isExtensionContextIdle,
+      isIdle,
       getPendingModelSwitch: pendingModelSwitchStore.get,
       setPendingModelSwitch: pendingModelSwitchStore.set,
       getActiveTurn: activeTurnRuntime.get,
-      getAbortHandler: bridgeRuntime.abort.getHandler,
-      hasAbortHandler: bridgeRuntime.abort.hasHandler,
-      getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
-      allocateItemOrder: bridgeRuntime.queue.allocateItemOrder,
-      allocateControlOrder: bridgeRuntime.queue.allocateControlOrder,
+      getAbortHandler: abort.getHandler,
+      hasAbortHandler: abort.hasHandler,
+      getActiveToolExecutions: lifecycle.getActiveToolExecutions,
+      allocateItemOrder: queue.allocateItemOrder,
+      allocateControlOrder: queue.allocateControlOrder,
       appendQueuedItem: queueMutationRuntime.append,
       updateStatus,
     });
+  const getQueueItemCount = Queue.createTelegramQueueItemCountGetter(
+    telegramQueueStore,
+  );
+  const getPromptTemplateCommands =
+    PromptTemplates.createTelegramPromptTemplateCommandGetter({
+      getCommands,
+      reservedCommandNames: Commands.TELEGRAM_RESERVED_COMMAND_NAMES,
+    });
   const menuActions = Menu.createTelegramMenuActionRuntimeWithStateBuilder<
     ActivePiModel,
     Pi.ExtensionContext
@@ -201,20 +228,80 @@ export default function (pi: Pi.ExtensionAPI) {
     runtime: modelMenuRuntime,
     createSettingsManager: Pi.createSettingsManager,
     getActiveModel: currentModelRuntime.get,
-    getThinkingLevel: piRuntime.getThinkingLevel,
-    buildStatusHtml: Status.createTelegramStatusHtmlBuilder({
-      getActiveModel: currentModelRuntime.get,
+    getThinkingLevel,
+    getQueueItemCount,
+    buildStatusHtml: Commands.createTelegramAppMenuHtmlBuilder({
+      buildStatusHtml: Status.createTelegramStatusHtmlBuilder({
+        getActiveModel: currentModelRuntime.get,
+      }),
+      getPromptTemplateCommands,
     }),
     storeModelMenuState: modelMenuRuntime.storeState,
-    isIdle: Pi.isExtensionContextIdle,
+    isIdle,
     canOfferInFlightModelSwitch: modelSwitchController.canOfferInFlightSwitch,
     sendTextReply,
     editInteractiveMessage,
     sendInteractiveMessage,
   });
 
+  // --- Queue Menu ---
+
+  const getQueueMenuState = Menu.createTelegramModelMenuStateBuilder({
+    runtime: modelMenuRuntime,
+    createSettingsManager: Pi.createSettingsManager,
+    getActiveModel: currentModelRuntime.get,
+  });
+  const queueMenuRuntime = MenuQueue.createTelegramQueueMenuRuntime({
+    telegramQueueStore,
+    queueMutationRuntime,
+    sendInteractiveMessage,
+    editInteractiveMessage,
+    answerCallbackQuery,
+    getModelMenuState: getQueueMenuState,
+    getStoredModelMenuState: modelMenuRuntime.getState,
+    storeModelMenuState: modelMenuRuntime.storeState,
+    updateStatusMessage: menuActions.updateStatusMessage,
+    updateStatus,
+  });
+
   // --- Polling ---
 
+  const inboundRouteRuntime = Routing.createTelegramInboundRouteRuntime<
+    Api.TelegramUpdate,
+    Api.TelegramMessage,
+    Api.TelegramCallbackQuery,
+    Pi.ExtensionContext,
+    ActivePiModel
+  >({
+    configStore,
+    bridgeRuntime,
+    activeTurnRuntime,
+    mediaGroupRuntime,
+    telegramQueueStore,
+    queueMutationRuntime,
+    modelMenuRuntime,
+    currentModelRuntime,
+    modelSwitchController,
+    menuActions,
+    openQueueMenu: queueMenuRuntime.openQueueMenu,
+    queueMenuCallbackHandler: queueMenuRuntime.handleCallbackQuery,
+    buttonActionStore,
+    attachmentHandlerRuntime,
+    updateStatus,
+    dispatchNextQueuedTelegramTurn,
+    answerCallbackQuery,
+    sendTextReply,
+    setMyCommands,
+    getCommands,
+    downloadFile: downloadTelegramBridgeFile,
+    getThinkingLevel,
+    setThinkingLevel,
+    setModel,
+    isIdle,
+    hasPendingMessages,
+    compact,
+    recordRuntimeEvent,
+  });
   const pollingRuntime = Polling.createTelegramPollingControllerRuntime<
     Api.TelegramUpdate,
     Pi.ExtensionContext
@@ -225,42 +312,10 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: Routing.createTelegramInboundRouteRuntime<
-      Api.TelegramUpdate,
-      Api.TelegramMessage,
-      Api.TelegramCallbackQuery,
-      Pi.ExtensionContext,
-      ActivePiModel
-    >({
-      configStore,
-      bridgeRuntime,
-      activeTurnRuntime,
-      mediaGroupRuntime,
-      telegramQueueStore,
-      queueMutationRuntime,
-      modelMenuRuntime,
-      currentModelRuntime,
-      modelSwitchController,
-      menuActions,
-      buttonActionStore,
-      attachmentHandlerRuntime,
-      updateStatus,
-      dispatchNextQueuedTelegramTurn,
-      answerCallbackQuery,
-      sendTextReply,
-      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,
+    handleUpdate: inboundRouteRuntime.handleUpdate,
+    stopTypingLoop: typing.stop,
     updateStatus,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
   });
   const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
     lock: lockRuntime,
@@ -268,34 +323,35 @@ export default function (pi: Pi.ExtensionAPI) {
     startPolling: pollingRuntime.start,
     stopPolling: pollingRuntime.stop,
     updateStatus,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
+  });
+  const queueSessionLifecycle = Queue.createTelegramSessionLifecycleRuntime<
+    Pi.ExtensionContext,
+    RuntimeTelegramQueueItem,
+    ActivePiModel
+  >({
+    getCurrentModel: getContextModel,
+    loadConfig: configStore.load,
+    setQueuedItems: telegramQueueStore.setQueuedItems,
+    setCurrentModel: currentModelRuntime.set,
+    setPendingModelSwitch: pendingModelSwitchStore.set,
+    syncCounters: queue.syncCounters,
+    syncFlags: lifecycle.syncFlags,
+    bindDeferredDispatchContext: deferredQueueDispatchRuntime.bind,
+    prepareTempDir,
+    updateStatus,
+    unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
+    clearPendingMediaGroups: mediaGroupRuntime.clear,
+    clearModelMenuState: modelMenuRuntime.clear,
+    getActiveTurnChatId: activeTurnRuntime.getChatId,
+    clearPreview: previewRuntime.clear,
+    clearActiveTurn: activeTurnRuntime.clear,
+    clearAbort: abort.clearHandler,
+    stopPolling: lockedPollingRuntime.suspend,
+    recordRuntimeEvent,
   });
   const sessionLifecycleRuntime = Lifecycle.appendTelegramLifecycleHooks(
-    Queue.createTelegramSessionLifecycleRuntime<
-      Pi.ExtensionContext,
-      RuntimeTelegramQueueItem,
-      ActivePiModel
-    >({
-      getCurrentModel: Pi.getExtensionContextModel,
-      loadConfig: configStore.load,
-      setQueuedItems: telegramQueueStore.setQueuedItems,
-      setCurrentModel: currentModelRuntime.set,
-      setPendingModelSwitch: pendingModelSwitchStore.set,
-      syncCounters: bridgeRuntime.queue.syncCounters,
-      syncFlags: bridgeRuntime.lifecycle.syncFlags,
-      bindDeferredDispatchContext: deferredQueueDispatchRuntime.bind,
-      prepareTempDir,
-      updateStatus,
-      unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
-      clearPendingMediaGroups: mediaGroupRuntime.clear,
-      clearModelMenuState: modelMenuRuntime.clear,
-      getActiveTurnChatId: activeTurnRuntime.getChatId,
-      clearPreview: previewRuntime.clear,
-      clearActiveTurn: activeTurnRuntime.clear,
-      clearAbort: bridgeRuntime.abort.clearHandler,
-      stopPolling: lockedPollingRuntime.suspend,
-      recordRuntimeEvent: runtimeEvents.record,
-    }),
+    queueSessionLifecycle,
     { onSessionStart: lockedPollingRuntime.onSessionStart },
   );
 
@@ -303,19 +359,19 @@ export default function (pi: Pi.ExtensionAPI) {
 
   Attachments.registerTelegramAttachmentTool(pi, {
     getActiveTurn: activeTurnRuntime.get,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
   });
 
   Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: Setup.createTelegramSetupPromptRuntime({
       getConfig: configStore.get,
       setConfig: configStore.set,
-      setupGuard: bridgeRuntime.setup,
+      setupGuard: setup,
       getMe: Api.fetchTelegramBotIdentity,
       persistConfig: configStore.persist,
       startPolling: lockedPollingRuntime.start,
       updateStatus,
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
     }),
     getStatusLines,
     reloadConfig: configStore.load,
@@ -327,68 +383,76 @@ export default function (pi: Pi.ExtensionAPI) {
 
   // --- Lifecycle Hooks ---
 
+  const agentEndResetter = Runtime.createTelegramAgentEndResetter({
+    abort,
+    typing,
+    clearActiveTurn: activeTurnRuntime.clear,
+    resetToolExecutions: lifecycle.resetActiveToolExecutions,
+    clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
+    clearDispatchPending: lifecycle.clearDispatchPending,
+  });
+  const queuedAttachmentSender =
+    Attachments.createTelegramQueuedAttachmentSender({
+      sendMultipart: callMultipart,
+      sendTextReply,
+      recordRuntimeEvent,
+    });
+  const outboundReplyPlanner =
+    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+  const outboundReplyArtifactSender =
+    OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+      execCommand: CommandTemplates.execCommandTemplate,
+      sendMultipart: callMultipart,
+      sendTextReply,
+      getHandlers: configStore.getOutboundHandlers,
+      recordRuntimeEvent,
+    });
+  const agentLifecycleHooks = Queue.createTelegramAgentLifecycleHooks<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    unknown,
+    Keyboard.TelegramInlineKeyboardMarkup
+  >({
+    setAbortHandler: Runtime.createTelegramContextAbortHandlerSetter(abort),
+    getQueuedItems: telegramQueueStore.getQueuedItems,
+    hasPendingDispatch: lifecycle.hasDispatchPending,
+    hasActiveTurn: activeTurnRuntime.has,
+    resetToolExecutions: lifecycle.resetActiveToolExecutions,
+    resetPendingModelSwitch: modelSwitchController.clearPendingSwitch,
+    setQueuedItems: telegramQueueStore.setQueuedItems,
+    clearDispatchPending: lifecycle.clearDispatchPending,
+    setActiveTurn: activeTurnRuntime.set,
+    createPreviewState: previewRuntime.resetState,
+    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    updateStatus,
+    getActiveTurn: activeTurnRuntime.get,
+    extractAssistant: Replies.extractLatestAssistantMessageText,
+    getPreserveQueuedTurnsAsHistory: lifecycle.shouldPreserveQueuedTurnsAsHistory,
+    resetRuntimeState: agentEndResetter,
+    dispatchNextQueuedTelegramTurn,
+    requestDeferredDispatchNextQueuedTelegramTurn:
+      deferredQueueDispatchRuntime.request,
+    clearPreview: previewRuntime.clear,
+    setPreviewPendingText: previewRuntime.setPendingText,
+    finalizeMarkdownPreview: previewRuntime.finalizeMarkdown,
+    sendMarkdownReply,
+    sendTextReply,
+    sendQueuedAttachments: queuedAttachmentSender,
+    planOutboundReply: outboundReplyPlanner,
+    sendOutboundReplyArtifacts: outboundReplyArtifactSender,
+    getActiveToolExecutions: lifecycle.getActiveToolExecutions,
+    setActiveToolExecutions: lifecycle.setActiveToolExecutions,
+    triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,
+  });
+  // Wire transport-level reply dedup reset via lifecycle
+  Lifecycle.setResetTransportReplyDedup(Replies.resetTransportReplyDedup);
+  const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(agentLifecycleHooks.onAgentStart);
   Lifecycle.registerTelegramLifecycleHooks(pi, {
     ...sessionLifecycleRuntime,
+    ...agentLifecycleHooks,
+    onAgentStart: agentStartWithDedupReset,
     onBeforeAgentStart: Prompts.createTelegramBeforeAgentStartHook(),
     onModelSelect: currentModelRuntime.onModelSelect,
-    ...Queue.createTelegramAgentLifecycleHooks<
-      Queue.PendingTelegramTurn,
-      Pi.ExtensionContext,
-      unknown
-    >({
-      setAbortHandler: Runtime.createTelegramContextAbortHandlerSetter(
-        bridgeRuntime.abort,
-      ),
-      getQueuedItems: telegramQueueStore.getQueuedItems,
-      hasPendingDispatch: bridgeRuntime.lifecycle.hasDispatchPending,
-      hasActiveTurn: activeTurnRuntime.has,
-      resetToolExecutions: bridgeRuntime.lifecycle.resetActiveToolExecutions,
-      resetPendingModelSwitch: modelSwitchController.clearPendingSwitch,
-      setQueuedItems: telegramQueueStore.setQueuedItems,
-      clearDispatchPending: bridgeRuntime.lifecycle.clearDispatchPending,
-      setActiveTurn: activeTurnRuntime.set,
-      createPreviewState: previewRuntime.resetState,
-      startTypingLoop: promptDispatchRuntime.startTypingLoop,
-      updateStatus,
-      getActiveTurn: activeTurnRuntime.get,
-      extractAssistant: Replies.extractLatestAssistantMessageText,
-      getPreserveQueuedTurnsAsHistory:
-        bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory,
-      resetRuntimeState: Runtime.createTelegramAgentEndResetter({
-        abort: bridgeRuntime.abort,
-        typing: bridgeRuntime.typing,
-        clearActiveTurn: activeTurnRuntime.clear,
-        resetToolExecutions: bridgeRuntime.lifecycle.resetActiveToolExecutions,
-        clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
-        clearDispatchPending: bridgeRuntime.lifecycle.clearDispatchPending,
-      }),
-      dispatchNextQueuedTelegramTurn,
-      requestDeferredDispatchNextQueuedTelegramTurn:
-        deferredQueueDispatchRuntime.request,
-      clearPreview: previewRuntime.clear,
-      setPreviewPendingText: previewRuntime.setPendingText,
-      finalizeMarkdownPreview: previewRuntime.finalizeMarkdown,
-      sendMarkdownReply,
-      sendTextReply,
-      sendQueuedAttachments: Attachments.createTelegramQueuedAttachmentSender({
-        sendMultipart: callMultipart,
-        sendTextReply,
-        recordRuntimeEvent: runtimeEvents.record,
-      }),
-      planOutboundReply:
-        OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
-      sendOutboundReplyArtifacts:
-        OutboundHandlers.createTelegramOutboundReplyArtifactSender({
-          execCommand: CommandTemplates.execCommandTemplate,
-          sendMultipart: callMultipart,
-          sendTextReply,
-          getHandlers: configStore.getOutboundHandlers,
-          recordRuntimeEvent: runtimeEvents.record,
-        }),
-      getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
-      setActiveToolExecutions: bridgeRuntime.lifecycle.setActiveToolExecutions,
-      triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,
-    }),
     onMessageStart: previewRuntime.onMessageStart,
     onMessageUpdate: previewRuntime.onMessageUpdate,
   });

package/lib/api.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram API transport helpers
+ * Zones: telegram transport, filesystem, runtime diagnostics
  * Wraps bot API calls, file downloads, runtime transport binding, and Telegram temp-file cleanup
  */
 

package/lib/attachment-handlers.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram inbound attachment handler pipeline
+ * Zones: telegram inbound, command templates, prompt preparation
  * Owns MIME/type matching, command-template execution, fallback handling, and prompt injection before prompt enqueueing
  */
 
@@ -299,6 +300,7 @@ async function executeTelegramAttachmentHandlerInvocation(
   const result = await deps.execCommand(invocation.command, invocation.args, {
     cwd,
     timeout,
+    ...(typeof handler === "object" && handler.retry !== undefined ? { retry: handler.retry } : {}),
     ...(stdin !== undefined ? { stdin } : {}),
   });
   if (result.code !== 0)
@@ -342,15 +344,20 @@ async function executeTelegramAttachmentHandler(
   const startedAt = Date.now();
   let output = "";
   for (const [index, step] of steps.entries()) {
-    output = await executeTelegramAttachmentHandlerInvocation(
-      step,
-      file,
-      cwd,
-      deps,
-      false,
-      getTelegramAttachmentCompositionStepTimeout(handler, step, startedAt),
-      index === 0 ? undefined : output,
-    );
+    try {
+      output = await executeTelegramAttachmentHandlerInvocation(
+        step,
+        file,
+        cwd,
+        deps,
+        false,
+        getTelegramAttachmentCompositionStepTimeout(handler, step, startedAt),
+        index === 0 ? undefined : output,
+      );
+    } catch (error) {
+      if (typeof step === "object" && step.critical) throw error;
+      output = "";
+    }
   }
   return output.trim();
 }

package/lib/attachments.ts

@@ -1,5 +1,6 @@
 /**
  * Telegram attachment domain helpers
+ * Zones: telegram outbound, pi agent tool, filesystem
  * Owns telegram_attach registration, attachment queueing, and attachment delivery so Telegram file output stays in one domain module
  */
 

package/lib/command-templates.ts

@@ -1,5 +1,6 @@
 /**
  * Command-template standard helpers
+ * Zones: shared utils, local process execution, automation standard
  * Owns shell-free command-template splitting, placeholder defaults, composition expansion, executable path expansion, and direct execution
  */
 
@@ -7,12 +8,16 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 
+export const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+
 export interface CommandTemplateObjectConfig {
   template?: CommandTemplateValue;
   args?: string[];
   defaults?: Record<string, unknown>;
   timeout?: number;
   output?: string;
+  retry?: number;
+  critical?: boolean;
 }
 
 export type CommandTemplateValue = string | CommandTemplateConfig[];
@@ -34,6 +39,7 @@ export interface CommandTemplateExecOptions {
   signal?: AbortSignal;
   stdin?: string;
   killGrace?: number;
+  retry?: number;
 }
 
 export interface CommandTemplateExecResult {
@@ -100,7 +106,13 @@ export function expandCommandTemplateConfigs(
   }
   if (typeof normalizedConfig.template !== "string") return [];
   return [
-    { ...normalizedConfig, ...context, template: normalizedConfig.template },
+    {
+      ...normalizedConfig,
+      ...context,
+      template: normalizedConfig.template,
+      retry: normalizedConfig.retry,
+      critical: normalizedConfig.critical,
+    },
   ];
 }
 
@@ -192,7 +204,22 @@ export function substituteCommandTemplateToken(
   );
 }
 
-export function execCommandTemplate(
+export async function execCommandTemplate(
+  command: string,
+  args: string[],
+  options: CommandTemplateExecOptions = {},
+): Promise<CommandTemplateExecResult> {
+  const maxAttempts = options.retry ?? 1;
+  let lastResult: CommandTemplateExecResult = { stdout: "", stderr: "", code: 1, killed: false };
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const result = await execCommandTemplateOnce(command, args, options);
+    if (result.code === 0) return result;
+    lastResult = result;
+  }
+  return lastResult;
+}
+
+function execCommandTemplateOnce(
   command: string,
   args: string[],
   options: CommandTemplateExecOptions = {},
@@ -231,8 +258,10 @@ export function execCommandTemplate(
       else
         options.signal.addEventListener("abort", killProcess, { once: true });
     }
-    if (options.timeout && options.timeout > 0)
+    if (options.timeout !== undefined && options.timeout > 0)
       timeoutId = setTimeout(killProcess, options.timeout);
+    else if (options.timeout === undefined)
+      timeoutId = setTimeout(killProcess, DEFAULT_COMMAND_TIMEOUT_MS);
     proc.stdout?.on("data", (data) => {
       stdout += data.toString();
     });