@llblab/pi-telegram 0.23.3 → 0.24.1

package/lib/locks.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram singleton lock helpers
- * Zones: shared singleton, filesystem, telegram runtime ownership
- * Owns shared locks.json access and Telegram bridge ownership semantics
+ * Zones: telegram ownership, filesystem, transport authority
+ * Owns extension-local owners.json access and Telegram bridge ownership semantics
  */
 
 import {
@@ -19,10 +19,11 @@ import {
 } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, join } from "node:path";
-import { resolveTelegramLocksPath } from "./paths.ts";
+import { resolveTelegramOwnersPath } from "./paths.ts";
 
-export const TELEGRAM_LOCK_KEY = "@llblab/pi-telegram";
-export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 5_000;
+export const TELEGRAM_LOCK_KEY = "default";
+export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 8_000;
+const TELEGRAM_OWNERSHIP_REFRESH_MS = 2_000;
 const TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS = 5;
 const TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS = 25;
 const TELEGRAM_LOCK_TRANSACTION_ATTEMPTS = 80;
@@ -42,18 +43,17 @@ function allocateTelegramLockRuntimeGeneration(): number {
   return generation;
 }
 
-function getLocksPath(): string {
-  return resolveTelegramLocksPath();
+function getOwnersPath(): string {
+  return resolveTelegramOwnersPath();
 }
 
 /**
- * Resolve the scoped lock key for the active Telegram profile.
- * Default profile → @llblab/pi-telegram
- * Named profile → @llblab/pi-telegram:<name>
+ * Resolve the extension-local owner slot for the active Telegram profile.
+ * Default profile → default
+ * Named profile → the validated profile name
  */
 export function resolveTelegramLockKey(activeProfile?: string): string {
-  if (activeProfile) return `${TELEGRAM_LOCK_KEY}:${activeProfile}`;
-  return TELEGRAM_LOCK_KEY;
+  return activeProfile || TELEGRAM_LOCK_KEY;
 }
 
 export interface TelegramActiveProfileGetter {
@@ -139,7 +139,7 @@ export interface TelegramLockRuntimeOptions {
   staleHeartbeatMs?: number;
 }
 
-export function readLocks(path = getLocksPath()): Record<string, unknown> {
+export function readLocks(path = getOwnersPath()): Record<string, unknown> {
   if (!existsSync(path)) return {};
   try {
     const value = JSON.parse(readFileSync(path, "utf8"));
@@ -161,7 +161,7 @@ function readLocksForTransaction(path: string): Record<string, unknown> {
   }
   const value: unknown = JSON.parse(source);
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`Invalid Telegram lock registry: ${path}`);
+    throw new Error(`Invalid Telegram owner store: ${path}`);
   }
   return value as Record<string, unknown>;
 }
@@ -182,8 +182,7 @@ interface TelegramLockTransactionOwner {
   generation: string;
 }
 
-const TELEGRAM_TRANSACTION_OWNER_PATTERN =
-  /^owner\.([A-Za-z0-9-]+)\.json$/u;
+const TELEGRAM_TRANSACTION_OWNER_PATTERN = /^owner\.([A-Za-z0-9-]+)\.json$/u;
 
 function getLockTransactionOwnerFile(generation: string): string {
   return `owner.${generation}.json`;
@@ -351,6 +350,8 @@ type TelegramTransactionGlobal = typeof globalThis & {
 
 export interface TelegramFileTransactionOptions {
   recoveryRename?: typeof renameSync;
+  attempts?: number;
+  retryDelayMs?: number;
 }
 
 function getActiveTransactionReclaims(): Set<string> {
@@ -367,7 +368,13 @@ function reclaimAbandonedDirectoryGuard(
   } catch {
     return false;
   }
-  const entries = readdirSync(path);
+  let entries: string[];
+  try {
+    entries = readdirSync(path);
+  } catch {
+    // Another recovery candidate may remove the observed guard after lstat.
+    return false;
+  }
   if (entries.length !== 1) return false;
   const entry = entries[0];
   let observedPid: number;
@@ -383,10 +390,7 @@ function reclaimAbandonedDirectoryGuard(
     observedReclaimGeneration = match[2];
   }
   const activeReclaims = getActiveTransactionReclaims();
-  if (
-    observedPid === process.pid &&
-    observedReclaimGeneration !== undefined
-  ) {
+  if (observedPid === process.pid && observedReclaimGeneration !== undefined) {
     if (activeReclaims.has(observedReclaimGeneration)) return false;
   } else if (isProcessAlive(observedPid)) {
     return false;
@@ -565,10 +569,7 @@ function recoverAbandonedLockTransaction(
   }
 
   const recoveryGuardPath = `${path}.recovery`;
-  const recoveryOwner = acquireLegacyRecoveryGuard(
-    recoveryGuardPath,
-    options,
-  );
+  const recoveryOwner = acquireLegacyRecoveryGuard(recoveryGuardPath, options);
   if (!recoveryOwner) return undefined;
   let recoveredOwner: TelegramLockTransactionOwner | undefined;
   try {
@@ -607,24 +608,28 @@ function acquireLockTransaction(
   path: string,
   options: TelegramFileTransactionOptions = {},
 ): TelegramLockTransactionOwner {
+  const attempts = Math.max(
+    1,
+    options.attempts ?? TELEGRAM_LOCK_TRANSACTION_ATTEMPTS,
+  );
+  const retryDelayMs = Math.max(
+    0,
+    options.retryDelayMs ?? TELEGRAM_LOCK_TRANSACTION_RETRY_DELAY_MS,
+  );
   mkdirSync(dirname(path), { recursive: true });
-  for (
-    let attempt = 0;
-    attempt < TELEGRAM_LOCK_TRANSACTION_ATTEMPTS;
-    attempt += 1
-  ) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
       return createLockTransactionGuard(path);
     } catch (error) {
       if (!isLockTransactionContentionError(error, path)) throw error;
       const recoveredOwner = recoverAbandonedLockTransaction(path, options);
       if (recoveredOwner !== undefined) return recoveredOwner;
-      if (attempt === TELEGRAM_LOCK_TRANSACTION_ATTEMPTS - 1) {
+      if (attempt === attempts - 1) {
         throw new Error(
           `Timed out acquiring Telegram lock transaction: ${path}`,
         );
       }
-      sleepSync(TELEGRAM_LOCK_TRANSACTION_RETRY_DELAY_MS);
+      sleepSync(retryDelayMs);
     }
   }
   throw new Error(`Failed to acquire Telegram lock transaction: ${path}`);
@@ -856,7 +861,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
   options: TelegramLockRuntimeOptions = {},
 ): TelegramLockRuntime<TContext> {
   const key = options.key ?? TELEGRAM_LOCK_KEY;
-  const locksPath = options.locksPath ?? getLocksPath();
+  const locksPath = options.locksPath ?? getOwnersPath();
   const pid = options.pid ?? process.pid;
   const isAlive = options.isProcessAlive ?? isProcessAlive;
   const getNowMs = options.getNowMs ?? Date.now;
@@ -1141,6 +1146,7 @@ export interface TelegramLockedPollingRuntimeDeps<
     details?: Record<string, unknown>,
   ) => void;
   ownershipCheckMs?: number;
+  ownershipRefreshMs?: number;
 }
 
 function snapshotLockContext(ctx: TelegramLockContext): TelegramLockContext {
@@ -1152,16 +1158,20 @@ export function createTelegramLockedPollingRuntime<
 >(
   deps: TelegramLockedPollingRuntimeDeps<TContext>,
 ): TelegramLockedPollingRuntime<TContext> {
-  let ownershipInterval: ReturnType<typeof setInterval> | undefined;
+  let ownershipCheckInterval: ReturnType<typeof setInterval> | undefined;
+  let ownershipRefreshInterval: ReturnType<typeof setInterval> | undefined;
   let ownershipStop: Promise<void> | undefined;
   let takeoverCandidate: TelegramLockEntry | undefined;
   let sessionAutoStartRun: Promise<void> | undefined;
   let sessionAutoStartGeneration = 0;
   const ownershipCheckMs = deps.ownershipCheckMs ?? 1000;
+  const ownershipRefreshMs =
+    deps.ownershipRefreshMs ?? TELEGRAM_OWNERSHIP_REFRESH_MS;
   const stopOwnershipWatcher = () => {
-    if (!ownershipInterval) return;
-    clearInterval(ownershipInterval);
-    ownershipInterval = undefined;
+    if (ownershipCheckInterval) clearInterval(ownershipCheckInterval);
+    if (ownershipRefreshInterval) clearInterval(ownershipRefreshInterval);
+    ownershipCheckInterval = undefined;
+    ownershipRefreshInterval = undefined;
   };
   const suspendPolling = async () => {
     sessionAutoStartGeneration += 1;
@@ -1191,15 +1201,24 @@ export function createTelegramLockedPollingRuntime<
   const startOwnershipWatcher = (ctx: TContext) => {
     const owner = snapshotLockContext(ctx);
     stopOwnershipWatcher();
-    ownershipInterval = setInterval(() => {
+    ownershipCheckInterval = setInterval(() => {
+      try {
+        if (deps.lock.owns(owner)) return;
+      } catch (error) {
+        deps.recordRuntimeEvent?.("lock", error, { phase: "check" });
+      }
+      stopAfterOwnershipLoss();
+    }, ownershipCheckMs);
+    ownershipRefreshInterval = setInterval(() => {
       try {
         if (deps.lock.refresh(owner)) return;
       } catch (error) {
         deps.recordRuntimeEvent?.("lock", error, { phase: "refresh" });
       }
       stopAfterOwnershipLoss();
-    }, ownershipCheckMs);
-    ownershipInterval.unref?.();
+    }, ownershipRefreshMs);
+    ownershipCheckInterval.unref?.();
+    ownershipRefreshInterval.unref?.();
   };
   const runOwnedPollingStart = async (
     ctx: TContext,

package/lib/logs.ts

@@ -102,6 +102,12 @@ export function createTelegramRuntimeJsonlLog(
   const getNowMs = options.getNowMs ?? Date.now;
   const scopeKeys = new Map<string, string | undefined>();
   let pending: Promise<void> = Promise.resolve();
+  let appendScheduled = false;
+  let queuedAppends: {
+    path: string;
+    previousPath: string;
+    line: string;
+  }[] = [];
 
   const ensureParent = (path: string) => {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
@@ -156,27 +162,79 @@ export function createTelegramRuntimeJsonlLog(
   };
 
   const appendLine = (line: string) => {
-    const path = resolvePath();
-    const previousPath = resolvePreviousPath();
+    queuedAppends.push({
+      path: resolvePath(),
+      previousPath: resolvePreviousPath(),
+      line,
+    });
+    if (appendScheduled) return;
+    appendScheduled = true;
     pending = pending
       .then(() => {
-        ensureParent(path);
-        withTelegramFileTransaction(`${path}.transaction`, () => {
-          if (
-            existsSync(path) &&
-            statSync(path).size > maxBytes &&
-            (!options.canReset || options.canReset())
-          ) {
-            const rotate = () =>
-              writeResetLocked(path, previousPath, "max-bytes", { maxBytes });
-            if (options.commitReset) {
-              options.commitReset(rotate);
-            } else {
-              rotate();
-            }
+        appendScheduled = false;
+        const batch = queuedAppends;
+        queuedAppends = [];
+        const groups = new Map<
+          string,
+          { path: string; previousPath: string; lines: string[] }
+        >();
+        for (const entry of batch) {
+          const key = `${entry.path}\u0000${entry.previousPath}`;
+          const group = groups.get(key);
+          if (group) group.lines.push(entry.line);
+          else groups.set(key, { ...entry, lines: [entry.line] });
+        }
+        for (const group of groups.values()) {
+          try {
+            ensureParent(group.path);
+            withTelegramFileTransaction(`${group.path}.transaction`, () => {
+              let currentSize = existsSync(group.path)
+                ? statSync(group.path).size
+                : 0;
+              let chunk = "";
+              let chunkBytes = 0;
+              const flushChunk = () => {
+                if (!chunk) return;
+                appendFileSync(group.path, chunk, { mode: 0o600 });
+                currentSize += chunkBytes;
+                chunk = "";
+                chunkBytes = 0;
+              };
+              const rotate = (): boolean => {
+                if (options.canReset && !options.canReset()) return false;
+                let rotated = false;
+                const commit = () => {
+                  writeResetLocked(
+                    group.path,
+                    group.previousPath,
+                    "max-bytes",
+                    { maxBytes },
+                  );
+                  rotated = true;
+                };
+                if (options.commitReset) options.commitReset(commit);
+                else commit();
+                if (rotated) currentSize = statSync(group.path).size;
+                return rotated;
+              };
+              for (const line of group.lines) {
+                const lineBytes = Buffer.byteLength(line);
+                if (
+                  currentSize + chunkBytes > 0 &&
+                  currentSize + chunkBytes + lineBytes > maxBytes
+                ) {
+                  flushChunk();
+                  rotate();
+                }
+                chunk += line;
+                chunkBytes += lineBytes;
+              }
+              flushChunk();
+            });
+          } catch {
+            // Diagnostics failures for one profile must not drop other groups.
           }
-          appendFileSync(path, line, { mode: 0o600 });
-        });
+        }
       })
       .catch(() => undefined);
   };

package/lib/media.ts

@@ -390,15 +390,6 @@ export function appendTelegramReplyContext(
   return text ? `${text}\n\n${replyContext}` : `_\n\n${replyContext}`;
 }
 
-export function appendTelegramForwardContext(
-  text: string,
-  forwardContext: string,
-): string {
-  if (!forwardContext) return text;
-  const forwardBlock = `[forward|${forwardContext.replace(/:\s+/g, ":")}]`;
-  return text ? `\n\n${forwardBlock} ${text}` : `\n\n${forwardBlock}`;
-}
-
 export function extractTelegramMessagePromptText(
   message: TelegramMediaMessage,
 ): string {

package/lib/menu-model.ts

@@ -484,7 +484,11 @@ export function createTelegramModelMenuStateBuilder<
     TelegramModelMenuStateBuilderContext<TModel>,
 >(
   deps: TelegramModelMenuStateBuilderDeps<TModel, TContext>,
-): (chatId: number, ctx: TContext, threadId?: number) => Promise<TelegramModelMenuState<TModel>> {
+): (
+  chatId: number,
+  ctx: TContext,
+  threadId?: number,
+) => Promise<TelegramModelMenuState<TModel>> {
   return async (chatId, ctx, threadId) => {
     const settingsManager = deps.createSettingsManager(ctx.cwd);
     return deps.runtime.buildState({
@@ -745,17 +749,6 @@ export function setTelegramModelScope(
   return { patterns, enabled };
 }
 
-export function toggleTelegramModelScope(
-  state: TelegramModelMenuState,
-  model: MenuModel,
-): { patterns: string[]; enabled: boolean } {
-  return setTelegramModelScope(
-    state,
-    model,
-    !isTelegramModelScoped(state, model),
-  );
-}
-
 export function buildTelegramModelCallbackPlan<
   TModel extends MenuModel = MenuModel,
 >(

package/lib/menu.ts

@@ -118,25 +118,6 @@ export type {
   TelegramThinkingMenuOpenDeps,
 } from "./menu-thinking.ts";
 
-export interface TelegramMenuEffectPort<TModel extends MenuModel = MenuModel> {
-  answerCallbackQuery: (
-    callbackQueryId: string,
-    text?: string,
-  ) => Promise<void>;
-  updateModelMenuMessage: () => Promise<void>;
-  updateThinkingMenuMessage: () => Promise<void>;
-  updateStatusMessage: () => Promise<void>;
-  persistScopedModelPatterns?: (patterns: string[]) => Promise<void>;
-  setModel: (model: TModel) => Promise<boolean>;
-  setCurrentModel: (model: TModel) => void;
-  setThinkingLevel: (level: ThinkingLevel) => void;
-  getCurrentThinkingLevel: () => ThinkingLevel;
-  stagePendingModelSwitch: (selection: ScopedTelegramModel<TModel>) => void;
-  restartInterruptedTelegramTurn: (
-    selection: ScopedTelegramModel<TModel>,
-  ) => Promise<boolean> | boolean;
-}
-
 export interface TelegramMenuCallbackEntryDeps {
   handleStatusAction: () => Promise<boolean>;
   handleThinkingAction: () => Promise<boolean>;

package/lib/outbound.ts

@@ -197,12 +197,6 @@ export function registerTelegramOutboundHandler(
   };
 }
 
-export function hasTelegramOutboundHandler(kind: string): boolean {
-  const registry = getOrCreateOutboundHandlerRegistry();
-  const list = registry.handlers.get(kind);
-  return !!list && list.length > 0;
-}
-
 export function getTelegramOutboundProgrammaticHandlers(
   kind: string,
 ): TelegramOutboundProgrammaticHandler[] {
@@ -953,15 +947,11 @@ export function createTelegramAssistantOutputSender<
   TReplyMarkup = unknown,
 >(deps: {
   recordOwnership?: Replies.TelegramReplyOwnershipRecorder["record"];
-  sendMessage: (
-    body: TelegramSendMessageBody,
-  ) => Promise<TelegramSentMessage>;
+  sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
   sendRichMessage: (
     body: TelegramSendRichMessageBody,
   ) => Promise<TelegramSentMessage>;
-  editMessage: (
-    body: TelegramEditMessageTextBody,
-  ) => Promise<unknown>;
+  editMessage: (body: TelegramEditMessageTextBody) => Promise<unknown>;
   getAssistantRenderingMode: () => "rich" | "html";
   execCommand: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["execCommand"];
   getHandlers?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["getHandlers"];

package/lib/paths.ts

@@ -10,6 +10,8 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
+
 export interface TelegramAgentDirResolutionInput {
   env?: Partial<Pick<NodeJS.ProcessEnv, "PI_CODING_AGENT_DIR">>;
   execPath?: string;
@@ -45,18 +47,19 @@ export function resolveTelegramConfigPath(): string {
   return join(resolveAgentDir(), "telegram.json");
 }
 
-/** Telegram singleton lock file (<agentDir>/locks.json). */
-export function resolveTelegramLocksPath(): string {
-  return join(resolveAgentDir(), "locks.json");
-}
-
 /** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
 export function resolveTelegramTempDir(agentDir = resolveAgentDir()): string {
   return join(agentDir, "tmp", "telegram");
 }
 
+/** Telegram transport ownership store (<agentDir>/tmp/telegram/owners.json). */
+export function resolveTelegramOwnersPath(): string {
+  return join(resolveTelegramTempDir(), "owners.json");
+}
+
 export function getTelegramProfilePathSuffix(profileName?: string): string {
-  return profileName ? `.${profileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}` : "";
+  if (!profileName || profileName === TELEGRAM_DEFAULT_PROFILE_NAME) return "";
+  return `.${profileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`;
 }
 
 export function resolveTelegramProfileTempFilePath(

package/lib/pi.ts

@@ -114,10 +114,6 @@ export function getSessionCompactionReason(
     : "unknown";
 }
 
-export type PiSendUserMessageOptions = NonNullable<
-  Parameters<ExtensionAPI["sendUserMessage"]>[1]
->;
-
 export interface PiExtensionApiRuntimePorts {
   sendUserMessage: ExtensionAPI["sendUserMessage"];
   exec: ExtensionAPI["exec"];

package/lib/queue.ts

@@ -1764,7 +1764,6 @@ export async function shutdownTelegramSessionRuntime<TQueueItem>(
       deps.clearPreview(activeTurnChatId, target ? { target } : undefined),
       new Promise<void>((resolve) => {
         timeout = setTimeout(resolve, previewTimeoutMs);
-        timeout.unref?.();
       }),
     ]).finally(() => {
       if (timeout) clearTimeout(timeout);
@@ -2240,10 +2239,6 @@ export interface TelegramPromptDeliveryOptions {
   deliverAs: "followUp";
 }
 
-export const TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY = {
-  deliverAs: "followUp",
-} as const satisfies TelegramPromptDeliveryOptions;
-
 export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
   executeControlItem: (
     item: Extract<

package/lib/replies.ts

@@ -871,29 +871,6 @@ export function dedupSendTextReply(
   };
 }
 
-/** Wrap a sendMarkdownReply with reply dedup. */
-export function dedupSendMarkdownReply<TReplyMarkup = unknown>(
-  dedup: ReplyDedupRuntime,
-  inner: (
-    chatId: number,
-    replyToMessageId: number | undefined,
-    markdown: string,
-    options?: { replyMarkup?: TReplyMarkup },
-  ) => Promise<number | undefined>,
-): (
-  chatId: number,
-  replyToMessageId: number,
-  markdown: string,
-  options?: { replyMarkup?: TReplyMarkup },
-) => Promise<number | undefined> {
-  return async (chatId, replyToMessageId, markdown, options) => {
-    const effectiveReplyTo = dedup.shouldReply(replyToMessageId)
-      ? replyToMessageId
-      : undefined;
-    return inner(chatId, effectiveReplyTo, markdown, options);
-  };
-}
-
 /**
  * Guest reply sender: answers guest queries with native Rich Markdown content.
  * Guest queries use InlineQueryResult input_message_content rather than chat

package/lib/runtime.ts

@@ -508,8 +508,7 @@ export async function waitForTelegramTypingLoopIdle(
   await Promise.race([
     inFlight,
     new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, timeoutMs);
-      timer.unref?.();
+      setTimeout(resolve, timeoutMs);
     }),
   ]);
 }

package/lib/sections.ts

@@ -358,7 +358,7 @@ export function createTelegramExtensionSectionRegistry(): TelegramSectionRegistr
   >();
   let nextToken = 0;
 
-  const 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}`);
@@ -708,50 +708,3 @@ export async function handleTelegramSectionSettingsOpen(
     return true;
   }
 }
-
-export async function handleTelegramSectionSettingsCallback(
-  registry: TelegramSectionRegistry,
-  token: TelegramSectionToken,
-  action: string,
-  payload: string,
-  chatId: number,
-  messageId: number,
-  callbackQueryId: string,
-  deps: TelegramSectionCallbackHandlerDeps,
-): Promise<boolean> {
-  const section = registry.getByToken(token);
-  if (!section || !section.registration.settings?.handleCallback) {
-    await deps.answerCallbackQuery(
-      callbackQueryId,
-      "This section is no longer available.",
-    );
-    return true;
-  }
-  try {
-    const ctx = buildTelegramSectionCallbackContext(
-      section.id,
-      token,
-      chatId,
-      messageId,
-      action,
-      payload,
-      callbackQueryId,
-      deps,
-      `settings:list`,
-    );
-    const result = await section.registration.settings.handleCallback(ctx);
-    if (result === "pass") {
-      await deps.answerCallbackQuery(callbackQueryId);
-    }
-    registry.clearError(token, "settings_callback");
-    return true;
-  } catch (error) {
-    const message = sectionErrorMessage(error);
-    registry.recordError(token, message, "settings_callback");
-    await deps.answerCallbackQuery(
-      callbackQueryId,
-      `Section error: ${message}`,
-    );
-    return true;
-  }
-}