@llblab/pi-telegram 0.17.4 → 0.18.0

package/lib/runtime-log.ts

@@ -0,0 +1,123 @@
+/**
+ * Telegram runtime JSONL diagnostics log
+ * Zones: telegram diagnostics, filesystem, session observability
+ * Owns session-local append-only runtime evidence for debugging without becoming routing state
+ */
+
+import { existsSync, mkdirSync, statSync, writeFileSync, appendFile } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export interface TelegramRuntimeJsonlEvent {
+  at: number;
+  category: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface TelegramRuntimeJsonlLogOptions {
+  path?: string;
+  maxBytes?: number;
+  getNowMs?: () => number;
+}
+
+export interface TelegramRuntimeJsonlLog {
+  path: string;
+  reset: (reason: string, scope?: Record<string, unknown>) => void;
+  resetIfScopeChanged: (
+    scopeKey: string,
+    reason: string,
+    scope?: Record<string, unknown>,
+  ) => void;
+  record: (event: TelegramRuntimeJsonlEvent) => void;
+}
+
+const DEFAULT_MAX_LOG_BYTES = 5 * 1024 * 1024;
+
+function getAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR
+    ? resolve(process.env.PI_CODING_AGENT_DIR)
+    : join(homedir(), ".pi", "agent");
+}
+
+export function getTelegramRuntimeLogPath(agentDir = getAgentDir()): string {
+  return join(agentDir, "tmp", "telegram", "logs.jsonl");
+}
+
+function safeJsonLine(value: unknown): string {
+  return JSON.stringify(value, (_key, item) => {
+    if (item instanceof Error) return item.message;
+    if (typeof item === "bigint") return item.toString();
+    if (typeof item === "function" || typeof item === "symbol") return undefined;
+    return item;
+  });
+}
+
+export function createTelegramRuntimeJsonlLog(
+  options: TelegramRuntimeJsonlLogOptions = {},
+): TelegramRuntimeJsonlLog {
+  const path = options.path ?? getTelegramRuntimeLogPath();
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_LOG_BYTES;
+  const getNowMs = options.getNowMs ?? Date.now;
+  let scopeKey: string | undefined;
+  let pending: Promise<void> = Promise.resolve();
+
+  const ensureParent = () => {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  };
+
+  const writeReset = (reason: string, scope?: Record<string, unknown>) => {
+    ensureParent();
+    writeFileSync(
+      path,
+      safeJsonLine({
+        at: getNowMs(),
+        kind: "reset",
+        reason,
+        scope,
+      }) + "\n",
+      { mode: 0o600 },
+    );
+  };
+
+  const appendLine = (line: string) => {
+    pending = pending
+      .catch(() => undefined)
+      .then(async () => {
+        ensureParent();
+        if (existsSync(path) && statSync(path).size > maxBytes) {
+          writeReset("max-bytes", { maxBytes });
+        }
+        await new Promise<void>((resolve, reject) => {
+          appendFile(path, line, { mode: 0o600 }, (error) => {
+            if (error) reject(error);
+            else resolve();
+          });
+        });
+      });
+  };
+
+  return {
+    path,
+    reset(reason, scope) {
+      scopeKey = scope ? safeJsonLine(scope) : undefined;
+      try {
+        writeReset(reason, scope);
+      } catch {
+        // Diagnostics must never break Telegram runtime behavior.
+      }
+    },
+    resetIfScopeChanged(nextScopeKey, reason, scope) {
+      if (scopeKey === nextScopeKey) return;
+      scopeKey = nextScopeKey;
+      try {
+        writeReset(reason, scope);
+      } catch {
+        // Diagnostics must never break Telegram runtime behavior.
+      }
+    },
+    record(event) {
+      appendLine(safeJsonLine({ kind: "event", ...event }) + "\n");
+    },
+  };
+}

package/lib/runtime.ts

@@ -4,7 +4,7 @@
  * Owns small session-local runtime primitives that are shared by orchestration but are not specific to queueing, rendering, polling, or Telegram transport
  */
 
