@llblab/pi-telegram 0.3.0 → 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,6 +3,8 @@
  * Normalizes inbound Telegram messages into reusable file, text, id, history, and media-group metadata
  */
 
+import { basename, dirname } from "node:path";
+
 const TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS = 1200;
 
 export interface TelegramPhotoSize {
@@ -89,10 +91,20 @@ export interface TelegramMediaGroupControllerOptions {
   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;
 }
 
@@ -101,6 +113,7 @@ export interface DownloadedTelegramFile {
   fileName?: string;
   isImage?: boolean;
   mimeType?: string;
+  kind?: TelegramAttachmentKind;
 }
 
 export interface DownloadedTelegramMessageFile {
@@ -108,6 +121,7 @@ export interface DownloadedTelegramMessageFile {
   fileName: string;
   isImage: boolean;
   mimeType?: string;
+  kind?: TelegramAttachmentKind;
 }
 
 export interface DownloadTelegramMessageFilesDeps {
@@ -281,17 +295,39 @@ export function createTelegramMediaGroupDispatchRuntime<
   };
 }
 
+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: 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;
 }
 
@@ -306,6 +342,7 @@ export async function downloadTelegramMessageFiles(
       fileName: file.fileName,
       isImage: file.isImage,
       mimeType: file.mimeType,
+      kind: file.kind,
     });
   }
   return downloaded;
@@ -325,6 +362,7 @@ export function collectTelegramFileInfos(
           file_id: photo.file_id,
           fileName: `photo-${message.message_id}.jpg`,
           mimeType: "image/jpeg",
+          kind: "photo",
           isImage: true,
         });
       }
@@ -340,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),
       });
     }
@@ -354,6 +393,7 @@ export function collectTelegramFileInfos(
         file_id: message.video.file_id,
         fileName,
         mimeType: message.video.mime_type,
+        kind: "video",
         isImage: false,
       });
     }
@@ -368,6 +408,7 @@ export function collectTelegramFileInfos(
         file_id: message.audio.file_id,
         fileName,
         mimeType: message.audio.mime_type,
+        kind: "audio",
         isImage: false,
       });
     }
@@ -379,6 +420,7 @@ export function collectTelegramFileInfos(
           ".ogg",
         )}`,
         mimeType: message.voice.mime_type,
+        kind: "voice",
         isImage: false,
       });
     }
@@ -393,6 +435,7 @@ export function collectTelegramFileInfos(
         file_id: message.animation.file_id,
         fileName,
         mimeType: message.animation.mime_type,
+        kind: "animation",
         isImage: false,
       });
     }
@@ -401,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,
       });
     }

package/lib/pi.ts

@@ -33,6 +33,7 @@ export interface PiSettingsManager {
 
 export interface PiExtensionApiRuntimePorts {
   sendUserMessage: ExtensionAPI["sendUserMessage"];
+  exec: ExtensionAPI["exec"];
   getThinkingLevel: ExtensionAPI["getThinkingLevel"];
   setThinkingLevel: ExtensionAPI["setThinkingLevel"];
   setModel: ExtensionAPI["setModel"];
@@ -41,11 +42,16 @@ export interface PiExtensionApiRuntimePorts {
 export function createExtensionApiRuntimePorts(
   api: Pick<
     ExtensionAPI,
-    "sendUserMessage" | "getThinkingLevel" | "setThinkingLevel" | "setModel"
+    | "sendUserMessage"
+    | "exec"
+    | "getThinkingLevel"
+    | "setThinkingLevel"
+    | "setModel"
   >,
 ): PiExtensionApiRuntimePorts {
   return {
     sendUserMessage: (content) => api.sendUserMessage(content),
+    exec: (command, args, options) => api.exec(command, args, options),
     getThinkingLevel: () => api.getThinkingLevel(),
     setThinkingLevel: (level) => api.setThinkingLevel(level),
     setModel: (model) => api.setModel(model),
@@ -62,6 +68,10 @@ export function getExtensionContextModel(
   return ctx.model;
 }
 
+export function getExtensionContextCwd(ctx: ExtensionContext): string {
+  return ctx.cwd;
+}
+
 export function isExtensionContextIdle(ctx: ExtensionContext): boolean {
   return ctx.isIdle();
 }

package/lib/queue.ts

@@ -1100,6 +1100,7 @@ export interface TelegramPromptEnqueueControllerDeps<
   createTurn: (
     messages: TMessage[],
     historyTurns: PendingTelegramTurn[],
+    ctx: TContext,
   ) => Promise<PendingTelegramTurn>;
   updateStatus: (ctx: TContext) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
@@ -1365,6 +1366,8 @@ export function createTelegramPromptEnqueueController<
     enqueue: (messages, ctx) =>
       enqueueTelegramPromptTurnRuntime(messages, {
         ...deps,
+        createTurn: (nextMessages, historyTurns) =>
+          deps.createTurn(nextMessages, historyTurns, ctx),
         updateStatus: () => deps.updateStatus(ctx),
         dispatchNextQueuedTelegramTurn: () =>
           deps.dispatchNextQueuedTelegramTurn(ctx),

package/lib/registration.ts

@@ -28,7 +28,7 @@ const SYSTEM_PROMPT_SUFFIX = `
 
 Telegram bridge extension is active.
 - Messages forwarded from Telegram are prefixed with "[telegram]".
