@llblab/pi-telegram 0.22.1 → 0.23.0

package/lib/outbound.ts

@@ -1,14 +1,22 @@
 /**
  * Telegram outbound surface helpers
  * Zones: telegram outbound, command templates, voice delivery
- * Owns configured outbound handler execution, text transforms, voice-file generation/delivery, runtime-event bridge, and compatibility re-exports; assistant markup parsing lives in outbound-markup and button callback actions live in outbound-buttons
+ * Owns configured outbound handler execution, text transforms, public assistant-output reply composition and mutation fencing, voice-file generation/delivery, runtime-event bridge, and compatibility re-exports; assistant markup parsing lives in outbound-markup and button callback actions live in outbound-buttons
  */
 
 import { randomUUID } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 
+import type { TelegramAssistantSegmentEvent } from "./activity.ts";
 import { resolveTelegramTempDir } from "./paths.ts";
+import * as Replies from "./replies.ts";
+import type {
+  TelegramEditMessageTextBody,
+  TelegramSendMessageBody,
+  TelegramSendRichMessageBody,
+  TelegramSentMessage,
+} from "./telegram-api.ts";
 
 import {
   planTelegramButtonReply,
@@ -905,3 +913,100 @@ export function createTelegramOutboundReplyArtifactSender(
     }
   };
 }
+
+// --- Public Assistant Output Delivery ---
+
+export interface TelegramAssistantOutputMutationFence {
+  run: <TArgs extends unknown[], TResult>(
+    mutation: (...args: TArgs) => Promise<TResult>,
+    ...args: TArgs
+  ) => Promise<TResult>;
+}
+
+export interface TelegramAssistantOutputDeliveryAuthority<TTransportStamp> {
+  transportStamp: TTransportStamp;
+  route: "direct" | "follower" | "none";
+  directEpoch?: number | string;
+  followerGeneration?: string;
+  target?: TelegramTarget;
+}
+
+export function createTelegramAssistantOutputMutationFence(
+  isAuthorityActive: () => boolean,
+): TelegramAssistantOutputMutationFence {
+  return {
+    run(mutation, ...args) {
+      if (!isAuthorityActive()) {
+        return Promise.reject(
+          new Error(
+            "Assistant output lost admission authority before transport mutation.",
+          ),
+        );
+      }
+      return mutation(...args);
+    },
+  };
+}
+
+export function createTelegramAssistantOutputSender<
+  TTransportStamp,
+  TReplyMarkup = unknown,
+>(deps: {
+  recordOwnership?: Replies.TelegramReplyOwnershipRecorder["record"];
+  sendMessage: (
+    body: TelegramSendMessageBody,
+  ) => Promise<TelegramSentMessage>;
+  sendRichMessage: (
+    body: TelegramSendRichMessageBody,
+  ) => Promise<TelegramSentMessage>;
+  editMessage: (
+    body: TelegramEditMessageTextBody,
+  ) => Promise<unknown>;
+  getAssistantRenderingMode: () => "rich" | "html";
+  execCommand: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["execCommand"];
+  getHandlers?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["getHandlers"];
+  recordRuntimeEvent?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["recordRuntimeEvent"];
+}): (
+  event: TelegramAssistantSegmentEvent,
+  authority: TelegramAssistantOutputDeliveryAuthority<TTransportStamp>,
+  isAuthorityActive: () => boolean,
+) => Promise<void> {
+  return async function sendAssistantOutput(
+    event,
+    authority,
+    isAuthorityActive,
+  ) {
+    const target = authority.target;
+    if (!target) {
+      throw new Error("Assistant output has no authorized Telegram target.");
+    }
+    const mutationFence =
+      createTelegramAssistantOutputMutationFence(isAuthorityActive);
+    const replyRuntime = Replies.createTelegramRenderedMessageDeliveryRuntime({
+      recordOwnership: deps.recordOwnership,
+      sendMessage(body) {
+        return mutationFence.run(deps.sendMessage, body);
+      },
+      sendRichMessage(body) {
+        return mutationFence.run(deps.sendRichMessage, body);
+      },
+      getAssistantRenderingMode: deps.getAssistantRenderingMode,
+      editMessage(body) {
+        return mutationFence.run(deps.editMessage, body);
+      },
+    });
+    const outboundRuntime = createTelegramOutboundTextReplyRuntime({
+      sendTextReply: replyRuntime.sendTextReply,
+      sendMarkdownReply: replyRuntime.sendMarkdownReply,
+      execCommand: deps.execCommand,
+      getHandlers: deps.getHandlers,
+      recordRuntimeEvent: deps.recordRuntimeEvent,
+    });
+    await outboundRuntime.sendMarkdownReply(
+      target.chatId,
+      undefined,
+      event.text,
+      { target },
+    );
+  };
+}

