@llblab/pi-telegram 0.3.0 → 0.5.0

package/lib/locks.ts

@@ -0,0 +1,336 @@
+/**
+ * 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/menu.ts

@@ -807,10 +807,6 @@ export function buildTelegramModelCallbackPlan<
 export async function openTelegramStatusMenu<
   TModel extends MenuModel = MenuModel,
 >(deps: TelegramStatusMenuOpenDeps<TModel>): Promise<void> {
-  if (!deps.isIdle()) {
-    await deps.sendBusyMessage();
-    return;
-  }
   const state = await deps.getModelMenuState();
   const messageId = await deps.sendStatusMenu(
     state,

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/prompts.ts

@@ -0,0 +1,44 @@
+/**
+ * Telegram prompt injection helpers
+ * Owns Telegram-specific system prompt suffixes injected into pi agent turns
+ */
+
+import type { BeforeAgentStartEvent } from "./pi.ts";
+import { TELEGRAM_PREFIX } from "./turns.ts";
+
+const SYSTEM_PROMPT_SUFFIX = `
+
+Telegram bridge extension is active.
+- Messages forwarded from Telegram are prefixed with "[telegram]".
+- [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 telegram_attach with the local path instead of only mentioning the path in text.
+- Do not assume mentioning a local file path in plain text will send it to Telegram. Use telegram_attach.`;
+
+export function buildTelegramBridgeSystemPrompt(options: {
+  prompt: string;
+  systemPrompt: string;
+  telegramPrefix?: string;
+  systemPromptSuffix: string;
+}): { systemPrompt: string } {
+  const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
+  const suffix = options.prompt.trimStart().startsWith(telegramPrefix)
+    ? `${options.systemPromptSuffix}\n- The current user message came from Telegram.`
+    : options.systemPromptSuffix;
+  return { systemPrompt: options.systemPrompt + suffix };
+}
+
+export function createTelegramBeforeAgentStartHook(
+  options: {
+    telegramPrefix?: string;
+    systemPromptSuffix?: string;
+  } = {},
+): (event: BeforeAgentStartEvent) => { systemPrompt: string } {
+  return (event) =>
+    buildTelegramBridgeSystemPrompt({
+      prompt: event.prompt,
+      systemPrompt: event.systemPrompt,
+      telegramPrefix: options.telegramPrefix,
+      systemPromptSuffix: options.systemPromptSuffix ?? SYSTEM_PROMPT_SUFFIX,
+    });
+}

package/lib/queue.ts

@@ -856,8 +856,9 @@ export function createTelegramAgentEndHook<
       preserveQueuedTurnsAsHistory: deps.getPreserveQueuedTurnsAsHistory(),
       resetRuntimeState: deps.resetRuntimeState,
       updateStatus: () => deps.updateStatus(ctx),
-      dispatchNextQueuedTelegramTurn: () =>
-        deps.dispatchNextQueuedTelegramTurn(ctx),
+      dispatchNextQueuedTelegramTurn: () => {
+        setTimeout(() => deps.dispatchNextQueuedTelegramTurn(ctx), 0);
+      },
       clearPreview: deps.clearPreview,
       setPreviewPendingText: deps.setPreviewPendingText,
       finalizeMarkdownPreview: deps.finalizeMarkdownPreview,
@@ -1100,6 +1101,7 @@ export interface TelegramPromptEnqueueControllerDeps<
   createTurn: (
     messages: TMessage[],
     historyTurns: PendingTelegramTurn[],
+    ctx: TContext,
   ) => Promise<PendingTelegramTurn>;
   updateStatus: (ctx: TContext) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
@@ -1365,6 +1367,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),
@@ -1397,8 +1401,9 @@ export interface TelegramRuntimeEventRecorderPort {
   ) => void;
 }
 
-export interface TelegramControlRuntimeDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramControlRuntimeDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   ctx: TContext;
   sendTextReply: (
     chatId: number,
@@ -1451,8 +1456,9 @@ export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
   onIdle: () => void;
 }
 
-export interface TelegramQueueDispatchControllerDeps<TContext = unknown>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramQueueDispatchControllerDeps<
+  TContext = unknown,
+> extends TelegramRuntimeEventRecorderPort {
   getQueuedItems: () => TelegramQueueItem<TContext>[];
   setQueuedItems: (items: TelegramQueueItem<TContext>[]) => void;
   canDispatch: (ctx: TContext) => boolean;