@llblab/pi-telegram 0.22.1 → 0.23.0

package/lib/bus.ts

@@ -158,28 +158,22 @@ export function getTelegramFollowerTargetOwnership(input: {
     target: TelegramTarget;
   }[];
   currentInstanceId?: string;
-}): { instanceId: string } | undefined {
+}): { instanceId: string; ownerGeneration?: string } | undefined {
   const liveFollower = input.followers.find((follower) => {
     return (
       follower.target?.chatId === input.target.chatId &&
       follower.target.threadId === input.target.threadId
     );
   });
-  if (liveFollower) return { instanceId: liveFollower.instanceId };
-  const record = input.activeThreadRecords?.find((candidate) => {
-    const isFollowerRecord = candidate.owner?.kind
-      ? candidate.owner.kind === "manual-follower"
-      : candidate.profileKey?.startsWith("manual:") === true;
-    return (
-      isFollowerRecord &&
-      candidate.status === "active" &&
-      candidate.instanceId &&
-      candidate.instanceId !== input.currentInstanceId &&
-      candidate.target.chatId === input.target.chatId &&
-      candidate.target.threadId === input.target.threadId
-    );
-  });
-  return record?.instanceId ? { instanceId: record.instanceId } : undefined;
+  if (liveFollower) {
+    return {
+      instanceId: liveFollower.instanceId,
+      ownerGeneration: liveFollower.registrationGeneration,
+    };
+  }
+  // Persisted records are restart hints, not live routing authority. Only an
+  // authenticated current follower registration may receive forwarded work.
+  return undefined;
 }
 
 const TELEGRAM_BUS_AGGREGATE_DELIVERY_FIELD = "__piTelegramAggregateDelivery";
@@ -237,6 +231,7 @@ export function isTelegramFollowerApiCallAllowed(input: {
     "sendDocument",
     "sendMediaGroup",
     "sendPhoto",
+    "sendRichMessage",
     "sendVoice",
   ]);
   const target = input.follower.target;
@@ -363,6 +358,13 @@ export type TelegramBusEnvelope = (
       registrationGeneration?: string;
       sentAtMs: number;
     }
+  | {
+      kind: "follower.disconnect";
+      requestId: string;
+      instanceId: string;
+      registrationGeneration?: string;
+      sentAtMs: number;
+    }
   | {
       kind: "leader.forwardCallback";
       requestId: string;
@@ -385,6 +387,7 @@ export type TelegramBusEnvelope = (
       recipientInstanceId: string;
       recipientRegistrationGeneration?: string;
       message: unknown;
+      forwardCommentBatchPosition?: "comment" | "forward";
       sentAtMs: number;
     }
   | {
@@ -473,6 +476,9 @@ export function parseTelegramBusEnvelope(
     case "follower.heartbeat":
       envelope = parseHeartbeatEnvelope(value, requestId);
       break;
+    case "follower.disconnect":
+      envelope = parseDisconnectEnvelope(value, requestId);
+      break;
     case "leader.forwardCallback":
       envelope = parseForwardCallbackEnvelope(value, requestId);
       break;
@@ -548,12 +554,20 @@ export interface TelegramBusLocalClientOptions {
   recordTransportEvent?: TelegramBusTransportEventRecorder;
 }
 
-export interface TelegramBusForeignOwnedForwarderDeps {
+export interface TelegramBusForeignOwnedForwarderDeps<TMessage = unknown> {
   socketPath: TelegramBusSocketPathSource;
   createRequestId: () => string;
   getNowMs?: () => number;
   timeoutMs?: number;
   getAuthSecret?: () => string | undefined;
+  getForwardCommentBatchPosition?: (
+    message: TMessage,
+  ) => "comment" | "forward" | undefined;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
 }
 
 export function createTelegramBusForeignOwnedUpdateForwarder<
@@ -562,7 +576,7 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
   TCallbackQuery,
   TMessage = unknown,
 >(
-  deps: TelegramBusForeignOwnedForwarderDeps,
+  deps: TelegramBusForeignOwnedForwarderDeps<TMessage>,
 ): {
   forwardCallback: (input: {
     query: TCallbackQuery;
@@ -598,7 +612,24 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
         operation: "operation",
       }),
     });
-    return response?.kind === "bus.ack" && response.ok;
+    const accepted = response?.kind === "bus.ack" && response.ok;
+    if (!accepted) {
+      deps.recordRuntimeEvent?.(
+        "bus",
+        response?.kind === "bus.ack"
+          ? response.message ?? "Follower rejected forwarded Telegram update."
+          : "Follower returned no forwarding acknowledgement.",
+        {
+          phase: "foreign-update-forward-rejected",
+          envelopeKind: envelope.kind,
+          recipientInstanceId:
+            "recipientInstanceId" in envelope
+              ? envelope.recipientInstanceId
+              : undefined,
+        },
+      );
+    }
+    return accepted;
   };
   return {
     forwardCallback: ({ query, ownership }) =>
@@ -632,6 +663,12 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
           ? { recipientRegistrationGeneration: ownership.ownerGeneration }
           : {}),
         message,
+        ...(deps.getForwardCommentBatchPosition?.(message) !== undefined
+          ? {
+              forwardCommentBatchPosition:
+                deps.getForwardCommentBatchPosition(message),
+            }
+          : {}),
         sentAtMs: getNowMs(),
       }),
     forwardEditedMessage: ({ message, ownership }) =>