package/lib/polling.ts

@@ -160,6 +160,7 @@ export function createTelegramPollingControllerRuntime<
       getUpdates: deps.getUpdates,
       persistConfig: deps.persistConfig,
       handleUpdate: deps.handleUpdate,
+      prepareUpdateBatch: deps.prepareUpdateBatch,
       updateStatus: deps.updateStatus,
       sleep: deps.sleep,
       maxUpdateFailures: deps.maxUpdateFailures,
@@ -909,6 +910,7 @@ export interface TelegramPollLoopDeps<
   ) => Promise<TUpdate[]>;
   persistConfig: (config: TelegramPollingConfig) => Promise<void>;
   handleUpdate: (update: TUpdate, ctx: TContext) => Promise<void>;
+  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   onErrorStatus: (message: string) => void;
   onStatusReset: () => void;
   sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
@@ -927,6 +929,7 @@ export interface TelegramPollLoopRunnerDeps<
   ) => Promise<TUpdate[]>;
   persistConfig: (config: TelegramPollingConfig) => Promise<void>;
   handleUpdate: (update: TUpdate, ctx: TContext) => Promise<void>;
+  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   updateStatus: (ctx: TContext, message?: string) => void;
   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
   maxUpdateFailures?: number;
@@ -973,6 +976,7 @@ export function createTelegramPollLoopRunner<
       getUpdates: deps.getUpdates,
       persistConfig: deps.persistConfig,
       handleUpdate: deps.handleUpdate,
