@llblab/pi-telegram 0.3.0 → 0.5.0

package/lib/routing.ts

@@ -0,0 +1,219 @@
+/**
+ * Telegram inbound routing composition
+ * Wires authorized updates into menus, commands, media grouping, and prompt queueing
+ */
+
+import * as Commands from "./commands.ts";
+import type { TelegramConfigStore } from "./config.ts";
+import type { TelegramAttachmentHandlerRuntime } from "./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 type { TelegramBridgeRuntime } from "./runtime.ts";
+import * as Turns from "./turns.ts";
+import * as Updates from "./updates.ts";
+
+export type TelegramRoutedMessage = Updates.TelegramUpdateMessage &
+  Media.TelegramMediaMessage &
+  Media.TelegramMediaGroupMessage &
+  Commands.TelegramCommandRuntimeMessage &
+  Turns.TelegramTurnMessage;
+
+export type TelegramRoutedCallbackQuery = Updates.TelegramCallbackQuery &
+  Menu.MenuCallbackQuery;
+
+export interface TelegramInboundRouteRuntimeDeps<
+  TUpdate extends Updates.TelegramUpdateFlow & {
+    message?: TMessage;
+    edited_message?: TMessage;
+    callback_query?: TCallbackQuery;
+  },
+  TMessage extends TelegramRoutedMessage,
+  TCallbackQuery extends TelegramRoutedCallbackQuery,
+  TContext,
+  TModel extends Model.MenuModel,
+> {
+  configStore: Pick<
+    TelegramConfigStore,
+    "getAllowedUserId" | "setAllowedUserId" | "persist"
+  >;
+  bridgeRuntime: TelegramBridgeRuntime;
+  activeTurnRuntime: Queue.TelegramActiveTurnStore;
+  mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage>;
+  telegramQueueStore: Queue.TelegramQueueStateStore<TContext>;
+  queueMutationRuntime: Queue.TelegramQueueMutationController<TContext>;
+  modelMenuRuntime: Menu.TelegramModelMenuRuntime<TModel>;
+  currentModelRuntime: Model.CurrentModelRuntime<TContext, TModel>;
+  modelSwitchController: Model.TelegramModelSwitchController<
+    TContext,
+    Model.ScopedTelegramModel<TModel>
+  >;
+  menuActions: Menu.TelegramMenuActionRuntime<TContext, TModel>;
+  attachmentHandlerRuntime: TelegramAttachmentHandlerRuntime<TContext>;
+  updateStatus: (ctx: TContext, error?: string) => void;
+  dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
+  answerCallbackQuery: (
+    callbackQueryId: string,
+    text?: string,
+  ) => Promise<void>;
+  sendTextReply: (
+    chatId: number,
+    replyToMessageId: number,
+    text: string,
+  ) => Promise<number | undefined>;
+  setMyCommands: Commands.TelegramBotCommandRegistrationDeps["setMyCommands"];
+  downloadFile: Media.DownloadTelegramMessageFilesDeps["downloadFile"];
+  getThinkingLevel: () => Model.ThinkingLevel;
+  setThinkingLevel: (level: Model.ThinkingLevel) => void;
+  setModel: (model: TModel) => Promise<boolean>;
+  isIdle: (ctx: TContext) => boolean;
+  hasPendingMessages: (ctx: TContext) => boolean;
+  compact: (
+    ctx: TContext,
+    callbacks: { onComplete: () => void; onError: (error: unknown) => void },
+  ) => void;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
+export function createTelegramInboundRouteRuntime<
+  TUpdate extends Updates.TelegramUpdateFlow & {
+    message?: TMessage;
+    edited_message?: TMessage;
+    callback_query?: TCallbackQuery;
+  },
+  TMessage extends TelegramRoutedMessage,
+  TCallbackQuery extends TelegramRoutedCallbackQuery,
+  TContext,
+  TModel extends Model.MenuModel,
+>(
+  deps: TelegramInboundRouteRuntimeDeps<
+    TUpdate,
+    TMessage,
+    TCallbackQuery,
+    TContext,
+    TModel
+  >,
+): Updates.TelegramUpdateRuntimeController<TContext, TUpdate> {
+  const callbackHandler = Menu.createTelegramMenuCallbackHandlerForContext<
+    TCallbackQuery,
+    TContext,
+    TModel
+  >({
+    getStoredModelMenuState: deps.modelMenuRuntime.getState,
+    getActiveModel: deps.currentModelRuntime.get,
+    getThinkingLevel: deps.getThinkingLevel,
+    setThinkingLevel: deps.setThinkingLevel,
+    updateStatus: deps.updateStatus,
+    updateModelMenuMessage: deps.menuActions.updateModelMenuMessage,
+    updateThinkingMenuMessage: deps.menuActions.updateThinkingMenuMessage,
+    updateStatusMessage: deps.menuActions.updateStatusMessage,
+    answerCallbackQuery: deps.answerCallbackQuery,
+    isIdle: deps.isIdle,
+    hasActiveTelegramTurn: deps.activeTurnRuntime.has,
+    hasAbortHandler: deps.bridgeRuntime.abort.hasHandler,
+    getActiveToolExecutions:
+      deps.bridgeRuntime.lifecycle.getActiveToolExecutions,
+    setModel: deps.setModel,
+    setCurrentModel: deps.currentModelRuntime.setCurrentModel,
+    stagePendingModelSwitch: deps.modelSwitchController.stagePendingSwitch,
+    restartInterruptedTelegramTurn:
+      deps.modelSwitchController.restartInterruptedTurn,
+  });
+  const commandHandler = Commands.createTelegramCommandHandlerTargetRuntime<
+    TMessage,
+    TContext
+  >({
+    hasAbortHandler: deps.bridgeRuntime.abort.hasHandler,
+    clearPendingModelSwitch: deps.modelSwitchController.clearPendingSwitch,
+    hasQueuedTelegramItems: deps.telegramQueueStore.hasQueuedItems,
+    setPreserveQueuedTurnsAsHistory:
+      deps.bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
+    abortCurrentTurn: deps.bridgeRuntime.abort.abortTurn,
+    isIdle: deps.isIdle,
+    hasPendingMessages: deps.hasPendingMessages,
+    hasActiveTelegramTurn: deps.activeTurnRuntime.has,
+    hasDispatchPending: deps.bridgeRuntime.lifecycle.hasDispatchPending,
+    isCompactionInProgress: deps.bridgeRuntime.lifecycle.isCompactionInProgress,
+    setCompactionInProgress:
+      deps.bridgeRuntime.lifecycle.setCompactionInProgress,
+    updateStatus: deps.updateStatus,
+    dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+    compact: deps.compact,
+    allocateItemOrder: deps.bridgeRuntime.queue.allocateItemOrder,
+    allocateControlOrder: deps.bridgeRuntime.queue.allocateControlOrder,
+    appendControlItem: deps.queueMutationRuntime.append,
+    showStatus: deps.menuActions.sendStatusMessage,
+    openModelMenu: deps.menuActions.openModelMenu,
+    getAllowedUserId: deps.configStore.getAllowedUserId,
+    setAllowedUserId: deps.configStore.setAllowedUserId,
+    setMyCommands: deps.setMyCommands,
+    persistConfig: deps.configStore.persist,
+    sendTextReply: deps.sendTextReply,
+    recordRuntimeEvent: deps.recordRuntimeEvent,
+  });
+  const promptEnqueue = Queue.createTelegramPromptEnqueueController<
+    TMessage,
+    TContext
+  >({
+    ...deps.telegramQueueStore,
+    getPreserveQueuedTurnsAsHistory:
+      deps.bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory,
+    setPreserveQueuedTurnsAsHistory:
+      deps.bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
+    createTurn: Turns.createTelegramPromptTurnRuntimeBuilder<
+      TMessage,
+      TContext
+    >({
+      allocateQueueOrder: deps.bridgeRuntime.queue.allocateItemOrder,
+      downloadFile: deps.downloadFile,
+      processAttachments: deps.attachmentHandlerRuntime.process,
+    }),
+    updateStatus: deps.updateStatus,
+    dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+  }).enqueue;
+  const commandOrPrompt = Commands.createTelegramCommandOrPromptRuntime<
+    TMessage,
+    TContext
+  >({
+    extractRawText: Media.extractFirstTelegramMessageText,
+    handleCommand: commandHandler,
+    enqueueTurn: promptEnqueue,
+  });
+  const mediaDispatch = Media.createTelegramMediaGroupDispatchRuntime<
+    TMessage,
+    TContext
+  >({
+    mediaGroups: deps.mediaGroupRuntime,
+    dispatchMessages: commandOrPrompt.dispatchMessages,
+  });
+  const editRuntime = Turns.createTelegramQueuedPromptEditRuntime<
+    TMessage,
+    TContext
+  >({
+    ...deps.telegramQueueStore,
+    updateStatus: deps.updateStatus,
+  });
+  return Updates.createTelegramPairedUpdateRuntime<TContext, TUpdate>({
+    getAllowedUserId: deps.configStore.getAllowedUserId,
+    setAllowedUserId: deps.configStore.setAllowedUserId,
+    persistConfig: deps.configStore.persist,
+    updateStatus: deps.updateStatus,
+    removePendingMediaGroupMessages: deps.mediaGroupRuntime.removeMessages,
+    removeQueuedTelegramTurnsByMessageIds:
+      deps.queueMutationRuntime.removeByMessageIds,
+    clearQueuedTelegramTurnPriorityByMessageId:
+      deps.queueMutationRuntime.clearPriorityByMessageId,
+    prioritizeQueuedTelegramTurnByMessageId:
+      deps.queueMutationRuntime.prioritizeByMessageId,
+    answerCallbackQuery: deps.answerCallbackQuery,
+    handleAuthorizedTelegramCallbackQuery: callbackHandler,
+    sendTextReply: deps.sendTextReply,
+    handleAuthorizedTelegramMessage: mediaDispatch.handleMessage,
+    handleAuthorizedTelegramEditedMessage: editRuntime.updateFromEditedMessage,
+  });
+}

package/lib/runtime.ts

@@ -327,8 +327,9 @@ export interface TelegramRuntimeEventRecorderPort {
   ) => void;
 }
 
-export interface TelegramTypingLoopStarterDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramTypingLoopStarterDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   typing: TelegramRuntimeTypingPort;
   getDefaultChatId: () => number | undefined;
   sendTypingAction: (chatId: number) => Promise<unknown>;
@@ -413,8 +414,9 @@ export function createTelegramAgentEndResetter(
   };
 }
 
-export interface TelegramPromptDispatchLifecycleDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramPromptDispatchLifecycleDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   lifecycle: Pick<
     TelegramRuntimeLifecyclePort,
     "setDispatchPending" | "clearDispatchPending"
@@ -424,8 +426,9 @@ export interface TelegramPromptDispatchLifecycleDeps<TContext>
   updateStatus: (ctx: TContext, error?: string) => void;
 }
 
-export interface TelegramPromptDispatchRuntimeDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramPromptDispatchRuntimeDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   lifecycle: TelegramPromptDispatchLifecycleDeps<TContext>["lifecycle"];
   typing: TelegramRuntimeTypingPort;
   getDefaultChatId: () => number | undefined;

package/lib/setup.ts

@@ -21,6 +21,11 @@ export interface TelegramSetupUser {
   username?: string;
 }
 
+export interface TelegramPollingStartResult {
+  ok: boolean;
+  message?: string;
+}
+
 export interface TelegramSetupDeps {
   hasUI: boolean;
   env: NodeJS.ProcessEnv;
@@ -34,7 +39,7 @@ export interface TelegramSetupDeps {
   }>;
   persistConfig: (config: TelegramSetupConfig) => Promise<void>;
   notify: (message: string, level: "info" | "error") => void;
-  startPolling: () => void | Promise<void>;
+  startPolling: () => unknown | Promise<unknown>;
   updateStatus: () => void;
 }
 
