@llblab/pi-telegram 0.2.10 → 0.4.0

package/lib/locks.ts

@@ -0,0 +1,306 @@
+/**
+ * Telegram singleton lock helpers
+ * Owns shared locks.json access and Telegram bridge ownership semantics
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export const TELEGRAM_LOCK_KEY = "@llblab/pi-telegram";
+
+function getAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR
+    ? resolve(process.env.PI_CODING_AGENT_DIR)
+    : join(homedir(), ".pi", "agent");
+}
+
+function getLocksPath(): string {
+  return join(getAgentDir(), "locks.json");
+}
+
+export interface TelegramLockEntry {
+  pid: number;
+  cwd?: string;
+}
+
+export interface TelegramLockContext {
+  cwd: string;
+}
+
+export type TelegramLockState =
+  | { kind: "inactive" }
+  | { kind: "active-here"; lock: TelegramLockEntry }
+  | { kind: "active-elsewhere"; lock: TelegramLockEntry }
+  | { kind: "stale"; lock: TelegramLockEntry };
+
+export interface TelegramLockAcquireOptions {
+  force?: boolean;
+}
+
+export type TelegramLockAcquireResult =
+  | { ok: true; lock: TelegramLockEntry; replacedStale: boolean }
+  | { ok: false; lock: TelegramLockEntry };
+
+export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
+  acquire: (
+    ctx: TContext,
+    options?: TelegramLockAcquireOptions,
+  ) => TelegramLockAcquireResult;
+  release: () => TelegramLockState;
+  getState: () => TelegramLockState;
+  getStatusLabel: () => string;
+  owns: (ctx?: TelegramLockContext) => boolean;
+}
+
+export interface TelegramLockRuntimeOptions {
+  key?: string;
+  locksPath?: string;
+  pid?: number;
+  isProcessAlive?: (pid: number) => boolean;
+}
+
+export interface TelegramLockedPollingStartOptions {
+  force?: boolean;
+}
+
+export type TelegramLockedPollingStartResult =
+  | { ok: true; message: string; canTakeover?: false }
+  | { ok: false; message: string; canTakeover?: boolean; owner?: string };
+
+export interface TelegramLockedPollingRuntime<TContext extends TelegramLockContext> {
+  start: (
+    ctx: TContext,
+    options?: TelegramLockedPollingStartOptions,
+  ) => Promise<TelegramLockedPollingStartResult>;
+  stop: () => Promise<string>;
+  suspend: () => Promise<void>;
+  onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
+}
+
+export interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext> {
+  lock: TelegramLockRuntime<TContext>;
+  hasBotToken: () => boolean;
+  startPolling: (ctx: TContext) => void | Promise<void>;
+  stopPolling: () => Promise<void>;
+  updateStatus: (ctx: TContext) => void;
+  recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
+  ownershipCheckMs?: number;
+}
+
+export function readLocks(path = getLocksPath()): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeLocks(path: string, locks: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, "utf8");
+    renameSync(tempPath, path);
+  } catch (error) {
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      /* best effort */
+    }
+    throw error;
+  }
+}
+
+export function parseTelegramLockEntry(value: unknown): TelegramLockEntry | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  if (typeof record.pid !== "number") return undefined;
+  return {
+    pid: record.pid,
+    cwd: typeof record.cwd === "string" ? record.cwd : undefined,
+  };
+}
+
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as { code?: string }).code === "EPERM";
+  }
+}
+
+function formatLock(lock: TelegramLockEntry): string {
+  return lock.cwd ? `pid ${lock.pid}, cwd ${lock.cwd}` : `pid ${lock.pid}`;
+}
+
+function getLockState(lock: TelegramLockEntry | undefined, pid: number, isAlive: (pid: number) => boolean): TelegramLockState {
+  if (!lock) return { kind: "inactive" };
+  if (lock.pid === pid) return { kind: "active-here", lock };
+  if (isAlive(lock.pid)) return { kind: "active-elsewhere", lock };
+  return { kind: "stale", lock };
+}
+
+function ownsLockContext(
+  lock: TelegramLockEntry | undefined,
+  pid: number,
+  ctx?: TelegramLockContext,
+): boolean {
+  if (!lock || lock.pid !== pid) return false;
+  return !lock.cwd || !ctx || lock.cwd === ctx.cwd;
+}
+
+function snapshotLockContext(ctx: TelegramLockContext): TelegramLockContext {
+  return { cwd: ctx.cwd };
+}
+
+function formatLockState(state: TelegramLockState): string {
+  switch (state.kind) {
+    case "inactive":
+      return "inactive";
+    case "active-here":
+      return "active here";
+    case "active-elsewhere":
+      return `active elsewhere (${formatLock(state.lock)})`;
+    case "stale":
+      return `stale (${formatLock(state.lock)})`;
+  }
+}
+
+export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
+  options: TelegramLockRuntimeOptions = {},
+): TelegramLockRuntime<TContext> {
+  const key = options.key ?? TELEGRAM_LOCK_KEY;
+  const locksPath = options.locksPath ?? getLocksPath();
+  const pid = options.pid ?? process.pid;
+  const isAlive = options.isProcessAlive ?? isProcessAlive;
+  const readLock = () => parseTelegramLockEntry(readLocks(locksPath)[key]);
+  const writeLock = (lock: TelegramLockEntry) => {
+    const locks = readLocks(locksPath);
+    locks[key] = lock;
+    writeLocks(locksPath, locks);
+  };
+  return {
+    acquire: (ctx, acquireOptions = {}) => {
+      const state = getLockState(readLock(), pid, isAlive);
+      if (state.kind === "active-elsewhere" && !acquireOptions.force)
+        return { ok: false, lock: state.lock };
+      const lock = { pid, cwd: ctx.cwd };
+      writeLock(lock);
+      return { ok: true, lock, replacedStale: state.kind === "stale" };
+    },
+    release: () => {
+      const state = getLockState(readLock(), pid, isAlive);
+      if (state.kind === "active-here" || state.kind === "stale") {
+        const locks = readLocks(locksPath);
+        delete locks[key];
+        writeLocks(locksPath, locks);
+      }
+      return state;
+    },
+    getState: () => getLockState(readLock(), pid, isAlive),
+    getStatusLabel: () => formatLockState(getLockState(readLock(), pid, isAlive)),
+    owns: (ctx) => ownsLockContext(readLock(), pid, ctx),
+  };
+}
+
+export function createTelegramLockedPollingRuntime<TContext extends TelegramLockContext>(
+  deps: TelegramLockedPollingRuntimeDeps<TContext>,
+): TelegramLockedPollingRuntime<TContext> {
+  let ownershipInterval: ReturnType<typeof setInterval> | undefined;
+  let ownershipStop: Promise<void> | undefined;
+  const ownershipCheckMs = deps.ownershipCheckMs ?? 1000;
+  const stopOwnershipWatcher = () => {
+    if (!ownershipInterval) return;
+    clearInterval(ownershipInterval);
+    ownershipInterval = undefined;
+  };
+  const updateStatusSafely = (ctx: TContext, phase: string) => {
+    try {
+      deps.updateStatus(ctx);
+    } catch (error) {
+      deps.recordRuntimeEvent?.("lock", error, { phase });
+    }
+  };
+  const suspendPolling = async () => {
+    stopOwnershipWatcher();
+    if (ownershipStop) {
+      await ownershipStop;
+      return;
+    }
+    await deps.stopPolling();
+  };
+  const stopAfterOwnershipLoss = (ctx: TContext) => {
+    if (ownershipStop) return;
+    stopOwnershipWatcher();
+    ownershipStop = deps.stopPolling()
+      .catch((error) => deps.recordRuntimeEvent?.("lock", error, { phase: "ownership-loss" }))
+      .finally(() => {
+        ownershipStop = undefined;
+        updateStatusSafely(ctx, "ownership-loss-status");
+      });
+  };
+  const startOwnershipWatcher = (ctx: TContext) => {
+    const owner = snapshotLockContext(ctx);
+    stopOwnershipWatcher();
+    ownershipInterval = setInterval(() => {
+      if (deps.lock.owns(owner)) return;
+      stopAfterOwnershipLoss(ctx);
+    }, ownershipCheckMs);
+    ownershipInterval.unref?.();
+  };
+  return {
+    start: async (ctx, options = {}) => {
+      if (!deps.hasBotToken()) return { ok: false, message: "Telegram bot is not configured." };
+      const acquired = deps.lock.acquire(ctx, options);
+      if (!acquired.ok) {
+        return {
+          ok: false,
+          canTakeover: true,
+          owner: formatLock(acquired.lock),
+          message: `Telegram bridge is active in another pi instance (${formatLock(acquired.lock)}).`,
+        };
+      }
+      await deps.startPolling(ctx);
+      startOwnershipWatcher(ctx);
+      deps.updateStatus(ctx);
+      const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
+      return { ok: true, message: `Telegram bridge connected.${staleSuffix}` };
+    },
+    stop: async () => {
+      await suspendPolling();
+      const state = deps.lock.release();
+      if (state.kind === "active-elsewhere") {
+        return `Telegram bridge is active in another pi instance (${formatLock(state.lock)}).`;
+      }
+      if (state.kind === "stale") return `Removed stale Telegram bridge lock (${formatLock(state.lock)}).`;
+      return "Telegram bridge disconnected.";
+    },
+    suspend: suspendPolling,
+    onSessionStart: async (_event, ctx) => {
+      if (!deps.hasBotToken()) return;
+      const ownsCurrentLock = deps.lock.owns(ctx);
+      const state = ownsCurrentLock ? undefined : deps.lock.getState();
+      const canResumeStaleSameCwd =
+        state?.kind === "stale" && state.lock.cwd === ctx.cwd;
+      if (!ownsCurrentLock && !canResumeStaleSameCwd) return;
+      try {
+        if (canResumeStaleSameCwd) {
+          const acquired = deps.lock.acquire(ctx);
+          if (!acquired.ok) return;
+        }
+        await deps.startPolling(ctx);
+        startOwnershipWatcher(ctx);
+        deps.updateStatus(ctx);
+      } catch (error) {
+        deps.recordRuntimeEvent?.("lock", error, { phase: "auto-start" });
+      }
+    },
+  };
+}