+      prepareUpdateBatch: deps.prepareUpdateBatch,
       onErrorStatus: (message) => {
         updateTelegramPollingStatusSafely(deps.updateStatus, ctx, {
           message,
@@ -1039,6 +1043,7 @@ export async function runTelegramPollLoop<
         buildTelegramLongPollRequest(deps.config.lastUpdateId),
         deps.signal,
       );
+      deps.prepareUpdateBatch?.(updates);
       consecutiveGetUpdatesConflicts = 0;
       for (const update of updates) {
         if (admittedUpdates.has(update.update_id)) {

package/lib/queue.ts

@@ -954,6 +954,11 @@ export interface TelegramAgentEndRuntimeDeps<
     options?: { target?: TelegramQueueTarget },
   ) => Promise<unknown>;
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
+  sendRichAttachmentReply?: (
+    turn: TTurn,
+    markdown: string,
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<boolean>;
   answerGuestQuery?: (
     guestQueryId: string,
     text?: string,
@@ -978,10 +983,6 @@ export interface TelegramAgentEndRuntimeDeps<
     plan: TelegramAgentEndOutboundReplyPlan,
     options?: { replyToPrompt?: boolean },
   ) => Promise<void>;
-  getDefaultChatId?: () => number | undefined;
-  getDefaultTarget?: () => TelegramQueueTarget | undefined;
-  isProactivePushEnabled?: () => boolean;
-  canSendProactivePush?: () => boolean;
   recordRuntimeEvent?: (
     category: string,
     error: unknown,
@@ -1029,6 +1030,10 @@ export interface TelegramAgentEndHookRuntimeDeps<
   >["sendMarkdownReply"];
   sendTextReply: TelegramAgentEndRuntimeDeps<TTurn>["sendTextReply"];
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
+  sendRichAttachmentReply?: TelegramAgentEndRuntimeDeps<
+    TTurn,
+    TReplyMarkup
+  >["sendRichAttachmentReply"];
   answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
   sendGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestReply"];
   sendGuestAttachment?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestAttachment"];
@@ -1038,10 +1043,6 @@ export interface TelegramAgentEndHookRuntimeDeps<
     TReplyMarkup
   >["planOutboundReply"];
   sendOutboundReplyArtifacts?: TelegramAgentEndRuntimeDeps<TTurn>["sendOutboundReplyArtifacts"];
-  getDefaultChatId?: TelegramAgentEndRuntimeDeps<TTurn>["getDefaultChatId"];
-  getDefaultTarget?: TelegramAgentEndRuntimeDeps<TTurn>["getDefaultTarget"];
-  isProactivePushEnabled?: TelegramAgentEndRuntimeDeps<TTurn>["isProactivePushEnabled"];
-  canSendProactivePush?: (ctx: TContext) => boolean;
   recordRuntimeEvent?: TelegramAgentEndRuntimeDeps<TTurn>["recordRuntimeEvent"];
 }
 
@@ -1135,12 +1136,9 @@ export function createTelegramAgentEndHook<
     await deps.loadConfig?.();
     if (deps.isSessionActive && !deps.isSessionActive(ctx)) return;
     const turn = deps.getActiveTurn();
-    const proactiveEnabled = deps.isProactivePushEnabled?.() ?? false;
-    const canProactivePush = deps.canSendProactivePush?.(ctx) ?? false;
     await handleTelegramAgentEndRuntime({
       turn,
-      assistant:
-        turn || proactiveEnabled ? deps.extractAssistant(event.messages) : {},
+      assistant: turn ? deps.extractAssistant(event.messages) : {},
       foldQueuedPromptsIntoHistory: deps.getFoldQueuedPromptsIntoHistory(),
       resetRuntimeState: deps.resetRuntimeState,
       isSessionActive: () => deps.isSessionActive?.(ctx) ?? true,
@@ -1165,16 +1163,13 @@ export function createTelegramAgentEndHook<
       sendMarkdownReply: deps.sendMarkdownReply,
       sendTextReply: deps.sendTextReply,
       sendQueuedAttachments: deps.sendQueuedAttachments,
+      sendRichAttachmentReply: deps.sendRichAttachmentReply,
       answerGuestQuery: deps.answerGuestQuery,
       sendGuestReply: deps.sendGuestReply,
       sendGuestAttachment: deps.sendGuestAttachment,
       sendGuestVoiceReply: deps.sendGuestVoiceReply,
       planOutboundReply: deps.planOutboundReply,
       sendOutboundReplyArtifacts: deps.sendOutboundReplyArtifacts,
-      getDefaultChatId: deps.getDefaultChatId,
-      getDefaultTarget: deps.getDefaultTarget,
-      isProactivePushEnabled: deps.isProactivePushEnabled,
-      canSendProactivePush: () => canProactivePush,
       recordRuntimeEvent: deps.recordRuntimeEvent,
     });
   };
@@ -1241,35 +1236,6 @@ export async function handleTelegramAgentEndRuntime<
     foldQueuedPromptsIntoHistory: deps.foldQueuedPromptsIntoHistory,
   });
   if (!turn) {
-    const proactiveEnabled = deps.isProactivePushEnabled?.() ?? false;
-    const canProactivePush = deps.canSendProactivePush?.() ?? false;
-    if (proactiveEnabled && finalText && !assistant.errorMessage) {
-      if (canProactivePush) {
-        const defaultTarget = deps.getDefaultTarget?.();
-        const defaultChatId =
-          defaultTarget?.chatId ?? deps.getDefaultChatId?.();
-        if (defaultChatId !== undefined) {
-          try {
-            await deps.sendMarkdownReply(defaultChatId, undefined, finalText, {
-              target: defaultTarget,
-            });
-          } catch (error) {
-            deps.recordRuntimeEvent?.("proactive-push", error, {
-              chatId: defaultChatId,
-              threadId: defaultTarget?.threadId,
-            });
-          }
-        }
-      } else {
-        deps.recordRuntimeEvent?.(
-          "proactive-push",
-          new Error(
-            "Proactive push skipped because this instance does not own Telegram polling.",
-          ),
-          { phase: "ownership" },
-        );
-      }
-    }
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
     return;
   }
@@ -1346,7 +1312,34 @@ export async function handleTelegramAgentEndRuntime<
     if (!finalText && hasOutboundArtifacts)
       await deps.clearPreview(turn.chatId, { target: turn.target });
     if (!isDeliveryActive()) return;
-    if (endPlan.kind === "text" && finalText) {
+    let richAttachmentDelivered = false;
+    if (
+      endPlan.kind === "text" &&
+      finalText &&
+      !hasOutboundArtifacts &&
+      deps.sendRichAttachmentReply
+    ) {
+      try {
+        richAttachmentDelivered = await deps.sendRichAttachmentReply(
+          turn,
+          finalText,
+          { replyMarkup },
+        );
+        if (!isDeliveryActive()) return;
+        if (richAttachmentDelivered) {
+          await deps.clearPreview(turn.chatId, { target: turn.target });
+        }
+      } catch (error) {
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "rich-attachment-commit-unknown",
+          chatId: turn.chatId,
+        });
+        if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+        return;
+      }
+    }
+    if (!isDeliveryActive()) return;
+    if (!richAttachmentDelivered && endPlan.kind === "text" && finalText) {
       try {
         const finalized = await deps.finalizeMarkdownPreview(
           turn.chatId,
@@ -1414,7 +1407,7 @@ export async function handleTelegramAgentEndRuntime<
       }
     }
     if (!isDeliveryActive()) return;
-    if (endPlan.shouldSendAttachmentNotice) {
+    if (!richAttachmentDelivered && endPlan.shouldSendAttachmentNotice) {
       await deps.sendTextReply(
         turn.chatId,
         turn.replyToMessageId,
@@ -1423,7 +1416,7 @@ export async function handleTelegramAgentEndRuntime<
       );
     }
     if (!isDeliveryActive()) return;
-    await deps.sendQueuedAttachments(turn);
+    if (!richAttachmentDelivered) await deps.sendQueuedAttachments(turn);
     if (!isDeliveryActive()) return;
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
   };

package/lib/routing.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram inbound routing composition
  * Zones: telegram inbound, orchestration, queue/menu/command composition
- * Wires authorized updates into menus, commands, media grouping, and prompt queueing
+ * Wires authorized updates into menus, commands, media grouping, and prompt queueing, and owns exact assistant-output target/route authority capture
  */
 
 import { readFile } from "node:fs/promises";
@@ -2471,3 +2471,90 @@ export function createTelegramInboundRouteRuntime<
     },
   });
 }