@@ -61,7 +66,7 @@ export interface TelegramSetupPromptRuntimeDeps<
   setupGuard: TelegramSetupGuard;
   getMe: TelegramSetupDeps["getMe"];
   persistConfig: (config: TelegramSetupConfig) => Promise<void>;
-  startPolling: (ctx: TContext) => void | Promise<void>;
+  startPolling: (ctx: TContext) => unknown | Promise<unknown>;
   updateStatus: (ctx: TContext) => void;
   recordRuntimeEvent?: (
     category: string,
@@ -78,6 +83,16 @@ const TELEGRAM_BOT_TOKEN_ENV_VARS = [
   "TELEGRAM_KEY",
 ] as const;
 
+function isTelegramPollingStartResult(
+  value: unknown,
+): value is TelegramPollingStartResult {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    typeof (value as { ok?: unknown }).ok === "boolean"
+  );
+}
+
 export function getTelegramBotTokenInputDefault(
   env: NodeJS.ProcessEnv = process.env,
   configToken?: string,
@@ -135,7 +150,10 @@ export async function runTelegramSetup(
     "Send /start to your bot in Telegram to pair this extension with your account.",
     "info",
   );
-  await deps.startPolling();
+  const startResult = await deps.startPolling();
+  if (isTelegramPollingStartResult(startResult) && startResult.message) {
+    deps.notify(startResult.message, startResult.ok ? "info" : "error");
+  }
   deps.updateStatus();
   return nextConfig;
 }

