@llblab/pi-telegram 0.4.0 → 0.5.1

package/lib/locks.ts

@@ -3,7 +3,14 @@
  * Owns shared locks.json access and Telegram bridge ownership semantics
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
@@ -68,7 +75,9 @@ export type TelegramLockedPollingStartResult =
   | { ok: true; message: string; canTakeover?: false }
   | { ok: false; message: string; canTakeover?: boolean; owner?: string };
 
-export interface TelegramLockedPollingRuntime<TContext extends TelegramLockContext> {
+export interface TelegramLockedPollingRuntime<
+  TContext extends TelegramLockContext,
+> {
   start: (
     ctx: TContext,
     options?: TelegramLockedPollingStartOptions,
@@ -78,13 +87,19 @@ export interface TelegramLockedPollingRuntime<TContext extends TelegramLockConte
   onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
 }
 
-export interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext> {
+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;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
   ownershipCheckMs?: number;
 }
 
@@ -116,8 +131,11 @@ export function writeLocks(path: string, locks: Record<string, unknown>): void {
   }
 }
 
-export function parseTelegramLockEntry(value: unknown): TelegramLockEntry | undefined {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+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 {
@@ -140,7 +158,11 @@ 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 {
+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 };
@@ -205,12 +227,15 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
       return state;
     },
     getState: () => getLockState(readLock(), pid, isAlive),
-    getStatusLabel: () => formatLockState(getLockState(readLock(), pid, isAlive)),
+    getStatusLabel: () =>
+      formatLockState(getLockState(readLock(), pid, isAlive)),
     owns: (ctx) => ownsLockContext(readLock(), pid, ctx),
   };
 }
 