+
+// --- Assistant Output Delivery Authority ---
+
+export interface TelegramAssistantOutputAuthority<TTransportStamp> {
+  transportStamp: TTransportStamp;
+  route: "direct" | "follower" | "none";
+  directEpoch?: number | string;
+  followerGeneration?: string;
+  target?: Queue.TelegramQueueTarget;
+}
+
+export interface TelegramAssistantOutputAuthorityRuntime<TTransportStamp> {
+  captureAuthority: () => TelegramAssistantOutputAuthority<TTransportStamp>;
+  isAuthorityActive: (
+    authority: TelegramAssistantOutputAuthority<TTransportStamp>,
+  ) => boolean;
+  canDeliver: () => boolean;
+}
+
+export function createTelegramAssistantOutputAuthorityRuntime<TTransportStamp>(deps: {
+  getPreferredTarget: () => Queue.TelegramQueueTarget | undefined;
+  getFallbackChatId: () => number | undefined;
+  getTransportStamp: () => TTransportStamp;
+  isTransportStampActive: (stamp: TTransportStamp) => boolean;
+  ownsDirect: () => boolean;
+  getDirectEpoch: () => number | string | undefined;
+  isFollowerRegistered: () => boolean;
+  getFollowerGeneration: () => string | undefined;
+}): TelegramAssistantOutputAuthorityRuntime<TTransportStamp> {
+  const getCurrentTarget = (): Queue.TelegramQueueTarget | undefined => {
+    const preferred = deps.getPreferredTarget();
+    if (preferred) return { ...preferred };
+    const chatId = deps.getFallbackChatId();
+    return chatId === undefined ? undefined : { chatId };
+  };
+  return {
+    captureAuthority() {
+      const target = getCurrentTarget();
+      const directEpoch = deps.ownsDirect()
+        ? deps.getDirectEpoch()
+        : undefined;
+      const followerGeneration = deps.isFollowerRegistered()
+        ? deps.getFollowerGeneration()
+        : undefined;
+      return {
+        transportStamp: deps.getTransportStamp(),
+        route:
+          directEpoch !== undefined
+            ? "direct"
+            : followerGeneration !== undefined
+              ? "follower"
+              : "none",
+        directEpoch,
+        followerGeneration,
+        target,
+      };
+    },
+    isAuthorityActive(authority) {
+      if (!deps.isTransportStampActive(authority.transportStamp)) return false;
+      const target = getCurrentTarget();
+      if (
+        authority.target === undefined ||
+        target?.chatId !== authority.target.chatId ||
+        target?.threadId !== authority.target.threadId
+      ) {
+        return false;
+      }
+      if (authority.route === "direct") {
+        return (
+          deps.ownsDirect() &&
+          deps.getDirectEpoch() === authority.directEpoch
+        );
+      }
+      if (authority.route === "follower") {
+        return (
+          !deps.ownsDirect() &&
+          deps.isFollowerRegistered() &&
+          deps.getFollowerGeneration() === authority.followerGeneration
+        );
+      }
+      return false;
+    },
+    canDeliver() {
+      return deps.ownsDirect() || deps.isFollowerRegistered();
+    },
+  };
+}

