@llblab/pi-telegram 0.54.4 → 0.55.0

package/lib/text-groups.ts

@@ -7,8 +7,9 @@
 import { setTimeout as waitForTimeout } from "node:timers/promises";
 
 import {
-  createTelegramPendingGroupLifecycle,
+  createTelegramPendingGroups,
   extractTelegramMessageText,
+  type TelegramPendingGroup,
   type TelegramMessageForwardOrigin,
   type TelegramMessageUser,
   type TelegramRichMessage,
@@ -32,19 +33,6 @@ export interface TelegramTextGroupMessage {
   forward_sender_name?: string;
 }
 
-export interface TelegramTextGroupState<TMessage, TContext = unknown> {
-  messages: TMessage[];
-  context?: TContext;
-  flushTimer?: ReturnType<typeof setTimeout>;
-  dispatching?: boolean;
-  suspended?: boolean;
-  reschedule?: (delayMs?: number) => void;
-  dispatchNow?: () => Promise<void>;
-  dispatchPromise?: Promise<void>;
-  dispatchLimit?: number;
-  forwardPairCandidate?: TelegramForwardCommentBatchPosition;
-}
-
 export type TelegramForwardCommentBatchPosition = "comment" | "forward";
 
 export interface TelegramTextGroupController<TMessage, TContext = unknown> {
@@ -157,11 +145,11 @@ function canStartTelegramTextGroup(
 function canAppendTelegramTextGroupMessage<
   TMessage extends TelegramTextGroupMessage,
 >(
-  state: TelegramTextGroupState<TMessage, unknown>,
+  group: TelegramPendingGroup<TMessage, unknown, unknown>,
   message: TMessage,
 ): boolean {
   const text = extractTelegramTextGroupText(message);
-  const previous = state.messages.at(-1);
+  const previous = group.messages.at(-1);
   return (
     !!previous &&
     message.message_id > previous.message_id &&
@@ -172,114 +160,12 @@ function canAppendTelegramTextGroupMessage<
   );
 }
 
-export function queueTelegramTextGroupMessage<
-  TMessage extends TelegramTextGroupMessage,
-  TContext = unknown,
->(options: {
-  message: TMessage;
-  context: TContext;
-  groups: Map<string, TelegramTextGroupState<TMessage, TContext>>;
-  debounceMs: number;
-  minSplitLength: number;
-  setTimer: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
-  clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
-  dispatchMessages: (
-    messages: TMessage[],
-    ctx: TContext,
-  ) => unknown | Promise<unknown>;
-  forceStart?: boolean;
-  dispatchImmediately?: boolean;
-  forwardPairCandidate?: TelegramForwardCommentBatchPosition;
-  delayMs?: number;
-}): boolean {
-  const key = getTelegramTextGroupKey(options.message);
-  if (!key) return false;
-  const existing = options.groups.get(key);
-  const duplicateIndex = existing?.messages.findIndex(
-    (message) => message.message_id === options.message.message_id,
-  );
-  if (existing && duplicateIndex !== undefined && duplicateIndex >= 0) {
-    existing.messages[duplicateIndex] = options.message;
-    existing.context = options.context;
-    existing.forwardPairCandidate = options.forwardPairCandidate;
-    if (!existing.suspended && !existing.dispatching && !existing.flushTimer) {
-      existing.reschedule?.();
-    }
-    return true;
-  }
-  if (
-    !existing &&
-    !options.forceStart &&
-    !canStartTelegramTextGroup(options.message, options.minSplitLength)
-  )
-    return false;
-  if (existing && !canAppendTelegramTextGroupMessage(existing, options.message))
-    return false;
-  const state = existing ?? { messages: [] };
-  state.messages.push(options.message);
-  state.context = options.context;
-  state.forwardPairCandidate = options.forwardPairCandidate;
-  const dispatchQueued = (): Promise<void> => {
-    state.flushTimer = undefined;
-    const queued = options.groups.get(key);
-    if (!queued || queued.context === undefined) return Promise.resolve();
-    if (queued.dispatching) return queued.dispatchPromise ?? Promise.resolve();
-    const dispatchCount = queued.dispatchLimit ?? queued.messages.length;
-    queued.dispatchLimit = undefined;
-    const dispatchedMessages = queued.messages.slice(0, dispatchCount);
-    const dispatchedIds = new Set(
-      dispatchedMessages.map((message) => message.message_id),
-    );
-    queued.dispatching = true;
-    const operation = Promise.resolve(
-      options.dispatchMessages(dispatchedMessages, queued.context),
-    ).then(
-      () => {
-        if (options.groups.get(key) !== queued) return;
-        queued.messages = queued.messages.filter(
-          (message) => !dispatchedIds.has(message.message_id),
-        );
-        queued.dispatching = false;
-        queued.dispatchPromise = undefined;
-        if (queued.messages.length === 0) options.groups.delete(key);
-        else if (!queued.flushTimer) scheduleDispatch();
-      },
-      (error) => {
-        if (options.groups.get(key) === queued) {
-          queued.dispatching = false;
-          queued.dispatchPromise = undefined;
-          if (!queued.flushTimer) scheduleDispatch();
-        }
-        throw error;
-      },
-    );
-    queued.dispatchPromise = operation;
-    return operation;
-  };
-  const scheduleDispatch = (delayMs = options.debounceMs): void => {
-    if (state.suspended) return;
-    state.flushTimer = options.setTimer(() => {
-      void dispatchQueued().catch(() => undefined);
-    }, delayMs);
-    state.flushTimer.unref?.();
-  };
-  state.reschedule = scheduleDispatch;
-  state.dispatchNow = dispatchQueued;
-  if (state.flushTimer) options.clearTimer(state.flushTimer);
-  scheduleDispatch(
-    options.dispatchImmediately ? 0 : (options.delayMs ?? options.debounceMs),
-  );
-  options.groups.set(key, state);
-  return true;
-}
-
 export function createTelegramTextGroupController<
   TMessage extends TelegramTextGroupMessage,
   TContext = unknown,
 >(
   options: TelegramTextGroupControllerOptions = {},
 ): TelegramTextGroupController<TMessage, TContext> {
-  const groups = new Map<string, TelegramTextGroupState<TMessage, TContext>>();
   const plannedForwardCommentStarts = new Set<string>();
   const plannedForwardCommentEnds = new Set<string>();
   const debounceMs = options.debounceMs ?? TELEGRAM_TEXT_GROUP_DEBOUNCE_MS;
@@ -305,7 +191,65 @@ export function createTelegramTextGroupController<
       : (timer: ReturnType<typeof setTimeout>): void => {
           (timer as unknown as AbortController).abort();
         });
-  const lifecycle = createTelegramPendingGroupLifecycle(groups, clearTimer);
+  const groups = createTelegramPendingGroups<
+    TMessage,
+    TContext,
+    TelegramForwardCommentBatchPosition
+  >({ debounceMs, requireContext: true, setTimer, clearTimer });
+  /** Admission policy for one message; the shared group machine owns timers, batches and dispatch. */
+  const queueTextGroupMessage = (options: {
+    key: string;
+    message: TMessage;
+    context: TContext;
+    dispatchMessages: (
+      messages: TMessage[],
+      ctx: TContext,
+    ) => unknown | Promise<unknown>;
+    forceStart: boolean;
+    dispatchImmediately: boolean;
+    forwardPairCandidate?: TelegramForwardCommentBatchPosition;
+    delayMs?: number;
+  }): boolean => {
+    const existing = groups.get(options.key);
+    const dispatchMessages = (messages: TMessage[], ctx?: TContext) =>
+      options.dispatchMessages(messages, ctx as TContext);
+    const queued = {
+      key: options.key,
+      message: options.message,
+      context: options.context,
+      ...(options.forwardPairCandidate === undefined
+        ? {}
+        : { meta: options.forwardPairCandidate }),
+      dispatchMessages,
+    };
+    if (
+      existing?.messages.some(
+        (message) => message.message_id === options.message.message_id,
+      )
+    ) {
+      groups.queue({ ...queued, delayMs: debounceMs, rearm: "ifIdle" });
+      return true;
+    }
+    if (
+      !existing &&
+      !options.forceStart &&
+      !canStartTelegramTextGroup(options.message, minSplitLength)
+    )
+      return false;
+    if (
+      existing &&
+      !canAppendTelegramTextGroupMessage(existing, options.message)
+    )
+      return false;
+    groups.queue({
+      ...queued,
+      delayMs: options.dispatchImmediately
+        ? 0
+        : (options.delayMs ?? debounceMs),
+      rearm: "always",
+    });
+    return true;
+  };
   return {
     prepareUpdateBatch(updates) {
       for (let index = 0; index + 1 < updates.length; index += 1) {
@@ -354,23 +298,19 @@ export function createTelegramTextGroupController<
       const forwarded = isTelegramForwardedMessage(message);
       const existing = key ? groups.get(key) : undefined;
       const text = extractTelegramTextGroupText(message);
-      if (existing && isTelegramTextGroupClearingCommand(text)) {
-        if (existing.flushTimer) clearTimer(existing.flushTimer);
-        groups.delete(key!);
-      }
+      if (existing && isTelegramTextGroupClearingCommand(text))
+        groups.clearKey(key!);
       const candidatePosition: TelegramForwardCommentBatchPosition = forwarded
         ? "forward"
         : "comment";
-      const existingCandidate = existing?.forwardPairCandidate;
+      const existingCandidate = existing?.meta;
       const pairCompleted =
         existingCandidate !== undefined &&
         existingCandidate !== candidatePosition;
       const separateFromCandidate =
         existingCandidate === candidatePosition &&
         !isTelegramTextGroupCommand(text);
-      if (separateFromCandidate && existing) {
-        existing.dispatchLimit = existing.messages.length;
-      }
+      if (separateFromCandidate && existing) groups.closeBatch(key!);
       const forceStart =
         plannedStart ||
         (forwardCommentWaitMs !== false &&
@@ -384,15 +324,12 @@ export function createTelegramTextGroupController<
         pairCompleted ||
         separateFromCandidate ||
         plannedForwardCommentEnds.delete(identity) ||
-        (forwarded && !!key && groups.has(key));
-      return queueTelegramTextGroupMessage({
+        (forwarded && !!key && groups.get(key) !== undefined);
+      if (!key) return false;
+      return queueTextGroupMessage({
+        key,
         message,
         context,
-        groups,
-        debounceMs,
-        minSplitLength,
-        setTimer,
-        clearTimer,
         dispatchMessages,
         forceStart,
         dispatchImmediately,
@@ -408,9 +345,11 @@ export function createTelegramTextGroupController<
             : undefined,
       });
     },
-    ...lifecycle,
+    flushMessage: groups.flushMessage,
+    suspend: groups.suspend,
+    resume: groups.resume,
     clear: () => {
-      lifecycle.clear();
+      groups.clear();
       plannedForwardCommentStarts.clear();
       plannedForwardCommentEnds.clear();
     },

package/lib/thread-display.ts

@@ -4,9 +4,11 @@
  * Owns mode-specific labels and serialized, authority-fenced title application.
  * Excludes routing, name allocation, profile mutation, and live-owner discovery.
  */
+import { homedir } from "node:os";
 import { isDeepStrictEqual } from "node:util";
 
 import type { TelegramThreadDisplayMode } from "./config.ts";
+import { normalizeTelegramWorkspacePath } from "./workspace-identity.ts";
 import type { TelegramApiCallOptions } from "./telegram-api.ts";
 import type {
   TelegramTopicTargetStore,
@@ -34,8 +36,11 @@ function directorySegments(cwd: string): string[] {
 function distinguishingDirectorySegments(
   cwd: string,
   directories: readonly string[],
+  homeDirectory?: string,
 ): string[] {
-  const parts = directorySegments(cwd);
+  // Substitute only exact home identity; qualification must still distinguish ordinary folders named home.
+  const segments = (directory: string) => directory === homeDirectory ? ["home"] : directorySegments(directory);
+  const parts = segments(cwd);
   if (!parts.length) return [];
   for (let depth = 1; depth <= parts.length; depth++) {
     const candidate = labelText(parts.slice(-depth).join("/"));
@@ -43,7 +48,7 @@ function distinguishingDirectorySegments(
       (other) =>
         other !== cwd &&
         labelText(
-          directorySegments(other).slice(-depth).join("/"),
+          segments(other).slice(-depth).join("/"),
         ).toLowerCase() === candidate.toLowerCase(),
     );
     if (!collides) return parts.slice(-depth);
@@ -69,8 +74,9 @@ function formatDirectoryLabel(
   cwd: string,
   directories: readonly string[],
   mode: "directory-snake" | "directory-title",
+  homeDirectory?: string,
 ): string {
-  const segments = distinguishingDirectorySegments(cwd, directories);
+  const segments = distinguishingDirectorySegments(cwd, directories, homeDirectory);
   if (!segments.length) return "/";
   const formatted = segments
     .map((segment) => {
@@ -143,6 +149,11 @@ export function resolveTelegramWorkspaceDisplayNames(
   liveBindingKeys: ReadonlySet<string> = new Set(),
 ): Map<string, string> {
   const labels = new Map<string, string>();
+  const homeDirectory =
+    (mode === "directory-snake" || mode === "directory-title") &&
+    (process.platform === "linux" || process.platform === "darwin")
+      ? normalizeTelegramWorkspacePath(homedir())
+      : undefined;
   const directories = Array.from(
     new Set(bindings.map((binding) => binding.cwd)),
   );
@@ -172,7 +183,7 @@ export function resolveTelegramWorkspaceDisplayNames(
       const base =
         mode === "directories"
           ? directoryLabel(binding.cwd, directories)
-          : formatDirectoryLabel(binding.cwd, directories, mode);
+          : formatDirectoryLabel(binding.cwd, directories, mode, homeDirectory);
       bases.set(binding.bindingKey, base);
       const showSuffix =
         mode === "directories"