@@ -1287,6 +1324,24 @@ function parseHeartbeatEnvelope(
     : undefined;
 }
 
+function parseDisconnectEnvelope(
+  value: Record<string, unknown>,
+  requestId: string,
+): TelegramBusEnvelope | undefined {
+  return typeof value.instanceId === "string" &&
+    typeof value.sentAtMs === "number"
+    ? {
+        kind: "follower.disconnect",
+        requestId,
+        instanceId: value.instanceId,
+        ...(typeof value.registrationGeneration === "string"
+          ? { registrationGeneration: value.registrationGeneration }
+          : {}),
+        sentAtMs: value.sentAtMs,
+      }
+    : undefined;
+}
+
 function parseForwardCallbackEnvelope(
   value: Record<string, unknown>,
   requestId: string,
@@ -1349,6 +1404,14 @@ function parseForwardMessageEnvelope(
             }
           : {}),
         message: value.message,
+        ...(kind === "leader.forwardMessage" &&
+        (value.forwardCommentBatchPosition === "comment" ||
+          value.forwardCommentBatchPosition === "forward")
+          ? {
+              forwardCommentBatchPosition:
+                value.forwardCommentBatchPosition,
+            }
+          : {}),
         sentAtMs: value.sentAtMs,
       }
     : undefined;

package/lib/commands.ts

@@ -307,6 +307,7 @@ export interface TelegramBridgeCommandRegistrationDeps {
     | Promise<void | TelegramBridgeCommandStartPollingResult>
     | TelegramBridgeCommandStartPollingResult;
   stopPolling: () => Promise<void | string>;
+  getDisconnectThreadName?: () => string | undefined;
   updateStatus: (ctx: ExtensionCommandContext) => void;
   getProfileNames?: () => string[];
   activateDefaultProfileConfig?: (ctx: ExtensionCommandContext) => Promise<void>;
@@ -411,11 +412,34 @@ export function registerTelegramBridgeCommands(
     },
   });
   pi.registerCommand("telegram-disconnect", {
-    description: "Stop the Telegram bridge in this Pi session",
+    description:
+      "Stop Telegram; in Threaded Mode, delete this instance's current thread",
     handler: async (_args, ctx) => {
-      const message = await deps.stopPolling();
-      if (message) ctx.ui.notify(message, "info");
-      deps.updateStatus(ctx);
+      const threadName = deps.getDisconnectThreadName?.();
+      if (threadName) {
+        const confirmed = await ctx.ui.confirm(
+          ctx.ui.theme.fg("accent", "pi-telegram"),
+          `Delete Telegram thread ${ctx.ui.theme.fg("warning", threadName)} and disconnect this Pi session?`,
+        );
+        if (!confirmed) {
+          ctx.ui.notify("Telegram disconnect cancelled.", "info");
+          deps.updateStatus(ctx);
+          return;
+        }
+      }
+      try {
+        const message = await deps.stopPolling();
+        if (message) ctx.ui.notify(message, "info");
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(
+          `Telegram disconnect did not complete: ${detail} Keep this Pi session open, restore leader connectivity, inspect /telegram-status --debug, and retry /telegram-disconnect.`,
+          "warning",
+        );
+        throw error;
+      } finally {
+        deps.updateStatus(ctx);
+      }
     },
   });
 }