-export function createTelegramLockedPollingRuntime<TContext extends TelegramLockContext>(
+export function createTelegramLockedPollingRuntime<
+  TContext extends TelegramLockContext,
+>(
   deps: TelegramLockedPollingRuntimeDeps<TContext>,
 ): TelegramLockedPollingRuntime<TContext> {
   let ownershipInterval: ReturnType<typeof setInterval> | undefined;
@@ -239,8 +264,11 @@ export function createTelegramLockedPollingRuntime<TContext extends TelegramLock
   const stopAfterOwnershipLoss = (ctx: TContext) => {
     if (ownershipStop) return;
     stopOwnershipWatcher();
-    ownershipStop = deps.stopPolling()
-      .catch((error) => deps.recordRuntimeEvent?.("lock", error, { phase: "ownership-loss" }))
+    ownershipStop = deps
+      .stopPolling()
+      .catch((error) =>
+        deps.recordRuntimeEvent?.("lock", error, { phase: "ownership-loss" }),
+      )
       .finally(() => {
         ownershipStop = undefined;
         updateStatusSafely(ctx, "ownership-loss-status");
@@ -257,7 +285,8 @@ export function createTelegramLockedPollingRuntime<TContext extends TelegramLock
   };
   return {
     start: async (ctx, options = {}) => {
-      if (!deps.hasBotToken()) return { ok: false, message: "Telegram bot is not configured." };
+      if (!deps.hasBotToken())
+        return { ok: false, message: "Telegram bot is not configured." };
       const acquired = deps.lock.acquire(ctx, options);
       if (!acquired.ok) {
         return {
@@ -279,7 +308,8 @@ export function createTelegramLockedPollingRuntime<TContext extends TelegramLock
       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)}).`;
+      if (state.kind === "stale")
+        return `Removed stale Telegram bridge lock (${formatLock(state.lock)}).`;
       return "Telegram bridge disconnected.";
     },
     suspend: suspendPolling,

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/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,
@@ -1060,6 +1061,7 @@ export interface TelegramQueueMutationControllerDeps<
 export interface TelegramQueueMutationController<TContext> {
   append: (item: TelegramQueueItem<TContext>, ctx: TContext) => void;
   reorder: (ctx: TContext) => void;
+  clear: (ctx: TContext) => number;
   removeByMessageIds: (messageIds: number[], ctx: TContext) => number;
   clearPriorityByMessageId: (messageId: number, ctx: TContext) => boolean;
   prioritizeByMessageId: (messageId: number, ctx: TContext) => boolean;
@@ -1261,6 +1263,7 @@ export function createTelegramQueueMutationController<TContext>(
     append: (item, ctx) =>
       appendTelegramQueueItemRuntime(item, buildRuntimeDeps(ctx)),
     reorder: (ctx) => reorderTelegramQueueItemsRuntime(buildRuntimeDeps(ctx)),
+    clear: (ctx) => clearTelegramQueueItemsRuntime(buildRuntimeDeps(ctx)),
     removeByMessageIds: (messageIds, ctx) =>
       removeTelegramQueueItemsByMessageIdsRuntime(
         messageIds,
@@ -1290,6 +1293,16 @@ export function reorderTelegramQueueItemsRuntime<TContext>(
   deps.updateStatus(deps.ctx);
 }
 
+export function clearTelegramQueueItemsRuntime<TContext>(
+  deps: TelegramQueueMutationRuntimeDeps<TContext>,
+): number {
+  const removedCount = deps.getQueuedItems().length;
+  if (removedCount === 0) return 0;
+  deps.setQueuedItems([]);
+  deps.updateStatus(deps.ctx);
+  return removedCount;
+}
+
 export function removeTelegramQueueItemsByMessageIdsRuntime<TContext>(
   messageIds: number[],
   deps: TelegramQueueMutationRuntimeDeps<TContext>,
@@ -1400,8 +1413,9 @@ export interface TelegramRuntimeEventRecorderPort {
   ) => void;
 }
 
-export interface TelegramControlRuntimeDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramControlRuntimeDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   ctx: TContext;
   sendTextReply: (
     chatId: number,
@@ -1454,8 +1468,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;

package/lib/routing.ts

@@ -116,7 +116,8 @@ export function createTelegramInboundRouteRuntime<
     isIdle: deps.isIdle,
     hasActiveTelegramTurn: deps.activeTurnRuntime.has,
     hasAbortHandler: deps.bridgeRuntime.abort.hasHandler,
-    getActiveToolExecutions: deps.bridgeRuntime.lifecycle.getActiveToolExecutions,
+    getActiveToolExecutions:
+      deps.bridgeRuntime.lifecycle.getActiveToolExecutions,
     setModel: deps.setModel,
     setCurrentModel: deps.currentModelRuntime.setCurrentModel,
     stagePendingModelSwitch: deps.modelSwitchController.stagePendingSwitch,
@@ -130,6 +131,7 @@ export function createTelegramInboundRouteRuntime<
     hasAbortHandler: deps.bridgeRuntime.abort.hasHandler,
     clearPendingModelSwitch: deps.modelSwitchController.clearPendingSwitch,
     hasQueuedTelegramItems: deps.telegramQueueStore.hasQueuedItems,
+    clearQueuedTelegramItems: deps.queueMutationRuntime.clear,
     setPreserveQueuedTurnsAsHistory:
       deps.bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
     abortCurrentTurn: deps.bridgeRuntime.abort.abortTurn,
@@ -138,7 +140,8 @@ export function createTelegramInboundRouteRuntime<
     hasActiveTelegramTurn: deps.activeTurnRuntime.has,
     hasDispatchPending: deps.bridgeRuntime.lifecycle.hasDispatchPending,
     isCompactionInProgress: deps.bridgeRuntime.lifecycle.isCompactionInProgress,
-    setCompactionInProgress: deps.bridgeRuntime.lifecycle.setCompactionInProgress,
+    setCompactionInProgress:
+      deps.bridgeRuntime.lifecycle.setCompactionInProgress,
     updateStatus: deps.updateStatus,
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
     compact: deps.compact,

package/lib/runtime.ts

@@ -327,8 +327,9 @@ export interface TelegramRuntimeEventRecorderPort {
   ) => void;
 }
 
-export interface TelegramTypingLoopStarterDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramTypingLoopStarterDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   typing: TelegramRuntimeTypingPort;
   getDefaultChatId: () => number | undefined;
   sendTypingAction: (chatId: number) => Promise<unknown>;
@@ -413,8 +414,9 @@ export function createTelegramAgentEndResetter(
   };
 }
 
-export interface TelegramPromptDispatchLifecycleDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramPromptDispatchLifecycleDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   lifecycle: Pick<
     TelegramRuntimeLifecyclePort,
     "setDispatchPending" | "clearDispatchPending"
@@ -424,8 +426,9 @@ export interface TelegramPromptDispatchLifecycleDeps<TContext>
   updateStatus: (ctx: TContext, error?: string) => void;
 }
 
-export interface TelegramPromptDispatchRuntimeDeps<TContext>
-  extends TelegramRuntimeEventRecorderPort {
+export interface TelegramPromptDispatchRuntimeDeps<
+  TContext,
+> extends TelegramRuntimeEventRecorderPort {
   lifecycle: TelegramPromptDispatchLifecycleDeps<TContext>["lifecycle"];
   typing: TelegramRuntimeTypingPort;
   getDefaultChatId: () => number | undefined;

package/lib/setup.ts

@@ -86,7 +86,11 @@ const TELEGRAM_BOT_TOKEN_ENV_VARS = [
 function isTelegramPollingStartResult(
   value: unknown,
 ): value is TelegramPollingStartResult {
-  return !!value && typeof value === "object" && typeof (value as { ok?: unknown }).ok === "boolean";
+  return (
+    !!value &&
+    typeof value === "object" &&
+    typeof (value as { ok?: unknown }).ok === "boolean"
+  );
 }
 
 export function getTelegramBotTokenInputDefault(

package/lib/status.ts

@@ -108,6 +108,7 @@ export interface TelegramStatusBarState {
   paired: boolean;
   compactionInProgress: boolean;
   processing: boolean;
+  processingStatus?: string;
   queuedStatus: string;
   error?: string;
 }
@@ -333,6 +334,10 @@ export function createTelegramBridgeStatusRuntime<
     getStatusBarState: (_ctx, error) => {
       const config = deps.getConfig();
       const queuedItems = deps.getQueuedItems();
+      const hasActiveTurn = deps.hasActiveTurn();
+      const hasPendingDispatch = deps.hasDispatchPending();
+      const hasPendingModelSwitch = deps.hasPendingModelSwitch();
+      const activeToolExecutions = deps.getActiveToolExecutions();
       const compactionInProgress = deps.isCompactionInProgress();
       return {
         hasBotToken: !!config.botToken,
@@ -340,9 +345,14 @@ export function createTelegramBridgeStatusRuntime<
         paired: !!config.allowedUserId,
         compactionInProgress,
         processing:
-          deps.hasActiveTurn() ||
-          deps.hasDispatchPending() ||
-          queuedItems.length > 0,
+          hasActiveTurn || hasPendingDispatch || queuedItems.length > 0,
+        processingStatus: getTelegramStatusBarProcessingStatus({
+          hasActiveTurn,
+          hasPendingDispatch,
+          hasPendingModelSwitch,
+          activeToolExecutions,
+          queuedItems: queuedItems.length,
+        }),
         queuedStatus: deps.formatQueuedStatus(queuedItems),
         error,
       };
@@ -367,6 +377,21 @@ export function createTelegramBridgeStatusRuntime<
   });
 }
 
+export function getTelegramStatusBarProcessingStatus(state: {
+  hasActiveTurn: boolean;
+  hasPendingDispatch: boolean;
+  hasPendingModelSwitch: boolean;
+  activeToolExecutions: number;
+  queuedItems: number;
+}): string | undefined {
+  if (state.hasPendingModelSwitch) return "model";
+  if (state.activeToolExecutions > 0) return "tool running";
+  if (state.hasActiveTurn) return "active";
+  if (state.hasPendingDispatch) return "dispatching";
+  if (state.queuedItems > 0) return "queued";
+  return undefined;
+}
+
 export function buildTelegramStatusBarText(
   theme: TelegramStatusBarTheme,
   state: TelegramStatusBarState,
@@ -386,7 +411,7 @@ export function buildTelegramStatusBarText(
     return `${label} ${theme.fg("accent", "compacting")}${queued}`;
   }
   if (state.processing) {
-    return `${label} ${theme.fg("accent", "processing")}${queued}`;
+    return `${label} ${theme.fg("accent", state.processingStatus ?? "processing")}${queued}`;
   }
   return `${label} ${theme.fg("success", "connected")}`;
 }

package/lib/turns.ts

@@ -57,9 +57,7 @@ export function formatTelegramTurnStatusSummary(
 ): string {
   const textSummary = truncateTelegramQueueSummary(rawText);
   if (textSummary) return textSummary;
-  const handlerSummary = truncateTelegramQueueSummary(
-    handlerOutputs.join(" "),
-  );
+  const handlerSummary = truncateTelegramQueueSummary(handlerOutputs.join(" "));
   if (handlerSummary) return handlerSummary;
   if (files.length === 1) {
     const fileName = basename(
@@ -121,7 +119,11 @@ export function buildTelegramTurnPrompt(options: {
   }
   const promptFiles = options.promptFiles ?? options.files;
   prompt = appendTelegramAttachmentSection(prompt, promptFiles);
-  prompt = appendTelegramListSection(prompt, "outputs", options.handlerOutputs ?? []);
+  prompt = appendTelegramListSection(
+    prompt,
+    "outputs",
+    options.handlerOutputs ?? [],
+  );
   return prompt;
 }
 
@@ -158,7 +160,9 @@ function splitTelegramPromptAttachmentSuffix(prompt: string): {
   const attachmentFiles = attachmentLines
     .map((line) => line.match(/^- (.+)$/)?.[1]?.trim())
     .filter((path): path is string => !!path)
-    .map((path) => (attachmentDir ? join(attachmentDir, path.replace(/^\/+/, "")) : path))
+    .map((path) =>
+      attachmentDir ? join(attachmentDir, path.replace(/^\/+/, "")) : path,
+    )
     .map((path) => ({
       path,
       fileName: basename(path),
@@ -301,8 +305,9 @@ export type BuildTelegramPromptTurnRuntimeOptions = Omit<
   "readBinaryFile"
 >;
 
-export interface TelegramPromptTurnRuntimeBuilderDeps<TContext = unknown>
-  extends DownloadTelegramMessageFilesDeps {
+export interface TelegramPromptTurnRuntimeBuilderDeps<
+  TContext = unknown,
+> extends DownloadTelegramMessageFilesDeps {
   allocateQueueOrder: () => number;
   processAttachments?: (
     files: DownloadedTelegramTurnFile[],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "private": false,
   "description": "Better Telegram DM bridge extension for pi",
   "type": "module",