-- [telegram] messages may include local temp file paths for Telegram attachments. Read those files as needed.
+- [telegram] messages may include [attachments] sections with a base directory plus relative local file entries. Resolve and read those files as needed.
 - Telegram is often read on narrow phone screens, so prefer narrow table columns when presenting tabular data; wide monospace tables can become unreadable.
 - If a [telegram] user asked for a file or generated artifact, use the telegram_attach tool with the local file path so the extension can send it with your next final reply.
 - Do not assume mentioning a local file path in plain text will send it to Telegram. Use telegram_attach.`;
@@ -96,16 +96,49 @@ export function registerTelegramAttachmentTool(
 
 // --- Command Registration ---
 
+export interface TelegramCommandStartPollingOptions {
+  force?: boolean;
+}
+
+export interface TelegramCommandStartPollingResult {
+  ok: boolean;
+  message?: string;
+  canTakeover?: boolean;
+  owner?: string;
+}
+
 export interface TelegramCommandRegistrationDeps {
   promptForConfig: (ctx: ExtensionCommandContext) => Promise<void>;
   getStatusLines: () => string[];
   reloadConfig: () => Promise<void>;
   hasBotToken: () => boolean;
-  startPolling: (ctx: ExtensionCommandContext) => void | Promise<void>;
-  stopPolling: () => Promise<void>;
+  startPolling: (
+    ctx: ExtensionCommandContext,
+    options?: TelegramCommandStartPollingOptions,
+  ) =>
+    | void
+    | Promise<void | TelegramCommandStartPollingResult>
+    | TelegramCommandStartPollingResult;
+  stopPolling: () => Promise<void | string>;
   updateStatus: (ctx: ExtensionCommandContext) => void;
 }
 
+function formatTelegramTakeoverTitle(ctx: ExtensionCommandContext): string {
+  return ctx.ui.theme.fg("accent", "pi-telegram");
+}
+
+function formatTelegramTakeoverPrompt(
+  ctx: ExtensionCommandContext,
+  owner?: string,
+): string {
+  const theme = ctx.ui.theme;
+  const action = theme.fg("warning", "move singleton lock here?");
+  const from = theme.fg("muted", "from:");
+  const to = theme.fg("muted", "to:");
+  const source = owner ?? "another pi instance";
+  return `${action}\n\n${from} ${source}\n${to} ${ctx.cwd}`;
+}
+
 export function registerTelegramCommands(
   pi: ExtensionAPI,
   deps: TelegramCommandRegistrationDeps,
@@ -130,14 +163,30 @@ export function registerTelegramCommands(
         await deps.promptForConfig(ctx);
         return;
       }
-      await deps.startPolling(ctx);
+      let result = await deps.startPolling(ctx);
+      if (result && !result.ok && result.canTakeover) {
+        const confirmed = await ctx.ui.confirm(
+          formatTelegramTakeoverTitle(ctx),
+          formatTelegramTakeoverPrompt(ctx, result.owner),
+        );
+        if (!confirmed) {
+          ctx.ui.notify("Telegram bridge takeover cancelled.", "info");
+          deps.updateStatus(ctx);
+          return;
+        }
+        result = await deps.startPolling(ctx, { force: true });
+      }
+      if (result?.message) {
+        ctx.ui.notify(result.message, result.ok ? "info" : "warning");
+      }
       deps.updateStatus(ctx);
     },
   });
   pi.registerCommand("telegram-disconnect", {
     description: "Stop the Telegram bridge in this pi session",
     handler: async (_args, ctx) => {
-      await deps.stopPolling();
+      const message = await deps.stopPolling();
+      if (message) ctx.ui.notify(message, "info");
       deps.updateStatus(ctx);
     },
   });
@@ -225,6 +274,41 @@ export interface TelegramLifecycleRegistrationDeps {
   onAgentEnd: (event: AgentEndEvent, ctx: ExtensionContext) => Promise<void>;
 }
 
+export interface TelegramSessionLifecycleHooks {
+  onSessionStart: (event: SessionStartEvent, ctx: ExtensionContext) => Promise<void>;
+  onSessionShutdown: (
+    event: SessionShutdownEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+}
+
+export interface TelegramExtraLifecycleHooks {
+  onSessionStart?: (
+    event: SessionStartEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+  onSessionShutdown?: (
+    event: SessionShutdownEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+}
+
+export function appendTelegramLifecycleHooks(
+  base: TelegramSessionLifecycleHooks,
+  extra: TelegramExtraLifecycleHooks,
+): TelegramSessionLifecycleHooks {
+  return {
+    onSessionStart: async (event, ctx) => {
+      await base.onSessionStart(event, ctx);
+      await extra.onSessionStart?.(event, ctx);
+    },
+    onSessionShutdown: async (event, ctx) => {
+      await base.onSessionShutdown(event, ctx);
+      await extra.onSessionShutdown?.(event, ctx);
+    },
+  };
+}
+
 export function registerTelegramLifecycleHooks(
   pi: ExtensionAPI,
   deps: TelegramLifecycleRegistrationDeps,