-const TELEGRAM_TYPING_ACTION_INTERVAL_MS = 2500;
+const TELEGRAM_TYPING_ACTION_INTERVAL_MS = 1500;
 const TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS = 250;
 
 export interface TelegramRuntimeQueueCounters {
@@ -26,6 +26,8 @@ export interface TelegramBridgeRuntimeState
   abortHandler?: () => void;
   typingInterval?: ReturnType<typeof setInterval>;
   typingInFlight?: Promise<void>;
+  typingLoopDeps?: TelegramTypingLoopDeps;
+  typingLoopKey?: string;
 }
 
 export interface TelegramRuntimeQueuePort {
@@ -318,10 +320,29 @@ export function abortTelegramTurn(state: TelegramBridgeRuntimeState): boolean {
   return true;
 }
 
+export interface TelegramTypingLoopTarget {
+  chatId: number;
+  threadId?: number;
+}
+
+function getTelegramTypingLoopThreadParams(
+  target: TelegramTypingLoopTarget | undefined,
+): { message_thread_id?: number } | undefined {
+  const threadId = target?.threadId;
+  return Number.isInteger(threadId)
+    ? { message_thread_id: threadId }
+    : undefined;
+}
+
 export interface TelegramTypingLoopDeps {
   chatId: number | undefined;
+  target?: TelegramTypingLoopTarget;
   intervalMs: number;
-  sendTypingAction: (chatId: number) => Promise<unknown>;
+  sendTypingAction: (
+    chatId: number,
+    options?: { message_thread_id?: number },
+  ) => Promise<unknown>;
+  sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
 }
 
 export interface TelegramRuntimeEventRecorderPort {
@@ -356,21 +377,34 @@ export interface TelegramTypingLoopStarterDeps<
 > extends TelegramRuntimeEventRecorderPort {
   typing: TelegramRuntimeTypingPort;
   getDefaultChatId: () => number | undefined;
-  sendTypingAction: (chatId: number) => Promise<unknown>;
+  sendTypingAction: (
+    chatId: number,
+    options?: { message_thread_id?: number },
+  ) => Promise<unknown>;
+  sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   intervalMs?: number;
 }
 
 export function createTelegramTypingLoopStarter<TContext>(
   deps: TelegramTypingLoopStarterDeps<TContext>,
-): (ctx: TContext, chatId?: number) => void {
-  return (ctx, chatId) => {
+): (
+  ctx: TContext,
+  chatId?: number,
+  options?: { target?: TelegramTypingLoopTarget },
+) => void {
+  return (ctx, chatId, options) => {
     deps.typing.start({
       chatId: chatId ?? deps.getDefaultChatId(),
+      target: options?.target,
       intervalMs: deps.intervalMs ?? TELEGRAM_TYPING_ACTION_INTERVAL_MS,
       sendTypingAction: async (targetChatId) => {
         try {
-          await deps.sendTypingAction(targetChatId);
+          const threadParams = getTelegramTypingLoopThreadParams(options?.target);
+          await deps.sendTypingAction(targetChatId, threadParams);
+          if (threadParams?.message_thread_id !== undefined) {
+            await deps.sendAggregateTypingAction?.(targetChatId);
+          }
         } catch (error) {
           const message =
             error instanceof Error ? error.message : String(error);
@@ -389,14 +423,33 @@ export function createTelegramTypingLoopStarter<TContext>(
   };
 }
 
+function getTelegramTypingLoopKey(deps: TelegramTypingLoopDeps): string {
+  const threadId = deps.target?.threadId;
+  return `${deps.chatId ?? 0}:${Number.isInteger(threadId) ? threadId : "all"}`;
+}
+
 export function startTelegramTypingLoop(
   state: TelegramBridgeRuntimeState,
   deps: TelegramTypingLoopDeps,
 ): boolean {
-  if (state.typingInterval || deps.chatId === undefined || deps.chatId === 0)
-    return false;
+  if (deps.chatId === undefined || deps.chatId === 0) return false;
+  const previousKey = state.typingLoopKey;
+  const nextKey = getTelegramTypingLoopKey(deps);
+  state.typingLoopDeps = deps;
+  state.typingLoopKey = nextKey;
   const sendTyping = (): void => {
-    const typing = Promise.resolve(deps.sendTypingAction(deps.chatId as number))
+    const activeDeps = state.typingLoopDeps;
+    if (!activeDeps || activeDeps.chatId === undefined || activeDeps.chatId === 0)
+      return;
+    const targetChatId = activeDeps.chatId;
+    const threadParams = getTelegramTypingLoopThreadParams(activeDeps.target);
+    const typing = Promise.resolve()
+      .then(async () => {
+        await activeDeps.sendTypingAction(targetChatId, threadParams);
+        if (threadParams?.message_thread_id !== undefined) {
+          await activeDeps.sendAggregateTypingAction?.(targetChatId);
+        }
+      })
       .then(() => undefined)
       .catch(() => undefined);
     state.typingInFlight = typing;
@@ -404,6 +457,11 @@ export function startTelegramTypingLoop(
       if (state.typingInFlight === typing) state.typingInFlight = undefined;
     });
   };
+  if (state.typingInterval) {
+    if (previousKey === nextKey) return false;
+    sendTyping();
+    return true;
+  }
   sendTyping();
   state.typingInterval = setInterval(sendTyping, deps.intervalMs);
   state.typingInterval.unref?.();
@@ -416,6 +474,8 @@ export function stopTelegramTypingLoop(
   if (!state.typingInterval) return false;
   clearInterval(state.typingInterval);
   state.typingInterval = undefined;
+  state.typingLoopDeps = undefined;
+  state.typingLoopKey = undefined;
   return true;
 }
 
@@ -478,7 +538,11 @@ export interface TelegramPromptDispatchLifecycleDeps<
     "setDispatchPending" | "clearDispatchPending"
   >;
   typing: Pick<TelegramRuntimeTypingPort, "stop">;
-  startTypingLoop: (ctx: TContext, chatId?: number) => void;
+  startTypingLoop: (
+    ctx: TContext,
+    chatId?: number,
+    options?: { target?: TelegramTypingLoopTarget },
+  ) => void;
   updateStatus: (ctx: TContext, error?: string) => void;
 }
 
@@ -488,13 +552,21 @@ export interface TelegramPromptDispatchRuntimeDeps<
   lifecycle: TelegramPromptDispatchLifecycleDeps<TContext>["lifecycle"];
   typing: TelegramRuntimeTypingPort;
   getDefaultChatId: () => number | undefined;
-  sendTypingAction: (chatId: number) => Promise<unknown>;
+  sendTypingAction: (
+    chatId: number,
+    options?: { message_thread_id?: number },
+  ) => Promise<unknown>;
+  sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   intervalMs?: number;
 }
 
 export interface TelegramPromptDispatchRuntime<TContext> {
-  startTypingLoop: (ctx: TContext, chatId?: number) => void;
+  startTypingLoop: (
+    ctx: TContext,
+    chatId?: number,
+    options?: { target?: TelegramTypingLoopTarget },
+  ) => void;
   onPromptDispatchStart: (ctx: TContext, chatId?: number) => void;
   onPromptDispatchFailure: (ctx: TContext, message: string) => void;
 }

package/lib/sections.ts

@@ -136,9 +136,16 @@ export interface TelegramSectionSettingsRow {
 
 // --- Runtime Port Builders ---
 
+/** @internal */
+export interface TelegramSectionTarget {
+  chatId: number;
+  threadId?: number;
+}
+
 /** @internal */
 export interface TelegramSectionRuntimeDeps {
   answerCallbackQuery: (id: string, text?: string) => Promise<void>;
+  target?: TelegramSectionTarget;
   editInteractiveMessage: (
     chatId: number,
     messageId: number,
@@ -151,6 +158,7 @@ export interface TelegramSectionRuntimeDeps {
     text: string,
     mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramInlineKeyboardMarkup,
+    options?: { target?: TelegramSectionTarget },
   ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;
   deleteMessage: (chatId: number, messageId: number) => Promise<void>;
@@ -191,6 +199,7 @@ function buildTelegramSectionContext(
           view.text,
           view.parseMode ?? "html",
           view.replyMarkup ?? { inline_keyboard: [] },
+          deps.target ? { target: deps.target } : undefined,
         )
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
@@ -239,6 +248,7 @@ function buildTelegramSectionCallbackContext(
           view.text,
           view.parseMode ?? "html",
           view.replyMarkup ?? { inline_keyboard: [] },
+          deps.target ? { target: deps.target } : undefined,
         )
         .then(() => {}),
     enqueuePrompt: deps.enqueuePrompt,
@@ -299,11 +309,6 @@ export function getTelegramSectionDiagnostics(): TelegramSectionDiagnostic[] {
 
 // --- Registry ---
 
-const MAIN_MENU_ROW = {
-  text: "⬆️ Main menu",
-  callback_data: "menu:back",
-} as const;
-
 const BACK_NAV_ROW = {
   text: "⬆️ Back",
 } as const;
@@ -353,7 +358,7 @@ export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistr
   >();
   let nextToken = 0;
 
-  function register(section: TelegramSectionRegistration): () => void {
+  const register = (section: TelegramSectionRegistration): () => void => {
     const duplicate = [...sections.values()].find((s) => s.id === section.id);
     if (duplicate) {
       throw new Error(`Telegram section id already registered: ${section.id}`);
@@ -371,22 +376,22 @@ export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistr
       sections.delete(token);
       errors.delete(token);
     };
-  }
+  };
 
-  function getSections(): RegisteredTelegramSection[] {
+  const getSections = (): RegisteredTelegramSection[] => {
     return [...sections.values()].sort((a, b) => {
       if (a.order !== b.order) return a.order - b.order;
       return a.id.localeCompare(b.id);
     });
-  }
+  };
 
-  function getByToken(
+  const getByToken = (
     token: TelegramSectionToken,
-  ): RegisteredTelegramSection | undefined {
+  ): RegisteredTelegramSection | undefined => {
     return sections.get(token);
-  }
+  };
 
-  function getDiagnostics(): TelegramSectionDiagnostic[] {
+  const getDiagnostics = (): TelegramSectionDiagnostic[] => {
     return getSections().map((s) => ({
       id: s.id,
       token: s.token,
@@ -394,26 +399,26 @@ export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistr
       status: errors.has(s.token) ? "error" : "active",
       lastError: errors.get(s.token)?.message,
     }));
-  }
+  };
 
-  function recordError(
+  const recordError = (
     token: TelegramSectionToken,
     message: string,
     source = "runtime",
-  ): void {
+  ): void => {
     if (sections.has(token)) errors.set(token, { message, source });
-  }
+  };
 
-  function clearError(token: TelegramSectionToken, source?: string): void {
+  const clearError = (token: TelegramSectionToken, source?: string): void => {
     const current = errors.get(token);
     if (!source || !current || current.source === source) errors.delete(token);
-  }
+  };
 
-  function clear(): void {
+  const clear = (): void => {
     sections.clear();
     errors.clear();
     nextToken = 0;
-  }
+  };
 
   return {
     register,
@@ -506,6 +511,7 @@ export function parseTelegramSectionCallback(
 /** @internal */
 export interface TelegramSectionCallbackHandlerDeps {
   answerCallbackQuery: (id: string, text?: string) => Promise<void>;
+  target?: TelegramSectionTarget;
   editInteractiveMessage: (
     chatId: number,
     messageId: number,
@@ -518,6 +524,7 @@ export interface TelegramSectionCallbackHandlerDeps {
     text: string,
     mode: "markdown" | "html" | "plain",
     replyMarkup: TelegramInlineKeyboardMarkup,
+    options?: { target?: TelegramSectionTarget },
   ) => Promise<number | undefined>;
   enqueuePrompt: (prompt: string) => Promise<void>;
   deleteMessage: (chatId: number, messageId: number) => Promise<void>;

package/lib/setup.ts

@@ -162,7 +162,7 @@ export async function runTelegramSetup(
 export function createTelegramSetupPromptRuntime<
   TContext extends TelegramSetupPromptContext,
 >(deps: TelegramSetupPromptRuntimeDeps<TContext>) {
-  return async function promptForConfig(ctx: TContext): Promise<void> {
+  return async (ctx: TContext): Promise<void> => {
     if (!ctx.hasUI || !deps.setupGuard.start()) return;
     try {
       const nextConfig = await runTelegramSetup({