@llblab/pi-telegram 0.11.2 → 0.13.0

package/lib/bindings.ts

@@ -0,0 +1,299 @@
+/**
+ * Telegram bridge binding composition
+ * Zones: telegram, pi agent, orchestration
+ * Owns pi-facing tool, command, and lifecycle hook registration for the entrypoint
+ */
+
+import * as CommandTemplates from "./command-templates.ts";
+import * as Commands from "./commands.ts";
+import * as Config from "./config.ts";
+import * as Keyboard from "./keyboard.ts";
+import * as Lifecycle from "./lifecycle.ts";
+import * as Locks from "./locks.ts";
+import * as Model from "./model.ts";
+import * as OutboundAttachments from "./outbound-attachments.ts";
+import * as OutboundHandlers from "./outbound.ts";
+import * as Pi from "./pi.ts";
+import * as Preview from "./preview.ts";
+import * as Prompts from "./prompts.ts";
+import * as Queue from "./queue.ts";
+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 TelegramApi from "./telegram-api.ts";
+
+type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
+
+type TelegramRuntimeEventRecorder = (
+  category: string,
+  error: unknown,
+  details?: Record<string, unknown>,
+) => void;
+
+type TelegramBridgeStatusUpdater =
+  Status.TelegramStatusRuntime<Pi.ExtensionContext>["updateStatus"];
+
+interface TelegramCommandsAndToolsBindingDeps {
+  pi: Pi.ExtensionAPI;
+  configStore: Config.TelegramConfigStore;
+  setup: Setup.TelegramSetupGuard;
+  activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
+  lockedPollingRuntime: Locks.TelegramLockedPollingRuntime<Pi.ExtensionContext>;
+  getStatusLines: () => string[];
+  updateStatus: TelegramBridgeStatusUpdater;
+  recordRuntimeEvent: TelegramRuntimeEventRecorder;
+}
+
+export function registerTelegramCommandsAndTools({
+  pi,
+  configStore,
+  setup,
+  activeTurnRuntime,
+  lockedPollingRuntime,
+  getStatusLines,
+  updateStatus,
+  recordRuntimeEvent,
+}: TelegramCommandsAndToolsBindingDeps): void {
+  OutboundAttachments.registerTelegramOutboundAttachmentTool(pi, {
+    getActiveTurn: activeTurnRuntime.get,
+    recordRuntimeEvent,
+  });
+  Commands.registerTelegramBridgeCommands(pi, {
+    promptForConfig: Setup.createTelegramSetupPromptRuntime({
+      getConfig: configStore.get,
+      setConfig: configStore.set,
+      setupGuard: setup,
+      getMe: TelegramApi.fetchTelegramBotIdentity,
+      persistConfig: configStore.persist,
+      startPolling: lockedPollingRuntime.start,
+      updateStatus,
+      recordRuntimeEvent,
+    }),
+    getStatusLines,
+    reloadConfig: configStore.load,
+    hasBotToken: configStore.hasBotToken,
+    startPolling: lockedPollingRuntime.start,
+    stopPolling: lockedPollingRuntime.stop,
+    updateStatus,
+  });
+}
+
+interface TelegramLifecycleBindingDeps {
+  pi: Pi.ExtensionAPI;
+  sessionLifecycleRuntime: Pick<
+    Lifecycle.TelegramLifecycleRegistrationDeps,
+    "onSessionStart" | "onSessionShutdown" | "onModelSelect"
+  >;
+  queueSessionLifecycle: Pick<
+    Lifecycle.TelegramLifecycleRegistrationDeps,
+    "onSessionShutdown"
+  >;
+  configStore: Pick<Config.TelegramConfigStore, "getOutboundHandlers">;
+  abort: Runtime.TelegramRuntimeAbortPort;
+  typing: Runtime.TelegramRuntimeTypingPort;
+  lifecycle: Runtime.TelegramRuntimeLifecyclePort;
+  activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
+  telegramQueueStore: Queue.TelegramQueueStore<Pi.ExtensionContext>;
+  modelSwitchController: Model.TelegramModelSwitchController<
+    Pi.ExtensionContext,
+    Model.ScopedTelegramModel<ActivePiModel>
+  >;
+  previewRuntime: Preview.TelegramAssistantPreviewRuntime<
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >;
+  promptDispatchRuntime: Runtime.TelegramPromptDispatchRuntime<Pi.ExtensionContext>;
+  deferredQueueDispatchRuntime: Queue.TelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>;
+  lockOwnershipGuard: Pick<
+    Locks.TelegramLockOwnershipGuard<Pi.ExtensionContext>,
+    "ownsContext"
+  >;
+  buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
+  callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
+  sendChatAction: NonNullable<
+    OutboundHandlers.TelegramVoiceReplySenderDeps["sendChatAction"]
+  >;
+  sendRecordVoiceAction: NonNullable<
+    OutboundHandlers.TelegramVoiceReplySenderDeps["sendRecordVoiceAction"]
+  >;
+  sendMarkdownReply: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["sendMarkdownReply"];
+  sendTextReply: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["sendTextReply"] &
+    NonNullable<OutboundHandlers.TelegramVoiceReplySenderDeps["sendTextReply"]>;
+  dispatchNextQueuedTelegramTurn: (ctx: Pi.ExtensionContext) => void;
+  answerGuestQuery: NonNullable<
+    Queue.TelegramAgentEndHookRuntimeDeps<
+      Queue.PendingTelegramTurn,
+      Pi.ExtensionContext,
+      Pi.AgentEndEvent["messages"][number],
+      Keyboard.TelegramInlineKeyboardMarkup
+    >["answerGuestQuery"]
+  >;
+  sendGuestReply: NonNullable<
+    Queue.TelegramAgentEndHookRuntimeDeps<
+      Queue.PendingTelegramTurn,
+      Pi.ExtensionContext,
+      Pi.AgentEndEvent["messages"][number],
+      Keyboard.TelegramInlineKeyboardMarkup
+    >["sendGuestReply"]
+  >;
+  finalizeMarkdownPreview: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["finalizeMarkdownPreview"];
+  proactivePushChatIdGetter: () => number | undefined;
+  isProactivePushEnabled: () => boolean;
+  updateStatus: TelegramBridgeStatusUpdater;
+  recordRuntimeEvent: TelegramRuntimeEventRecorder;
+}
+
+export function registerTelegramLifecycleRuntimeHooks({
+  pi,
+  sessionLifecycleRuntime,
+  queueSessionLifecycle,
+  configStore,
+  abort,
+  typing,
+  lifecycle,
+  activeTurnRuntime,
+  telegramQueueStore,
+  modelSwitchController,
+  previewRuntime,
+  promptDispatchRuntime,
+  deferredQueueDispatchRuntime,
+  lockOwnershipGuard,
+  buttonActionStore,
+  callMultipart,
+  sendChatAction,
+  sendRecordVoiceAction,
+  sendMarkdownReply,
+  sendTextReply,
+  dispatchNextQueuedTelegramTurn,
+  answerGuestQuery,
+  sendGuestReply,
+  finalizeMarkdownPreview,
+  proactivePushChatIdGetter,
+  isProactivePushEnabled,
+  updateStatus,
+  recordRuntimeEvent,
+}: TelegramLifecycleBindingDeps): void {
+  const agentEndResetter = Runtime.createTelegramAgentEndResetter({
+    abort,
+    typing,
+    clearActiveTurn: activeTurnRuntime.clear,
+    resetToolExecutions: lifecycle.resetActiveToolExecutions,
+    clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
+    clearDispatchPending: lifecycle.clearDispatchPending,
+  });
+  const queuedAttachmentSender =
+    OutboundAttachments.createTelegramQueuedOutboundAttachmentSender({
+      sendMultipart: callMultipart,
+      sendTextReply,
+      recordRuntimeEvent,
+    });
+  const outboundReplyPlanner =
+    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+  const outboundReplyArtifactSender =
+    OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+      execCommand: CommandTemplates.execCommandTemplate,
+      sendMultipart: callMultipart,
+      sendTextReply,
+      sendChatAction,
+      sendRecordVoiceAction,
+      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,
+    sendMarkdownReply,
+    sendTextReply,
+    sendQueuedAttachments: queuedAttachmentSender,
+    answerGuestQuery,
+    sendGuestReply,
+    planOutboundReply: outboundReplyPlanner,
+    sendOutboundReplyArtifacts: outboundReplyArtifactSender,
+    isCurrentOwner: lockOwnershipGuard.ownsContext,
+    getDefaultChatId: proactivePushChatIdGetter,
+    isProactivePushEnabled,
+    recordRuntimeEvent,
+    getActiveToolExecutions: lifecycle.getActiveToolExecutions,
+    setActiveToolExecutions: lifecycle.setActiveToolExecutions,
+    triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,
+  });
+  Lifecycle.setResetTransportReplyDedup(Replies.resetTransportReplyDedup);
+  const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
+    agentLifecycleHooks.onAgentStart,
+  );
+  const compactionObserver = Lifecycle.createTelegramCompactionObserverRuntime({
+    setCompactionInProgress: lifecycle.setCompactionInProgress,
+    updateStatus,
+    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    stopTypingLoop: typing.stop,
+    requestDeferredDispatchNextQueuedTelegramTurn:
+      deferredQueueDispatchRuntime.request,
+    dispatchNextQueuedTelegramTurn,
+    recordRuntimeEvent,
+  });
+  const messageActivityTypingHooks =
+    Lifecycle.createTelegramMessageActivityTypingHooks({
+      hasActiveTurn: activeTurnRuntime.has,
+      startTypingLoop: promptDispatchRuntime.startTypingLoop,
+      onMessageStart: previewRuntime.onMessageStart,
+      onMessageUpdate: previewRuntime.onMessageUpdate,
+    });
+  Lifecycle.registerTelegramLifecycleHooks(pi, {
+    ...sessionLifecycleRuntime,
+    ...agentLifecycleHooks,
+    async onSessionShutdown(event, ctx) {
+      compactionObserver.onSessionShutdown();
+      await queueSessionLifecycle.onSessionShutdown(event, ctx);
+    },
+    onSessionBeforeCompact: compactionObserver.onSessionBeforeCompact,
+    onSessionCompact: compactionObserver.onSessionCompact,
+    onAgentStart: agentStartWithDedupReset,
+    onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
+      isProactivePushEnabled,
+      isCurrentOwner: lockOwnershipGuard.ownsContext,
+    }),
+    ...messageActivityTypingHooks,
+  });
+}