package/lib/media.ts

@@ -3,59 +3,49 @@
  * Normalizes inbound Telegram messages into reusable file, text, id, history, and media-group metadata
  */
 
-export interface TelegramPhotoSizeLike {
-  file_id: string;
-  file_size?: number;
-}
+import { basename, dirname } from "node:path";
 
-export interface TelegramDocumentLike {
-  file_id: string;
-  file_name?: string;
-  mime_type?: string;
-}
+const TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS = 1200;
 
-export interface TelegramVideoLike {
+export interface TelegramPhotoSize {
   file_id: string;
-  file_name?: string;
-  mime_type?: string;
+  file_size?: number;
 }
 
-export interface TelegramAudioLike {
+export interface TelegramDocument {
   file_id: string;
   file_name?: string;
   mime_type?: string;
 }
 
-export interface TelegramVoiceLike {
-  file_id: string;
-  mime_type?: string;
-}
+export type TelegramVideo = TelegramDocument;
+export type TelegramAudio = TelegramDocument;
+export type TelegramAnimation = TelegramDocument;
 
-export interface TelegramAnimationLike {
+export interface TelegramVoice {
   file_id: string;
-  file_name?: string;
   mime_type?: string;
 }
 
-export interface TelegramStickerLike {
+export interface TelegramSticker {
   file_id: string;
 }
 
-export interface TelegramMessageLike {
+export interface TelegramMediaMessage {
   message_id: number;
   text?: string;
   caption?: string;
   media_group_id?: string;
-  photo?: TelegramPhotoSizeLike[];
-  document?: TelegramDocumentLike;
-  video?: TelegramVideoLike;
-  audio?: TelegramAudioLike;
-  voice?: TelegramVoiceLike;
-  animation?: TelegramAnimationLike;
-  sticker?: TelegramStickerLike;
+  photo?: TelegramPhotoSize[];
+  document?: TelegramDocument;
+  video?: TelegramVideo;
+  audio?: TelegramAudio;
+  voice?: TelegramVoice;
+  animation?: TelegramAnimation;
+  sticker?: TelegramSticker;
 }
 
-export interface TelegramMediaGroupMessageLike {
+export interface TelegramMediaGroupMessage {
   message_id: number;
   chat: { id: number };
   media_group_id?: string;
@@ -66,15 +56,76 @@ export interface TelegramMediaGroupState<TMessage> {
   flushTimer?: ReturnType<typeof setTimeout>;
 }
 
+export interface TelegramMediaGroupController<
+  TMessage extends TelegramMediaGroupMessage,
+> {
+  queueMessage: (options: {
+    message: TMessage;
+    dispatchMessages: (messages: TMessage[]) => void;
+  }) => boolean;
+  removeMessages: (messageIds: number[]) => number;
+  clear: () => void;
+}
+
+export interface TelegramMediaGroupDispatchRuntimeDeps<
+  TMessage extends TelegramMediaGroupMessage,
+  TContext,
+> {
+  mediaGroups: TelegramMediaGroupController<TMessage>;
+  dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
+}
+
+export interface TelegramMediaGroupDispatchRuntime<
+  TMessage extends TelegramMediaGroupMessage,
+  TContext,
+> {
+  handleMessage: (message: TMessage, ctx: TContext) => Promise<void>;
+}
+
+export interface TelegramMediaGroupControllerOptions {
+  debounceMs?: number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+export type TelegramAttachmentKind =
+  | "photo"
+  | "document"
+  | "video"
+  | "audio"
+  | "voice"
+  | "animation"
+  | "sticker";
+
 export interface TelegramFileInfo {
   file_id: string;
   fileName: string;
   mimeType?: string;
+  kind: TelegramAttachmentKind;
   isImage: boolean;
 }
 
-export interface DownloadedTelegramFileLike {
+export interface DownloadedTelegramFile {
   path: string;
+  fileName?: string;
+  isImage?: boolean;
+  mimeType?: string;
+  kind?: TelegramAttachmentKind;
+}
+
+export interface DownloadedTelegramMessageFile {
+  path: string;
+  fileName: string;
+  isImage: boolean;
+  mimeType?: string;
+  kind?: TelegramAttachmentKind;
+}
+
+export interface DownloadTelegramMessageFilesDeps {
+  downloadFile: (fileId: string, fileName: string) => Promise<string>;
 }
 
 export function guessExtensionFromMime(
@@ -106,43 +157,43 @@ export function guessMediaType(path: string): string | undefined {
   return undefined;
 }
 
-export function isImageMimeType(mimeType: string | undefined): boolean {
+function isImageMimeType(mimeType: string | undefined): boolean {
   return mimeType?.toLowerCase().startsWith("image/") ?? false;
 }
 
 export function extractTelegramMessageText(
-  message: TelegramMessageLike,
+  message: TelegramMediaMessage,
 ): string {
   return (message.text || message.caption || "").trim();
 }
 
 export function extractTelegramMessagesText(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): string {
   return messages.map(extractTelegramMessageText).filter(Boolean).join("\n\n");
 }
 
 export function extractFirstTelegramMessageText(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): string {
   return messages.map(extractTelegramMessageText).find(Boolean) ?? "";
 }
 
 export function collectTelegramMessageIds(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): number[] {
   return [...new Set(messages.map((message) => message.message_id))];
 }
 
 export function getTelegramMediaGroupKey(
-  message: TelegramMediaGroupMessageLike,
+  message: TelegramMediaGroupMessage,
 ): string | undefined {
   if (!message.media_group_id) return undefined;
   return `${message.chat.id}:${message.media_group_id}`;
 }
 
 export function removePendingTelegramMediaGroupMessages<
-  TMessage extends TelegramMediaGroupMessageLike,
+  TMessage extends TelegramMediaGroupMessage,
 >(
   groups: Map<string, TelegramMediaGroupState<TMessage>>,
   messageIds: number[],
@@ -167,7 +218,7 @@ export function removePendingTelegramMediaGroupMessages<
 }
 
 export function queueTelegramMediaGroupMessage<
-  TMessage extends TelegramMediaGroupMessageLike,
+  TMessage extends TelegramMediaGroupMessage,
 >(options: {
   message: TMessage;
   groups: Map<string, TelegramMediaGroupState<TMessage>>;
@@ -191,22 +242,114 @@ export function queueTelegramMediaGroupMessage<
   return true;
 }
 
+export function createTelegramMediaGroupController<
+  TMessage extends TelegramMediaGroupMessage,
+>(
+  options: TelegramMediaGroupControllerOptions = {},
+): TelegramMediaGroupController<TMessage> {
+  const groups = new Map<string, TelegramMediaGroupState<TMessage>>();
+  const debounceMs = options.debounceMs ?? TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS;
+  const setTimer =
+    options.setTimer ??
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
+      setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? clearTimeout;
+  return {
+    queueMessage: ({ message, dispatchMessages }) =>
+      queueTelegramMediaGroupMessage({
+        message,
+        groups,
+        debounceMs,
+        setTimer,
+        clearTimer,
+        dispatchMessages,
+      }),
+    removeMessages: (messageIds) =>
+      removePendingTelegramMediaGroupMessages(groups, messageIds, clearTimer),
+    clear: () => {
+      for (const state of groups.values()) {
+        if (state.flushTimer) clearTimer(state.flushTimer);
+      }
+      groups.clear();
+    },
+  };
+}
+
+export function createTelegramMediaGroupDispatchRuntime<
+  TMessage extends TelegramMediaGroupMessage,
+  TContext,
+>(
+  deps: TelegramMediaGroupDispatchRuntimeDeps<TMessage, TContext>,
+): TelegramMediaGroupDispatchRuntime<TMessage, TContext> {
+  return {
+    handleMessage: async (message, ctx) => {
+      const queuedMediaGroup = deps.mediaGroups.queueMessage({
+        message,
+        dispatchMessages: (messages) => {
+          void deps.dispatchMessages(messages, ctx);
+        },
+      });
+      if (queuedMediaGroup) return;
+      await deps.dispatchMessages([message], ctx);
+    },
+  };
+}
+
+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<DownloadedTelegramFile, "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 formatTelegramHistoryText(
   rawText: string,
-  files: DownloadedTelegramFileLike[],
+  files: DownloadedTelegramFile[],
+  handlerOutputs: string[] = [],
 ): string {
   let summary = rawText.length > 0 ? rawText : "(no text)";
-  if (files.length > 0) {
-    summary += `\nAttachments:`;
-    for (const file of files) {
-      summary += `\n- ${file.path}`;
-    }
-  }
+  summary = appendTelegramAttachmentSection(summary, files);
+  summary = appendTelegramListSection(summary, "outputs", handlerOutputs);
   return summary;
 }
 
+export async function downloadTelegramMessageFiles(
+  messages: TelegramMediaMessage[],
+  deps: DownloadTelegramMessageFilesDeps,
+): Promise<DownloadedTelegramMessageFile[]> {
+  const downloaded: DownloadedTelegramMessageFile[] = [];
+  for (const file of collectTelegramFileInfos(messages)) {
+    downloaded.push({
+      path: await deps.downloadFile(file.file_id, file.fileName),
+      fileName: file.fileName,
+      isImage: file.isImage,
+      mimeType: file.mimeType,
+      kind: file.kind,
+    });
+  }
+  return downloaded;
+}
+
 export function collectTelegramFileInfos(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): TelegramFileInfo[] {
   const files: TelegramFileInfo[] = [];
   for (const message of messages) {
@@ -219,6 +362,7 @@ export function collectTelegramFileInfos(
           file_id: photo.file_id,
           fileName: `photo-${message.message_id}.jpg`,
           mimeType: "image/jpeg",
+          kind: "photo",
           isImage: true,
         });
       }
@@ -234,6 +378,7 @@ export function collectTelegramFileInfos(
         file_id: message.document.file_id,
         fileName,
         mimeType: message.document.mime_type,
+        kind: "document",
         isImage: isImageMimeType(message.document.mime_type),
       });
     }
@@ -248,6 +393,7 @@ export function collectTelegramFileInfos(
         file_id: message.video.file_id,
         fileName,
         mimeType: message.video.mime_type,
+        kind: "video",
         isImage: false,
       });
     }
@@ -262,6 +408,7 @@ export function collectTelegramFileInfos(
         file_id: message.audio.file_id,
         fileName,
         mimeType: message.audio.mime_type,
+        kind: "audio",
         isImage: false,
       });
     }
@@ -273,6 +420,7 @@ export function collectTelegramFileInfos(
           ".ogg",
         )}`,
         mimeType: message.voice.mime_type,
+        kind: "voice",
         isImage: false,
       });
     }
@@ -287,6 +435,7 @@ export function collectTelegramFileInfos(
         file_id: message.animation.file_id,
         fileName,
         mimeType: message.animation.mime_type,
+        kind: "animation",
         isImage: false,
       });
     }
@@ -295,6 +444,7 @@ export function collectTelegramFileInfos(
         file_id: message.sticker.file_id,
         fileName: `sticker-${message.message_id}.webp`,
         mimeType: "image/webp",
+        kind: "sticker",
         isImage: true,
       });
     }