package/lib/sync.ts

@@ -123,6 +123,7 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
   getLeaderTarget: () => TelegramTarget | undefined;
   getCurrentLeaderEpoch?: () => number | string | undefined;
   clearLeaderTarget: () => void;
+  disconnectFollowerThread?: () => Promise<boolean>;
   getSyncState: () => TSyncState;
   setSyncState: (state: TSyncState) => void;
   stopPolling: () => Promise<string>;
@@ -160,13 +161,25 @@ export function createTelegramManualThreadDisconnectHandler<
     const currentRecord = deps.getCurrentThreadRecord();
     if (currentRecord?.target.threadId) {
       const isManualFollower = currentRecord.owner?.kind === "manual-follower";
-      if (!isManualFollower) {
-        const leaderEpoch = deps.getCurrentLeaderEpoch?.();
+      const leaderEpoch = deps.getCurrentLeaderEpoch?.();
+      const ownsLeader = deps.getCurrentLeaderEpoch
+        ? leaderEpoch !== undefined
+        : !isManualFollower;
+      if (isManualFollower && !ownsLeader) {
+        if (deps.disconnectFollowerThread) {
+          const disconnected = await deps.disconnectFollowerThread();
+          if (!disconnected) {
+            throw new Error(
+              "Telegram follower thread deletion requires a live leader registration.",
+            );
+          }
+        }
+      } else {
         const stillOwnsLeaderEpoch = () =>
           !deps.getCurrentLeaderEpoch ||
           (leaderEpoch !== undefined &&
             deps.getCurrentLeaderEpoch() === leaderEpoch);
-        await ThreadReconciler.applyThreadReconciliationPlan(
+        const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
           ThreadReconciler.planDisconnectedInstanceThreadCleanup({
             target: currentRecord.target as TelegramTarget & {
               threadId: number;
@@ -185,6 +198,11 @@ export function createTelegramManualThreadDisconnectHandler<
             recordRuntimeEvent: deps.recordRuntimeEvent,
           },
         );
+        if (cleanup.incompleteActions?.length) {
+          throw new Error(
+            "Telegram thread deletion was not confirmed; inspect /telegram-status --debug and retry /telegram-disconnect.",
+          );
+        }
         if (!stillOwnsLeaderEpoch()) return deps.stopPolling();
         const offlineChanged =
           deps.topicTargetStore.markOfflineByInstanceId(deps.instanceId) > 0;
@@ -278,6 +296,15 @@ export interface TelegramStaleTopicApiErrorRecoveryDeps<TSyncState> {
   getNowMs?: () => number;
 }
 
+export function createTelegramStaleTopicApiErrorRecoveryRuntime<
+  TSyncState extends TelegramSyncState,
+>(
+  deps: TelegramStaleTopicApiErrorRecoveryDeps<TSyncState>,
+): (apiBody: unknown, error: unknown) => Promise<boolean> {
+  return (apiBody, error) =>
+    recoverStaleTelegramTopicApiError(apiBody, error, deps);
+}
+
 export async function recoverStaleTelegramTopicApiError<
   TSyncState extends TelegramSyncState,
 >(
@@ -493,6 +520,16 @@ export interface TelegramSyncStateRuntime {
   ): void;
 }
 
+export function createTelegramConfigSyncPersister<TConfig>(deps: {
+  persist: (config?: TConfig) => Promise<void>;
+  markConfigChange: (action: string) => void;
+}): (config?: TConfig) => Promise<void> {
+  return async (config) => {
+    await deps.persist(config);
+    deps.markConfigChange("config-persist");
+  };
+}
+
 export function createTelegramSyncStateRuntime(
   initialState = createUnknownTelegramSyncState(),
 ): TelegramSyncStateRuntime {

package/lib/telegram-api.ts

@@ -212,19 +212,83 @@ export type TelegramSendMessageBody = Record<string, unknown> & {
   reply_parameters?: TelegramReplyParameters;
 };
 
-export type TelegramInputRichMessage =
-  | {
-      markdown: string;
-      html?: never;
-      is_rtl?: boolean;
-      skip_entity_detection?: boolean;
-    }
-  | {
-      html: string;
-      markdown?: never;
-      is_rtl?: boolean;
-      skip_entity_detection?: boolean;
-    };
+export interface TelegramInputMediaPhoto extends Record<string, unknown> {
+  type: "photo";
+  media: string;
+  has_spoiler?: boolean;
+}
+
+export interface TelegramInputMediaVideo extends Record<string, unknown> {
+  type: "video";
+  media: string;
+  thumbnail?: string;
+  width?: number;
+  height?: number;
+  duration?: number;
+  supports_streaming?: boolean;
+  has_spoiler?: boolean;
+}
+
+export interface TelegramInputMediaAnimation extends Record<string, unknown> {
+  type: "animation";
+  media: string;
+  thumbnail?: string;
+  width?: number;
+  height?: number;
+  duration?: number;
+  has_spoiler?: boolean;
+}
+
+export interface TelegramInputMediaAudio extends Record<string, unknown> {
+  type: "audio";
+  media: string;
+  thumbnail?: string;
+  duration?: number;
+  performer?: string;
+  title?: string;
+}
+
+export interface TelegramInputMediaVoiceNote extends Record<string, unknown> {
+  type: "voice_note";
+  media: string;
+  caption?: string;
+  parse_mode?: string;
+  caption_entities?: unknown[];
+  duration?: number;
+}
+
+export type TelegramInputRichMessageMediaValue =
+  | TelegramInputMediaAnimation
+  | TelegramInputMediaAudio
+  | TelegramInputMediaPhoto
+  | TelegramInputMediaVideo
+  | TelegramInputMediaVoiceNote;
+
+export interface TelegramInputRichMessageMedia {
+  id: string;
+  media: TelegramInputRichMessageMediaValue;
+}
+
+type TelegramInputRichMessageCommon = {
+  is_rtl?: boolean;
+  skip_entity_detection?: boolean;
+};
+
+export type TelegramInputRichMessage = TelegramInputRichMessageCommon &
+  (
+    | {
+        markdown: string;
+        html?: never;
+        blocks?: never;
+        media?: TelegramInputRichMessageMedia[];
+      }
+    | {
+        html: string;
+        markdown?: never;
+        blocks?: never;
+        media?: TelegramInputRichMessageMedia[];
+      }
+  );
 
 export type TelegramSendRichMessageBody = Record<string, unknown> & {
   chat_id: number;