package/lib/status.ts

@@ -83,6 +83,7 @@ export interface TelegramRuntimeEventRecorderOptions {
 export interface TelegramBridgeStatusLineState {
   botUsername?: string;
   allowedUserId?: number;
+  lockState?: string;
   pollingActive: boolean;
   lastUpdateId?: number;
   activeSourceMessageIds?: number[];
@@ -107,6 +108,7 @@ export interface TelegramStatusBarState {
   paired: boolean;
   compactionInProgress: boolean;
   processing: boolean;
+  processingStatus?: string;
   queuedStatus: string;
   error?: string;
 }
@@ -148,6 +150,7 @@ export interface TelegramBridgeStatusRuntimeDeps<
   getQueuedItems: () => TQueueItem[];
   formatQueuedStatus: (items: TQueueItem[]) => string;
   getRecentRuntimeEvents: () => TelegramRuntimeEvent[];
+  getRuntimeLockState?: () => string;
 }
 
 export interface TelegramStatusRuntime<
@@ -331,6 +334,10 @@ export function createTelegramBridgeStatusRuntime<
     getStatusBarState: (_ctx, error) => {
       const config = deps.getConfig();
       const queuedItems = deps.getQueuedItems();
+      const hasActiveTurn = deps.hasActiveTurn();
+      const hasPendingDispatch = deps.hasDispatchPending();
+      const hasPendingModelSwitch = deps.hasPendingModelSwitch();
+      const activeToolExecutions = deps.getActiveToolExecutions();
       const compactionInProgress = deps.isCompactionInProgress();
       return {
         hasBotToken: !!config.botToken,
@@ -338,9 +345,14 @@ export function createTelegramBridgeStatusRuntime<
         paired: !!config.allowedUserId,
         compactionInProgress,
         processing:
-          deps.hasActiveTurn() ||
-          deps.hasDispatchPending() ||
-          queuedItems.length > 0,
+          hasActiveTurn || hasPendingDispatch || queuedItems.length > 0,
+        processingStatus: getTelegramStatusBarProcessingStatus({
+          hasActiveTurn,
+          hasPendingDispatch,
+          hasPendingModelSwitch,
+          activeToolExecutions,
+          queuedItems: queuedItems.length,
+        }),
         queuedStatus: deps.formatQueuedStatus(queuedItems),
         error,
       };
@@ -350,6 +362,7 @@ export function createTelegramBridgeStatusRuntime<
       return {
         botUsername: config.botUsername,
         allowedUserId: config.allowedUserId,
+        lockState: deps.getRuntimeLockState?.(),
         pollingActive: deps.isPollingActive(),
         lastUpdateId: config.lastUpdateId,
         activeSourceMessageIds: deps.getActiveSourceMessageIds(),
@@ -364,6 +377,21 @@ export function createTelegramBridgeStatusRuntime<
   });
 }
 
+export function getTelegramStatusBarProcessingStatus(state: {
+  hasActiveTurn: boolean;
+  hasPendingDispatch: boolean;
+  hasPendingModelSwitch: boolean;
+  activeToolExecutions: number;
+  queuedItems: number;
+}): string | undefined {
+  if (state.hasPendingModelSwitch) return "model";
+  if (state.activeToolExecutions > 0) return "tool running";
+  if (state.hasActiveTurn) return "active";
+  if (state.hasPendingDispatch) return "dispatching";
+  if (state.queuedItems > 0) return "queued";
+  return undefined;
+}
+
 export function buildTelegramStatusBarText(
   theme: TelegramStatusBarTheme,
   state: TelegramStatusBarState,
@@ -383,7 +411,7 @@ export function buildTelegramStatusBarText(
     return `${label} ${theme.fg("accent", "compacting")}${queued}`;
   }
   if (state.processing) {
-    return `${label} ${theme.fg("accent", "processing")}${queued}`;
+    return `${label} ${theme.fg("accent", state.processingStatus ?? "processing")}${queued}`;
   }
   return `${label} ${theme.fg("success", "connected")}`;
 }
