@llblab/pi-telegram 0.17.4 → 0.18.0

package/lib/bindings.ts

@@ -21,6 +21,7 @@ import * as Replies from "./replies.ts";
 import * as Runtime from "./runtime.ts";
 import * as Setup from "./setup.ts";
 import * as Status from "./status.ts";
+import * as Target from "./target.ts";
 import * as TelegramApi from "./telegram-api.ts";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
@@ -37,10 +38,12 @@ type TelegramBridgeStatusUpdater =
 interface TelegramCommandsAndToolsBindingDeps {
   pi: Pi.ExtensionAPI;
   configStore: Config.TelegramConfigStore;
+  persistConfig: () => Promise<void>;
   setup: Setup.TelegramSetupGuard;
   activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
   lockedPollingRuntime: Locks.TelegramLockedPollingRuntime<Pi.ExtensionContext>;
-  getStatusLines: () => string[];
+  stopPolling?: () => Promise<void | string>;
+  getStatusLines: (options?: Status.TelegramBridgeStatusLineOptions) => string[];
   buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
   sendMarkdownReply: (
     chatId: number,
@@ -50,6 +53,7 @@ interface TelegramCommandsAndToolsBindingDeps {
   ) => Promise<number | undefined>;
   callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
   getDefaultChatId: () => number | undefined;
+  getDefaultTarget?: () => OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"];
   canSendDirect: () => boolean;
   updateStatus: TelegramBridgeStatusUpdater;
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
@@ -58,14 +62,17 @@ interface TelegramCommandsAndToolsBindingDeps {
 export function registerTelegramCommandsAndTools({
   pi,
   configStore,
+  persistConfig,
   setup,
   activeTurnRuntime,
   lockedPollingRuntime,
+  stopPolling,
   getStatusLines,
   buttonActionStore,
   sendMarkdownReply,
   callMultipart,
   getDefaultChatId,
+  getDefaultTarget,
   canSendDirect,
   updateStatus,
   recordRuntimeEvent,
@@ -73,27 +80,29 @@ export function registerTelegramCommandsAndTools({
   OutboundAttachments.registerTelegramOutboundAttachmentTool(pi, {
     getActiveTurn: activeTurnRuntime.get,
     getDefaultChatId,
+    getDefaultTarget,
     canSendDirect,
     sendMultipart: callMultipart,
     recordRuntimeEvent,
   });
   OutboundAttachments.registerTelegramOutboundMessageTool(pi, {
     getDefaultChatId,
+    getDefaultTarget,
     canSendDirect,
-    planMessage: OutboundHandlers.createTelegramOutboundReplyPlanner(
-      buttonActionStore,
-    ),
+    planMessage:
+      OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
     sendMarkdownMessage: (chatId, markdown, options) =>
       sendMarkdownReply(chatId, undefined, markdown, options),
     recordRuntimeEvent,
   });
+  Prompts.registerTelegramHelpTool(pi);
   Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: Setup.createTelegramSetupPromptRuntime({
       getConfig: configStore.get,
       setConfig: configStore.set,
       setupGuard: setup,
       getMe: TelegramApi.fetchTelegramBotIdentity,
-      persistConfig: configStore.persist,
+      persistConfig,
       startPolling: lockedPollingRuntime.start,
       updateStatus,
       recordRuntimeEvent,
@@ -102,7 +111,7 @@ export function registerTelegramCommandsAndTools({
     reloadConfig: configStore.load,
     hasBotToken: configStore.hasBotToken,
     startPolling: lockedPollingRuntime.start,
-    stopPolling: lockedPollingRuntime.stop,
+    stopPolling: stopPolling ?? lockedPollingRuntime.stop,
     updateStatus,
   });
 }
@@ -115,7 +124,7 @@ interface TelegramLifecycleBindingDeps {
   >;
   configStore: Pick<
     Config.TelegramConfigStore,
-    "getOutboundHandlers" | "hasBotToken"
+    "get" | "getOutboundHandlers" | "hasBotToken" | "load"
   >;
   abort: Runtime.TelegramRuntimeAbortPort;
   typing: Runtime.TelegramRuntimeTypingPort;
@@ -157,6 +166,14 @@ interface TelegramLifecycleBindingDeps {
     Keyboard.TelegramInlineKeyboardMarkup
   >["sendTextReply"] &
     NonNullable<OutboundHandlers.TelegramVoiceReplySenderDeps["sendTextReply"]>;
+  editInteractiveMessage: (
+    chatId: number,
+    messageId: number,
+    text: string,
+    mode: "html" | "markdown",
+    replyMarkup: Keyboard.TelegramInlineKeyboardMarkup,
+  ) => Promise<void>;
+  deleteMessage: (chatId: number, messageId: number) => Promise<void>;
   dispatchNextQueuedTelegramTurn: (ctx: Pi.ExtensionContext) => void;
   answerGuestQuery: NonNullable<
     Queue.TelegramAgentEndHookRuntimeDeps<
@@ -181,7 +198,9 @@ interface TelegramLifecycleBindingDeps {
     Keyboard.TelegramInlineKeyboardMarkup
   >["finalizeMarkdownPreview"];
   proactivePushChatIdGetter: () => number | undefined;
+  proactivePushTargetGetter: () => Queue.TelegramQueueTarget | undefined;
   isProactivePushEnabled: () => boolean;
+  canSendProactivePush: (ctx: Pi.ExtensionContext) => boolean;
   updateStatus: TelegramBridgeStatusUpdater;
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }
@@ -206,12 +225,16 @@ export function registerTelegramLifecycleRuntimeHooks({
   sendRecordVoiceAction,
   sendMarkdownReply,
   sendTextReply,
+  editInteractiveMessage,
+  deleteMessage,
   dispatchNextQueuedTelegramTurn,
   answerGuestQuery,
   sendGuestReply,
   finalizeMarkdownPreview,
   proactivePushChatIdGetter,
+  proactivePushTargetGetter,
   isProactivePushEnabled,
+  canSendProactivePush,
   updateStatus,
   recordRuntimeEvent,
 }: TelegramLifecycleBindingDeps): void {
@@ -258,9 +281,15 @@ export function registerTelegramLifecycleRuntimeHooks({
     setFoldQueuedPromptsIntoHistory: lifecycle.setFoldQueuedPromptsIntoHistory,
     setActiveTurn: activeTurnRuntime.set,
     createPreviewState: previewRuntime.resetState,
-    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    startTypingLoop: (ctx) => {
+      const turn = activeTurnRuntime.get();
+      promptDispatchRuntime.startTypingLoop(ctx, turn?.chatId, {
+        target: turn?.target,
+      });
+    },
     updateStatus,
     getActiveTurn: activeTurnRuntime.get,
+    loadConfig: configStore.load,
     extractAssistant: Replies.extractLatestAssistantMessageText,
     getFoldQueuedPromptsIntoHistory:
       lifecycle.shouldFoldQueuedPromptsIntoHistory,
@@ -269,6 +298,16 @@ export function registerTelegramLifecycleRuntimeHooks({
     dispatchNextQueuedTelegramTurn,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
+    scheduleActiveTurnDelivery(task) {
+      const timer = setTimeout(() => {
+        void task().catch((error) => {
+          recordRuntimeEvent("delivery", error, {
+            phase: "agent-end-background-delivery",
+          });
+        });
+      }, 0);
+      timer.unref?.();
+    },
     clearPreview: previewRuntime.clear,
     setPreviewPendingText: previewRuntime.setPendingText,
     finalizeMarkdownPreview,
@@ -280,8 +319,9 @@ export function registerTelegramLifecycleRuntimeHooks({
     planOutboundReply: outboundReplyPlanner,
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
     getDefaultChatId: proactivePushChatIdGetter,
+    getDefaultTarget: proactivePushTargetGetter,
     isProactivePushEnabled,
-    canSendProactivePush: lockOwnershipGuard.ownsContext,
+    canSendProactivePush,
     recordRuntimeEvent,
     getActiveToolExecutions: lifecycle.getActiveToolExecutions,
     setActiveToolExecutions: lifecycle.setActiveToolExecutions,
@@ -291,11 +331,18 @@ export function registerTelegramLifecycleRuntimeHooks({
   const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
     agentLifecycleHooks.onAgentStart,
   );
+  const startActiveTurnTypingLoop = (ctx: Pi.ExtensionContext): void => {
+    const turn = activeTurnRuntime.get();
+    promptDispatchRuntime.startTypingLoop(ctx, turn?.chatId, {
+      target: turn?.target,
+    });
+  };
   const compactionObserver = Lifecycle.createTelegramCompactionObserverRuntime({
     setCompactionInProgress: lifecycle.setCompactionInProgress,
     updateStatus,
-    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    startTypingLoop: startActiveTurnTypingLoop,
     stopTypingLoop: typing.stop,
+    shouldStartTypingLoop: activeTurnRuntime.has,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
     dispatchNextQueuedTelegramTurn,
@@ -304,11 +351,12 @@ export function registerTelegramLifecycleRuntimeHooks({
   const messageActivityTypingHooks =
     Lifecycle.createTelegramMessageActivityTypingHooks({
       hasActiveTurn: activeTurnRuntime.has,
-      startTypingLoop: promptDispatchRuntime.startTypingLoop,
+      startTypingLoop: startActiveTurnTypingLoop,
       onMessageStart: previewRuntime.onMessageStart,
       onMessageUpdate: previewRuntime.onMessageUpdate,
       recordRuntimeEvent,
     });
+  const messageActivityHooks = messageActivityTypingHooks;
   Lifecycle.registerTelegramLifecycleHooks(pi, {
     ...sessionLifecycleRuntime,
     ...agentLifecycleHooks,
@@ -319,11 +367,19 @@ export function registerTelegramLifecycleRuntimeHooks({
     onSessionBeforeCompact: compactionObserver.onSessionBeforeCompact,
     onSessionCompact: compactionObserver.onSessionCompact,
     onAgentStart: agentStartWithDedupReset,
+    async onToolExecutionStart(event, _ctx) {
+      agentLifecycleHooks.onToolExecutionStart();
+    },
+    onToolExecutionUpdate() {},
+    async onToolExecutionEnd(event, ctx) {
+      agentLifecycleHooks.onToolExecutionEnd(event, ctx);
+    },
+    onAgentEnd: agentLifecycleHooks.onAgentEnd,
     onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
       isConfigured: configStore.hasBotToken,
       isProactivePushEnabled,
       isCurrentOwner: lockOwnershipGuard.ownsContext,
     }),
-    ...messageActivityTypingHooks,
+    ...messageActivityHooks,
   });
 }

package/lib/bus-api.ts

@@ -0,0 +1,314 @@
+/**
+ * Telegram bus-aware API runtime
+ * Zones: multi-instance bus, telegram api transport, live instance routing
+ * Wraps the direct Telegram Bot API runtime so follower instances can route outbound calls through the bus leader
+ */
+
+import type {
+  TelegramApiCallOptions,
+  TelegramBridgeApiRuntime,
+  TelegramEditMessageTextBody,
+  TelegramInputRichMessage,
+  TelegramSendMessageBody,
+  TelegramSendMessageDraftBody,
+  TelegramSendRichMessageBody,
+  TelegramSendRichMessageDraftBody,
+  TelegramSentMessage,
+  TelegramUpdate,
+} from "./telegram-api.ts";
+
+export type TelegramBusApiCall = (
+  method: string,
+  args: unknown[],
+) => Promise<unknown>;
+
+export interface TelegramBusAwareApiRuntimeDeps {
+  directRuntime: TelegramBridgeApiRuntime;
+  ownsDirect: () => boolean;
+  callFollowerApi: TelegramBusApiCall;
+  getDefaultTarget?: () => { chatId: number; threadId?: number } | undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asBoolean(value: unknown): boolean {
+  return Boolean(value);
+}
+
+function asSentMessage(value: unknown): TelegramSentMessage {
+  return asRecord(value) as unknown as TelegramSentMessage;
+}
+
+function withDefaultThreadTarget(
+  body: Record<string, unknown>,
+  target: { chatId: number; threadId?: number } | undefined,
+): Record<string, unknown> {
+  if (target?.threadId === undefined) return body;
+  if (body.message_thread_id !== undefined) return body;
+  return body.chat_id === target.chatId
+    ? { ...body, message_thread_id: target.threadId }
+    : body;
+}
+
+export function createTelegramAggregateTypingActionSender(
+  runtime: Pick<TelegramBridgeApiRuntime, "call">,
+): (chatId: number) => Promise<unknown> {
+  return (chatId) =>
+    runtime.call("sendChatAction", { chat_id: chatId, action: "typing" });
+}
+
+export function createTelegramBusAwareApiRuntime(
+  deps: TelegramBusAwareApiRuntimeDeps,
+): TelegramBridgeApiRuntime {
+  return {
+    call<TResponse>(
+      method: string,
+      body: Record<string, unknown>,
+      options?: TelegramApiCallOptions,
+    ): Promise<TResponse> {
+      return deps.ownsDirect()
+        ? deps.directRuntime.call<TResponse>(method, body, options)
+        : (deps.callFollowerApi("call", [
+            method,
+            body,
+            options,
+          ]) as Promise<TResponse>);
+    },
+    callMultipart<TResponse>(
+      method: string,
+      fields: Record<string, string>,
+      fileField: string,
+      filePath: string,
+      fileName: string,
+      options?: TelegramApiCallOptions,
+    ): Promise<TResponse> {
+      return deps.ownsDirect()
+        ? deps.directRuntime.callMultipart<TResponse>(
+            method,
+            fields,
+            fileField,
+            filePath,
+            fileName,
+            options,
+          )
+        : (deps.callFollowerApi("callMultipart", [
+            method,
+            fields,
+            fileField,
+            filePath,
+            fileName,
+            options,
+          ]) as Promise<TResponse>);
+    },
+    downloadFile(fileId: string, suggestedName: string): Promise<string> {
+      return deps.ownsDirect()
+        ? deps.directRuntime.downloadFile(fileId, suggestedName)
+        : (deps.callFollowerApi("downloadFile", [
+            fileId,
+            suggestedName,
+          ]) as Promise<string>);
+    },
+    deleteWebhook(signal?: AbortSignal): Promise<boolean> {
+      return deps.directRuntime.deleteWebhook(signal);
+    },
+    getUpdates(
+      body: Record<string, unknown>,
+      signal?: AbortSignal,
+    ): Promise<TelegramUpdate[]> {
+      return deps.directRuntime.getUpdates(body, signal);
+    },
+    setMyCommands(commands): Promise<boolean> {
+      return deps.ownsDirect()
+        ? deps.directRuntime.setMyCommands(commands)
+        : deps
+            .callFollowerApi("call", ["setMyCommands", { commands }])
+            .then(asBoolean);
+    },
+    sendChatAction(
+      chatId: number,
+      action: string,
+      options?: { message_thread_id?: number },
+    ): Promise<boolean> {
+      const body = withDefaultThreadTarget(
+        {
+          chat_id: chatId,
+          action,
+          ...(options?.message_thread_id !== undefined
+            ? { message_thread_id: options.message_thread_id }
+            : {}),
+        },
+        deps.getDefaultTarget?.(),
+      );
+      return deps.ownsDirect()
+        ? deps.directRuntime.sendChatAction(chatId, action, options)
+        : deps
+            .callFollowerApi("call", ["sendChatAction", body])
+            .then(asBoolean);
+    },
+    sendTypingAction(
+      chatId: number,
+      options?: { message_thread_id?: number },
+    ): Promise<unknown> {
+      const body = withDefaultThreadTarget(
+        {
+          chat_id: chatId,
+          action: "typing",
+          ...(options?.message_thread_id !== undefined
+            ? { message_thread_id: options.message_thread_id }
+            : {}),
+        },
+        deps.getDefaultTarget?.(),
+      );
+      return deps.ownsDirect()
+        ? deps.directRuntime.sendTypingAction(chatId, options)
+        : deps
+            .callFollowerApi("call", ["sendChatAction", body])
+            .then(asBoolean);
+    },
+    sendRecordVoiceAction(
+      chatId: number,
+      options?: { message_thread_id?: number },
+    ): Promise<unknown> {
+      const body = withDefaultThreadTarget(
+        {
+          chat_id: chatId,
+          action: "record_voice",
+          ...(options?.message_thread_id !== undefined
+            ? { message_thread_id: options.message_thread_id }
+            : {}),
+        },
+        deps.getDefaultTarget?.(),
+      );
+      return deps.ownsDirect()
+        ? deps.directRuntime.sendRecordVoiceAction(chatId, options)
+        : deps
+            .callFollowerApi("call", ["sendChatAction", body])
+            .then(asBoolean);
+    },
+    sendMessageDraft(
+      chatId: number,
+      draftId: number,
+      text?: string,
+      options?: TelegramSendMessageDraftBody extends Record<string, unknown>
+        ? {
+            parse_mode?: string;
+            entities?: unknown[];
+            message_thread_id?: number;
+          }
+        : never,
+    ): Promise<boolean> {
+      const body: Record<string, unknown> = {
+        chat_id: chatId,
+        draft_id: draftId,
+      };
+      if (text !== undefined) body.text = text;
+      if (options?.parse_mode !== undefined)
+        body.parse_mode = options.parse_mode;
+      if (options?.entities !== undefined) body.entities = options.entities;
+      if (options?.message_thread_id !== undefined) {
+        body.message_thread_id = options.message_thread_id;
+      }
+      const scopedBody = withDefaultThreadTarget(
+        body,
+        deps.getDefaultTarget?.(),
+      );
+      return deps.ownsDirect()
+        ? deps.directRuntime.sendMessageDraft(chatId, draftId, text, options)
+        : deps
+            .callFollowerApi("call", ["sendMessageDraft", scopedBody])
+            .then(asBoolean);
+    },
+    sendMessage(body: TelegramSendMessageBody): Promise<TelegramSentMessage> {
+      return deps.ownsDirect()
+        ? deps.directRuntime.sendMessage(body)
+        : deps
+            .callFollowerApi("call", ["sendMessage", body])
+            .then(asSentMessage);
+    },
+    sendRichMessage(
+      body: TelegramSendRichMessageBody,
+    ): Promise<TelegramSentMessage> {
+      return deps.ownsDirect()
+        ? deps.directRuntime.sendRichMessage(body)
+        : deps
+            .callFollowerApi("call", ["sendRichMessage", body])
+            .then(asSentMessage);
+    },
+    sendRichMessageDraft(
+      body: TelegramSendRichMessageDraftBody,
+    ): Promise<boolean> {
+      return deps.ownsDirect()
+        ? deps.directRuntime.sendRichMessageDraft(body)
+        : deps
+            .callFollowerApi("call", ["sendRichMessageDraft", body])
+            .then(asBoolean);
+    },
+    async editMessageText(
+      body: TelegramEditMessageTextBody,
+    ): Promise<"edited" | "unchanged"> {
+      if (deps.ownsDirect()) return deps.directRuntime.editMessageText(body);
+      await deps.callFollowerApi("call", ["editMessageText", body]);
+      return "edited";
+    },
+    async answerCallbackQuery(
+      callbackQueryId: string,
+      text?: string,
+    ): Promise<void> {
+      if (deps.ownsDirect()) {
+        await deps.directRuntime.answerCallbackQuery(callbackQueryId, text);
+        return;
+      }
+      await deps.callFollowerApi("call", [
+        "answerCallbackQuery",
+        {
+          callback_query_id: callbackQueryId,
+          ...(text !== undefined ? { text } : {}),
+        },
+      ]);
+    },
+    async answerGuestQuery(
+      guestQueryId: string,
+      text?: string,
+      options?: { parseMode?: string; richMessage?: TelegramInputRichMessage },
+    ): Promise<void> {
+      if (deps.ownsDirect()) {
+        await deps.directRuntime.answerGuestQuery(guestQueryId, text, options);
+        return;
+      }
+      const body: Record<string, unknown> = { guest_query_id: guestQueryId };
+      if (text !== undefined || options?.richMessage) {
+        const inputContent: Record<string, unknown> = options?.richMessage
+          ? { rich_message: options.richMessage }
+          : { message_text: text };
+        if (!options?.richMessage && options?.parseMode) {
+          inputContent.parse_mode = options.parseMode;
+        }
+        body.result = {
+          type: "article",
+          id: "1",
+          title: "Response",
+          input_message_content: inputContent,
+        };
+      }
+      await deps.callFollowerApi("call", ["answerGuestQuery", body]);
+    },
+    async deleteMessage(chatId: number, messageId: number): Promise<void> {
+      if (deps.ownsDirect())
+        return deps.directRuntime.deleteMessage(chatId, messageId);
+      await deps.callFollowerApi("call", [
+        "deleteMessage",
+        {
+          chat_id: chatId,
+          message_id: messageId,
+        },
+      ]);
+    },
+    prepareTempDir(): Promise<number> {
+      return deps.directRuntime.prepareTempDir();
+    },
+  };
+}