package/lib/config.ts

@@ -60,10 +60,10 @@ export interface TelegramConfig {
   inboundHandlers?: TelegramInboundHandlerConfig[];
   attachmentHandlers?: TelegramInboundHandlerConfig[];
   outboundHandlers?: TelegramOutboundHandlerConfig[];
-  proactivePush?: boolean;
   assistant?: {
     draftPreviews?: boolean;
     rendering?: TelegramAssistantRenderingMode;
+    proactivePush?: boolean;
   };
   /** @deprecated use assistant.draftPreviews */
   draftPreviews?: boolean;
@@ -85,7 +85,7 @@ export interface TelegramConfig {
  * Per-profile bot/session identity fields.
  * Stored under `profiles.<name>` in telegram.json.
  * Shared bridge settings (inboundHandlers, outboundHandlers, voice, time,
- * assistant, proactivePush) stay at the top level.
+ * assistant) stay at the top level.
  */
 export interface TelegramBotProfile {
   botToken: string;
@@ -259,31 +259,39 @@ export async function readTelegramConfig(
     onInvalidConfig?: (recovery: TelegramInvalidConfigRecovery) => void;
   } = {},
 ): Promise<TelegramConfig> {
-  return withTelegramFileTransaction(`${configPath}.transaction`, () => {
-    if (!existsSync(configPath)) return {};
-    const identity = statSync(configPath);
-    const content = readFileSync(configPath, "utf8");
-    try {
-      return JSON.parse(content) as TelegramConfig;
-    } catch (error) {
-      const currentIdentity = statSync(configPath);
-      if (
-        currentIdentity.dev !== identity.dev ||
-        currentIdentity.ino !== identity.ino ||
-        currentIdentity.size !== identity.size ||
-        currentIdentity.mtimeMs !== identity.mtimeMs
-      ) {
-        throw new Error(
-          `Telegram config changed while validating invalid content: ${configPath}`,
-          { cause: error },
-        );
+  if (!existsSync(configPath)) return {};
+  const content = readFileSync(configPath, "utf8");
+  try {
+    return JSON.parse(content) as TelegramConfig;
+  } catch {
+    // Atomic config publication makes ordinary reads safe without serialization.
+    // Acquire the transaction only before destructive invalid-file recovery.
+    return withTelegramFileTransaction(`${configPath}.transaction`, () => {
+      if (!existsSync(configPath)) return {};
+      const identity = statSync(configPath);
+      const currentContent = readFileSync(configPath, "utf8");
+      try {
+        return JSON.parse(currentContent) as TelegramConfig;
+      } catch (error) {
+        const currentIdentity = statSync(configPath);
+        if (
+          currentIdentity.dev !== identity.dev ||
+          currentIdentity.ino !== identity.ino ||
+          currentIdentity.size !== identity.size ||
+          currentIdentity.mtimeMs !== identity.mtimeMs
+        ) {
+          throw new Error(
+            `Telegram config changed while validating invalid content: ${configPath}`,
+            { cause: error },
+          );
+        }
+        const recoveryPath = getInvalidTelegramConfigRecoveryPath(configPath);
+        renameSync(configPath, recoveryPath);
+        options.onInvalidConfig?.({ configPath, recoveryPath, error });
+        return {};
       }
-      const recoveryPath = getInvalidTelegramConfigRecoveryPath(configPath);
-      renameSync(configPath, recoveryPath);
-      options.onInvalidConfig?.({ configPath, recoveryPath, error });
-      return {};
-    }
-  });
+    });
+  }
 }
 
 export async function writeTelegramConfig(
@@ -538,7 +546,7 @@ export function createTelegramConfigStore(
 export function createTelegramProactivePushChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
-  return () => configStore.get().proactivePush ?? false;
+  return () => configStore.get().assistant?.proactivePush ?? true;
 }
 
 export function createTelegramProactivePushSetter(
@@ -546,7 +554,11 @@ export function createTelegramProactivePushSetter(
 ): (enabled: boolean) => Promise<void> {
   return async (enabled) => {
     await loadLatestTelegramConfig(configStore);
-    const config = { ...configStore.get(), proactivePush: enabled };
+    const current = configStore.get();
+    const config = {
+      ...current,
+      assistant: { ...current.assistant, proactivePush: enabled },
+    };
     configStore.set(config);
     await configStore.persist(config);
   };

package/lib/media.ts

@@ -682,11 +682,107 @@ export async function downloadTelegramMessageFiles(
   return downloaded;
 }
 
+function collectTelegramRichBlockFileInfos(
+  blocks: unknown,
+  messageId: number,
+): TelegramFileInfo[] {
+  if (!Array.isArray(blocks)) return [];
+  const files: TelegramFileInfo[] = [];
+  let mediaIndex = 0;
+  const visit = (entries: unknown): void => {
+    if (!Array.isArray(entries)) return;
+    for (const entry of entries) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const type = getObjectField(entry, "type");
+      if (
+        type === "photo" ||
+        type === "animation" ||
+        type === "audio" ||
+        type === "video" ||
+        type === "voice_note"
+      ) {
+        mediaIndex += 1;
+      }
+      if (type === "photo") {
+        const photos = getObjectField(entry, "photo");
+        if (Array.isArray(photos)) {
+          const photo = photos
+            .filter(
+              (value): value is TelegramPhotoSize =>
+                typeof value === "object" &&
+                value !== null &&
+                typeof getObjectField(value, "file_id") === "string",
+            )
+            .sort((a, b) => (a.file_size ?? 0) - (b.file_size ?? 0))
+            .at(-1);
+          if (photo) {
+            files.push({
+              file_id: photo.file_id,
+              fileName: `photo-${messageId}-${mediaIndex}.jpg`,
+              mimeType: "image/jpeg",
+              kind: "photo",
+              isImage: true,
+            });
+          }
+        }
+      }
+      const fileField =
+        type === "animation"
+          ? "animation"
+          : type === "audio"
+            ? "audio"
+            : type === "video"
+              ? "video"
+              : type === "voice_note"
+                ? "voice_note"
+                : undefined;
+      if (fileField) {
+        const media = getObjectField(entry, fileField);
+        const fileId = getObjectField(media, "file_id");
+        const mimeType = getObjectField(media, "mime_type");
+        const fileName = getObjectField(media, "file_name");
+        if (typeof fileId === "string") {
+          const kind =
+            type === "voice_note" ? "voice" : (type as TelegramAttachmentKind);
+          const fallbackExtension =
+            kind === "voice" ? ".ogg" : kind === "audio" ? ".mp3" : ".mp4";
+          files.push({
+            file_id: fileId,
+            fileName:
+              typeof fileName === "string"
+                ? fileName
+                : `${kind}-${messageId}-${mediaIndex}${guessExtensionFromMime(
+                    typeof mimeType === "string" ? mimeType : undefined,
+                    fallbackExtension,
+                  )}`,
+            mimeType: typeof mimeType === "string" ? mimeType : undefined,
+            kind,
+            isImage: false,
+          });
+        }
+      }
+      visit(getObjectField(entry, "blocks"));
+      const items = getObjectField(entry, "items");
+      if (Array.isArray(items)) {
+        for (const item of items) visit(getObjectField(item, "blocks"));
+      }
+    }
+  };
+  visit(blocks);
+  return files;
+}
+
 export function collectTelegramFileInfos(
   messages: TelegramMediaMessage[],
 ): TelegramFileInfo[] {
   const files: TelegramFileInfo[] = [];
   for (const message of messages) {
+    files.push(
+      ...collectTelegramRichBlockFileInfos(
+        message.rich_message?.blocks,
+        message.message_id,
+      ),
+    );
     if (Array.isArray(message.photo) && message.photo.length > 0) {
       const photo = [...message.photo]
         .sort((a, b) => (a.file_size ?? 0) - (b.file_size ?? 0))
@@ -786,5 +882,10 @@ export function collectTelegramFileInfos(
       });
     }
   }
-  return files;
+  const seenFileIds = new Set<string>();
+  return files.filter((file) => {
+    if (seenFileIds.has(file.file_id)) return false;
+    seenFileIds.add(file.file_id);
+    return true;
+  });
 }

package/lib/menu-settings.ts

@@ -159,7 +159,10 @@ export function buildProactivePushSettingsText(
   return [
     `${PROACTIVE_PUSH_SETTINGS_TITLE} <code>${proactivePushEnabled ? "on" : "off"}</code>`,
     "",
-    "Send successful local Pi task results to Telegram when the bridge is connected.",
+    "Control whether public assistant output from local/autonomous work is projected to Telegram.",
+    "",
+    "<code>-</code> <code>on</code> (default): send each completed public block, including visible checkpoints and the final answer, while connected.",
+    "<code>-</code> <code>off</code>: keep local/autonomous assistant blocks in Pi; Telegram-originated replies still use their normal delivery path.",
   ].join("\n");
 }
 

package/lib/outbound-attachments.ts

@@ -10,7 +10,10 @@ import { basename } from "node:path";
 import { Type } from "@sinclair/typebox";
 
 import type { ExtensionAPI } from "./pi.ts";
-import { buildTelegramMultipartReplyParameters } from "./replies.ts";
+import {
+  buildTelegramMultipartReplyParameters,
+  normalizeTelegramNativeMarkdown,
+} from "./replies.ts";
 import {
   getTelegramTargetThreadParams,
   type TelegramTarget,
@@ -97,6 +100,152 @@ export interface TelegramQueuedOutboundAttachmentTurnView extends TelegramOutbou
   target?: TelegramTarget;
 }
 
+class TelegramRichAttachmentCommitUnknownError extends Error {
+  readonly kind = "commit-unknown" as const;
+
+  constructor(cause: unknown) {
+    super("Telegram Rich media upload may have committed without a message id.");
+    this.name = "TelegramRichAttachmentCommitUnknownError";
+    this.cause = cause;
+  }
+}
+
+function isTelegramRichAttachmentCommitUnknownError(error: unknown): boolean {
+  return (
+    error instanceof TelegramRichAttachmentCommitUnknownError ||
+    (typeof error === "object" &&
+      error !== null &&
+      (error as { kind?: unknown }).kind === "commit-unknown")
+  );
+}
+
+export interface TelegramRichOutboundAttachmentPlan {
+  method: "sendRichMessage";
+  fields: Record<string, string>;
+  fileField: "rich_media_upload";
+  filePath: string;
+  fileName: string;
+}
+
+export interface TelegramRichOutboundAttachmentSenderDeps extends TelegramOutboundAttachmentRuntimeEventRecorderPort {
+  sendMultipart: TelegramQueuedOutboundAttachmentDeliveryDeps["sendMultipart"];
+  getRenderingMode: () => "rich" | "html";
+  recordOwnership?: (input: {
+    chatId: number;
+    messageId: number;
+    target?: TelegramTarget;
+  }) => void;
+}
+
+export function planTelegramRichOutboundAttachment(options: {
+  turn: TelegramQueuedOutboundAttachmentTurnView;
+  markdown: string;
+  renderingMode: "rich" | "html";
+  replyMarkup?: unknown;
+}): TelegramRichOutboundAttachmentPlan | undefined {
+  if (options.renderingMode !== "rich") return undefined;
+  if (!options.markdown.trim()) return undefined;
+  if (options.turn.queuedAttachments.length !== 1) return undefined;
+  const attachment = options.turn.queuedAttachments[0]!;
+  const normalizedPath = attachment.path.toLowerCase();
+  const mediaType = normalizedPath.endsWith(".jpg") ||
+      normalizedPath.endsWith(".jpeg") ||
+      normalizedPath.endsWith(".png")
+    ? "photo"
+    : normalizedPath.endsWith(".mp4")
+      ? "video"
+      : normalizedPath.endsWith(".mp3")
+        ? "audio"
+        : undefined;
+  if (!mediaType) return undefined;
+  const mediaId = "artifact";
+  const richMessage = {
+    markdown: `${normalizeTelegramNativeMarkdown(options.markdown)}\n\n![](tg://${mediaType}?id=${mediaId})`,
+    media: [
+      {
+        id: mediaId,
+        media: {
+          type: mediaType,
+          media: "attach://rich_media_upload",
+        },
+      },
+    ],
+    skip_entity_detection: true,
+  };
+  const replyParameters =
+    options.turn.replyToMessageId > 0
+      ? JSON.stringify({
+          message_id: options.turn.replyToMessageId,
+          allow_sending_without_reply: true,
+        })
+      : undefined;
+  return {
+    method: "sendRichMessage",
+    fields: {
+      chat_id: String(options.turn.chatId),
+      ...(replyParameters ? { reply_parameters: replyParameters } : {}),
+      ...getTelegramMultipartTargetFields(options.turn.target),
+      rich_message: JSON.stringify(richMessage),
+      ...(options.replyMarkup
+        ? { reply_markup: JSON.stringify(options.replyMarkup) }
+        : {}),
+    },
+    fileField: "rich_media_upload",
+    filePath: attachment.path,
+    fileName: attachment.fileName,
+  };
+}
+
+export function createTelegramRichOutboundAttachmentSender(
+  deps: TelegramRichOutboundAttachmentSenderDeps,
+) {
+  return async (
+    turn: TelegramQueuedOutboundAttachmentTurnView,
+    markdown: string,
+    options?: { replyMarkup?: unknown },
+  ): Promise<boolean> => {
+    const plan = planTelegramRichOutboundAttachment({
+      turn,
+      markdown,
+      renderingMode: deps.getRenderingMode(),
+      replyMarkup: options?.replyMarkup,
+    });
+    if (!plan) return false;
+    try {
+      const result = await deps.sendMultipart(
+        plan.method,
+        plan.fields,
+        plan.fileField,
+        plan.filePath,
+        plan.fileName,
+      );
+      const messageId =
+        result && typeof result === "object" &&
+          Number.isInteger((result as { message_id?: unknown }).message_id)
+          ? (result as { message_id: number }).message_id
+          : undefined;
+      if (messageId === undefined) {
+        throw new TelegramRichAttachmentCommitUnknownError(
+          new Error("Successful Rich media upload omitted message_id."),
+        );
+      }
+      deps.recordOwnership?.({
+        chatId: turn.chatId,
+        messageId,
+        target: turn.target,
+      });
+      return true;
+    } catch (error) {
+      if (isTelegramRichAttachmentCommitUnknownError(error)) throw error;
+      deps.recordRuntimeEvent?.("attachment", error, {
+        phase: "rich-media-known-failure",
+        fileName: plan.fileName,
+      });
+      return false;
+    }
+  };
+}
+
 export type TelegramGuestCachedAttachmentResult =
   | {
       type: "document";