@@ -404,6 +432,7 @@ export function buildTelegramBridgeStatusLines(
     "connection:",
     `- bot: ${state.botUsername ? `@${state.botUsername}` : "not configured"}`,
     `- allowed user: ${state.allowedUserId ?? "not paired"}`,
+    ...(state.lockState ? [`- owner: ${state.lockState}`] : []),
     "",
     "polling:",
     `- state: ${state.pollingActive ? "running" : "stopped"}`,

package/lib/turns.ts

@@ -4,7 +4,7 @@
  */
 
 import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
+import { basename, dirname, join } from "node:path";
 
 import {
   collectTelegramMessageIds,
@@ -53,9 +53,12 @@ export function truncateTelegramQueueSummary(
 export function formatTelegramTurnStatusSummary(
   rawText: string,
   files: DownloadedTelegramTurnFile[],
+  handlerOutputs: string[] = [],
 ): string {
   const textSummary = truncateTelegramQueueSummary(rawText);
   if (textSummary) return textSummary;
+  const handlerSummary = truncateTelegramQueueSummary(handlerOutputs.join(" "));
+  if (handlerSummary) return handlerSummary;
   if (files.length === 1) {
     const fileName = basename(
       files[0]?.fileName || files[0]?.path || "attachment",
@@ -66,10 +69,37 @@ export function formatTelegramTurnStatusSummary(
   return "(empty message)";
 }
 
+function appendTelegramListSection(
+  text: string,
+  title: string,
+  items: string[],
+): string {
+  if (items.length === 0) return text;
+  const prefix = text.length > 0 ? `${text}\n\n` : "";
+  return `${prefix}[${title}]\n${items.map((item) => `- ${item}`).join("\n")}`;
+}
+
+function appendTelegramAttachmentSection(
+  text: string,
+  files: Pick<DownloadedTelegramTurnFile, "path">[],
+): string {
+  if (files.length === 0) return text;
+  const dirs = [...new Set(files.map((file) => dirname(file.path)))];
+  const sameDir = dirs.length === 1;
+  const header = sameDir ? `[attachments] ${dirs[0]}` : "[attachments]";
+  const items = sameDir
+    ? files.map((file) => `/${basename(file.path)}`)
+    : files.map((file) => file.path);
+  const prefix = text.length > 0 ? `${text}\n\n` : "";
+  return `${prefix}${header}\n${items.map((item) => `- ${item}`).join("\n")}`;
+}
+
 export function buildTelegramTurnPrompt(options: {
   telegramPrefix: string;
   rawText: string;
   files: DownloadedTelegramTurnFile[];
+  promptFiles?: DownloadedTelegramTurnFile[];
+  handlerOutputs?: string[];
   historyTurns?: Pick<PendingTelegramTurn, "historyText">[];
 }): string {
   let prompt = options.telegramPrefix;
@@ -87,12 +117,13 @@ export function buildTelegramTurnPrompt(options: {
         ? `\n${options.rawText}`
         : ` ${options.rawText}`;
   }
-  if (options.files.length > 0) {
-    prompt += "\n\nTelegram attachments were saved locally:";
-    for (const file of options.files) {
-      prompt += `\n- ${file.path}`;
-    }
-  }
+  const promptFiles = options.promptFiles ?? options.files;
+  prompt = appendTelegramAttachmentSection(prompt, promptFiles);
+  prompt = appendTelegramListSection(
+    prompt,
+    "outputs",
+    options.handlerOutputs ?? [],
+  );
   return prompt;
 }
 
@@ -101,7 +132,7 @@ function splitTelegramPromptAttachmentSuffix(prompt: string): {
   attachmentSuffix: string;
   attachmentFiles: DownloadedTelegramTurnFile[];
 } {
-  const marker = "\n\nTelegram attachments were saved locally:";
+  const marker = "\n\n[attachments]";
   const markerIndex = prompt.indexOf(marker);
   if (markerIndex === -1) {
     return {
@@ -112,11 +143,32 @@ function splitTelegramPromptAttachmentSuffix(prompt: string): {
   }
   const promptWithoutAttachments = prompt.slice(0, markerIndex);
   const attachmentSuffix = prompt.slice(markerIndex);
-  const attachmentFiles = attachmentSuffix
-    .split("\n")
+  const attachmentLines: string[] = [];
+  let readingAttachments = false;
+  let attachmentDir: string | undefined;
+  for (const line of attachmentSuffix.split("\n")) {
+    const trimmed = line.trim();
+    const attachmentMatch = trimmed.match(/^\[attachments\](?:\s+(.+))?$/);
+    if (attachmentMatch) {
+      readingAttachments = true;
+      attachmentDir = attachmentMatch[1]?.trim();
+      continue;
+    }
+    if (readingAttachments && /^\[[^\]]+\](?:\s+.*)?$/.test(trimmed)) break;
+    if (readingAttachments) attachmentLines.push(line);
+  }
+  const attachmentFiles = attachmentLines
     .map((line) => line.match(/^- (.+)$/)?.[1]?.trim())
     .filter((path): path is string => !!path)
-    .map((path) => ({ path, fileName: basename(path), isImage: false }));
+    .map((path) =>
+      attachmentDir ? join(attachmentDir, path.replace(/^\/+/, "")) : path,
+    )
+    .map((path) => ({
+      path,
+      fileName: basename(path),
+      isImage: false,
+      kind: "document" as const,
+    }));
   return { promptWithoutAttachments, attachmentSuffix, attachmentFiles };
 }
 
@@ -242,6 +294,8 @@ export interface BuildTelegramPromptTurnOptions {
   queueOrder: number;
   rawText: string;
   files: DownloadedTelegramTurnFile[];
+  promptFiles?: DownloadedTelegramTurnFile[];
+  handlerOutputs?: string[];
   readBinaryFile: (path: string) => Promise<Uint8Array>;
   inferImageMimeType: (path: string) => string | undefined;
 }
@@ -251,30 +305,51 @@ export type BuildTelegramPromptTurnRuntimeOptions = Omit<
   "readBinaryFile"
 >;
 
-export interface TelegramPromptTurnRuntimeBuilderDeps extends DownloadTelegramMessageFilesDeps {
+export interface TelegramPromptTurnRuntimeBuilderDeps<
+  TContext = unknown,
+> extends DownloadTelegramMessageFilesDeps {
   allocateQueueOrder: () => number;
+  processAttachments?: (
+    files: DownloadedTelegramTurnFile[],
+    rawText: string,
+    ctx: TContext,
+  ) => Promise<{
+    rawText: string;
+    promptFiles?: DownloadedTelegramTurnFile[];
+    handlerOutputs?: string[];
+  }>;
 }
 
 export function createTelegramPromptTurnRuntimeBuilder<
   TMessage extends TelegramTurnMessage & TelegramMediaMessage,
+  TContext = unknown,
 >(
-  deps: TelegramPromptTurnRuntimeBuilderDeps,
+  deps: TelegramPromptTurnRuntimeBuilderDeps<TContext>,
 ): (
   messages: TMessage[],
   historyTurns?: PendingTelegramTurn[],
+  ctx?: TContext,
 ) => Promise<PendingTelegramTurn> {
-  return async (messages, historyTurns = []) =>
-    buildTelegramPromptTurnRuntime({
+  return async (messages, historyTurns = [], ctx) => {
+    const rawText = extractTelegramMessagesText(messages);
+    const files = await downloadTelegramMessageFiles(messages, {
+      downloadFile: deps.downloadFile,
+    });
+    const processed = deps.processAttachments
+      ? await deps.processAttachments(files, rawText, ctx as TContext)
+      : { rawText, promptFiles: files };
+    return buildTelegramPromptTurnRuntime({
       telegramPrefix: TELEGRAM_PREFIX,
       messages,
       historyTurns,
       queueOrder: deps.allocateQueueOrder(),
-      rawText: extractTelegramMessagesText(messages),
-      files: await downloadTelegramMessageFiles(messages, {
-        downloadFile: deps.downloadFile,
-      }),
+      rawText: processed.rawText,
+      files,
+      promptFiles: processed.promptFiles,
+      handlerOutputs: processed.handlerOutputs,
       inferImageMimeType: guessMediaType,
     });
+  };
 }
 
 export async function buildTelegramPromptTurn(
@@ -291,6 +366,8 @@ export async function buildTelegramPromptTurn(
         telegramPrefix: options.telegramPrefix,
         rawText: options.rawText,
         files: options.files,
+        promptFiles: options.promptFiles,
+        handlerOutputs: options.handlerOutputs,
         historyTurns: options.historyTurns,
       }),
     },
@@ -316,10 +393,15 @@ export async function buildTelegramPromptTurn(
     laneOrder: options.queueOrder,
     queuedAttachments: [],
     content,
-    historyText: formatTelegramHistoryText(options.rawText, options.files),
+    historyText: formatTelegramHistoryText(
+      options.rawText,
+      options.promptFiles ?? options.files,
+      options.handlerOutputs,
+    ),
     statusSummary: formatTelegramTurnStatusSummary(
       options.rawText,
-      options.files,
+      options.promptFiles ?? options.files,
+      options.handlerOutputs,
     ),
   };
 }

package/package.json

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